W2: Procedural island generator

Island.generate(seed) builds a 513 x 513 heightfield (2 m spacing, the whole
1,024 m world) from the match seed's "worldgen" stream: a warped coastline,
a coastal shelf and interior dome, two to four summits joined by ridges,
rolling and rocky detail, and flattened marsh in wet lowland. Land is scaled
so the tallest summit lands between ISLAND_PEAK_MIN and ISLAND_PEAK_MAX,
under the last tide. Each sample gets an elevation band (sea, beach, marsh,
forest, highland, summit) for terrain materials.

- Simulation generates the island unless a test supplies its own ground,
  and spawns players on dry land until the drop arrives.
- The headless server logs world_hash in its start line.
- Island.heightmap_hash() is SHA-256 over millimetre heights and bands.
- tools/island_map.gd draws a top-down map with tide contours.
- New island constants in tuning.gd; GDD gains an island section.

Tests: a 100-seed sweep checks generation time (slowest 617 ms against
5 s), land area, at least two distinct high points, walkable land, bands,
and that no more than 3% of dry land is cut off at sea levels 0 and 8 m
(worst seen 0.87%). A separate server process given only the seed must
log the same heightmap hash.

Closes #9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 14:15:59 -05:00
co-authored by Claude Opus 5.5
parent f1ce780474
commit c70d0c1c4f
15 changed files with 658 additions and 5 deletions
+250
View File
@@ -0,0 +1,250 @@
## The procedural island. One seed gives one island, on the server and on every client,
## so terrain is never sent over the network: both ends call `Island.generate(seed)`.
##
## The island is built in layers, each a pure function of the seed:
## 1. a warped coastline around the world centre, falling to the sea floor outside it;
## 2. a raised interior plateau that keeps land joined through the early tide;
## 3. two to four summits, joined by ridges, which become the last dry ground;
## 4. rolling detail, rocky highland detail, and flattened marsh in wet lowland.
## Then the land is scaled so the tallest summit lands in the tuned peak range.
##
## All randomness comes from the match seed's "worldgen" stream. FastNoiseLite is a
## seeded, pure function in the engine core with no rendering dependency.
class_name Island
extends RefCounted
enum Band { SEA, BEACH, MARSH, FOREST, HIGHLAND, SUMMIT }
## Height of the coastal shelf the land rises to, before detail and summits, in metres.
const PLATEAU_HEIGHT: float = 11.0
## Extra height of a broad dome over the interior, so each tide phase takes a ring of
## land rather than the whole plateau at once.
const DOME_HEIGHT: float = 16.0
## Fraction of the radius, measured inward from the coast, over which land rises to the plateau.
const COAST_RISE: float = 0.32
## How far the coastline is pushed in or out, as a fraction of the radius.
const COAST_WARP: float = 0.22
const DETAIL_METRES: float = 6.5
const ROCK_METRES: float = 7.0
const RIDGE_FRACTION: float = 0.55
const MARSH_LEVEL: float = 3.6
## Moisture above this turns wet lowland into marsh.
const MARSH_MOISTURE: float = 0.05
var match_seed: int = 0
var ground: SimGround
## Elevation band per heightfield sample, same layout as `ground.heights`.
var bands: PackedByteArray = PackedByteArray()
## The summit centres the generator placed, as (x, height, z), tallest first.
var summits: Array[Vector3] = []
## Wall-clock generation time is measured by callers; the island never reads a clock.
## Builds the island for `seed_value`.
static func generate(seed_value: int) -> Island:
var island: Island = Island.new()
island.match_seed = seed_value
island._build()
return island
## SHA-256 hex digest of the heightfield, heights rounded to millimetres. Two machines
## that agree on this agree on every walkable surface.
func heightmap_hash() -> String:
var buffer: StreamPeerBuffer = StreamPeerBuffer.new()
buffer.big_endian = false
buffer.put_32(ground.samples)
buffer.put_32(roundi(ground.cell * 1000.0))
for value: float in ground.heights:
buffer.put_32(roundi(value * 1000.0))
buffer.put_data(bands)
var hasher: HashingContext = HashingContext.new()
hasher.start(HashingContext.HASH_SHA256)
hasher.update(buffer.data_array)
return hasher.finish().hex_encode()
## The elevation band at world position (x, z), from the nearest sample.
func band_at(x: float, z: float) -> Band:
var limit: int = ground.samples - 1
var gx: int = clampi(roundi(x / ground.cell), 0, limit)
var gz: int = clampi(roundi(z / ground.cell), 0, limit)
return bands[gz * ground.samples + gx] as Band
## The highest terrain sample, in metres.
func max_height() -> float:
var best: float = -INF
for value: float in ground.heights:
best = maxf(best, value)
return best
func _build() -> void:
var rng: RandomNumberGenerator = SimRng.new(match_seed).stream("worldgen")
var size: float = Tuning.WORLD_SIZE_METRES
var cell: float = Tuning.ISLAND_GRID_METRES
var side: int = roundi(size / cell) + 1
var centre: Vector2 = Vector2(size, size) * 0.5
var radius: float = Tuning.ISLAND_RADIUS_METRES
var coast: FastNoiseLite = _noise(rng.randi(), 1.0 / 260.0, 3)
var detail: FastNoiseLite = _noise(rng.randi(), 1.0 / 170.0, 4)
var rock: FastNoiseLite = _noise(rng.randi(), 1.0 / 60.0, 3)
rock.fractal_type = FastNoiseLite.FRACTAL_RIDGED
var moisture: FastNoiseLite = _noise(rng.randi(), 1.0 / 200.0, 2)
var peaks: Array[Dictionary] = _place_summits(rng, centre, radius)
var ridges: Array[Dictionary] = _link_summits(peaks)
var heights: PackedFloat32Array = PackedFloat32Array()
heights.resize(side * side)
var wet: PackedFloat32Array = PackedFloat32Array()
wet.resize(side * side)
for gz: int in side:
var z: float = gz * cell
for gx: int in side:
var x: float = gx * cell
var index: int = gz * side + gx
var offset: Vector2 = Vector2(x, z) - centre
# Inland is 0 at the coast, 1 at the centre, negative out to sea.
var inland: float = 1.0 - offset.length() / radius + COAST_WARP * coast.get_noise_2d(x, z)
if inland <= 0.0:
heights[index] = -Tuning.ISLAND_SEA_DEPTH * clampf(-inland / 0.12, 0.0, 1.0) - 0.4
continue
var rise: float = _smooth(0.0, COAST_RISE, inland)
var height: float = PLATEAU_HEIGHT * rise + DOME_HEIGHT * _smooth(0.15, 1.1, inland) + 0.6
var raise: float = 0.0
for peak: Dictionary in peaks:
var reach: float = Vector2(x, z).distance_squared_to(peak["at"]) / pow(peak["radius"], 2.0)
raise = maxf(raise, peak["height"] * exp(-1.6 * reach))
for ridge: Dictionary in ridges:
var gap: float = _distance_to_segment(Vector2(x, z), ridge["from"], ridge["to"])
raise = maxf(raise, ridge["height"] * exp(-pow(gap / ridge["width"], 2.0)))
var inner: float = _smooth(0.08, 0.45, inland)
height += raise * inner
height += DETAIL_METRES * detail.get_noise_2d(x, z) * rise
# Rock grows with altitude, so highlands are craggy and lowlands rolling.
var altitude: float = clampf((height - PLATEAU_HEIGHT - DOME_HEIGHT) / 28.0, 0.0, 1.0)
height += ROCK_METRES * (rock.get_noise_2d(x, z) + 0.3) * altitude
heights[index] = height
wet[index] = moisture.get_noise_2d(x, z)
_scale_to_peak(heights, rng)
var band_data: PackedByteArray = PackedByteArray()
band_data.resize(side * side)
for index: int in heights.size():
var height: float = heights[index]
if height > 0.0 and height < Tuning.ISLAND_MARSH_TOP + 1.5 and wet[index] > MARSH_MOISTURE:
# Flatten wet lowland towards a marsh level just above the beach.
var weight: float = _smooth(MARSH_MOISTURE, MARSH_MOISTURE + 0.25, wet[index])
weight *= 1.0 - _smooth(Tuning.ISLAND_MARSH_TOP - 1.0, Tuning.ISLAND_MARSH_TOP + 1.5, height)
height = lerpf(height, maxf(MARSH_LEVEL, Tuning.ISLAND_BEACH_TOP + 0.3), weight)
heights[index] = height
band_data[index] = _classify(height, wet[index])
ground = SimGround.from_heights(heights, side, cell)
bands = band_data
for peak: Dictionary in peaks:
var at: Vector2 = peak["at"]
summits.append(Vector3(at.x, ground.terrain_height(at.x, at.y), at.y))
summits.sort_custom(func(a: Vector3, b: Vector3) -> bool: return a.y > b.y)
func _noise(noise_seed: int, frequency: float, octaves: int) -> FastNoiseLite:
var noise: FastNoiseLite = FastNoiseLite.new()
noise.noise_type = FastNoiseLite.TYPE_SIMPLEX_SMOOTH
noise.seed = noise_seed & 0x7FFFFFFF
noise.frequency = frequency
noise.fractal_type = FastNoiseLite.FRACTAL_FBM
noise.fractal_octaves = octaves
return noise
## Picks summit centres well inside the coast and far enough apart. The first is the
## tallest. Heights here are before scaling to the peak range.
func _place_summits(rng: RandomNumberGenerator, centre: Vector2, radius: float) -> Array[Dictionary]:
var count: int = rng.randi_range(Tuning.ISLAND_MIN_SUMMITS, Tuning.ISLAND_MAX_SUMMITS)
var peaks: Array[Dictionary] = []
var spacing: float = Tuning.ISLAND_SUMMIT_SPACING_METRES
var attempts: int = 0
while peaks.size() < count and attempts < 400:
attempts += 1
# Relax the spacing slowly if the island can't fit them all.
var needed: float = spacing * (1.0 - 0.3 * attempts / 400.0)
var angle: float = rng.randf() * TAU
var distance: float = radius * rng.randf_range(0.12, 0.55)
var at: Vector2 = centre + Vector2(cos(angle), sin(angle)) * distance
var clear: bool = true
for peak: Dictionary in peaks:
if at.distance_to(peak["at"]) < needed:
clear = false
break
if not clear:
continue
var height: float = 46.0 if peaks.is_empty() else rng.randf_range(30.0, 42.0)
peaks.append({"at": at, "height": height, "radius": rng.randf_range(95.0, 145.0)})
return peaks
## Joins each summit to its nearest neighbour with a lower ridge, giving highland spines.
func _link_summits(peaks: Array[Dictionary]) -> Array[Dictionary]:
var ridges: Array[Dictionary] = []
var linked: Dictionary = {}
for index: int in peaks.size():
var nearest: int = -1
var best: float = INF
for other: int in peaks.size():
var gap: float = (peaks[index]["at"] as Vector2).distance_to(peaks[other]["at"])
if other != index and gap < best:
best = gap
nearest = other
if nearest < 0:
continue
var key: Vector2i = Vector2i(mini(index, nearest), maxi(index, nearest))
if linked.has(key):
continue
linked[key] = true
var low: float = minf(peaks[index]["height"], peaks[nearest]["height"])
ridges.append({
"from": peaks[index]["at"], "to": peaks[nearest]["at"],
"height": low * RIDGE_FRACTION, "width": 50.0,
})
return ridges
## Scales land heights so the tallest point lands in the tuned peak range. The sea
## floor is left alone, so the coastline doesn't move.
func _scale_to_peak(heights: PackedFloat32Array, rng: RandomNumberGenerator) -> void:
var highest: float = 0.0
for value: float in heights:
highest = maxf(highest, value)
var target: float = rng.randf_range(Tuning.ISLAND_PEAK_MIN, Tuning.ISLAND_PEAK_MAX)
var factor: float = target / highest
for index: int in heights.size():
if heights[index] > 0.0:
heights[index] *= factor
func _classify(height: float, wetness: float) -> int:
if height <= 0.0:
return Band.SEA
if height < Tuning.ISLAND_BEACH_TOP:
return Band.BEACH
if height < Tuning.ISLAND_MARSH_TOP and wetness > MARSH_MOISTURE:
return Band.MARSH
if height < Tuning.ISLAND_FOREST_TOP:
return Band.FOREST
if height < Tuning.ISLAND_SUMMIT_BAND:
return Band.HIGHLAND
return Band.SUMMIT
static func _smooth(from: float, to: float, value: float) -> float:
return smoothstep(from, to, value)
static func _distance_to_segment(point: Vector2, from: Vector2, to: Vector2) -> float:
var span: Vector2 = to - from
var t: float = clampf((point - from).dot(span) / maxf(span.length_squared(), 0.0001), 0.0, 1.0)
return point.distance_to(from + span * t)