Files
tidewall/test/client/test_terrain.gd
T
claudeandClaude Opus 5.5 8b74485168 W3: Chunked terrain mesh, collision and LOD
TerrainView draws the island as 16 x 16 chunks of 64 m, each at one of
four detail levels (2, 4, 8 and 16 m spacing) chosen by distance to the
camera. TerrainChunkBuilder builds chunk geometry on WorkerThreadPool
threads; the main thread only uploads finished meshes, within a 2 ms
per-frame budget, nearest chunks first.

- Seams: every chunk hangs skirts deeper than twice the most any level
  strays from the full-resolution edge, so neighbours at any two levels
  meet without a crack. Normals come from the full-resolution heightfield
  at every level, and back faces light like the ground above them.
- Splat material: a procedural shader blends sand, marsh, grass and rock
  with weights from the island's bands, averaged over 4 m so borders
  blend. Steep ground turns to rock and summits weather pale.
- Collision stays SimGround's heightfield, with no renderer involved.
- Capture scenarios terrain, terrain_lod (tinted by level) and
  terrain_cracks (magenta sky). tools/crack_check.gd counts sky pixels
  seen through the ground; make terrain-capture requires cracks in a
  skirtless control and none in the real terrain.

Tests: chunk vertices sit on the heightfield; skirts cover every pairing
of levels on sampled shared edges; detail falls with distance; flying
across the island at 30 m/s for 2,037 frames streams 661 chunk rebuilds
with the worst main-thread frame at 0.8 to 1.4 ms (headless, CPU only);
24 players over 900 ticks on two generated islands never sink into the
ground, and a player sprints up towards a summit unharmed.
make terrain-capture: control 437 crack pixels, terrain 0.

Closes #10

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 14:28:30 -05:00

133 lines
6.1 KiB
GDScript

extends TestCase
const SEED: int = 2
## The streaming budget from issue W3: no frame's terrain work may exceed this.
const FRAME_SPIKE_USEC: int = 8_000
var _island: Island
func before_each() -> void:
if _island == null:
_island = Island.generate(SEED)
func test_chunk_vertices_sit_on_the_heightfield() -> void:
var ground: SimGround = _island.ground
var chunk: Vector2i = Vector2i(7, 6)
var rect: Rect2 = TerrainChunkBuilder.chunk_rect(ground, chunk)
for lod: int in TerrainChunkBuilder.LOD_STEPS.size():
var arrays: Array = TerrainChunkBuilder.build(ground, _island.bands, chunk, lod)
var vertices: PackedVector3Array = arrays[Mesh.ARRAY_VERTEX]
var per_side: int = TerrainChunkBuilder.CHUNK_CELLS / TerrainChunkBuilder.LOD_STEPS[lod] + 1
assert_eq(vertices.size(), per_side * per_side + 4 * per_side, "vertex count at level %d" % lod)
var triangles: int = 2 * (per_side - 1) * (per_side - 1) + 4 * 2 * (per_side - 1)
assert_eq((arrays[Mesh.ARRAY_INDEX] as PackedInt32Array).size(), triangles * 3)
for index: int in per_side * per_side:
var vertex: Vector3 = vertices[index]
assert_true(rect.grow(0.001).has_point(Vector2(vertex.x, vertex.z)), "vertex %s outside its chunk" % vertex)
assert_near(vertex.y, ground.terrain_height(vertex.x, vertex.z), 0.001)
for normal: Vector3 in arrays[Mesh.ARRAY_NORMAL] as PackedVector3Array:
assert_true(normal.is_normalized() and normal.y > 0.0, "bad normal %s" % normal)
for weights: Color in arrays[Mesh.ARRAY_COLOR] as PackedColorArray:
assert_near(weights.r + weights.g + weights.b + weights.a, 1.0, 0.001)
func test_world_is_covered_by_chunks() -> void:
var ground: SimGround = _island.ground
var count: int = TerrainChunkBuilder.chunks_per_side(ground)
var last: Rect2 = TerrainChunkBuilder.chunk_rect(ground, Vector2i(count - 1, count - 1))
assert_near(last.end.x, Tuning.WORLD_SIZE_METRES, 0.001)
assert_near(last.end.y, Tuning.WORLD_SIZE_METRES, 0.001)
func test_skirts_cover_every_level_pairing_on_shared_edges() -> void:
# Along every shared edge, two neighbours at any two detail levels may disagree on
# height. The skirt of each must hang further than that, or a crack opens.
var ground: SimGround = _island.ground
var count: int = TerrainChunkBuilder.chunks_per_side(ground)
var levels: int = TerrainChunkBuilder.LOD_STEPS.size()
var checked: int = 0
for z: int in range(2, count - 2, 3):
for x: int in range(2, count - 2, 3):
var a: Vector2i = Vector2i(x, z)
var b: Vector2i = Vector2i(x + 1, z)
var depth: float = minf(TerrainChunkBuilder.skirt_depth(ground, a), TerrainChunkBuilder.skirt_depth(ground, b))
for lod_a: int in levels:
var edge_a: PackedFloat32Array = _edge_profile(a, lod_a, 3)
for lod_b: int in levels:
var edge_b: PackedFloat32Array = _edge_profile(b, lod_b, 2)
for index: int in edge_a.size():
var gap: float = absf(edge_a[index] - edge_b[index])
assert_true(gap < depth - TerrainChunkBuilder.SKIRT_MARGIN * 0.5,
"chunks %s/%s levels %d/%d: gap %.2f m, skirt %.2f m" % [a, b, lod_a, lod_b, gap, depth])
checked += 1
assert_true(checked > 100, "checked only %d pairings" % checked)
func test_detail_falls_with_distance() -> void:
var view: TerrainView = TerrainView.new()
view.setup(_island)
view.focus = Vector3(500.0, 30.0, 500.0)
var here: Vector2i = Vector2i(7, 7)
assert_eq(view.wanted_lod(here), 0, "the focus chunk is full detail")
var previous: int = 0
for x: int in range(7, 16):
var lod: int = view.wanted_lod(Vector2i(x, 7))
assert_true(lod >= previous, "detail must not rise with distance")
previous = lod
assert_eq(previous, TerrainChunkBuilder.LOD_STEPS.size() - 1, "the far edge is coarsest")
view.free()
func test_streaming_across_the_island_stays_under_the_frame_budget() -> void:
# The profiler scenario: load the island around one end, then fly the focus across it
# at 30 m/s for a 60 fps frame rate (0.5 m per frame), measuring the main-thread time
# TerrainView spends each frame. Geometry is built on worker threads. Headless, so this
# measures CPU work only; GPU upload time needs a real-GPU playtest.
var tree: SceneTree = Engine.get_main_loop() as SceneTree
var view: TerrainView = TerrainView.new()
view.setup(_island)
view.focus = Vector3(150.0, 30.0, 150.0)
tree.root.add_child(view)
view.build_all_now()
var loaded: int = view.uploads
view.max_frame_usec = 0
var start: Vector3 = view.focus
var finish: Vector3 = Vector3(880.0, 30.0, 860.0)
var frames: int = ceili(start.distance_to(finish) / 0.5)
for frame: int in frames:
view.focus = start.lerp(finish, float(frame) / frames)
await tree.process_frame
for _frame: int in 600:
if view.settled():
break
await tree.process_frame
var streamed: int = view.uploads - loaded
print(" terrain streaming: %d frames, %d chunk rebuilds, worst frame %d us" % [frames, streamed, view.max_frame_usec])
assert_true(streamed > 50, "expected real streaming, got %d rebuilds" % streamed)
assert_true(view.settled(), "terrain never caught up with the focus")
assert_true(view.max_frame_usec < FRAME_SPIKE_USEC, "worst frame %d us" % view.max_frame_usec)
view.queue_free()
await tree.process_frame
## Heights along a chunk's edge at full-resolution spacing, as that chunk draws them at
## `lod`: each coarse span is a straight line between its end samples.
func _edge_profile(chunk: Vector2i, lod: int, edge_column_side: int) -> PackedFloat32Array:
var arrays: Array = TerrainChunkBuilder.build(_island.ground, _island.bands, chunk, lod)
var vertices: PackedVector3Array = arrays[Mesh.ARRAY_VERTEX]
var step: int = TerrainChunkBuilder.LOD_STEPS[lod]
var per_side: int = TerrainChunkBuilder.CHUNK_CELLS / step + 1
# Side 3 is the east column, side 2 the west column; both run along z.
var column: int = per_side - 1 if edge_column_side == 3 else 0
var profile: PackedFloat32Array = PackedFloat32Array()
for position: int in TerrainChunkBuilder.CHUNK_CELLS + 1:
var low: int = position / step
var high: int = mini(low + 1, per_side - 1)
var t: float = float(position % step) / step
var a: float = vertices[low * per_side + column].y
var b: float = vertices[high * per_side + column].y
profile.append(lerpf(a, b, t))
return profile