Files
tidewall/src/client/terrain/terrain_chunk_builder.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

179 lines
7.0 KiB
GDScript

## 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()