Start here

↑ ↓ to move, Enter to openKeyword search
Maps and levels

Master heightfields and adaptive collision prototype

Rendered from the repository, where it is written as the work happens: it keeps its history, and a status line above says when it describes a design rather than something shipped.

tools/level/heightfield.py is shared by terrain rendering and collision research. A pwr-heightfield-v1 manifest explicitly states metre-space origin, spacing, dimensions, axis order, encoded-height scale/offset and SHA-256 hashes. It never normalizes a terrain to its observed minimum/maximum. The origin is always minimum X/Y; row_order: "-y" means the stored image starts at maximum Y and is flipped when loaded. Decoded arrays always increase in authoring Y.

{
  "schema": "pwr-heightfield-v1",
  "coordinates": "authoring_metres_z_up",
  "origin_m": [-1000, -1000],
  "spacing_m": [1.9550342130987293, 1.9550342130987293],
  "dimensions": [1024, 1024],
  "row_order": "+y",
  "height": {
    "path": "terrain.r32",
    "encoding": "float32_raw_le",
    "offset_m": 0,
    "scale_m": 400,
    "sha256": "replace-with-the-export-file-sha256"
  }
}

That example assumes a calibrated normalized R32 export. If the export stores actual metres, use scale 1. Supported heights include 16-bit PNG/TIFF/raw LE and float32 NPY/TIFF/raw LE. Eight-bit concept images cannot masquerade as 16-bit terrain. Optional same-grid masks decode to [0,1]; road, shore, flat or bases supply collision priorities. Metadata such as water_level_m, generator settings and source receipts is preserved.

load_heightfield(path) returns Heightfield: heights_m, origin_m, spacing_m, dimensions, bounds_m, masks, metadata, manifest_sha256, sample(x,y), sample_mask(...) and resample_grid(dimensions). Sampling is bilinear unless surface_interpolation: "triangle_nw_se" explicitly selects the actual Unreal Landscape triangles in canonical +Y authoring space. Masks remain bilinear. Sampling rejects out-of-bounds coordinates by default. Input hashes, dimensions, finite values and explicit height calibration are checked.

Adaptive research command

python tools/level/adaptive_heightfield.py <final-master.json> `
  --out out/pwr/terrain-collision --terrain-budget 26000 `
  --reserve-surfaces 4000 --reserve-edges 10000 --refinement-iterations 5

The NumPy-only RTIN hierarchy pads edge samples to a 2^k+1 working grid at the original spacing, then clips the mesh back to the original domain. It does not stretch1024 samples into1025: that shifts sharp features before collision approximation even begins. It uses shared edge decisions, then independently rasterizes the resulting mesh at every original master vertex and cell centre. Measured failures guide subsequent priority adjustments under the same triangle budget. This follows the right-triangulated hierarchy concept described in Mapbox Martini; the implementation and measurement code live in this repository.

Outputs are collision-surface.npz (vertices_m, triangles) and collision-report.json. The latter includes region maxima/RMS/percentiles, signed offsets, topology, reserved architectural surfaces, estimated closure surfaces/edges, and native table headroom. Default measured targets are 0.50 m ground, 0.15 m roads, 0.25 m shore and 0.10 m flat foundations. Budget changes must preserve the native 32,767-surface and 65,534-edge limits after architecture and the world enclosure. Reported reserves are estimates, not compiler counts.

accuracy_and_mesh_budget_pass is an explicit acceptance gate. A completed research command can exit successfully while truthfully reporting a failed accuracy target; consumers must inspect that gate. runtime_ready is always false: this output is an open height surface, not a native collision package. World closure, architecture intersections, packed BSP table validation, native ray probes, vehicle handling and multiplayer remain separate requirements.

For bilinear source fields, sampled measurements do not establish a mathematical continuous error bound. They include full original source resolution and cell centres, not only retained mesh vertices. Rendering must use the same finalized master. Any road cut/fill or proposed local visual adjustment creates a new master and must regenerate dependent masks, placements and error reports.

Dense static terrain

--chunked --hierarchy-threshold 0.2 --cliff-error 2 measures dense terrain for the existing standalone-static collision path. This requires an explicit walkable mask. --terrain-budget is a total triangle cap, not a claim that the whole terrain fits one 16-bit definition. The native compiler must validate each actual piece and report its real surface ranges.

Uniform runtime NW–SE triangles require special care: RTIN alternates diagonal directions, and a saddle may have zero midpoint residual while differing at its cell centre. The builder forces implicated cells to leaves, then changes paired unit-cell diagonals to match Unreal. The independent source-grid/centre audit then covers the complete overlay of the axis/45-degree triangle meshes.

export_terrain_collision.py checks the accuracy and hash receipt and exports Morton-ordered CE-world-unit triangles. It also writes an ordered NPZ and a candidate seam receipt. Native splitting can take fewer than 8,192 surfaces when tree tables grow, so candidate seams must not be presented as verified compiled boundaries. upgrade_ce_map.py validates the exported master hash before appending these surfaces to the foliage/architecture collision tail.

Reproducible proof

python -m unittest discover -s tools/level -p test_heightfield.py -v
python tools/level/probe_adaptive_heightfield.py --out out/pwr/terrain-prototype

The synthetic 2 km fixture is explicitly not PWR geography. It exercises curved graded roads, a lake shore, rolling relief and a flat foundation. Its reports demonstrate both attainable precision and insufficient-budget failures. A flat plane remains two triangles with exact sampled height. The test suite also checks Gaea-style raw calibration, axis direction, content tampering, source format rejection and non-power-of-two source coverage.