Documentation / generated/godot-operations.md
Core 11629ae · View or edit Markdown on GitHub ↗

Godot operation reference

Generated from the current declarations. Do not edit this file by hand.

Types, limits and defaults below describe resolved values. Runtime expressions must produce these types. Unknown options are rejected; defaults apply only when omitted. Constructor options must be constant after document composition.

Index#

box, camera, capsule, cylinder, directionalLight, material, omniLight, plane, readGLTF, sphere, spotLight, sprite3D, torus, transformGroup

box#

Creates a MeshInstance3D holding a native BoxMesh centred on position, with edge lengths size in metres and the connected material. Choose it for blocks, walls, platforms or bounding volumes; it is the simplest primitive and the box readback (12 triangles, exact bounds) is the easiest to check. The mesh stays an editable BoxMesh in Godot. Use plane for a zero-thickness floor and readGLTF for shapes that are not primitives.

Common mistakes and assumptions:

• size holds full edge lengths, not half-extents: size [2, 2, 2] spans -1 to 1 around position.
• It needs a material input naming an earlier material node. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: BoxMesh. Output kind: ["geometry"].

camera#

Creates the scene's single perspective Camera3D at position, turned with look_at so that it looks at target with +Y up, and makes it the current camera. Every Godot document needs exactly one camera node; it frames the optional preview image and the view when the saved project is run. With orbit enabled, a fixed trusted script lets a user orbit, zoom and reset the view interactively in Godot.

Common mistakes and assumptions:

• A camera directly above or below its target (no horizontal separation) is rejected, because the Y-up look-at direction would be undefined; offset position slightly in X or Z for a near top-down view.
• Schemaxis does not check that geometry is inside the view; a preview can be valid but empty if the camera misses it.
• A second camera node fails planning with INVALID_SELECTION.

Native binding: Camera3D. Output kind: ["camera"].

Inputs: none.

capsule#

Creates a MeshInstance3D holding a native CapsuleMesh: a cylinder with hemispherical ends standing along its local Y axis, centred on position. height is the total height including both caps, so it must be at least twice the radius; tessellation is fixed at 32 radial segments and 8 rings. Choose it for character or obstacle placeholders and rounded rods.

Common mistakes and assumptions:

• A height below 2 x radius fails planning with INVALID_ARGUMENT; with height exactly 2 x radius the capsule is a sphere.
• It needs a material input naming an earlier material node. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: CapsuleMesh. Output kind: ["geometry"].

cylinder#

Creates a MeshInstance3D holding a native CylinderMesh with equal top and bottom radius, standing along its local Y axis and centred on position (it extends height/2 above and below). Tessellation is fixed at 32 radial segments and one ring (192 triangles). Choose it for posts, pipes and columns; rotate it to lie along another axis. Cones are not available because only one radius is accepted.

Common mistakes and assumptions:

• position is the centre of the cylinder, not its base: to stand a 1.2 m post on the ground at y = 0, use position y = 0.6.
• It needs a material input naming an earlier material node. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: CylinderMesh. Output kind: ["geometry"].

directionalLight#

Creates a DirectionalLight3D: parallel light from a distant source such as the sun, whose direction comes only from rotation (light travels along the node's rotated -Z axis); it has no position and lights the whole scene equally. Choose it as the main key or sun light; add omniLight or spotLight for local light. Shadows are not offered for this operation. Schemaxis does not require any light node; add one when the preview or running project should show directional shading.

Common mistakes and assumptions:

• Rotation [0, 0, 0] points the light horizontally along -Z; tilt it downward with a negative X angle (the default is [-45, -30, 0]).

Native binding: DirectionalLight3D. Output kind: ["light"].

Inputs: none.

material#

Creates a Godot StandardMaterial3D resource with an opaque base colour, roughness and metallic value; it is not a scene node by itself. Choose it once per distinct surface look and connect it to the material input of box, sphere, cylinder, plane, capsule, torus or readGLTF nodes; several meshes may share one material. The resource is saved inside scene.tscn as each mesh's material override, and the reopened values are compared with the authored ones.

Common mistakes and assumptions:

• Every material must feed at least one geometry node; an unused material fails planning with INVALID_SELECTION.
• Declare the material before the meshes that use it; inputs may only refer to earlier nodes.
• Transparency, textures and emission are not available; alpha is always 1. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: StandardMaterial3D. Output kind: ["material"].

Inputs: none.

omniLight#

Creates an OmniLight3D: a point light at position that shines in all directions and lights nothing beyond range metres. attenuation shapes how brightness falls with distance inside that radius, and shadows can be enabled. Choose it for lamps, fill and rim lights; use spotLight for a directed cone and directionalLight for sunlight.

Common mistakes and assumptions:

• Objects farther than range from the light receive none of its light, however high energy is.

Native binding: OmniLight3D. Output kind: ["light"].

Inputs: none.

plane#

Creates a MeshInstance3D holding a native PlaneMesh: a flat, zero-thickness rectangle (2 triangles) in its local XZ plane, facing +Y and centred on position. Choose it for floors, ground or backdrop panels; size gives its X and Z extents. Rotate it to make a wall. The default 10 x 10 m plane suits a ground under the default camera.

Common mistakes and assumptions:

• With the default material settings Godot draws only the face pointing along the plane's +Y normal, so a plane seen from below or from behind is invisible; rotate it so its normal faces the camera.
• It needs a material input naming an earlier material node. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: PlaneMesh. Output kind: ["geometry"].

readGLTF#

Imports one static triangle mesh from a self-contained .gltf 2.0 file with Godot's GLTFDocument and places it as an editable ArrayMesh in a MeshInstance3D, using the connected material and the authored position, rotation and scale. Choose it to bring CAD or modelling output into a scene when no primitive fits. Schemaxis accepts only a narrow subset (one scene, one untransformed node, one mesh with one TRIANGLES primitive, embedded base64 buffers, POSITION and optional NORMAL, at most 8 MiB) and rejects anything else instead of discarding it. The file bytes are captured and hashed before import, and the native bounds and triangle count are checked against values measured from those bytes.

Common mistakes and assumptions:

• GLB files, external .bin or texture URIs, node transforms, glTF materials, animation, skins and extensions are rejected with UNSUPPORTED_RESOURCE; export a plain embedded .gltf mesh instead.
• The glTF's own materials are not imported; the surface look comes only from the material input.
• Verification establishes bounds and triangle count, not vertex-by-vertex or normal equivalence. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: GLTFDocument. Output kind: ["geometry"].

sphere#

Creates a MeshInstance3D holding a full native SphereMesh of the given radius, centred on position. Schemaxis fixes the height at twice the radius and the tessellation at 32 radial segments and 15 rings (1024 triangles), so a sphere always reopens with exactly those native parameters. Choose it for balls, markers and material comparisons; for an ellipsoid, apply a non-uniform scale.

Common mistakes and assumptions:

• The surface is a polygon approximation with 32 segments around; it is not suitable as an exact analytic sphere.
• It needs a material input naming an earlier material node. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: SphereMesh. Output kind: ["geometry"].

spotLight#

Creates a SpotLight3D: a cone of light from position along the node's rotated -Z axis, with angle as the cone's half-angle and range as its reach in metres. attenuation and angleAttenuation shape the fall-off with distance and towards the cone edge; shadows can be enabled. Choose it for key lights, stage lights or torches; use omniLight for light in all directions.

Common mistakes and assumptions:

• With rotation [0, 0, 0] the cone points horizontally along -Z; aim it with a negative X angle (downward) and a Y angle (heading).
• angle is measured from the cone axis to its edge, so 45 gives a 90-degree wide cone.

Native binding: SpotLight3D. Output kind: ["light"].

Inputs: none.

sprite3D#

Embeds a PNG image as an editable Sprite3D with an ImageTexture: a flat, double-sided picture centred on position, facing +Z, whose world size is the image size in pixels multiplied by pixelSize. Choose it to show pixel art, a sprite sheet from an Aseprite operation or any other PNG inside a 3D scene; it needs no material and counts as the visible geometry a scene requires. Schemaxis uses nearest-neighbour filtering so pixels stay crisp, and checks the reopened texture's dimensions and RGBA pixel digest.

Common mistakes and assumptions:

• Only non-interlaced 8-bit RGB or RGBA PNG up to 4096 x 4096 pixels is accepted; palette, greyscale, 16-bit and interlaced files fail with INVALID_IMAGE.
• The sprite is not a billboard and has no rotation or scale option: it always faces +Z, so a camera looking along +Z sees its back (mirrored).
• A whole sprite sheet is shown as one picture; frames are not animated.

Native binding: Sprite3D. Output kind: ["image"].

Inputs: none.

torus#

Creates a MeshInstance3D holding a native TorusMesh: a ring lying in its local XZ plane around the local Y axis, centred on position. innerRadius is the radius of the hole and outerRadius the overall radius, so the tube is outerRadius - innerRadius thick. Tessellation is fixed at 32 rings and 16 ring segments. Choose it for rings, wheels and seals.

Common mistakes and assumptions:

• innerRadius must be smaller than outerRadius; equal or reversed values fail planning with INVALID_ARGUMENT.
• It needs a material input naming an earlier material node. Schemaxis qualified this operation natively only on small CPU-only scenes with Godot 4.7.2 (build, fresh-process reopen and readback); visual quality and GUI editing were not qualified.

Native binding: TorusMesh. Output kind: ["geometry"].

transformGroup#

Create a named, non-renderable Node3D transform group to move, rotate and scale a static assembly together. Connect child geometry or other groups through inputs.parent. Transform options are local to the parent; leaving parent out attaches to the scene root. Group world bounds enclose descendant geometry; empty groups have no bounds. Cameras, lights and sprites stay at the root.

Common mistakes and assumptions:

• This is a transform hierarchy, not Godot named membership groups, animation, instancing or physics. All descendants remain owned by the saved scene root.

Native binding: Node3D. Output kind: ["group"].