# THE DESCENT — Unreal port: Brief (Administrator, from the user's notes of 2026-10-04)

The user has decided to **stop the browser version and start the Unreal Engine port**. The browser game
(v2, three.js) is frozen and is now the **reference implementation**: `D:\HADAL - The Descent\the-descent\`
(`src/*.js`, `docs/DESIGN_V2.md`, `docs/BRIEF_V2.md`, `docs/GameLore.txt`). Read it, port its ideas, do not edit it.

The Unreal project is `D:\HADAL - The Descent\TheDescentUE\TheDescent.uproject` (UE 5.8.1, C++). An empty module
already compiles (see §4).

**Update of 2026-10-11 (recorded, not designed or built):** the user rewrote the lore and added gameplay
changes after the port was finished. They are in `Docs\updates\2026-10-11\BRIEF_UPDATE.md` as U15–U29, D1 and
L1–L14. That file replaces U12 (bloom), the Shear default of §3 and "the lore stays" of §3.

Team: **Designer** (Opus) designs and writes specs. **Coder** (Sonnet) writes all the code. **Critique** (Opus)
checks the result **only** against the user's requirements below. The **Administrator** (main agent) relays
between them and the user.

---

## 1. Requirements carried over from v2 (still non-negotiable for the finished game)

`the-descent/docs/BRIEF_V2.md` lists V1–V13 in the user's words. In short: dark Subnautica-like realism where
deeper is darker and your own lights are precious (V1); one open world with several routes, found by sonar, map,
swimming and terraforming (V2); thalassophobia and psychological horror as the main selling point, with audio
(V3); a big multi-deck carrier with few exterior lights (V4); a sub bay where subs never clip (V5); a
Subnautica-style cockpit dashboard in every vehicle with accurate, consistent meters (V6); terraforming with
visible ore veins and clean carving (V7); mine → store → sell or refine → craft, with crush depth (V8); swimming,
the free moon-pool drop, leaving and re-entering subs, O2 on the HUD (V9); detailed Tender with real glass and a
spinning propeller (V10); inventory and hotbar with a future weapon slot (V11); a carrier the player pilots
by hand (V12); neumorphic UI (V13). First person, Half-Life feel. Nutrition through a cybernetic wall plug.

Where a new requirement in §2 changes one of these, §2 wins.

## 2. NEW requirements (the user's notes, numbered U1–U14 for the Critique)

Quoted lines are the user's own words. "Subtub" is the user's word for the small submarine (the Tender).

**U1 Placeable objects.** "Add a complete new mechanic where player can place furnitures or fabricator,
refinery, or whatever created objects."
→ A build/placement mode. Things the player crafts (furniture, fabricator, refinery, lockers, lights, the
automation arms of U14 and so on) are items that are placed in the world by the player: ghost preview, valid
or invalid colour, rotate, confirm, pick back up. The fabricator and the refinery are placeable objects too,
not fixed props.

**U2 Slower hunger.** "Nutrition loss is too rapid needs to be more slow decrease." (v2 drained 100% in 9
minutes.)

**U3 Biomass.** "There should be biomass where nutrition in the vessel needs to be refilled. So player needs
to collect fish or biological fauna from the sea to fill it up so player can live, the vessel shouldnt [have]
unlimited storage of nutrition."
→ The carrier has a finite biomass reserve that the wall ports draw from. The player collects fish and
other fauna in the sea and loads them into the vessel to refill it. An empty reserve means no feeding.

**U4 Carrier steered with the mouse.** "Vessel should be controllable just like the subtubs with mouse, but
according to its scale."
→ At the helm the mouse steers the carrier the same way it steers a Tender, but heavy and slow to respond.

**U5 Carrier interior temperature.** "inside vessel 26 degree celcius perfect for human"
→ Any temperature readout taken inside the carrier reads 26 °C. Water temperature applies only outside.

**U6 Dry interior.** "inside vessel should not be water effects and fish clipping inside."
→ No underwater fog, tint, caustics, particles or marine snow inside the hull, and no fish or other fauna
passing through it. The only water inside is the moon pool surface.

**U7 No invisible walls.** "while using subtub for some reason I couldnt go deeper or move as freely as if I
hit some unvisible wall"
→ Cause in v2: positions were clamped to the world box (`10_player.js:391`, `06_carrier.js:521`). In the port
there must be no invisible limit. The playable space ends in visible rock, or the player gets a diegetic
warning well before a soft limit.

**U8 Bigger map.** "the terrain is too small for the gameplay we need a bigger map more free space to
explore" (v2 was 560 × 700 × 600 m.)

**U9 Carrier speed.** The user was asked and chose: **keep the 2.0 m/s top speed, but reach it within a few
seconds** (v2 took about 20 s).

**U10 One tool for drill and suction.** "subtubs suction device and drill device should be all-in-one player
first drill then suck it up the ores this way we have opened the left side free."
→ One tool on the Tender both drills and collects. The left side has no tool on it and stays free for
something later.

**U11 Cargo dashboard.** "there should be dashboard in subtubs where it shows clearly the cargo hold
visually"
→ A cockpit display that shows the hold's contents as a picture (what is in it and how full it is), not just
a number.

**U12 Bloom.** "bloom effect is too much needs a rework"

**U13 Ore pipes and boxes.** "transparant ore pipes inside vessel while subtub docked cargo unload. so we can
see the ores move through the pipes into the cargo bay > from cargo bay > (cargobay creates box) into carriage
box."
→ When a Tender docks, its hold unloads through transparent pipes that run through the carrier's interior.
The player can see the ore pieces travel through the pipes to the cargo bay, where a machine packs them
into ore boxes.

**U14 Carry the box, then automate.** "player needs to take the ore box physically to put into ore refinery
to process it. this system is upgradable where player can craft industrial robotics arms like devices to
automize the process while in progress."
→ The player picks an ore box up, carries it and puts it into the refinery by hand. Craftable industrial
robot arms automate that handling once built. (They are placed with U1.)

## 3. Standing instructions from the user

- **Tender model:** use `D:\HADAL - The Descent\models\Kazah-stern-cavity-fixedv4.blend`. It is 3.27 m wide,
  6.99 m long, 2.51 m tall, 70 mesh objects, 112k triangles, node materials with no image textures. In
  Blender its nose points to −Y and the two propulsors are at +Y. `Rotor_Port` and `Rotor_Stbd` are separate
  objects with their origins on the rotor hubs. Other parts that can move or need their own material:
  `Canopy_Glass`, `Canopy_Lid`, `Hatch_Lid`, `Tool_Housing`, `Nose_Lens`, `Chin_Sensor`.
- **Player's cybernetic arm (approved by the user 2026-10-04):** use
  `D:\HADAL - The Descent\models\robotic-arm\robotic-arm.blend` for the first-person arm. It lies along +X and
  is about 0.78 m from shoulder to fingertips. Every segment is its own object with its origin on its joint,
  parented in a chain: `RA_Root` → `RA_UpperArm` → `RA_Forearm` → `RA_Wrist` → `RA_Hand` → five fingers of three
  phalanges each (`RA_Index_1..3`, `RA_Middle_1..3`, `RA_Ring_1..3`, `RA_Pinky_1..3`, `RA_Thumb_1..3`), plus
  `RA_PistonRod` on the forearm. 17k triangles, materials `RA_ArmorWhite`, `RA_Rubber`, `RA_Frame`. No armature
  and no animations, so it is animated in code by rotating the parts. Ignore the leftover default `Cube`,
  `Camera` and `Light` objects in the file. Never save over the .blend.
- **Decisions the user was told on 2026-10-04 and did not change** (they are the defaults until the user
  says otherwise): the Tender's tool is mounted mirrored on the starboard (right) side so the left stays free,
  without changing the .blend; nutrition lasts 40 minutes from full; the world size of DESIGN §2.7; three
  Tenders, all Kazah, in three paint schemes; the top of the world ends in the Shear current; leaving the helm
  brings the carrier to a stop.
- **Moving parts are separate objects** with their origin on the axis of motion. Never bake a part that
  moves into a static mesh.
- **No STALKER assets.** Nothing from `D:\Games II\STALKER` may be used. Do not read from that folder.
- `D:\HADAL - The Descent\Assets\` holds third-party reference files the user collected. Do not import them unless
  the Administrator says so. `D:\HADAL - The Descent\models\` holds the user's own models.
- The lore (`GameLore.txt`) stays: Hadra, the Throat, Tethys, the carrier CANTICLE, the strata.

## 4. Environment (verified on this PC, 2026-10-04)

- **Engine:** UE 5.8.1 at `E:\Tools\UE_5.8`, with engine source. i9-13900F, RX 7800 XT, 32 GB RAM, Windows 10.
- **C++ toolchain:** no Visual Studio is registered, so UnrealBuildTool finds nothing by itself. MSVC
  14.44 is reached through an AutoSDK junction. **Every build must set `UE_SDKS_ROOT`:**
  ```powershell
  $env:UE_SDKS_ROOT = "D:\HADAL - The Descent\.tools\AutoSDK"
  & "E:\Tools\UE_5.8\Engine\Build\BatchFiles\Build.bat" TheDescentEditor Win64 Development -Project="D:\HADAL - The Descent\TheDescentUE\TheDescent.uproject" -WaitMutex -NoHotReloadFromIDE
  ```
  The empty module builds in about 45 s. Windows SDK 10.0.22621.
- **Editor binaries:** `E:\Tools\UE_5.8\Engine\Binaries\Win64\UnrealEditor.exe` and `UnrealEditor-Cmd.exe`.
- **Offscreen run, proven:** this renders on the real GPU with no window and wrote a 1280×720 PNG
  18 s after launch (`Saved\Screenshots\WindowsEditor\HighresScreenshot00000.png`). The process does not exit
  by itself, so the harness must quit the game or the caller must stop the process it started.
  ```powershell
  & "E:\Tools\UE_5.8\Engine\Binaries\Win64\UnrealEditor.exe" "D:\HADAL - The Descent\TheDescentUE\TheDescent.uproject" /Engine/Maps/Templates/OpenWorld -game -windowed -ResX=1280 -ResY=720 -RenderOffscreen -unattended -nosplash -nosound -nopause -log -ExecCmds="HighResShot 1280x720"
  ```
- **Blender:** 5.2.2 at `E:\Steam\steamapps\common\Blender\blender.exe` (runs headless with `-b`).
- **Python:** 3.14 at `E:\Tools\Programs\Python\python.exe`. Node.js is not installed.
- **The user's own editor** is open on `D:\UEtest\MyProject`. Leave that project and that editor process alone.
  Never kill `UnrealEditor` processes you did not start.
- Enabled plugins so far: `PythonScriptPlugin`, `ModelContextProtocol`, `ModelingToolsEditorMode`.

## 5. Ground rules for the port

1. **Code first.** Gameplay is C++ in the `TheDescent` module. Do not depend on hand-made Blueprint or
   level assets. Assets that must exist (map, materials, imported meshes) are created by scripts in
   `TheDescentUE/Tools/` that can be re-run, so the project can be rebuilt from text plus source art.
2. **Everything must be verifiable without a person at the keyboard.** The Coder builds a harness first
   (milestone M0): console commands, a JSON state dump, a scenario runner that drives the game, takes
   screenshots offscreen and exits, and headless automation tests. An agent must be able to change code,
   build, run a scenario and look at the PNG.
3. **Units:** design in metres, 1 m = 100 Unreal units. Depth is `DATUM − altitude` from one function, as
   in v2.
4. **The user will open the project in the editor and press Play.** That has to work.
5. Keep the browser version's good ideas where they fit: SDF-defined terrain with surface-nets carving,
   density-field collision for vehicles, one source of truth for every meter.

## 6. Deliverables

- **Designer:** `TheDescentUE/Docs/DESIGN_UE.md`. Architecture, class list, how each v2 module maps to
  Unreal, full specs for U1–U14, the bigger world, a milestone plan with acceptance tests per milestone,
  and the risks.
- **Coder:** the code, the tools and `TheDescentUE/Docs/STATUS.md`, kept current: what works, how to
  build, run and test it, and what is open.
- **Critique:** a pass, partial or fail verdict per requirement, with evidence.