hex_terrain API

pub struct TerrainType { tt_key: text, tt_rise: float, tt_steep: float, tt_wet: boolean }

One terrain type = content (a bundle row in the consuming game). tt_rise and tt_steep are INDEPENDENT; tt_wet marks water bodies (sea/lake): they take no relief and no boundary contest.

pub struct TerrainParams { tp_seed: integer, tp_tile: float, tp_sea: float, tp_lake_fill: float, tp_acc_min: float, tp_meander: float, tp_seg_min: float, tp_nb_base: float, tp_nb_boost: float, tp_steep_delta: float, tp_carve_max: float, tp_valley_w: float, tp_valley_max: float, tp_detail_wl: float, tp_ridge_wl: float, tp_warp: float }

Algorithm parameters (engine side). terrain_params() gives the blueprint's user-tuned defaults; every field is meters unless noted.

pub fn terrain_params(seed: integer, tile: float) -> TerrainParams

The knobs a generated terrain is built from: a seed and a tile size, plus the thresholds that follow. Hold one and the terrain is reproducible — same params, same world.

pub struct Terrain { tr_nx: integer, tr_ny: integer, tr_h: vector<float>, tr_mat: vector<integer>, tr_moist: vector<float>, tr_flow: vector<integer>, tr_acc: vector<float>, tr_relief: vector<float>, tr_wet: vector<boolean> }

Parallel per-cell vectors, index = r * tr_nx + c (odd-r offset coords).

pub fn terrain_new(nx: integer, ny: integer) -> Terrain

An empty nx-by-ny terrain: height, material and moisture per cell, all parallel, so a cell index means the same thing in each.

pub fn terrain_idx(t: Terrain, c: integer, r: integer) -> integer

The flat index of column c, row r. The one place the row-major layout is written down.

pub fn terrain_center(p: TerrainParams, c: integer, r: integer) -> (float, float)

Cell center in world meters — hex_grid's odd-r lattice scaled so the horizontal pitch equals tp_tile (hex_grid's unit pitch is SQRT3).

pub fn terrain_flow_to(t: Terrain, c: integer, r: integer) -> (integer, integer)

The downstream cell of (c, r) — itself when it has no flow direction.

pub fn terrain_hash01(seed: integer, ix: integer, iy: integer, ch: integer) -> float

A reproducible value in 0..1 for this seed and cell. A hash, not a random: the same inputs give the same answer on every machine and every run, which is what makes a generated world shareable by seed alone.

pub fn terrain_vnoise(seed: integer, x: float, y: float, wl: float, ch: integer) -> float

Smooth value noise at a world point, at the given wavelength. Built on terrain_hash01, so it inherits the same reproducibility.

pub fn terrain_fbm(seed: integer, x: float, y: float, wl0: float, octaves: integer, ch: integer) -> float

Fractal sum, roughly in [-1, 1].

pub fn terrain_detail_at(p: TerrainParams, x: float, y: float) -> float

Detail noise with DOMAIN WARP (the sampling space is swirled by a second noise so the value-noise lattice never reads as a repeating pattern).

pub fn terrain_ridge_at(p: TerrainParams, x: float, y: float) -> float

LOW-frequency ridged field, crest-sharpened: roughly ONE combined crest per steep zone — peaks consolidate into ridgelines instead of speckling.

pub fn terrain_hydrology(t: Terrain, p: TerrainParams, lake_mat: integer)

PRIORITY-FLOOD pit fill + steepest-descent flow + accumulation. After this every land cell drains to the sea; cells the flood raised by more than tp_lake_fill become lakes (material set to lake_mat). Selection-based flood (O(n^2)) — overland grids are small and this runs once at gen time.

pub fn terrain_relief_pass(t: Terrain, types: vector<TerrainType>, p: TerrainParams)

Wet flags + the compounded neighbor relief. Call AFTER the caller has classified land materials (relief reads the final wet set).

pub struct TerrainSurf { sf_h: float, sf_blend: float, sf_mat: integer, sf_mix: float, sf_relief: float, sf_moist: float, sf_watery: float, sf_lakey: float }

One blended surface record at a fine point.

pub fn terrain_surface_at(t: Terrain, types: vector<TerrainType>, p: TerrainParams, x: float, y: float) -> TerrainSurf

Smooth kernel blend of the overland cells around (x, y) + the boundary-line contest + the fine height. Pure function — THE seam invariant lives here.

pub fn terrain_blend_h(t: Terrain, p: TerrainParams, x: float, y: float) -> float

Lightweight coarse-blend height only (for slopes along river courses).

pub fn terrain_lake_field(p: TerrainParams, x: float, y: float, lakey: float) -> float

The fractally jittered lake contour field (>= 0.5 = lake water).

pub fn terrain_water_at(t: Terrain, types: vector<TerrainType>, p: TerrainParams, x: float, y: float) -> boolean

Is (x, y) open water (sea by the fine height contour, or lake)? PRE-carve — this is the shoreline rivers attach to.

pub struct TerrainRiver { rv_x: vector<float>, rv_y: vector<float>, rv_w: vector<float>, rv_d: vector<float>, rv_vw: vector<float>, rv_x0: float, rv_y0: float, rv_x1: float, rv_y1: float }

One river course PIECE: fine polyline (ends ON the shorelines) with per-vertex water width, carve depth and valley falloff width.

pub fn terrain_edge_cross(p: TerrainParams, ca: integer, ra: integer, cb: integer, rb: integer) -> (float, float)

THE EDGE BIT (user rule): a river never exits mid-side; each shared edge carries one canonical left/right bit. Both tiles hash the SORTED cell pair, so they derive the same crossing point — seamless.

pub fn terrain_control_pt(p: TerrainParams, c: integer, r: integer) -> (float, float)

The interior routing point of a tile (hash-jittered off-center; the natural confluence spot — tributaries entering the tile share it).

pub fn terrain_rivers(t: Terrain, types: vector<TerrainType>, p: TerrainParams) -> vector<TerrainRiver>

All river course pieces, fully shaped: anchors (edge bits + control points) -> fractal displacement -> corner-cut smoothing -> shoreline trim -> width/ depth/valley-width per vertex (slope-shaped + the estuary depth bonus).

pub struct TerrainSample { ts_h: float, ts_mat: integer, ts_water: integer, ts_rdist: float }

The terrain at one point, as terrain_sample answers it: the carved height, the land material, the water there (0 dry, 1 river, 2 sea, 3 lake) and the distance to the nearest river.

pub fn terrain_sample(t: Terrain, types: vector<TerrainType>, p: TerrainParams, rivers: vector<TerrainRiver>, x: float, y: float) -> TerrainSample

The full sample: surface + ADDITIVE valley carving from every course near the point + the water classification (sea floods the carved mouth). Pure function of (t, types, p, rivers, x, y) — THE window-independence invariant.