Scenario Godot 3D World

Godot 3D world (level and environment artist)

Target: Godot 4.7.2.stable, macOS Apple Silicon, Jolt Physics, Forward+.

REQUIRED BACKGROUND: scenario-godot-expert (channels, gd_run, the review loop, 4.7 traps). If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

Status (2026-10-02): all 14 live test groups in tests/code/godot-3d-world/test_world_live.py passed (live_20261002-215949.json); L8 and L12 were extended and passed again in round 2 (live_20261002-223935.json). The 11 offline checks pass. Details in references/procedures.md.

Toolkit: scripts/gd_world.py (runner side) and scripts/agentkit/world/*.gd (jobs, a post-import script and two runtime scripts), installed with gd_world.install_world(P).

Stance (the expert delta)

1. Zero Y before normalizing the camera-relative direction. GDQuest (JlgZtOFMdfc 00:22:00): otherwise looking down slows the walk. With the order right, the controller kept 6.00 m/s at -60 degrees of pitch.
2. CharacterBody3D needs a stairs module, and the step height must come from the tread. Majikayo (Tb-R3l0SQdc 00:17:01) snaps up with body_test_motion and checks the tread with a ray, because the capsule touches the leading edge. A stock r 0.35 capsule stops at 0.18 m steps. Taking the height from the capsule's travel let it climb 0.6 m over a 0.45 m limit; the tread ray fixed it.
3. Guard the snap-down with a floor-below ray. Majikayo (00:14:58): without it, every ledge walk-off snaps down. The guard does not fix steep stairs: keep the rise at or under about 0.25 m for smooth descents.
4. Graybox in CSG, then bake it; never animate it. Four Games (gIK02BgCCBI) and PiCode (S5kRpEKIh38 00:01:51): static CSG costs about what modeled geometry costs, moving CSG is slow, and the cost follows the operand (a 128-segment sphere cut cost 1,000 times a box cut per move). CSG needs closed meshes: an open CSGMesh3D operand is silently ignored, with no error.
5. Prefer simple collision for props. Four Games (00:05:37) prefers -colonly hand shapes. Trimesh (-col) for static level geometry only, box or convex for props and anything dynamic, -noimp for reference geometry.
6. Post-import scripts work outside the tree. Allard (5fDuf2IlizU 00:11:14): set owners, use local transforms, use reparent(node, false); set collision layers in the script so they cannot be forgotten (00:15:15). Reproduced: an unowned node is not saved, global_transform returns identity, default reparent() zeroes the position.
7. Spring arm with a sphere and the player excluded. Octodemy (ZCb12AHKMfE 00:07:40, 00:08:35): SphereShape3D r 0.3, a top_level pivot, add_excluded_object(player). The arm stops one radius before a wall.
8. AI GLBs are normalized placeholders until a manifest says otherwise. Scenario-delivered Tripo, Meshy and Hitem3D files arrived unit-boxed, pivot centered, double-sided, metallic 1.0, 4K maps, 15k to 1M triangles. Jan (L5emNlNYVfY 00:02:00, vendor) remeshes to 6k to 8k triangles first. Size, pivot, facing, collision and budget come from a manifest the import script applies.
9. Terrain3D: check the region layout, prepare the textures, save binary. Tokisan (oV8c9alXVwU 00:20:22): badly placed regions multiply memory. In 1.0.2 a 1,024 m terrain centered on the origin takes 16 regions of 256 or 4 of 512 (1.05 km² allocated), but 4 of 1,024 (4.19 km²). Textures seamless, square, power of two, equal sizes, channel-packed (albedo plus height, normal plus roughness), one compression for all (00:04:33; Four Games ejlD8cM9kk4 00:10:06). Save as .res, since .tres loads slowly (YtiAI2F6Xkk 00:01:30).
10. Hand over runnable code, and label measurements. A plan for someone without this kit gives the GDScript the helper runs (procedures.md has it), not only gd_world.* calls. Numbers measured here are effect sizes on an M-series Mac: say so, and re-measure on the target.

Disagreements: capsule (GDQuest) or cylinder (Juli, U5A_JArREUc): capsule for ledge tolerance, cylinder for clean wall-run and slide normals. CharacterBody3D (GDQuest, Juli) or RigidBody3D (Bramwell, sVsn9NqpVhg): RigidBody only when the player must be a simulated object.

Establish first

Workflow

1. Project gate (P1). gd_world.physics_gate(P) proves the engine: with Jolt, a ray on a concave shape returns face_index -1 (Godot Physics returns 8). A hand-written project.godot gets Godot Physics. Name the layers with set_layer_names. GATE: engine_running "Jolt Physics", no flags.
2. Player (P2). build_player, then controller_suite (headless, --fixed-fps 60). GATE: speed at move_speed, same speed looking down, jump apex within 0.1 m of v²/2g, stairs to max_step_height and a refusal above, no snap at the ledge, 40-degree ramp yes and 50 no, arm shorter at the wall.
3. Blockout (P3). validate_layout(layout) offline, then build_village, door_test, bake. GATE: every door walkable by the real capsule (0.70 m blocks, 0.72 m passes for r 0.35; the offline rule asks 1.00 m [added margin]), baked triangles equal CSG triangles, capture reads as intended.
4. Kit (P4). build_kit, build_grid, stairs_walk. Materials go on the mesh surfaces and each item holds one StaticBody3D and one NavigationRegion3D (docs). Set the lightmap texel size before building the library (GridMap auto-UV2 uses 0.1 per the docs, not re-measured; the .import default is 0.2) and keep navmesh cell size equal to the map's 0.25 (docs). GATE: a ray hit on every used cell, and the player climbs each stairs item (a 3 m story needs 8 steps; 6 blocked).
5. Terrain (P5, P6). Small worlds: build_island (chunked ArrayMesh plus one HeightMapShape3D), then collision_check. Sculpted or painted worlds: gd_world.terrain3d, with change_region_size() (setting region_size is ignored) and region-aligned placement. Painting is a human step: base paint on large consistent areas, then spray, never spray over autoshader areas (YtiAI2F6Xkk 00:05:45 to 00:07:25). GATE: collision within 0.1 m at 400 rays, region count and size recorded, .res data, capture opened.
6. Scatter (P7). gd_world.scatter, always windowed. GATE: every instance grounded, a buffer per tile in the .tscn, rejections counted, close capture checked.
7. Props from GLB (P8). glb_stats and glb_flags offline, then ingest_glbs(P, drop, manifest) (pre-written .import with LODs, shadow meshes and light baking, post_import_prop.gd, textures retuned to VRAM at 2048), then audit_props and lod_probe. Asset front is +Z (Vector3.MODEL_FRONT); look_at(t, up, true) turns +Z to the target. Blender exports are triangulated, transforms applied, rig in rest pose (docs). GATE: manifest heights, base at y 0, cull back, budget flags understood, lineup capture next to a 1.8 m reference, facing checked.
8. Streaming (P9). runtime/cell_streamer.gd, unload_radius greater than load_radius, tested windowed with world_stream.gd:walk. GATE: 0 requests pacing on a border, every cell unloaded and the node count back to baseline at the end, worst frame within budget.
9. Audit and profile (P10). audit_level(scenes), then gd_run.profile_scene(..., driver="vulkan"). GATE: no leftover CSG, no headless MultiMesh, no unnamed layers; GPU ms and draw calls recorded. Windowed frame time is capped at the display refresh, so judge GPU and CPU ms.