·
scene · drop-in viewer
What it does
No description provided yet.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
This asset doesn't declare a schema or structured payload.
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
74+items
# Art — NINE BELLS
The sprite runtime every slice draws through, and the hand-painted artwork of
the plague doctor and the infected.
## What it provides
### `NB.provide.makeSprite(spec) -> handle`
The way anything in this game gets a picture on screen. **Installed by
`art.start()`, which the scene entrypoint calls before traverse, rounds,
backdrop, kit and stage start** — so it is there by the time you need it.
A sprite is **one quad wearing one material**. An animation lives in a sheet:
the material's `frame` picks a cell out of a `cols` x `rows` grid, so playing an
animation is writing a number. Nothing spawns a quad per frame.
```lua
local s = NB.makeSprite({
texture = "<texture guid>", -- the sheet. required (unless `sheets`)
cols = 2, rows = 2, -- the grid it is cut into. default 1 x 1
inset = 0.035, -- crop this fraction off each cell's edges
x = 0, y = 0, z = NB.Z.play,
width = 2.9, height = 2.9, -- WORLD UNITS
pivot = "bottom", -- "bottom" (default) = (x, y) is the FEET
parent = "CityRoot", -- entity, entity name, or nil for FXRoot
name = "doctor",
-- Several sheets: a character's animations usually arrive as separate
-- images. Name them, and an animation says which one it plays from.
sheets = { idle = { texture = "<guid>", cols = 2, rows = 2 }, ... },
anims = {
idle = { sheet = "idle", frames = { 0, 1, 3, 2 }, fps = 3.5, loop = true },
run = { sheet = "run", row = 0, from = 0, to = 3, fps = 11, loop = true },
land = { sheet = "act", frames = { 0 }, fps = 3, loop = false,
next = "idle", scale = 1.0, offsetY = -0.30 },
},
anim = "idle",
tint = { 1, 1, 1, 1 }, -- multiplies
emissive = { 0, 0, 0, 1 }, -- ADDED. black unless you want glow
flip = false,
key = "lean", -- "alpha" | "lean" | "color" | "checker"
keyColor = { 1, 0, 1, 1 }, keyTolerance = 0.70, keySoftness = 0.06,
keyDespill = 0.85,
cutoff = 0.35,
static = true, -- scenery mode, see below
})
```
**The handle**
| Call | Does |
|---|---|
| `s:setAnim(name, restart?)` | play a named animation. Already playing it is a no-op unless `restart`, so a state machine may call it every frame |
| `s:setPos(x, y, z?)` | world position of the pivot |
| `s:setFlip(bool)` | face the other way — no second sheet |
| `s:setTint(r, g, b, a)` | multiply |
| `s:setEmissive(r, g, b, a)` | add — lantern glow, ember, a hit flash |
| `s:setFrame(n)` | set the cell directly; stops the animation |
| `s:setSize(w, h)` | world units |
| `s:setVisible(bool)` / `s:setParent(p)` | |
| `s:destroy()` | despawns the quad and frees its material |
Fields: `s.entity` (the EntityProxy), `s.anim`, `s.finished` (a non-looping
animation has ended), `s.x/.y/.z`.
Every method is a **no-op after `:destroy()`** rather than an error — a sprite
outliving its owner by a frame is normal and should not take a slice down.
**Three things about animations that are easy to get wrong**
- **On a ONE-frame animation that does not loop, `fps` is how long the pose is
HELD** before `next` takes over — `1 / fps` seconds. A landing at `fps = 30`
is a landing nobody sees.
- **`scale` and `offsetY` are per animation.** Separately drawn sheets never
agree about how much of a cell the figure fills or where its feet sit, so an
animation may resize and nudge its own quad. The doctor's values were set by
standing every pose on a known ground line and looking at the boots.
- **A sheet swap is free.** An animation naming a different `sheet` swaps the
texture and the grid on the material it already has.
**Keying.** The image generators do not write an alpha channel. Generate art
over a flat saturated colour that appears nowhere in the picture and key it out.
`key = "lean"` is the one to use: it scores how far a pixel leans toward
`keyColor`'s own channels and away from the others, which takes the flat
backdrop **and** the half-strength spill a generator paints for smoke, glass and
soft edges, while a warm rim light or a bone-white mask sharing part of the hue
survives. A plain RGB distance (`key = "color"`) cannot do that, because the
texture is sampled in linear space while the key colour is authored in display
terms. `keyDespill` pulls the background's hue back out of the pixels that
survive, which is what removes the coloured fringe on the cut edge.
`key = "checker"` handles the grey/white transparency checkerboard a generator
paints when asked for a transparent background. `key = "alpha"` trusts the
texture's own alpha.
**`inset` saves a sheet a generator drew grid lines on.** Asked for a grid, the
generators draw the borders they were told not to. `inset` walks the sampled
window in from each cell's edges as a fraction of the cell, cropping the seam
off instead of ringing every frame with it. The doctor's action sheet needs
`0.035`.
**`static = true` is the scenery mode, and the city slice wants it.** Static
sprites SHARE one material per distinct (texture, frame, look), so a thousand
tiles cost a handful of materials instead of a thousand. `:setAnim` does nothing
on a static sprite; `:setFrame` re-shares onto the material for that cell.
### The artwork
`art.SHEETS` maps a name to its sheet (`texture` guid, `cols`, `rows`, `inset`).
`art.doctorSpec(overrides)` and `art.infectedSpec(kind, overrides)` hand back a
ready spec so no other slice repeats the frame arithmetic or re-tunes the key:
```lua
local art = require("game.art")
local body = NB.makeSprite(art.doctorSpec({ parent = "doctor" }))
body:setAnim("run")
```
**The doctor's body is already on screen.** `art.start()` hangs it under the
`doctor` anchor and publishes the handle as **`NB.ext.artDoctor`** — drive it
with `:setAnim(...)`. It stands off if a body carrying real artwork is already
hanging there, so a slice that makes its own from `art.doctorSpec()` wins and
the doctor is never drawn twice.
**Doctor animations** — `idle`, `run`, `jump`, `rise`, `fall`, `land`, `hang`,
`ride`, `vault`, `probe`, `censer`, `drink`, `treat`, `down`. Four sheets, one
action each, drawn from one fixed description of the figure so he is the same
man throughout. Ask for a name that is not there and the sprite says so once in
the log and keeps playing what it had.
**Infected kinds** — `bearer` (stooped under a hooded sheet, a bundle held to
the chest), `crawler` (low and horizontal, dragging itself), `watcher` (tall and
thin, head tipped back at the sky). Animations `idle`, `walk`, `recoil`, `calm`.
## Reads
`game.nb` — the shared spine. Keeps its own session state under `NB.ext`.
## Design
See `/zero/source/design/spec.md`.
▲ 1↑ born
# nb
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this module provides and who
consumes it, then delete both comment lines. -->
TODO: describe this module.
▲ 0↑ born
# fogwall
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this material provides and who
consumes it, then delete both comment lines. -->
TODO: describe this material.
▲ 0↑ born
# Camera2D — the camera of Ashcross
The only camera in Nine Bells. Orthographic, side-on, never rotating, never
leaving the `NB.CAMERA.z` plane; it looks straight down -Z at a flat city on a
1080x1440 portrait screen, which covers sixteen world units vertically and only
twelve across.
## In play
It follows `NB.state.doctor` — not an entity, because the traverse slice runs its
own 2D physics and writes the doctor's position into the blackboard. There is a
deadzone the doctor moves inside without the camera answering (narrow
horizontally, because there is almost no horizontal room to give away), a lead in
the direction of travel scaled by run speed, and a softer vertical time constant
so a landing reads as weight. It publishes where it ended up into
`NB.state.cameraX` / `cameraY`, which is what the backdrop reads for its scripted
parallax and what every slice reads to decide whether a thing is on screen.
## When a moment takes it
| Call | What it does |
|---|---|
| `:panTo(x, y, seconds, ease)` | a TIMED move along an eased curve; `:isPanning()` says when it has arrived |
| `:zoomTo(height, seconds, ease)` | a TIMED change of lens. 16 is the playing frame, 10 a push onto a face, 22 the district opening out |
| `:setDrift(vx, vy)` | a slow creep added to a driven shot — a held frame that drifts is alive, one that is nailed down is a still |
| `:kick(amount)` | the shake: a bell, a hard landing, a floor giving way |
| `:snapTo(x, y)` | a cut. Take the override too (`:driveTo`) or the follow walks it straight back |
| `:driveTo(x, y)` | the untimed, damped drive |
| `:release()` | hand the shot back to the doctor, cancelling any pan and drift |
| `:setBounds(minX, maxX, minY, maxY)` | the city slice's limits on the FOLLOW. A driven shot ignores them: a staged moment may look above the roofline |
| `:pose()` | where the shot is, with the shake taken back out |
Ease names: `linear` `inQuad` `outQuad` `inOutQuad` `outCubic` `inOutCubic`
`inOutSine` `outExpo`.
## It also carries the staging clock
`game.stage` installs `NB.ext.stageTick` and `NB.ext.stagePostTick`; this
component calls them once a frame, in edit mode as well as in play, so a moment
can be rehearsed without entering play and locking the VFS for the other slices.
The pre-tick runs before the pose, so a cue that starts a pan this frame is
answered this frame; the post-tick runs after it, which is where anything held in
front of the lens is placed so it never lags the shake. Both calls are guarded: a
staging module mid-edit can never take the camera down with it.
## Usage
```lua
rig.component.add("Camera", {
projection = "orthographic",
behavior = asset.resolve("game.Camera2D", "component"),
})
```
Owned by the staging slice. See `/zero/source/design/spec.md`.
▲ 0↑ born
# Field Kit — NINE BELLS
The apothecary's field kit interface: title screen, case-notes page, the stacked portrait HUD (bells, contagion, charcoal, tincture belt, patients), pause, end cards, and the on-screen text of every spoken line.
## Provides
`start()` — called once by the scene entrypoint after the scene loads.
## Reads
`game.nb` — the shared spine: constants, the `NB.state` blackboard, the `NB.on`/`NB.emit` bus, and the `NB.provide` registries.
## Design
See `/zero/source/design/spec.md`.
▲ 0↑ born
# The Bell — the sound of Ashcross
The score, the air of the quarantined district, the shared one-shot library
every other slice calls, the mix, and every spoken line.
Nothing here is a recording. The whole bank is **arithmetic** — `audio.synth`
renders it and `audio.bake` writes it out as `.soundClip` assets under
`/zero/source/audio`. The bell is sixteen inharmonic partials struck twice a
fraction of a hertz apart, in a reverb that grows from a street to a nave
between the first toll and the ninth. The only recorded thing in the game is
the speech, and that is re-voiced through the same kit.
## What a slice calls
```lua
NB.sfx("vault") -- a one-shot
NB.sfx("step", { pitch = 1.05 }) -- with a trim
NB.sfx("brazier", { x = 12, y = 40 }) -- heard from where it happened
NB.music("late") -- crossfade the bed
NB.say("Bellman", "Nine. Ashcross is closed. God keep whoever is still inside it.")
```
An unknown name is a quiet no-op. `NB.say` **always** emits `"say"` first, so
the field kit prints the line whether or not there is audio behind it.
## The names
| group | names |
|---|---|
| feet | `step` (picks its own surface) · `step_stone` · `step_wood` · `step_water` |
| the arc | `jump` · `land` · `land_hard` · `ledge` (`grab`) · `drop` · `climb` · `bonk` |
| the cane | `vault` · `cane_probe` (`probe`) · `probe_sound` · `probe_rotten` · `board_crack` · `board_break` (`board.break`) |
| the censer | `puff` (`censer`, `smoke`) · `censer_chain` · `censer_empty` (`censer.empty`) · `brazier_refill` (`brazier`, `charcoal`) |
| tinctures | `tincture` (`drink`) · `tincture_theriac` · `tincture_aquavitae` · `tincture_vinegar` · `dash` · `belt` · `tincture.end` · `tincture.empty` |
| the round | `pickup` · `shutter` · `patient.near` · `treat_tick` · `treat_done` (`treat`) · `lantern_light` (`lantern`) · `gate` · `hurt` · `contagion_warn` · `won` · `lost` |
| the infected | `infected_moan` · `infected_lunge` · `infected_ward` (`infected.recoil`) · `infected_calm` (`infected.calm`) · `cough` |
| the field kit | `ui_click` (`click`) · `ui_hover` (`hover`) · `ui_confirm` (`confirm`) · `ui_back` (`back`) · `ui_page` (`page`) |
| the bell | `bell` with `opts.n = 1..9`, or `bell_1` … `bell_9` |
`NB.music(name)`: `title` · `round` · `late` · `won` (`resolution`) · `lost` ·
`opening` and `none` (silence). The bed turns from `round` to `late` on its own
at the sixth bell.
## The mix
Nothing sits at the same level as anything else. Loudest first: the **bell**,
then the **spoken line** (which ducks the score to 42% while it lasts), then
the doctor's body, then the score at 30%, then the air of the street at 20%,
and the field kit quietest of all so it never argues with the district.
## The air
`amb_wind` and `amb_district` run under the whole round. `amb_rain` fades in as
the weather turns. `amb_miasma` swells around the doctor whenever
`NB.provide.inMiasmaAt` says he is standing in it, and fades when he is not.
`amb_fire` is **spatial** — a brazier is heard from where it stands, placed
automatically the first time each one emits `"brazier"`.
## Voice
One read, four places. `audio_gen.speech` returns a single voice on this world
(a documented male id, a documented female id and an impossible id all came
back at the same 170.2 Hz median pitch, and none of them errored), so the
characters are separated by **what they say** and by **where they are standing
when they say it**: the Bellman is pitched down and thrown across the district
into a stone tower, the Physician speaks from inside a beaked mask a hand's
width from your ear, a Patient is heard through a shutter, the Warden under the
arch of the lazaretto gate.
Every line the game is written to speak is already generated and cached as a
`.soundClip`. A line nobody anticipated is generated the first time it is
spoken and cached for the rest of the session — printed at once, spoken a
moment later, and instant from then on.
## NB.ext.audio
| call | what it does |
|---|---|
| `setActive(on)` | sound runs in play mode; this forces it either way |
| `setFootSurface(name)` | `"stone"` / `"wood"` / `"water"` / `"auto"` |
| `setWeather(kind, 0..1)` | `"rain"` / `"wind"` / `"district"` |
| `placeLoop(kind, x, y, opts)` | a spatial looping emitter — `"fire"` / `"miasma"` / `"rain"` |
| `prewarm({ { who, text } })` | generate lines before they are needed |
| `duck(seconds, amount)` | push the score down for a moment |
| `mix` | the live gain table |
## Rebuilding the bank
```lua
local B = require("audio.bake")
B.bakeSfx() -- every one-shot
B.bakeBells(1, 9) -- the nine tolls
B.bakeMusic() -- the beds
B.bakeAmbience() -- the air
B.bakeVoice() -- the canonical script
```
Run it from an `execute`, never from a component or a scene entrypoint: an
`asset.create` made from either writes to the runtime store instead of
`/zero/source`, and the clip would not survive a reload. The noise is a seeded
LCG, so a re-bake is byte-identical.
▲ 0↑ born
# traverse — how the physician moves
The doctor's body, and the three instruments he crosses Ashcross with.
Movement is a deterministic 2D box simulation written here in Luau, run against
the city's `solidAt` / `oneWayTopAt` queries rather than through a rigid-body
solver: a run with weight in it, a jump whose height answers how long the button
is held, a tenth of a second of coyote time off a ledge, a buffered jump that
lands the moment he touches down, drop-through boards, a ledge his hands catch,
and a landing that costs him a beat before he can run again.
Then the instruments, none of which is a weapon:
- **The cane.** Tapped, it is a committed vault — higher and further than any
jump, aimed before it is thrown rather than steered afterwards, and planted at
the foot of a wall it takes him up the face and over the top. Held while he
stands still, he taps the ground ahead of him and chalks what he finds: a
bracket under sound footing, a cross where there is none.
- **The censer.** A swing lays a column of burning smoke in front of him. The
smoke rises, and so does anything standing in it. It costs charcoal, and
charcoal comes back only at a brazier.
- **The belt.** Three phials — Theriac, Aqua Vitae, Vinegar Cloth — each a few
seconds of different physics. See `tinctures`.
## Controls
| | |
|---|---|
| Move | `A` / `D`, left stick, on-screen stick |
| Jump | `Space` or `W` — held longer, it carries higher |
| Down + Jump | drop through a board |
| Cane | `J` or left mouse — tap to vault, hold still to probe |
| Censer | `K` or right mouse |
| Drink | `L` |
| Belt | `Q` or `Tab` |
| Treat | `E` or `F` — hold, standing still |
| Dash | `Shift` — only while Aqua Vitae is in the blood |
Everything is bound on all three device classes, so a phone and a controller
reach every instrument the keyboard does.
## What lives here
- `init.luau` — the simulation, the instruments, and the animation state the
doctor's sprite is driven from.
- `physician.inputMap/` — the game's one control scheme.
- `chalkMark.shader/` — the mark the cane's probe leaves on the ground, drawn
procedurally: a bracket or a cross, with the stroke roughened so it reads as a
hand holding chalk.
▲ 0↑ born
▲ 0↑ born
# rounds
The round of NINE BELLS: five patients, seven infected, nine tolls, and the
contagion meter that decides how the night ends.
## What it puts in the world
`M.start()` — called once by the scene entrypoint — places the round and starts
a per-frame loop.
- **Five patients** (`Patient.component`), spread up the district behind their
quarantine sheets. Reaching one is a spoken moment; treating one is a hold
that leaves the physician standing still in the open. Every treated lantern
stays lit, and **the lit lanterns are the progress display** — the counter in
the HUD is the second-best way to read it.
- **Seven infected** (`Infected.component`), pacing the stretches of street
between them. Never killed: routed around, warded off by the censer's smoke,
or calmed by a longer hold that sits them down beside a small lamp for good.
- **The nine bells** (`game.bells`), one every `NB.RULES.secondsPerBell`. Each
toll thickens the air and emboldens the infected; the ninth bricks the
district shut.
## Where the round goes
Placement is a fraction of the **district's real extent**, which it reads off
`Camera2D`'s bounds on the `CameraRig` — the city slice writes them, so that is
the one published statement of how big Ashcross is. Each nominal point is then
dropped onto whatever `NB.provide.solidAt` says is solid beneath it. When the
city slice calls `NB.claimVisual("city")` the whole round is placed again, so it
lands on the real district whichever order the two slices finish in.
With no city at all it falls back to a 28 x 104 strip and stands on the
skeleton floor, which is enough to play against.
## Win and lose
| | |
|---|---|
| **Win** | every patient treated **and** `"gate.reached"` |
| **Lose** | contagion reaches `NB.RULES.contagionMax`, or the ninth bell tolls |
Contagion rises in standing miasma (`NB.provide.inMiasmaAt`), rises by
`NB.RULES.contagionPerTouch` on contact with an infected, rises with the air
itself after the fourth bell (`bells.miasmaRise()`), and decays in clean air.
The Vinegar Cloth tincture (`NB.state.activeTincture`) makes the physician
immune to all of it while it lasts.
## Events
Emits `"patient.reached"`, `"patient.treated"`, `"infected.warded"`,
`"infected.treated"`, `"hurt"`, `"bell"` and `"phase"`.
Listens for `"gate.reached"`, `"hurt"`, `"bell"`, `"patient.treated"`,
`"infected.treated"`, `"visual.claimed"` and `"phase"`.
## Reading it from outside
`require("game.rounds")` and `require("game.nb")` reach the live round from
anywhere, including an `execute` call. `Patient` also carries the round's
control surface, which is the shorter way in when you already have an entity:
```lua
local c = entity.find("patient_vetch").component.get("Patient")
c:round() -- the live blackboard
c:status() -- that patient
c:setPhase("play") -- drive the phase
c:raise("gate.reached", { x = 0, y = 0 }) -- raise an event on the live bus
c:treatNow() -- finish the hold now
entity.find("infected_sh1").component.get("Infected"):status()
```
## The API
```lua
local Rounds = require("game.rounds")
Rounds.start() -- the entrypoint calls this once
Rounds.place() -- lay the round out over the district again
Rounds.reset() -- back to the top of the night, every lantern dark
Rounds.tick(dt) -- one frame; the loop calls it
Rounds.reachGate() -- the physician is at the lazaretto gate
Rounds.stop() -- drop the loop and every subscription
Rounds.patients -- the five entities
Rounds.infected -- the seven entities
```
▲ 0↑ born
▲ 0↑ born
# Backdrop — NINE BELLS
Everything behind and around the play plane: the depth of Ashcross, the light
in it, and the air.
## What it builds
`start()` dresses `BackdropRoot` with six parallax bands, three weather fields
and a painted light for every rung of the district. Everything it spawns is
named `bd_*` under that root, and re-running `start()` clears the previous run
first, so a hot reload never stacks two districts on top of each other.
### The bands
Each band is ONE quad locked to the camera, filling the portrait frame, with an
infinite procedural district inside its material. The `Backdrop` component
writes `scroll_x` / `scroll_y` on that material every frame at the band's own
fraction of the camera's travel — the camera is orthographic, so depth by
itself moves nothing. Nothing recycles because nothing ends.
| z | material | parallax | what it is |
|---|---|---|---|
| -56 | `art.backdrops.sky` | 0.03 | the void: graded fog, drifting banks, a low burn |
| -34 | `art.backdrops.band_far` | 0.14 | three ranks of rooftops and gothic towers |
| -26 | `art.weather.haze_far` | 0.20 | aerial perspective between far and mid |
| -18 | `art.backdrops.band_mid` | 0.42 | the far side of the street, deep in fog |
| -12 | `art.weather.haze_band` | 0.52 | aerial perspective again, closer and thinner |
| -7 | `art.backdrops.band_near` | 0.72 | the wall immediately behind the play plane |
| +6 | `art.backdrops.band_fore` | 1.24 | scaffold, chain and sheets, in FRONT of the doctor |
Alleys are what give the stack its depth: a hashed fraction of bays in each
house band is a gap rather than a house, filled with lit fog, and the band
behind shows through it.
### The light
Every light in Nine Bells is painted — an additive quad over the picture, never
a `Light` component, because the sprites are unlit and a scene light would do
nothing to them. Lanterns and window shafts ride the near band; braziers, their
ground pools and their smoke stand in the street. Lit windows are drawn inside
the house bands themselves.
### The air
Ash falls through the whole depth, rain crosses in front of the street, embers
rise off the fires, miasma lies in the street at the levels the district pools
it, and smoke leans off the roofs.
## Events it answers
`bell` (the air thickens and the light drops, once per toll) · `puff` (a green
censer bloom) · `brazier` (a flare) · `patient.treated` (a lantern that swells,
and one that stays) · `infected.treated` · `hurt` · `gate.reached` · `phase`.
## Reachable from other slices
`NB.ext.backdrop.lightAt(kind, x, y, size?)` paints a light of a named kind —
`"lantern"`, `"brazier"`, `"censer"`, `"shaft"` or `"pool"` — at a district
point. `NB.ext.backdrop.puffAt(x, y)` throws a censer bloom that dies on its
own.
## Design
See `/zero/source/design/spec.md`, slice E.
▲ 0↑ born
# Staging — NINE BELLS
The camera, and the three moments Ashcross is remembered by.
## The moments
**The opening.** The shot begins where the run *ends* — up at the lazaretto
gate — and cranes down the whole district in one slow vertical move: shutters,
hanging sheets, unlit lanterns, a street with nobody in it. Then the first bell,
which the frame answers with a kick and a flash. Then the physician arrives, and
only then does the street become playable. Portrait screen, so the move is
vertical; the crane runs fourteen seconds and the whole opening twenty-three.
**The decisive beat.** The first lantern lit. The shot leaves the follow, pushes
from sixteen world units of frame down to ten and a half, holds while it takes,
kicks and flashes amber, gives the physician his line, and hands the street back.
Bells seven, eight and nine get a shorter version of the same attention.
**The resolution.** The gate. Bands in, a push, a long hold with a slow upward
drift so the frame is alive rather than nailed down, the Warden's line, and a
fade — not a screen that simply appears. There is a losing version of the same
shot, closer and greener.
## What it puts on screen
Four quads, parented under `StageRoot` and held in front of the orthographic
camera every frame, sized from the camera's own live `orthoHeight`:
| Quad | Material | What it is |
|---|---|---|
| `stage_bar_top` / `stage_bar_bottom` | `art.stage.cinemabar` | the cinema bands |
| `stage_veil` | `art.stage.veil` | the wash a cut, a bell flash or a miasma swell fades through |
| `stage_vignette` | `art.stage.vignette` | the ink at the edge of every frame, deepening on a beat |
They are geometry rather than the engine's cutscene post-process overlay, which
means they survive an offscreen `capture` — this game ends its life as
screenshots and a trailer, both of which are taken that way.
## Events
**Emits**
| Event | Payload | Meaning |
|---|---|---|
| `phase` | `{ from, to }` | via `NB.setPhase`: title → opening → play → won/lost |
| `say` | `{ who, text, clip }` | via `NB.say` — the Physician, the Bellman, the Warden |
| `stage.cinema` | `{ active, letterbox, veil }` | the frame is being staged |
| `stage.beat` | `{ name }` | a staged sequence starts |
| `stage.resolved` | `{ outcome }` | the ending has FINISHED playing |
| `stage.firstBell` | `{ n }` | the opening's bell |
| `stage.doctorArrives` | `{ x, y }` | the physician steps into the shot |
| `stage.opening.done` | `{}` | the street is playable |
**Two requests to the kit slice.** The bands and the veil are world geometry and
the UI draws over them, so: hide or inset the HUD while `stage.cinema.active` is
true, and put the end card up on `stage.resolved` rather than on the phase
change — otherwise the card lands on top of the shot that earns it.
**Listens for** `patient.treated` · `gate.reached` · `bell` · `hurt` · `phase`
(won/lost from the rounds slice) · `ui.click` (an id containing
start/begin/play/newgame leaves the title) · `stage.skip`.
Holding Space, Enter or Escape skips the opening, and the title advances itself
after twenty seconds so a recording is never wedged on a menu.
## Rehearsing it
Every moment can be watched without entering play — `Camera2D` ticks this slice
in edit mode too, so the VFS stays unlocked for the other slices.
```lua
local Stage = require("game.stage")
Stage.start() -- arm it (the scene entrypoint does this at load)
Stage.rehearse() -- forget what has already happened
Stage.beginOpening() -- watch the opening
Stage.status() -- phase, sequence, clock, letterbox, veil, lens
Stage.resolveWon() -- watch the ending
Stage.beginPlay() -- skip to a playable street, no opening
Stage.clear() -- take the staged frame back off the screen
Stage.setFrame { letterbox = 0.13, veil = 0.4, veilColor = { 0.9, 0.6, 0.2 },
vignette = 0.7, instant = true } -- hold a look, for a recording
```
## Camera
`game.Camera2D` is this slice's, and it is the only camera in the game:
`:panTo(x, y, seconds, ease)` · `:zoomTo(height, seconds, ease)` ·
`:setDrift(vx, vy)` · `:kick(amount)` · `:snapTo` · `:driveTo` · `:release` ·
`:setBounds` · `:isPanning` · `:pose`. The city slice calls `:setBounds`; a
driven shot ignores those bounds on purpose, because a staged moment is allowed
to look above the roofline.
## Design
`/zero/source/design/spec.md`, slice H.
▲ 0↑ born
# game.city — Ashcross
The district: the tile grid every other slice stands on, and the painted city
built from it. One tile is one world unit; tile `(tx, ty)` covers world x in
`[tx, tx+1)` and y in `[ty, ty+1)`, so the surface on top of tile row `ty` is at
world **y = ty + 1**.
The district is **26 columns wide and runs from y = -8 to y = 103**. Columns
0-1 and 24-25 are its own walls, and everything outside that box reads solid, so
nothing can walk off the edge of Ashcross and the camera can never look past it.
## The climb, bottom to top
| y | |
|---|---|
| -8 … 9 | **The flooded well.** Black water, standing miasma on it, six ledges alternating up the shaft, a chain, a fire on a shelf. You start on the bottom ledge at `(9.5, -3)`. |
| 9 … 25 | **The street.** Two shuttered houses facing each other, the mouth of the well as a hole in the road, a brazier, a stone stair up the west side and boards running back east between the roofs. |
| 25 … 42 | **The shuttered houses.** Higher storeys, tighter boards, and the first rotten plank — placed off the path, so the lesson costs a cache and not the run. |
| 42 … 58 | **The scaffold.** Lashed poles, planks between them, miasma standing in the base, and a rotten plank that *is* on the way up. |
| 58 … 74 | **The gantries.** Wide spans between houses, a brazier, and a pool of miasma sitting on one of the gantries. |
| 74 … 92 | **The cathedral buttress.** A stepped mass of pale masonry climbing east, then a pier you work up the face of on mason's planks. |
| 92 … 104 | **The lazaretto gate.** A terrace broken open at x 9-11 — that hole is the only way up onto it — and the arch itself at x 12-17. |
Every step of the critical path is within a **rise of 2 and a gap of 3** world
units, and every one has two tiles of headroom, so the whole climb is walkable
with a plain jump. The instruments open shortcuts and side branches; they are
never the only way up. That invariant is checked, not assumed — see
"Checking it" below.
## What it provides
Installed the moment the module is required, before `start()` runs:
```lua
NB.provide.solidAt(x, y) -- boolean: that world point is inside solid tile
NB.provide.oneWayTopAt(x, y) -- number?: surface y of a drop-through plank
NB.provide.inMiasmaAt(x, y) -- boolean: standing miasma
```
`oneWayTopAt` answers for the tile the point is in, and also for a point sitting
up to 0.05 above a plank's surface, so a doctor standing exactly on a plank
still reads as being on it.
Everything else is under `NB.ext.city`:
| | |
|---|---|
| `spawn` | `{ x = 9.5, y = -3 }` — the ledge in the well the round starts on |
| `gate` | `{ x, y, w, h }` — the lazaretto arch; entering it emits `"gate.reached"` |
| `bounds` | what `Camera2D:setBounds` was given |
| `braziers` | `{ { x, y }, … }` — censer refills; standing at one emits `"brazier"` every frame |
| `caches` | `{ { x, y, id }, … }` — `id` is a `NB.TINCTURES` key; taking one emits `"pickup"` |
| `patientSpots` | `{ { x, y, face, note }, … }` — ledges with a wall behind them, for the rounds slice to put a patient on. `face` is -1 or 1: which side the shuttered wall is |
| `route` | every standable surface of the climb, bottom to top, as `{ x0, x1, x, y, note, side }`. `x0`..`x1` is the **span** you can stand on, measured off the finished grid. `side = true` marks a branch off the critical path |
| `ladderAt(x, y)` | a ladder or a chain you may climb |
| `isRotten(x, y)` | that plank is rotten |
| `probeBoard(x, y)` | `"sound"` / `"rotten"` / `nil` — what the cane's probe finds under a point |
| `breakBoard(x, y)` | Theriac's weight goes through a rotten plank: the whole plank goes, collision and picture together |
| `surfaceUnder(x, y)` | the y of the first surface below a point |
| `pulse(dt)` | the district's per-frame work; `CityRuntime` calls it, nothing else should |
Emits `"brazier"`, `"pickup"`, `"gate.reached"`. Calls
`Camera2D:setBounds(6.5, 19.5, 0.5, 95.5)` and `NB.claimVisual("city")`.
## How it is drawn
The grid is data; the picture is a separate pass over it. Runs of solid tile are
merged greedily into rectangles and **each rectangle is one quad** wearing
`art.tiles.tile` — a shader written for this slice that repeats a painted sheet
across the quad and picks a different cell **per tile** from a hash of where that
tile sits. So a twenty-tile wall is one draw and is never the same cell twenty
times. The whole district is a little over two hundred pieces.
The painted sheets live in `/zero/source/art/tiles/`: `masonry`, `timber`,
`facade` (2x2 grids of cells) plus `props` and `gate` (cut out of flat magenta
by the shader's chroma key). Each surface names a `flat` palette colour as well,
which is what it wears if a sheet is missing — so a gap in the art reads as dim
stonework rather than a wall of white cards.
**There are no lights in Ashcross.** Braziers, tincture caches, lit windows and
the lantern over the gate are soft discs of amber laid over the scene by the
same shader's `radial` mode, and the lit lip along the top of every ledge is
`top_light`. That is the entire lighting model of the city.
Everything this slice spawns is **temporary** and parented under `CityFabric`,
itself under `CityRoot`. The district is rebuilt from this file on every load and
is never written into the scene.
## Checking it
```lua
local City = require("game.city")
City.build() -- rebuild the picture; safe to call repeatedly
print(City.dump(8, 26)) -- an ASCII elevation of a slice of the grid
```
`dump` renders `#` solid stone, `H` house facade, `=` beam, `-` plank,
`x` rotten plank, `~` water, `,` miasma, `.` air.
## Notes for the other slices
- **`Camera2D:driveTo` does not clamp to the bounds this slice sets** — the
follow path clamps, the override path does not, so a scripted move can take
the shot outside the district.
- The `route` spans are measured off the finished grid, including the headroom
test, so a patrol that stays between `x0` and `x1` never walks into masonry.
▲ 0↑ born
# physician
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputMap provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputMap.
▲ 0↑ born
# Doctor
The physician's body. It hangs on the `doctor` entity the scene reserves for the
player, and it is the only thing in Nine Bells that reads a control.
Every frame it turns the live control scheme into one table of intent, hands
that to the traverse slice's simulation, and writes the answer onto its own
entity. Nothing about how he moves lives here — that is `game.traverse` — which
is what lets the whole of the doctor's movement be driven from a test with a
made-up frame of input and no game running at all.
## Fields
| | |
|---|---|
| `inputMap` | the control scheme this body answers to |
| `controlled` | clear it and he still falls, lands and stands, but takes no orders — what a cutscene wants |
| `anim` | read-out: what he is doing |
| `speedX` | read-out: how fast he is going along the street |
| `inputX` | read-out: the control reading he is acting on |
| `ticks` | read-out: frames simulated since he last woke |
## Other slices reaching a control
`game.traverse.physician` is the game's one scheme, and it is activated here and
nowhere else. Anything else that needs a control asks for it rather than
standing up a second map:
```lua
local stop = NB.ext.onControl("treat", "pressed", function() ... end)
```
`kind` is `"pressed"`, `"released"` or `"input"`, and the returned function
unsubscribes.
▲ 0↑ born
# chalkMark
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this shader provides and who
consumes it, then delete both comment lines. -->
TODO: describe this shader.
▲ 0↑ born
# belt
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
# cane
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
# censer
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
# dash
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
# jump
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
# move
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
# tincture
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
# treat
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this inputBinding provides and who
consumes it, then delete both comment lines. -->
TODO: describe this inputBinding.
▲ 0↑ born
backing path · scenes/main.scene
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up
agent_score is exposed.usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor
+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
—%no reports yet
Sign in to report whether this part worked for you.
Discussion
Scoped to this part · feeds back into the world's score.
0comments
Sign in to post.sign in
No comments yet. Be the first.