From 8b744851689174c54bbacb4155ca60e4b841f6dc Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 14:28:30 -0500 Subject: [PATCH] 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 --- CLAUDE.md | 1 + Makefile | 6 +- docs/ARCHITECTURE.md | 15 ++ src/client/terrain/terrain.gdshader | 81 ++++++++ src/client/terrain/terrain.gdshader.uid | 1 + src/client/terrain/terrain_chunk_builder.gd | 178 ++++++++++++++++++ .../terrain/terrain_chunk_builder.gd.uid | 1 + src/client/terrain/terrain_view.gd | 176 +++++++++++++++++ src/client/terrain/terrain_view.gd.uid | 1 + test/capture/terrain.tscn | 6 + test/capture/terrain_cracks.tscn | 11 ++ test/capture/terrain_cracks_control.tscn | 12 ++ test/capture/terrain_lod.tscn | 10 + test/capture/terrain_scene.gd | 71 +++++++ test/capture/terrain_scene.gd.uid | 1 + test/client/test_terrain.gd | 132 +++++++++++++ test/client/test_terrain.gd.uid | 1 + test/sim/test_island_movement.gd | 60 ++++++ test/sim/test_island_movement.gd.uid | 1 + tools/crack_check.gd | 52 +++++ tools/crack_check.gd.uid | 1 + tools/terrain_capture_check.sh | 23 +++ 22 files changed, 840 insertions(+), 1 deletion(-) create mode 100644 src/client/terrain/terrain.gdshader create mode 100644 src/client/terrain/terrain.gdshader.uid create mode 100644 src/client/terrain/terrain_chunk_builder.gd create mode 100644 src/client/terrain/terrain_chunk_builder.gd.uid create mode 100644 src/client/terrain/terrain_view.gd create mode 100644 src/client/terrain/terrain_view.gd.uid create mode 100644 test/capture/terrain.tscn create mode 100644 test/capture/terrain_cracks.tscn create mode 100644 test/capture/terrain_cracks_control.tscn create mode 100644 test/capture/terrain_lod.tscn create mode 100644 test/capture/terrain_scene.gd create mode 100644 test/capture/terrain_scene.gd.uid create mode 100644 test/client/test_terrain.gd create mode 100644 test/client/test_terrain.gd.uid create mode 100644 test/sim/test_island_movement.gd create mode 100644 test/sim/test_island_movement.gd.uid create mode 100644 tools/crack_check.gd create mode 100644 tools/crack_check.gd.uid create mode 100755 tools/terrain_capture_check.sh diff --git a/CLAUDE.md b/CLAUDE.md index eb7ec92..c1bed02 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,6 +25,7 @@ continuity. | `tools/godot.sh ...` | Runs the pinned engine. Headless by default. | | `tools/capture.sh ` | Renders the real client offscreen in a throwaway `tidewall-capture-*` Docker container (Xvfb, Mesa software rendering) and saves a PNG. Fails on a blank frame or a renderer fallback. | | `tools/godot.sh --script res://tools/island_map.gd -- --seed=N --out=res://captures/island.png` | Draws a top-down map of a seed's island, with a contour at each tide level. | +| `make terrain-capture` | Renders the terrain crack check and a skirtless control in the capture container. The control must crack and the real terrain must not. Needs Docker. | | `make capture-test` | Proves the capture harness works and rejects a blank frame. Needs Docker, so it isn't part of `make check`. | Run one group of tests with `tools/run_tests.sh --root=res://test/sim` or diff --git a/Makefile b/Makefile index b1d6694..901567a 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # Tidewall build entry points. Everything runs headless with the repo-local engine. GODOT := tools/godot.sh -.PHONY: check import parse test test-selfcheck smoke capture-test binaries verify-engine +.PHONY: check import parse test test-selfcheck smoke capture-test terrain-capture binaries verify-engine ## Everything that must pass before a push. check: verify-engine binaries parse test test-selfcheck smoke @@ -33,3 +33,7 @@ smoke: import ## Renders the capture test scenes in the offscreen container. Needs Docker. capture-test: import @tools/capture_selfcheck.sh + +## Renders the terrain crack check and its control in the offscreen container. Needs Docker. +terrain-capture: import + @tools/terrain_capture_check.sh diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 99d9c4c..f12ac54 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -120,11 +120,26 @@ sent on a reliable ordered event stream, since a dropped wall is a gameplay lie. | `src/audio/` | Sound playback, music | `src/sim/` (read only) | | `src/app/` | Startup and mode selection | Everything | +## Terrain + +The island's heightfield (`Island`, in `src/sim/`) is the only terrain collision, on +the server and in client prediction. Nothing in the renderer is ever used for collision. + +The client draws it with `TerrainView` (`src/client/terrain/`): 64 m chunks at four +levels of detail chosen by distance to the camera. `TerrainChunkBuilder` builds chunk +geometry on `WorkerThreadPool` threads, and the main thread only uploads finished meshes, +within a per-frame budget. Each chunk hangs skirts from its edges deeper than any two +levels can disagree, so a level boundary never opens a crack. Normals come from the +full-resolution heightfield at every level, so lighting doesn't change across a boundary. +The terrain shader blends procedural sand, marsh, grass and rock layers using splat +weights from the island's elevation bands, with rock on steep ground. + ## Performance budgets | Budget | Target | |---|---| | Server tick | Under **12 ms** with 24 players | | Client | **60 fps** on a GTX 1060-class GPU at medium settings | +| Terrain streaming | Under **8 ms** of main-thread work in any frame (measured headless; GPU upload unmeasured) | Software rendering in CI can't verify the client budget. It needs a real GPU playtest. diff --git a/src/client/terrain/terrain.gdshader b/src/client/terrain/terrain.gdshader new file mode 100644 index 0000000..195e657 --- /dev/null +++ b/src/client/terrain/terrain.gdshader @@ -0,0 +1,81 @@ +// Tidewall terrain: four procedural layers (sand, marsh, grass, rock) blended by the +// splat weights in the vertex colour, with rock taking over on steep ground and weathered +// pale stone on the summits. No textures: every pattern is generated here. +shader_type spatial; +render_mode cull_disabled; + +uniform float summit_height = 50.0; +uniform float max_slope_cos = 0.69; +uniform vec3 sand_colour : source_color = vec3(0.80, 0.71, 0.52); +uniform vec3 marsh_colour : source_color = vec3(0.37, 0.39, 0.25); +uniform vec3 grass_colour : source_color = vec3(0.31, 0.42, 0.22); +uniform vec3 rock_colour : source_color = vec3(0.47, 0.44, 0.39); +uniform vec3 summit_colour : source_color = vec3(0.74, 0.72, 0.67); +// Debug: tint each chunk by its level of detail (set per instance by TerrainView). +instance uniform float lod_tint = -1.0; + +varying vec3 world_position; +varying vec3 world_normal; + +float hash(vec2 p) { + p = fract(p * vec2(123.34, 456.21)); + p += dot(p, p + 45.32); + return fract(p.x * p.y); +} + +float value_noise(vec2 p) { + vec2 i = floor(p); + vec2 f = fract(p); + vec2 u = f * f * (3.0 - 2.0 * f); + return mix(mix(hash(i), hash(i + vec2(1.0, 0.0)), u.x), + mix(hash(i + vec2(0.0, 1.0)), hash(i + vec2(1.0, 1.0)), u.x), u.y); +} + +float fbm(vec2 p) { + float total = 0.0; + float amplitude = 0.5; + for (int octave = 0; octave < 4; octave++) { + total += amplitude * value_noise(p); + p *= 2.03; + amplitude *= 0.5; + } + return total; +} + +void vertex() { + world_position = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz; + world_normal = normalize((MODEL_MATRIX * vec4(NORMAL, 0.0)).xyz); +} + +void fragment() { + vec2 p = world_position.xz; + float broad = fbm(p * 0.035); + float fine = fbm(p * 0.6); + + float ripple = 0.5 + 0.5 * sin(dot(p, vec2(0.55, 0.32)) + broad * 9.0); + vec3 sand = sand_colour * (0.9 + 0.12 * fine) * (0.97 + 0.04 * ripple); + vec3 marsh = mix(marsh_colour * 0.75, marsh_colour * 1.1, smoothstep(0.35, 0.65, broad + 0.2 * fine)); + vec3 grass = grass_colour * (0.78 + 0.35 * broad) * (0.9 + 0.15 * fine); + grass = mix(grass, grass * vec3(1.15, 1.05, 0.7), smoothstep(0.55, 0.75, broad)); + float strata = 0.5 + 0.5 * sin(world_position.y * 2.1 + broad * 5.0); + vec3 rock = rock_colour * (0.82 + 0.22 * fine + 0.1 * strata); + vec3 summit = summit_colour * (0.88 + 0.14 * fine); + rock = mix(rock, summit, smoothstep(summit_height - 4.0, summit_height + 4.0, world_position.y + 3.0 * broad)); + + vec4 weights = max(COLOR, vec4(0.0)); + float steep = 1.0 - smoothstep(max_slope_cos - 0.08, max_slope_cos + 0.12, world_normal.y); + weights = mix(weights, vec4(0.0, 0.0, 0.0, 1.0), steep); + weights /= max(weights.r + weights.g + weights.b + weights.a, 0.0001); + + vec3 albedo = sand * weights.r + marsh * weights.g + grass * weights.b + rock * weights.a; + if (lod_tint >= 0.0) { + vec3 tints[4] = vec3[](vec3(1.0, 0.5, 0.5), vec3(0.5, 1.0, 0.5), vec3(0.5, 0.6, 1.0), vec3(1.0, 1.0, 0.4)); + albedo *= tints[int(lod_tint) % 4]; + } + ALBEDO = albedo; + // Skirts and any face seen from below must light like the ground above them, so + // use the terrain normal for both faces instead of the flipped back-face normal. + NORMAL = normalize((VIEW_MATRIX * vec4(world_normal, 0.0)).xyz); + ROUGHNESS = mix(0.95, 0.6, weights.g); + SPECULAR = 0.2; +} diff --git a/src/client/terrain/terrain.gdshader.uid b/src/client/terrain/terrain.gdshader.uid new file mode 100644 index 0000000..169dca2 --- /dev/null +++ b/src/client/terrain/terrain.gdshader.uid @@ -0,0 +1 @@ +uid://c7ee5h5pe6qjq diff --git a/src/client/terrain/terrain_chunk_builder.gd b/src/client/terrain/terrain_chunk_builder.gd new file mode 100644 index 0000000..72d0444 --- /dev/null +++ b/src/client/terrain/terrain_chunk_builder.gd @@ -0,0 +1,178 @@ +## Builds render-mesh arrays for one square chunk of the island's heightfield at one +## level of detail. Pure and thread-safe: it only reads the heightfield and bands, so +## TerrainView runs it on worker threads and only uploads meshes on the main thread. +## +## Seams: every chunk hangs a skirt, a vertical strip of triangles, from each edge down +## by more than any level of detail can disagree with any other along that edge. A +## neighbour at a different detail level then meets a wall instead of a gap, so there +## are never cracks to see through. Normals come from the full-resolution heightfield at +## every level, so lighting matches across a level boundary. +## +## Splat weights go in the vertex colour: r sand, g marsh, b grass, a rock. The terrain +## shader blends procedural layers with them. +class_name TerrainChunkBuilder +extends RefCounted + +## Heightfield cells along a chunk's side. 32 cells of 2 m make 64 m chunks. +const CHUNK_CELLS: int = 32 +## Sample step at each level of detail. Level 0 is full resolution. +const LOD_STEPS: Array[int] = [1, 2, 4, 8] +const SKIRT_MARGIN: float = 0.5 +## Samples either side that splat weights are averaged over. +const WEIGHT_RADIUS: int = 2 + +const _BAND_WEIGHTS: Dictionary = { + Island.Band.SEA: Color(1.0, 0.0, 0.0, 0.0), + Island.Band.BEACH: Color(1.0, 0.0, 0.0, 0.0), + Island.Band.MARSH: Color(0.0, 1.0, 0.0, 0.0), + Island.Band.FOREST: Color(0.0, 0.0, 1.0, 0.0), + Island.Band.HIGHLAND: Color(0.0, 0.0, 0.0, 1.0), + Island.Band.SUMMIT: Color(0.0, 0.0, 0.0, 1.0), +} + + +## Chunks along each side of the world. +static func chunks_per_side(ground: SimGround) -> int: + return (ground.samples - 1) / CHUNK_CELLS + + +## World-space bounds of a chunk's footprint, as (min x, min z, size). +static func chunk_rect(ground: SimGround, chunk: Vector2i) -> Rect2: + var size: float = CHUNK_CELLS * ground.cell + return Rect2(chunk.x * size, chunk.y * size, size, size) + + +## Mesh arrays for `chunk` at level `lod`, ready for ArrayMesh.add_surface_from_arrays. +## Vertices are in world space. `skirts` is false only for the capture that proves the +## crack check can see cracks. +static func build(ground: SimGround, bands: PackedByteArray, chunk: Vector2i, lod: int, skirts: bool = true) -> Array: + var step: int = LOD_STEPS[lod] + var per_side: int = CHUNK_CELLS / step + 1 + var origin: Vector2i = chunk * CHUNK_CELLS + var samples: int = ground.samples + var heights: PackedFloat32Array = ground.heights + var cell: float = ground.cell + + var vertices: PackedVector3Array = PackedVector3Array() + var normals: PackedVector3Array = PackedVector3Array() + var colours: PackedColorArray = PackedColorArray() + var uvs: PackedVector2Array = PackedVector2Array() + var total: int = per_side * per_side + 4 * per_side + vertices.resize(total) + normals.resize(total) + colours.resize(total) + uvs.resize(total) + + for row: int in per_side: + for column: int in per_side: + var gx: int = origin.x + column * step + var gz: int = origin.y + row * step + var index: int = row * per_side + column + var at: int = gz * samples + gx + vertices[index] = Vector3(gx * cell, heights[at], gz * cell) + normals[index] = _normal(heights, samples, cell, gx, gz) + colours[index] = _weights(bands, samples, gx, gz) + uvs[index] = Vector2(gx, gz) * cell + + var indices: PackedInt32Array = PackedInt32Array() + for row: int in per_side - 1: + for column: int in per_side - 1: + var a: int = row * per_side + column + var b: int = a + 1 + var c: int = a + per_side + var d: int = c + 1 + indices.append_array(PackedInt32Array([a, b, c, b, d, c])) + + var depth: float = skirt_depth(ground, chunk) if skirts else 0.0 + var skirt_start: int = per_side * per_side + # Edges in order: north (row 0), south (last row), west (column 0), east (last column). + for edge: int in 4: + for position: int in per_side: + var top: int = _edge_vertex(edge, position, per_side) + var index: int = skirt_start + edge * per_side + position + vertices[index] = vertices[top] - Vector3(0.0, depth, 0.0) + normals[index] = normals[top] + colours[index] = colours[top] + uvs[index] = uvs[top] + for position: int in per_side - 1: + var top_a: int = _edge_vertex(edge, position, per_side) + var top_b: int = _edge_vertex(edge, position + 1, per_side) + var low_a: int = skirt_start + edge * per_side + position + var low_b: int = low_a + 1 + indices.append_array(PackedInt32Array([top_a, top_b, low_a, top_b, low_b, low_a])) + + var arrays: Array = [] + arrays.resize(Mesh.ARRAY_MAX) + arrays[Mesh.ARRAY_VERTEX] = vertices + arrays[Mesh.ARRAY_NORMAL] = normals + arrays[Mesh.ARRAY_COLOR] = colours + arrays[Mesh.ARRAY_TEX_UV] = uvs + arrays[Mesh.ARRAY_INDEX] = indices + return arrays + + +## How far the skirts hang below a chunk's edges: twice the most that any level of +## detail strays from the full-resolution edge, plus a margin. Two neighbours share +## each edge, so this covers any pairing of levels. +static func skirt_depth(ground: SimGround, chunk: Vector2i) -> float: + var worst: float = 0.0 + var origin: Vector2i = chunk * CHUNK_CELLS + for edge: int in 4: + for step: int in LOD_STEPS: + for position: int in CHUNK_CELLS + 1: + var low: int = (position / step) * step + var high: int = mini(low + step, CHUNK_CELLS) + var t: float = 0.0 if high == low else float(position - low) / float(high - low) + var exact: float = _edge_height(ground, origin, edge, position) + var coarse: float = lerpf(_edge_height(ground, origin, edge, low), _edge_height(ground, origin, edge, high), t) + worst = maxf(worst, absf(exact - coarse)) + return 2.0 * worst + SKIRT_MARGIN + + +## Splat weights averaged over the samples within WEIGHT_RADIUS, so layer borders blend +## over a few metres instead of stepping from sample to sample. +static func _weights(bands: PackedByteArray, samples: int, gx: int, gz: int) -> Color: + var total: Color = Color(0.0, 0.0, 0.0, 0.0) + var count: int = 0 + for z: int in range(maxi(gz - WEIGHT_RADIUS, 0), mini(gz + WEIGHT_RADIUS, samples - 1) + 1): + for x: int in range(maxi(gx - WEIGHT_RADIUS, 0), mini(gx + WEIGHT_RADIUS, samples - 1) + 1): + total += _BAND_WEIGHTS[bands[z * samples + x]] + count += 1 + return total / float(count) + + +static func _edge_height(ground: SimGround, origin: Vector2i, edge: int, position: int) -> float: + var gx: int = origin.x + var gz: int = origin.y + match edge: + 0: + gx += position + 1: + gx += position + gz += CHUNK_CELLS + 2: + gz += position + _: + gx += CHUNK_CELLS + gz += position + return ground.heights[gz * ground.samples + gx] + + +static func _edge_vertex(edge: int, position: int, per_side: int) -> int: + match edge: + 0: + return position + 1: + return (per_side - 1) * per_side + position + 2: + return position * per_side + _: + return position * per_side + per_side - 1 + + +static func _normal(heights: PackedFloat32Array, samples: int, cell: float, gx: int, gz: int) -> Vector3: + var left: float = heights[gz * samples + maxi(gx - 1, 0)] + var right: float = heights[gz * samples + mini(gx + 1, samples - 1)] + var up: float = heights[maxi(gz - 1, 0) * samples + gx] + var down: float = heights[mini(gz + 1, samples - 1) * samples + gx] + return Vector3(left - right, 2.0 * cell, up - down).normalized() diff --git a/src/client/terrain/terrain_chunk_builder.gd.uid b/src/client/terrain/terrain_chunk_builder.gd.uid new file mode 100644 index 0000000..9c5d8fe --- /dev/null +++ b/src/client/terrain/terrain_chunk_builder.gd.uid @@ -0,0 +1 @@ +uid://ccwnw5e74lpwj diff --git a/src/client/terrain/terrain_view.gd b/src/client/terrain/terrain_view.gd new file mode 100644 index 0000000..29c4d1b --- /dev/null +++ b/src/client/terrain/terrain_view.gd @@ -0,0 +1,176 @@ +## Draws the island's terrain as streamed chunks with distance-based levels of detail. +## +## Each frame it picks the wanted detail level for every chunk from its distance to +## `focus` (normally the camera). Chunks whose level changed are rebuilt by +## TerrainChunkBuilder on WorkerThreadPool threads; the main thread only turns finished +## arrays into meshes, and stops for the frame once it has spent UPLOAD_BUDGET_USEC. +## So streaming never builds geometry on the main thread. +## +## Collision never comes from here. The simulation's SimGround is the one solid shape, +## on the server and in client prediction alike. +class_name TerrainView +extends Node3D + +const SHADER: Shader = preload("res://src/client/terrain/terrain.gdshader") +## Distance from the focus to a chunk's nearest point at which each coarser level takes +## over. Index i is where level i + 1 begins. +const LOD_DISTANCES: Array[float] = [90.0, 200.0, 420.0] +## Main-thread time allowed per frame for turning finished builds into meshes. +const UPLOAD_BUDGET_USEC: int = 2_000 +## Builds allowed in flight at once, so a fast camera can't queue the whole island. +const MAX_IN_FLIGHT: int = 6 + +## Where detail is centred, in world space. +var focus: Vector3 = Vector3.ZERO +## Tint chunks by detail level, for captures that check seams. +var show_lod: bool = false +## False only to prove that seams would crack without skirts. Never off in the game. +var skirts: bool = true +## Main-thread microseconds spent in the most recent `_process`, and the most ever. +var last_frame_usec: int = 0 +var max_frame_usec: int = 0 +var uploads: int = 0 + +var _island: Island +var _material: ShaderMaterial +var _per_side: int = 0 +## Chunk -> MeshInstance3D +var _instances: Dictionary = {} +## Chunk -> level currently shown +var _shown: Dictionary = {} +## Chunk -> level being built +var _building: Dictionary = {} +var _finished: Array[Dictionary] = [] +var _mutex: Mutex = Mutex.new() +var _tasks: Array[int] = [] + + +## Prepares the view for `island`. Call before adding to the tree, or right after. +func setup(island: Island) -> void: + _island = island + _per_side = TerrainChunkBuilder.chunks_per_side(island.ground) + _material = ShaderMaterial.new() + _material.shader = SHADER + _material.set_shader_parameter("summit_height", Tuning.ISLAND_SUMMIT_BAND) + _material.set_shader_parameter("max_slope_cos", cos(deg_to_rad(Tuning.MAX_SLOPE_DEGREES))) + + +## Builds every chunk at its wanted level right now, on the calling thread. For loading +## screens, tests and captures, where a hitch doesn't matter. +func build_all_now() -> void: + for chunk: Vector2i in _all_chunks(): + var lod: int = wanted_lod(chunk) + _apply(chunk, lod, TerrainChunkBuilder.build(_island.ground, _island.bands, chunk, lod, skirts)) + + +## The detail level `chunk` should be shown at for the current focus. +func wanted_lod(chunk: Vector2i) -> int: + var rect: Rect2 = TerrainChunkBuilder.chunk_rect(_island.ground, chunk) + var nearest: Vector2 = Vector2( + clampf(focus.x, rect.position.x, rect.end.x), clampf(focus.z, rect.position.y, rect.end.y)) + var distance: float = nearest.distance_to(Vector2(focus.x, focus.z)) + for index: int in LOD_DISTANCES.size(): + if distance < LOD_DISTANCES[index]: + return index + return LOD_DISTANCES.size() + + +## The level a chunk is shown at, or -1 if it isn't built yet. +func shown_lod(chunk: Vector2i) -> int: + return _shown.get(chunk, -1) + + +## True when every chunk is shown at its wanted level and nothing is building. +func settled() -> bool: + if not _building.is_empty(): + return false + for chunk: Vector2i in _all_chunks(): + if shown_lod(chunk) != wanted_lod(chunk): + return false + return true + + +func _process(_delta: float) -> void: + if _island == null: + return + var started: int = Time.get_ticks_usec() + _upload_finished(started) + _queue_changes() + last_frame_usec = Time.get_ticks_usec() - started + max_frame_usec = maxi(max_frame_usec, last_frame_usec) + + +func _exit_tree() -> void: + for task: int in _tasks: + WorkerThreadPool.wait_for_task_completion(task) + _tasks.clear() + + +func _queue_changes() -> void: + # Nearest chunks first, so detail arrives where the player is looking from. + var pending: Array[Vector2i] = [] + for chunk: Vector2i in _all_chunks(): + if not _building.has(chunk) and shown_lod(chunk) != wanted_lod(chunk): + pending.append(chunk) + var centre: Vector2 = Vector2(focus.x, focus.z) + var ground: SimGround = _island.ground + pending.sort_custom(func(a: Vector2i, b: Vector2i) -> bool: + return TerrainChunkBuilder.chunk_rect(ground, a).get_center().distance_squared_to(centre) \ + < TerrainChunkBuilder.chunk_rect(ground, b).get_center().distance_squared_to(centre)) + for chunk: Vector2i in pending: + if _building.size() >= MAX_IN_FLIGHT: + break + var lod: int = wanted_lod(chunk) + _building[chunk] = lod + _tasks.append(WorkerThreadPool.add_task(_build_on_worker.bind(chunk, lod))) + + +func _build_on_worker(chunk: Vector2i, lod: int) -> void: + var arrays: Array = TerrainChunkBuilder.build(_island.ground, _island.bands, chunk, lod, skirts) + _mutex.lock() + _finished.append({"chunk": chunk, "lod": lod, "arrays": arrays}) + _mutex.unlock() + + +func _upload_finished(started: int) -> void: + # Reap completed tasks so the pool doesn't keep their records. + var running: Array[int] = [] + for task: int in _tasks: + if WorkerThreadPool.is_task_completed(task): + WorkerThreadPool.wait_for_task_completion(task) + else: + running.append(task) + _tasks = running + while Time.get_ticks_usec() - started < UPLOAD_BUDGET_USEC: + _mutex.lock() + var result: Dictionary = {} if _finished.is_empty() else _finished.pop_front() + _mutex.unlock() + if result.is_empty(): + return + var chunk: Vector2i = result["chunk"] + _building.erase(chunk) + _apply(chunk, result["lod"], result["arrays"]) + + +func _apply(chunk: Vector2i, lod: int, arrays: Array) -> void: + var mesh: ArrayMesh = ArrayMesh.new() + mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, arrays) + mesh.surface_set_material(0, _material) + var instance: MeshInstance3D = _instances.get(chunk) + if instance == null: + instance = MeshInstance3D.new() + instance.name = "Chunk_%d_%d" % [chunk.x, chunk.y] + add_child(instance) + _instances[chunk] = instance + instance.mesh = mesh + instance.set_instance_shader_parameter("lod_tint", float(lod) if show_lod else -1.0) + _shown[chunk] = lod + uploads += 1 + + +func _all_chunks() -> Array[Vector2i]: + var chunks: Array[Vector2i] = [] + for z: int in _per_side: + for x: int in _per_side: + chunks.append(Vector2i(x, z)) + return chunks diff --git a/src/client/terrain/terrain_view.gd.uid b/src/client/terrain/terrain_view.gd.uid new file mode 100644 index 0000000..e37d638 --- /dev/null +++ b/src/client/terrain/terrain_view.gd.uid @@ -0,0 +1 @@ +uid://dl7o5bhcs733r diff --git a/test/capture/terrain.tscn b/test/capture/terrain.tscn new file mode 100644 index 0000000..a9eafa8 --- /dev/null +++ b/test/capture/terrain.tscn @@ -0,0 +1,6 @@ +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://test/capture/terrain_scene.gd" id="1"] + +[node name="CaptureTerrain" type="Node3D"] +script = ExtResource("1") diff --git a/test/capture/terrain_cracks.tscn b/test/capture/terrain_cracks.tscn new file mode 100644 index 0000000..6f60dc4 --- /dev/null +++ b/test/capture/terrain_cracks.tscn @@ -0,0 +1,11 @@ +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://test/capture/terrain_scene.gd" id="1"] + +[node name="CaptureTerrainCracks" type="Node3D"] +script = ExtResource("1") +eye = Vector2(520, 640) +lift = 160.0 +target = Vector3(520, 20, 470) +crack_check = true +fov = 60.0 diff --git a/test/capture/terrain_cracks_control.tscn b/test/capture/terrain_cracks_control.tscn new file mode 100644 index 0000000..da68cca --- /dev/null +++ b/test/capture/terrain_cracks_control.tscn @@ -0,0 +1,12 @@ +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://test/capture/terrain_scene.gd" id="1"] + +[node name="CaptureTerrainCracksControl" type="Node3D"] +script = ExtResource("1") +eye = Vector2(520, 640) +lift = 160.0 +target = Vector3(520, 20, 470) +crack_check = true +fov = 60.0 +skirts = false diff --git a/test/capture/terrain_lod.tscn b/test/capture/terrain_lod.tscn new file mode 100644 index 0000000..68b6244 --- /dev/null +++ b/test/capture/terrain_lod.tscn @@ -0,0 +1,10 @@ +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://test/capture/terrain_scene.gd" id="1"] + +[node name="CaptureTerrainLod" type="Node3D"] +script = ExtResource("1") +eye = Vector2(560, 700) +lift = 140.0 +target = Vector3(520, 20, 430) +show_lod = true diff --git a/test/capture/terrain_scene.gd b/test/capture/terrain_scene.gd new file mode 100644 index 0000000..d91b7d2 --- /dev/null +++ b/test/capture/terrain_scene.gd @@ -0,0 +1,71 @@ +## Capture scenario for the streamed island terrain. The camera stands `lift` metres above +## the ground at `eye` (x, z) and looks at `target`. With `crack_check` the sky is a flat +## magenta that appears nowhere in the terrain, so any crack between chunks shows up as +## magenta pixels for tools/crack_check.gd to count. +extends Node3D + +const CRACK_COLOUR: Color = Color(1.0, 0.0, 1.0) + +@export var island_seed: int = 2 +@export var eye: Vector2 = Vector2(700.0, 760.0) +@export var lift: float = 12.0 +@export var target: Vector3 = Vector3(520.0, 35.0, 470.0) +@export var show_lod: bool = false +@export var crack_check: bool = false +@export var fov: float = 70.0 +## Off only in terrain_cracks_control, which must show cracks. +@export var skirts: bool = true + + +func _ready() -> void: + var island: Island = Island.generate(island_seed) + var environment: Environment = Environment.new() + if crack_check: + environment.background_mode = Environment.BG_COLOR + environment.background_color = CRACK_COLOUR + environment.ambient_light_source = Environment.AMBIENT_SOURCE_COLOR + environment.ambient_light_color = Color(0.5, 0.5, 0.5) + environment.tonemap_mode = Environment.TONE_MAPPER_LINEAR + else: + var sky_material: ProceduralSkyMaterial = ProceduralSkyMaterial.new() + sky_material.sky_top_color = Color(0.32, 0.5, 0.68) + sky_material.sky_horizon_color = Color(0.82, 0.78, 0.68) + sky_material.ground_bottom_color = Color(0.18, 0.2, 0.2) + sky_material.ground_horizon_color = Color(0.82, 0.78, 0.68) + var sky: Sky = Sky.new() + sky.sky_material = sky_material + environment.background_mode = Environment.BG_SKY + environment.sky = sky + environment.ambient_light_source = Environment.AMBIENT_SOURCE_SKY + environment.ambient_light_energy = 0.45 + environment.tonemap_mode = Environment.TONE_MAPPER_FILMIC + environment.fog_enabled = true + environment.fog_light_color = Color(0.78, 0.78, 0.74) + environment.fog_density = 0.0005 + environment.fog_aerial_perspective = 0.4 + var world: WorldEnvironment = WorldEnvironment.new() + world.environment = environment + add_child(world) + + var sun: DirectionalLight3D = DirectionalLight3D.new() + sun.rotation_degrees = Vector3(-35.0, -130.0, 0.0) + sun.light_energy = 0.95 + sun.shadow_enabled = not crack_check + sun.directional_shadow_max_distance = 600.0 + add_child(sun) + + var camera: Camera3D = Camera3D.new() + camera.fov = fov + camera.far = 2000.0 + camera.position = Vector3(eye.x, island.ground.terrain_height(eye.x, eye.y) + lift, eye.y) + add_child(camera) + camera.look_at(target) + camera.make_current() + + var terrain: TerrainView = TerrainView.new() + terrain.setup(island) + terrain.focus = camera.position + terrain.show_lod = show_lod + terrain.skirts = skirts + add_child(terrain) + terrain.build_all_now() diff --git a/test/capture/terrain_scene.gd.uid b/test/capture/terrain_scene.gd.uid new file mode 100644 index 0000000..0ebce01 --- /dev/null +++ b/test/capture/terrain_scene.gd.uid @@ -0,0 +1 @@ +uid://bcc26uufsyxi8 diff --git a/test/client/test_terrain.gd b/test/client/test_terrain.gd new file mode 100644 index 0000000..5ebdd60 --- /dev/null +++ b/test/client/test_terrain.gd @@ -0,0 +1,132 @@ +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 diff --git a/test/client/test_terrain.gd.uid b/test/client/test_terrain.gd.uid new file mode 100644 index 0000000..eefc5ef --- /dev/null +++ b/test/client/test_terrain.gd.uid @@ -0,0 +1 @@ +uid://boq3wln8pjs5j diff --git a/test/sim/test_island_movement.gd b/test/sim/test_island_movement.gd new file mode 100644 index 0000000..013d3e4 --- /dev/null +++ b/test/sim/test_island_movement.gd @@ -0,0 +1,60 @@ +extends TestCase + +## Character movement on generated islands, in the headless simulation with no renderer: +## the server's collision is SimGround's heightfield, never a render mesh. + +const TICKS: int = 900 + + +func test_players_never_sink_into_generated_terrain() -> void: + for seed_value: int in [11, 12]: + var sim: Simulation = Simulation.new(seed_value) + var random: RandomNumberGenerator = RandomNumberGenerator.new() + random.seed = seed_value + var ids: Array[int] = [] + for _index: int in 12: + ids.append(sim.add_player()) + var grounded: int = 0 + var samples: int = 0 + for _tick: int in TICKS: + for id: int in ids: + var move: Vector2 = Vector2(random.randf_range(-1.0, 1.0), random.randf_range(-1.0, 1.0)) + var buttons: int = PlayerCommand.BUTTON_SPRINT if random.randf() < 0.5 else 0 + if random.randf() < 0.004: + buttons |= PlayerCommand.BUTTON_JUMP + sim.submit_command(id, PlayerCommand.from_input(sim.tick, move, random.randf() * TAU, 0.0, buttons)) + sim.step() + for id: int in ids: + var player: SimEntity = sim.entities.find(id) + var floor_height: float = sim.ground.terrain_height(player.position.x, player.position.z) + assert_true(player.position.y >= floor_height - 0.01, + "seed %d player %d sank to %.2f below ground at %s" % [seed_value, id, floor_height - player.position.y, player.position]) + assert_false(is_nan(player.position.length()), "position became NaN") + samples += 1 + if player.on_ground: + grounded += 1 + assert_true(grounded > samples * 0.7, "seed %d: players grounded only %d of %d ticks" % [seed_value, grounded, samples]) + + +func test_walking_up_to_a_summit_and_back_down() -> void: + # Head straight for the tallest summit from the plateau below it, then walk away. + var sim: Simulation = Simulation.new(21) + var id: int = sim.add_player() + var player: SimEntity = sim.entities.find(id) + var summit: Vector3 = sim.island.summits[0] + var start: Vector2 = Vector2(summit.x, summit.z) + Vector2(150.0, 0.0) + player.position = Vector3(start.x, sim.ground.terrain_height(start.x, start.y), start.y) + var lowest_start: float = player.position.y + var highest: float = player.position.y + for _tick: int in 60 * Tuning.TICK_RATE_HZ: + var towards: Vector2 = Vector2(summit.x - player.position.x, summit.z - player.position.z) + if towards.length() < 3.0: + break + var yaw: float = atan2(towards.x, towards.y) + sim.submit_command(id, PlayerCommand.from_input(sim.tick, Vector2(0.0, 1.0), yaw, 0.0, PlayerCommand.BUTTON_SPRINT)) + sim.step() + highest = maxf(highest, player.position.y) + assert_true(highest > lowest_start + 15.0, + "climbed only from %.1f to %.1f m towards a %.1f m summit" % [lowest_start, highest, summit.y]) + assert_true(highest <= sim.island.max_height() + 0.01, "rose above the highest ground without jumping") + assert_eq(player.health, Tuning.PLAYER_MAX_HEALTH, "walking the hills must not hurt") diff --git a/test/sim/test_island_movement.gd.uid b/test/sim/test_island_movement.gd.uid new file mode 100644 index 0000000..137d25c --- /dev/null +++ b/test/sim/test_island_movement.gd.uid @@ -0,0 +1 @@ +uid://bcjg7fnxpwnju diff --git a/tools/crack_check.gd b/tools/crack_check.gd new file mode 100644 index 0000000..60b91a4 --- /dev/null +++ b/tools/crack_check.gd @@ -0,0 +1,52 @@ +## Counts crack pixels in a terrain_cracks capture. terrain_scene.gd draws the sky as a +## flat magenta that appears nowhere in the terrain. Magenta connected to the top of the +## frame is open sky above the world's edge; any other magenta is sky seen through a gap +## in the terrain. Prints the counts and exits 1 if there are any cracks. +## +## tools/godot.sh --script res://tools/crack_check.gd -- --image=/abs/path/cracks.png +extends SceneTree + + +func _init() -> void: + var path: String = "" + for arg: String in OS.get_cmdline_user_args(): + if arg.begins_with("--image="): + path = arg.trim_prefix("--image=") + var image: Image = Image.load_from_file(path) + if image == null or image.is_empty(): + printerr("crack_check: can't read '%s'" % path) + quit(2) + return + var width: int = image.get_width() + var height: int = image.get_height() + var magenta: PackedByteArray = PackedByteArray() + magenta.resize(width * height) + var total: int = 0 + for y: int in height: + for x: int in width: + var pixel: Color = image.get_pixel(x, y) + if pixel.r > 0.8 and pixel.b > 0.8 and pixel.g < 0.25: + magenta[y * width + x] = 1 + total += 1 + # Flood the open sky from the top row; what's left is seen through cracks. + var queue: PackedInt32Array = PackedInt32Array() + for x: int in width: + if magenta[x] == 1: + magenta[x] = 2 + queue.append(x) + var head: int = 0 + while head < queue.size(): + var at: int = queue[head] + head += 1 + var x: int = at % width + var y: int = at / width + for next: Vector2i in [Vector2i(x + 1, y), Vector2i(x - 1, y), Vector2i(x, y + 1), Vector2i(x, y - 1)]: + if next.x < 0 or next.y < 0 or next.x >= width or next.y >= height: + continue + var index: int = next.y * width + next.x + if magenta[index] == 1: + magenta[index] = 2 + queue.append(index) + var cracks: int = total - queue.size() + print("crack_check: %d crack pixels (%d magenta, %d of it open sky)" % [cracks, total, queue.size()]) + quit(1 if cracks > 0 else 0) diff --git a/tools/crack_check.gd.uid b/tools/crack_check.gd.uid new file mode 100644 index 0000000..9187aea --- /dev/null +++ b/tools/crack_check.gd.uid @@ -0,0 +1 @@ +uid://dg44m8rk0l17g diff --git a/tools/terrain_capture_check.sh b/tools/terrain_capture_check.sh new file mode 100755 index 0000000..b545e77 --- /dev/null +++ b/tools/terrain_capture_check.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +# Proves terrain chunks meet without cracks across detail levels. Renders the +# terrain_cracks scenario, where a magenta sky shows through any gap, and requires zero +# crack pixels. It first renders terrain_cracks_control, the same view with skirts turned +# off, and requires cracks there, so a passing result means the check can see them. +# Needs Docker, like tools/capture.sh. +set -uo pipefail +cd "$(dirname "${BASH_SOURCE[0]}")/.." +mkdir -p captures +status=0 + +tools/capture.sh terrain_cracks_control captures/terrain_cracks_control.png --frames=10 >/dev/null || exit 1 +if tools/godot.sh --script res://tools/crack_check.gd -- --image="$PWD/captures/terrain_cracks_control.png" | grep crack_check; then + echo "terrain-capture FAIL: the control without skirts showed no cracks, so the check proves nothing" + status=1 +fi +tools/capture.sh terrain_cracks captures/terrain_cracks.png --frames=10 >/dev/null || exit 1 +if ! tools/godot.sh --script res://tools/crack_check.gd -- --image="$PWD/captures/terrain_cracks.png" | grep crack_check; then + echo "terrain-capture FAIL: cracks between terrain chunks" + status=1 +fi +[[ $status -eq 0 ]] && echo "terrain-capture: ok (control cracks, real terrain has none)" +exit $status