# umbral.Config
The one shared module. Every number UMBRAL obeys and every table it reads lives here so a
system never invents its own copy.
**Read by:** `scenes/main.scene/build.luau` (which builds the map from `MAP`), `umbral.Art`
(region palettes and backdrop depths), `umbral.Ilva` (the `PLAYER` tuning table),
`umbral.Enemies` and `umbral.Hud`.
## What it holds
| Table | What it is |
|---|---|
| `PALETTE` | The seven colours the whole game is drawn in, as linear rgb. Void, stone, bronze, turquoise, amber, bone, blood. |
| `PLAYER` | Ilva's tuning: health, the Coro's maximum and what fills and spends it, the healing ring, i-frames, the two swings' damage and timing, the Badajo's reach, the echo's radius and duration. |
| `REGIONS` | The nine regions: id, display name, the palette tint it leans on, its musical bordón, and the depth band its backdrop sits at. |
| `MAP` | The geometry: `solids` (solid rectangles), `oneWay` (jumped up through), `braziers`, `bells`, and the spawn point. |
## Conventions
A tile is **one world unit** and the grid is whole units. Gameplay is the plane `z = 0`.
Rectangles are `{ x, y, w, h }` with `x, y` the bottom-left corner. Ilva's collision box is
`0.625 × 1.25`, so a corridor is at least 3 units high and a doorway at least 2.
A bell is named `bell_<name>`; hidden geometry is named `hidden_<anything>`. Those two names
are the only contract between the art pass and the echo mechanic.
`Config.colour(name)` returns the three channels of a palette entry so a light can be built
from a name rather than from numbers repeated in five files.
# umbral.Look
The side camera. An orthographic camera that rides the player down Véspera.
**Attaches to:** the `CameraRig` entity of the scene's PlayerPrototype. It needs a sibling
`Camera` component — that is what it writes each frame — and it is happiest beside an
`AudioListener`.
## Why the behaviour field is empty
`Camera.behavior` is left unset on purpose. The engine documents that a camera with no
behaviour has nothing overwriting its transform, which is what lets this component own the
pose every frame without fighting a built-in rig. The built-in `twoDKit.Camera2D` was
rejected: it is pixel-perfect for a 128×128 atlas of 16 px tiles, and UMBRAL's reference art
is painterly.
## Fields
| Field | Default | What |
|---|---|---|
| `height` | 9 | World-space vertical extent the frame covers (`orthoHeight`). |
| `damp` | 0.10 | Follow smoothing per frame at 60 Hz. |
| `lookAhead` | 2.6 | How far ahead of her travel the frame leads, in world units. |
| `lookDown` | 1.2 | How far the frame drops when she is falling. |
| `distance` | 14 | How far in front of the play plane the camera sits. |
## How it follows
It reads the entity in `Camera.follow`, which the engine binds per peer when a player's
prototype clone spawns — so every player looks through their own camera at their own body,
and no id is ever authored ahead of time. If that slot is not readable it does nothing rather
than guessing, which is why a camera that never moves means the follow binding is missing
rather than the maths being wrong.
The aim is the body's position lifted 1.9 units, so the frame is centred on Ilva rather than
on her feet; the horizontal lead is read from her travel and clamped, so a sprint leads the
frame and a standing still camera does not creep.
# Art
The architecture and decoration of Véspera, built at scene load.
`Art.decorate(map, Config)` is called once by `scenes/main.scene/build.luau`, after the
map's solids, braziers and bells are placed. It hangs everything under a single
`art_root` entity, dropping the previous one first, so a scene that rebuilds on every
write lands the same content once.
What it builds:
- **The three depth bands** — a far card at z=-36 (the drowned city), silhouette
arches at z=-26 separating it from the middle card, the middle card at z=-18, and
the real arcades at z=-9 in front of both.
- **The near silhouettes** at z=+2.5 — columns and hanging chains the frame is seen
through.
- **El Campanario** — two tiers of blind arcading, corbels under every climbing
ledge, wall sconces with flame, chains from the vault, banners.
- **La Nave de las Cuerdas** — an arcade on the play plane's shoulder, vault ribs,
the jellyfish of cold light adrift above the water, candle ledges, rubble.
- **The props the map names** — each brazier's plan-pass cube is replaced by the
generated copper bowl while its amber light is kept; each bell is replaced by the
generated cracked bronze bell and given a black-oak yoke, iron straps and the chain
that carries it into the dark.
Adds no colliders: the play plane stays exactly what `umbral.Config.MAP` states.
`Art.echoPulse(x, y, radius)` is the echo's visible half — a ring of turquoise light
leaving a struck bell, carried by `umbral.art.EchoRing`. `ilva` calls it if it is
there; the game runs without it.
# umbral.Motor
Ilva's motor: a 2D platformer body driven on the engine's own physics.
**Attaches to:** the player body entity (the `body` of the scene's PlayerPrototype). It needs
a `BoxCollider` and a `Physics` component — it adds both itself if they are absent — and it
reads an input map carrying `move`, `jump` and `sprint`, which the scene supplies as
`inputMaps.umbralMove` (keyboard, gamepad and touch together).
## Why it is not a script-driven kinematics solver
The body is a **dynamic rigid body** with a box collider, held to the XY plane by axis locks
(`lockTranslationZ`, `lockRotationX/Y/Z`). This component writes the horizontal velocity from
the move control and the vertical velocity for jumps; the engine's simulation does the rest —
collisions, one-way ledges, contact with anything in the world. Nothing here re-implements
collision, so a ledge added anywhere in the scene works the moment it exists.
`twoDKit.Player2D` was installed first and rejected: its motor holds the body still unless a
`twoDKit.Level2D` exists (`update` returns early on `#Levels.all() == 0`), and it activates
controlsKit's `platformer` scheme, which suppresses every other input map in the `player`
group. UMBRAL builds its own architecture, so both were dead weight here.
## Feel, and the fields that set it
| Field | Default | What |
|---|---|---|
| `speed` | 7.5 | Top horizontal speed, units/s. |
| `accel` / `airAccel` | 60 / 34 | How fast she reaches it on the ground and in the air. |
| `friction` | 48 | How fast she stops with no input on the ground. |
| `jumpSpeed` | 15.5 | Upward speed a full jump gives. |
| `jumpCut` | 0.45 | Share of the rise that survives letting go early — variable height. |
| `airJumps` | 0 | Mid-air jumps. Set to 1 by the Vuelo de la Sal. |
| `canDash` | false | The Paso de Marea. |
| `coyote` / `buffer` | 0.10 / 0.12 | Grace after leaving a ledge, and grace before landing for an early press. |
`grounded` and `facing` are public and synced, so every peer sees her footing and her heading.
## Methods
- `ref:readState()` — `{ x, y, vx, vy, grounded, facing, clock, dashing, airJumpsLeft }`.
`clock` advancing is the proof the motor is stepping; if it stays at 0 the body is not
being simulated, whatever else looks right.
- `ref:placeAt(x, y)` — put her feet at a point, at rest.
## The two failures worth remembering
Ground is detected through `Physics.groundContact`, with a short downward raycast under her
feet as the fallback, so a body resting on a merged collider reads as standing.
Movement silently doing nothing has two causes seen here: a control read as `v.x` when the
axis reports a bare number (the handler now accepts both), and a suppressed input map — the
motor's own map is in the `umbral` group precisely because controlsKit's `platformer` scheme
suppresses everything in `player`.
# umbral.Enemies
What lives in Véspera, and where. The scene calls `Enemies.populate(map, Config)`
once during the build; every foe is a `spawnSynced` entity carrying its own
component from `umbral/foes/`.
| Foe | Where | What it teaches |
|---|---|---|
| Penitente Ciego | El Campanario x15, La Nave x80 | It is blind. It hunts the SOUND of her feet and her bell, never her body. Stand still and walk past behind it. |
| Ahogado Oficiante | El Corredor x33 | Its chant seals a ring round her. Leaving the ring (dash) or ringing her bell breaks it. |
| Salino | ledges at x61 and x77 | An enemy above you is a different problem. It clings, it aims, it spits. |
| Siete Cuerdas | x66 and x68.6, two out of phase | Unkillable. It teaches the beat: quiet, tight, cutting. |
| El Ciego de la Nave | the dais, x100 | The boss. It rings before every attack, cracks at half health, and leaves a way of moving behind. |
## The damage contract
Every foe exposes a synced `health` field. **Writing it down is a hit** — the foe
watches it and reacts (staggers, cracks, dies). So Ilva's Badajo can hurt anything
here by writing `health` on the entity it found with its cast, without knowing
what it hit. `Enemies.hurt(name, amount)` does the same by name.
A foe hurts her through `umbral.foes.Sense.hurtPlayer(amount, fromX)`, which
calls `umbral.Combat` or the `umbral.Ilva` component by whatever name the ilva
slice exposes, and falls back to writing `health` on the body.
`SieteCuerdas` cannot be killed: a drop in `health` only tightens its beat.
## Sense
`umbral.foes.Sense` is the only place a foe is allowed to learn anything about
Ilva: `Sense.noise()` (0 silence .. 1 a bell at arm's length, with where it came
from), `Sense.bell()`, `Sense.body()`.
# umbral.Ilva
Ilva herself, beyond her body: the bell fragments she has left, the Coro, the Badajo's two
swings, i-frames and knockback, the healing ring, death and the return to the last bell, and
the game's signature verb — ring a bell and the room's hidden geometry shows.
**Attaches to:** the player body, beside `twoDKit.Player2D`. The motor on that body owns her
movement; this component never replaces it, it reads `state()` and touches her position only
to hold her during a healing ring, to shove her with a blow, and to put her back at the last
bell. It reads its controls through the `umbral` controlsKit scheme (`Combat.registerScheme`).
## Fields
| Field | Sync | What |
|---|---|---|
| `health` | yes | Bell fragments left. The HUD draws this. |
| `healthMax` | yes | Bell fragments she can hold. |
| `coro` | yes | The Coro: filled by a landed strike, spent by the healing ring. |
| `coroMax` | yes | How much Coro she can hold. |
| `dead` | yes | Down, and walking back to the last bell. |
| `swing` | yes | `light`, `heavy`, or empty. |
| `chain` | yes | Where she is in the three-strike chain. |
| `healing` | yes | Holding the healing ring: held still until it lands or she lets go. |
| `revealed` | yes | The room's hidden geometry is lit by the last echo. |
| `lastBell` | yes | The last bell she rang, bare name. Respawn goes there. |
| `invuln` | no | Seconds of i-frames left after a blow. |
## Verbs
- **Toque ligero** — tap attack. Three chainable strikes; the third reaches further and
recovers slower. A press inside `chainFrom` queues the next one.
- **Toque pesado** — hold attack past the light swing. Descending, heavier, anchors her.
- **Campanada** — hold heal standing on the ground with Coro to spare. She is pinned to the
spot for `healTime`, pays `coroPerHeal`, gains `healAmount`.
- **Eco** — press echo. Rings the nearest `bell_` in `ecoRadius` and shows every `hidden_`
entity for `ecoTime` seconds. A swing that touches a bell does the same.
## Methods
`takeHit(damage, dirX)` — a blow from anything that wants to hurt her. `kill()`,
`addCoro(amount)`, `status()`.
# BellLook
Gives every bell in the map its real body.
`build.luau` places each bell as `bell_<name>` carrying a cube and a turquoise `Light`; the
shape is a stand-in for the art. This component — attached to the `Map` root by
`umbral.Art.decorate` — finds those entities and replaces the cube with
`umbral.art.meshes.bell_great`, the generated bronze bell (cracked, verdigrised, names engraved
around the lower band).
It replaces the whole `Model` rather than writing its `model` field: a write to that field after
the component exists reads back as the new mesh but never reaches the renderer, so the bell would
keep drawing its cube. Each bell keeps its position, the scale `umbral.Art` gives it from its own
radius, and its `Light`.
Idempotent: it runs once and stops. Siblings it needs: nothing.
# Motes
A field of small emissive flecks drifting through the air — the salt and the dust of Véspera.
Attach it to an empty entity placed where the field should be centred; it spawns its own
`mote_*` children on `awake` and moves them on three slow sines in `update`. Re-attaching
gathers the children already present rather than building a second field, so a hot reload
does not double it.
Fields: `count`, `width`, `height`, `depth` (the extent it fills), `size`, `speed`, `seed`
(arrangement), `colorR/G/B` and `glow` (how hard the evidence blooms). It needs no sibling
component; give it a parent under the scene's map. `umbral.Atmos` places three of them:
the tower's falling salt, the nave's, and the amber dust that catches the braziers.
# umbral.Hud
The face of UMBRAL, on the camera rig: the HUD, the title screen and the map.
**Attaches to:** the `CameraRig` of the scene's PlayerPrototype (the scene calls
`tryAttach(rig, "umbral.Hud", {})`), beside the `Camera`, `umbral.Look` and `AudioListener`.
## What it puts on the glass
- `umbral_hud` — the corner of `play.png`: bell medallion, VIDA and CORO in tapered bronze
cases, the region name, the way into the map. Layer 20.
- `umbral_title` — `title.png`: the bronze wordmark, the subtitle, the drowned bell, the
filigree corners, the menu. Shown on entering play, layer 60, and taken down by NUEVA PARTIDA.
- `umbral_map` — the rooms of `umbral.Config.MAP` drawn as a plan, with Ilva's mark on it.
All three scale from `ui.screenSize().width`, so a phone gets the same display fitted to a
410-point canvas.
## What it reads
`health`, `healthMax`, `coro` and `coroMax` off the local player's `umbral.Ilva` component,
found through `layers.active.players.localPlayer`, its children, or the `body` entity. Every
read is `pcall`ed and falls back to a safe value, because that component is another slice's and
may not be attached yet. The bars ease toward the values rather than snapping.
The region comes from the world position against `umbral.Config.REGIONS`, and the same walk
drives the region's bordón, Ilva's footsteps (one per stride of travel), the impact when a
landed strike fills the Coro, a lower impact when health drops, and the bell on the echo
control. Slots the engine cannot answer are skipped, never raised.
## Callbacks
`title_new`, `title_options`, `title_quit`, `toggle_map`, `close_map`. They only fire in play.
# IlvaLook
Puts Ilva's real body where the scene left a stand-in.
`build.luau` gives the player's visual (`IlvaVisual`, a child of the motor's `body`) a
capsule, because the look has to be replaceable without touching movement. This component —
attached to the `Map` root by `umbral.Art.decorate` — waits for the player rig to exist (it is
a prototype, so it is only there once the peer has joined), points the visual's `Model` at
`umbral.art.meshes.ilva`, and scales and offsets her from the visual's own measured bounds so
her feet stand on the body's origin and she is as tall as her collision box, 1.25 units.
It is idempotent: a visual already carrying the mesh and standing at the right size is left
alone, and it stops correcting once the measurement agrees with the target.
Siblings it needs: nothing. It only reads `IlvaVisual` and its `Model` component.
# Atmosphere
Applies the medium of Véspera one frame after the scene loads: the fog, the display
transform, bloom and the vignette.
The scene build cannot register a post-process pass or write the fog — those are runtime
state and the build refuses to hold them — so `umbral.Art.decorate` places an entity
carrying this component and the component applies them. It re-applies on every reload
and every pass is looked up by name before it is registered, so nothing stacks.
Needs `umbral.Atmos` (it calls `Atmos.runtime()`); no sibling component is required.