# The Sci-Fi Hard-Vacuum Cell
This is V5's hard simulation. Where its sibling spends fifty hours on _who you
are_, the Hard-Vacuum cell spends them on _where the vectors go_. It is the
Expanse surface — the genre where a spaceship is not a fighter jet with a
re-skin but a chunk of mass with a single engine bolted to the back, where you
do not "turn left" so much as **rotate the whole hull and burn**, and where
thrust is a budget you spend out of a finite propellant tank. The
moment-to-moment loop is **crew a ship, plot a burn, flip and decelerate, fight
a duel of leading shots and salvo timing, then clamp hull-to-hull at matched
drift and breach the airlock** — the genre that lives or dies on whether the
flight model is honestly Newtonian, whether a railgun slug takes real travel
time across fifty kilometres so you have to lead, whether your coffee cup slides
aft when the engine lights, and whether "down" is a different direction in a
burn than on a spinning habitat ring. It is the most _systems-ambitious_ of the
five ruleset cells, and proves V5's thesis from the **simulation** side: one
engine that also runs a modern crime sandbox can carry a bit-deterministic
ship-sim on the same spine.
The cell is one of two sub-rulesets in V5's Sci-Fi cell. Hard Vacuum is the
crew-operated ship-sim campaign (`V5SciFiHardVacuum`); its sibling, the Mass
Effect-style **Galactic Squad** RPG, shares the same galaxy geography and
faction map but commands a squad on foot instead of flying a Newtonian hull —
that surface is documented at
[./scifi-galactic-squad.md](./scifi-galactic-squad.md). On disk, both map to the
_same_ engine join-key, `EV5Cell::SciFi` — two rulesets over one cell. This page
inventories what the Hard-Vacuum stack actually does on the player's side of the
screen, and points at the exact Unreal C++ behind each feature. For the full
mode taxonomy, roster, and the scope this slots into, start at the hub:
[../V5_features.md](../V5_features.md).
## What ships, honestly
**The cell's systems are real, compiled, and tested.** The campaign module and
the Newtonian core it composes both exist under `V5/ue/Source/` with a
`Public/`/`Private/` split, a `*.Build.cs`, and a `Private/Tests/` automation
spec, and the linker has been through them on this box:
`libUnrealEditor-V5SciFiHardVacuum.so`, `-V5Spaceship.so`, and the competitive
`-V5SciFiPvP.so` all sit in `V5/ue/Binaries/Linux/`, built by the `ueagent` user
(the Spaceship core carries **61 `.o`** objects in the build tree, the cell and
PvP modules **13** each). The signature logic is real domain-specific code — a
closed-form kinematic integrator, a quadratic lead-prediction solver, a
cascading component-damage walker, a matched-drift boarding gate, a
faction-reputation endgame resolver — and each is pinned by UE
`IMPLEMENT_SIMPLE_AUTOMATION_TEST` assertions
(`V5.SciFiHardVacuum.CatalogInventory`, `.ShipPhysicsCombat`,
`.CrewCoopFactionState`, `.CapitalCruiserExpansion`, plus `V5.Spaceship.Systems`
and `V5.Spaceship.FlipBurnDeterminism`) that check _values_, not truthiness.
**"Cell" means a thin campaign module composing a shared core.** Exactly like
the other cells, V5 puts the frame-critical verbs in a shared module and makes
the playable sub-ruleset a content-and-validation module.
`V5SciFiHardVacuum.Build.cs` declares a dependency on precisely one gameplay
module — `V5Spaceship` — and its job is to _author and validate_ the campaign
catalog (24 missions, three endings, five crew stations, six factions, the
Year-1 capital cruiser) and to _compose_ the deterministic Newtonian solver into
an Expanse shape. The novel per-frame algorithms live one layer down in that
core, and the sections below keep the two layers distinct.
**The solver is not PhysX, and there are no `.uasset` binaries.** Two honest
qualifications. First, despite the monolith's prose, hard-vacuum flight does
**not** run on PhysX: `V5ShipPhysicsSystems.cpp` is a hand-written, closed-form
kinematic integrator — no rigid body, no physics tick — and the runtime ship
pawn sets `bCanEverTick = false`. That is the honest and, for rollback
determinism, the _better_ call. Second, the three ship classes are a validated
JSON catalog, the 18 hull meshes are recipe paths under
`/Game/V5Spaceship/Meshes/`, and the capital cruiser is a catalog struct — not
cooked art. And one seam matters: **the in-world zero-G shooter — marines
breaching room-to-room — is not in this module.** Only the boarding _clamp gate_
and the zero-G recoil _math_ live in `V5Spaceship`; the actual gunfight runs on
the shared squad-combat/GAS stack the cell feeds, the same ruleset Galactic
Squad uses. Where a claim depends on art, audio, or the in-world runtime, this
page says so.
## The hard-vacuum experience — what the cell plays like
Strip the campaign down and you get three interlocking spines: a ship you crew,
a belt you cross, and a faction map you play one contract at a time. All three
are validator-enforced catalogs built by
`UV5_HardVacuum_Catalog::BuildModeCatalog`
(`V5/ue/Source/V5SciFiHardVacuum/Private/V5SciFiHardVacuumSystems.cpp:171`), and
`ValidateModeCatalog` (line 318) refuses anything but the authored shape.
### Three ship classes and five crew stations
The player flies one of **three controllable classes**, and their tuning is real
data, not flavour text. `ship_catalog.json` (schema v1, validated by
`UV5_Ship_Catalog::ValidateShipCatalogJson`) authors the **Skiff** (82 t dry,
2.0 G main engine, 42°/s RCS, 18 t propellant, 1–2 crew), the **Corvette** (480
t, 1.3 G, 24°/s, 96 t, 3–6 crew), and the **Frigate** (1 700 t, 1.0 G, 14°/s,
260 t, 5–10 crew). The numbers are internally consistent in the way the genre
demands: the heavier the hull, the _lower_ its sustained thrust-G and the
_slower_ its attitude torque — a Frigate turns like the freight train it is. The
validator insists on **exactly three player classes** (Capital is
NPC/raid-scale, deliberately excluded) and **exactly 18 hull meshes**, all under
the canonical content path.
Crewing a Frigate is the cell's co-op heart. `BuildCrewStations` (line 234)
authors **five stations — Pilot, Navigator, Weapons, Comms, Engineer** — each
mapped to the ship component it owns (Weapons→Weapons, Comms→Comms,
Engineer→Engine, Pilot/Navigator→Bridge) and stamped with primary-and-assist
authority tags. `UV5_HardVacuum_CrewCoop::BuildCrewCoopSession` (line 377) then
seats **one to six players**: the first five take primary seats, a sixth is a
relief seat, and any station left unmanned is added to `AiAssistedStations` so a
solo player still flies a fully-crewed ship. The `CrewCoopFactionState` spec
proves both ends — a solo session leaves **four AI-assisted stations**, a
six-player session **covers every station** with the last player flagged
`bReliefSeat`.
### Twenty-four contracts, six mission shapes, and faction politics
`BuildMissions` (line 193) authors a **24-mission campaign, one hour each, 24
hours total** — a count the validator pins with
`IsNearlyEqual(sumHours, 24.0, 0.01)`. The missions rotate through six authored
shapes — **Transit, Salvage, Combat, Boarding, Political**, and a **Finale** on
the last beat — each carrying a recommended ship class and a focus station, so
the campaign teaches every seat. Roughly a third are **faction-restricted**:
they carry a `RequiredFactionId` and a `MinimumFactionReputation` gate, and
`UV5_HardVacuum_Factions::EvaluateFactionGate` (line 413) enforces it honestly —
open contract work passes freely, but a gated mission checks that the faction's
running state exists, is not locked out, and clears the reputation bar,
returning a human-readable reason either way.
The politics resolve at the end. The galaxy holds **six factions — three
primary** (Outer Authority, Free Belt, Black Channel) **and three secondary**
(Saturn Brokers, Miner Guild, Signal Clergy), and `ResolveEndgameFactionState`
(line 444) walks the player's standing to pick a winner: the highest-reputation,
non-locked _primary_ faction dominates the ending, every secondary faction above
reputation 50 is logged as an ally, and the matching one of **three endings**
(each gated at reputation 70) is selected. The spec drives it concretely — with
the Free Belt at 82, the resolver names `ending.hard_vacuum.free_belt`, lists at
least two secondary allies, and confirms the Political/Finale missions counted
toward the endgame. (Faction names are planning ids pending IP-clearance; the
geometry behind them is described, not cooked.)
## Newtonian flight and ship systems
The flight model is the cell's reason to exist, and every verb of it lives in
the shared `V5Spaceship` core. The diagram below is the honest composition: a
thin campaign catalog plus one Newtonian solver, with three outward seams — the
deterministic substrate the netcode rolls back, the boarding handoff to
squad-combat, and the competitive `V5SciFiPvP` layer.
```mermaid
flowchart TB
subgraph MODE["V5SciFiHardVacuum — catalog + validate + compose"]
HVC["UV5_HardVacuum_Catalog
24 missions · 5 crew stations · 6 factions · 3 endings"]
end
subgraph CORE["V5Spaceship — deterministic Newtonian core"]
Eng["MainEngine + RCS
kinematic integrator · reaction-mass economy"]
Flip["FlipAndBurn
slerp-to-vector then decel burn"]
Grav["GravityZone + LooseObject
thrust-G / spin-G / zero-G · coffee cup"]
Wep["PDC · Railgun · Torpedo
one quadratic intercept solver"]
Dmg["DamageModel + Boarding + ZeroGRecoil
cascades · clamp gate · Newton's third law"]
end
HVC --> Eng & Flip & Grav & Wep & Dmg
Eng -. deterministic substrate .-> Net([V5Netcode 8-frame rollback])
Dmg -. boarding clamp .-> Squad([shared squad-combat ruleset])
CORE --> PvP["V5SciFiPvP
1v1 Ship Duel · 5v5 Capital Raid"]
```
### The kinematic integrator and the reaction-mass economy
A ship is a value. `FV5ShipNewtonianState`
(`V5Spaceship/Public/V5SpaceshipTypes.h:107`) carries position, velocity, an
`Attitude` rotator, angular velocity, a `ReactionMassKg` propellant budget, and
the current flight mode — and the whole simulation is a pure function over it.
`UV5_Ship_MainEngine::ApplyMainEngineBurn` (`V5ShipPhysicsSystems.cpp:91`) is
the heart, and it is a genuine second-order kinematic step:
```
a = Attitude.Vector() · (MaxMainEngineG · 9.80665 · throttle)
pos = pos + v·dt + ½·a·dt²
v = v + a·dt
reactionMass -= throttle · MaxMainEngineG · dt · 7.5
```
Thrust always points along the ship's facing vector, so you steer by rotating
and burning — there is no lateral "strafe to target." Crucially, **the engine
only fires while it has propellant**: when `ReactionMassKg <= 0`, throttle is
zero, or `dt <= 0`, the function refuses to integrate and drops the ship to
`Coast`. That is a fail-loud seam — a dry tank coasts, it does not silently keep
accelerating. `UV5_Ship_RCSThruster::ApplyRCS` (line 110) integrates rotation
the same honest way: it clamps each pitch/yaw/roll axis to `[-1, 1]`,
accumulates angular velocity scaled by the class's `RCSTorqueDegPerSecond`,
integrates and normalizes the attitude, and spends its own smaller propellant
slice (`input·dt·0.65`). The runtime `AV5_Ship_NewtonianPawn`
(`V5ShipNewtonianPawn.cpp`) is a deliberately inert `APawn` —
`bCanEverTick = false` — whose `SimulateSubstep` calls the two static solvers
and then converts solver metres to UE centimetres (`PositionMeters · 100`). The
pawn is a view; the state is the simulation.
### Burn, coast, and flip-and-burn
The signature manoeuvre is the Expanse-style **flip-and-burn**, and it is a real
two-phase routine, not an animation. `UV5_Ship_FlipAndBurn::StepFlipAndBurn`
(`V5ShipPhysicsSystems.cpp:145`) takes a target velocity, computes the `DeltaV`
needed to reach it, and if the nose is more than **1°** off the required burn
vector it **slerps the attitude** toward it (`FQuat::Slerp` rate-limited by
`RCSTorqueDegPerSecond · dt`), spending RCS propellant. Once aligned within a
degree, it hands off to a full-throttle main-engine burn — a hull that
physically rotates to face its deceleration vector and burns to kill velocity,
the genre's "180° rotation under RCS, then full deceleration burn." And it is
**bit-deterministic**: `V5.Spaceship.FlipBurnDeterminism`
(`V5SpaceshipTests.cpp:121`) runs a 3 600-step flip-and-burn **twice from the
same initial state** and asserts the final position, velocity, and attitude
match to within 0.001 — the stability the
[netcode rollback model](../architecture/netcode-authority-and-determinism.md)
needs to rewind and resimulate eight frames of ship-duel without desync.
### Gravity zones and the coffee cup
Habitat gravity changes with what the ship is doing.
`UV5_Ship_GravityZone::EvaluateGravityZone` (line 132) resolves three regimes:
**Thrust-G** (down is opposite the thrust vector during a burn), **Spin-G**
(down is radial on a centrifuge ring), and **Zero-G** (no field at all — it
returns an empty result). Pawn locomotion reads it to decide whether you walk
down the deck, walk around the ring, or float. The most charming detail is the
loose-object simulation: `UV5_Ship_LooseObjectSim::SimulateLooseObject`
(line 178) models the proverbial coffee cup as keeping its own momentum while
the ship accelerates underneath it —
`relativeVelocity -= shipAcceleration · dt`. Strap it down and it rides along;
leave it loose during a burn and it slides aft, exactly as the cell's
`ShipPhysicsCombat` spec asserts when it lights a 4 m/s² burn and watches the
cup drift across the table.
### One intercept solver, three barrels
Ship combat is built on a single, real **lead-prediction solver**.
`SolveIntercept` (`V5ShipPhysicsSystems.cpp:26`) frames "when does a projectile
of speed _s_ launched from the origin meet a target at relative position **P**
moving at relative velocity **V**?" as the quadratic `|P + V·t|² = (s·t)²`,
expands it to `A·t² + B·t + C` with `A = V·V − s²`, `B = 2·P·V`, `C = P·P`,
takes the earliest positive root, and confirms the impact point is in range.
Three weapons reuse it with strict niches: the **PDC** fires 7 km/s bullets out
to 8 km and additionally gates on a `TrackingQuality ≥ 0.3` envelope; the
**railgun** throws a 60 km/s slug out to 50 km, so the slug's travel time is
real and the player must lead; and the **torpedo** is a guided physics body
(`SimulateTorpedoStep` accelerates it 80 m/s² toward its mark) that is _itself_
a valid PDC target — the spec fires the PDC at a torpedo's body to prove
point-defence works — the whole salvo-saturation metagame in one solver. Every
failure path returns a human-readable `FailureReason`, never a silent miss.
### Component damage, boarding, and zero-G recoil
Damage is per-component and **cascading**.
`UV5_Ship_DamageModel::ApplyComponentDamage` (line 236) subtracts HP from the
hit component, then walks every component to emit downstream effects: an engine
below half thrust flags `effect.engine.thrust_reduced` and at zero goes offline;
comms below half emit `effect.comms.torpedo_guidance_degraded` (shoot out the
comms array and the enemy's torpedoes go dumb); weapons degrade PDC tracking; a
dead reactor triggers an emergency shutdown; and a battered airlock (below 35%
HP) flags `boarding_vulnerable`. Boarding then has teeth:
`UV5_Ship_Boarding::EvaluateBoardingClamp` (line 251) only permits a magnetic
clamp within **25 m and near-zero relative drift (≤ 0.5 m/s)**, and only marks
the airlock breach-ready within **5°** alignment — the Expanse's matched-drift
rule. Past that gate, the marine fight is the shared squad-combat ruleset, not
this module. Finally `UV5_Ship_ZeroGCombat::ApplyRecoilTumble` (line 270)
enforces Newton's third law on foot: firing in vacuum pushes the shooter back
(`v − dir·impulse/mass`) and induces a tumble about `dir × up`. These map onto
the `V5_AttributeSet_Spaceship` GAS attributes and the `IMC_SciFi_RCS` /
`IMC_SciFi_ZeroG` input contexts described in the architecture companion.
## The Year-1 capital cruiser and competitive ship combat
The campaign's endgame scales up. `BuildCapitalCruiser` (line 281) authors the
**Asterion-class Capital Cruiser** — a Capital-class hull (4 800 t dry, 0.65 G,
6°/s RCS, 720 t propellant, eight crew) with **eight crew stations** (including
the reactor and damage-control seats the validator insists on) and **eight
weapon hardpoints**: a spinal railgun, four PDC mounts
(port/starboard/dorsal/ventral), a forward and aft torpedo bay, and a boarding
clamp. `ValidateCapitalCruiserCatalog` (line 340) pins every id, the eight-crew
capacity, and the boarding/5v5-raid flags.
That cruiser anchors the competitive layer, which lives in its own module,
`V5SciFiPvP` (over `V5Netcode`, `V5OnlineServices`, and `V5Spaceship`).
`UV5_SciFiPvP_Catalog::BuildCatalog` authors **two modes — a 1v1 Ship Duel on
Corvettes and a 5v5 Capital Raid on Frigates** — across **eight arenas**, each
with an environmental hazard (debris field, ring plane, magnetosphere, ship
graveyard) and rollback support. Both modes run on **dedicated servers at 60 Hz
with an 8-frame rollback window**, and
`UV5_SciFiPvP_Rollback::EvaluateShipPvPRollback` delegates straight to the
shared `V5Netcode` rollback evaluator that the determinism test makes safe.
Capital Raid is the ranked, anti-cheat-gated mode: `EvaluateMatchResult`
computes ranked points as
`1200 + scoreDiff·100 + (cores·200 + breaches·75) + clamp(duration, 0, 180)·2`,
and **fails closed** — rejecting with a typed reason (`anti-cheat.dirty`,
`match.leaver_forfeit`, `match.loss`) rather than awarding a fabricated score.
The Year-1 expansion adds six ranked Capital Raid maps and a 90-day season bound
to the Asterion cruiser, and a Pro Circuit Season 2 catalog authors a full
**16-seed, 30-match double-elimination bracket** over eight esports-only maps —
all of it validator-pinned by `V5.SciFiPvP.Catalog`, `.RollbackModes`,
`.CapitalRaidRankedExpansion`, and `.ProCircuitSeason2Expansion`.
## Where this connects
The Hard-Vacuum cell is one face of a single game, and it hands off at
well-defined seams:
- **Its own sibling.** The Mass Effect-style Galactic Squad RPG shares this
cell's galaxy, factions, and the `V5Spaceship` boarding seam, but commands a
squad on foot instead of flying a hull — see
[./scifi-galactic-squad.md](./scifi-galactic-squad.md).
- **The shared spine.** The `EV5Cell::SciFi` join key, the Bureau-XP ledger, the
GAS attribute sets, the netcode rollback substrate, and the squad-combat
ruleset the boarding clamp hands off to are the cross-cell systems documented
in [./shared-cross-cell-systems.md](./shared-cross-cell-systems.md).
- **Architecture companion.** The deterministic Newtonian solver, the intercept
mathematics, the boarding clamp, and how this module sits beside the Chaos
vehicle and horse-AI locomotion systems are documented with line citations in
[../architecture/spaceship-vehicles-and-mounts.md](../architecture/spaceship-vehicles-and-mounts.md).
- The feature hub: [../V5_features.md](../V5_features.md).