Build chunked render meshes with LOD and seam handling, biome splat materials, and server-side collision that needs no renderer.
Acceptance
Collision works in the headless server, and character tests pass on generated terrain.
No visible cracks between LOD levels in a capture.
Chunk streaming causes no frame spike over 8 ms in the profiler scenario.
**Depends on:** W2
Build chunked render meshes with LOD and seam handling, biome splat materials, and server-side collision that needs no renderer.
**Acceptance**
- Collision works in the headless server, and character tests pass on generated terrain.
- No visible cracks between LOD levels in a capture.
- Chunk streaming causes no frame spike over 8 ms in the profiler scenario.
claude
added this to the v0.2 Movement and Island milestone 2026-11-09 05:26:05 +00:00
src/client/terrain/terrain_view.gd: TerrainView draws the island as 16 × 16 chunks of 64 m. Each chunk is shown at one of four detail levels (2, 4, 8 and 16 m spacing), chosen by its distance to the camera. Geometry is built on WorkerThreadPool threads, nearest chunks first, with at most 6 in flight. The main thread only uploads finished meshes, within 2 ms per frame.
terrain_chunk_builder.gd: builds a chunk's arrays as a pure function. Seams: skirts hang from every edge, deeper than twice the most any level strays from the full-resolution edge. Normals come from the full-resolution heightfield at every level, so lighting matches across a boundary.
terrain.gdshader: a procedural splat with no textures. It blends sand, marsh, grass and rock using band weights averaged over 4 m. Steep ground turns to rock, and summits weather to pale stone.
Collision: the server and prediction use SimGround's heightfield only. Nothing from the renderer is involved.
Capture scenarios: terrain, terrain_lod (chunks tinted by level), terrain_cracks and terrain_cracks_control. tools/crack_check.gd counts sky pixels seen through the ground. make terrain-capture requires cracks in the skirtless control and none in the real terrain.
How it was tested
make check passes: 111 tests, self-check and smoke.
On seeds 11 and 12, 12 players move randomly for 900 ticks and never sink into the ground. A player sprints from 150 m out towards the tallest summit, climbs more than 15 m, and takes no damage.
Seams: on sampled shared edges, every pairing of the four levels is checked, and each gap is smaller than the skirt.
make terrain-capture: the control shows 437 crack pixels, and the real terrain shows 0. I also looked at the captures. The level rings are visible in terrain_lod, with no seams. Before a fix, the cracks view showed skirts lit as back faces, as thin dark lines. The shader now lights both faces from the terrain normal, and the lines are gone.
Profiler scenario (test_streaming_across_the_island_stays_under_the_frame_budget): the camera flies 1 km across the island at 30 m/s (0.5 m per frame at 60 fps), for 2,037 frames and 661 chunk rebuilds. The worst main-thread frame was 0.8 to 1.4 ms across 7 runs, against the 8 ms limit. This is headless CPU time only. GPU upload cost and real frame times need a GPU playtest.
One earlier run, under heavy host load (load average about 10), recorded a single 238 ms frame. I couldn't reproduce it in 7 later runs, so I opened a hardening follow-up to keep watching it.
The coastal views show bare sea floor, because water arrives with W6. Lowland is plain grass until W5 adds vegetation.
Done in 8b74485.
**What changed**
- `src/client/terrain/terrain_view.gd`: `TerrainView` draws the island as 16 × 16 chunks of 64 m. Each chunk is shown at one of four detail levels (2, 4, 8 and 16 m spacing), chosen by its distance to the camera. Geometry is built on `WorkerThreadPool` threads, nearest chunks first, with at most 6 in flight. The main thread only uploads finished meshes, within 2 ms per frame.
- `terrain_chunk_builder.gd`: builds a chunk's arrays as a pure function. **Seams:** skirts hang from every edge, deeper than twice the most any level strays from the full-resolution edge. Normals come from the full-resolution heightfield at every level, so lighting matches across a boundary.
- `terrain.gdshader`: a procedural splat with no textures. It blends sand, marsh, grass and rock using band weights averaged over 4 m. Steep ground turns to rock, and summits weather to pale stone.
- **Collision:** the server and prediction use `SimGround`'s heightfield only. Nothing from the renderer is involved.
- Capture scenarios: `terrain`, `terrain_lod` (chunks tinted by level), `terrain_cracks` and `terrain_cracks_control`. `tools/crack_check.gd` counts sky pixels seen through the ground. `make terrain-capture` requires cracks in the skirtless control and none in the real terrain.
**How it was tested**
- `make check` passes: 111 tests, self-check and smoke.
- On seeds 11 and 12, 12 players move randomly for 900 ticks and never sink into the ground. A player sprints from 150 m out towards the tallest summit, climbs more than 15 m, and takes no damage.
- Seams: on sampled shared edges, every pairing of the four levels is checked, and each gap is smaller than the skirt.
- `make terrain-capture`: the control shows 437 crack pixels, and the real terrain shows **0**. I also looked at the captures. The level rings are visible in `terrain_lod`, with no seams. Before a fix, the cracks view showed skirts lit as back faces, as thin dark lines. The shader now lights both faces from the terrain normal, and the lines are gone.
- **Profiler scenario** (`test_streaming_across_the_island_stays_under_the_frame_budget`): the camera flies 1 km across the island at 30 m/s (0.5 m per frame at 60 fps), for 2,037 frames and 661 chunk rebuilds. The worst main-thread frame was 0.8 to 1.4 ms across 7 runs, against the 8 ms limit. This is **headless CPU time only**. GPU upload cost and real frame times need a GPU playtest.
- One earlier run, under heavy host load (load average about 10), recorded a single 238 ms frame. I couldn't reproduce it in 7 later runs, so I opened a hardening follow-up to keep watching it.
The coastal views show bare sea floor, because water arrives with W6. Lowland is plain grass until W5 adds vegetation.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Depends on: W2
Build chunked render meshes with LOD and seam handling, biome splat materials, and server-side collision that needs no renderer.
Acceptance
Done in
8b74485.What changed
src/client/terrain/terrain_view.gd:TerrainViewdraws the island as 16 × 16 chunks of 64 m. Each chunk is shown at one of four detail levels (2, 4, 8 and 16 m spacing), chosen by its distance to the camera. Geometry is built onWorkerThreadPoolthreads, nearest chunks first, with at most 6 in flight. The main thread only uploads finished meshes, within 2 ms per frame.terrain_chunk_builder.gd: builds a chunk's arrays as a pure function. Seams: skirts hang from every edge, deeper than twice the most any level strays from the full-resolution edge. Normals come from the full-resolution heightfield at every level, so lighting matches across a boundary.terrain.gdshader: a procedural splat with no textures. It blends sand, marsh, grass and rock using band weights averaged over 4 m. Steep ground turns to rock, and summits weather to pale stone.SimGround's heightfield only. Nothing from the renderer is involved.terrain,terrain_lod(chunks tinted by level),terrain_cracksandterrain_cracks_control.tools/crack_check.gdcounts sky pixels seen through the ground.make terrain-capturerequires cracks in the skirtless control and none in the real terrain.How it was tested
make checkpasses: 111 tests, self-check and smoke.make terrain-capture: the control shows 437 crack pixels, and the real terrain shows 0. I also looked at the captures. The level rings are visible interrain_lod, with no seams. Before a fix, the cracks view showed skirts lit as back faces, as thin dark lines. The shader now lights both faces from the terrain normal, and the lines are gone.test_streaming_across_the_island_stays_under_the_frame_budget): the camera flies 1 km across the island at 30 m/s (0.5 m per frame at 60 fps), for 2,037 frames and 661 chunk rebuilds. The worst main-thread frame was 0.8 to 1.4 ms across 7 runs, against the 8 ms limit. This is headless CPU time only. GPU upload cost and real frame times need a GPU playtest.The coastal views show bare sea floor, because water arrives with W6. Lowland is plain grass until W5 adds vegetation.