# atmos
The station's own life, with nothing visible in it: the soundscape, the dust
hanging in the air, the emergency lighting that fails and comes back.
Everything is spawned in play from `init.luau` under `atmos_*` names, so the
scene file stays the plan pass's and a reload never stacks a second copy. The
light components the scene already carries are driven in place — never rebuilt.
## Sound (`game/audio/*.soundClip`, all heard through the AudioListener on the player camera)
| what | how | where it comes from |
| --- | --- | --- |
| room tone | non-positional looping bed, never stops | everywhere |
| emergency alarm | looping, muffled, `maxDistance` 170 | down the tunnel mouth at (1, 4.2, −8) |
| the announcement | one shot every 44–62 s on two PA speakers | platform ceiling (6.6, 6.85, 26) and the stair (8, 6.5, 44) |
| water dripping | one shot every 2.5–8 s, pitched per hit | five ceiling leaks over the platform and the carriage roof |
| knocking | one shot every 16–38 s | the carriage door, the maintenance door, the evac shutter, and twice from the dark |
| footsteps that are not the player's | a short-lived spatial host at a random platform spot, every 20–42 s | along the platform, a few metres off |
| steel settling | one shot every 26–58 s | deep in the tunnel |
| work lamp hum | looping, follows the lamp's own brightness | the two sodium work lamps |
## Dust
`ambientDrift`'s `dustMotes` field — a **lit** particle field, so motes take
every lamp in reach and do not appear where no light falls. One field follows
the player camera (34 × 5.2 × 34 m), so the held torch is always full of dust;
standing fields give the platform, the carriage and the maintenance room depth
to look down. `game/materials/` is not used yet: the field brings its own.
## The failing lights
Every red downlight — the seven `emergency_*`, `carriage_red`, `evac_light` —
plus the dying tube in the maintenance room, runs its own failure clock: a
burst of stutter, then a slow filament ramp back up. Every 40–85 s the station
ring main browns out and all of them go together. The two sodium work lamps
stay lit and only wander a few percent.
What the cycle is doing is published to `Core.state.atmos` for anything that
wants to read it — `emergency` (0..1, the dimmest red lamp), `flickering`,
`brownout`, `events`, `workLamp`. `Atmos.debug()` reports the same from inside.
## Contract
`start(ctx)`, `update(dt)`, `onPlayer(player)`, `stop()`. Builds on the first
play-mode frame it sees; `update` wraps each half in `pcall` and `warn`s, so it
never raises out.
# survival
The `game.survival` module handles player interactions with the environment, including picking up items, opening doors, entering hiding spots, and solving the fuse-and-key puzzle required to escape. It defines the mechanics for environmental engagement and progression towards the game's objective. Other game slices, such as `game.player` (to update inventory) or `game.screens` (to display objectives), will call this module to manage these interactions and their effects on the game state.
# core
The `game.core` module defines the shared constants, rules, and global state for the game "LAST CARRIAGE: EVACUATION." It provides a central source of truth for game data like world layout, noise levels, item definitions, and narrative documents. All other game slices (`game.atmos`, `game.player`, etc.) require this module to access consistent game parameters and to interact with the shared game state and event bus.
# player
The player's body in the dark, for LAST CARRIAGE: EVACUATION. Required by
`scenes/main.scene/entrypoint.luau`, which calls `start(ctx)` on scene load,
`onPlayer(player)` once the local body exists, `update(dt)` every frame in
play, and `stop()` on unload.
It does not move the body itself — the avatar the scene's PlayerPrototype
spawns carries the engine's `CharacterController`, and the CameraRig carries
`@builtin::controller.first_person`, so walking and looking are already the
engine's. This module is everything on top of that:
- **The gait.** Walk, run and crouch, each with its own speed, its own
footfall cadence and its own loudness from `Core.NOISE`. Every footfall is
published twice: on aiKit's noise bus (`AI.noise(pos, metres, body, kind)`,
with `Core.NOISE` carried to metres by `METRES_PER_LOUDNESS`) and on Core's
`noise` event. Crouching is genuinely quiet and genuinely slower; running is
genuinely loud. `Core.state.noiseLevel` tracks what the body is making.
- **The eye.** Crouch drops the camera from 1.62 m to 1.04 m; a step bob and a
breath sway ride on top, both written through the camera behaviour's own
`offsetX`/`offsetY` fields so they compose with the look the engine drives.
- **The torch.** A narrow, hard-edged spot (13° outer, 6° inner, 11 m) held low
and to the right, with a small warm wash at the hand. The cell drains over
eleven minutes of play and the beam dims, misses and stutters as it goes.
- **The dust.** `Core.state.dust` rises on the track bed and in the service
tunnel, holds on the open platform and falls in the carriage and the
maintenance room, at the rates in `Core.DUST`. The mask's filter is spent
only in bad air, and at `criticalAt` the run ends on `died`.
- **The breath.** In and out on a clock that quickens with exertion and with
dust load, and audible in its own right.
## Reading it
`Player.get()` returns `{ gait, noise, crouched, battery, eye }` for the HUD,
the screens or a debug overlay. Nothing else here is another slice's to call.
## Notes for later passes
- Sounds live in `game/player.module/audio/` — `step_walk`, `step_run`,
`step_crouch`, `breath_in`, `breath_out`, all hand-synthesized PCM.
- The torch is lights only: no barrel mesh is drawn, so the beam is the whole
of what the player sees of it. A held-torch model is a slot for polish.
# screens
The `game.screens` module manages all user interface and visual displays in the game "LAST CARRIAGE: EVACUATION." This includes the main menu, opening cinematics, the heads-up display (HUD), in-game documents, and both the success and failure ending sequences. Other game slices, such as `game.core` (to update HUD elements) or `game.survival` (to display documents), will call this module to present information or transition between different screen states.
# game.creatures
The infected of LAST CARRIAGE: EVACUATION — three of them standing in the
station, and the one in the rescue uniform that keeps calling.
The entry point (`scenes/main.scene/entrypoint.luau`) requires this module and
calls `start(ctx)`, `update(dt)`, `onPlayer(player)` and `stop()`. `start` runs
once at scene load and spawns everything; `update` is the per-frame work and
never raises (its own body is wrapped, and a failure is warned rather than
thrown).
## The rule the slice is built on
**Nobody here can see the player.** Every creature is an aiKit `listener` brain:
sight is off in the preset, the brain writes spots from sounds only, and it acts
on where a noise *was*, never on where the player is. The player's footsteps
reach them through aiKit's own footstep noise (silent below its quiet speed, so a
crouch-walk is not heard and a walk is). Everything else the game makes a sound
with — a thrown bottle, a struck door, a bang — arrives on Core's `noise` event
and goes onto aiKit's bus here, with no maker named, so a creature walks to the
bottle rather than to whoever threw it.
`Core.NOISE` is a 0..1-ish loudness; aiKit hears in metres of carry and
multiplies that by the listener's hearing sensitivity. `metres()` maps between
them at 7 m per unit, which puts a walk at about 5 m and a run at about 11 m —
the reaches aiKit's own footstep noises use — and a crouch-walk under 2 m.
## What spawns
| entity | preset | where | what it is |
| --- | --- | --- | --- |
| `Infected_Carriage` | `infected` | (−0.55, 2.2, 20.2) | standing in the red light at the far end of the carriage |
| `Infected_Pillar` | `infected` | (7.55, 2.2, 27.4) | on the platform by the pillar row |
| `Infected_Stair` | `infected` | (8.10, 2.2, 40.4) | between the work lamp and the evacuation stair |
| `Rescuer` | `rescuer` | (6.20, 2.2, −5.0) | the dark south end of the platform, where the tunnel mouth is |
The bodies are one generated figure — `game/models/infected_rig`, made from
`design/references/infected-rescuer.png`: shredded black rescue coveralls with a
torn reflective stripe, dust-caked grey skin, goggles pushed up, both arms held
stiffly forward. The ordinary infected wear it smaller and tinted greyer; the
rescuer wears it full height and closest to the reference. `look.shape = "none"`
in both presets keeps aiKit from building its own stylised body underneath.
`game/models/infected_walk_anims.a` is a slow shamble, retuned onto each body's
`ClipPlayer` once the skinned mesh has hydrated.
## The rescuer
Blind like the others, and it never learns where the player is. It hears a
sound, walks to just short of it, stops, knocks three times on metal, and then
asks for an answer in the player's own voice (`game/models/infected_voice`,
spoken from its position). Its knock is put on the noise bus attributed to
itself, so the other infected come to it while the rescuer ignores its own
sound. Answering it — any loud noise nearby — is what brings it all the way in;
from then on it closes and strikes.
## Events and shared state
- `Core.emit("hurt", {})` when a creature lands a melee hit (the brain's `acted`
event, throttled).
- `Core.emit("hunted", { on = true|false })` when the number of creatures
actively following a sound, searching or attacking changes from zero.
- `Core.emit("voice", { who = "rescuer", line = "infected_voice" })` when the
rescuer speaks.
- `Core.state.creaturesNear` — how many are hunting; `Core.state.rescuerDistance`
— metres from the player to the rescuer.
- `Core.state.phase` reaching `dead` or `escaped` freezes the whole slice.
## Surviving a reload
A module reload in the middle of a game starts its module-level state again,
while the creatures it spawned are still standing in the station. `adopt()` takes
those over instead of spawning a second set on top of them; the Core noise
listener is registered when the file loads (not when the scene starts) for the
same reason, and only the newest registration acts.
## The nav map
The station's navKit map is baked when play starts. A scene load that did not
finish leaves it unbaked, and then every path comes back "no path on map
'default'" and the creatures stand still — so `ensureMap()` asks for the bake
itself the first time it finds no map, and does nothing once there is one.
## Known constraint
The carriage and the platform are separate islands on the nav map: 0.85 m of
track bed stands between the carriage door and the platform edge, which no walker
crosses. A creature therefore stays on the surface it was placed on — the
`Infected_Carriage` one is confined to the carriage, and the rescuer has to be
placed on the platform to reach the player at all.
## Debugging
`Creatures.debugState()` hands back the slice's live state table (read only):
the roster, the rescuer's `lead` / `callT` / `lastDist`, and the frame counter.
# door_open
[[describe]] Say what this sound is and what it is for.
# fuse_power
[[describe]] Say what this sound is and what it is for.
# pick_clink
[[describe]] Say what this sound is and what it is for.
# breath_masked
One shallow, tense breath through a rubber dust mask — inhale and exhale, air
hissing through a dense filter, faint fabric rustle. Quiet, muffled, close: a
person trying to stay silent. No reverb tail.
Plays once per breath cycle in `game/player.module`, pitched to fit the cycle,
so it quickens into a pant as the player runs or as the dust builds.
# probe_click
[[describe]] Say what this sound is and what it is for.
# step_wet_1
One boot on wet concrete in the tiled station — sole scuff into a soft wet slap,
with a little grit under it. Close and dry, no reverb tail.
Take 1 of 3. The player's stride cycles through the three takes so no footfall
repeats itself; the gaits are the same boot moved in pitch and weight, so a run
lands brighter and a crouch heavier and lower.
# step_wet_2
One boot on wet concrete in the tiled station — heel first, flat and heavy, a
short wet squelch and grit crunch. Close and dry, no reverb tail.
Take 2 of 3. The player's stride cycles through the three takes so no footfall
repeats itself; the gaits are the same boot moved in pitch and weight, so a run
lands brighter and a crouch heavier and lower.
# step_wet_3
One quick, lighter boot on wet concrete in the tiled station — a scuff and a
small wet slap of a worn sole, faint grit. Close and dry, no reverb tail.
Take 3 of 3. The player's stride cycles through the three takes so no footfall
repeats itself; the gaits are the same boot moved in pitch and weight, so a run
lands brighter and a crouch heavier and lower.