3D: first objects and running a level

Minimum parts of a 3D level

Entity3D stores a spatial transform. Rendering and physical interaction require separate objects.

MeshInstance3D alone is not an obstacle for a character. Separate visuals from the physics body: rotating decorative geometry should not accidentally change the collision shape. The first 3D game provides a working sequence.

Axes, scale and transforms

The coordinate system is right-handed: +X right, +Y up and +Z back. Camera forward is local -Z; Vector3.Forward is (0, 0, -1). An imported model can have a different authored orientation.

For ordinary game scale, treat 1 unit as 1 meter. Check model size, collision shape and movement speed together. Changing visual scale does not automatically correct an incorrectly sized collider.

Position, Rotation and Scale describe a local transform. GlobalPosition is in world space. A child Entity3D inherits the transform of its immediate Entity3D parent; an ordinary Entity between them breaks the chain. TopLevel disables transform inheritance. See 3D transforms.

Editor view and game camera

In the 3D workspace, select an object in the tree, locate it with the focus-selection action, then change its transform in the inspector or with a gizmo. Check assigned editor shortcuts if a familiar key does not work.

Flying through the 3D workspace changes the editor view. It does not move Camera3D in the game. For the intended game view, configure Camera3D and make it current through Current or MakeCurrent(). The camera must face the geometry; the object must be between Near and Far and included in CullMask.

A Viewport uses one current camera. An additional SubViewport needs its own camera for its 3D view. Confirm the intended frame by running the level before adjusting lighting.

Lighting at runtime

The editor's preview sun and environment do not replace level objects. If a model appears in the editor but becomes dark at runtime, check actual lights, WorldEnvironment and material settings. Unshaded materials are a separate mode, so not every surface requires lighting.

Start with one understandable light source and a controlled environment. Do not enable every effect at once: first check exposure, shadows and surface readability. Continue with lights and shadows and environment.

Verify the first result

1. Confirm that MeshInstance3D has a Mesh and a nonzero scale.
2. Aim Camera3D at the object and run the intended document.
3. Check the frame under actual level lighting, not only the editor preview.
4. If the object must collide, check its physics shape and actual contact separately from its appearance.

For external models, see 3D import; for initial structures, see CSG.