W4: Points of interest

PoiSet.generate(island) places 10 to 16 points of interest per island from
the seed's "poi" stream: hilltop shrines, lighthouses, docks, salt works,
quarries and fishing hamlets, at least 85 m apart. Each kind has a siting
rule (height band, flatness, coast or summit) that loosens step by step
until its minimum is placed. Piers are sited so their deck clears the
ground all the way out to water 1.5 m deep.

Poi assembles each from modular parts in a local frame turned in quarter
turns, so every solid stays an axis-aligned box: walls with a door and
lintel, plinths, steps down to the ground, roofs, a stair to a loft. Each
POI carries loot spawn markers, exposed through PoiSet.loot_markers(),
and walking routes from open ground into its interiors.

- Simulation adds every POI solid to its ground and never spawns players
  inside one.
- SimGround indexes solids in 8 m cells, so collision queries only test
  nearby boxes. Smoke p95 tick is 0.47 ms with about 300 solids.
- Movement tests the body where it will stand after stepping up, so
  stairs with treads narrower than the body can be climbed. The
  traversal test found the lighthouse stair impassable without it.
- PoiView draws parts as one MultiMesh per look, in the seafaring
  palette. Capture scenarios poi_<kind> frame each kind.
- Summit stone is darker so it no longer reads as snow.

Tests: 30 seeds get every kind within its limits, 10 to 16 in total,
spaced and sited; placement is deterministic; loot markers stand on
floors and are not inside solids; a player walks every route of every
POI on 4 seeds through doors, up steps and the lighthouse stair; stairs
with 0.45 m treads are climbed and a step doesn't carry the body into a
wall; the solid index matches a full scan on 500 queries.

Closes #11

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 14:47:10 -05:00
co-authored by Claude Opus 5.5
parent 8b74485168
commit 5021d13686
23 changed files with 949 additions and 13 deletions
+378
View File
@@ -0,0 +1,378 @@
## Places an island's points of interest from the match seed. Like the island itself,
## both ends build the same set from the seed alone.
##
## Kinds, all original to Tidewall: fishing hamlets, docks, lighthouses, a quarry, salt
## works and hilltop shrines. Each kind has a siting rule (a band of height, how flat,
## near the coast or a summit) and is assembled from Poi's modular parts.
class_name PoiSet
extends RefCounted
## Kinds in placing order: the most particular sites are claimed first.
const ORDER: Array[String] = ["shrine", "lighthouse", "dock", "salt_works", "quarry", "hamlet"]
const CANDIDATES: int = 260
const RELAX_STEPS: Array[float] = [1.0, 1.5, 2.2, 3.2]
const STRICT_ONLY: Array[float] = [1.0]
const PIER_DECK_MIN: float = 1.4
const PIER_WATER_DEPTH: float = 1.5
const PIER_PAST_WATER: float = 6.0
const PIER_MAX_METRES: float = 36.0
## Radius around a site whose terrain must lie within a kind's flatness, in metres.
const SITE_RADIUS: Dictionary = {
"shrine": 6.0, "lighthouse": 6.0, "dock": 5.0, "salt_works": 12.0, "quarry": 10.0, "hamlet": 14.0,
}
var pois: Array[Poi] = []
var _island: Island
var _ground: SimGround
static func generate(island: Island) -> PoiSet:
var placed: PoiSet = PoiSet.new()
placed._island = island
placed._ground = island.ground
placed._place_all(SimRng.new(island.match_seed).stream("poi"))
return placed
## Every loot spawn marker, for the loot system: {"position": Vector3, "poi": index,
## "kind": String}, in placing order.
func loot_markers() -> Array[Dictionary]:
var markers: Array[Dictionary] = []
for index: int in pois.size():
for at: Vector3 in pois[index].loot:
markers.append({"position": at, "poi": index, "kind": pois[index].kind})
return markers
## Adds every POI's solids to `ground`.
func add_solids_to(ground: SimGround) -> void:
for poi: Poi in pois:
for solid: AABB in poi.solids:
ground.add_solid(solid)
func count_of(kind: String) -> int:
var count: int = 0
for poi: Poi in pois:
if poi.kind == kind:
count += 1
return count
func _place_all(rng: RandomNumberGenerator) -> void:
var wanted: Dictionary = {}
var total: int = 0
for kind: String in ORDER:
var limits: Dictionary = Tuning.POI_KINDS[kind]
wanted[kind] = rng.randi_range(limits["min"], limits["max"])
total += wanted[kind]
while total > Tuning.POI_MAX_TOTAL:
for kind: String in ORDER:
if total > Tuning.POI_MAX_TOTAL and wanted[kind] > Tuning.POI_KINDS[kind]["min"]:
wanted[kind] -= 1
total -= 1
for kind: String in ORDER:
for index: int in wanted[kind]:
# Every kind's minimum must be placed, so loosen its siting rules step by step
# when the island is awkward. Extras only go on good sites.
var steps: Array[float] = RELAX_STEPS if index < Tuning.POI_KINDS[kind]["min"] else STRICT_ONLY
for relax: float in steps:
if _place_one(kind, rng, relax):
break
# If a strict siting rule left the island short, relax and top up with hamlets.
var relax: float = 1.5
while pois.size() < Tuning.POI_MIN_TOTAL and relax < 4.0:
_place_one("hamlet", rng, relax)
relax += 0.25
## Tries candidate sites for `kind` and builds the best. `relax` widens the siting rules.
func _place_one(kind: String, rng: RandomNumberGenerator, relax: float) -> bool:
var best: Vector2 = Vector2.ZERO
var best_score: float = INF
var size: float = Tuning.WORLD_SIZE_METRES
for _attempt: int in CANDIDATES:
var site: Vector2
if kind == "shrine" and count_of("shrine") < _island.summits.size():
var summit: Vector3 = _island.summits[count_of("shrine")]
site = Vector2(summit.x, summit.z) + Vector2(rng.randf_range(-25.0, 25.0), rng.randf_range(-25.0, 25.0))
else:
site = Vector2(rng.randf_range(0.08, 0.92) * size, rng.randf_range(0.08, 0.92) * size)
var score: float = _site_score(kind, site, relax)
if score < best_score:
best_score = score
best = site
if best_score == INF:
return false
var height: float = _ground.terrain_height(best.x, best.y)
var poi: Poi = Poi.new(kind, Vector3(best.x, height, best.y), _facing_for(kind, best, rng), _ground)
call("_build_" + kind, poi, rng)
pois.append(poi)
return true
## Lower is better; INF means unsuitable.
func _site_score(kind: String, site: Vector2, relax: float) -> float:
for poi: Poi in pois:
if Vector2(poi.origin.x, poi.origin.z).distance_to(site) < Tuning.POI_SPACING_METRES:
return INF
var height: float = _ground.terrain_height(site.x, site.y)
var spread: float = _spread(site, SITE_RADIUS[kind])
match kind:
"shrine":
if height < Tuning.ISLAND_FOREST_TOP or spread > 4.0 * relax:
return INF
return spread - height * 0.2
"lighthouse":
var sea: float = _distance_to_sea(site, 80.0)
if height < 6.0 or height > 30.0 * relax or sea > 60.0 * relax or spread > 3.0 * relax:
return INF
return spread + sea * 0.05 - height * 0.05
"dock":
if height < 0.4 or height > 2.4 * relax or spread > 2.5 * relax:
return INF
var turn: int = _seaward(site)
if turn < 0 or _pier_length(site, turn) == 0.0:
return INF
return spread + _pier_length(site, turn) * 0.05
"salt_works":
if height < Tuning.ISLAND_BEACH_TOP * 0.5 or height > Tuning.ISLAND_MARSH_TOP * relax or spread > 2.0 * relax:
return INF
return spread
"quarry":
if height < Tuning.ISLAND_FOREST_TOP - 6.0 or height > Tuning.ISLAND_SUMMIT_BAND * relax or spread > 4.0 * relax:
return INF
return spread
_:
if height < Tuning.ISLAND_MARSH_TOP or height > Tuning.ISLAND_FOREST_TOP * relax or spread > 2.5 * relax:
return INF
return spread
return INF
## Highest minus lowest terrain within `radius` of `site`.
func _spread(site: Vector2, radius: float) -> float:
var low: float = INF
var high: float = -INF
for ring: float in [0.0, radius * 0.5, radius]:
for index: int in 8:
var angle: float = TAU * index / 8.0
var at: Vector2 = site + Vector2(cos(angle), sin(angle)) * ring
var height: float = _ground.terrain_height(at.x, at.y)
low = minf(low, height)
high = maxf(high, height)
return high - low
func _distance_to_sea(site: Vector2, limit: float) -> float:
for distance: float in range(0, int(limit) + 1, 5):
for index: int in 8:
var angle: float = TAU * index / 8.0
var at: Vector2 = site + Vector2(cos(angle), sin(angle)) * distance
if _ground.terrain_height(at.x, at.y) <= 0.0:
return distance
return INF
## The quarter turn whose front faces open sea within 30 m, or -1.
func _seaward(site: Vector2) -> int:
var directions: Array[Vector2] = [Vector2(0.0, 1.0), Vector2(1.0, 0.0), Vector2(0.0, -1.0), Vector2(-1.0, 0.0)]
var best: int = -1
var deepest: float = -0.5
for turn: int in 4:
var far: Vector2 = site + directions[turn] * 30.0
var depth: float = _ground.terrain_height(far.x, far.y)
if depth < deepest:
deepest = depth
best = turn
return best
## Deck height for a pier at `site`, in world metres: a little above the shore, and
## always clear of the starting sea.
func _deck_top(site: Vector2) -> float:
return maxf(_ground.terrain_height(site.x, site.y) + 0.3, PIER_DECK_MIN)
## How long a pier from `site` facing quarter turn `turn` must be to reach water at
## least PIER_WATER_DEPTH deep, plus PIER_PAST_WATER. 0 if it can't: the sea is too far
## away, or the ground rises under the deck on the way.
func _pier_length(site: Vector2, turn: int) -> float:
var directions: Array[Vector2] = [Vector2(0.0, 1.0), Vector2(1.0, 0.0), Vector2(0.0, -1.0), Vector2(-1.0, 0.0)]
var deck: float = _deck_top(site)
for distance: float in range(4, int(PIER_MAX_METRES) + 1, 2):
var at: Vector2 = site + directions[turn] * distance
var height: float = _ground.terrain_height(at.x, at.y)
if height > deck - 0.4:
return 0.0
if height < -PIER_WATER_DEPTH:
return minf(distance + PIER_PAST_WATER, PIER_MAX_METRES)
return 0.0
func _facing_for(kind: String, site: Vector2, rng: RandomNumberGenerator) -> int:
if kind == "dock":
return _seaward(site)
return rng.randi_range(0, 3)
func _build_hamlet(poi: Poi, rng: RandomNumberGenerator) -> void:
# Huts around a yard, doors facing in, and a net-drying rack in the middle.
var huts: int = rng.randi_range(3, 4)
var spots: Array[Vector3] = [Vector3(0.0, 0.0, -9.0), Vector3(-9.0, 0.0, 0.0), Vector3(9.0, 0.0, 0.0), Vector3(0.0, 0.0, 9.0)]
for index: int in huts:
var hut: Poi = _child(poi, spots[index], index)
hut.hut(Vector3.ZERO, rng.randf_range(5.0, 6.5), rng.randf_range(4.5, 5.5), 2.8, Poi.LOOK_TARRED_WOOD, Poi.LOOK_ROOF)
_adopt(poi, hut)
for x: float in [-2.0, 2.0]:
poi.box(Vector3(x - 0.1, -0.5, -0.1), Vector3(0.2, 2.6, 0.2), Poi.LOOK_PLANK)
poi.box(Vector3(-2.2, 2.0, -0.08), Vector3(4.4, 0.12, 0.16), Poi.LOOK_PLANK)
poi.add_loot(Vector3(0.0, poi.ground_at(Vector3(0.0, 0.0, 1.5)) - poi.origin.y, 1.5))
func _build_dock(poi: Poi, _rng: RandomNumberGenerator) -> void:
# A plank pier running out to sea on posts, with a net shed on the shore behind it.
var site: Vector2 = Vector2(poi.origin.x, poi.origin.z)
var deck_top: float = _deck_top(site) - poi.origin.y
var length: float = _pier_length(site, poi.facing)
poi.box(Vector3(-1.5, deck_top - 0.25, 0.0), Vector3(3.0, 0.25, length), Poi.LOOK_PLANK)
for z: float in range(2, int(length), 4):
for x: float in [-1.4, 1.2]:
poi.box(Vector3(x, -Tuning.ISLAND_SEA_DEPTH - poi.origin.y, z), Vector3(0.2, deck_top + Tuning.ISLAND_SEA_DEPTH + poi.origin.y + 0.9, 0.2), Poi.LOOK_TARRED_WOOD, false)
poi.box(Vector3(-1.6, deck_top, length - 0.2), Vector3(3.2, 0.9, 0.2), Poi.LOOK_PAINT)
var shed: Poi = _child(poi, Vector3(0.0, 0.0, -8.0), 0)
shed.hut(Vector3.ZERO, 5.0, 4.5, 2.6, Poi.LOOK_TARRED_WOOD, Poi.LOOK_ROOF)
_adopt(poi, shed)
# Steps down from the landward end of the deck to the shore.
var landing: Vector3 = poi.steps_down(Vector3(0.0, deck_top, 0.0), Vector3(0.0, 0.0, -1.0), 2.4, Poi.LOOK_PLANK)
var on_deck: Vector3 = Vector3(0.0, deck_top, 1.0)
var end: Vector3 = Vector3(0.0, deck_top, length - 1.5)
poi.add_loot(end)
poi.add_route([landing, on_deck, end])
func _build_lighthouse(poi: Poi, _rng: RandomNumberGenerator) -> void:
# A square stone tower: a keeper's room, a stair along the back wall up to a loft,
# and the light chamber above. The loot is in the loft.
var side: float = 7.0
var half: float = side * 0.5
var under: Vector2 = poi.terrain_range(Vector2(-half, -half), Vector2(side, side))
var floor_y: float = under.y - poi.origin.y + 0.15
poi.plinth(Vector2(-half, -half), Vector2(side, side), floor_y, Poi.LOOK_STONE)
var loft: float = floor_y + 3.5
var top: float = floor_y + 13.0
var inner: float = side - 2.0 * Poi.WALL
var x0: float = -half
var z0: float = -half
poi.box(Vector3(x0, floor_y, z0), Vector3(side, top - floor_y, Poi.WALL), Poi.LOOK_STONE)
poi.box(Vector3(x0, floor_y, z0), Vector3(Poi.WALL, top - floor_y, side), Poi.LOOK_STONE)
poi.box(Vector3(half - Poi.WALL, floor_y, z0), Vector3(Poi.WALL, top - floor_y, side), Poi.LOOK_STONE)
var side_width: float = (side - Poi.DOOR_WIDTH) * 0.5
poi.box(Vector3(x0, floor_y, half - Poi.WALL), Vector3(side_width, top - floor_y, Poi.WALL), Poi.LOOK_STONE)
poi.box(Vector3(x0 + side_width + Poi.DOOR_WIDTH, floor_y, half - Poi.WALL), Vector3(side_width, top - floor_y, Poi.WALL), Poi.LOOK_STONE)
poi.box(Vector3(x0 + side_width, floor_y + Poi.DOOR_HEIGHT, half - Poi.WALL), Vector3(Poi.DOOR_WIDTH, top - floor_y - Poi.DOOR_HEIGHT, Poi.WALL), Poi.LOOK_STONE)
# Painted bands, the light chamber and its cap.
for band: float in [4.5, 8.5]:
poi.box(Vector3(x0 - 0.05, floor_y + band, z0 - 0.05), Vector3(side + 0.1, 1.2, side + 0.1), Poi.LOOK_PAINT, false)
poi.box(Vector3(-2.0, top, -2.0), Vector3(4.0, 2.4, 4.0), Poi.LOOK_LAMP)
poi.box(Vector3(-2.5, top + 2.4, -2.5), Vector3(5.0, 0.4, 5.0), Poi.LOOK_ROOF)
# Stair along the back wall, rising towards -x, ten steps up to the loft.
var stair_width: float = 1.1
var steps: int = ceili((loft - floor_y) / Poi.STEP_RISE)
var rise: float = (loft - floor_y) / steps
var tread: float = 0.5
var stair_z: float = z0 + Poi.WALL
var start_x: float = half - Poi.WALL - 1.0
for index: int in steps:
var step_top: float = floor_y + rise * (index + 1)
var x: float = start_x - tread * (index + 1)
poi.box(Vector3(x, floor_y, stair_z), Vector3(tread, step_top - floor_y, stair_width), Poi.LOOK_PLANK)
var stair_end_x: float = start_x - tread * steps
# The loft covers the room except the stair well above the flight.
var well_end: float = start_x + 0.2
poi.box(Vector3(x0 + Poi.WALL, loft - 0.3, stair_z + stair_width), Vector3(inner, 0.3, inner - stair_width), Poi.LOOK_PLANK)
poi.box(Vector3(x0 + Poi.WALL, loft - 0.3, stair_z), Vector3(stair_end_x - x0 - Poi.WALL, 0.3, stair_width), Poi.LOOK_PLANK)
poi.box(Vector3(well_end, loft - 0.3, stair_z), Vector3(half - Poi.WALL - well_end, 0.3, stair_width), Poi.LOOK_PLANK)
var door: Vector3 = Vector3(0.0, floor_y, half)
var foot: Vector3 = poi.steps_down(door, Vector3(0.0, 0.0, 1.0), Poi.DOOR_WIDTH + 0.4, Poi.LOOK_STONE)
var room: Vector3 = Vector3(0.0, floor_y, half - 1.5)
var stair_foot: Vector3 = Vector3(start_x + 0.4, floor_y, stair_z + stair_width * 0.5)
var stair_top: Vector3 = Vector3(stair_end_x + 0.25, loft, stair_z + stair_width * 0.5)
var loft_spot: Vector3 = Vector3(stair_end_x + 0.6, loft, z0 + Poi.WALL + stair_width + 1.6)
poi.add_loot(Vector3(1.5, floor_y, half - 2.0))
poi.add_loot(loft_spot)
poi.add_route([foot + Vector3(0.0, 0.0, 1.5), foot, door, room, stair_foot, stair_top, loft_spot])
func _build_quarry(poi: Poi, rng: RandomNumberGenerator) -> void:
# Cut stone blocks, a lifting frame and a tool shed.
var shed: Poi = _child(poi, Vector3(0.0, 0.0, -6.0), rng.randi_range(0, 3))
shed.hut(Vector3.ZERO, 5.0, 4.0, 2.6, Poi.LOOK_PLANK, Poi.LOOK_ROOF)
_adopt(poi, shed)
for index: int in rng.randi_range(5, 8):
var at: Vector3 = Vector3(rng.randf_range(-9.0, 9.0), 0.0, rng.randf_range(1.0, 10.0))
var size: Vector3 = Vector3(rng.randf_range(1.2, 2.4), rng.randf_range(0.8, 1.8), rng.randf_range(1.2, 2.4))
var base: float = poi.ground_at(at) - poi.origin.y - 0.3
poi.box(Vector3(at.x, base, at.z), size + Vector3(0.0, 0.3, 0.0), Poi.LOOK_STONE)
var frame_z: float = 5.0
for x: float in [-3.0, 3.0]:
var base: float = poi.ground_at(Vector3(x, 0.0, frame_z)) - poi.origin.y - 0.3
poi.box(Vector3(x - 0.15, base, frame_z - 0.15), Vector3(0.3, 5.3, 0.3), Poi.LOOK_TARRED_WOOD)
poi.box(Vector3(-3.3, poi.ground_at(Vector3(0.0, 0.0, frame_z)) - poi.origin.y + 4.8, frame_z - 0.2), Vector3(6.6, 0.4, 0.4), Poi.LOOK_TARRED_WOOD)
poi.add_loot(Vector3(0.0, poi.ground_at(Vector3(0.0, 0.0, 12.0)) - poi.origin.y, 12.0))
func _build_salt_works(poi: Poi, rng: RandomNumberGenerator) -> void:
# Shallow evaporation pans behind low walls you can step over, and a boiling house.
var house: Poi = _child(poi, Vector3(0.0, 0.0, -9.0), 0)
house.hut(Vector3.ZERO, 8.0, 6.0, 3.2, Poi.LOOK_TARRED_WOOD, Poi.LOOK_ROOF)
_adopt(poi, house)
poi.box(Vector3(2.4, house.origin.y - poi.origin.y - 0.5, -12.8), Vector3(0.8, 6.5, 0.8), Poi.LOOK_STONE)
for row: int in 2:
for column: int in 3:
var x0: float = -10.5 + column * 7.0
var z0: float = 1.0 + row * 6.0
var base: float = poi.ground_at(Vector3(x0 + 3.0, 0.0, z0 + 2.5)) - poi.origin.y
poi.box(Vector3(x0, base - 0.3, z0), Vector3(6.0, 0.35, 5.0), Poi.LOOK_SALT, false)
for wall: Array in [[Vector3(x0, 0, z0), Vector3(6.0, 0, 0.25)], [Vector3(x0, 0, z0 + 4.75), Vector3(6.0, 0, 0.25)],
[Vector3(x0, 0, z0), Vector3(0.25, 0, 5.0)], [Vector3(x0 + 5.75, 0, z0), Vector3(0.25, 0, 5.0)]]:
var at: Vector3 = wall[0]
var size: Vector3 = wall[1]
poi.box(Vector3(at.x, base - 0.3, at.z), Vector3(size.x, 0.6, size.z), Poi.LOOK_STONE)
poi.add_loot(Vector3(-7.5, poi.ground_at(Vector3(-7.5, 0.0, 3.5)) - poi.origin.y, 3.5))
if rng.randf() < 0.5:
poi.add_loot(Vector3(6.5, poi.ground_at(Vector3(6.5, 0.0, 9.5)) - poi.origin.y, 9.5))
func _build_shrine(poi: Poi, rng: RandomNumberGenerator) -> void:
# A small open-fronted stone shrine with a painted lintel, and cairns around it.
poi.hut(Vector3.ZERO, 4.0, 3.6, 2.6, Poi.LOOK_STONE, Poi.LOOK_PAINT)
for index: int in rng.randi_range(3, 5):
var angle: float = TAU * index / 5.0 + rng.randf() * 0.4
var at: Vector3 = Vector3(cos(angle), 0.0, sin(angle)) * rng.randf_range(6.0, 9.0)
if at.z > 2.0 and absf(at.x) < 2.5:
continue # Keep the approach to the door clear.
var base: float = poi.ground_at(at) - poi.origin.y - 0.2
for layer: int in 3:
var size: float = 1.2 - layer * 0.3
poi.box(Vector3(at.x - size * 0.5, base + layer * 0.5, at.z - size * 0.5), Vector3(size, 0.5, size), Poi.LOOK_STONE)
## A sub-part with its own local frame at `offset` in the parent's frame, turned by a
## further `turns` quarter turns.
func _child(parent: Poi, offset: Vector3, turns: int) -> Poi:
var at: Vector3 = parent.to_world(offset)
at.y = _ground.terrain_height(at.x, at.z)
var facing: int = parent.facing + turns
if parent.kind == "hamlet":
# Spots around the yard: back, left, right, front. Turn each door to the yard.
facing = parent.facing + [0, 1, 3, 2][turns]
return Poi.new(parent.kind, at, facing, _ground)
func _adopt(parent: Poi, child: Poi) -> void:
parent.solids.append_array(child.solids)
parent.parts.append_array(child.parts)
parent.loot.append_array(child.loot)
parent.routes.append_array(child.routes)