ImmediateMesh

ImmediateMesh is a Mesh resource rather than an overlay drawing command or Entity. SurfaceBegin opens one surface, SurfaceAddVertex adds corners, and SurfaceEnd publishes the finished surface. Assign it to MeshInstance3D.Mesh and place the instance in the tree to display it. Geometry persists between frames: another Begin/End appends a surface rather than replacing the previous one.

using var mesh = new ImmediateMesh();
mesh.SurfaceBegin(Mesh.PrimitiveType.Lines);
mesh.SurfaceSetColor(new Color(1, 0, 0));
mesh.SurfaceAddVertex(new Vector3(0, 0, 2));
mesh.SurfaceAddVertex(new Vector3(1, 0, 2));
mesh.SurfaceEnd();
int surfaceCount = mesh.GetSurfaceCount(); // 1

The example creates line data without a visible object. When assigning mesh to an instance, keep the resource alive for its entire use rather than ending its using scope early. Visible color requires a material that uses vertex color, for example StandardMaterial3D with VertexColorUseAsAlbedo = true. SurfaceSetColor does not configure the material. An unshaded material suits diagnostic lines independent of lighting. This API does not set pixel line width.

Use Begin → optional attribute setters → vertex additions → End. Only one surface can be open. End without vertices is rejected and does not close the builder. Supply pairs for Lines and corner triples for Triangles; the builder creates no indices, bones/weights, custom channels, blend shapes or LODs. Prepare large repeated geometry with ArrayMesh or SurfaceTool rather than rebuilding it here every frame.

Attributes are latched for subsequent vertices. The first setter call also fills already-added vertices of the current surface with that value. Later calls affect only future vertices. Unlike SurfaceTool, a channel can be enabled after the first vertex. Successful End resets channel-presence flags: set required attributes again for every Begin. Color uses eight bits per channel: values are clamped to 0…1 and quantized. Normals/tangents are packed, so readback need not reproduce original floats bit for bit.

SurfaceAddVertex2D stores Vector2 in a mesh buffer; it neither creates a CanvasItem nor switches the scene to 2D. Do not mix 2D and 3D in one surface. SurfaceEnd resets dimensionality for the next surface. Known 1.0.0 defect: ClearSurfaces during an unfinished 2D build does not reset its dimensionality. The next first Vector3 loses Z and subsequent Vector3 additions are rejected. Create a new ImmediateMesh after such an interruption; repeating ClearSurfaces does not fix it.

SurfaceEnd emits Changed; ClearSurfaces does not. Call EmitChanged explicitly if dependent code requires a notification after clearing. ClearSurfaces removes all completed surfaces and cancels the current build. SurfaceGetArrays results are snapshots rather than a live editor. Inspect these arrays for vertex types/counts; do not copy C++ virtual SurfaceGetArrayLen/SurfaceGetFormat into C# code, where these public methods are absent.

Prepare triangle normals and UVs yourself. When normals exist without tangents, the engine derives a helper tangent from the normal rather than UV mapping. Supply consistent tangents for normal mapping or use SurfaceTool.GenerateTangents. SurfaceSetUV2 merely writes coordinates: it neither unwraps geometry nor bakes lighting.

17 Windows headless checks covered CPU data and reproduced the dimensionality defect. The full native run is marked unsuccessful because that scenario emits a diagnostic, even though its expected behavior was recorded. Visible drawing, normal mapping, arbitrary geometry and performance remain unestablished; the engine was not patched.

Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.

public ImmediateMesh();

public void ClearSurfaces();

public void SurfaceAddVertex(Vector3 vertex);

public void SurfaceAddVertex2D(Vector2 vertex);

public void SurfaceBegin(Mesh.PrimitiveType primitive, Material material = null);

public void SurfaceEnd();

public void SurfaceSetColor(Color color);

public void SurfaceSetNormal(Vector3 normal);

public void SurfaceSetTangent(Plane tangent);

public void SurfaceSetUV(Vector2 uV);

public void SurfaceSetUV2(Vector2 uV2);