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>
This commit is contained in:
2026-11-10 14:28:30 -05:00
co-authored by Claude Opus 5.5
parent c70d0c1c4f
commit 8b74485168
22 changed files with 840 additions and 1 deletions
+1
View File
@@ -25,6 +25,7 @@ continuity.
| `tools/godot.sh ...` | Runs the pinned engine. Headless by default. | | `tools/godot.sh ...` | Runs the pinned engine. Headless by default. |
| `tools/capture.sh <scene-or-scenario> <out.png>` | 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/capture.sh <scene-or-scenario> <out.png>` | 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. | | `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`. | | `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 Run one group of tests with `tools/run_tests.sh --root=res://test/sim` or
+5 -1
View File
@@ -1,7 +1,7 @@
# Tidewall build entry points. Everything runs headless with the repo-local engine. # Tidewall build entry points. Everything runs headless with the repo-local engine.
GODOT := tools/godot.sh 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. ## Everything that must pass before a push.
check: verify-engine binaries parse test test-selfcheck smoke 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. ## Renders the capture test scenes in the offscreen container. Needs Docker.
capture-test: import capture-test: import
@tools/capture_selfcheck.sh @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
+15
View File
@@ -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/audio/` | Sound playback, music | `src/sim/` (read only) |
| `src/app/` | Startup and mode selection | Everything | | `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 ## Performance budgets
| Budget | Target | | Budget | Target |
|---|---| |---|---|
| Server tick | Under **12 ms** with 24 players | | Server tick | Under **12 ms** with 24 players |
| Client | **60 fps** on a GTX 1060-class GPU at medium settings | | 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. Software rendering in CI can't verify the client budget. It needs a real GPU playtest.
+81
View File
@@ -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;
}
+1
View File
@@ -0,0 +1 @@
uid://c7ee5h5pe6qjq
+178
View File
@@ -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()
@@ -0,0 +1 @@
uid://ccwnw5e74lpwj
+176
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
uid://dl7o5bhcs733r
+6
View File
@@ -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")
+11
View File
@@ -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
+12
View File
@@ -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
+10
View File
@@ -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
+71
View File
@@ -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()
+1
View File
@@ -0,0 +1 @@
uid://bcc26uufsyxi8
+132
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
uid://boq3wln8pjs5j
+60
View File
@@ -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")
+1
View File
@@ -0,0 +1 @@
uid://bcjg7fnxpwnju
+52
View File
@@ -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)
+1
View File
@@ -0,0 +1 @@
uid://dg44m8rk0l17g
+23
View File
@@ -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