# THE DESCENT — Unreal port: Design (Designer → Coder)

Single source of truth for the Unreal Engine 5.8.1 port. Requirements come from `BRIEF_UE.md` (U1–U14, plus
V1–V13 from `the-descent/docs/BRIEF_V2.md`). Where this document and the brief disagree, **the brief wins**.
Where this document and the code disagree, **this document wins** until it is amended.

The browser version (`the-descent/src/*.js`, `the-descent/docs/DESIGN_V2.md`) is the reference implementation.
Numbers marked *(v2)* are ported unchanged because they worked. Numbers marked *(new)* replace or add to v2.

Contents: 0 Conventions · 1 Architecture · 2 Terrain and world · 3 Carrier · 4 Tender · 5 Player · 6 Systems ·
7 Look · 8 Sonar, map, horror, audio, UI · 9 Verification harness · 10 Milestones · 11 Risks and open questions.

---

## 0. Conventions (read before anything else)

| Topic | Rule |
|---|---|
| Units | The design is in **metres, seconds, degrees**. 1 m = 100 Unreal units (uu). Convert only through `Descent::MetresToUU / UUToMetres` (`Source/TheDescent/DescentUnits.h`, exists). Every number in this document is metres unless it says uu, cm or px. |
| World axes | Unreal axes: **+X north ("down-canyon"), +Y east, +Z up**. Altitude is Z in metres. |
| Vessel axes | Carrier, Tender and every placed object: **+X bow / nose, +Y starboard (right), +Z up**. Port is −Y. |
| Heading ψ | Unreal yaw: 0° = +X, positive toward +Y (clockwise seen from above). Pitch positive = nose up. |
| Depth | `Depth = DATUM − Z` with **`DATUM = 1780 m`** *(v2)*. One function, `Descent::DepthOfZ(double Zm)`, is the only place that computes depth. The rim of the Throat is Z = +40 (depth 1,740 m). |
| v2 → UE coordinates | v2 was right-handed, y up, bow toward −z. Map every v2 vector with **(x, y, z)₍v2₎ → (X = −z, Y = x, Z = y)**. All tables below are already converted. |
| Kazah (Blender → UE) | Blender nose −Y, port +X, Z up. **(x, y, z)₍blender₎ → (X = −y, Y = −x, Z = z)**. `Tools/blender/export_kazah.py` already does this (see `Vehicles/KazahLayout.inl`). |
| Randomness | Gameplay uses the seeded `mulberry32` port (`Descent::FRng`). World seeds are fixed (§2.9) so tests are repeatable. `FMath::Rand` is allowed only for cosmetics. |
| Helpers | Port these v2 helpers verbatim into `Core/DescentMath.h`: `clamp`, `lerp`, `smooth(e0,e1,x)` (smoothstep), `damp(a,b,k,dt) = lerp(a,b,1−exp(−k·dt))`, `smin(a,b,k)` (`h = max(k−abs(a−b),0)/k; min(a,b) − h²·k/4`), `mulberry32`, 3D simplex noise `makeNoise3(seed)` (`01_core.js:39–64`). |

---

## 1. Architecture

### 1.1 Module, plugins, project settings

One runtime module, `TheDescent` (exists). No editor module: assets are made by Python scripts under
`TheDescentUE/Tools/` run with `UnrealEditor-Cmd.exe … -run=pythonscript -script=…` (`PythonScriptPlugin`,
already enabled; commandlet in `Engine/Plugins/Experimental/PythonScriptPlugin/.../PythonScriptCommandlet.cpp`).

`TheDescent.Build.cs` dependencies to add as the milestones need them:

| Module | Why | First needed |
|---|---|---|
| `ProceduralMeshComponent` (plugin `ProceduralMeshComponent`, add to `.uproject`) | terrain chunks, carrier blockout | M1 |
| `Slate`, `SlateCore`, `UMG` | neumorphic UI, `UWidgetComponent` dashboards | M2 |
| `PhysicsCore` | collision shapes and queries | M2 |
| `Json` (already), `RenderCore` (already) | harness | M0 |

Not used, do not add: Niagara, MetaSounds, Mover, Water, Chaos Vehicles, Geometry Scripting, Lumen-only features.
They are present in the engine but every effect here is specified without them so that nothing depends on
hand-authored assets.

`Config/DefaultEngine.ini`, `[/Script/Engine.RendererSettings]` (names verified in
`Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h`):

```ini
r.DynamicGlobalIlluminationMethod=0      ; no Lumen GI: ambient is a material term (§7.3), deterministic for tests
r.ReflectionMethod=2                     ; screen-space reflections
r.Shadow.Virtual.Enable=1                ; already set
r.CustomDepth=3                          ; custom depth WITH stencil (dry-interior mask, §7.4)
r.DefaultFeature.AutoExposure=False
r.DefaultFeature.MotionBlur=False
r.DefaultFeature.LensFlare=False
r.DefaultFeature.Bloom=True              ; values come from the post-process component (§7.6)
r.AllowStaticLighting=False              ; already set
```

M0 currently ships `r.DynamicGlobalIlluminationMethod=1` and `r.ReflectionMethod=1` (Lumen). **Change both in
M1** to the values above. Reasons: the terrain and the carrier blockout are procedural meshes with no distance
fields or Lumen cards, so Lumen would light them from screen traces only; Lumen's temporal gather lags behind
a moving headlamp, which is the main light of this game; and the luminance tests of §7.10 need a renderer
whose output does not depend on warm-up history. Revisit Lumen for the interior when real static meshes
replace the blockout (§11).

`[/Script/EngineSettings.GameMapsSettings]` is already set by M0: `GameDefaultMap` and `EditorStartupMap` =
`/Game/Maps/Descent_Main`, `GlobalDefaultGameMode=/Script/TheDescent.DescentGameMode`. From M1 on the map
holds **only a PlayerStart**: `Tools/ue/import_assets.py` must stop placing fog, exposure and the showcase rig
in it, because **everything is spawned by code at BeginPlay** (§1.5) and a second height fog or post-process
volume in the map would fight `ADescentEnvironment`. Pressing Play in the editor and running `-game` then
give the same world. The showcase rig stays available to the `kazah_showcase` scenario, spawned by the scenario.

### 1.2 Source layout

```
Source/TheDescent/
  DescentUnits.h                 (exists)
  Core/      DescentMath.h  DescentTuning.h  DescentGameMode.*  DescentSimSubsystem.*  DescentSave.*
  World/     DescentWorldDef.*  DescentSDF.*  DescentTerrainSubsystem.*  TerrainChunk.*  SurfaceNets.*
             DescentOreSubsystem.*  DescentShear.*
  Vehicles/  DescentCarrier.*  CarrierLayout.*  CarrierBlockout.*  CarrierHelm.*  CarrierCarousel.*
             KazahTender.* (exists)  KazahLayout.inl (generated)  TenderFlight.*  TenderTool.*  TenderHold.*
  Player/    DescentCharacter.*  DescentCharacterMovement.*  DescentPlayerController.*  DescentInteraction.*
             DescentCarry.*  DescentVitals.*  DescentInventory.*
  Systems/   DescentItems.*  DescentStore.*  DescentCargo.* (pipes, packer, boxes)  DescentRefinery.*
             DescentFabricator.*  DescentEconomy.*  DescentBuild.*  DescentPlaceables.*  DescentRobotArm.*
             DescentBiomass.*
  Life/      DescentFauna.*  DescentFlora.*
  Render/    DescentEnvironment.*  DescentMarineSnow.*  DescentLightPool.*
  Sonar/     DescentSonar.*  DescentSurveyMap.*
  Horror/    DescentHorror.*  DescentLeviathan.*  DescentBeacons.*
  Audio/     DescentAudio.*
  UI/        NeuStyle.*  NeuWidgets.*  DescentHUD.*  DescentWindows.*  DescentDash.*
  Debug/     (exists) + DescentCommands_<System>.cpp
  Tests/     (exists) + one .cpp per system
```

### 1.3 Class list

Actors (A), components and UObjects (U), plain C++ (F), Slate (S). "Sim" means it is stepped by
`UDescentSimSubsystem` (§1.4), not by its own `Tick`.

| Class | Kind | Owns / does |
|---|---|---|
| `ADescentGameMode` (exists) | A | Default pawn `ADescentCharacter`, controller `ADescentPlayerController`. `StartPlay` runs the boot sequence §1.5. |
| `UDescentSimSubsystem` | `UWorldSubsystem` | The ordered simulation step (§1.4), sim clock, `FastForward`. |
| `UDescentSaveGame` | `USaveGame` | §6.12. |
| `FDescentWorldDef` | F, immutable after `Build()` | Every SDF primitive, deposit, beacon and landmark of the level (§2.7–2.9). |
| `FDescentSDF` | F, thread-safe | `GenRaw`, `Gather`, primitive distance functions (§2.2). |
| `UDescentTerrainSubsystem` | `UWorldSubsystem` | Chunk map, density queries, carving, cleanup, streaming, async jobs, component pool (§2.3–2.6). |
| `ADescentTerrainActor` | A | Owner of the pooled `UProceduralMeshComponent`s. No logic. |
| `FTerrainChunk`, `FSurfaceNets` | F | Chunk data; mesher (static, thread-safe). |
| `UDescentOreSubsystem` | `UWorldSubsystem` | Deposit state (mined counters), crystals, loose ore chunks (instanced). Sim. |
| `ADescentCarrier` | A | CANTICLE. Root + components below. One per world. |
| `UCarrierHelmComponent` | U | Rigid-body state and `CarrierPhysics` (§3.6). Sim. |
| `UCarrierBlockoutComponent` | U | Builds hull and interior from `FCarrierLayout` into procedural mesh components with convex collision (§3.2). |
| `UCarrierCarouselComponent` | U | Carousel angle, cradles, launch/dock paths (§3.5). Sim. |
| `UCarrierSystemsComponent` | U | Hull %, power %, biomass reserve, room lights, flicker. Sim. |
| `FCarrierLayout` | F, static tables | Decks, rooms, doors, windows, stairs, anchors, keep-out zones, pipe routes (§3.3). |
| `AKazahTender` (exists, extend) | A | The Tender. Parts from the Kazah manifest + components below (§4). |
| `UTenderFlightComponent` | U | Flight model, collision, energy, crush (§4.3). Sim. |
| `UTenderToolComponent` | U | The single drill-plus-suction tool (§4.5). Sim. |
| `UTenderHoldComponent` | U | Ore hold and bio-tank contents, in arrival order (§4.6). |
| `ADescentCharacter` | `ACharacter` | The player on foot and swimming. Camera, flashlight, carry point. |
| `UDescentCharacterMovement` | `UCharacterMovementComponent` | Walking on the moving carrier; custom swim mode (§5.2–5.3). Engine tick. |
| `ADescentPlayerController` | `APlayerController` | Mode state machine (§5.6), Enhanced Input (§5.7), view targets. |
| `UDescentInteractionComponent` | U (on character) | Focus search and `E` (§5.4). |
| `UDescentCarryComponent` | U (on character) | Carrying an ore box (§5.5). |
| `UDescentVitalsComponent` | U (on character) | Nutrition, O₂, health, death/respawn (§5.8). Sim. |
| `UDescentInventoryComponent` | U (on character) | 24 slots, hotbar 5, equipment (§6.1). |
| `IDescentInteractable` | interface | `GetPrompt`, `GetFocusPoint`, `GetRange`, `GetMinDot`, `CanUse`, `Use(Character)`. |
| `UDescentStoreSubsystem` | `UWorldSubsystem` | Carrier storage (items), cargo ledger over ore boxes, upgrades `FUpgradeState`, debt. |
| `UDescentCargoSubsystem` | `UWorldSubsystem` | Unload jobs, pipe network, packer, box sockets, robot-arm scheduling (§6.3–6.6). Sim. |
| `ADescentOreBox` | A | A physical ore box: type, count ≤ 6 (§6.4). |
| `ADescentPlaceable` | A, base | Anything placed with build mode (§6.10). Subclasses: `APlaceableFabricator`, `APlaceableRefinery`, `APlaceableLocker`, `APlaceableBoxRack`, `APlaceableRobotArm`, `APlaceableLight`, `APlaceableFurniture`. |
| `ADescentFixture` | A, base | Fixed carrier stations that are *not* placeable: `AFixtureHelm`, `AFixtureNutrientPort`, `AFixtureVat`, `AFixturePacker`, `AFixtureTerminal`, `AFixtureBed`, `AFixtureCarouselConsole`, `AFixtureChartTable`, `AFixtureLadder`. |
| `UDescentBuildComponent` | U (on character) | Build / placement mode (§6.10). |
| `UDescentFaunaSubsystem` | `UWorldSubsystem` | Fish schools, jellies, polyps; biomass capture; hull exclusion (§6.9). Sim. |
| `ADescentEnvironment` | A | Height fog, unbound post-process component, surface sun, material parameter collection writes (§7). Late step. |
| `UDescentLightPool` | U (on environment) | Pool of 24 shadowless point lights for flares, glows, bioluminescence (§7.5). |
| `UDescentMarineSnowComponent` | `UInstancedStaticMeshComponent` | Marine snow (§7.7). |
| `UDescentSonarSubsystem`, `UDescentSurveyMap` | `UWorldSubsystem` | §8.1–8.2. Sim. |
| `UDescentHorrorSubsystem`, `ADescentLeviathan`, `ADescentBeacon` | | §8.3. Sim. |
| `UDescentAudioSubsystem` | `UWorldSubsystem` | §8.4. Late step. |
| `FNeuStyle`, `SNeuPanel`, `SNeuButton`, `SNeuGauge`, `SNeuWindow`, `SDescentHUD`, `SDescentDash`, `SCargoDisplay`, `SSurveyMap`, … | S | §8.5. |
| `UDescentDebugSubsystem`, `FDescentStateRegistry`, `FDescentScenario*` (exist) | | §9. |

Static data lives in code, not in assets: `DescentItems.cpp` (items, recipes), `CarrierLayout.cpp`,
`DescentWorldDef.cpp`, `DescentTuning.h` (every constant in this document, grouped in namespaces
`Descent::Tune::Carrier`, `::Tender`, `::Player`, `::Econ`, `::Look`, …). User-tunable values are also console
variables (`descent.Look.Bloom`, `descent.Player.NutritionMinutes`, `descent.Terrain.StreamRadius`).

### 1.4 Ownership and tick order

**Rule: anything that changes game state is stepped by `UDescentSimSubsystem`, in one fixed order, with one `dt`.**
Actor and component `Tick` are for cosmetics only (rotor spin, lamp blink, widget redraw). This is the Unreal
form of v2's single `update(dt)` and it is what makes `Descent.Sim.FastForward` (§9.2) and the headless route
tests possible.

`UDescentSimSubsystem` registers two `FTickFunction`s on the persistent level (`FTickFunction::RegisterTickFunction`,
`Engine/Classes/Engine/EngineBaseTypes.h:341`):

- **`SimTick` in `TG_PrePhysics`**: calls `Step(min(DeltaSeconds, 0.05))`. `ADescentCharacter` adds it as a tick
  prerequisite (`FTickFunction::AddPrerequisite`, same header `:426`), so the carrier has already moved when the
  character's movement component runs.
- **`LateTick` in `TG_PostUpdateWork`** (after the camera manager has updated): calls `LateStep(dt)`.

`Step(dt)` order (v2 `13_main.js update()` re-ordered for Unreal):

| # | Step | Owner |
|---|---|---|
| 1 | Sim clock; latch intents from input or from debug commands (§5.7) | Sim, PlayerController |
| 2 | Carrier: helm intent → `CarrierPhysics` → move actor; sensors at 4 Hz; hull consequences | `UCarrierHelmComponent`, `UCarrierSystemsComponent` |
| 3 | Carousel rotation; launch / dock / board animations | `UCarrierCarouselComponent`, PlayerController |
| 4 | Tenders: flight of the piloted Tender, drift of abandoned ones, collision, energy, crush; docked recharge | `UTenderFlightComponent` |
| 5 | Tender tool: drill (carve + cleanup), suction | `UTenderToolComponent`, Terrain, Ore |
| 6 | Vitals: nutrition, O₂, health, honest void, death timer | `UDescentVitalsComponent` |
| 7 | Terrain: start fill / mesh jobs, synchronous remesh of carved chunks (budget), apply finished jobs (budget) | `UDescentTerrainSubsystem` |
| 8 | Ore: loose chunks, crystals | `UDescentOreSubsystem` |
| 9 | Cargo: unload jobs, pipes, packer, robot arms; refinery; fabricator timers | `UDescentCargoSubsystem`, placeables |
| 10 | Fauna, flora, biomass capture | `UDescentFaunaSubsystem` |
| 11 | Sonar ray budget, contacts; map visits | `UDescentSonarSubsystem`, `UDescentSurveyMap` |
| 12 | Horror director, beacons, ending | `UDescentHorrorSubsystem` |

Then the engine runs `UDescentCharacterMovement` (walking or swimming) in the same tick group.

`LateStep(dt)`: interaction focus → environment (fog, post-process, sun, parameter collection, dry/wet state) →
light pool commit → marine snow → audio parameters → HUD model (10 Hz) → dashboards (8 Hz).

### 1.5 Boot sequence (`ADescentGameMode::StartPlay`)

1. `FDescentWorldDef::Build()` (deterministic, < 200 ms).
2. Spawn `ADescentEnvironment`, `ADescentTerrainActor`, `ADescentCarrier` at the start pose (0, 0, −30), ψ = 0.
3. Spawn three `AKazahTender`s into the carousel cradles; spawn start fixtures and start placeables (§3.4).
4. `UDescentTerrainSubsystem::StreamInitialBlocking(Focus = carrier, Radius = 120 m)` with a `ParallelFor` over
   fill + mesh, then apply all. Target < 3 s.
5. Place the character on the bridge (carrier-local (40.5, 0, 1.5), facing the bow) *(v2)*; mode `Title`, then
   `Foot` on first click (or immediately when a scenario is running).
6. Load the save if `Continue` was chosen (§6.12).

### 1.6 v2 file → Unreal counterpart

| v2 file | Unreal counterpart |
|---|---|
| `00_head.html` (CSS tokens, HUD DOM, overlays) | `UI/NeuStyle.*`, `UI/NeuWidgets.*`, `UI/DescentHUD.*`, `UI/DescentWindows.*` (Slate, §8.5) |
| `01_core.js` (math, datum, noise, renderer, `waterMat`, composer, virtual lights) | `Core/DescentMath.h`, `DescentUnits.h`; `Render/DescentEnvironment.*` + materials made by `Tools/make_materials.py` (§7); `Render/DescentLightPool.*` |
| `02_audio.js` | `Audio/DescentAudio.*` + `Tools/gen_audio.py` (§8.4) |
| `03_world.js` | `World/DescentWorldDef.*`, `World/DescentSDF.*` (§2.2, 2.7–2.9) |
| `04_terrain.js` | `World/DescentTerrainSubsystem.*`, `TerrainChunk.*`, `SurfaceNets.*` (§2.3–2.6) |
| `05_life.js` | `Life/DescentFauna.*`, `Life/DescentFlora.*`, `World/DescentOreSubsystem.*` (loose ore, crystals), `Render/DescentMarineSnow.*`, flares in `Player/` |
| `06_carrier.js` | `Vehicles/DescentCarrier.*`, `CarrierLayout.*`, `CarrierBlockout.*`, `CarrierHelm.*`, `CarrierCarousel.*` (§3) |
| `06_routes.js` | `World/DescentRoutes.*` (waypoints, autopilot, `ClearRoute`) used by tests (§2.10) |
| `07_vehicles.js` | `Vehicles/KazahTender.*`, `TenderFlight.*`, `UI/DescentDash.*` (§4) |
| `08_items.js` | `Systems/DescentItems.*`, `DescentStore.*`, `DescentRefinery.*`, `DescentFabricator.*`, `DescentEconomy.*` (§6) |
| `09_sonar_map.js` | `Sonar/DescentSonar.*`, `Sonar/DescentSurveyMap.*` (§8.1–8.2) |
| `10_player.js` | `Player/*` (§5), `Vehicles/TenderFlight.*`, `TenderTool.*` |
| `11_ui.js` | `UI/DescentHUD.*`, `UI/DescentWindows.*` |
| `12_horror.js` | `Horror/*` (§8.3) |
| `13_main.js` | `Core/DescentSimSubsystem.*`, `Core/DescentGameMode.*`, `Debug/*` |

### 1.7 Engine features relied on (all verified in the 5.8.1 source)

| Feature | Header (under `E:\Tools\UE_5.8\Engine\`) |
|---|---|
| `UProceduralMeshComponent::SetProcMeshSection`, `SetCollisionConvexMeshes` | `Plugins/Runtime/ProceduralMeshComponent/Source/ProceduralMeshComponent/Public/ProceduralMeshComponent.h` |
| `UE::Tasks::Launch` | `Source/Runtime/Core/Public/Tasks/Task.h` |
| Character on a moving base: `bFastAttachedMove`, `bStayBasedInAir`, `bImpartBaseVelocityX/Y/Z`, `PhysCustom`, `UpdateBasedMovement` | `Source/Runtime/Engine/Classes/GameFramework/CharacterMovementComponent.h` |
| Enhanced Input in code: `UInputMappingContext::MapKey`, `AddMappingContext`, `InjectInputForAction` | `Plugins/EnhancedInput/Source/EnhancedInput/Public/InputMappingContext.h`, `EnhancedInputSubsystemInterface.h` |
| `FPostProcessSettings` (bloom, manual exposure), `EBlendableLocation` | `Source/Runtime/Engine/Classes/Engine/Scene.h`, `Classes/Engine/BlendableInterface.h` |
| `UExponentialHeightFogComponent` setters incl. `SetVolumetricFogStartDistance` | `Source/Runtime/Engine/Classes/Components/ExponentialHeightFogComponent.h` |
| Lights: `bUseInverseSquaredFalloff`, `SetLightFalloffExponent`, `SetVolumetricScatteringIntensity` | `Classes/Components/PointLightComponent.h`, `LightComponent.h` |
| Custom depth / stencil per primitive | `Classes/Components/PrimitiveComponent.h` (`SetRenderCustomDepth`, `SetCustomDepthStencilValue`) |
| Instanced meshes with per-instance data | `Classes/Components/InstancedStaticMeshComponent.h` (`SetNumCustomDataFloats`, `SetCustomData`, `BatchUpdateInstancesTransforms`) |
| World-space Slate dashboards | `Source/Runtime/UMG/Public/Components/WidgetComponent.h` (`SetSlateWidget`, `SetDrawSize`, `SetManuallyRedraw`, `RequestRedraw`) |
| Slate drawing | `Source/Runtime/SlateCore/Public/Rendering/DrawElementTypes.h` (`FSlateDrawElement::MakeBox`, `MakeLines`, `MakeCustomVerts`), `Public/Brushes/SlateRoundedBoxBrush.h` |
| Materials by script | `Source/Editor/MaterialEditor/Public/MaterialEditingLibrary.h`; `Runtime/Engine/Public/Materials/MaterialExpressionCustom.h`, `MaterialExpressionPerInstanceCustomData.h`, `MaterialParameterCollection.h` |
| Audio component volume, pitch, low-pass | `Classes/Components/AudioComponent.h` |
| Collision queries and penetration | `Classes/Engine/World.h` (`SweepSingleByChannel`, `OverlapMultiByChannel`), `PrimitiveComponent.h` (`ComputePenetration`) |
| Save game, compression | `Classes/Kismet/GameplayStatics.h`, `Runtime/Core/Public/Misc/Compression.h` |
| Runtime textures | `Classes/Engine/Texture2D.h` (`CreateTransient`, `UpdateTextureRegions`) |
| Fixed time step for runs | `-UseFixedTimeStep -FPS=30` (`Runtime/Launch/Private/LaunchEngineLoop.cpp`) |

---

## 2. Terrain and world

### 2.1 Decisions

| Decision | Choice | Why |
|---|---|---|
| World representation | Analytic SDF (`FDescentSDF::GenRaw`) sampled into 20 m chunks of 1.25 m voxels, edited by carving. Same as v2. | Proven; carving, collision, sonar and the map all read one field. |
| Mesher | Surface nets with gradient normals, on worker threads. Port of `04_terrain.js meshChunk`. | Clean carving (V7b). |
| Mesh component | One `UProceduralMeshComponent` per meshed chunk, pooled, fed with `SetProcMeshSection` from a section built on a worker. | Vertex format (position, normal, colour, UV0–UV3) maps 1:1; no intermediate mesh structure; no asset needed. |
| Terrain physics collision | **None.** Chunks never cook collision (`bEnableCollision = false`, component `NoCollision`). Every interaction with rock queries the density field. | Nothing walks on rock: the player is on foot only inside the carrier. Tender, swimmer, carrier, loose ore, fish, flares and sonar all used the density field in v2. It removes trimesh cooking, the largest cost of runtime terrain in Unreal. |
| World bounds | **None.** The chunk map is a hash map keyed by integer chunk coordinates; chunks are classified lazily. Outside the designed voids the SDF is solid rock. | U7: no clamp exists anywhere. See §2.11 for how the playable space ends. |

### 2.2 The density function

`double FDescentSDF::GenRaw(const FVector& Pm, const FPrimList& L)`: signed, **positive = rock, negative = water**,
approximately metres near surfaces. `Gen = clamp(GenRaw, −4, +4)` (`CLAMP_D = 4`). Port of `03_world.js genRaw`
with the axes of §0.

```
open = +1e9; obig = +1e9
for seg in L.Segs:  d = SegDistR(seg, P);  if seg.bBig: obig = min(obig, d) else open = min(open, d)
if L.bCanyon:
    fl  = Zf(X) + 4*sin(0.07*Y - 0.02*X) + 3*sin(0.045*X)
    hw  = 70 + 0.18*max(0, Z - fl)
    cyn = max(|Y - Yc(X)| - hw,  fl - Z,  X - 850,  -250 - X)
    cyn = min(cyn, (40 + 3*sin(0.03*Y)*cos(0.025*X)) - Z)        // everything above the rim is open sea
    open = smin(open, cyn, 10)
for c in L.Chambers:  open = smin(open, (length((P - c.C)/c.R) - 1) * min(c.R.x, c.R.y, c.R.z), c.K)
for w in L.Wells:     obig = smin(obig, max(hypot(X-w.X, Y-w.Y) - w.R,  Z - w.Z1,  w.Z0 - Z), 12)
if L.bAbyss:          open = smin(open, AbyssSDF(P), 14)
for p in L.Pores:     open = smin(open, length(P - p.C) - p.R, 2.6)
for z in L.Sponges:   open = smin(open, SpongeSDF(z, P), 4)
n1 = noise3(0.02*X, 0.02*Y, 0.024*Z);  n2 = noise3(0.07*X + 11, 0.07*Y, 0.07*Z)
rock = open + 5.5*n1 + 1.4*n2 + (Z < -330 ? 1.8*noiseB(0.05*P) : 0)
if obig < 1e8:  rb = obig + 2.2*n1 + 0.8*n2;  rock = (rock < 1e8) ? smin(rock, rb, 8) : rb   // carrier voids: low noise
for s in L.Shelves:   rock = max(rock, ShelfRock(s, P, 1.4*noiseB(0.09*P) + 0.8*n2))
for p in L.Pinches:   rock = max(rock, PinchRock(p, P) + 0.7*n2)
for r in L.Rings:     rock = max(rock, RingRock(r, P) + 0.7*n2)
return rock
```

`Yc(X) = 30·sin(0.006·X) + 12·sin(0.017·X)`; `Zf(X) = lerp(−120, −260, smooth(−100, 800, X))`.
`noise3 = makeNoise3(20193)`, `noiseB = makeNoise3(771)`.

Primitive functions (ported from `03_world.js:129–165`, axes converted):

- `SegDistR(seg, P)`: distance to the segment minus the radius interpolated along it.
- `ShelfRock(s, P, noise) = min( s.T + noise − |Z − s.Zc|,  SlotSDF(s, X, Y),  s.Rclip − hypot(X−s.X, Y−s.Y),  min over crack segments (SegDist − s.CrackR) )`.
  `SlotSDF` is a stadium: `a` = offset along the slot axis, `o` = across; `al = clamp(a, −(Half−W), Half−W)`;
  `hypot(a − al, o) − W`.
- `PinchRock(p, P) = min( p.Half − |along|,  (hypot(u/p.Ax, v/p.Ay) − 1)·min(p.Ax, p.Ay),  (TubeR + 14) − hypot(u, v) )`
  with `along`, `u` (horizontal, across the axis) and `v` (up) the coordinates of `P − p.C` in the pinch frame.
- `RingRock(r, P) = min( r.Half − |Z − r.Zc|,  hypot(X−w.X, Y−w.Y) − r.RInner,  (w.R + 12) − hypot(…) )`.
- `AbyssSDF(P) = max( hypot(X−1250, Y+300) − Rz − 5·sin(0.05·Z + 0.04·Y),  Z + 1400,  −1640 − Z )`,
  `Rz = lerp(70, 6, smooth(−1400, −1640, Z))`.
- `SpongeSDF(zone, P) = max( (max(|nA|, |nB|) − 0.085)·28,  BoxSDF(zone.Box, P) + 12 )` with
  `nA = noise3(0.016·P + 37)`, `nB = noiseB(0.016·P − 53)`. Two ridged noises intersected give worm-like
  tunnels 5–9 m wide.

`Gather(Center, Radius, FPrimList&)` collects the primitives that can affect a region (port of `gatherLists`,
same margins: segment `+10`, chamber `+16`, pore `+8`, well `+14`, shelf `+8/+10`, pinch `+48`). Because the
new world has about 600 segments and 900 pores, `FDescentWorldDef` keeps a uniform 80 m bucket grid of
primitive indices built once in `Build()`; `Gather` reads the buckets it overlaps.

`GenQuick(P)` (for points whose chunk has no data) caches one gathered list per 40 m cell in an LRU map of
4,096 entries.

### 2.3 Chunks

| Constant | Value |
|---|---|
| Voxel size `VS` | 1.25 m *(v2)* |
| Core samples per axis `CN` | 16 → chunk size `CS` = 20 m *(v2)* |
| Padding | 2 samples each side → `P = CN + 4 = 20`, `P³ = 8,000` samples *(v2)* |
| Density storage | `float[8000]` + `uint8 Cut[8000]` = 40 KB per filled chunk |
| Chunk key | `FIntVector C`, chunk covers `[C·CS, (C+1)·CS)`; sample `(i, j, k)` is at `((C·CN − 2) + (i, j, k))·VS` |

States: `Unclassified → Uniform(±4) | Candidate`; `Candidate → Filling → Mixed | Empty`; `Mixed → Meshing → Meshed`.
Flags: `bModified` (carved at least once; data is then kept for ever and saved), `Version` (incremented by every
edit; a job result with a stale version is dropped and re-queued).

Classification (lazy, on first touch): `v = GenRaw(ChunkCentre)`; `|v| > CS·0.87 + 10` → `Uniform(sign v)`,
else `Candidate`. Chunks that intersect a sponge zone box grown by 12 m are always `Candidate` (the sponge is
not a distance field).

### 2.4 Meshing (worker thread)

Port `04_terrain.js:104–167` exactly: cells `1..CN+1` on each axis; one vertex per mixed cell at the mean of
its edge crossings; normal = negated, normalised trilinear blend of the eight corner central-difference
gradients; one quad per sign change along +x, +y, +z for samples `2..CN+1`. The 2-sample padding makes
neighbouring chunks produce identical border vertices, so there are no seams as long as every copy of a
sample is edited together (§2.5).

Output: one `FProcMeshSection` (`ProcVertexBuffer`, `ProcIndexBuffer`, `SectionLocalBox`, `bEnableCollision = false`):

| Vertex field | Content |
|---|---|
| `Position` | chunk-local uu (component sits at the chunk origin) |
| `Normal` | gradient normal; `Tangent` = any unit vector perpendicular to it |
| `Color.rgb` | `RockColor(P, N)` below, sRGB-encoded; `Color.a` = cut amount (max `Cut` of the 8 corners / 255) |
| `UV0` | `(OreType 0..3, OreStrength 0..1)` from `DepositAt` (0 = none, 1 ferrite, 2 cobalt, 3 pearl); strength = `min(1, 1.6·k)`; zero when the deposit is mined out |
| `UV1` | `(Basalt 0..1, 0)` = `saturate(ClaimDist(P) / 40)` (§2.11) |

`RockColor` (palette *(v2)*; blend heights *(new)*):

```
tBase #3a3d40  tDark #222428  tSilt #6b6252  tRust #6a3e2a  tBio #3c5a44
hBase #5a4232  hDark #2e231c  hCrust #9a9282   sBase #2a2432  sBand #4a3f58
wH = smooth(-330,-400,Z);  wS = smooth(-930,-1000,Z)
n = noise3(.05X,.05Y,.08Z);  m = noiseB(.018X,.018Y,.03Z);  up = smooth(.35,.85,N.z)
c = lerp(tBase,tDark,smooth(-.2,.6,n));  c = lerp(c,tRust,.6*smooth(.45,.7,m));  c = lerp(c,tSilt,.85*up*smooth(-.4,.3,n))
if Z > -110: c = lerp(c,tBio,.6*up*smooth(0,.6,m)*smooth(-110,-40,Z))
if wH > 0:   c = lerp(c, lerp(lerp(hBase,hDark,smooth(-.3,.5,n)), hCrust, .5*smooth(.5,.8,m)+.25*up), wH)
if wS > 0:   c = lerp(c, lerp(sBase,sBand,.5+.5*sin(.8Z+3n)), wS)
```

Triangle winding: Unreal is left-handed; after the port take the screenshot `terrain_basic_lit` (§10 M1). If the
rock is lit from the inside, swap two indices in `Quad()` once.

### 2.5 Carving, cleanup, queries (game thread)

`int32 Carve(Centre, Radius, Rate, Dt, bIgnoreHardness = false)`: port of `04_terrain.js carve`:

- For every sample within `Radius + 2`: `target = dist − Radius`; `nv = smin(old, target, 1.6)`;
  `nv = max(nv, old − MaxDrop)`, `MaxDrop = Rate·Dt / Hardness(P)`; `nv = max(nv, −4)`; write if `nv < old`.
- `Cut = max(Cut, 200)` where `dist < Radius + 0.6`.
- Every chunk that holds a copy of the sample (core or padding) is written in the same call. Only the chunk
  whose **core** owns the sample counts removal and ore.
- A sample that goes from rock to water counts as removed. If it lies in a deposit that is not mined out:
  `Deposit.Removed++`; **every 6 removed core samples → `Mined++` and one loose ore chunk** *(v2)* via
  `OnOreFreed(Deposit, P)`.
- Samples with `ClaimDist(P) > 40` are never written (dense basalt, §2.11).
- Returns removed count. Touched chunks: `bModified = true`, `Version++`, added to the dirty set.

`Hardness(P)` *(new bands)*: 1.0 for Z > −260; 1.2 to −560; 1.5 to −960; 1.9 below; multiplied by
`1 + 7·saturate(ClaimDist(P)/40)` in the basalt ramp.

`CleanupFloating(Centre, Radius)`: port of `cleanupFloating`: region half-size `ceil((Radius + 4)/VS)` samples;
flood-fill rock from the region boundary; any rock sample not reached is set to −0.8 and reported through
`OnRockFreed`. The tool calls it every 0.35 s while drilling with `Radius = DrillR + 1.5`, and once with
`DrillR + 2` when drilling stops *(v2)*.

Query API (metres, game thread only; chunk pointer of the last query is cached):

```cpp
double  Density(const FVector& Pm) const;                       // trilinear in chunk data; GenQuick clamp when no data; ±4 for Uniform
FVector Gradient(const FVector& Pm, double H = 0.6) const;      // normalised, points INTO rock; (0,0,1) if degenerate
double  Raycast(const FVector& Om, const FVector& Dir, double MaxD, double MinStep = 0.3) const;  // sphere trace + 7 bisections; −1 if no hit; 0 if origin in rock
bool    PushOutSphere(FVector& InOutCentreM, double RadiusM, FVector* OutNormal = nullptr) const; // pen = Radius + Density; move by −Gradient·pen
```

Step rule in `Raycast`: `t += max(MinStep, −0.85·d)` *(v2)*.

### 2.6 Streaming, threading, budgets

| Item | Value |
|---|---|
| Foci | camera; the carrier if it is more than 70 m from the camera; the piloted Tender when the camera is not in it |
| Load radius `R` / unload radius `RU` | 160 m / 200 m (cvar `descent.Terrain.StreamRadius`; low preset 120 / 150) |
| Queue rebuild | every 0.5 s or when the first focus has moved 10 m; nearest first |
| Fill job (worker) | `Gather` + 8,000 `Gen` samples; returns `Mixed` or `Empty` (an empty chunk frees its data until edited). Target ≤ 0.6 ms. |
| Mesh job (worker) | gets a **copy** of `Data` and `Cut` (40 KB memcpy on the game thread) plus the deposit list; returns the section. Target ≤ 0.3 ms. |
| Launching | `UE::Tasks::Launch`; at most 12 jobs in flight; results through a multi-producer queue |
| Apply (game thread) | at most 1.5 ms per frame: take a pooled component, `SetProcMeshSection(0, Section)`, set its location; drop results whose `Version` is stale |
| Carved chunks | remeshed **synchronously** on the game thread, nearest to the camera first, 2.5 ms per frame, each chunk at most once per 3 frames; the rest goes to the async queue |
| Unload | every 0.33 s: a meshed chunk farther than `RU` from every focus returns its component to the pool; unmodified chunks also free `Data` |
| While `Filling` | queries fall back to `GenQuick`; a carve that hits a chunk without data fills it synchronously first |
| Memory cap | 4,000 filled chunks (160 MB). Modified chunks are never evicted. |
| Render budget | ≤ 900 meshed chunks, ≤ 900k terrain triangles at `R` = 160 m. Dump both in the `terrain` state section. |

Chunk components: `CastShadow = true`, `bAffectDistanceFieldLighting = false`, material `MI_Terrain` (§7.8), no
collision, no navigation.

### 2.7 The new world: extents and strata (U8)

The designed region ("the claim") is the box **X −330..1,560, Y −980..480, Z −1,700..+60**: 1,890 × 1,460 ×
1,760 m, about 19 times the volume of v2 (600 × 560 × 700 m). The Tender's descent range goes from 500 m (v2)
to 1,400 m. Voids are 2–3 times larger in every dimension (the Great Void is 720 × 640 × 280 m against v2's
320 × 230 × 104 m).

| Stratum | Z (m) | Depth (m) | Character | HUD band name | Hardness | Tender rating needed |
|---|---|---|---|---|---|---|
| Open sea above the rim | > +40 | < 1,740 | the Shear (§2.11) | — | — | — |
| S0 The Throat (canyon) | +40 … −260 | 1,740–2,040 | black basalt, silt, last surface light, light shafts | THE THROAT; below 2,040 m THROAT FLOOR | 1.0 | base 2,300 |
| S1 Upper Honeycomb | −260 … −560 | 2,040–2,340 | porous rock, first voids, ferrite, some cobalt | THE HONEYCOMB (from 2,150 m) | 1.2 | base 2,300 |
| S2 The Great Void | −560 … −960 | 2,340–2,740 | kilometre-scale dark, cobalt, first pearl | THE HONEYCOMB | 1.5 | Mk I 2,700 |
| S3 Seam intrusion | −960 … −1,420 | 2,740–3,200 | laminated purple rock, pearl | HONEYCOMB · SEAM INTRUSION (from 2,700 m) | 1.9 | Mk II 3,150 |
| Abyss | < −1,420 | > 3,200 | the shaft below the goal; the Floor's glow | BELOW SURVEY (from 3,180 m) | 1.9 | none sold |

Surface light *(v2)*: `L(Z) = clamp(exp(−(40 − Z)/68), 0, 1)` (0.36 at the start, 0.05 at Z −165, < 0.01 below −300).
Water temperature: `4.2 + 9·clamp((Depth − 1740)/1400, 0, 1) + (Depth > 2300 ? 6 : 0)` °C.
Carrier start: (0, 0, −30), ψ = 0, depth 1,810 m *(v2)*. **Goal:** bring the carrier to the Seam Gallery,
anchor depth 3,105 m (Z −1,325).

### 2.8 The carrier route network

The CANTICLE is 122 m long (X −62..+60 with the stern shroud), 30.2 m wide with pods, 31.1 m tall (keel −12.9,
sail top +18.2). Its circumscribed radius in plan is 61.8 m. It turns only in open water, descends only by
ballast, and pitches at most ±10°.

Fit rules that every carrier-scale void obeys (after the chokes are dug):

| Void kind | Rule | Margin |
|---|---|---|
| Well (vertical cylinder) | radius **80 m** | 18 m around the hull's circumscribed circle, minus wall noise ≤ 3 m |
| Gallery (tube) | radius **34 m**, slope ≤ 9.5°, bend centreline radius ≥ 150 m (sagitta of a 120 m chord: 12 m) | sideways: 15.1 m (pods) + 12 m (bend) + 3 m (noise) = 30.1 m ≤ 34 m; upward: 18.2 m (sail) + 3 m = 21.2 m ≤ 34 m |
| Chamber | every semi-axis ≥ 60 m in plan where the carrier must turn | — |
| Wall noise on carrier voids | ±2.2 m (n1) ±0.8 m (n2) instead of ±5.5 / ±1.4 | keeps clearances honest |

Chambers (ellipsoids: centre, semi-axes along X, Y, Z, blend k):

| Id | Name | Centre | Semi-axes | k | Notes |
|---|---|---|---|---|---|
| H1 | HONEYCOMB I | (400, −470, −200) | (150, 130, 62) | 10 | junction, ore-rich, pores |
| H2 | THE GREAT VOID | (640, −230, −700) | (360, 320, 140) | 12 | leviathan zone; KILO-7 station on its floor |
| H3 | THE UNDERCROFT | (900, −420, −1,020) | (260, 220, 95) | 12 | wreck of the *ANTIPHON* |
| G | SEAM GALLERY (**goal**) | (1,250, −300, −1,330) | (300, 240, 90) | 12 | ending: carrier origin inside the ellipsoid scaled 0.7 and Z ≤ −1,290 |
| ABYSS | — | axis (1,250, −300) | r 70 → 6 | 14 | Z −1,400 … −1,640, closed at the bottom |

Wells (radius 80):

| Id | Name | Axis (X, Y) | Z top … bottom | Joins |
|---|---|---|---|---|
| WA | THE THROAT WELL | (760, −25) | −250 … −665 | canyon floor → Great Void roof |
| WB | THE BORE | (430, −420) | −200 … −700 | H1 → Great Void south-west flank |
| WC | THE DROP | (820, −330) | −800 … −950 | Great Void floor → Undercroft roof |
| WD | THE GULLET | (1,060, −380) | −1,080 … −1,280 | Undercroft floor → Seam Gallery roof |

Galleries (radius 34, low noise; turtle path: start point, heading ψ, pitch, then steps `s L` = straight L metres,
`t Δψ R` = turn by Δψ degrees on centreline radius R; one waypoint every ≤ 8 m, port of `turtlePath`):

| Id | Name | Start | ψ, pitch | Steps | Length | Ends at |
|---|---|---|---|---|---|---|
| B | THE LONG GALLERY | (−20, −62, −105) | −75°, −7° | s 120 · t +35 R240 · s 140 · t +20 R240 · s 60 | 550 m | ≈ (322, −449, −172), inside H1 |
| S | THE HAIRPIN | (900, −230, −765) | 0°, −9.5° | s 380 · t −180 R150 · s 301 | 1,152 m | ≈ (978, −526, −955), inside H3 |

Chokes (rock added back with `max`; each one stops the carrier and lets a Tender through):

| Id | Name | Where | Geometry | What the carrier needs | Dig |
|---|---|---|---|---|---|
| SA | THROAT COLLAPSE | shelf in WA, Zc −350 | half-thickness 3, clip radius 88; slot along ψ 0°: half-length 52, half-width 14; Tender crack r 3.4 through (760, 35, −339) → (764, 39, −350) → (758, 43, −361) | slot ≥ 129 × 34 m (half-length 64.5, half-width 17) | ≈ 8,400 m³ |
| SC | DROP COLLAPSE | shelf in WC, Zc −880 | half-thickness 3, clip 88; slot along ψ −79°: half-length 50, half-width 13; crack r 3.3 through (881, −318, −869) → (885, −322, −880) → (879, −326, −891) | same | ≈ 10,100 m³ |
| NEEDLE | THE NEEDLE | pinch in B at s = 330 m | half-length 7; opening semi-axes 26 (horizontal) × 15 (vertical) | vertical semi-axis ≥ 18.5 m | ≈ 4,000 m³ |
| HTHROAT | HAIRPIN THROAT | pinch in S at s = 950 m (straight return leg) | half-length 6; opening semi-axes 12 × 12 | semi-axes ≥ 17 (horizontal) × 18.5 (vertical) | ≈ 6,400 m³ |
| BRING | THE BORE PINCH | ring in WB, Zc −450 | half-height 7, inner radius 56 | two notches, for bow and stern: clear radius ≥ 64 m along the hull axis, 34 m wide | ≈ 4,500 m³ |
| DRING | THE GULLET RING | ring in WD, Zc −1,180 | half-height 7, inner radius 48 | same notches | ≈ 9,500 m³ |

Dig volumes are the rock between the natural opening and the hull's swept outline plus 1.5 m. At the Mk I
drill's ≈ 54 m³/s (v2 measurement) a choke takes 2–3 minutes of drilling, i.e. two or three Tender charges.

Carrier routes to the goal. Every route needs digging at each tier. The two ways into the Great Void cost about
the same rock (SA ≈ 8,400 m³ against NEEDLE + BRING ≈ 8,500 m³): the Throat route is short, the Long Gallery
route is longer but passes the ore of Honeycomb I. The two ways out of it (SC, or HTHROAT) differ the same way.

1. **THROAT ROUTE.** Canyon → WA (dig SA) → Great Void → WC (dig SC) → Undercroft → WD (dig DRING) → Seam Gallery.
2. **LONG GALLERY ROUTE.** Canyon → gallery B (dig NEEDLE) → H1 → WB (dig BRING) → Great Void → then as route 1.
3. **HAIRPIN ROUTE.** Route 1 or 2 to the Great Void → gallery S (dig HTHROAT) → Undercroft → WD (dig DRING) → Seam Gallery.

Canyon: X −250..850, 173 m wide at the carrier's start height, floor Z −120 falling to −260; open to the sea
above Z +40 (formula in §2.2).

### 2.9 Tender-only content, landmarks and procedural variation

Designed Tender tubes (Catmull-Rom through the points, radius interpolated with smoothstep; one segment per
≤ 3 m; port of the non-turtle branch of `TUBE_DEFS`). Points are (X, Y, Z, radius):

| Id | Name | Points | Purpose |
|---|---|---|---|
| E1 | EAST SPUR | (30, 78, −62, 12) (45, 125, −72, 10) (60, 155, −78, 9) (68, 172, −84, 12) | ore dead end near the start |
| E2 | WEST SPUR | (70, −45, −95, 11) (85, −115, −104, 9) (105, −140, −108, 9) | ore dead end |
| C | WRECK HOLLOW | (260, 80, −165, 18) (285, 150, −178, 18) (310, 200, −190, 17) (330, 235, −200, 22) | leads to chamber DEAD |
| X | THE CRACK | (375, 280, −208, 3.6) (392, 300, −214, 3.3) (410, 322, −224, 3.4) (424, 340, −232, 4.2) | leads to the honest void |
| D | THE CRAWL | (450, −40, −210, 5.5) (440, −130, −226, 4.6) (455, −210, −218, 5.0) (430, −290, −208, 5.2) (415, −345, −200, 6.5) | Tender shortcut canyon → H1 |
| LG | GROTTO PASSAGE | (620, 40, −240, 9) (650, 110, −252, 8) (670, 160, −262, 10) | leads to the Lantern Grotto |
| CH | THE CHIMNEYS | (330, −520, −245, 6) (318, −535, −380, 5) (345, −510, −500, 5.5) (372, −478, −560, 6) | H1 floor → the Bore below its pinch |
| E3 | BLIND GALLERY | (700, 60, −705, 14) (735, 120, −712, 12) (760, 165, −716, 11) | dead end off the Great Void, ore |
| SV | SIEVE MOUTH | (470, −450, −770, 8) (440, −530, −795, 7) (430, −620, −820, 9) | Great Void → the Sieve |
| SD | SIEVE DRAIN | (640, −600, −1,000, 7) (720, −540, −1,020, 8) | the Sieve → Undercroft |
| UP | THE UNDERPASS | (1,080, −320, −1,062, 7) (1,160, −262, −1,140, 6) (1,225, −232, −1,215, 6) (1,258, −240, −1,262, 8) | Undercroft → Seam Gallery, Tender only |

Side chambers:

| Id | Name | Centre | Semi-axes | k | Notes |
|---|---|---|---|---|---|
| DEAD | WRECK HOLLOW | (345, 250, −204) | (46, 40, 30) | 8 | derelict Tender at (355, 262, −226), 2193 survey probe at (338, 240, −226), beacons b1, b2 |
| LANTERN | LANTERN GROTTO | (690, 205, −268) | (60, 55, 34) | 8 | dense bioluminescent polyps and lanternfish: the first reliable biomass (U3) |
| HONEST | HONEST VOID | (436, 356, −236) | (26, 26, 20) | 5 | full pressure: 14 HP/s to a Tender, 25 health/s to a swimmer |
| HONEST2 | HONEST VOID II | (520, −760, −900) | (30, 30, 22) | 5 | inside the Sieve; the sponge may open into it |

Sponge zone **THE SIEVE**: box X 300..760, Y −900..−560, Z −1,010..−790 (formula in §2.2). A Tender-only maze
between the Great Void and the Undercroft, pearl-rich, needs the Mk I rating to enter and Mk II for its lower half.

Landmarks (blockout meshes built in code, each a class under `Horror/` or `Life/`):

| Landmark | Where | What |
|---|---|---|
| Derelict BT-01 and survey probe HDR-01 | Wreck Hollow | a dark Kazah hull without lights; a 3.2 m rusted probe |
| KILO-7 depth station (gone quiet) | Great Void floor (560, −330, −826) | three 6 m cylinders, a docking ring, dead lamps, one red beacon still blinking (b6) |
| *ANTIPHON*, a Pilgrim-class hull | Undercroft floor (980, −520, −1,105) | a 60 m hull broken in two, a carrier that came before you (b7) |
| The Floor's glow | below the Abyss | no geometry: a magenta term in the water colour for downward view directions (§7.2), pulsing with the heartbeat |

Procedural variation, generated once in `FDescentWorldDef::Build()` from fixed seeds, so every run and every
test sees the same world:

| Layer | Seed | Rule |
|---|---|---|
| Wall noise | 20193, 771 | §2.2; the craggy look of all walls |
| Pores | 99 | 900 spheres, radius 2.5–10.5, on the walls of H1, H2, H3, G and of Tender tubes below Z −330 (v2 placement: point on the surface + `radius·(0.1..0.8)` outward) |
| Worm tunnels | 5150 | 36 random-walk tubes: start from a random wall point of H1/H2/H3/G/DEAD/LANTERN (march to the wall, then inward along the normal), radius 3–6 m, 60–220 m long in 8 m steps, heading jitter ±25° and pitch jitter ±15° per step; 40% end in a pocket chamber (semi-axes 8–16 m) |
| Deposits | 4242 | §2.12 |
| Flora, polyps, jellies, school homes | 12, 13 | §6.9 |

**Rejection rule for every procedural void (pores, worms, pockets, sponge):** it is discarded (or, for the
sponge, masked with `max(SpongeSDF, 30 − d)`) if it comes within 30 m + its own radius of any well or gallery
axis (`nearCarrierRoute` in v2). Designed landmarks and chokes therefore always win over procedural content,
and no procedural void can open a carrier-sized bypass around a choke. Chokes are applied last with `max`.

Dead-contractor beacons (range 24 m; text typed out and cut with `[SIGNAL LOST]`). b1–b5 keep the v2 texts
(`03_world.js:273–279`), with "Spiral"/"Hairpin" wording as in the code:

| Id | Name | Position | Text |
|---|---|---|---|
| b1 | CONTRACTOR H-19877 | (350, 255, −222) | v2 b1 |
| b2 | SURVEY PROBE 2193 | (338, 240, −224) | v2 b2 |
| b3 | CONTRACTOR H-20114 | (448, −175, −222) | v2 b3 |
| b4 | CONTRACTOR H-18830 | 12 m before HTHROAT on gallery S | v2 b4 |
| b5 | CONTRACTOR H-20390 | (820, −330, −872) | v2 b5 |
| b6 | DEPTH STATION KILO-7 | (560, −330, −826) | "KILO-7 automatic. Station population: zero. Last docking: four hundred and eleven days. Fuel, air and trade remain available to contract holders. Please do not attempt to answer the knocking on the lower hatch. Tethys reminds you that the knocking is" |
| b7 | PILGRIM-CLASS *ANTIPHON* | (980, −520, −1,105) | "ANTIPHON carrier log. We cut the Drop wide enough and she went through like a hymn. Hull at sixty percent. The crew wants to hold here but the stratum is right under us, I can see the well. Something came up it an hour ago and has not gone back down. It is still under the" |
| b8 | CONTRACTOR H-17002 | (500, −740, −895) | "The Sieve is all pearl. I have a full hold and I cannot find the way I came in. The sonar says there is a big room behind this wall, pressure reads wrong, reads honest. If I cut through I can use it to turn around. Cutting now. The wall is" |

### 2.10 Route data for tests (`World/DescentRoutes.*`)

Port `06_routes.js` (waypoints, `apControl` autopilot, `sweepCarve`, `clearRoute`). Waypoints `(X, Y, Z, speed,
heading or none, hold)`:

- Common tail `T`: (820, −330, −740, 0.9) · hold ψ −79° · (820, −330, −990, 0) · turn ψ −12° · (1,060, −380, −1,040, 0.9) · hold · (1,060, −380, −1,310, 0) · (1,200, −320, −1,325, 0.5) **GOAL**.
- **R1**: canyon (0, 0, −30) → (600, −20, −60, 1.6) → (760, −25, −200, 0.9) · hold ψ 0° · (760, −25, −640, 0) · turn ψ −79° · `T`.
- **R2**: (−20, −30, −105, 1.2) · turn ψ −75° · `galleryPts(B, every 30 m)` · (430, −420, −200, 0.5) · hold · (430, −420, −680, 0) · turn ψ 13° · `T`.
- **R3**: R1 to (760, −25, −640) · turn ψ −56° · (900, −230, −765, 0.9) · hold ψ 0° · `galleryPts(S, every 30 m)` · turn ψ −12° · then `T` from (1,060, −380, −1,040).

`ClearRoute(n)` sweeps the hull's sample points (+1.6 m) along the route poses and carves 6.5 m spheres where
rock is within 6 m (`sweepCarve`), i.e. it does what the player does with a Tender.

### 2.11 How the playable space ends (U7)

There is **no position clamp in any code path**. The v2 clamps (`10_player.js:390–391`, `06_carrier.js:521`,
the swimmer's `SURFACE_Y − 2`) are not ported. A test asserts it (§10 M3). The space ends in four ways, each
visible or announced:

| Direction | What the player meets | Numbers |
|---|---|---|
| Sideways and around every void | **Rock.** Solid, drillable inside the claim box. | — |
| Beyond the claim box | **Dense basalt**: glassy black rock with hexagonal jointing (material blend on `UV1.x`), drill rate falls to 1/8 over 40 m, then nothing cuts it. The drill shows "DENSE BASALT — NO PURCHASE" on the dash and sparks white. `ClaimDist(P)` = signed distance to the box X −330..1,560, Y −980..480, Z −1,700..+60. | ramp 0–40 m |
| Down | **Crush depth.** Ratings: Tender 2,300 / 2,700 / 3,150 m, carrier 3,250 m. Damage `(0.6 + over/25)` HP/s, alarm every 1.6 s, warning on the dash from 50 m above the rating. The Abyss shaft narrows to nothing at Z −1,640 (depth 3,420 m). | §6.8 |
| Up, above the rim | **The Shear**: a permanent current over the Throat's mouth. Marine snow streaks sideways, a low roar rises, the HUD shows "SHEAR CURRENT — ASCENT NOT AUTHORISED" from Z = +10, i.e. 15 m before any push. | below |

Shear velocity field `FDescentShear::VelocityAt(P)` (m/s), added to the position integration of Tenders,
swimmers and loose ore:

```
h = Z - 25;   a = (Z > 25) ? (horizontal distance from the canyon centreline polyline) - 150 : 0
s = clamp(h / 4, 0, 40) + clamp(a / 10, 0, 40)
dir = normalize(0.8 * (unit horizontal vector toward the centreline) + 0.6 * (0, 0, -1))    // straight down when over the centreline
return dir * s
```

It reaches 10 m/s at Z = +65 and 25 m/s (more than a boosted, upgraded Dart) at Z = +125, so nothing leaves
the Throat, and nothing stops dead either. The carrier's ballast-up authority is multiplied by
`1 − smooth(−25, −5, Z)`; at Z > −25 the helm radio says "I will not rise into the Shear."

### 2.12 Ore deposits and loose ore

Ore types *(v2)*: 0 ferrite (orange, 60 cr), 1 cobalt (cyan, 120 cr), 2 pearl (magenta, 260 cr).

Deposits: capsule veins embedded in walls, built by the v2 algorithm (`buildDeposits`): pick a source point in
open water, march a random ray to the wall (≤ 70 m), take the outward normal, place the capsule centre 0.35·r
behind the surface along a random tangent. Half-length 2–6 m, radius 1.3–2.6 m, **yield
`round(2 + half·radius·0.9)`** chunks, no two within 8 m. **Target 600 deposits** (v2: 120). Sources: half of
all tube segments; 30 random points per chamber; one per 15 m of canyon; 5 above each shelf, 4 around each
pinch, 8 per well, 3 per worm pocket.

Type by height *(new bands)*, `r` uniform in [0, 1):

| Z | ferrite | cobalt | pearl |
|---|---|---|---|
| > −370 | r < 0.92 | else | — |
| −370 … −970 | r < 0.40 | r < 0.93 | else |
| < −970 | r < 0.15 | r < 0.55 | else |

Veins show in the rock through `UV0` (§7.8): coloured, faceted, glinting. **Crystals**: 3–7 instanced shards
on each vein's exposed surface; carving within `DrillR` of one pops it into a loose chunk *(v2 `crystalsCheckCarve`)*.

Loose ore chunks: pool of 160 instances (`UInstancedStaticMeshComponent`, faceted 0.34 m mesh built in code,
emissive ore colour). Per step *(v2 `updateLoose`)*: suction first (§4.5); gravity −0.5 m/s²; drag `exp(−1.2·dt)`;
`+ Shear`; collide with the density field at 0.35 m (reflect ×1.4, damp ×0.8). A swimmer can take one within
2.6 m (goes to the suit inventory).

---

## 3. Carrier (CANTICLE)

All coordinates in this section are **carrier-local metres** (+X bow, +Y starboard, +Z up), converted from v2
with the rule of §0. The carrier has no user-made model yet, so it is a **procedural blockout built in code**.

### 3.1 Walking inside a moving vessel: the decision

| Option | Verdict |
|---|---|
| A. `ACharacter` + `UCharacterMovementComponent` standing on the carrier's real collision (moving base) | **Chosen.** |
| B. v2's carrier-local kinematic walker on hand-written walk rectangles | Rejected: placed objects (U1) would need their own collision code, and the user's future interior models would need hand-authored walk rectangles that match them. |
| C. Static interior set somewhere else, exterior rendered separately | Rejected: the moon pool, the bridge windows and Tenders rising into the bay all need one continuous space. |

Why A works here, with the settings that make it solid (`CharacterMovementComponent.h`):

- The carrier is moved kinematically in sim step 2, **before** the character's movement tick (prerequisite,
  §1.4), with `SetActorLocationAndRotation(…, bSweep = false)`. `UpdateBasedMovement` then carries the capsule
  with the full base transform, including pitch (`CharacterMovementComponent.cpp:2531`).
- `bFastAttachedMove = true`: the based move is applied without a sweep. This is safe because nothing outside
  the carrier has collision (terrain has none, §2.1), so no world geometry can be in the way.
- `bStayBasedInAir = true`, `StayBasedInAirHeight = 300` uu, `bImpartBaseVelocityX/Y/Z = true`: a jump inside
  the hull stays with the hull.
- `bIgnoreBaseRotation = false`: carrier yaw turns the character and the view with it.
- Gravity stays world-down. The capsule stays upright while the deck pitches up to ±10° under it; with the
  22.9° stair ramps the steepest floor is 33°, below `SetWalkableFloorAngle(50)`.
- Placed objects, ore boxes and future interior meshes are ordinary collision attached to the carrier, so the
  character collides with them with no extra code.
- When nobody is at the helm the carrier comes to all stop within seconds (§3.6), so most walking happens on
  a base that is at rest.

Fallback if base-following jitter shows up in the `walk_moving` scenario (§10 M6): freeze carrier translation
to all stop whenever the character is in `Foot` mode and not at the helm. It costs "walk around while under
way", which the brief does not require.

### 3.2 Blockout construction and later replacement

`UCarrierBlockoutComponent` builds everything from `FCarrierLayout` at `BeginPlay`:

- **Hull**: a lathe of `HullRadius(x)` (64 segments around; rings every 2 m and along the nose ellipse) with
  the moon-pool rectangle left out of the belly, plus sail, pods, pylons, fins, shroud, keel and bow dome
  (dimensions in §3.3). One `UProceduralMeshComponent`, single-sided material, **no collision**. Because it is
  single-sided, rooms see the sea through their window openings; real hull models must have real windows.
- **Rooms**: for each room one `UProceduralMeshComponent` `Room_<Id>` whose sections are boxes and prisms
  merged per material (floor, ceiling, walls with door and window holes, props), and whose collision is the
  same boxes passed once to `SetCollisionConvexMeshes` (one physics body per room). Collision profile: blocks
  `Pawn`, `Visibility` and the trace channel `Placement`.
- **Stairs**: the collision is one convex ramp per flight; the 16 visual steps have no collision.
- **Vessel-versus-vessel collision** does not use physics: Tenders and swimmers call
  `ICarrierHullShape::PushOut(LocalP, Radius, OutNormal)`. The blockout implements it analytically (v2
  `subCollide` / `updateSwim`: radial push-out to `HullRadius(x) + Radius` for |x| < 62, except inside the
  moon-pool shaft Y 3.5..8.5, X −35..−23, Z < −7.5).
- **Lighting channels**: sea = channel 0, carrier interior = channel 1. Interior lamps light channel 1 only
  and have `VolumetricScatteringIntensity = 0`; interior meshes, placeables, boxes and the character receive
  channel 1; the hull exterior and terrain receive channel 0; Tenders receive both; the flashlight lights both.
- **Custom depth**: every interior primitive, fixture, placeable, ore box, pipe and docked Tender interior
  renders custom depth with **stencil 1 ("dry")** (§7.4).

Replacement by real models later: `FRoomDef::OverrideMesh` and `FCarrierLayout::HullOverrideMesh` are asset
paths, empty by default. When one is set, the builder spawns a `UStaticMeshComponent` with that mesh (authored
in carrier-local coordinates) and skips the blockout for that room or for the hull; collision then comes from
the mesh. Fixtures, pipes, lights, keep-out zones and the dry volume keep coming from the layout tables
(`Anchors`), so gameplay does not change when the art does.

### 3.3 Hull, decks and rooms

Hull *(v2)*:

| Part | Dimensions |
|---|---|
| `HullRadius(x)` | `x > 40`: `12·sqrt(1 − ((x−40)/20)²)` (nose to x = 60); `abs(x) ≤ 40`: 12; `x < −40`: `12 − 5·smooth(40, 60, −x)` (taper to 7 at x = −60) |
| Sail | x −10..30, y ±3, top z 18.2; mast (cosmetic) to z 22.8 at x 8 |
| Thruster pods | radius 1.9, x −40..−20, at y ±13.2, z −3.5 (outer edge y ±15.1) |
| Stern | cruciform fins 0.5 × 7 × 9 at radius 9.5, x −52; shroud ring radius 6.8 at x −61 |
| Keel | 1.2 × 1.4 × 60 at z −12.2 (bottom −12.9), centred x 6; bow sonar dome at x 42, z −8.8 |
| Moon pool | belly opening y 3.5..8.5, x −35..−23 (5 × 12 m); shaft walls z −11.6..−7.5; water surface z −8.3 |

Decks (floor z): **D1 −7.5, D2 −3.0, D3 +1.5**. Room height 4.2; tall rooms 8.7. Doors are 2.4 m high.

| Deck | Room (id) | x | y | Contents (fixtures are fixed; *placeable* items are start placements, §3.4) |
|---|---|---|---|---|
| D3 | BRIDGE (`bridge`) | 36..48 | −8..8 | Helm console and chair, helm fixture at (44.3, 0, 2.7); side consoles; chart table at (39.5, 0, 2.4). Windows: bow wall x 48, y −6.5..6.5, 1.6–3.8 m above the floor; both side walls x 42..46.5, 1.8–3.4 m |
| D3 | QUARTERS A, B (`q1`, `q2`) | 28..36, 20..28 | −9..−1.6 | bed at (33, −7.3) and (25, −7.3); locker. Porthole in A: y −9, x 31..33 |
| D3 | QUARTERS C, D (`q3`, `q4`) | 28..36, 20..28 | 1.6..9 | bed at (33, 7.3) and (25, 7.3). D is the emergency-lit cot room (red lamp) |
| D3 | HABITATION (`hab`) | 6..20 | −9..−1.6 | *couch, table, shelf*; porthole y −9, x 12..17 |
| D3 | FABRICATION (`fab`) | −8..6 | −9..−1.6 | *fabricator* at (−1, −6.5); workbench |
| D3 | COMPONENTS (`comp`) | −8..6 | 1.6..9 | electronics racks with status lights |
| D3 | UPPER DECK corridor (`corr3`) | −8..36 | −1.6..1.6 | ceiling pipes |
| D2/D3 | STAIRWELL, tall (`stair`) | 6..20 | 1.6..9 | ramp y 5.25..8.55 from x 18.6 (D2) up to x 7.95 (D3); D3 landing x 6.05..7.95 |
| D2 | GALLEY (`galley`) | 20..36 | −10..10 | 3 tables; **nutrient ports** at (24, −9.9), (24, 9.9), (32, −9.9), socket 1.45 m above the floor; **nutrient vat** at (21.2, 6.0); windows both sides x 24..32 |
| D2 | CARGO BAY (`cargo`, v2 "storage") | 6..20 | −10..−1.6 | **packer** at (18.6, −5.0) with 4 outfeed slots at x 17.0, y −6.2 / −5.4 / −4.6 / −3.8; storage wall (5 lockers) along y −9.4; **Tethys terminal** at (9, −1.8) |
| D2 | ORE PROCESSING (`refinery`) | −16..6 | −10..−1.6 | *refinery* at (−2, −6.5), hopper facing +y; conveyor prop |
| D2 | ENGINE ROOM (`engine`) | −16..6 | 1.6..10 | reactor with pulsing core at (−4, 6); coolant tanks; pipes |
| D2 | MID DECK corridor (`corr2`) | −18..20 | −1.6..1.6 | **ore pipe** and **bio pipe** under the ceiling (§6.3) |
| D1/D2 | SUB BAY, tall (`bay`) | −40..−18 | −9..9 | D2 gallery x −19.8..−18; stairs y −8.75..−7.25 from x −19.7 (D2) down to x −30.6 (D1); D1 floor with the pool; carousel console at (−22, 1.6); ladder on the pool's inboard edge at (−29, 3.5); railings on three pool sides, gap x −30.3..−27.7 on the inboard side |

Doors (deck: y-range, x-range): D3: bridge (−1.2..1.2, 35.6..36.4); q1 (−2..−1.2, 31..33); q2 (−2..−1.2, 23..25);
q3 (1.2..2, 31..33); q4 (1.2..2, 23..25); hab (−2..−1.2, 12..14); stair landing (1.2..2, 6.3..8); fab
(−2..−1.2, −2..0); comp (1.2..2, −2..0). D2: galley (−1.2..1.2, 19.6..20.4); cargo (−2..−1.2, 13..15); stair
(1.2..2, 15..17); refinery (−2..−1.2, −6..−4); engine (1.2..2, −6..−4); bay gallery (−1.2..1.2, −18.4..−17.6).
A cyan strip and a "DECK n" stencil (`UTextRenderComponent`) sit over every door.

Room lamps (point lights on channel 1, no shadows, falloff exponent model §7.5, radius 11 m, tall rooms 16 m),
position (x, y) under the ceiling, colour, relative intensity:

| Room | Lamps | Colour | Int. |
|---|---|---|---|
| bridge | (41, 0) (44, −5) (44, 5) | #8fc8ff | 1.3 |
| q1 / q2 / q3 | (32, −5) / (24, −5) / (32, 5) | #ffd2a0 | 1.1 / 1.1 / 1.0 |
| q4 | (24, 5) | #ff3018 | 1.4 |
| hab | (16, −5) (9, −5) | #ffe0b8 | 1.2 |
| fab | (2, −5) (−5, −5) | #a8e8ff | 1.4 |
| comp | (−1, 5) | #9affc8 | 0.9 |
| corr3 | (30, 0) (18, 0) (6, 0) (−4, 0) | #d8e8ff | 0.9 |
| stair | (13, 5) (10, 5 at 4.5 m) | #d8e8ff | 1.0 |
| galley | (28, −5) (28, 5) (33, 0) | #ffd8a8 | 1.2 |
| cargo | (13, −6) | #d0e0ff | 1.1 |
| refinery | (0, −6) (−10, −6) | #ffb070 | 1.2 |
| engine | (0, 6) (−10, 6) | #80c0ff | 1.0 × (0.85 + 0.15·sin 2.4t) |
| corr2 | (14, 0) (2, 0) (−10, 0) | #d8e8ff | 0.9 |
| bay | (−24, −5) (−34, 5) (−36, −5) (−22, 5) (−29, −8) | #c8e8ff | 1.5 |

Exterior lights (V4a: the hull is a dark mass): red port nav (24, −12.1, 0.5); green starboard nav (24, 12.1,
0.5); white mast, 0.12 s flash every 2.2 s (8, 0, 22.9); white stern, slow pulse (−60.5, 0, 2); **one flood**
spot at (46, 0, −9.2) aimed at local (130, 0, −30); a dim pool glow at (−29, 6, −12), radius 20. Nothing else.

**Dry volume** `ADescentCarrier::IsDry(LocalP)`: `hypot(y, z) < HullRadius(x) − 0.3` and `|x| < 60`, and not
(inside the pool rectangle and `z < −8.3`). Everything in §7.4 (no water effects), §6.9 (no fauna) and U5
(temperature) keys off this one function.

**Temperature (U5)**: `Descent::AmbientTemperatureAt(WorldP)` returns **26.0 °C** when `IsDry`, otherwise the
water temperature of §2.7. Every readout (HUD, Tender dash, helm dash, PDA status) calls it with its own
reference point. On foot and at the helm the label is `CABIN 26.0 °C`; a Tender docked in the bay also reads 26.0.

### 3.4 Fixtures and start placeables

Fixed (class `ADescentFixture`, cannot be picked up): helm, chart table, 4 beds, 3 nutrient ports, nutrient vat,
packer, storage wall (capacity 60), Tethys terminal, carousel console, pool ladder, unload boom, hand intake
hatch on the pipe riser (§6.3).

Spawned through the build system at game start, so the player can pick them up and move them (U1):
fabricator (−1, −6.5, D3, facing +y); refinery (−2, −6.5, D2, facing +y); couch (14, −7.8), table (14, −5.2),
shelf (9, −2.0) in the habitation room; 3 galley tables with benches at (28, −5.5), (28, 0), (28, 5.5).

### 3.5 Sub bay, carousel and hoist (V5)

| Item | Value |
|---|---|
| Hub | (−29, 0, 0), rotates about z; three arms 120° apart, radius 6; fixed cradles hang at z −1.0 *(v2)* |
| Tender pose in a cradle | origin at the cradle, nose tangential; at the launch slot the nose points to the bow |
| Launch slot | the arm at yaw +90° (pointing +y): cradle at **(−29, 6, −1)**, over the pool |
| Rotation | console adds **+120° (clockwise seen from above)** at 0.35 rad/s (≈ 6 s) *(v2)*. Blocked while any Tender is out, while a hold is unloading, or while the hoist is moving |
| Hoist *(new)* | the cradle at the launch slot is a hoist with two stops: STOWED z −1.0 and **BOARD z −6.3** (hull bottom 0.23 m above deck level, inside the pool mouth; canopy sill 1.25 m above the deck). It rests at BOARD whenever the carousel is idle. Travel 2 m/s (2.65 s). A rotation is: raise to STOWED → rotate → lower to BOARD |
| Boarding | `E` within 4.5 m of the Tender at BOARD: canopy lid opens (0.5 s), camera moves to the seat (0.9 s) *(v2 timing)*; mode `Docked` |
| Launch | `Space` in `Docked`: straight down from (−29, 6, −6.3) to DOCK_BELOW **(−29, 6, −16)** over 3.2 s (smoothstep), then control is handed over with velocity = carrier velocity + (0, 0, −1) |
| Dock | allowed when the Tender is within ±7 m in y and ±9 m in x of the launch column and at local z −34..−11 *(v2)* and the hoist cradle is free: 1.6 s blend to DOCK_BELOW and carrier alignment, then 2.6 s rise to BOARD, attach, start unloading (§6.3) |
| Pool fit | Kazah at the slot spans x −32.26..−25.27, y 4.36..7.64: 0.86 m to each long pool edge, 1.7 m and 2.7 m to the ends |
| Clearance | farthest Tender corner from the hub: 8.5 m < 8.84 m (bay wall inside face); rotating Tenders span z −1.97..+0.55, 3.7 m above heads on D1, 0.7 m clear of the D2 gallery edge |

Clearance test (automation, pure geometry): sweep the carousel through 360° in 1° steps with all three
Tenders at STOWED; the minimum distance between any two Tender boxes (6.99 × 3.27 × 2.51 m around the model
bounds) must be ≥ 2 m, and no box may intersect the bay walls, the D2 gallery slab, the stairs, the hub, the
pipe riser (§6.3) or the unload boom in its stowed pose. Second sweep: the hoist from STOWED to BOARD to
DOCK_BELOW must not intersect the pool rim or shaft.

### 3.6 Helm: the player pilots the carrier (V12, U4, U9)

State (`UCarrierHelmComponent`): position, yaw, pitch, roll, velocity, yaw rate, throttle, ballast, strafe,
hull 0..100, power 0..100, contacts, scrape 0..1.

**Controls at the helm (U4: the mouse steers, as in a Tender, at the carrier's scale):**

| Input | Effect |
|---|---|
| Mouse | moves the **aim point**: `AimYaw` (world heading) and `AimPitch`. 0.05° per pixel yaw, 0.03° per pixel pitch. `AimYaw` is clamped to within ±40° of the hull heading, `AimPitch` to ±10°. The hull turns toward the aim, so the aim reticle drifts back to the centre of the view as the hull catches up. |
| W / S | throttle lever up / down at 1.5 per second, range −0.5..1. X = all stop. |
| A / D | lateral thrusters (port / starboard) |
| Space / C | ballast up / down |
| Right mouse (hold) | free look (±80° yaw, −50..+35° pitch); the aim stays where it was |
| V | next camera; R deep sonar ping; F floodlight; E leave the helm |

**Dynamics** *(new constants for U9 and U4; structure of v2 `carrierPhysics`)*:

| Quantity | Value |
|---|---|
| Forward speed | `v_target = throttle × 2.0 m/s`; `dv/dt = (v_target − v_fwd)/τ`, **τ = 1.2 s** → 90% of top speed 2.8 s after the lever is full, lever takes 0.67 s (v2: ≈ 20 s) |
| Lateral | target ±0.6 m/s, τ = 1.5 s; unintended sideways velocity is damped at 0.6 s⁻¹ *(v2 keel damping)* |
| Vertical | `v_z = v_fwd·sin(pitch) + ballast·1.3 m/s`, ballast response τ = 1.5 s |
| Yaw | `err = wrap(AimYaw − Yaw)`; `ω_target = clamp(1.2·err, ±0.10 rad/s)`; `dω/dt = clamp((ω_target − ω)/0.8, ±α)`, `α = 0.03 + 0.01·abs(v_fwd)` rad/s² |
| Pitch | target `AimPitch` when `abs(v_fwd) > 0.3`, else 0; response τ = 2.5 s; hard limit ±10° |
| Roll | `−0.25·ω` rad (cosmetic) |
| Collision | 250 hull sample points (list below) against `Density`. Contact when `d > −0.5`. Push = `−Gradient × (d + 0.5)`, summed, scaled `0.6/max(1, 0.35·contacts)`. Normal velocity removed ×0.9. Yaw torque `0.00006 × Σ(r × n)·pen`. Velocity × `exp(−1.5·dt)` while in contact *(v2)* |
| Hull damage | `Σpen × (0.08 + 0.9·speed) × dt` *(v2)* |
| Scrape | `damp(scrape, contacts ? min(1, 0.3·Σpen + 0.4·speed) : 0, 6, dt)` → audio |
| Power | drain `0.05·abs(throttle)` %/s, regen 0.02 %/s; at 0 the throttle is forced to 0 *(v2)* |
| Rating | **3,250 m** *(new)*; below it hull loses `(0.6 + over/25)` per second |
| The Shear | ballast-up authority × `1 − smooth(−25, −5, Z)` (§2.11) |
| Leaving the helm | all stop: throttle, strafe and ballast targets → 0, `AimYaw = Yaw`, `AimPitch = 0` |

Hull sample points (carrier-local): rings at x = 59, 54, 48, 40, 30, 18, 6, −6, −18, −30, −40, −50, −58 with
radius `HullRadius(x)` and 14 points each (8 where |x| > 50); sail at x = 28, 22, 16, 10, 4, −2, −8: (x, 0, 18.2)
and (x, ±2.6, 15); pods (−21 / −30 / −39, ±15.1, −3.5); keel (30, 0, −12.9), (−10, 0, −12.9); stern (−55, 0, −15),
(−55, 0, 16), (−55, ±14, 0).

Hull consequences *(v2)*: below 30%: alarm every 6 s, interior lamps stutter (`sin 23t + sin 37.3t + sin(5.1t+1) > 1.2`
→ ×0.2), creaks double. At 0% ("CRIPPLED"): throttle capped at 0.25, ballast at ±0.4, radio line; no game
over. Repair: fabricator recipe *Carrier Hull Patch* (+25).

Cameras (`V` cycles; all are `UCameraComponent`s on the carrier, only one active):

| # | View | Pose (carrier-local) | FOV |
|---|---|---|---|
| 0 | BRIDGE | eye at (44.2, 0, 3.15), first person, helm dash visible | 72° |
| 1 | CHASE | (−85, 0, 28) looking at (30, 0, 0) | 60° |
| 2 | TOP-DOWN | 130 m above, heading-up | 60° |
| 3 | BOW CAM | (60, 0, −10.5), pitched −8.6° | 85° |
| 4 | KEEL CAM | (−5, 0, −14.5), pitched −69° | 95° |

In views 1–4 the water fog density is ×0.3, the hull gets a faint cyan rim (material parameter), eight feed
lights (radius 48 m) at (70, 0, −3), (34, ±24, 0), (−12, ±24, −4), (12, 0, −26), (20, 0, 27), (−76, 0, 0) come on
with the flood, and the HUD shows the **PROXIMITY** panel: 22 sensor rays (four around the hull at x = 50, 25,
0, −25, −50, plus bow and stern), 30 m range in 1.5 m steps, refreshed at 4 Hz; dots green > 10 m, amber, red
< 4 m *(v2)*.

**Helm dash (V6)**: in view 0 a `UWidgetComponent` over the helm console shows the same `SDescentDash` widget as
the Tender (§4.6) fed by `UCarrierHelmComponent::MakeDashModel()`: title `CANTICLE · HELM`; left arc carrier
HULL %; right arc POWER %; depth of the carrier origin with `RATING 3,250 m`; `CABIN 26.0 °C   SPD x.x m/s`;
`STORAGE u/c · THROTTLE n%`; `HDG nnn° · CONTACTS n`. In views 1–4 there is no dash, so the HUD vehicle panel
shows the same values.

Helm sonar: range 420 m, 4,200 rays, cooldown 4 s, origin (40, 0, −10) *(range raised from 320 m for the larger voids)*.

---

## 4. Tender (the Kazah "subtub")

All coordinates in this section are **Tender-local metres** (+X nose, +Y starboard, +Z up, origin = the Blender
origin). Model bounds: X −3.26..+3.73, Y ±1.635, Z −0.965..+1.545 (6.99 × 3.27 × 2.51 m).

### 4.1 Parts → components

The export (`Tools/blender/export_kazah.py`, `Vehicles/KazahLayout.inl`) merges everything that never moves
into `Body` and keeps the parts below separate, each with its pivot on its axis of motion. `AKazahTender`
(exists) assembles them. Meshes live in `/Game/Vehicles/Kazah/SM_Kazah_<Part>`.

| Part | Pivot (m) | Component and behaviour |
|---|---|---|
| `Body` | (0, 0, 0) | `UStaticMeshComponent`. Hull, tanks, propulsor ducts, guard hoops, stern fittings. Three child `UBoxComponent`s give it simple collision (blocks `Pawn`) so the player cannot walk through a Tender hanging in the bay: hull 6.6 × 1.9 × 2.0 at (0.2, 0, 0.2); two side boxes 3.0 × 0.9 × 0.9 at (−0.1, ±1.0, −0.4) |
| `Cockpit_Interior` | (0, 0, 0) | seat and console. Renders custom-depth stencil 1 (dry). Hidden parts are not needed: it is small enough to stay visible in first person |
| `Canopy_Lid` | (1.207, 0, −0.035) | hinge about the Y axis at its rear-bottom edge. Opens to −55° pitch in 0.5 s when boarding or leaving in the bay. `Canopy_Glass` is attached to it and moves with it |
| `Canopy_Glass` | (1.207, 0, −0.035) | glass material `MI_KazahGlass` (§7.9) |
| `Hatch_Lid` | (−0.288, 0, 1.338) | roof hatch, hinge at its aft edge. Opens to −70° in 0.4 s when the pilot leaves to swim or enters from the water |
| `Rotor_Port`, `Rotor_Stbd` | (−2.830, −1.085, 0.130), (−2.832, 1.085, 0.130) | spin about X, counter-rotating. **RPM = 305 × thrust** (thrust 0..1.7; 0 when idle) *(v2: `spin += 32·thrust·dt`)* |
| `Tool_Housing` | (1.972, ∓0.690, −0.775) | the one drill-plus-suction tool. See §4.5 for the side |
| `Nose_Lens` | (3.687, 0, 0) | headlight lens; emissive when the lamp is on; the spot light sits 5 cm ahead of it |
| `Chin_Sensor` | (3.136, −0.005, −0.451) | sonar transducer: ping origin; pulses cyan on a ping |

Added in code (blockout, replaceable): drill bit (cone 0.18 m radius × 0.45 m, spins about X) and intake ring
(torus radius 0.22 m) on the front face of the tool housing; a blinking top beacon; the launch clamps are
part of the carrier.

Fleet *(v2 specs, all three use the Kazah model)*:

| Id | Name | Speed × | Drill radius | Drill rate × | Hold | Paint (overrides the "Pearl ceramic lacquer" colour) |
|---|---|---|---|---|---|---|
| BT-01 | TENDER | 1.0 | +0 | 1.0 | 8 | as modelled (0.638, 0.711, 0.674) |
| BT-02 | DART | 1.3 | −0.4 | 0.85 | 6 | deep teal (0.03, 0.35, 0.33) |
| BT-03 | MOLE | 0.8 | +0.9 | 1.4 | 12 | burnt orange (0.60, 0.12, 0.03) |

### 4.2 Derived stats: one place

`FTenderStats UTenderFlightComponent::Stats() const` is the only source of every Tender number *(v2 `subStats`)*:

| Stat | Formula |
|---|---|
| `HullMax` | `100 × (1 + 0.5·HullMk)` HP. Hull is stored in **absolute HP**; all damage is in HP; display `round(100·Hull/HullMax)` % |
| `Rating` *(new)* | 2,300 m; 2,700 with Depth Module Mk I; 3,150 with Mk II |
| `Capacity` | 100 energy units; 170 with Power Cell II. `Power` is stored as % of capacity; a drain of `u` units/s lowers it by `100·u/Capacity` %/s |
| `Speed` | `9 × spec.Speed × (1 + 0.25·ThrustMk)` m/s |
| `HoldCap` | `spec.Hold + 8·HoldMk` |
| `BioCap` *(new)* | 4.0 FU (§6.9) |
| `DrillR` | `3.0 + 0.7·DrillMk + spec.DrillR` m |
| `DrillRate` | `9 × (1 + 0.5·DrillMk) × spec.DrillRate` |
| `SonarRange` | 160 m; 260 m with the Sonar Module |
| `SuctionRange`, `SuctionPull` | 13 m, 9; with Suction Mk II 22 m, 16 |

### 4.3 Flight model *(v2 `updateSub`, numbers unchanged)*

| Quantity | Value |
|---|---|
| Steering | mouse sets yaw and pitch directly: 0.102° per pixel (v2 `SENS × 0.85`); pitch limit ±77° |
| Roll | cosmetic: `damp(roll, −0.2·strafe + clamp(−0.004·lookDX, ±0.3), 3, dt)` rad |
| Thrust | `wish = fwd·W/S + right·A/D + worldUp·Space/C`, normalised if longer than 1 |
| Velocity | `vel = lerp(vel, wish·MaxS, 1 − exp(−1.8·dt))`; `MaxS = Speed × (boost ? 1.7 : 1) × hungerMul × (powered ? 1 : 0.3)` |
| Position | `pos += (vel + Shear(pos))·dt`. **No clamp of any kind (U7).** |
| Terrain collision | spheres below, two iterations: `pen = r + Density(c)`; if `pen > 0`: `pos −= Gradient·0.9·pen`; remove the into-rock velocity ×1.2; remember the largest normal speed as `hit` |
| Carrier collision | `ICarrierHullShape::PushOut` with radius 2.0 m around the Tender origin, using velocity relative to the carrier |
| Impact damage | if `hit > 4.5 m/s`: `(hit − 4.5) × 5` HP, shake, clank, toast "Hull impact −n%" |
| Energy drains (units/s) | idle 0.1; boost 0.7; headlight 0.06; drill 1.3; laser 1.9; suction 0.35. Radio warning at 20% |
| Crush | below `Rating`: `(0.6 + over/25)` HP/s, alarm and creak every 1.6 s; dash warning from 50 m above the rating |
| Honest void | 14 HP/s while inside either honest void |
| Hull 0 | death "implode" (§5.8) |
| Docked | +6 %/s power, +4 HP/s hull |

Collision spheres (centre, radius): nose (2.6, 0, 0.3) 1.0; cockpit (1.2, 0, 0.3) 1.15; centre (−0.3, 0, 0.2)
1.35; stern (−2.2, 0, 0.15) 1.1; propulsors (−2.55, ±1.09, 0.13) 0.55; tanks (0, ±1.0, −0.45) 0.5; tool
(1.97, toolSide·0.69, −0.78) 0.3.

### 4.4 Lights

| Light | Spec |
|---|---|
| Headlamp | spot at (3.74, 0, 0), aimed 3° down; exponent falloff (§7.5), radius 90 m, inner / outer cone 14.5° / 26.4°, colour #e6f6ff, start intensity 3.2, **casts shadows**, volumetric scattering 1.0. `F` toggles. Multiplied by the horror flicker (§8.3) |
| Lens glow | `Nose_Lens` emissive 6.0 when on, 0.1 when off |
| Cockpit glow | point light at the dash, radius 1.5 m, intensity 0.15, cyan, no volumetric scattering |
| Top beacon | emissive blink 0.25 s every 1.6 s, no light component |

### 4.5 The single drill-plus-suction tool (U10)

- **One tool.** `Tool_Housing` carries both the drill bit and the suction intake. There is no second arm.
- **Side.** U10 says the left side stays free. In the model the housing sits on the **port (left)** side
  (pivot Y −0.690). The Tender therefore mounts it **mirrored on the starboard side**: component location
  (1.972, +0.690, −0.775), relative scale (1, −1, 1). One constant, `Descent::Tune::Tender::ToolSide = +1`,
  switches it back (see the open question in §11). The port hardpoint (1.972, −0.690, −0.775) is an empty
  named socket `Hardpoint_Port`; the state dump reports `hardpoints: { starboard: "drill_suction", port: "empty" }`.
- **Use.** Hold **LMB: drill**. Hold **RMB: suction**. If both are held the drill wins (one motor). `T` swaps
  the drill bit for the laser head once the Laser Cutter is fabricated. The player drills a vein, the ore
  breaks loose, then sucks the loose chunks in with the same tool.
- **Aim.** A ray from the cockpit camera along the view direction. The tool head swivels up to 25° toward
  the hit point.

| Function | Rule *(v2 numbers)* |
|---|---|
| Drill | reach 16 m. On a hit: `Carve(hit + dir·0.8, DrillR, DrillRate, dt)` (hardness inside `Carve`); cleanup timer (§2.5); bit spins 38 rad/s; a pale stream from the tool tip to the hit; sparks and rock debris every 0.04 s; a glow light (colour (1.0, 0.8, 0.55), radius 9 m) at the hit; shake 0.12 |
| Laser head | reach 28 m; `Carve(hit + dir·0.5, max(1.6, 0.6·DrillR), 1.6·DrillRate, dt)`; red beam; shake 0.04 |
| Suction | nozzle = tool tip. Every loose chunk within `SuctionRange` and inside the cone (`cos ≥ 0.55` to the view direction, or closer than 3 m) is accelerated toward the nozzle by `SuctionPull × (1.2 − d/SuctionRange)`. Within 1.6 m it is captured into the hold. If the hold is full the chunk is pushed back (velocity × −0.3) and "HOLD FULL — dock to unload" shows every 2 s. The same cone captures fauna into the bio-tank (§6.9). Motes stream into the intake ring; the ring glows cyan |
| Basalt | drilling dense basalt (§2.11): white sparks, no carve, dash line "DENSE BASALT — NO PURCHASE" |

### 4.6 Cockpit, dashboards and the cargo display (V6, U11)

- **Eye**: (1.95, 0, 0.72), FOV 72°. In `Sub` mode the view is rigid to the hull (the mouse steers). In
  `Docked` the mouse looks around: yaw ±75°, pitch −52..+40°. Near clip plane 5 cm (`r.SetNearClipPlane 5`).
- **Canopy** from inside: `MI_KazahGlass` with a 0.22 fresnel rim, faint smudges and condensation *(v2)*.
- **Main dash** `DashMain`: a `UWidgetComponent` hosting `SDescentDash`, 1.10 × 0.45 m, centre at eye +
  (0.75, 0, −0.34), pitched back 14°; draw size 1024 × 420 px; manual redraw at 8 Hz and whenever the rounded
  depth changes. Layout *(v2 §4.3, pixel coordinates)*:

  | Element | Place | Content |
  |---|---|---|
  | Title | top centre | `BT-01 TENDER · DRILL` (or `· LASER`, `· SUCTION` while sucking) |
  | Left arc | centre (210, 230), radius 130, 270° sweep, 14 px thick, round caps, 13% track, glow | **HULL** %; cyan, red below 30% |
  | Right arc | centre (814, 230), radius 130 | **POWER** %; amber, red below 20% |
  | Depth | centre top, 86 px bold | `2,061 m`; below it `RATING 2,300 m`, or `!! CRUSH DEPTH 2,300 m` in red |
  | Depth bar | x 362..662, y 208 | fill = depth between 1,740 and 3,400 m; red tick = rating |
  | Line 1 | under the bar | `TEMP xx.x °C   SPD x.x m/s` |
  | Line 2 | bottom | `HOLD u/c · BIO b/4.0`; red when the hold is full |

- **Cargo display (U11)** `DashCargo`: a second `UWidgetComponent` hosting `SCargoDisplay`, 0.30 × 0.30 m, centre
  at eye + (0.60, 0.36, −0.30), yawed 35° toward the pilot; draw size 512 × 512 px. It is a **picture of the
  hold**, not a number:
  - a cut-away tank outline divided into `HoldCap` cells, 4 columns, filled bottom-up **in the order the
    chunks arrived**; each filled cell shows a faceted chunk in its ore colour (ferrite #ff9a3c, cobalt
    #3fe6ff, pearl #ff5ad8) with its symbol (Fe, Co, Pe); empty cells are inset wells;
  - a new chunk drops in from the top over 0.3 s;
  - header `CARGO 5/8`; footer three chips `Fe 3 · Co 2 · Pe 0`;
  - a vertical green bar on the right for the bio-tank, `BIO 1.2/4.0`;
  - full hold: the outline turns red and pulses, header `HOLD FULL`;
  - while unloading (§6.3) the cells empty top-down in step with the pieces leaving through the boom.
- **One source of truth.** `FTenderDashModel UTenderFlightComponent::MakeDashModel()` builds every value once;
  `SDescentDash`, `SCargoDisplay`, the HUD vehicle panel and the `tenders` state section all read that model.
  Depth uses the Tender origin in every sub mode (§5.9).
- The mirrored position on the port side, eye + (0.60, −0.36, −0.30), is reserved (`DashAux`, hidden).

### 4.7 Abandoned Tenders

A Tender the pilot left to swim stays where it is (zero thrust, velocity damped by `exp(−1.8·dt)`, still
subject to the Shear and to collision). It can be re-entered within 4.5 m. The carousel stays locked until it
is docked again.

---

## 5. Player

### 5.1 The pawn

`ADescentCharacter` is the only possessed pawn for the whole game. Vehicles are never possessed: the player
controller routes intents to them (§5.7) and switches the view target. While piloting, the character is
attached to the vehicle, hidden, with movement mode `MOVE_None` and no collision.

| Item | Value |
|---|---|
| Capsule | radius 0.34 m, half-height 0.90 m; eye 1.65 m above the feet *(v2)* |
| Camera | `UCameraComponent` on the character, FOV 72°, uses control rotation; view bob as v2 (`0.045·sin(2·bob)` vertical) |
| Lighting channels | 0 and 1 |

### 5.2 On foot (inside the carrier only)

`UDescentCharacterMovement`, `MOVE_Walking` / `MOVE_Falling`, with the moving-base settings of §3.1.

| Quantity | Value *(v2)* |
|---|---|
| Walk / sprint | 2.9 / 4.8 m/s, × `hungerMul` (`nutrition < 20 ? lerp(0.55, 1, nutrition/20) : 1`); carrying a box: 2.3 m/s, no sprint |
| Acceleration | braking and acceleration tuned so velocity follows `damp(k = 12)` |
| Jump | 4.4 m/s × `sqrt(hungerMul)`; gravity scale 1.12 (11 m/s²) |
| Step height / walkable angle | 0.35 m / 50° |
| Footstep sound | every 1.35 m walked |
| Pool | stepping or jumping through the gap in the pool railing: when the feet pass the water plane (carrier z −8.3) inside the pool rectangle → `Swim`, entry velocity `(0, 0, min(−2.5, 0.6·v_z))`, splash |

### 5.3 Swimming

Custom movement mode `MOVE_Custom / Swim` implemented in `PhysCustom` (`CharacterMovementComponent.h:2007`).
The capsule is replaced by a 0.45 m sphere test against the density field; the move itself is a
`SafeMoveUpdatedComponent` sweep so physics objects (Tender collision boxes) still block.

| Quantity | Value *(v2 §4.13)* |
|---|---|
| Speed | 2.8 m/s; sprint 4.2 (O₂ drain ×1.4); propulsor 7.5 (hold LMB or Q with it selected); all × `hungerMul` |
| Response | `vel = lerp(vel, wish·MaxS, 1 − exp(−2.2·dt))`; `wish` from the full view rotation plus Space / C on world up |
| Sink | 0.12 m/s² downward |
| Position | `pos += (vel + Shear(pos))·dt`. **No clamp.** |
| Terrain | `PushOutSphere(pos, 0.45)` twice per step |
| Carrier hull | `ICarrierHullShape::PushOut(pos, 0.6)`; inside the moon-pool shaft the head cannot rise above the water plane − 0.35 m |
| Tenders | pushed out to 2.2 m from an undocked Tender's origin |
| O₂ | −1 per second (−1.4 sprinting or gliding). With the head within 0.6 m of the pool surface inside the shaft: +20 per second. At 0: health −9 per second, "DROWNING" |
| Breath sound | every 3.4 s; every 1.8 s below 10 s of O₂ |
| Ladder | `E` in the shaft, within 1.6 m of the water surface and y < 5.3: 1.6 s climb, then `Foot` at carrier-local (−29, 2.6, −7.5) |
| Leave a Tender | `E` in `Sub` away from the dock: the roof hatch opens, the swimmer appears at Tender-local (1.2, −2.2, 0.2) |
| Enter a Tender | `E` within 4.5 m of an undocked Tender |
| Take loose ore or a polyp | `E` within 2.6 m → suit inventory |

### 5.4 Interaction

`UDescentInteractionComponent` keeps a registry of `IDescentInteractable`s (fixtures, placeables, boxes,
Tenders, sockets). Each late step it scores every candidate with the v2 rule: within `GetRange()` of the eye
and `dot(view, toTarget) ≥ GetMinDot()`; `score = dot − 0.05·distance`; the best one is the focus. The HUD
prompt shows `[E] <label>` 30 px below the crosshair. `E` calls `Use`. Typical range 2.4 m, min dot 0.55–0.75
(the v2 `INTERACT` values). Collision is not involved, so the result is the same with blockout or real meshes.

### 5.5 Carrying (needed for U14)

`UDescentCarryComponent`:

- `E` on an `ADescentOreBox` (range 2.4 m, both hands free, not in build mode): the box attaches to the carry
  point, 0.75 m ahead of the eye and 0.35 m below, collision off, tilting slightly with view pitch.
- While carrying: walk 2.3 m/s, no sprint, no hotbar tools, cannot board, cannot climb the ladder, cannot open
  the PDA map table or the build menu.
- `E` on a **box socket** (refinery hopper, rack slot, packer outfeed slot) within 2.4 m: the box goes into the
  socket (0.25 s lerp). A socket refuses a box it cannot take and says why (toast).
- `LMB` or `G`: put the box down. Trace from the carry point straight down up to 2.5 m on the `Placement`
  channel; the box lands upright on the hit, attached to the carrier, with its collision back on. Refused
  over the pool, on stairs, or when the landing spot overlaps something.
- Boxes are never physics-simulated: a pitching carrier would make simulated boxes slide and jitter.

### 5.6 Mode state machine (`ADescentPlayerController`)

```
Title ─click→ Foot
Foot ─E port→ Jack ─(4.8 s)→ Foot                 Foot ─E bed→ Sleep ─(2.4 s)→ Foot
Foot ─E helm→ Helm ─E→ Foot                       Foot ─B→ Build ─LMB place / RMB cancel→ Foot
Foot ─E box→ Foot+Carry ─E socket / LMB drop→ Foot
Foot ─E Tender at BOARD→ Board ─(1.4 s)→ Docked ─Space→ Launch ─(3.2 s)→ Sub
Docked ─E→ Foot (at the pool rim)                 Sub ─E under the pool→ Dock ─(4.2 s)→ Docked
Sub ─E elsewhere→ Swim ─E near a free Tender→ Sub
Foot ─through the pool gap→ Swim ─E at the ladder→ Ladder ─(1.6 s)→ Foot
any ─Tab / M / E station→ UI overlay (the mode underneath is kept) ─Esc / Tab / E→ back
drown / hunger / implode → Dead ─(2.6 s)→ respawn → Foot (galley)
```

`EDescentMode { Title, Foot, Jack, Sleep, Helm, Build, Board, Docked, Launch, Sub, Dock, Swim, Ladder, Dead }`;
UI and Carry are flags on top of a mode, not modes.

### 5.7 Input

Enhanced Input, created in C++ (`NewObject<UInputAction>`, `NewObject<UInputMappingContext>`, `MapKey`); no
input assets. Handlers do not act directly: they write the current **intent**, and the sim reads intents.
Debug commands write the same intents (§9.2), so tests and players go through one path.

```cpp
struct FDescentIntent { FVector Move; FVector2D Look; bool bPrimary, bSecondary, bSprint, bJump, bDown; };   // Move: X forward, Y right, Z up, each −1..1
```

| Action | Keys | Foot | Swim | Tender (`Sub`) | Helm |
|---|---|---|---|---|---|
| Move | W A S D | walk | swim | thrust, strafe | throttle lever (W/S), lateral thrusters (A/D) |
| Up / down | Space / C or Ctrl | jump | rise / sink | rise / sink | ballast |
| Look | mouse (arrow keys also) | look | look | **steer** | **steer (aim point)**; RMB held = free look |
| Sprint | Shift | sprint | sprint | boost | — |
| Use | E | focus action | focus action | dock / leave to swim | leave helm |
| Primary | LMB | use hotbar tool; in build: place; carrying: put down | use tool | **drill** | — |
| Secondary | RMB | in build: cancel | — | **suction** | free look |
| Light | F | flashlight | flashlight | headlamp | floodlight |
| Sonar | R | — ("useless inside the hull") | handheld ping | ping | deep ping |
| Tool swap | T | — | — | drill ↔ laser | — |
| Camera | V | — | — | — | next view |
| All stop | X | — | — | — | throttle 0 |
| Hotbar | 1–5, G = use | select | select | — | — |
| Build | B; wheel or Q / E rotate; Alt free placement | build mode | — | — | — |
| PDA / map | Tab / M | open | open | open | open |
| Objective | J | pin / fold | | | |
| Pause | Esc, P, H | pause and key list | | | |

Mouse sensitivity base: 0.12° per pixel on foot and swimming (v2 `SENS = 0.0021 rad`).

### 5.8 Vitals, death and respawn

| Vital | Rule |
|---|---|
| **Nutrition (U2)** | 0..100%. **Drains 100% in 40 minutes: 0.0417 % per second** (v2: 9 minutes, 0.185 %/s). Console variable `descent.Player.NutritionMinutes` (default 40). Starts at 42%. Not drained in `Title`, `Jack`, `Sleep`, `Dead`. Below 20%: radio warning, speed penalty (`hungerMul`). Below 25%: hallucinations (§8.3). At 0% for 20 s: death "hunger". Sleeping 2 h costs 10 points (not below 8) |
| O₂ | seconds: 45 base, 90 / 150 with a tank. Drains only in `Swim`. Refills 20 per second everywhere else |
| Health | 0..100. +0.4 per second out of the water when nutrition > 20%. Sleep restores it |
| Jack-in feed | §6.9 (needs biomass) |

Death *(v2)*: fade to black over 2.0 s, respawn after 2.6 s on foot in the galley at (24, −5, −3), health 60,
O₂ full.

| Cause | Consequence |
|---|---|
| Drown, or an honest void while swimming | debt +900 cr, radio line |
| Hunger | nutrition set to 35 if the reserve has at least 1.4 FU (which it consumes), else to 15; debt +900 cr |
| Implode (Tender hull 0) | that Tender's hold and bio-tank are lost; a replacement hull is "printed" into the free cradle with full hull and 60% power; debt +4,800 cr |

### 5.9 The "controlled body" reference point *(v2 §4.2)*

`FVector ADescentPlayerController::RefPointM()` is the point every depth, compass, temperature and map "YOU"
readout uses:

| Mode | Reference point |
|---|---|
| `Board`, `Docked`, `Launch`, `Sub`, `Dock`, or `Dead` by implosion | the Tender origin |
| `Helm` (every camera view) | the carrier origin |
| `Swim` | the swimmer |
| everything else | the eye |

`CurDepth() = DepthOfZ(RefPointM().Z)`. HUD, dash and map show `round(CurDepth())`; a test asserts they are equal.

---

## 6. Systems

The loop (V8, U13, U14): **mine → Tender hold → dock → pipes → packer → ore box → carry (or robot arm) →
refinery → carrier storage → fabricator / Tethys terminal.**

### 6.1 Items, inventory, hotbar, equipment (V11)

`DescentItems.cpp` holds the static item table *(v2 `ITEMS`, plus new rows)*:

| Id | Name | Category | Stack | Value (cr) | Notes |
|---|---|---|---|---|---|
| `ferrite`, `cobalt`, `pearl` | Basalt Ferrite, Cobalt Glass, Seam Pearl | ore | 10 | 60, 120, 260 | in the suit only when picked up by hand |
| `ingot`, `wafer`, `lattice` | Ferrite Ingot, Cobalt Wafer, Pearl Lattice | refined | — (storage) | 115, 230, 500 | refine time 14, 22, 34 s |
| `flashlight`, `scanner`, `propulsor` | Flashlight, Handheld Sonar, Sea-Glide Propulsor | tool | 1 | — | |
| `flare`, `beacon` | Flare, Marker Beacon | use | 10, 5 | — | |
| `tank1`, `tank2` | High-Capacity O₂ Tank, Ultra O₂ Tank | tank | 1 | — | 90 s, 150 s |
| `silverfin`, `lanternfish`, `jelly`, `polyp` *(new)* | fauna | bio | 10 | — | 0.10, 0.15, 0.60, 0.40 FU (§6.9) |
| `weapon` | Weapon slot | weapon | — | — | greyed placeholder, "not licensed" |
| `kit_*` *(new)* | build kits (§6.10) | kit | — (storage) | — | never in the suit |

Suit inventory: 24 slots; hotbar 5 slots (keys 1–5), start `flashlight, scanner, flare, –, –`; start kit:
flashlight, 3 flares, handheld sonar *(v2)*. Equipment: O₂ tank slot, and a **weapon slot shown greyed** (the
architecture for future guns: `Equip.Weapon`, item category `weapon`, a view-model slot on the character).

### 6.2 Carrier storage and the cargo ledger

`UDescentStoreSubsystem`:

- **Storage** (`Store`): counts of refined goods and kits. Capacity for refined goods: **60 + 40 per placed
  Storage Locker** *(v2 numbers)*. Kits do not count toward capacity.
- **Cargo ledger**: raw ore is physical. `CountOre(type)` sums the contents of every `ADescentOreBox` aboard;
  `ConsumeOre(type, n)` takes from the emptiest boxes first and deletes boxes that reach 0. Recipes and the
  terminal use these two functions, so "2 Ferrite" in a recipe means two pieces out of a box.
- **Upgrades** `FUpgradeState { HullMk, DepthMk, CellMk, ThrustMk, SonarMk, DrillMk, bLaser, SuctionMk, HoldMk }`.
- **Debt**: starts at 184,220 cr *(v2)*.

### 6.3 Unloading through transparent pipes (U13)

Two pipe routes run through the carrier's interior, built by the blockout as swept glass tubes
(`MI_PipeGlass`, §7.9) with brackets every 2 m. Coordinates are carrier-local.

**Ore pipe** (inner radius 0.16 m, 72 m):

```
(−29.37, 6.00, −7.10)  belly coupling of the Tender at BOARD (Tender-local (−0.37, 0, −0.80))
(−29.37, 6.00, −7.35)  riser 0.25 m
(−22.80, 8.75, −7.35)  unload boom, 7.1 m, pivots at this end on the starboard pool corner
(−22.80, 8.75,  0.90)  riser up the starboard bay wall
(−19.20, 8.75,  0.90)  forward under the bay ceiling
(−19.20, 0.60,  0.90)  inboard above the D2 gallery
( 18.60, 0.60,  0.90)  through the bay wall above the door, along the MID DECK corridor ceiling (38 m)
( 18.60, −5.00, 0.90)  through the corridor wall into the CARGO BAY
( 18.60, −5.00, −0.60) down into the packer inlet
```

**Bio pipe** (inner radius 0.09 m, green tint) shares the boom and riser 0.3 m outboard, runs beside the ore
pipe along the corridor at y 0.95 to x 21.0, crosses the galley ceiling to (21.2, 6.0, 0.9) and drops into
the nutrient vat.

**The unload boom** rests along the starboard pool edge (pointing aft, in the 0.5 m strip between pool and
wall) and swings 23° inboard under the Tender's belly to couple. It is a separate component with its origin on
the pivot.

Unload job (`UDescentCargoSubsystem`), started when a dock completes:

| Step | Rule |
|---|---|
| Couple | boom swings in and couples: 1.0 s; the carousel is locked |
| Feed | every 0.45 s one piece leaves the hold, **last in first out** (the cargo display empties top-down), as long as `PackerBuffer + PiecesInPipe < 24`. Otherwise the feed pauses with "PACKER FULL — clear the outfeed" |
| Travel | each piece is an instanced 0.17 m ore chunk (emissive ore colour × 2, so it glows through the glass) moving along the route polyline at **4 m/s**: 18 s from belly to packer |
| Bio | the bio-tank empties at 0.5 FU/s as green blobs along the bio pipe; each blob adds its FU to the reserve when it reaches the vat |
| Finish | hold empty and no pieces in the pipe: boom decouples (0.6 s), carousel unlocks, toast with the totals |
| Interrupt | `Space` (launch) during the feed: decouple first (0.6 s); pieces already in the pipe keep going; the rest stays in the hold |

**Hand intake**: `AFixtureIntakeHatch` on the riser at (−22.8, 8.4, −6.3). `E`: "Deposit ore (n)" sends the
suit's ore pieces into the ore pipe one per 0.45 s; "Deposit biomass (n)" sends fauna items into the bio pipe.
The vat has the same biomass intake.

### 6.4 The packer and ore boxes (U13)

`AFixturePacker` in the cargo bay at (18.6, −5.0), 2.4 × 3.0 × 2.4 m, with four **outfeed slots** on its aft
face at x 17.0, y −6.2 / −5.4 / −4.6 / −3.8, 0.9 m above the floor.

- Pieces drop from the pipe into the **buffer** (max 24), shown through a glass panel.
- The packer moves one piece per 0.3 s from the buffer into the **partial box** of its ore type (three partial
  boxes, one per type, each shown as a 6-dot gauge on the console).
- When a partial box reaches **6 pieces** and an outfeed slot is free: 1.5 s packing animation, then an
  `ADescentOreBox` appears in the lowest free slot. If no slot is free the full partial waits and pieces of
  that type stay in the buffer.
- Console (`E`): shows buffer, the three gauges and the slots; button **EJECT PARTIALS** pushes every non-empty
  partial out as a part-filled box (needs free slots).

`ADescentOreBox`: 0.6 × 0.4 × 0.4 m crate; one ore type; `Count` 1..6; a colour band and a text label
(`FERRITE ×6`). It is always in exactly one place: a socket, the floor (attached to the carrier), a robot
arm's gripper, or the player's hands.

**Box sockets** (`FBoxSocket { Owner, LocalTransform, Rank, Accepts(Box) }`) are the common interface for
packer outfeed slots (rank 0, output only), rack slots (rank 1), and refinery hoppers (rank 2, input only).

### 6.5 The refinery (U14, by hand)

`APlaceableRefinery` (3.2 × 3.2 × 3.2 m, a furnace with a glowing slit, one **hopper socket** at chest height
on its front, a small console):

- The player carries a box to the hopper and presses `E` (§5.5). The hopper accepts the box if
  `Queue + Box.Count ≤ 12` *(v2 queue limit)*; the box's pieces join the queue and the empty crate disappears.
- One piece at a time: **14 s ferrite → ingot, 22 s cobalt → wafer, 34 s pearl → lattice** *(v2)*. The product
  goes to carrier storage; if storage is full the job waits at 100%.
- Console window: queue, progress bar, output counts. There is no "queue from storage" button any more: the
  only way in is a box.
- Sleeping (2 h) advances the refinery by 120 s *(v2)*.
- Several refineries work in parallel.

### 6.6 Automation: robot arms and racks (U14, upgrades)

The flow is upgradable while the game is in progress, in this order:

| Step | What the player builds (§6.7, placed with §6.10) | Effect |
|---|---|---|
| 0 | nothing | carry every box by hand: ≈ 30 m from the packer to the refinery's start position |
| 1 | — (free) | pick the refinery up and place it in the cargo bay, next to the packer |
| 2 | Box Rack | 4 buffer slots (rank 1) anywhere |
| 3 | Handling Arm Mk I | reach 3.2 m, one box every 4.0 s |
| 4 | Handling Arm Mk II | reach 4.5 m, one box every 2.5 s |
| 5 | second Refinery | parallel processing |

`APlaceableRobotArm`: base, yaw joint, shoulder, elbow, wrist and gripper are **separate components with their
origins on their axes** (blockout boxes and cylinders; a user model can replace them part for part). Floor or
ceiling mounted. Logic, evaluated when idle:

1. Collect sockets within reach (horizontal distance base → socket ≤ reach, |Δz| ≤ 2 m).
2. Among occupied sockets that are outputs or buffers, take the one with the **lowest rank** whose box is
   accepted by some empty socket of **higher rank** within reach; target = the highest-rank such socket.
3. Run the cycle: reach and grip (25%), swing (50%), place (25%). The joint angles come from two-link inverse
   kinematics in the vertical plane through base and target; they are visual only, the transfer is timed.
4. `E` on the arm toggles its power and shows its status (`IDLE — nothing in reach`, `IDLE — no free target`,
   `MOVING FERRITE ×6`).

Because boxes only move to a higher rank, arms can be chained through one rack (outfeed 0 → rack 1 → hopper 2)
and can never loop. Longer chains are out of scope.

### 6.7 Fabricator and recipes

`APlaceableFabricator` (2.2 × 1.6 × 1.8 m). `E` opens the window, tabbed by category, two columns of rows (icon,
name, description, cost chips, BUILD). Cost comes from storage and the cargo ledger. Build time 2 s, chime.

| Cat | Recipe | Cost | Effect |
|---|---|---|---|
| SUBMERSIBLE | Hull Reinforcement | 3 Ingot | Tender `HullMax` ×1.5 |
| | Depth Module Mk I | 3 Ingot, 2 Wafer | rating 2,300 → 2,700 m |
| | Depth Module Mk II (needs Mk I) | 3 Wafer, 2 Lattice | → 3,150 m |
| | Power Cell II | 2 Ingot, 2 Wafer | capacity ×1.7 |
| | Thruster Upgrade | 3 Ingot, 1 Cobalt | speed +25% |
| | Sonar Module | 2 Wafer | ping 260 m; flags honest voids red |
| MINING | Drill Head Mk II | 3 Ingot | radius +0.7 m, rate +50% |
| | Drill Head Mk III (needs II) | 2 Ingot, 2 Wafer, 1 Lattice | again |
| | Laser Cutter | 2 Wafer, 1 Lattice | alternative tool head (`T`) |
| | Suction Mk II | 2 Ingot, 1 Cobalt | range 22 m, pull 16 |
| | Hold Expansion | 3 Ingot | every hold +8 |
| CARRIER | Carrier Hull Patch (repeatable, only below 99.5%) | 4 Ingot, 1 Wafer | carrier hull +25 |
| EXPLORATION | Handheld Sonar | 1 Ingot, 1 Wafer | tool |
| | Flares ×5 | 2 Ferrite | consumable |
| | Marker Beacons ×2 | 1 Ingot, 1 Cobalt | consumable |
| | High-Capacity O₂ Tank | 2 Ingot | 90 s |
| | Ultra O₂ Tank | 1 Ingot, 1 Wafer, 1 Lattice | 150 s |
| | Sea-Glide Propulsor | 2 Ingot, 1 Wafer | tool |
| BUILD *(new, each gives one kit)* | Storage Locker | 4 Ingot | +40 storage while placed |
| | Box Rack | 2 Ingot | 4 box slots |
| | Handling Arm Mk I | 4 Ingot, 2 Wafer | §6.6 |
| | Handling Arm Mk II (needs one Mk I built) | 2 Ingot, 2 Wafer, 1 Lattice | §6.6 |
| | Work Light | 1 Ingot | wall or ceiling lamp |
| | Table / Chair / Shelf | 1 Ingot each | furniture |
| | Bunk / Couch | 2 Ingot each | bunk: sleep anywhere |
| | Fabricator | 6 Ingot, 2 Wafer | a second fabricator |
| | Refinery | 8 Ingot, 3 Wafer | a second refinery |
| WEAPONS | Harpoon Sidearm | — | locked row: "Tethys has not licensed weapons" |

### 6.8 Selling, debt, crush depth

- **Tethys terminal** (cargo bay): sells refined goods from storage (1 or all) and raw ore **by the box**
  ("FERRITE ×6 — 360 cr [SELL]"; the box is collected by a wall chute and disappears). Credit comes off the
  debt. Values in §6.1.
- Fees *(v2)*: nutrient feed 12 cr; recovery 900 cr; implosion 4,800 cr.
- **Crush depth**: Tender ratings 2,300 / 2,700 / 3,150 m; carrier 3,250 m; damage `(0.6 + over/25)` HP/s.
  The first chokes of both upper routes (SA at 2,130 m, BRING at 2,230 m) are inside the base rating; the
  Great Void needs Mk I; the Undercroft, the Sieve's lower half and the Seam Gallery need Mk II. Cobalt (for
  Mk I) occurs above 2,300 m; pearl (for Mk II) occurs above 2,700 m (§2.12).

### 6.9 Biomass, feeding and fauna (U2, U3)

**The carrier's nutrient reserve is finite.**

| Item | Value |
|---|---|
| Unit | FU (feed unit). **1 FU = 25 points of nutrition = 10 minutes of life** at the U2 drain rate |
| Reserve | `UCarrierSystemsComponent::BiomassFU`, capacity **20 FU**, **starts at 6 FU** |
| Vat | `AFixtureVat` in the galley at (21.2, 6.0): a glass tank, radius 0.9 m, 2.8 m tall, whose green liquid level **is** the reserve (level = FU/20); a ring gauge and `BIOMASS 6.0 / 20 FU` on its front. It also takes fauna items by hand |
| Jack-in feed | the 4.8 s wall-plug sequence of v2 (approach 0–0.7 s, feed 1.0–4.1 s, release at 4.8 s). `target = min(100, n0 + 25·Reserve)`; the feed raises nutrition from `n0` to `target` and consumes `(target − n0)/25` FU; 12 cr is billed |
| Empty reserve | below 0.1 FU the port ring turns red, the plug does not engage, radio: "Nutrient reserve empty. The sea is full of protein, contractor." |
| HUD | on foot the vitals panel shows a small `BIO 6.0` readout; below 2 FU it turns amber, at 0 red |

**Collecting fauna:**

| Fauna | Where | Value | How it is collected |
|---|---|---|---|
| Silverfin (schools of 26) | 5 school homes above Z −400: canyon (150, 20, −90), (450, 10, −150), (700, −30, −200); H1 centre; Wreck Hollow | 0.10 FU | Tender suction (§4.5): fish inside the suction cone are pulled in and captured within 1.6 m of the nozzle → bio-tank |
| Lanternfish (schools of 26, glowing) | 9 homes: Lantern Grotto ×2; Great Void (500, −200, −680), (760, −300, −720), (640, −420, −640); Sieve (480, −700, −900); Undercroft (850, −400, −1,010), (1,000, −480, −1,040); Seam Gallery centre | 0.15 FU | suction |
| Jellies (90, drifting) | chambers and tubes *(v2 placement)* | 0.60 FU | suction, or by hand while swimming (`E` within 2.6 m) |
| Lantern polyps (sessile, glowing, clusters of 3–6) | wall points: Lantern Grotto 25 clusters, H1 10, Great Void 15, Undercroft 10 | 0.40 FU | by hand (`E` within 2.6 m), or suction within 6 m |

- Tender bio-tank: 4.0 FU. When full, fauna is not captured ("BIO-TANK FULL").
- Schools: v2 boids (`05_life.js updateFish`: cohesion 0.35, target 0.25, alignment 0.6, separation, flee
  within 10 m of a Tender or swimmer, wall avoidance by density look-ahead, speed 1.0..3.6·(0.8 + 0.3·scale));
  fish stay within 45 m of their home. Only the 6 nearest homes within 220 m of the player are simulated and
  drawn (one instanced mesh per species). Each home keeps a persistent `Alive` count; it regrows +1 per 30 s
  while the player is more than 100 m away. Polyps regrow after 600 s.
- **No fauna inside the hull (U6).** Every fish, jelly and spawn point is tested in carrier-local space: a
  target or spawn within `HullRadius(x) + 6` is rejected; a fish within `HullRadius(x) + 3` is steered
  radially outward (acceleration 30 × penetration); a fish found inside `HullRadius(x) + 0.5` is projected
  out in the same step. The moon-pool shaft lies inside that radius, so nothing swims up it. The same test
  with a 3 m sphere applies to Tenders, except for fish currently being sucked in. The `fauna` state section
  reports `inside_hull`, which must be 0.
- Flora (cosmetic, `Life/DescentFlora.*`, port of `buildFlora`): instanced fronds and tube clusters placed on
  up-facing rock found by marching to the wall, denser above Z −200; bioluminescent clusters deeper, each a
  light-pool request (intensity ≈ 1.0, radius 8 m). Carving removes flora within `DrillR + 1` of the hit.
  Fauna, flora and jellies are spawned only for the regions near the player (same 220 m rule as schools).

### 6.10 Build and placement mode (U1)

`UDescentBuildComponent`. Everything the player crafts in the BUILD category is a **kit** in carrier storage;
placing it turns the kit into an `ADescentPlaceable` in the world; picking it up turns it back into a kit.
The start fabricator, refinery and furniture are placeables too (§3.4).

| Kit | Size x × y × z (m) | Mounts on | Function |
|---|---|---|---|
| Fabricator | 2.2 × 1.6 × 1.8 | floor | §6.7 |
| Refinery | 3.2 × 3.2 × 3.2 | floor | §6.5 |
| Storage Locker | 0.8 × 1.2 × 2.3 | floor | +40 storage |
| Box Rack | 1.4 × 0.5 × 1.0 | floor | 4 sockets, rank 1 |
| Handling Arm Mk I / II | 0.6 × 0.6 × 1.2 base | floor or ceiling | §6.6 |
| Work Light | 0.3 × 0.3 × 0.15 | wall or ceiling | point light, radius 8 m, channel 1 |
| Table, Chair, Shelf, Couch | 1.4 × 0.9 × 0.78; 0.5 × 0.5 × 0.9; 1.2 × 0.4 × 2.0; 3.4 × 1.0 × 0.8 | floor | furniture |
| Bunk | 2.1 × 1.0 × 0.6 | floor | sleep |

Flow:

1. **`B`** on foot (not carrying): the build menu (neumorphic list with icon, name, count in storage). Pick a kit.
2. **Ghost**: a translucent hologram of the object follows the aim. Trace from the eye, 6 m, channel
   `Placement`. Colour **green #72e3a5 when valid, red #ff6b57 when not**, with the reason under the crosshair.
3. **Snapping**: position snaps to a 0.25 m grid in carrier-local space (hold Alt for free placement). Rotation
   about the surface normal in 15° steps with the mouse wheel or Q / E. Wall items align their back to the wall.
4. **`LMB`** confirms (kit −1, the object appears, attached to the carrier). **`RMB`** or Esc cancels.
5. **Pick up**: look at a placeable and hold `E` for 0.8 s → kit +1.

Validity rules (all must hold; the first that fails is the reason shown):

| # | Rule |
|---|---|
| 1 | The hit is on the carrier interior and its normal matches the kit's mount: floor `n·up > 0.9`, wall `abs(n·up) < 0.2`, ceiling `n·up < −0.9` |
| 2 | The whole footprint is inside one room of `FCarrierLayout` (rooms and corridors both count) and inside the dry volume |
| 3 | Not in a keep-out zone: 1.2 m in front of and behind every door (door width + 0.4 m); stair ramps and landings; the pool rectangle grown by 0.6 m; the hoist column; in the bay, anything reaching above carrier z −3.5 within 9.0 m of the hub axis (Tender sweep); the helm (x 43..46.6, y ±1.8); 1.0 m around each nutrient port; 1.2 m in front of the packer outfeed; fixture bodies |
| 4 | The object's box, shrunk by 2 cm, overlaps nothing that blocks (`OverlapMultiByChannel` with a box shape): walls, fixtures, other placeables, ore boxes, the player |
| 5 | Floor items: all four corners find the floor within 5 cm (no overhang over the pool or a stair edge) |
| 6 | At most 200 placed objects |

Pick-up is refused, with a reason, when: a refinery has a queue or a box in its hopper; a rack or arm holds a
box; removing a locker would leave storage over capacity; a fabricator is mid-build.

On placement an object registers with the systems it serves (box sockets with the cargo subsystem, locker
with storage, lamp with the light list) and unregisters on pick-up. Placeables render custom-depth stencil 1.
Placement is limited to the carrier's interior in this version.

### 6.11 Hand tools, flares, sleep *(v2)*

| Tool | Use |
|---|---|
| Flashlight | toggle (LMB with it selected, or `F`). Spot, radius 55 m, cones 12° / 20.6°, start intensity 2.0, casts shadows, lights channels 0 and 1 |
| Handheld Sonar | swimming only: ping 90 m, 900 rays, 3 s cooldown |
| Flare | swimming only: thrown at 7 m/s; gravity −0.35 m/s², drag `exp(−0.8·dt)`; rests on rock; burns 120 s as a pooled light (radius 26 m, intensity 3.2, flickering, fading over its last 10 s); at most 6 alive |
| Marker Beacon | swimming only: drops a marker (map and HUD), amber blink every 1.5 s |
| Propulsor | hold LMB: 7.5 m/s |

Sleep (bed or bunk): fade 1.2 s; +2 h on the clock; refinery +120 s; health 100; nutrition −10 (not below 8);
docked Tenders fully charged and repaired; **autosave**; wake after 2.4 s.

### 6.12 Saving

`UDescentSaveGame` in slot `descent_0` (`UGameplayStatics::SaveGameToSlot`). Written on sleep, on every dock,
and from the pause menu; loaded by "Continue" on the title card.

| Block | Content |
|---|---|
| Player | vitals, inventory, hotbar, equipment, flags (radio lines already played), logs found |
| Economy | debt, storage counts, upgrades |
| Carrier | position, yaw, hull, power, biomass FU, carousel angle |
| Tenders | per Tender: docked or world transform, hull, power, hold order, bio-tank |
| Placeables | class id, carrier-local transform, state (refinery queue and progress, arm power) |
| Boxes | type, count, socket id or carrier-local transform; packer buffer and partials |
| Terrain | every chunk with `bModified`: key, density quantised to int16 (step 4/32767), cut bits, compressed with `FCompression::CompressMemory(NAME_Zlib, …)`; per-deposit `Mined` |
| Map | the survey bitset (§8.2), compressed; markers |
| Horror | timers and one-shot flags; ending state |

The player always loads on foot in the bed's room; an undocked Tender is restored where it was left.

---

## 7. Look (V1, V10, U6, U12)

### 7.1 The model in one paragraph

There is no sky, no sky light and no global illumination. A pixel is lit only by: local lights with a soft
art-directed falloff; a "surface sun" that exists only near the top of the Throat; a small ambient term inside
the materials; emissive surfaces; and one post-process material that turns distance into water (per-channel
absorption, then fog toward the water colour). Exposure is manual and fixed. This is v2's model
(`01_core.js`), it is deterministic, and it lets a test measure "dark but readable" from a PNG.

All shared values go through one material parameter collection, `MPC_Descent`, written once per frame by
`ADescentEnvironment` (`UKismetMaterialLibrary::SetScalarParameterValue / SetVectorParameterValue`):

| Parameter | Meaning |
|---|---|
| `Time` | sim time |
| `SurfaceLight` | `L(Z_camera)` (§2.7) |
| `FogDensity` | `ρ = 0.015 + 0.006·(1 − L)`; × 0.3 in helm camera views 1–4 *(v2)* |
| `WaterTop`, `WaterDeep` | linear (0.028, 0.275, 0.323) and (0.0018, 0.0159, 0.0232) (sRGB #2f8f9a, #06222a) |
| `SunDir` | normalised (−0.12, 0.20, 1.0) (direction **to** the sun) |
| `AmbientWaterSky`, `AmbientWaterGround`, `AmbientDry` | §7.3 |
| `Pulse`, `FloorGlow`, `HullRim` | heartbeat pulse 0..1.6, Floor glow 0..1.2, helm-view hull rim 0..1 |
| `CarrierOrigin`, `CarrierFwd`, `CarrierUp` | for the hull-capsule test in particle materials |
| `BeamPos`, `BeamDir`, `BeamAmt` | the player's own lamp, for marine snow |
| `ShearVel` | Shear velocity at the camera, for snow streaks |
| `Jack`, `Hunger`, `Damage`, `Fade`, `Flash`, `FlashColor`, `Glitch`, `Pressure`, `Grain` | screen effects (§7.6) |

### 7.2 Water: the post-process material `PP_Water`

Domain Post Process, blendable location **`BL_SceneColorBeforeDOF`** (it runs on HDR scene colour before
translucency is composited, so cockpit glass, pipes and sonar points are not fogged twice). One `Custom` node
(port of `GLSL_WATER` / `FOG_FRAG`):

```
// inputs: Scene = PostProcessInput0.rgb, Depth = SceneDepth (uu), Stencil = CustomStencil, Dir = normalised camera-to-pixel vector
if (Stencil == 1) return Scene;                               // dry pixel: no water at all (§7.4)
d   = min(length(camera-to-pixel), 1500 m)                    // metres along the view ray; sky pixels = 1500
abs = exp(-d * FogDensity * float3(3.2, 1.05, 0.8));          // red dies first
fog = 1 - exp(-pow(d * FogDensity, 1.35));
up  = Dir.z * 0.5 + 0.5;
wc  = lerp(WaterDeep, WaterTop, smoothstep(0.2, 1.0, up)) * (0.03 + 0.97 * SurfaceLight);
wc += float3(0.25, 0.62, 0.65) * pow(saturate(dot(Dir, SunDir)), 6) * SurfaceLight * 0.35;
wc += float3(0.35, 0.06, 0.22) * smoothstep(-0.2, -1.0, Dir.z) * FloorGlow * (1 + 2 * Pulse);   // the Floor, far below
return lerp(Scene * abs, wc, fog);
```

World materials that are translucent and far from the camera (jellies, the leviathan's photophores, beam
cones) apply the same two lines themselves through a material function `MF_WaterFog`.

Volumetric light beams come from `UExponentialHeightFogComponent` with volumetric fog. It is used **only** for
in-scattering of local lights; its own haze is kept negligible so it does not double the post-process fog:

| Setting | Value |
|---|---|
| `FogDensity` | 0.02 (≈ 0.002 per metre), `FogHeightFalloff` 0.001, `FogInscatteringColor` black, `FogMaxOpacity` 1 |
| `SetVolumetricFog(true)`, `VolumetricFogExtinctionScale` | 4.0 |
| `VolumetricFogAlbedo` | (140, 215, 225) |
| `VolumetricFogScatteringDistribution` | 0.2 (close to isotropic, so the player's own beam is visible from behind it) |
| `VolumetricFogDistance` | 12,000 uu |
| `VolumetricFogStartDistance` | 200 uu in a Tender cockpit, 50 uu swimming |

### 7.3 Ambient

Every opaque material is an instance of `M_DescentSurface` and adds, as emissive,
`BaseColor × lerp(AmbientWater(N), AmbientDry, AmbientMix)`:

- `AmbientWater(N) = lerp(AmbientWaterGround, AmbientWaterSky, 0.5 + 0.5·N.z)`, with
  `AmbientWaterSky = (0.35 + 0.1L, 0.62 + 0.1L, 0.66) × (0.015 + 1.25·L) / π` and
  `AmbientWaterGround = (0.03, 0.05, 0.06) × (0.015 + 1.25·L) / π` *(v2 hemisphere light)*. At depth this is
  0.5% of albedo: black to the eye, which is the point of V1.
- `AmbientDry = (0.95, 0.90, 0.82) × 0.06 × HullFlicker` for carrier interiors, placeables and boxes
  (`AmbientMix = 1`). Room lamps do the rest.

Metal and glass get a fake environment reflection (v2 `envTex`): a small cube map `T_DescentEnv` generated by
`Tools/make_materials.py` (dark teal gradient with two soft highlights), sampled along the reflection vector
and scaled by fresnel × the instance's `EnvReflect` (0.15–1.2) × `(0.2 + 0.8·SurfaceLight)` outside or × 0.6
inside. Real screen-space reflections add to it.

### 7.4 Dry interior: how water effects stay out of the hull (U6)

`ADescentEnvironment` computes `EDescentEnv` once per frame from the camera position:
**Dry** if `Carrier->IsDry(CarrierLocal(Camera))`, otherwise **Water** (this includes a Tender cockpit, which
is dry air surrounded by water and is handled by the stencil and the fog start distance).

| Effect | In Water | In Dry |
|---|---|---|
| `PP_Water` | on for every pixel whose custom stencil ≠ 1 | still on, but **all interior pixels have stencil 1** and pass through untouched; sea seen through a window or the moon pool (stencil 0) is still fogged, so it still looks like sea |
| Volumetric fog | on | **off** (`SetVolumetricFog(false)`, `FogDensity` 0), blended over 0.3 s. The flood beam seen from the bridge is a separate additive cone mesh, as in v2 |
| Marine snow | on | particles inside the hull capsule or inside a Tender cockpit sphere are collapsed to zero size in the material, from any viewpoint; the component is hidden entirely when Dry and the camera is more than 6 m from every window and from the pool |
| Caustics, light shafts | on near the top | never on interior materials (the sun is on lighting channel 0 only) |
| Fauna | §6.9 | never inside the hull or the pool shaft |
| Screen "wet" effects (bubbles, breath, low-pass audio) | swim only | off |
| Moon pool | — | the only water inside: a translucent rippling surface at carrier z −8.3 (`M_PoolWater`, port of the v2 pool shader, opacity 0.86), plus 14 falling drip particles near it |
| Temperature | water temperature | 26.0 °C (§3.3) |

Custom depth with stencil 1 is set on: all room meshes, fixtures, placeables, ore boxes, pipes and their
contents, the pool rim, the character's first-person arm, the cockpit interior, seat and dash of the Tender
being piloted, and the helm console.

### 7.5 Lights and the "dark but readable" rule

All gameplay lights use **`bUseInverseSquaredFalloff = false`** with `LightFalloffExponent` 3 (attenuation
`(1 − (d/R)²)³`). This removes the v2 open item "the Tender lamp is too bright within about 8 m": near
surfaces get the same illuminance as surfaces at 15 m, and the range ends softly at `R`. Intensities below are
unitless start values; the calibration scenario fixes them (§7.10).

| Light | Type | R (m) | Cone inner / outer | Colour | Start intensity | Shadows | Vol. scattering | Channels |
|---|---|---|---|---|---|---|---|---|
| Tender headlamp | spot | 90 | 14.5° / 26.4° | #e6f6ff | 3.2 | yes | 1.0 | 0, 1 |
| Flashlight | spot | 55 | 12° / 20.6° | #fff2dc | 2.0 | yes | 0.8 | 0, 1 |
| Carrier flood | spot | 160 | 13° / 24° | #dff4ff | 5.0 | yes | 1.2 | 0 |
| Carrier nav lights (4) | point | 9 | — | red, green, white | 0.4 | no | 0.2 | 0 |
| Pool glow | point | 20 | — | (0.55, 0.85, 0.9) | 1.4 | no | 0.3 | 0 |
| Helm feed lights (8, external views only) | point | 48 | — | (0.55, 0.85, 0.95) | 1.15 | no | 0 | 0 |
| Room lamps (§3.3) | point | 11 / 16 | — | per room | 0.9–1.5 | no | 0 | 1 |
| Surface sun | directional | — | — | #9fd8d0 | `1.6 × L(Z_camera)`; hidden when `L < 0.02` | yes | 1.0 | 0 |
| Pooled lights (below) | point | per use | — | per use | per use | no | 0.3 | 0 |

`UDescentLightPool`: 24 shadowless point lights. Systems register requests each frame
`{position, colour, intensity, radius, priority}`; the pool keeps the 24 with the lowest
`distance²/radius² − priority` (and only those below 9), as v2 `commitVL` did with 14. Users: flares
(3.2, 26 m, prio 0.6), drill glow (1.6, 9 m, 1), bioluminescent clusters (≈1.0, 8 m, −0.3), jellies (0.5·s,
7·s m, −0.2), dead beacons (0.8, 10 m), player beacons (0.9 blink, 12 m), refinery glow (1.2, 7 m), ore box
strips, sonar transducer flash.

All lamps the player owns are multiplied by the horror flicker (§8.3).

### 7.6 Post-process settings (one unbound `UPostProcessComponent` on `ADescentEnvironment`)

Field names from `FPostProcessSettings` (`Engine/Classes/Engine/Scene.h`); set the matching `bOverride_` flag for each.

| Setting | Value | Note |
|---|---|---|
| `AutoExposureMethod` | `AEM_Manual` | fixed exposure: a dark scene stays dark |
| `AutoExposureApplyPhysicalCameraExposure` | false | |
| `AutoExposureBias` | 0.0 (cvar `descent.Look.ExposureEV`) | calibrated once in §7.10 |
| **`BloomMethod`** | `BM_SOG` | **U12 bloom rework** |
| **`BloomIntensity`** | **0.15** × `descent.Look.Bloom` (default 1.0, range 0..2; also a "Bloom" slider in the pause menu) | engine default 0.675; v2 used strength 0.7 |
| **`BloomThreshold`** | **1.2** | engine default −1 (everything blooms); only real emitters bloom now |
| **`BloomSizeScale`** | **2.0** | engine default 4 |
| `BloomDirtMaskIntensity`, `LensFlareIntensity` | 0 | |
| `VignetteIntensity` | 0.45 | |
| `FilmGrainIntensity` | 0.15 | |
| `SceneFringeIntensity` | 0.2 | |
| `AmbientOcclusionIntensity` / radius | 0.5 / 60 uu | helps the interior blockout read |
| `MotionBlurAmount` | 0 | |
| Blendables | `PP_Water` (weight 1), `PP_ScreenFX` (weight 1) | |

Emissive budget, so that bloom never smears readable things: dashboards, HUD-in-world and signs ≤ 1.0 (below
the threshold: **text never blooms**); ore veins ≤ 1.0 with sparkle peaks 2.0; nav lights and beacons 3;
lamp lenses 6; sonar points ≤ 2.5 during their first-second flash.

`PP_ScreenFX` (`BL_SceneColorAfterTonemapping`): port of the v2 `fxPass` shader in one `Custom` node: warp,
chromatic split `0.0012 + 0.012·max(Jack, Glitch) + 0.005·Hunger + 0.01·Damage`, glitch slices, jack-in tint
and scanlines, hunger desaturation and breathing vignette, damage red vignette, flash colour, grain, fade.

### 7.7 Marine snow, shafts, caustics

- **Marine snow** (`UDescentMarineSnowComponent`): 3,200 instanced quads (1,500 on the low preset) seeded in a
  40 m cube. Material `M_MarineSnow` (unlit, additive): world position offset wraps each mote into the cube
  around the camera (`CamPos + (frac((P − CamPos)/40 + 0.5) − 0.5)·40`), faces the camera, 2.5–6 cm; brightness =
  surface light + beam term (`pow(saturate(dot(dirFromBeam, BeamDir)), 6)·BeamAmt`, with distance falloff) +
  0.02; stretched along `ShearVel`; **zero size inside the hull capsule or a cockpit sphere**.
- **Light shafts**: free with the surface sun's volumetric scattering and shadowing by the canyon walls;
  present only where `L > 0.02` (Z above about −226).
- **Caustics**: a light-function material `M_Caustics` on the surface sun (port of `causticPat`), strength
  `1.3·L²`.

### 7.8 Terrain material `M_Terrain`

Opaque, default lit, world-space normal (tangent-space normal off). Inputs: vertex colour (rock colour, alpha =
cut), `UV0` (ore type, strength), `UV1.x` (basalt). `Custom` nodes port the v2 terrain shader
(`04_terrain.js:11–39`):

| Output | Rule |
|---|---|
| Base colour | `VertexColor × (0.72 + 0.5·strata)`, `strata = 0.55·vnoise(0.42·Z, 0.015·X, 0.015·Y) + 0.45·vnoise(0.31·P)`; fresh cuts cooler: `lerp(c, c·(0.75, 0.82, 0.9), 0.5·cut)`; ore: `lerp(c, OreColour·(0.35 + 0.65·facet), 0.85·smoothstep(0.05, 0.6, strength))`, `facet = hash(floor(2.2·P))`; basalt: `lerp(c, (0.012, 0.014, 0.018), basalt)` |
| Normal | vertex normal perturbed by the gradient of `vnoise(0.55·P)·0.28 + vnoise(2.1·P)·0.10`; on ore, per-facet random normals × 0.9; on basalt, hexagonal jointing lines |
| Roughness | 0.9; ore 0.18; basalt 0.25 |
| Emissive | ambient (§7.3) + ore glow `OreColour × smoothstep(0.1, 0.8, strength) × (0.05 + 0.1·sin(1.3·Time + phase) + 1.5·sparkle)`, `sparkle = pow(hash(cell + floor(0.7·Time)), 18)` |

Ore glow colours: ferrite (1.0, 0.45, 0.12), cobalt (0.15, 0.75, 1.0), pearl (1.0, 0.25, 0.8) *(v2)*.

### 7.9 Materials and how they are made

`Tools/ue/make_materials.py` (re-runnable, called by `Tools/import_assets.ps1` next to the existing
`import_assets.py`; `unreal.MaterialEditingLibrary`: `create_material_expression`, `connect_material_property`,
`connect_material_expressions`, `recompile_material`, `set_material_instance_*_parameter_value`) creates
everything under `/Game/Materials/`. Each master is a handful of nodes around `MaterialExpressionCustom`
blocks whose HLSL is kept in `Tools/ue/shaders/*.ush.txt`, so the look is text under version control.

| Asset | Kind | Used by |
|---|---|---|
| `MPC_Descent` | parameter collection | everything |
| `M_DescentSurface` (+ instances) | opaque lit; parameters `BaseColor`, `Metallic`, `Roughness`, `Emissive`, `AmbientMix`, `EnvReflect`, `PanelScale` (procedural panel lines and rivets from local position, 0 = off), `Hazard` (stripes) | carrier hull, rooms, fixtures, placeables, boxes, Kazah |
| `M_Terrain` | §7.8 | rock |
| `M_DescentGlass` (+ `MI_KazahGlass`, `MI_PipeGlass`, `MI_WindowGlass`) | translucent, surface per-pixel lighting, screen-space reflections on; opacity `lerp(0.06, 0.45, fresnel³)`; refraction index 1.03; tint; `EnvReflect` | canopy (V10: real glass, interior visible through it), pipes, windows |
| `M_PoolWater` | translucent, animated ripple | moon pool |
| `M_Emissive` (+ instances) | unlit | lamps, screens, nav lights, strips |
| `M_Hologram` | translucent unlit, fresnel, colour parameter | build ghost (green / red) |
| `M_OreChunk`, `M_Fish`, `M_Jelly`, `M_Polyp`, `M_Leviathan` | lit / translucent with `MF_WaterFog` | loose ore, fauna, the leviathan |
| `M_MarineSnow`, `M_SonarPoint`, `M_SonarShell`, `M_BeamCone` | unlit additive | particles, sonar, beams |
| `M_Caustics` | light function | surface sun |
| `PP_Water`, `PP_ScreenFX` | post process | §7.2, §7.6 |
| `T_DescentEnv` | cube map | reflections |

Kazah materials: M0's `import_assets.py` already makes `/Game/Vehicles/Kazah/Materials/MI_<material>` (14
instances) on its own masters `M_Kazah_Opaque` and `M_Kazah_Glass`. **In M1 re-parent them** to
`M_DescentSurface` (`AmbientMix` 0) and `M_DescentGlass`, keeping the instance names and paths, so the Tender
gets the ambient term, the environment reflection and the same glass as the rest of the game; then delete the
two M0 masters. Reference values read from the `.blend` (base colour linear, metallic, roughness), to check
the manifest against; the numbered Blender duplicates (`.001`, `.003`, …) are the same material:

| Blender material | Base colour | Metal | Rough | Extra |
|---|---|---|---|---|
| Pearl ceramic lacquer | (0.638, 0.711, 0.674) | 0.18 | 0.31 | the paint colour overridden per Tender (§4.1) |
| Cabin ivory | (0.367, 0.448, 0.448) | 0.04 | 0.58 | |
| Cockpit titanium frame | (0.133, 0.223, 0.253) | 0.65 | 0.36 | |
| Deep ocean enamel | (0.015, 0.068, 0.089) | 0.35 | 0.32 | |
| Marine teal enamel | (0.025, 0.155, 0.187) | 0.25 | 0.32 | |
| Graphite machinery | (0.020, 0.030, 0.040) | 0.82 | 0.32 | |
| Satin titanium | (0.342, 0.420, 0.462) | 0.92 | 0.29 | `EnvReflect` 0.8 |
| Impeller alloy | (0.133, 0.187, 0.214) | 0.94 | 0.26 | `EnvReflect` 0.8 |
| Recessed seams | (0.006, 0.011, 0.013) | 0.45 | 0.55 | |
| Rubber seals | (0.004, 0.006, 0.007) | 0.02 | 0.76 | |
| Safety burnt orange | (0.787, 0.113, 0.010) | 0.22 | 0.35 | |
| Optical cyan | (0.010, 0.107, 0.163) | 0.35 | 0.13 | emissive (0.007, 0.263, 0.434) × 0.35 |
| Headlight crystal | (0.492, 0.807, 0.955) | 0 | 0.10 | emissive (0.367, 0.748, 1.0), 6 on / 0.1 off |
| Clear blue canopy | → `MI_KazahGlass`, tint (0.523, 0.869, 0.955), roughness 0.065 | | | |

### 7.10 Calibration and the luminance tests

Every screenshot gets a sidecar `Saved/Shots/<stem>.json` (§9.4) with `mean_luma`, `centre_luma` (mean over the
central 40% × 40% of the frame) and others, all on sRGB-encoded values in 0..1.

Calibration scenario `look_calibrate` (run once, then again whenever a light or the exposure changes): the
Tender at (640, −230, −700) in the middle of the Great Void, a flat grey test wall (albedo 0.30, 40 × 40 m)
spawned square to the lamp at 10 m, then 20 m, then 40 m; headlamp on; nothing else. Adjust
`descent.Look.ExposureEV` (and the lamp's intensity if needed) until the `centre_luma` values fall in the
bands below.

| Test (scenario) | Condition | Required |
|---|---|---|
| `look_calibrate` | grey wall at 10 m / 20 m / 40 m, lamp on | `centre_luma` 0.38–0.50 / 0.25–0.40 / 0.06–0.18 |
| `look_deep_lamp` | Tender in the Great Void 15 m from a rock wall, lamp on | `centre_luma` 0.06–0.35 *(v2 rule)* |
| `look_deep_dark` | same, lamp off | `mean_luma` < 0.03 |
| `look_near_wall` | Tender 6 m from a rock wall, lamp on | `centre_luma` ≤ 0.55 (v2 measured 0.57: "too bright") |
| `look_throat` | Tender at the start depth (Z −30), lamp off | `mean_luma` 0.05–0.25; light shafts visible |
| `look_rooms` | one shot per room, on foot | each `mean_luma` 0.10–0.45 |
| `look_bloom` (U12) | dry, a 0.30 m sphere with emissive 6.0 at 10 m in darkness | mean luma of the ring between 3 and 6 sphere radii ≤ 4% of the sphere's own luma; with `descent.Look.Bloom 0` ≤ 1%; a dash screenshot shows no glow around text |

---

## 8. Sonar, map, horror, audio, UI

### 8.1 Sonar *(v2 `09_sonar_map.js`)*

| Ping | Range | Rays | Cooldown | Cost | Origin |
|---|---|---|---|---|---|
| Tender (`R`) | 160 m (260 m with the Sonar Module) | 2,200 | 2.5 s | 1.5 energy units | `Chin_Sensor` |
| Handheld (`R` or LMB with the scanner) | 90 m | 900 | 3 s | swimming only | the eye |
| Helm (`R`) | 420 m | 4,200 | 4 s | — | carrier-local (40, 0, −10) |

- Directions: a Fibonacci sphere with a random rotation per ping. Rays are marched through `Density` from
  1.5 m with step `max(0.9, −0.95·d)`, **420 rays per sim step** (260 on the low preset) across all active pings.
- A hit creates a point born at `t0 + distance/170` (the 170 m/s reveal). Life **20 s**; it fades from 45%
  of its life to the end; in its first second it flashes ×3.5.
- Storage: ring buffer of 30,000 points in one `UInstancedStaticMeshComponent` (a 2-triangle quad), per-instance
  custom data `(BornTime, Kind)`; transforms and custom data are batch-updated once per frame. Material
  `M_SonarPoint`: unlit additive, **depth test disabled**, camera-facing, sized to 2–6 px on screen (contact
  kinds up to 60 px), colour cyan near → deep blue beyond 140 m; kind 1 (honest void, with the Sonar Module)
  pink-red; kind 2 (unknown contact) red; kind 3 (beacon) amber.
- Ping shell: an expanding icosphere, fresnel additive, radius `170·(t − t0)`, alpha `0.6·(1 − r/range)`.
- Every hit marks the survey map. A ping calls `UDescentHorrorSubsystem::OnSonarPing` (leviathan, beacons, ghosts).
- Contacts live 16 s; ghost contacts 2.2 s.

### 8.2 Survey map

`UDescentSurveyMap`: a 3D bitset over the claim box, cells **4 × 4 m in plan, 8 m tall** (473 × 365 × 220 bits,
4.7 MB), plus 2D `Visited` and `Flagged` (honest) layers and a marker list. `Mark(P, kind)` from sonar hits;
`Visit(P)` from the Tender, the swimmer and the carrier.

View `SSurveyMap` (PDA › SURVEY MAP, key `M`, or the bridge chart table): top-down. A transient 473 × 365
texture is rebuilt when the data or the slice changes: per column, the shallowest known cell inside the slice
gives the colour `HSL(0.52 − 0.32·t, 0.65, 0.50 − 0.18·t)`, `t = clamp((depth − 1,740)/1,460, 0, 1)`; flagged
cells red; visited-only cells grey at 35%. Slate overlays: 100 m grid; the dashed target circle at the Seam
Gallery with `TARGET STRATUM · 3,105 m (Tethys survey)`; carrier and YOU arrows labelled with depth; beacons
and player markers; unknown contacts as red rings; **place names that appear once any of their probe points
is known or visited** (chambers, wells, galleries; chokes in amber with a ◆); a depth legend. Controls: wheel
or ± zoom, drag to pan, `F` follow, **depth slice** slider: `AUTO` (reference depth ± 60 m, the default,
because the world now has four tiers stacked in plan), a fixed depth ± 40 m, or `ALL`.

### 8.3 Horror director *(v2 §4.9, depths rescaled)*

`dz = clamp((depth − 1,760)/1,400, 0, 1)`; `hallu = nutrition < 25 ? smooth(25, 5, nutrition) : 0`.

| Event | Trigger | Frequency | Effect |
|---|---|---|---|
| Hull creak | always | every 18–45 s ÷ `(1 + 2dz + 4·scrape + 4·crushing + 3·stress)`, ×2 below 30% carrier hull; `stress = clamp((carrierDepth − 2,900)/350, 0, 1.4)` | panned creak; inside the carrier a 0.05 shake half the time |
| Pressure groan | depth | every 40–80 s ÷ dz | groan |
| **Heartbeat from below** | always | every 80–100 s, echo after 1.4 s | strength `0.25 + 0.9dz`; `Pulse` → 1 (decays 0.35/s): the Floor glow and the water pulse; shake. First time below 1,900 m: radio "Did you feel that?" |
| Light flicker | random; forced 0.4 s when the leviathan is within 70 m | chance `dt/110·(1 + dz)`; lasts 0.6–1.6 s | every player-owned lamp × `flickerMul` (v2 formula) |
| **Leviathan** | camera in H1, H2, H3, G, or the canyon below Z −100, and not inside a vessel's dry volume | first time when depth > 1,905 m, then cooldown 160–320 s | 40 instanced segments, 3.8 m apart (≈ 150 m), radius up to 5.2 m, dark skin, two rows of faint cyan photophores; crosses 80–120 m ahead (55–75 m on a "near" pass) on a 520 m spline at 8.5 m/s with a slow vertical wave; a long call panned to its side; on sonar a red cluster of 26 points "UNKNOWN · MASSIVE". **Never attacks, never collides** |
| Sonar ghost | on any ping | 4% above 2,340 m, 14% deeper, 50% if nutrition < 25 | a red contact at 60–95% of the range that vanishes after 2.2 s |
| Dead beacons | Tender or swimmer within 24 m | once each (8) | red blinking beacon; the log types out at 55 characters/s and **cuts mid-sentence** with "[SIGNAL LOST]" and a static burst; added to PDA › LOGS and the map |
| Whispers | `hallu > 0` or depth > 2,700 m | every 25–45 s ÷ `(0.2 + 2·hallu + 0.4)` | formant-noise whisper; if `hallu > 0.3` a 0.5 s screen glitch |
| Phantom | `hallu > 0.2`, in the water | every 20–40 s ÷ hallu | a black humanoid with two pale eyes, 12–18 m ahead, for 0.35 s |
| False radio | `hallu > 0.4` | chance `dt/40` | a "?????" line that cuts out |
| Honest void | inside one | continuous | groans, alarms, damage, red warning |
| The Shear | above Z +10 | continuous | roar, snow streaks, warning (§2.11) |
| Ending | carrier origin inside the Seam Gallery ellipsoid × 0.7 and Z ≤ −1,290 | once | radio "Anchoring…"; `FloorGlow` ramps to 1.2 over 8 s; at 6 s a double heartbeat, a (0.8, 0.25, 0.6) flash, shake 1.2, radio "…Depth gauge reads 66.666 km. Disregard. Disreg" (cut); at 16 s the end card (hull %, balance, logs n/8, time), then play continues |

Rules *(v2)*: no jump scares; nothing harms the player except pressure, drowning, hunger and impacts; audio
carries the dread. Radio lines: keep the v2 texts (`10_player.js`, `13_main.js`), with these changes: `helm1`
describes mouse steering; `dock1`, `ore1` describe the pipes and the packer; new one-shot lines `shear1`,
`basalt1`, `bio0` (reserve empty), `box1` (first box packed: "Carry it to the refinery, contractor. Tethys does
not pay porters."), `arm1`.

### 8.4 Audio (V3)

Code first, no hand-made assets: `Tools/audio/gen_audio.py` (standard-library Python 3.14, fixed seeds) renders
every sound of the v2 cue list to 16-bit 48 kHz WAV in `SourceArt/Audio/`, and `Tools/ue/import_assets.py`
brings them in as `/Game/Audio/SW_<name>` (loops flagged looping). `UDescentAudioSubsystem` owns one `UAudioComponent` per loop and
sets volume, pitch and low-pass every frame (`SetVolumeMultiplier`, `SetPitchMultiplier`,
`SetLowPassFilterFrequency`); one-shots are spawned 2D with a pan, or 3D for world sources.

| Loop | Recipe to render *(v2 `02_audio.js`)* | Driven by |
|---|---|---|
| `drone` | two detuned saws 36 → 28 Hz through a low-pass | gain 0.05–0.16 with depth, halved inside; filter 140 → 80 Hz |
| `sea` | brown noise, low-pass 300 → 180 Hz | quieter inside |
| `hum` | 55 + 110 Hz | inside the carrier only |
| `tender_engine` | saw 60 Hz | pitch `1 + 0.1·speed`, gain with thrust |
| `prop_wash` | band noise 400 Hz | pitch and gain with speed |
| `carrier_engine` | 31 Hz saw + brown rumble | gain `abs(throttle)` |
| `drill`, `laser`, `suction` | saw + square + grind with 7 Hz tremolo; 880 / 441 Hz band; wobbling band noise | tool state |
| `scrape` | 13 Hz AM brown noise | `scrape` |
| `static` | high-pass noise | `hallu` |
| `shear` *(new)* | wide low noise with slow swell | Shear speed / 20 |
| `pipe_flow` *(new)* | soft rattle of pieces in a tube | pieces in the pipes, 3D along the corridor |

Master low-pass: 5,200 Hz in air, 2,400 Hz in a Tender, 1,300 Hz swimming *(v2)*.

One-shots *(v2)*: `ping` (1,180 / 1,192 / 2,360 Hz with 4 echoes), `creak`, `groan`, `clank`, `heartbeat`,
`bubble`, `breath`, `step`, `click`, `splash`, `alarm`, `jack`, `leviathan`, `whisper`, `radio_blip`,
`static_burst`, `thud`, `chunk`, `craft`; *(new)* `box_pack`, `box_place`, `arm_servo`, `pipe_clack`, `place_ok`,
`place_bad`, `vat_gurgle`.

Tests cannot hear, so the `audio` state section lists each loop's current volume, pitch and filter, and the
last 20 one-shots with their sim time (§9.3).

### 8.5 UI: neumorphic, in Slate (V13)

All UI is Slate (`SCompoundWidget` / `SLeafWidget` with `OnPaint`), added to the viewport with
`UGameViewportClient::AddViewportWidgetContent`. The same widgets are used on screen and, through
`UWidgetComponent::SetSlateWidget`, on the world dashboards.

**Tokens** *(v2)*: `bg` #1a1f26, `bg2` #1d232b, `hi` (light shadow) #262e39, `lo` (dark shadow) #0e1216, `txt`
#cfe3ec, `dim` #7f95a3, `cyan` #62d9e6, `amber` #f5b95a, `red` #ff6b57, `green` #72e3a5, `violet` #a58cff;
corner radius 16 px. Fonts: the engine's Roboto (`FCoreStyle::GetDefaultFontStyle("Bold" | "Regular" | "Mono", size)`).

**Shadows.** Slate has no blurred box shadow, so `FNeuStyle` generates four 9-slice textures at start-up
(`UTexture2D::CreateTransient`, 64 × 64, a rounded rectangle blurred with a Gaussian): outer soft (σ 7 px),
outer small (σ 3.5 px), inner soft, inner small. An **extruded** panel draws the dark shadow at (+6, +6) tinted
`lo`, the light shadow at (−5, −5) tinted `hi`, then the body (`FSlateRoundedBoxBrush`, `bg`). An **inset** well
draws the body in `bg2` and the inner-shadow texture (dark top-left, light bottom-right) on top.

| Widget | Look and behaviour |
|---|---|
| `SNeuPanel` | extruded card or inset well (flag) |
| `SNeuButton` | extruded; pressed or "on" → inset with cyan text; disabled 35% opacity |
| `SNeuGauge` | inset circular well; 270° arc drawn with `MakeLines` (thick, anti-aliased, round caps as small discs), 13% track, value in the centre, label below. No needles |
| `SNeuSlot` | hotbar slot: extruded 52 px square, selected = inset |
| `SNeuCell` | inventory cell: extruded 74 px square, empty = inset |
| `SNeuRow` | list row (recipes, kits, boxes) with a 40 px icon, name, description, cost chips, button |
| `SNeuWindow` | the PDA and station frame: max 980 × 640, header with tab buttons, body of inset columns |
| `SNeuSlider`, `SNeuProgress` | inset track, extruded thumb |

Icons are drawn in code from primitives as in v2 (`itemIcon`): ore = pentagon, refined = stacked bars, tank =
capsule, tool = disc, kit = isometric box, each with a two-letter glyph.

**HUD layout** *(v2 §4.8; safe margin 14 px)*:

| Region | Content | Shown when |
|---|---|---|
| Top centre | depth (large), band name, rating, compass strip | always |
| Top left | objective, ≤ 30% width, 3 lines, folds to one line after 10 s (`J`) | always |
| Top right | toast stack (3) | |
| Bottom left | vitals: health, O₂ (seconds), nutrition gauges; small `BIO` reserve readout; `CABIN 26.0 °C` on foot | always |
| Bottom right | vehicle panel (hull, power, hold, speed) | only when no dash is on screen (helm external views) |
| Bottom centre | hotbar; radio line 16 px above it, width `min(560, W − 2·vitalsWidth − 60)`; in vehicles the radio sits at the bottom centre | hotbar on foot and swimming |
| Centre | crosshair; prompt 30 px below; helm aim reticle and hull-nose marker at the helm; build reason text | |
| Right centre | PROXIMITY panel | helm views 1–4 |
| World markers | beacons, carrier, Tender (distance labels) | |

Below 900 px width: gauges 56 px, radio moves under the depth panel, objective hidden unless `J`.

**Windows**: PDA (INVENTORY with equipment and the greyed weapon slot · SURVEY MAP · LOGS · STATUS), fabricator
(tabs per category, two columns), refinery (queue and output), packer (buffer, three gauges, four slots, EJECT),
storage, Tethys terminal (sell refined, sell boxes, ledger), nutrient vat, build menu, pause (resume, Bloom
slider, key list in a two-column inset), title card (progress bar, DIVE, CONTINUE), end card.

For tests the HUD reports every top-level widget's rectangle (§9.3); a test asserts that radio, prompt,
vitals, hotbar, vehicle panel, objective and depth panel do not intersect at 1280 × 720, 1000 × 560 and 800 × 450.

---

## 9. Verification harness

Every milestone is checked by an agent with no person at the keyboard: build, run a scenario, read the JSON,
look at the PNG. This section is the contract. §9.1 describes what M0 already built (names taken from the
code on 2026-10-04); the rest is what each milestone adds. If `STATUS.md` later names something differently,
`STATUS.md` wins for M0 items and this section must be amended.

### 9.1 What exists (M0)

| Thing | Name |
|---|---|
| Build | `Tools\build.ps1` → one `BUILD PASS/FAIL` line, log `Saved\Logs\build_last.log` |
| Assets | `Tools\export_kazah.ps1` (Blender → `SourceArt\Kazah\` + `Vehicles\KazahLayout.inl`), `Tools\import_assets.ps1` (`Tools\ue\import_assets.py`: meshes, materials, the map) |
| Scenario run | `Tools\run_scenario.ps1 -Name <name> [-ResX 1280 -ResY 720 -TimeoutSec 300]`: launches `UnrealEditor.exe -game -RenderOffscreen -DescentScenario=<name>`; PASS = exit code 0 **and** the log line `DESCENT_SCENARIO_RESULT PASS`; log `Saved\Logs\scenario_<name>.log` |
| Headless tests | `Tools\run_tests.ps1 [-Filter Descent]`: `UnrealEditor-Cmd.exe -nullrhi`, `Automation RunTests <Filter>`, report `Saved\Automation\Reports\index.json` |
| Scenario DSL | `DESCENT_SCENARIO(name, "description") { S.TimeLimit; S.Do; S.Until; S.WaitFrames; S.WaitSeconds; S.Exec; S.Camera; S.LookAt; S.Shot; S.DumpState; S.Quit; }` (`Debug/DescentScenario.h`) |
| Screenshots | `Saved\Shots\<scenario>_<label>.png`; a black or wrong-sized frame fails the scenario |
| State dumps | `Saved\State\<scenario>_<label>.json` = `{ "schema": 1, "name": …, "<section>": {…}, … }`; sections register with `FDescentStateProviderRegistrar`; positions in metres; existing sections `meta`, `camera`, `pawn`, `world` |
| Console commands | `Descent.DumpState <name>`, `Descent.Shot <name>`, `Descent.Teleport x y z`, `Descent.Camera x y z pitch yaw roll [fov]`, `Descent.Scenario <name>`, `Descent.ListScenarios`, `Descent.Sections`, `Descent.Quit [code]` |
| Scenarios | `smoke`, `kazah_showcase` |
| Automation tests | `Descent.Harness.*`, `Descent.Kazah.Layout`, `Descent.Kazah.RotorSpin` |

### 9.2 Additions to the harness itself (M1)

| Addition | Contract |
|---|---|
| Fixed time step | `run_scenario.ps1` adds `-UseFixedTimeStep -FPS=30`: every frame advances the game by exactly 1/30 s, so scenario results do not depend on the machine's frame rate |
| `S.WaitSim(seconds)` | waits on `UDescentSimSubsystem::SimTime()`, not on the wall clock |
| `S.FastForward(seconds, dt = 1/30)` and `Descent.Sim.FastForward <seconds> [dt]` | calls `UDescentSimSubsystem::Step(dt)` in a loop inside one frame (no rendering, no character movement). Terrain queries never wait for async jobs (they fall back to the analytic field), so this is safe |
| `S.Expect(label, [](Ctx) → bool)` and `S.ExpectNear(label, value, expected, tolerance)` | fail the scenario with the label and the numbers in the log |
| `S.WaitStreamIdle()` | until `terrain.pending_jobs == 0` and all chunks within the load radius are meshed |
| Shot sidecar | every shot also writes `Saved\Shots\<stem>.json`: `{ "w", "h", "mean_luma", "centre_luma", "non_black", "p99_luma", "mean_rgb": [r,g,b] }` (sRGB-encoded 0..1; `centre_luma` = central 40% × 40%). `Descent.ShotRegion <stem> x0 y0 x1 y1` (fractions) appends `"regions": [...]` with the mean luma of a rectangle; `Descent.ShotRing <stem> cx cy r0 r1` (pixels) the mean luma of a ring (used by `look_bloom`) |
| Intent override | `Descent.Player.Intent fwd right up lookYawDeg lookPitchDeg seconds [primary] [secondary] [sprint]` holds a `FDescentIntent` for a sim duration |

### 9.3 Console commands added by the systems

All take metres and degrees. A command that fails logs `DESCENT_CMD_FAIL <command>: <reason>` and, inside a
scenario, fails it.

| Command | Does | From |
|---|---|---|
| `Descent.World.Goto <place>` | moves the controlled body (fly pawn, Tender, swimmer or carrier with `carrier:` prefix) to a named place: `start`, `canyon_mid`, `wellA`, `shelfA`, `needle`, `h1`, `bore`, `void`, `kilo7`, `drop`, `shelfC`, `hairpin`, `undercroft`, `antiphon`, `gullet`, `goal`, `abyss`, `hollow`, `honest`, `grotto`, `sieve`, `spur_e1` | M1 |
| `Descent.World.Density x y z`, `.Carve x y z r`, `.Cleanup x y z r` | query or edit the field; results in the log and in `terrain.last_*` | M1 |
| `Descent.World.Slice <axis X, Y or Z> <coord> <stem> [metresPerPixel=2]` | writes `Saved\Shots\<stem>.png`: rock white, water black, carved grey, deposits in ore colours, route axes in red, over the claim box | M1 |
| `Descent.World.NearestDeposit [type]` | fills `ore.query = { pos, normal, type, yield, mined }` for the deposit nearest to the controlled body | M1 |
| `Descent.World.ClearRoute <route 1..3>` | carves the carrier's swept volume along a route (§2.10) | M1 |
| `Descent.Look.Set <param> <value>` with param one of `Exposure`, `Bloom`, `WaterPP`, `Volumetric`, `Snow`, `Lamp` | look switches for tests | M1 |
| `Descent.Player.Place <room>` / `Descent.Player.PlaceLocal x y z yaw` | puts the character on foot in the carrier (carrier-local) | M2 |
| `Descent.Player.MoveTo <room>` or `Descent.Player.MoveTo <x> <y>` | walks with real movement input toward a carrier-local point until within 0.4 m or 20 s | M2 |
| `Descent.Player.Look yaw pitch`, `.Use`, `.Set <vital> v` (`nutrition`, `o2`, `health`), `.Give <item> n`, `.Mode` (prints) | | M2–M3 |
| `Descent.Tender.Board [i]`, `.Launch`, `.Dock`, `.Exit`, `.Enter [i]`, `.Teleport x y z`, `.LookAt x y z`, `.Set <stat> v` (`hull`, `power`) | | M3 |
| `Descent.Carrier.Carousel` | rotate one step | M3 |
| `Descent.Player.Swim x y z`, `.PoolDrop`, `.Climb` | | M3 |
| `Descent.Tender.Drill <0 or 1>`, `.Suck <0 or 1>`, `.Ping`, `.GiveOre <type> n`, `.GiveBio fu` | | M4 |
| `Descent.Upgrade <name> <level>` | sets a field of `FUpgradeState` | M4 |
| `Descent.Cargo.SpawnBox <type> <count> [socket]`, `.Eject` | | M5 |
| `Descent.Store.Give <item> n`, `Descent.Sell <item> n`, `Descent.Sell box:<id>` | | M5 |
| `Descent.Carrier.Helm <0 or 1>`, `.Throttle v`, `.AimDelta yawDeg pitchDeg`, `.Ballast v`, `.Strafe v`, `.View n`, `.Teleport x y z yaw`, `.SetHull v`, `.Autopilot <route 1..3, or stop>` | | M6 |
| `Descent.Build.Ghost <kit> x y z yaw` (carrier-local; evaluates validity without placing), `.Place <kit> x y z yaw`, `.Pickup <id>` | | M7 |
| `Descent.Craft <recipeId>`, `Descent.Save [slot]`, `Descent.Load [slot]` | | M7 |
| `Descent.Bio.Set fu`, `Descent.Fauna.Spawn <kind> x y z n`, `Descent.Player.Jack [port]`, `.Sleep` | | M8 |
| `Descent.Sonar.Ping`, `Descent.Horror.Levi [near]`, `.Flicker`, `.Heartbeat`, `.Ghost`, `Descent.Carrier.Finish` | | M9 |
| `Descent.UI.Open <window>` (`pda`, `map`, `logs`, `fabricator`, `refinery`, `packer`, `storage`, `terminal`, `vat`, `build`, `pause`), `.Close`, `.Tab <name>` | | M2–M10 |

### 9.4 State sections

Each system registers one section. Numbers are rounded to 4 decimals; positions are `[x, y, z]` metres.

| Section | Fields |
|---|---|
| `meta`, `camera`, `pawn`, `world` | as built in M0 |
| `sim` | `time_s`, `step_count`, `fixed_dt`, `paused` |
| `world_def` | `seed`, `segments`, `chambers`, `wells`, `pores`, `worms`, `deposits`, `hash` (FNV of all primitive data: equal across runs) |
| `terrain` | `chunks_known`, `chunks_filled`, `chunks_meshed`, `chunks_modified`, `triangles`, `pending_jobs`, `apply_ms`, `fill_ms_avg`, `mesh_ms_avg`, `last_density`, `last_removed`, `floating_after_cleanup` |
| `ore` | `deposits`, `mined_total`, `loose`, `crystals`, `query` |
| `env` | `state` (`Water`/`Dry`), `surface_light`, `fog_density`, `volumetric_fog`, `exposure_ev`, `bloom_intensity`, `bloom_threshold`, `snow_instances_visible`, `temperature_c` (at the reference point), `sun_on` |
| `player` | `mode`, `ui_open`, `carrying` (box id or null), `local_m` (carrier-local, feet), `world_m`, `room`, `ref_point_m`, `ref_depth_m`, `focus` (label of the current interaction focus), `flashlight` |
| `vitals` | `nutrition`, `nutrition_rate_per_s`, `o2_s`, `o2_max_s`, `health`, `dead_reason` |
| `carrier` | `pos_m`, `yaw_deg`, `pitch_deg`, `speed_mps`, `vel_mps`, `yaw_rate_dps`, `throttle`, `aim_yaw_deg`, `aim_pitch_deg`, `ballast`, `hull`, `power`, `contacts`, `scrape`, `crippled`, `depth_m`, `view`, `exterior_lights`, `biomass_fu`, `carousel { angle_deg, busy, launch_slot, hoist_z, min_clearance_m }`, `autopilot { on, route, index, stalled, done }` |
| `tenders` | array: `id`, `name`, `docked`, `pos_m`, `yaw_deg`, `pitch_deg`, `speed_mps`, `hull`, `hull_max`, `power`, `rating_m`, `depth_m`, `contacts`, `lamp`, `drilling`, `sucking`, `tool { side, functions, head }`, `hardpoints { starboard, port }`, `hold { cap, used, order: ["ferrite", …] }`, `bio_fu`, `rotor_rpm`, `dash { depth_text, hull_pct, power_pct, temp_c, speed, hold_text }` |
| `cargo` | `unloading`, `pipe_pieces`, `pipe_length_m`, `packer { buffer, partial: [f, c, p], slots: [4 × box id or null] }`, `boxes: [{ id, type, count, where }]`, `sockets`, `arms: [{ id, state, moved }]` |
| `store` | item counts, `used`, `cap`, `ore_ledger { ferrite, cobalt, pearl }`, `kits { … }` |
| `econ` | `debt`, `earned`, `sold` |
| `upgrades` | the fields of `FUpgradeState` |
| `refineries` | array: `id`, `room`, `queue`, `current`, `progress`, `hopper` |
| `build` | `active`, `ghost { kit, valid, reason, local_m, yaw_deg }`, `placed: [{ id, kit, room, local_m, yaw_deg }]` |
| `bio` | `reserve_fu`, `cap_fu`, `port_refused`, `vat_level` |
| `fauna` | `schools_active`, `fish_alive`, `jellies`, `polyps`, `inside_hull`, `captured_total` |
| `sonar` | `points_alive`, `pings_active`, `contacts`, `last_ping_range` |
| `map` | `known_cells`, `visited_cells`, `flagged_cells`, `markers`, `labels_discovered` |
| `horror` | `leviathan_active`, `pulse`, `flicker`, `hallu`, `counters { creak, groan, heartbeat, whisper, phantom, ghost }`, `logs_found`, `ending` |
| `audio` | `loops { name: { volume, pitch, lowpass_hz } }`, `master_lowpass_hz`, `one_shots: [{ name, time_s }]` (last 20) |
| `ui` | `hud { depth_text, band, rating_text, prompt, radio, toasts, shear_warning }`, `widgets: [{ name, visible, x, y, w, h }]`, `window`, `cargo_display { cells: […] }` |
| `perf` | `frame_ms_avg`, `game_ms_avg`, `sim_ms_avg`, `draw_calls`, `triangles` |

### 9.5 Conventions for scenarios and tests

- Scenario names: `m<N>_<what>` for milestone acceptance, `look_<what>` for the look tests of §7.10. Shot and
  state labels are part of the acceptance tables in §10: do not rename them.
- A scenario asserts its own pass conditions with `S.Expect…`; the screenshots are for the Critique and the
  Administrator to look at.
- Automation tests (`-nullrhi`, no rendering) cover pure logic: `Descent.<System>.<Name>`. Anything that needs
  the renderer is a scenario.
- Every acceptance scenario ends with `S.DumpState("end")`.

---

## 10. Milestone plan

M0 (harness, Kazah pipeline, showcase) is the Coder's current work. Each later milestone ends in something a
person can play and an agent can verify. The core loop (walk → board → dive → drill → collect → dock → pipes
→ box → carry → refinery) is complete at **M5**.

### M1 — Rock and water

**Playable result:** fly a lamp through the whole new world; carve rock with a console command.
**Build:** `Core/DescentMath`, `DescentTuning`, `UDescentSimSubsystem` (with `FastForward`), `World/*` (definition,
SDF, terrain, routes, deposits, shear function), `M_Terrain`, `ADescentEnvironment` with `PP_Water`, fog, sun,
`MPC_Descent`, manual exposure and the bloom settings, `UDescentLightPool`, a headlamp on `ADescentFlyPawn`,
harness additions §9.2, renderer settings §1.1.

| Check | Kind | Pass when |
|---|---|---|
| `Descent.World.Determinism` | automation | `GenRaw` at 2,000 seeded points matches a stored hash; `world_def.hash` equal on two builds |
| `Descent.World.CarrierFit` | automation | for each route, sweeping the hull points along the route poses: before `ClearRoute` the minimum clearance is negative at each of its chokes and ≥ 1.0 m everywhere else; after `ClearRoute` it is ≥ 1.0 m everywhere |
| `Descent.World.NoBypass` | automation | no pore, worm, pocket or sponge sample within 30 m of a well or gallery axis is open |
| `Descent.Terrain.SeamMatch`, `.CarveOre`, `.Cleanup`, `.NoBounds` | automation | border vertices of neighbouring chunks are identical; 6 removed vein samples give 1 chunk; cleanup leaves no unconnected rock; a chunk at (100 km, 100 km, −100 km) can be queried, filled and carved |
| `m1_world_slices` | scenario | shots `plan_z-30`, `plan_z-200`, `plan_z-700`, `plan_z-1020`, `plan_z-1330`, `section_y-25`, `section_y-330`, `section_x760` show canyon, wells, galleries, chambers and chokes where §2.8 puts them; `world_def.deposits == 600` |
| `m1_terrain_tour` | scenario | at `start`, `wellA`, `shelfA`, `h1`, `void`, `hollow`, `grotto`, `undercroft`, `goal`: `terrain.pending_jobs == 0` after `WaitStreamIdle`, `terrain.triangles ≤ 900,000`, each shot `tour_<place>` has `non_black > 0.2` |
| `m1_carve` | scenario | at `NearestDeposit`: five `Carve` calls of radius 3: `terrain.last_removed > 0`, `ore.mined_total` rises, `terrain.floating_after_cleanup == 0`; shots `vein_before`, `carved_after`, `seam_wire` (wireframe at a chunk border, no gaps) |
| `look_calibrate`, `look_deep_lamp`, `look_deep_dark`, `look_near_wall`, `look_throat`, `look_bloom` | scenarios | the bands of §7.10 |

Completes: **U8**; U12 (settings; confirmed again in M10); V1 (exterior); V7a (veins visible), V7b (clean carving). Starts U7.

### M2 — Walk the carrier

**Playable result:** press Play, stand on the bridge, walk every room and deck of the CANTICLE.
**Build:** `FCarrierLayout`, `UCarrierBlockoutComponent`, lamps and exterior lights, `ADescentCharacter`,
`UDescentCharacterMovement` (walking), `ADescentPlayerController` (modes `Title`, `Foot`), input, interaction,
fixture stubs (helm, beds, ports, consoles show prompts), moon-pool surface, dry volume, `EDescentEnv`, stencil
mask, lighting channels, temperature, neumorphic kit core, HUD (depth panel, vitals, prompt, cabin temperature).

| Check | Kind | Pass when |
|---|---|---|
| `Descent.Carrier.Layout`, `.DryVolume`, `.Temperature` | automation | every room box lies inside `HullRadius`; every door joins two rooms; `IsDry` true at each room centre, false 1 m outside the hull and 1 m below the pool surface; `AmbientTemperatureAt` = 26.0 inside, water formula outside |
| `m2_walk` | scenario | `MoveTo` through bridge → corr3 → stair → galley → cargo → refinery → engine → bay gallery → bay floor; at each stop `player.room` matches and `player.local_m.z` = 1.5 / −3.0 / −7.5 ± 0.05; shots `room_<id>` for all 16 rooms with `mean_luma` 0.10–0.45 |
| `m2_dry` (U5, U6) | scenario | on the bridge: `env.state == "Dry"`, `env.volumetric_fog == false`, `env.snow_instances_visible == 0`, `env.temperature_c == 26.0`, HUD shows `CABIN 26.0 °C`; shots `bridge_water_on` and `bridge_water_off` (`Descent.Look.Set WaterPP 0`): the interior region of the two shots differs by < 0.01 mean luma (no water on interior pixels) while the window region differs (sea is fogged). Camera 40 m outside: `env.state == "Water"` |
| `m2_exterior` (V4a) | scenario | shot `exterior_dark` from 80 m: hull is a dark mass; `carrier.exterior_lights == 6` |

Completes: **V4**, **U5**, **U6** (water effects; the fauna half in M8). V13 started.

### M3 — Board, launch, dive, swim, dock

**Playable result:** walk to the bay, board the Tender, drop through the moon pool, fly the canyon with the
headlamp, leave the Tender to swim, climb back, dock.
**Build:** `AKazahTender` flight, lights, cockpit camera, dash with depth / hull / power, collision spheres,
energy, crush, honest voids; carousel, hoist, launch and dock; swim mode, O₂, pool drop, ladder, leave / enter;
the Shear; vitals (O₂, health), death and respawn (drown, implode); glass material; rotor spin from thrust.

| Check | Kind | Pass when |
|---|---|---|
| `Descent.Carousel.Clearance` | automation | §3.5: ≥ 2 m between Tenders through 360°; no intersection with bay, gallery, stairs, hub, riser, boom; hoist path clear of the pool rim |
| `Descent.Tender.Stats`, `Descent.Shear.Field` | automation | stats table of §4.2; shear 0 at Z ≤ 25, 10 m/s at Z 65, direction has a downward part |
| `m3_launch_dock` (V5) | scenario | mode sequence `Foot → Board → Docked → Launch → Sub → Dock → Docked`; `carrier.carousel.min_clearance_m ≥ 0.3` throughout; shots `bay_carousel`, `launch_mid`, `cockpit` (dash readable, canopy frame visible), `tender_close` (glass with the interior visible through it), `dock_rise` |
| `m3_carousel` | scenario | three steps of 120° ± 0.5°; refused while a Tender is out; shot `rotation_mid` |
| `m3_rotor` (V10) | scenario | `rotor_rpm == 0` idle, `305 ± 5` at thrust 1 |
| `m3_no_walls` (**U7**) | scenario | (a) from `canyon_mid` fly east at boost: the Tender keeps moving until `tenders[0].contacts > 0` at visible rock; (b) inside a pocket carved at (5,000, 0, −300) (outside every v2 bound) the Tender moves ≥ 10 m along ±X, ±Y, ±Z and the depth readout follows; (c) at Z −1,900 in a carved shaft the dash reads 3,680 m; (d) flying up from the canyon: `ui.hud.shear_warning` true above Z 10, Z never exceeds 135, and speed never changes by more than 2 m/s in one step (a current, not a wall); (e) the same (b) for the swimmer; shot `shear` |
| `m3_swim` (V9) | scenario | pool drop → `Swim`; O₂ falls 1.0 ± 0.05 per second; ladder → `Foot`, O₂ refills; with O₂ 0 health falls 9 per second, death, respawn in the galley, debt +900; shots `swim_under_carrier`, `ladder` |
| `m3_crush` (V8) | scenario | 5 s at depth 2,280 m: no hull loss; 5 s at 2,320 m: 7.0 ± 0.5 HP lost |

Completes: **U7**, **V5**, **V9**, **V10**. Parts of V6, V8.

### M4 — Mine

**Playable result:** drill a glowing vein, watch the ore break loose, suck it in, see the hold fill on the cargo display.
**Build:** `UTenderToolComponent` (drill, laser head, suction), loose ore and crystals, `UTenderHoldComponent`,
`SCargoDisplay`, the complete dash, HUD vehicle panel, hardness and basalt, tool mounted on starboard.

| Check | Kind | Pass when |
|---|---|---|
| `m4_mine` (V7) | scenario | facing `NearestDeposit`: 8 s of drill → `ore.loose > 0`; 10 s of suction → `tenders[0].hold.used ≥ 3`; shots `vein_closeup`, `drilling`, `carved`, `suction` |
| `m4_cargo_display` (**U11**) | scenario | `ui.cargo_display.cells` equals `tenders[0].hold.order` after each capture; shot `cargo_display` (camera on the panel) shows one coloured cell per chunk and `CARGO n/8`; with a full hold the shot `cargo_full` shows the red outline and `ui.hud.toasts` contains `HOLD FULL` |
| `m4_tool` (**U10**) | scenario | `tool.side == "starboard"`, `tool.functions == ["drill","suction"]`, `hardpoints.port == "empty"`; LMB intent alone sets `drilling`, RMB alone sets `sucking`; shots `tender_front`, `tender_port_side` show no tool on the port side |
| `m4_meters` (V6) | scenario | at five positions `ui.hud.depth_text == tenders[0].dash.depth_text == round(player.ref_depth_m)`; with `Upgrade CellMk 1` the drain in %/s is 1/1.7 of before; an impact at 10 m/s with `HullMk 1` costs 27.5 HP (18.3%) |
| `m4_basalt` | scenario | drilling 50 m outside the claim box removes nothing; dash shows the basalt line; shot `basalt` |

Completes: **U10**, **U11**, **V6** (Tender), **V7**.

### M5 — Unload, box, refine: the core loop closes

**Playable result:** the whole loop by hand, start to finish.
**Build:** `UDescentCargoSubsystem` (pipes, boom, unload job, packer, sockets), `ADescentOreBox`,
`UDescentCarryComponent`, `ADescentPlaceable` base with the start refinery and fabricator spawned, refinery logic
and window, `UDescentStoreSubsystem`, Tethys terminal, intake hatch.

| Check | Kind | Pass when |
|---|---|---|
| `Descent.Cargo.PackerMath`, `.PipeRoute`, `Descent.Store.Ledger` | automation | 14 ferrite + 3 cobalt in → 2 ferrite boxes, partials [2, 3, 0]; ore pipe length 72 ± 1 m and every vertex inside the hull; `ConsumeOre` empties the emptiest box first |
| `m5_core_loop` (**U13**, **U14**) | scenario | bridge → walk to the bay → board → launch → mine ≥ 6 ferrite → dock. During unloading `cargo.pipe_pieces > 0`; shots `pipe_bay`, `pipe_corridor`, `pipe_cargo` each show glowing pieces inside the glass pipe; then `cargo.boxes[0] == { type: "ferrite", count: 6, where: "packer.out0" }` (shot `packer_box`). Leave the Tender, walk to the cargo bay, `Use` the box → `player.carrying` set (shot `carry_box`); walk to the refinery, `Use` the hopper → `refineries[0].queue == 6` (shot `refinery_hopper`); `FastForward 90` → `store.ingot == 6` |
| `m5_sell` (V8) | scenario | selling 2 ingots lowers `econ.debt` by exactly 230; selling a `ferrite ×6` box by 360 |
| `m5_packer_full` | scenario | with four boxes on the outfeed and a full buffer the feed pauses, `ui.hud.toasts` contains `PACKER FULL`, the hold keeps its remainder |

Completes: **U13**, **U14** (manual), V8 (store, sell, refine).

### M6 — Pilot the carrier

**Playable result:** take the helm, steer the CANTICLE with the mouse down the canyon, scrape a wall, switch cameras.
**Build:** `UCarrierHelmComponent` complete, helm fixture, five cameras, proximity panel, helm dash, flood and
feed lights, hull consequences, autopilot and route tests, the moving-base walking check.

| Check | Kind | Pass when |
|---|---|---|
| `Descent.Routes.BlockedBeforeDig` | automation (`FastForward`) | on each route the autopilot stalls (`stalled`, `contacts > 0`) at its first undug choke |
| `Descent.Routes.ReachGoal_1`, `_2`, `_3` (V2) | automation (`FastForward`) | after `ClearRoute(n)` the autopilot reaches GOAL with `carrier.hull > 50` and `horror.ending` set |
| `m6_helm_speed` (**U9**) | scenario | from rest with throttle 1: `speed_mps ≥ 1.80` at 4.0 s; 1.95–2.05 at 10 s; never above 2.05; all stop: ≤ 0.2 within 4 s |
| `m6_helm_mouse` (**U4**) | scenario | `AimDelta 30 0`: yaw changes by 5–20° after 3 s (heavy), reaches 30 ± 1° within 14 s, `yaw_rate_dps ≤ 5.8` always; `AimDelta 0 −8` at speed: `pitch_deg` −8 ± 1 within 8 s; pitch never beyond ±10; helm HUD shows the aim reticle (shot `helm_aim`) |
| `m6_scrape` (V12) | scenario | driven into the canyon wall: `contacts > 0`, `hull` falls, `scrape > 0`; shots `helm_bridge`, `helm_chase`, `helm_topdown`, `helm_bow`, `helm_keel`, proximity panel visible |
| `m6_walk_moving` | scenario | carrier at 2 m/s, turning, pitched 8°: standing still for 5 s moves `player.local_m` by < 0.02 m; walking bridge → corridor succeeds; `player.room` never becomes null |

Completes: **U4**, **U9**, **V12**; V2 (routes); V6 (helm dash).

### M7 — Build and craft

**Playable result:** craft a locker, a rack and a handling arm; rearrange the cargo bay so boxes flow by themselves.
**Build:** `UDescentBuildComponent`, all placeables, fabricator window and recipes, upgrades, inventory, hotbar,
PDA inventory tab, robot arms and racks, save and load.

| Check | Kind | Pass when |
|---|---|---|
| `Descent.Build.Rules`, `Descent.Recipes.Costs`, `Descent.Arms.Ranks` | automation | each validity rule of §6.10 rejects its counter-example; every recipe consumes exactly its cost; an arm never moves a box to an equal or lower rank |
| `m7_build` (**U1**) | scenario | `Build.Ghost kit_table` in the habitation room: `ghost.valid` true (shot `ghost_valid`, green); in a doorway: false with reason `KEEP_OUT` (shot `ghost_invalid`, red); `Place` → `build.placed` +1, kit −1; the player walking at the table is stopped by it; `Pickup` → kit +1; pick up the empty refinery and place it in the cargo bay → `refineries[0].room == "cargo"`; shot `cargo_rearranged` |
| `m7_arms` (**U14**) | scenario | refinery 2.5 m from the packer outfeed, an arm between them, two boxes on the outfeed: `FastForward 20` → `refineries[0].queue == 12`, `cargo.arms[0].moved == 2`; shot `arm_moving` (mid-swing, box in the gripper) |
| `m7_craft` (V8) | scenario | Depth Module Mk I → `tenders[0].rating_m == 2700`; Hull Patch only when the hull is damaged; locked weapon row visible (shot `fabricator`) |
| `m7_inventory` (V11) | scenario | shot `pda_inventory` with the greyed weapon slot; a flare assigned to slot 4 |
| `m7_save` | scenario | carve, mine, place, box, then `Save`, `Load`: the sections `terrain.chunks_modified`, `ore.mined_total`, `build.placed`, `cargo.boxes`, `store`, `econ`, `upgrades`, `carrier.pos_m` are equal before and after |

Completes: **U1**, **U14** (automation), V8 (crafting), V11.

### M8 — Survive

**Playable result:** hunger matters slowly; the vat runs low; you go fishing with the Tender to stay alive.
**Build:** nutrition, jack-in with the reserve, vat, bio pipe, `UDescentFaunaSubsystem`, capture and bio-tank,
hull exclusion, hand tools, tanks, hunger death, sleep, flora.

| Check | Kind | Pass when |
|---|---|---|
| `m8_hunger` (**U2**) | scenario | `FastForward 600`: nutrition falls by 25.0 ± 0.3; `vitals.nutrition_rate_per_s == 0.0417 ± 0.0005` |
| `m8_biomass` (**U3**) | scenario | reserve 6.0, nutrition 42: jack-in → nutrition 100, reserve 3.68 ± 0.05, debt +12. `Bio.Set 0`: the port refuses (`bio.port_refused`, red ring, shot `port_empty`). Suction at the canyon school: `tenders[0].bio_fu > 0`; dock: `bio.reserve_fu` rises by the same amount through the bio pipe (shot `bio_pipe`); a polyp taken by hand and loaded at the vat adds 0.4. Shots `vat_low`, `vat_high` show the level |
| `m8_no_fauna_inside` (**U6**) | scenario | carrier parked on the school home (150, 20, −90); sampled every second for 120 s: `fauna.inside_hull == 0`; shots `bridge_window_fish` (fish outside the glass), `bay_pool` (none in the pool) |
| `m8_tools` (V9, V11) | scenario | a thrown flare raises `centre_luma`; a placed beacon appears in `map.markers`; tank equip changes `o2_max_s` to 90 |

Completes: **U2**, **U3**, **U6**, V9, V11.

### M9 — Sonar, map, dread, sound

**Playable result:** ping the Great Void and watch it draw itself; find a dead beacon; hear the heartbeat; reach the end.
**Build:** sonar, survey map and PDA tabs, beacons and logs, landmarks, leviathan, horror director,
hallucinations, ending, `gen_audio.py`, `UDescentAudioSubsystem`, radio lines.

| Check | Kind | Pass when |
|---|---|---|
| `m9_sonar` (V2) | scenario | a Tender ping at `void`: `sonar.points_alive > 1,500` within 2 s, `map.known_cells` rises; shots `sonar_void`, `map_auto`, `map_all` |
| `m9_leviathan`, `m9_beacon`, `m9_hallucination`, `m9_heartbeat` (V3) | scenarios | `Horror.Levi near`, 6 s, lamp on: shot `leviathan` shows the dark body and photophores, `sonar.contacts ≥ 1` after a ping; approaching b1: `horror.logs_found` +1 and `ui.hud.radio` ends with `[SIGNAL LOST]`; nutrition 10: whisper and phantom counters rise, shot `hunger_view`; `Horror.Heartbeat`: `horror.pulse > 0.9` |
| `m9_audio` (V3) | scenario | drilling: `audio.loops.drill.volume > 0`; swimming: `master_lowpass_hz == 1300`; in the carrier: `hum.volume > 0`; a ping adds `ping` to `one_shots` |
| `m9_ending` | scenario | `Carrier.Finish`: `horror.ending` set; end card after 16 s (shot `endcard`) |

Completes: **V2**, **V3**.

### M10 — Interface complete, look locked

**Playable result:** the whole game with every screen in the neumorphic style, tuned look, stable frame time.
**Build:** all windows, layout rules, title / pause / end cards, Bloom slider, low preset, tuning, performance pass.

| Check | Kind | Pass when |
|---|---|---|
| `m10_ui_layout` (V13) | scenario | at 1280 × 720, 1000 × 560, 800 × 450, in `Foot`, `Sub`, helm chase and helm bridge: no two of `radio`, `prompt`, `vitals`, `hotbar`, `vehicle`, `objective`, `depth` intersect (`ui.widgets`); shots per case |
| `m10_ui_windows` (V13) | scenario | title, pause, PDA (4 tabs), fabricator, refinery, packer, storage, terminal, vat, build menu, end card: each fits the viewport at 1280 and 800; shots |
| `m10_bloom` (**U12**) | scenario | `look_bloom` passes; shots `dash_bloom`, `sonar_bloom`, `vein_bloom`, `bay_lamps_bloom` show no haze over text or whole lamps; the pause-menu slider changes `env.bloom_intensity` |
| `m10_look` (V1) | scenario | all of §7.10 again, plus `look_rooms` |
| `m10_perf` | scenario | tour of nine places: `perf.frame_ms_avg ≤ 16.7` at 1920 × 1080 on this PC; `terrain.triangles ≤ 900,000` |
| `m10_full_run` | scenario | start → core loop once → `ClearRoute 1` → autopilot route 1 → ending, with no `DESCENT_CMD_FAIL` and no error in the log |

Completes: **V13**, **U12**, **V1**. After M10 every U1–U14 and V1–V13 has a passing check.

### Requirement → milestone index

| Req | Milestone | Req | Milestone | Req | Milestone |
|---|---|---|---|---|---|
| U1 | M7 | U10 | M4 | V5 | M3 |
| U2 | M8 | U11 | M4 | V6 | M4 (Tender), M6 (helm) |
| U3 | M8 | U12 | M1, confirmed M10 | V7 | M1, M4 |
| U4 | M6 | U13 | M5 | V8 | M3 (crush), M5, M7 |
| U5 | M2 | U14 | M5 (hand), M7 (arms) | V9 | M3, M8 |
| U6 | M2 (water), M8 (fauna) | V1 | M1, M10 | V10 | M3 |
| U7 | M3 | V2 | M6 (routes), M9 (sonar, map) | V11 | M7, M8 |
| U8 | M1 | V3 | M9 | V12 | M6 |
| U9 | M6 | V4 | M2 | V13 | M2 onward, M10 |

---

## 11. Risks and open questions

### 11.1 Technical risks, each with a fallback

| # | Risk | How it shows | Fallback |
|---|---|---|---|
| R1 | Hundreds of `UProceduralMeshComponent`s use the dynamic draw path; game-thread cost per visible chunk | `perf.game_ms_avg` rises in the Great Void (M1 tour) | group 2 × 2 × 2 chunks into one component (40 m render cells); if still too slow, a custom component with a static-draw scene proxy. The chunk data model does not change |
| R2 | Character jitter or drift on the moving, pitching carrier | `m6_walk_moving` fails | all stop while the player is on foot (§3.1) |
| R3 | Materials by Python: a `Custom` node, post-process domain or parameter collection cannot be set from script | `make_materials.py` errors | build the same graphs from C++ in an editor-only commandlet (`UMaterialEditingLibrary` is a C++ API first); the HLSL text files stay |
| R4 | Three shadow-casting spots on dynamic geometry with virtual shadow maps are too slow | `m10_perf` | only the lamp of the vehicle you are in casts shadows; then classic shadow maps for spots |
| R5 | Switching volumetric fog off inside the hull pops, or sea seen through windows loses its beams | `m2_dry` shots | keep volumetric fog on always with `FogDensity` 0.005 and interior lamps at scattering 0; the stencil mask alone keeps the interior free of the post-process water |
| R6 | Manual exposure and exponent-falloff lights need more calibration than expected | §7.10 bands not reachable together | calibrate the three lamp intensities separately; the bands, not the start values, are the requirement |
| R7 | The Kazah `Body` is very dense (the hull object evaluates to ≈ 880k triangles with modifiers; the brief says 112k for the model) | frame time with three Tenders in view | export without the subdivision modifier, or enable Nanite on `SM_Kazah_Body`; check `Descent.Kazah.Layout` reports the triangle count |
| R8 | Mirroring `Tool_Housing` with a negative scale shows inverted shading | `m4_tool` shots | export a mirrored copy of that one part from the export script (the `.blend` is not changed) |
| R9 | World-space Slate dashboards cost too much or do not take the dry stencil | cockpit shots | draw the dashboards into a `UCanvasRenderTarget2D` with `FCanvas` and show them on an emissive quad |
| R10 | Sponge noise (the Sieve) makes fill jobs slow or classification wrong | `terrain.fill_ms_avg` | replace the sponge with 60 more worm tunnels inside the same box |
| R11 | Automation tests that need a world do not run under `-nullrhi` | `run_tests.ps1` | move those to scenarios with `FastForward`; keep pure-math tests headless |
| R12 | Route lengths feel slow at 2 m/s (the Hairpin is 1,152 m: almost 10 minutes) | playtest | shorten gallery S with one more well, or add a helm "cruise" assist; a user decision (below) |
| R13 | Scope: ten milestones | schedule | the order already puts the core loop first (M5); M8–M10 can be re-cut without touching M1–M7 |

Not adopted on purpose, to be revisited: Lumen GI and reflections for the carrier interior once real static
meshes exist (they have distance fields); Niagara for particles if assets by hand become acceptable.

### 11.2 Decisions that are the user's

1. **Tool side (U10).** The Kazah model has its `Tool_Housing` on the **port (left)** side. U10 says the left
   side stays free. The design mirrors the housing to starboard at assembly time (the `.blend` is untouched).
   Is that what you want, or should the tool stay where you modelled it and the *right* side be the free one?
2. **Hunger (U2).** 100% now lasts **40 minutes** (was 9). Slower or faster?
3. **Size and pace (U8).** The new world is 1.9 × 1.5 × 1.8 km with a 1.4 km descent. A full carrier descent is
   about 25–35 minutes of piloting plus three or four digs; the longest gallery takes about 10 minutes at 2.0 m/s.
   Is that the scale you want, or should it be about half?
4. **Fleet.** Three Tenders as in v2 (TENDER, DART, MOLE), all using the Kazah model in three paints, or one Tender?
5. **The top of the world.** Above the Throat's rim a visible current ("the Shear") pushes everything back
   down, with a warning first. The alternative is to let the player rise 1,740 m to the surface. Which?
6. **Your robotic-arm model** (`models/robotic-arm`, a jointed arm with fingers): use it for the first-person
   cybernetic arm in the jack-in animation? The handling arms of U14 are blockout until you model them.
7. **Leaving the helm.** The carrier comes to all stop when you leave the helm (as in v2). Should it instead
   keep its heading and throttle so you can walk around while under way?