Escapement
README.md
Command
Everything between the player and the referee. One of these is attached to the
scene's Command entity by scenes/main.scene/build.luau, and it is the only
thing in the game that reads the mouse.
What it does
- Picks a tooth from a pixel. The cursor's ray is built from the live camera's own pose and lens, then crossed with each gear ring's plane and measured in that plane. Picking therefore needs no collider on anybody else's geometry, and a platform hidden behind a nearer one is correctly unclickable.
- Draws the board's overlay. Green rings mark the cells the selected automaton can step to this tooth; a violet ring beside each one marks where that same cell will have travelled once the machine turns, with a rod drawn along the carry. Red rings mark the blight this automaton could strike now, and where every blight will be a tooth from now.
- Runs the HUD. Winding per automaton, the tooth count, the phase, and the
cost of the action under the cursor before it is spent — all of it built by
game.ui, which this component feeds a plainviewtable. - Frames the board. The scene's PlayerPrototype CameraRig is retuned at runtime: distance, zoom range, field of view, and an orbit focus lifted above the rings so the board reads from above rather than edge-on.
It asks the referee, it does not rule
Every action is put to Director by name, and the verdict it answers with —
{ ok, reason } — is what the HUD prints. canMove / canStrike / canWind
decide whether a click is offered; move / strike / windAlly / hold
perform it; reachable / strikeTargets / windTargets decide what the
overlay draws. When the referee exposes no verb for something, this component
falls back to spend / restore and Core.neighbours, so the interface stays
playable against a partial referee.
What the player does
| Input | Effect |
|---|---|
| Left-click an automaton | take command of it |
| Left-click a green cell | move there — 1 winding |
| Left-click a blight in reach | strike it — 2 winding |
| Left-click the automaton you already command | hold; it winds back up when the turn ends |
| The wind an ally buttons in the bar | spend 2 to give an adjacent ally 3 |
| Advance the machine button, or Space | end the turn |
| Tab | next automaton |
| H | how to play |
| Escape | clear the selection |
| Right-drag / scroll | orbit and zoom |
Called from elsewhere
local c = entity.find("Command").component.get("Command")
c:select(unitId) -- take command
c:hovered() -- { ring, sector } under the cursor
c:pickAt(px, py) -- the same pick at an exact viewport pixel
c:previewAt(ring, sector) -- what a click there would do, and cost
c:clickCell(ring, sector) -- resolve, judge and spend, in one call
c:reachableNow() / c:strikeTargetsNow() / c:windTargets()
c:windTarget(unitId) -- spend 2, give 3
c:endTurn()
clickCell and pickAt exist so the whole command chain can be exercised
without a mouse in the loop.