475 lines
45 KiB
Markdown
475 lines
45 KiB
Markdown
# Unreal prototype
|
||
|
||
An Unreal Engine 5 project, C++ first, that builds and proves three things in order: a movement controller,
|
||
fighting, and crafting. **Engine: Unreal Engine 5.8, launcher build at `D:\UE_5.8` (D-39). Project: `Salty`
|
||
(D-40).** Where an older doc says `<Project>`, read `Salty`.
|
||
|
||
## Before you start
|
||
|
||
Read [`Docs/Spec/README.md`](Docs/Spec/README.md) (the notation and the twelve cross-cutting rules) and
|
||
[`Docs/Spec/Architecture.md`](Docs/Spec/Architecture.md) before writing or changing any code. Nearly every wiring
|
||
decision follows from them.
|
||
|
||
For *what* to build next, read [`Docs/Steps.md`](Docs/Steps.md). It is a ladder, not a roadmap: each rung says
|
||
what exists afterwards, links the spec sections that define it, and states the proof that closes it. The spec
|
||
docs under `Docs/Spec/` are the specification; each is C++-shaped pseudocode plus the reasoning, and the
|
||
pseudocode is meant to be implemented rather than admired. If a step and its spec disagree, the spec wins and the
|
||
step is corrected.
|
||
|
||
The human summary is [`Docs/Design.md`](Docs/Design.md). Ideas from the two earlier projects that are not built
|
||
are in [`Docs/Ideas.md`](Docs/Ideas.md); do not build one inside a step about something else.
|
||
|
||
## Where the project actually is
|
||
|
||
Step 1 is built (see `Docs/Worklog.md`): `Salty.uproject` at the root, the `SaltyCore` and `Salty` modules, the
|
||
placeholder test, the tag namespaces, LFS, the scripts and `L_Gym`. It was created from the engine's Third Person
|
||
template; the plain template classes are `ATemplate*` and are the placeholder body until step 3. The template's
|
||
`Variant_*` folders under `Source/Salty/` and `Content/` are reference only (D-41): do not add code there, do not
|
||
depend on them. Four Fab asset packs sit in `Content/` (`HouseForge_01`, `Medieval_Weapons`, `Elite_RockyMeadows`,
|
||
`RPGEnvironmentVFX`); none is referenced yet, and a pack is used only when a step's spec names the asset.
|
||
|
||
Step 2 is built: `UTelemetrySubsystem` on the game instance with the null, log and JSON Lines sinks
|
||
(`-telemetry` or `telemetry.File 1` writes `Saved/Telemetry/session_*.jsonl`), the four session events,
|
||
`ASaltyGameMode` minting the session id into `ASaltyGameState`, and `bs.TelemetryTest` in
|
||
`Source/Salty/Core/SaltyCheats.cpp`, the home of every later `bs.*` command. Emit with a name from
|
||
`TelemetryEvents` and a `FTelemetryPayload`.
|
||
|
||
The editor serves the engine's MCP plugin on `127.0.0.1:8000/mcp` while it is open (D-43); `.mcp.json` points
|
||
Claude Code at it. Reconnect with `/mcp` once the editor is up. Close the editor and its Live Coding console
|
||
before a shell build.
|
||
|
||
Off the ladder, and **[`Docs/World-Pipeline.md`](Docs/World-Pipeline.md) is the map of it**: what order a
|
||
painted world map becomes ground in Unreal, which of the three routes is actually live, what every artefact is
|
||
and whether it is tracked, and the traps. Read it before running any of this; the rest of this section is the
|
||
reasoning behind it.
|
||
|
||
**`Content/Maps/L_World` is the one world level, and it is the planet-map region (D-72).**
|
||
There is no `L_Region` any more: a second world level was a second thing to keep dressed, lit and in step,
|
||
and the region always was the world. `Region.json` says which level it builds, the tile PNGs are named after
|
||
it, and `build_region.sh` reads the name out of the manifest rather than carrying one of its own.
|
||
|
||
What follows describes the numpy pipeline, which now builds `L_Canvas_Proto` rather than `L_World` — legacy
|
||
by D-47 and kept only because it is still the one path that carries the erosion pass's flow, wear and deposit
|
||
maps into Unreal. `World.json`'s `level` is named apart from the real world deliberately: `create_world.py`
|
||
empties whatever level it is handed, so a manifest still pointing at `L_World` would replace 98 landscapes
|
||
with a 14 km square on one run, without a prompt.
|
||
|
||
`Content/Maps/L_Canvas_Proto`, a ~200 km² world-partitioned landscape, is a product of three inputs and
|
||
nothing else: the manifest `RawContent/World/World.json` (size, what a heightmap value means in metres, the
|
||
height source, the paint-layer rules), the PNGs `Scripts/Authoring/generate_heightmap.py` writes from it into
|
||
`RawContent/World/Heightmaps/`, and `Scripts/Authoring/create_world.py`, which imports them through
|
||
`ULandscapeAuthoringLibrary` in the `SaltyEditor` module and dresses the level as Elite_RockyMeadows dresses its
|
||
demo maps (landscape material and layers, sun with cloud shadows, skybox, fog, grade; numbers read with
|
||
`dump_level.py`). The height source is seeded noise today, weathered and carved by `heightmap_erosion.py`
|
||
(hydraulic droplets, thermal weathering, strata; D-46); a real heightmap is a manifest edit and a rerun
|
||
(`RawContent/World/README.md`). Run `create_world.py` detached, never under a tool timeout, and never while the
|
||
editor has `L_World` open. No gameplay code references the world; the gym is still the test level. Where the
|
||
generator is going is settled in [`Docs/Terrain.md`](Docs/Terrain.md) (D-47, D-48): a Go core in
|
||
`Tools/Terrain/`, stream-power fluvial erosion instead of droplets as the thing that shapes the land, a canvas
|
||
of 7141 vertices at 200 cm over −512…1536 m, and a `Generated` edit layer so sculpting survives a rerun. Read
|
||
it before touching the generator, and the numpy pipeline is not to be extended.
|
||
|
||
The Go core now exists and works: `Tools/Terrain/` builds an uplift *rate* field and lets a Braun-Willett
|
||
stream-power solve produce the terrain from it, with a Roering nonlinear hillslope law and per-uplift-class
|
||
statistics. The coast is a pass of its own (D-51, `internal/coast`), running after the solve: a continental
|
||
shelf whose width follows the relief behind the shore, a surf that planes a shore platform and leaves a cliff
|
||
where its reach ends, and a sediment budget carried along the shore into the bays and out of the river mouths.
|
||
It stops at the geology grid, so the detail passes are unbuilt and `L_World` still comes from the numpy
|
||
pipeline. **[`Docs/Terrain-Next.md`](Docs/Terrain-Next.md) is the working brief** — how to run it, what
|
||
each output map is for, what still looks wrong, and what has already been measured and rejected. Start there.
|
||
|
||
**The source is a painted map now (D-53).** An author paints a flat cylindrical world map; a JSON legend
|
||
beside it says what each colour means in uplift mm/yr and erodibility; the simulation makes the terrain.
|
||
**And a class is two rates, not one (D-55).** `n` is 1, so a class's uplift rate *is* its hillslope angle, and
|
||
one rate over a painted blob is therefore one landscape over it - the first planet's continents came out
|
||
uniformly dissected from the waterline to the summit with no flat ground on them anywhere. A class now carries
|
||
`massif: {floor_mm_yr, fraction}` and cuts one planet-wide upland fabric, so a painted lowland is a plain with
|
||
hill masses standing out of it. The threshold is a quantile of the **planet**, never of the region.
|
||
**And there is a tool for the painting now (D-56):** `terrain studio` serves a painter on `127.0.0.1:8099`
|
||
where the brushes *are* the legend's classes, the panel shows the hillslope angle each rate buys as you type
|
||
it, the canvas wraps at the seam, and `plan` is a button. It saves by patching the *text* of the legend and
|
||
the manifest, so their commentary survives. **Its canvas is a GPU texture (D-61)**, because the 2D one put
|
||
all twenty-nine million cells through `putImageData` and a whole-image downsample on every pointer event -
|
||
105 ms an event whatever the brush touched, against 6 ms flat now. A stroke uploads only its own rectangle
|
||
(`UNPACK_ROW_LENGTH`, no copy), drawing is one quad, the seam is `REPEAT`, and one rAF loop owns the screen.
|
||
Do not put per-event work back on the input path, and do not reintroduce a second copy of a sheet in a
|
||
canvas: `full` and `ovFull` are the authority and are encoded only when pushed. **`ctrl+z` undoes a stroke**,
|
||
which is copy-on-write over a 256 px tile grid recorded at the top of `stamp` - the only writer, which is
|
||
what makes it complete. Anything new that writes to a sheet goes through `stamp` or records its own tiles
|
||
first, and wraps a rectangle into runs *before* cutting it into tiles: the grid does not line up with itself
|
||
across the seam, because 7738 is not a multiple of 256. The painted waterline is also roughened before projection now -
|
||
`coast_jitter_px` had been in the manifest since D-53 with nothing reading it - by adding fractal noise to the
|
||
signed distance from the shore rather than by warping the painting.
|
||
`RawContent/World/Templates/` holds the first one and its README is how to paint another;
|
||
`RawContent/World/Planet.json` is the planet's own manifest and `World.json` beside it — the square 14.28 km
|
||
canvas the numpy pipeline still builds — is untouched by any of it. `terrain plan` reads the painting and cuts
|
||
the planet into regions in four seconds without eroding anything; `terrain bake` solves it, about two hours at
|
||
100 km round. **Paint the uplift, never the height:** a solve handed a painted surface erodes it into
|
||
something else and throws the drainage network away, which is the reason the generator exists.
|
||
|
||
**And the overlay can be proposed from a bake now (D-68).** `terrain overlay` reads a finished bake and
|
||
fills the annotation layer in: woodland, settlements and the roads between them, which are all consequences
|
||
of ground an author cannot see while painting. **It never touches a painted pixel** - it fills blanks, so
|
||
generate, move the towns, regenerate is a loop that runs both ways - and it is **opt-in per mark** through a
|
||
`generate` block, so a legend without one produces the blank sheet it always did. Roads are a minimum
|
||
spanning tree over least-cost paths with water impassable, so each landmass gets its own network; forest
|
||
takes its treeline from a quantile of the land's own heights, because metres mean nothing until a world is
|
||
baked; `not_classes` keeps marks off the ice caps. The `coast` kind is supported and deliberately not
|
||
shipped enabled, because `coast_jitter` is the one overlay property a pass reads and generating it would
|
||
move the next bake's coastline everywhere. It proposes and does not decide: there is no economy, no history
|
||
and no climate in the Go tool, so "where would a city be" is answered with drainage, slope and distance to
|
||
the sea.
|
||
|
||
**And generating it is a button now (D-70).** The studio's overlay tab has **Generate marks**, and because a
|
||
button is pressed repeatedly rather than once, every press is a fresh seed and each draft *replaces* the last
|
||
rather than piling on it: the server remembers exactly which pixels the previous generation put down and
|
||
clears those alone, so hand-painted work is never in the set. It runs before the first bake too, on the
|
||
painting alone - flat height, no slope, drainage nil rather than zero - and says which of the two ran, because
|
||
a sketch that knows nothing about rivers must not be mistaken for one that does. A bake made from a
|
||
*different painting* is ignored with its reason printed: `CheckBake` compares only how a heightmap is
|
||
encoded, and two paintings of one planet agree on every one of those numbers, so nothing else would catch it.
|
||
|
||
**And there is a second painting now (D-57), which is not geology.** An *overlay* the same size as the
|
||
template, registered to it, painted in the studio's other tab (`o`), carries **marks** rather than classes:
|
||
forests, settlements, roads, and stretches of coast. Blank on it is alpha, never a reserved colour, and an
|
||
opaque pixel matching no mark is dropped and counted rather than snapped to the nearest — the class legend's
|
||
rule inverted, because most of an overlay is nothing. Exactly one mark property is read by any pass:
|
||
`coast_jitter` scales the waterline roughening per pixel, so a coastline drawn deliberately is pinned with a
|
||
brush stroke (`0`) while the rest of the world is still roughened, and a fjord coast is the same knob above 1.
|
||
Everything else is **inert and travels**: an 8-bit mark index beside every detail tile, and `overlay.json` with
|
||
every feature in world metres — a centre, area and extent per blob, an ordered polyline per path, because what
|
||
UE builds from a road is a spline. Nothing in the generator reads any of it back. `RawContent/World/Templates/
|
||
Map3.overlay.json` is the starter legend.
|
||
|
||
**A painting is a composition and the seed re-rolls what it does not fix (D-58).** One painting is many
|
||
worlds: the same seed change that moves the massifs, the swell, the initial relief and the coastline detail
|
||
now also moves the **rock** and the **faults**, neither of which existed on the painted path before. Lithology
|
||
is one planet-wide rock field cut into `pipeline.lithology`'s types at a quantile of the *planet*, multiplying
|
||
each class's own `k_mult` by its `lithology_mix`; before it, `map_erodibility.png` was a recolour of
|
||
`map_class.png`. Faults are a per-class `faults: {per_1000km2, throw_m, length_km}` - a rate difference across
|
||
a line, steep one side and gentle the other, which erosion carves into a scarp - drawn once for the planet in
|
||
world metres and filtered per region, so a fault crossing a region boundary is one fault. Neither could be
|
||
ported from `uplift.Build`: its lithology takes a percentile of the grid it is handed and its fault centres
|
||
are fractions of that grid, which is what D-53's decomposition forbids. `--seed` is on `plan`, `bake` and
|
||
`tiles`, and the studio has a Re-roll button. Measured: seed 7 against 9342 on one painting moves 13.8 % of
|
||
the uplift map and 24.9 % of the erodibility map.
|
||
|
||
**And a fault was a welt with a cliff down the middle (D-62).** Raised as "each fault line makes a rough line
|
||
of mountains that just doesn't look realistic", and it was not a legend number set wrong: `per_1000km2`,
|
||
`throw_m` and `length_km` say how many, how long and how much, and nothing said what *shape* a fault is. That
|
||
was two constants with a step between them - the whole throw one side of the trace, the whole throw negated
|
||
the other, one 8 m cell apart, which is **89 degrees**, inside an upthrown flank only 600 m wide. Both halves
|
||
are unsolvable and for the same reason the painted path exists. A discontinuity in the *rate* is a painted
|
||
cliff, so the trace facets at any throw and turning `throw_m` down only lowers the artefact. And 600 m is
|
||
narrower than one hillslope - the drainage density puts a divide 1.1 km from its channel - so no valley can
|
||
cut it and the profile is **printed** on the surface instead of being eroded into a landform, which is why
|
||
every fault in a bake read as a smooth ruled ridge through terrain dissected everywhere else. The profile is
|
||
continuous now, zero *on* the trace, with a 6 km footwall and a 4 km hanging wall, and the along-strike throw
|
||
is a bell rather than a flat top over the middle two thirds, so the cross-section is never extruded.
|
||
**`throw_m` is the step across the fault now, not a full throw on each side**, so a legend written before it
|
||
asks for half what it used to get. Measured on a 400 m throw: the steepest cell in the rate field went from
|
||
89 to **17.4 degrees**, and solving the same landscape for a thousand steps, the old profile left a
|
||
ruler-straight cliff with a dead apron at 43 m of relief - *less than the 45 m with no fault at all* -
|
||
against a dissected range front at 97 m.
|
||
|
||
**And widening it made a *set* of them stack (D-63).** D-62 was verified on a region two traces reach, which
|
||
is the wrong place to verify a width change: `FaultDelta` accumulates with `+=`, harmless at 600 m because
|
||
two faults almost never met, and at 6 km they meet constantly - and a fault set is sub-parallel *by
|
||
construction*, since traces inside one cell of the orientation grain share a strike. On a 22 km landmass
|
||
crossed by 13 traces, **75 % of the faulted ground had two or more faults on it**, the sum was a median
|
||
1.77x the largest single contribution, and the repose clamp fired on 4.1 % of the region against 0.15 %
|
||
planet-wide before - which is how the mountains came to read as "streaking horizontally like someone just
|
||
cut them apart with a knife". The bound is a soft knee per cell keyed to the **largest single contribution
|
||
there** (a planet-wide throw would not bite: 744 m biggest throw against a 209 m biggest contribution):
|
||
identity below it so a lone fault is untouched, bending onto 1.6x above it. Continuous and
|
||
frame-independent, and it runs unconditionally or a cell's value would depend on which frame asked.
|
||
**The other half was the initial relief reading the finished rate**: `painted.go` scaled the
|
||
symmetry-breaking noise by `rate/maxClassRate` with the fault delta in it and unbounded, so a 6 km footwall
|
||
stamped ~166 m of ridged fBm on a landmass whose whole relief was 221 m - and initial relief the size of
|
||
the landscape is not a symmetry-breaker, it is the landscape. Pre-fault rate now, bounded at one. Measured,
|
||
same region, same seed, same steps: max **221 -> 116 m**, repose-clamped cells **160 289 -> 2 865**, median
|
||
slope **6.3 -> 1.8 deg**, slope-area exponent **-0.94 -> -0.60** against a theoretical -0.50. The corduroy
|
||
is gone; the residual flank ribbing is Terrain-Next 4.B3, predates D-62 and is now diagnosed there.
|
||
|
||
**`terrain plan` prints two angles per class now, and the second is the one to read.** `divide` is
|
||
`U/(K·A^m)` at one cell — exact, and the *steepest* ground a rate can make; `typical` is the median over the
|
||
class, measured at a third of it in tangent. Almost none of a map is divide, so the old single column is how a
|
||
legend gets set two or three times too hot. **And `preview.png` lies about scale the same way**: its
|
||
hypsometric ramp tops out at a percentile of the world being drawn, so a 47 m lowland continent gets the
|
||
bare rock and snow a 2800 m range would. `palette.land_top_m` is an absolute ceiling in metres and every
|
||
run now prints which ceiling its preview used. Measured: the real 45.9 x 19.8 km lowland bakes to
|
||
**0..47 m with a 0.61° median slope**, 4.4 % of it over three degrees and nothing over eight - a plain,
|
||
and it always was one. What makes one read as hill country in the *numbers* is its massif `fraction` and
|
||
the rate the massifs reach, both of which are the author's.
|
||
|
||
Two rules govern anything written here. **The geology solve is decomposed per landmass, exactly** — ocean
|
||
cells are fixed at sea level and nothing in the solve can move them, so no flow path crosses open water and a
|
||
landmass in a box of its own gets the same answer as the whole planet would. Everything else, the coastal pass
|
||
included, runs once over the whole cylinder: it costs 26 ns a cell against 80 ns a cell *per step* for the
|
||
solve, and cutting it up would truncate the fetch across every strait and split the sediment budget.
|
||
*Decompose the solve, not the map.* And **index every noise and hash by absolute world coordinates** rather
|
||
than by grid index, through `noise.WorldUV` and a `world.Frame` — done for the router and the painted path,
|
||
still to do for the detail passes, which are the only thing that tiles.
|
||
|
||
The detail passes are built and tiled: `terrain tiles` runs passes 8 to 12 and 14 over a bake and writes 5 km
|
||
tiles of 2500 samples at 2 m, about twelve seconds each, with a hillshade and the flow, wear and deposit maps
|
||
beside each one. Their margin is measured rather than reasoned - three droplet lifetimes - and the droplets
|
||
spawn from a hash of world position so a tile's interior is what it would have been in one whole run.
|
||
|
||
**And a planet can be judged now (D-59).** `internal/stats` sorted a copy of every land cell, so a bake
|
||
printed its elevation range and nothing else - no slopes, no per-uplift-class breakdown, no drainage density.
|
||
Fixed-bin histograms replace the sorts and `field.LocalRelief` the O(radius²) window, but the property that
|
||
matters is that a histogram **adds**: a planet's statistics are pooled from its regions, exactly, where a
|
||
median of medians would not be. Each region accumulates while its grid is alive and they merge in region
|
||
order; the *extent* is measured once on the composited cylinder, because regions carry overlapping ocean
|
||
margins. A partial bake says PARTIAL rather than letting the whole world's extent be read against three
|
||
islands' ground. About 120 ns a cell, so a planet is a few seconds at the end of a two-hour bake.
|
||
|
||
**And a planet has a shore now (D-60).** `internal/coast` ran on a flat grid, so a bake laid the painted sea
|
||
floor and stopped: the land met the painted ocean depth in one cell, with no shelf, no surf platform, no beach
|
||
and no exposure anywhere. Four primitives wrap now - `boxBlur`'s running sum, `fetch`'s ray march,
|
||
`shelfWidth`'s inland march and the distance-field gradient both marches steer by - and the test for it is
|
||
that the same island in two places is the same island, not that the seam looks right. **The abyss is a field**,
|
||
because a painted planet's sea classes carry their own depths and one global number would step to the painting
|
||
wherever they disagreed; it also means the break can never be deeper than the water it is a break in. Memory
|
||
was the other half: `Geometry.Ref` holds a waterline *slot* rather than a cell index, so the sediment supply is
|
||
a few hundred thousand entries instead of 608 MB, and `Measure` holds one distance transform at a time. 7.9 s
|
||
over the whole 76 M cell cylinder; the seam step in the sea floor went from a mean of 9.1 m to 0.32 m, which is
|
||
what an ordinary column is. The pass is now the memory peak of a bake, about 8.3 GB against the solve's 3.6.
|
||
|
||
**And the ocean was thirty metres deep (D-64).** Reported as "it is just a landmass and no oceans really",
|
||
against the exported heightmap. The legend paints `ocean` at 512 m over 56 % of the planet and 17 % of it got
|
||
there; 40 % of the world was water between 0 and 30 m, which at the manifest's `-1024..2048` encoding is 1 %
|
||
of the 16-bit ramp from sea level, so the shelf and the land came out the same grey and every landmass's
|
||
shelf halo fused it to its neighbours. The depth at the shelf break is one number, and both call sites took
|
||
it from `pipeline.continent.sea_floor_m` - the **square canvas's** block, whose own comment says −30 m is not
|
||
a shelf break because a real one does not fit on a 14.28 km canvas. It is `pipeline.coast.break_m` now, 130 m
|
||
on a planet and the old reading on the square canvas, which is unchanged. What hid it is arithmetic: the
|
||
derived margin reaches `shelf_km.hi() + slope_km` = 4.6 km from every shore, and 1069 km of shoreline against
|
||
a 3111 km² sea is more margin than there is ocean, so no strait ever reached the painting. **The margin's
|
||
width is right and was never the problem** - 512 m over 4.6 km is a 6.3° continental slope. The profile is
|
||
monotone at any break depth, so every profile test passed; this had to be found in a histogram, and a bake
|
||
prints its sea floor's three numbers now. It also prints **how much of the 16-bit ramp the world used** - 28 %,
|
||
with land at 7 % - because too *wide* an `elevation_m` clips nothing and `clip_fraction` only ever catches one
|
||
too narrow. **The whole-planet re-bake was killed by memory pressure and its numbers are still owed**; what is
|
||
measured is the mechanism at unit scale, 33 % → 8 % of a painted 512 m sea left shallower than 50 m.
|
||
|
||
**And the mountain flanks were laser-carved, which was D8 (D-65).** Reported as "streaks going down the
|
||
side of the mountains", and `Terrain-Next.md` 4.B3 had the wrong cause: it blamed the ridged-fBm initial
|
||
relief and dismissed grid locking because the ribs are *oblique*, which is not a counter-indication - D8's
|
||
parallel-flow grooves run in whatever direction the slope faces. The grooves are **channels**: in
|
||
`map_flow.png`, absent from `map_uplift.png`, and the network is **pinnate** - ruler-straight parallel trunks
|
||
with barbs at a fixed angle - with 25 sources and **no confluences** in a 12.8 km window. What settles it is
|
||
that the pitch is **18 cells in both the 32 m bake and the 8 m one**, and everything fixed in metres would
|
||
have changed by four. Isolated with no erosion at all, on a planar ramp where the correct specific catchment
|
||
area is the same along a contour: D8 gives the most-drained cell **769x the median** and leaves **29.5 % of
|
||
the grid draining nothing**, because every cell picks the same steepest neighbour and the flow lines never
|
||
converge. Drainage area is **Freeman MFD** now - `Accumulate` only, D8 receivers kept because Braun-Willett
|
||
walks one receiver chain - ordered by **Kahn over the flow graph, not by elevation**: exact, O(n), and a
|
||
bucket sort would leak every lake bed's area, since the queue quantises to a centimetre and the flood's
|
||
epsilon ladder is a millimetre a cell. 769 -> **1.34**, 29.5 % -> **0.4 %**, float32 is enough (2.4e-9 over a
|
||
closed basin), and it costs **101 ns a cell against D8's 17**. `pipeline.fluvial.mfd_exponent` is 1; 0 is the
|
||
old behaviour, so the A/B is one flag. Three repairs alongside: the repose clamp jitters its pop order and
|
||
allowance (the residual octagon on a clamped cone is the octile metric, not the order, and is irreducible);
|
||
`DiffuseNonlinear` is the isotropic **nine-point** stencil, because the clamp cuts across eight faces and a
|
||
five-point smoother cannot transport across a diagonal one at all; and `field.SmoothEdgePreserving` is ported
|
||
from the World Orogen browser generator, **off by default**, and measured against its own acceptance gates
|
||
it fails them: two passes at `slope_ref` 0.3 move the slope-area exponent from -1.02 to +0.36 and the
|
||
mountain median slope by 3.7 degrees, and one gentle pass at 0.02 still lands at +0.16. It is a filter, not a
|
||
polish, and it is for somebody who decides in a file that they want the look more than the statistic. That generator routes single-receiver too; what keeps its flanks clean is that it solves on an
|
||
irregular Voronoi mesh with no lattice directions, which a raster pipeline cannot adopt. **Do not fold a
|
||
pass's precondition into another pass**: the Kahn counts were first computed in `ComputeReceivers` for free,
|
||
and because the walk consumes them a second call returned a silently wrong area that only a benchmark caught.
|
||
|
||
**And the painting has a browser twin (D-66).** `Tools/Orogen/` is World Orogen, the GPL browser planet
|
||
generator D-65 borrowed its smooth from, and its import page now has a **Painted Map** source that reads the
|
||
*same* painting and legend `terrain plan` does and solves them on its 204K-region sphere mesh in about
|
||
twelve seconds: the same classify, vote, stroke, coast, massif, rock and swell steps, then a Braun-Willett
|
||
solve with the ocean fixed, then Orogen's own climate, satellite view and exports - plus class, uplift,
|
||
erodibility, drainage, slope and basin layers. It is for looking at a painting's rivers on a globe in half a
|
||
minute and tuning the legend's numbers in a table before a two-hour bake; it is not ground a player can
|
||
stand on, and it carries no faults, craters, plates or detail passes, because a 44 km cell cannot
|
||
show them. The legend is the contract between the two tools: new keys optional, nothing renamed. Serve the
|
||
folder with any static server (`npx serve Tools/Orogen`) and open `/import`.
|
||
|
||
**And the twin reads the planet's own files now (D-67).** Three things carried across, each one a question an
|
||
author has *while typing a number*. The class table prints the **typical** hillslope angle a rate makes and
|
||
what it reads as, with the divide angle in the tooltip - `plan.go`'s functions ported exactly and checked
|
||
against `plan.json` to 1e-9 - because the divide is the steepest ground a rate can make, almost none of a map
|
||
is divide, and reading it as the landscape is how a legend gets set two or three times too hot. The
|
||
**overlay** is carried as a *texture* over the globe and the map rather than voted onto the mesh, since a road
|
||
is 8 px and a region there is 44 km; marks are voted for one thing only, `coast_jitter`. And `Planet.json` is
|
||
read directly, outranking a legend's own `planet` block because it is the file the bake reads. `terrain
|
||
studio` serves all of it: `share.go` sets the CORS header on **GET and HEAD alone** and answers no preflight,
|
||
so **Load from studio** brings the whole planet in four seconds, including strokes made since the last save,
|
||
and no browser tab can ever paint, save, plan or bake. The two tools are not interchangeable and the twin is
|
||
not on a path to replace the bake: the 8 m geology grid, the coast pass, the faults, the craters and the
|
||
detail tiles are the Go tool's, and only they produce ground a player can stand on.
|
||
|
||
**And there is ground in Unreal now, 900 km² of it (D-69).** `L_Region` is a *window cut out of a finished planet heightmap* and laid out as a grid of landscapes - 6 x 6 tiles of 2551 vertices at 200 cm, 10 x 10 components of 255 quads each, **30.60 km a side, 936 km² of map holding 905 km² of land**, built one batch at a time by `Scripts/Authoring/build_region.sh`. Its contract is `RawContent/World/Region.json` and `RawContent/World/README.md` is how to move the window. Today's source is the Orogen twin's export, and three things about it are the whole design. **The scale is a choice, not the planet's**: the export carries none, and at `Planet.json`'s 100 km circumference the planet is 31.8 km across, so a flat 30 km square does not fit on it at all; 22.583 m a pixel is a 185 km circumference, the finest reading whose best window still clears 900 km² of land. **The map is read flat**, which at latitude -24 stretches the ground 9.6 % east-west - cheaper than any projection over a patch two thirds the width of the planet. **The heights are Orogen's normalised metres, not the generator's**: `terrain bake` makes this same continent a 116 m plain and the export makes it 2972 m, so the relief is art. The source resolves about 200 m, so below that the ground is smooth and no upsample can invent what is not there - **the detail is still the Go tool's**, and when `terrain tiles` replaces the window as the source, `generate_region_tiles.py` is the only thing that changes. Seams are exact rather than blended, because every vertex is sampled from its global position in the window. Do not run a landscape import for the whole grid in one process: a hundred components cost about a gigabyte the editor never gives back, and thirty-six tiles in one run reached 14.7 GB by the ninth. Do not pass a script's arguments after `-script=` either - they go inside the quoted value, and the engine silently eats them otherwise.
|
||
|
||
**And Orogen exports that tile set itself now (D-71).** The Python cutter exists because Orogen gives two
|
||
things Unreal can import neither of - a picture, and one flat 8192 x 4096 PNG with **no scale on it**, which
|
||
is what forced `metres_per_pixel` to be a number somebody chose. The browser twin's export card now has
|
||
**Unreal Landscape…**: it renders a window of the planet straight into the tiles the importer wants - a
|
||
16-bit height at 255*N+1 vertices and three 8-bit weightmaps per tile, plus the `Region.json` describing
|
||
them - into a folder picked through the File System Access API, so the files land in `RegionTiles/` and
|
||
`create_region_world.py` reads them unchanged. **The window is sampled once and then cut**: every tile is
|
||
resampled out of one float raster by its *global* vertex position, which is what makes a shared column
|
||
bit-identical (measured: 0 of 1021 vertices differ on either seam, heights and paint). A tile rendered under
|
||
its own camera would put a rasteriser's luck on every seam, where one 16-bit step is 11 cm of crack. The
|
||
paint closes only because tiles carry a one-vertex margin for the slope's central difference - D-69's numpy
|
||
defect, met again in JavaScript. **The panel is for the number you have not typed yet**: it re-plans on the
|
||
keystroke and prints ground, components, files, sample spacing and what the flat reading costs, and it
|
||
immediately said what this project had not: **936 km² on a 100 km planet is 29 % of the entire globe**, a
|
||
window 110 degrees on a side stretched 74.7 % at its edge, because a 100 km circumference is a 3183 km²
|
||
world. The projection is cosine-corrected at the centre latitude so the error splits between the two edges;
|
||
the defaults are 4 x 2 tiles, 208 km² at 5.4 %. **It does not make ground finer** - the mesh resolves a
|
||
couple of hundred metres and no sampling invents what is not there - so `generate_region_tiles.py` stays,
|
||
because it is the path that will read `terrain tiles`. Two traps worth keeping: never `<input type="number">`
|
||
for a decimal (it parses in the browser's locale, so a comma-decimal machine turns 0.17 into NaN and writes
|
||
a tile set of nothing), and a build now **refuses to start when the editor holds the level** (D-71a) -
|
||
`--rebuild` empties first and saves last, so a lock detected late is indistinguishable from data loss.
|
||
|
||
**And the ground is collected in one place now (D-69a).** `Content/Terrain/` is the project's own ground, copied out of the asset packs by `Scripts/Authoring/collect_terrain_assets.py` from the list in `RawContent/Terrain/ground.json`; adding a substance is a line in that file and a rerun. A copy is not ownership - a duplicated material function still samples the pack's textures, because the reference is inside the graph - so the copies are repointed at each other and the asset registry is then asked what still points outside the folder. The packs are never modified. Elite_RockyMeadows' sky kit stays separate in `Scripts/Authoring/rocky_meadows.py`, which both `create_world.py` and `create_region_world.py` now dress from.
|
||
|
||
**And there is a map of it now, in the game and in the editor (D-73).** The three candidate sources were one:
|
||
`Region.json` imports the **whole** Orogen export with no crop, so `L_World` *is* the planet map and
|
||
world-to-map is `u = (X/100 + 35700) / 71400` — one multiply and one add per axis. There is **no scene capture
|
||
and no render target**, and a capture would have been wrong rather than merely expensive: the level is
|
||
world-partitioned, so a capture only ever sees the streamed-in region, and a map is the thing that must show
|
||
ground nobody is standing on. `FWorldMapProjection` in `SaltyCore` is the whole transform, pure and tested;
|
||
`SWorldMap` is **one Slate widget with three ways in** — `UWorldMapWidget` for UMG, the editor's **Window →
|
||
World Map** tab, and `bs.WorldMap` straight over the viewport — because the editor tab has no `UWorld` at all
|
||
and anything needing one could not have been shared. A whole cylinder **wraps**, so a view across the seam is
|
||
two draws of two parts of one image and `WrapU` uses floor rather than `FMath::Fmod`, which keeps its
|
||
argument's sign and would leave a westward pan sampling nothing. The art is `Tools/MapArt`, a Go tool, because
|
||
the engine's Python cannot decode 33 megapixels of RGB — `heightmap_io.py` is greyscale-only and unfilters a
|
||
byte at a time — and it renders four 4096 x 2048 layers in six seconds from `RawContent/World/MapArt/layers.json`.
|
||
The default layer, `relief`, is **derived rather than exported**: hillshade and a hypsometric tint off the same
|
||
heightmap the landscape was cut from, so the map and the ground are the same shape by construction, where a
|
||
colormap shows biome and a player needs landform. Nothing inside a PNG says which planet it is, so `mapart
|
||
check` measures land/sea agreement against the heightmap instead — the pasted `orogen-colormap-14733759` scores
|
||
97.5 % against `orogen-heightmap-7945` and is the same world; Orogen numbers each *export*, not each planet.
|
||
The definition's projection is copied out of `Region.json` and never typed, because a map that disagrees with
|
||
the landscape about how big the world is is the one bug here that still looks like a plausible map. Overlay
|
||
marks are not drawn yet and transfer by the same normalised coordinates when they are.
|
||
|
||
Where it is going: the coastal detail pass, which the shelf and the shore platform have just unblocked.
|
||
Composition tuning is parked, and on a painted world most of it is the author's job now.
|
||
|
||
Next: step 3, the body, the camera, the input map and the gym. Step 1's PIE proof (two clients, dedicated
|
||
server, two pawns in the gym) is still a person's to tick. Update this section when a step closes.
|
||
|
||
## Layout
|
||
|
||
The `.uproject` sits at the repository root, which is what the `.gitignore` assumes.
|
||
|
||
| Path | What it is |
|
||
| --- | --- |
|
||
| `Salty.uproject`, `Source/Salty.Target.cs`, `SaltyEditor.Target.cs`, `SaltyServer.Target.cs` | The project and its three build targets. The server target needs a source-built engine (OD-04) |
|
||
| `Source/SaltyCore/` | Rules, data types, tags, the telemetry contract. Knows no `AActor`. Tests in `Tests/` |
|
||
| `Source/Salty/` | Gameplay: `Core/`, `Stats/`, `Movement/`, `Interaction/`, `Combat/`, `Crafting/`, `UI/`, `World/`, one folder per feature. `Variant_*` is template reference (D-41) |
|
||
| `Source/SaltyEditor/` | Editor-only tools: `Authoring/` (the landscape library the Python scripts call), `WorldMap/` (the dockable map tab). May depend on `Salty`; never the reverse |
|
||
| `Content/<Feature>/` | Assets per feature: `Definitions/` for data assets, Blueprints, meshes, montages |
|
||
| `Content/Maps/L_Gym` | The movement test level, authored by `Scripts/Authoring/create_gym.py`. Never leaves the project |
|
||
| `Content/Terrain/` | The project's own ground: textures, layer functions, the landscape material and its layer infos, collected out of the packs (D-69a). Built by `collect_terrain_assets.py` from `RawContent/Terrain/ground.json` |
|
||
| `Content/Maps/L_World` | **The world.** Ground from a planet map, one landscape a tile (D-69, D-72). Built by `Scripts/Authoring/build_region.sh`; the contract is `RawContent/World/Region.json`, written by hand or by Orogen's Unreal export (D-71). Never run a build with the editor holding the level |
|
||
| `Content/Maps/L_Canvas_Proto` | The numpy pipeline's square 14.28 km canvas, legacy (D-47). Built by `create_world.py` from `World.json`. Named apart from `L_World` on purpose: that script empties whatever level it is handed |
|
||
| `Content/World/` | World dressing the project owns rather than borrows. `M_Sea_Proto`, the placeholder grey the sea plane wears; authored on demand by `rocky_meadows.sea_grey_material` |
|
||
| `Content/World/Maps/` | The world map's textures and `DA_WorldMap_L_World` (D-73). Built by `Scripts/Authoring/build_world_map.sh`; the contract is `RawContent/World/MapArt/layers.json` and the projection is copied out of `Region.json` |
|
||
| `Tools/MapArt/` | Renders the map's layers from the planet images: downsamples what is already coloured, shades relief from the heightmap. Go, because the engine's Python cannot decode 33 megapixels of RGB |
|
||
| `Content/Tests/` | Functional test maps |
|
||
| `Config/Tags/<Feature>.ini` | Gameplay tag source of truth, one file per top-level namespace |
|
||
| `Scripts/` | `run-tests.sh`, `build.sh`, and `Authoring/` for editor Python scripts. Run by hand; there is no CI. `UE_ROOT` overrides the engine path |
|
||
| `Docs/` | The documentation set. Update it when you change how something works |
|
||
| `Docs/Worklog.md` | One terse line per step closed or wall hit |
|
||
|
||
Module dependency is one way: `Salty` depends on `SaltyCore`, never the reverse. If the core module seems
|
||
to need an actor, the thing it needs is data.
|
||
|
||
## Conventions
|
||
|
||
- **The server decides.** Every mutation is a `Server*` path that validates its instigator and re-checks its
|
||
preconditions, even in standalone play. The client predicts its own movement and its own animation, nothing
|
||
else. Never write a listen-server assumption or an "is this the host" branch.
|
||
- **Rules are pure C++ in the core module; actors and components adapt them.** A preview and the real thing call
|
||
the same function. Every pure rule has automation tests, one per rejection reason.
|
||
- **One funnel per consequence.** All damage through `UDamageExecution`; all interactions through
|
||
`UInteractionSubsystem`; all activity quality through `FActivityResult`. Do not add a second path.
|
||
- **One stat block; everything is an effect on it.** Every body has `UStatBlockAttributeSet`; every buff,
|
||
debuff, surface, weight, gear and base value is a gameplay effect applied through `ApplyStatus` or
|
||
`ApplyDefaults`. Never add a multiplier, a modifier list or a status timer to a component. Counters are
|
||
`Immune.*` tags and resist attributes on the receiver. See `Docs/Spec/Stats.md`.
|
||
- **Content is data.** `UPrimaryDataAsset` subclasses, addressed by gameplay tag or primary asset id, art through
|
||
soft references. No string ids. If a variant needs code, the model is wrong.
|
||
- **Gameplay Tags are the vocabulary.** Defined in `Config/Tags/`; tags code references are declared natively
|
||
with `UE_DECLARE_GAMEPLAY_TAG_EXTERN` / `UE_DEFINE_GAMEPLAY_TAG`. No string literal tag at a call site.
|
||
- **C++ owns rules, replicated properties and RPCs. Blueprints own composition, tuning and cosmetics.** A
|
||
Blueprint is a child of a C++ class that sets assets and numbers and wires `*_Cosmetic` hooks.
|
||
- **Lifetimes are the engine's.** Game-instance subsystems for the application, world subsystems for a map,
|
||
the player state for a player across bodies, the pawn for a body. Nothing about a player that would matter
|
||
tomorrow lives on the character actor.
|
||
- **No world searches in gameplay code.** No `GetAllActorsOfClass`, no static gameplay singletons. Subsystems are
|
||
the registries; actors register in `BeginPlay` and unregister in `EndPlay`.
|
||
- **Every rejection carries a reason tag** a player can read. **Nothing is destroyed silently.**
|
||
- **Emit telemetry through `UTelemetrySubsystem` with names from `TelemetryEvents`**, never a literal, never a
|
||
static helper. Every feature emits; the catalogue in `Docs/Spec/Telemetry.md` and the feature spec agree.
|
||
- **Naming is Unreal's:** `A`/`U`/`F`/`E`/`I` prefixes, no project prefix on classes, `PascalCase` members, asset
|
||
prefixes `BP_ DA_ DT_ IA_ IMC_ GA_ GE_ GC_ ABP_ AM_ SK_ SM_ M_ MI_ WBP_ T_ L_`. Placeholders carry `_Proto`.
|
||
- **Units are centimetres and seconds.** `FText` for anything a player reads. `TObjectPtr` for object properties.
|
||
- **The design word "material" is "substance"** in code and docs. `UMaterial` is the engine's.
|
||
- Do not add an interface, a module or an abstraction for one implementation with no test double. The two source
|
||
projects were each trimmed of speculative abstraction once already; the interfaces that exist here are the ones
|
||
with several implementations named in the specs.
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
Scripts/run-tests.sh # headless: UnrealEditor-Cmd Salty.uproject -ExecCmds="Automation RunTests Salty; Quit" -unattended -nopause -NullRHI
|
||
Scripts/run-tests.sh Core # a filter: Salty.Core.*
|
||
Scripts/build.sh Win64 Development # UAT BuildCookRun for the game target; add -server for the server target once the engine is a source build
|
||
D:/UE_5.8/Engine/Build/BatchFiles/Build.bat SaltyEditor Win64 Development -Project="<abs>\Salty.uproject" -WaitMutex # compile the editor from a shell
|
||
UnrealEditor-Cmd.exe Salty.uproject -run=pythonscript -script=Scripts/Authoring/create_gym.py # rerun an authoring script
|
||
Scripts/Authoring/build_world_map.sh # the world map: render the art, import it, write the definition asset
|
||
cd Tools/MapArt && go run . check # is every map layer the same planet L_World was cut from?
|
||
```
|
||
|
||
In the editor the map is **Window → World Map**; in game it is **`M`**, with **`N`** to switch layers - both
|
||
`DebugExecBindings` in `Config/DefaultInput.ini` onto `bs.WorldMap` and `bs.WorldMapLayer`, which is the
|
||
engine's own mechanism for binding a key to a console command and exists in development builds only. It needs
|
||
no Input Action, no mapping context and no asset, so it does not pre-empt step 3, where the real input map is
|
||
designed; when the map gets a HUD it gets an `Input.*` action and those two lines go away. Drag to pan, wheel
|
||
to zoom about the cursor, right-double-click to fit, **left-double-click to go back to the player and follow
|
||
them again** (`bs.WorldMapFollow` does the same). The map opens centred on you with an arrow, haloed so it is
|
||
findable at whole-world zoom, pointing where you are looking; panning by hand drops the follow deliberately,
|
||
because a map that snaps back as you let go of it cannot be read.
|
||
|
||
There is no CI, deliberately, and there will not be until there is a reason. Run the tests yourself before saying
|
||
a step is done. Every replicated step is also played in the editor with two clients, "Run Dedicated Server" on, and
|
||
network emulation at 100 ms and 5 % loss with `p.NetShowCorrections 1`.
|
||
|
||
## Working with the editor
|
||
|
||
- Prefer editing C++ and `.ini` files directly. Blueprints and maps are binary; keep them thin and keep logic out
|
||
of them so a diff can be reviewed.
|
||
- Batch authoring (a folder of definition assets, a greybox level from a table) goes through the editor's Python
|
||
API in `Scripts/Authoring/`, idempotent, kept so it can be rerun. Do not hand-edit `.uasset` files.
|
||
- Blueprint-side wiring an authoring script cannot express is done once in the editor and recorded in the step's
|
||
worklog line so it can be redone.
|
||
- Watch for the compile trap: a C++ error that stops the editor launching is fixed in the files, with the build
|
||
output, not by guessing. The editor's Live Coding is fine for iteration and unreliable for header changes; a
|
||
header change means a full rebuild.
|
||
- Every `.uasset` and `.umap` goes through Git LFS; `.gitattributes` is created in step 1. Run `git lfs install`
|
||
once per machine. Never commit `Saved/`, `Intermediate/`, `DerivedDataCache/` or `Binaries/`; the `.gitignore`
|
||
covers them.
|
||
|
||
## Documentation upkeep
|
||
|
||
- A step that lands updates: its status in `Docs/Steps.md`; a **What was built, and where it differs** section at
|
||
the end of the spec it built from; a line in `Docs/Worklog.md`; a line in `Docs/Decisions.md` if a decision was
|
||
taken; and the "Where the project actually is" section above.
|
||
- A design change that contradicts a decision names the decision it supersedes in the log. Never delete a log
|
||
line.
|
||
- Do not turn `Docs/Steps.md` into a roadmap. Detail the next step when the current one closes, not before.
|