godotengine / godotengine/godot-docs

Godot winding direction for SurfaceTool, ArrayMesh, and MeshDataTool are incorrect

Open
#10,757 1 comment 1 reaction 0 assignees View on GitHub
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:**
v4.4.beta4.official.93d270693

**Issue description:**

In the documentation for SurfaceTool, ArrayMesh, and MeshDataTool it states:

> Note: Godot uses clockwise [winding order](https://learnopengl.com/Advanced-OpenGL/Face-culling) for front faces of triangle primitive modes.

I've been banging my head against this problem for quite a few hours, googled all around, and I think this is just incorrect in the documentation.

I believe Godot uses _counterclockwise_ winding order when dealing with primitive triangles.

And indeed, in the documentation that the godot docs link to on https://learnopengl.com/ it says

> By default, triangles defined with counter-clockwise vertices are processed as front-facing triangles.

And on the [official openGL documentation](https://www.khronos.org/opengl/wiki/Face_Culling) it states:

> On a freshly created [OpenGL Context](https://www.khronos.org/opengl/wiki/OpenGL_Context), the default front face is GL_CCW.

I tested a project that I'll link below, but I wrote some code to do the winding order as follows:

```
var st = SurfaceTool.new()
st.begin(Mesh.PRIMITIVE_TRIANGLES)
st.add_vertex(Vector3(0, 2, 0))
st.add_vertex(Vector3(2, 2, 2))
st.add_vertex(Vector3(0, 2, 2))
var mesh = st.commit()
```

I think you can agree this is a clockwise winding order, and assuming godot is a right-handed coordinate system, you'd expect the normal face to point "down"(-Y axis in 3D godot).

However, I created a simple project, and that's simply not the case; you can see the triangle from "above" but not below, which implies that the triangle normal is actually facing "up"(+Y). See the yellow triangle below:

![Image](https://github.com/user-attachments/assets/70d3bd6f-bbe8-4137-b845-cf1e0bd6c578)

Looking "down"(-Y):

![Image](https://github.com/user-attachments/assets/de5a69d4-3616-4cdf-83b7-0e1e11cf4aae)

Here's the project with the above code:

[winding_direction_test.zip](https://github.com/user-attachments/files/19173403/winding_direction_test.zip)

**URL to the documentation page:**
https://docs.godotengine.org/en/stable/classes/class_surfacetool.html#description
https://docs.godotengine.org/en/stable/classes/class_arraymesh.html
https://docs.godotengine.org/en/stable/classes/class_meshdatatool.html

Maybe I'm misunderstanding something here, so please double check me if I've got this right. I'll attach the sample project with the above code to the issue.

If the docs are wrong, I'm happy to submit a pull request to update the docs.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.