# core <!-- 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.

# units The pieces on the board: what the five automata are built out of, how a wound spring is drawn on one, what a seized automaton looks like, what the rust-blight is made of, and the whole of the blight's turn. ```lua local Units = require("game.units") ``` ## The five, and how to tell them apart Every automaton is assembled from hard-surface parts in three surfaces — polished brass for what is alive and working, blackened iron for structure, and hot spring-gold for stored winding — and each is given one feature no other piece has, so the board is readable at a glance from the commander's camera. | Automaton | Read it by | |---|---| | **Governor** | The tallest. Twin flyballs swinging off its crown, and a spire on top. | | **Lance** | The long spar out front, with a bright tip and an iron vamplate. | | **Anvil** | The widest, lowest and darkest — an iron block under a brass plate. | | **Sparrow** | The smallest, and the only one with wings. | | **Winder** | The glowing key ring standing above its shoulders. | ## The winding gauge Six coil rings climb the back of every automaton. The lit rings are the winding it still holds, out of `Core.WINDING_MAX`; spent coils go dark and shrink. It is deliberately the brightest thing on the model, because winding is the only resource in the game. ## Seized An automaton at zero winding is not wounded, it is stopped. Its whole body turns dead oxide, it slumps off true and sinks onto its base, and every coil goes out. It stops reading as a piece and starts reading as something in the way — which is exactly what it now is until an ally spends 2 to wind it back up. ## The blight Rust does not stand on the metal, it grows across it: a low crust of pitted lobes, spines leaning off the edges, a live bloom breathing at the heart, and brass slivers of the machine half-eaten and still poking out of the crust. A `spore` is a small patch, a `creep` spreads wide and low, a `canker` is taller and spikier. Struck blight shrinks as its crust comes off. ## The blight's turn ```lua Units.blightTurn(director) -- the rust's entire turn; idempotent per tick ``` The rust wants the escapement. - **It drains before it climbs.** Anything an automaton-width away is bitten instead of walked past, and it bites to finish: the automaton this drain would seize outright, otherwise the one with the least winding left. A seized automaton is left alone — it is already terrain. - **It climbs whenever the machine has opened a way inward.** A cell is scored by its ring first and by its angle to the escapement gate second, so when no crossing is open the rust walks the ring toward where the gate will be, and takes the bridge the moment one lines up. - **It never backs off.** Only a strictly better cell is worth a move, so the rust never paces on the spot. - **Reinforcements crawl in** through a free vent on the outer ring every `Units.BLIGHT_SPAWN_EVERY` ticks, up to `Units.BLIGHT_CAP` on the board at once, and the waves get tougher the longer the hour runs. The `director` argument only has to answer `:spend(unitId, amount)` and `:finish(outcome, reason)` — the referee's own calls — so the blight never writes game state behind the referee's back. ## The rest of the surface ```lua Units.muster(side, kind, ring, sector, root) -- record in Core.state() + body in the world Units.buildBody(unit, root) -- (re)build one body Units.refreshWinding(unit) -- redraw the coil gauge Units.refreshRust(unit) -- redraw a blight's crust Units.applyFrozen(unit, frozen) -- the seized look, on and off Units.heading(unit) -- automata face outward, blight faces in Units.describe(unit) -- one line naming a piece ```

# Director The referee. One of these sits on the scene's `Director` entity and owns `Core.state()` — it is the only thing that writes the tick, the phase, the outcome, and every unit's ring, sector, winding and rust. Everything else in Escapement reads that state and reacts to the signals fired here. The law it applies lives next door in `game.rules`, which answers every legality question purely off the shared state. This component is the half that is allowed to write: it asks the law, applies the answer, and fires the signal. ## Getting hold of it ```lua local d = entity.find("Director").component.get("Director") ``` ## Commanding an automaton One action each per turn. Winding is the resource that carries *across* turns, so the question is never "what can I afford this turn" but "how long can this automaton keep going". | Call | Costs | Does | |---|---|---| | `d:move(unitId, ring, sector)` | 1 | steps one open link | | `d:strike(unitId, targetId)` | 2 | bites `power` off a blight's rust | | `d:windAlly(unitId, targetId)` | 2 | gives an adjacent automaton 3, thawing it | | `d:hold(unitId)` | — | stands still, and books the end-of-turn winding | | `d:endTurn()` | — | the blight's turn, the winding, then the machine turns | Every one of them answers `{ ok = boolean, reason = string }`. A refusal carries the reason in plain words — *"the machine offers no crossing there this tick"*, *"frozen — an adjacent automaton must wind it back up"* — so an interface can tell the player why rather than doing nothing. Ask before you spend with `d:canMove(unitId, ring, sector)`, `d:canStrike(unitId, targetId)` and `d:canWind(unitId, targetId)`, which answer the same shape without touching anything. ## Reading the board | Call | Answers | |---|---| | `d:snapshot()` | tick, phase, outcome, selection, every unit, the planks down | | `d:reachable(unitId)` | the cells this automaton may step onto, this tick | | `d:strikeTargets(unitId)` | the blight ids it may bite, this tick | | `d:windTargets(unitId)` | the ally ids it may wind, this tick | | `d:preview(unitId)` | the world point its cell will be at once the machine turns | | `d:planks()` | the counterweight ground currently lying on the board | | `d:cost(kind)` | what `"move"`, `"strike"` or `"windAlly"` costs | | `d:unit(unitId)` | the live unit record | `d:snapshot()` is the one to use from a script, a tool or a test. Components and modules share one require registry and can read `Core.state()` directly; an `execute` call gets its own registry and therefore its own, empty `Core`. ## The turn, in order `d:endTurn()` runs the rest of the turn in one call: 1. **blight** — the rust takes its turn. If the unit host offers a `runBlight`, that is the blight's turn and the referee only supplies the economy calls it makes. Otherwise the referee runs its own climb, and sends its own reinforcements in through the vents. 2. **the winding** — every automaton that stood still all turn is wound: three on a mainspring node, one anywhere else. Standing still means it was not commanded *and* its winding is no lower than when the turn began, so rust in the gears is the one thing a spring cannot be wound through. 3. **advance** — the tick lands. Every address stays where it is and every cell moves, so every unit is carried wherever the metal takes it. The match ends the moment any of these is true, checked after every phase: the rust stands on the escapement (**lost**), every automaton has run down (**lost**), or the tick reaches `Core.TICKS_TO_HOUR` (**won**). `Core.SIGNAL.matchEnded` carries `{ outcome, reason }`. `d:newMatch()` clears the board and musters the roster again — what an end-of-match screen calls to play once more. ## Fields | Field | Default | Meaning | |---|---|---| | `autoPlay` | `false` | end the turn on a timer, with nobody commanding | | `secondsPerAutoTurn` | `2.5` | how long each of those turns lasts | | `blightWaves` | `true` | send reinforcements when the referee is running the blight itself |