# screens.art
BATTLEBOX's broadcast graphics package, used by `screens.BroadcastScreens` and `screens.garageArt`: the palette (from `game.rules` COLORS), chrome-and-hazard-yellow SVG display lettering (BATTLEBOX logo, KNOCKOUT!, FIGHT!, JUDGES' DECISION, the `<NAME> WINS` banner), black hazard-trimmed panels (`trimmed`), health bars with a damage trail, the hex match clock, the weapon and drive status panels, the 3-2-1 / KO-count slam numbers, judges' scorecards, the title name plates, the YOU WIN / YOU LOSE chip and the hazard-striped confirm button (any callback, optional width and key hint).
Bot colours come from the designs: `slotColor(slot)` is the corner design's primary paint as a HUD colour (`teamColor` lifts a colour too dark to read on black); `rgbOf` turns it into glow rgba. Health panels and scorecards take the corner key for their ids and the display name and colour to show. Every builder takes the screen metrics (`w`, `h`, scale `k`) so the screens read on a phone.
# screens.match
BATTLEBOX's match flow as a module: `toTitle`, `toGarage(keep)` / `garage` (BUILD YOUR BOT from the title, GARAGE after a result), `testDrive` / `endTest` / `testing`, `startMatch`, `confirm` (FIGHT from the title, REMATCH from a result screen), `tick(dt)` and `countingBot` for the HUD's 10-count.
- **title** restores the last-used build once per session (`screens.garage.restore`) and poses both corners for the faceoff.
- **garage** opens `editor.session` on the player's build (`screens.garage.open`). With the 3D build view (`editor.view`) both corner bots are parked out of shot and the camera holds the `build` shot on the view's stand; without it a temporary turntable (`GarageTurntable`, materials `screens.turntable` / `screens.turntableRim`) stands the player's corner bot slowly turning under the `garage` shot. FIGHT closes the garage (the build goes to `Rules.setDesign("HAVOC")` and `last.json`) and starts the countdown; BACK returns to the title.
- **test drive** puts the build in the player's corner and runs phase `free` (bots drive, no clock) with the chase shot and the rival parked out of the way; `endTest` (Esc / pad B / ◀ GARAGE) returns to the garage with the session and its undo history intact.
- **countdown / fight / ko / decision**: 3-2-1, the 3:00 clock, KNOCKOUT on destroyed or a 10 s immobile count, the judges' decision at 0:00.
It sequences `game.rules` phases, `reset`, `decide` and camera shots and duplicates none of its numbers. A bot that cannot be posed in a frame (mid-rebuild) is logged once and does not stop the flow.
# game.rules
BATTLEBOX's constants, rules and live match state, shared by every part of the game. `require("game.rules")`.
- **Constants**: `TITLE`, `PLAYER` ("HAVOC"), `RIVAL` ("RIPTIDE"), `COLORS` palette, `MATCH_SECONDS` (180), `COUNTDOWN_SECONDS`, `KO_COUNT_SECONDS` (10), `IMMOBILE_SPEED`, `MAX_HEALTH` (100), `ARENA` (16 x 16 m box, wall height, camera inset), `STARTS` (start squares, yaw), `HAZARDS` (every floor saw, kill-saw slot, the screw pit and the four pulverizers, with damage footprints), `BOT_SPECS` (size, mass, drive, weapon RPM and damage).
- **Rules**: `weaponDamage(attacker, rpm)` = maxHitDamage x (rpm/maxRpm)^2, zero below 20% spin; `weaponKnockback`; `hazardAt(x, z)`; `decide()` for the judges (more damage dealt wins, then more health, then RIPTIDE).
- **State** (per peer, single-player vs the AI): `state()`, `bot(name)`, `opponent(name)`, `isLive()`; phases `free` / `title` / `countdown` / `fight` / `ko` / `decision`.
- **Mutations**: `registerBot`, `setPhase`, `applyDamage(victim, amount, cause, attacker?)`, `reset()`.
- **Events**: `on(event, fn)` returns an unsubscribe; `emit(event, payload)`. Events: phase, hit, hazard, damage, destroyed, ko, decision, reset, weapon, pulverize.
- **Camera**: `kickCamera(0..1)`, `setShot("chase" | "faceoff" | "orbit", focus?)`, read by `game.ArenaCam`.
- `formatClock(seconds)` -> "2:14".
State lives in `modules.state()`, so it survives hot reloads. Owned by the plan step; slices read it and may ask for additions in `design/spec.md`.
# screens.garage
The ROBOT MAKER's panel state and every action it takes (BUILD YOUR BOT), independent of drawing.
- **The bot being built lives in `editor.session`.** Every panel edit goes through the session (undo/redo, mirror twins, snapping, normalizing), and the module listens with `Session.on` to redraw. Multi-part edits are wrapped in `beginDrag`/`endDrag` so they are one undo step.
- **The 3D build view** (`editor.view`) is driven from here: palette cards call `View.beginPlace(type)`, the toolbar `setTool` / `setView` / `focus`, issue clicks `Session.select` + `View.focus`. `View()` hands the view `pointerBlocked(x, y)` (the panel rects the art reports, in window points) and the pad focus (`setPadEnabled`, pad Y). While the view is not up, the palette adds parts at a default spot and edits are pushed to the player's corner (~4/s) so the turntable bot shows them.
- **Zones and rows.** `rows(zone)` describes the toolbar, palette, right panel (PART inspector / BOT / OPPONENT), stats issues and the BUILDS menu as rows of items with action ids; `act(id, value)` runs them (taps, keys and pad all resolve to the same ids). The cursor (`move`, `select`, `cycleZone`, `setZone`, `togglePadView`, `back`) walks the same rows.
- **Inspector**: typed numeric fields for position (cm), rotation (°), size (by the type's `sizeRule`: diameter for round parts), every `params` entry (number / enum / bool / text), material picker with blurbs, paint override (role, custom colour, finish), mirror link (MIRROR / UNLINK), DUPLICATE / DELETE. Several parts selected: MOVE BY, and the size, material, params and paint they share. Fields take a typed value (Enter or leaving the field commits), ± steps (the snap step) and drag-scrub on the label.
- **Saves** (this machine only, written straight through at play): `/source/local/garage/builds/<slot>.json` as v2 `Design.encode` JSON, `last.json` (build, slot, opponent) restored once per session by `restore()`. A v1 save in `builds/` converts to v2 in place when first listed (original kept in `/source/local/garage/v1-backup/`); a v1 `last.json` converts on restore.
- `open(keep)` / `close()` / `flush()` / `tick(dt)` are called by `screens.match`; `setHooks{ fight, back, testDrive }` wires the flow. FIGHT is refused (with the first problem) unless `stats.legal`.
Drawn by `screens.garageArt`, routed by `screens.BroadcastScreens` (taps) and `screens.MatchDirector` (keys/pad via `screens.garageNav`).
# bots.parts
The catalogue of every part a combat robot can be built from, and the maths every system shares to place them.
- **Catalogue:** 26 part types in 7 categories:
- Structure: base plate, frame rail, block, ballast.
- Armour: plate, wedge, box, dome and cylinder shells, forks.
- Drive: wheel, tank tread, caster.
- Weapons: vertical and horizontal spinners, drum, flipper, hammer/axe, lifter, crusher, ram spike.
- Power and control: battery, receiver/ESC.
- Utility: self-righter.
- Decor: name plate, status light.
- **What each type defines:** its shape, size limits, a sizing rule, default material and settings, and paint role. Materials (aluminium, steel, titanium, AR500, Hardox, UHMW, polycarbonate) use real densities and damage behaviour; LiPo and LiFePO4 battery chemistries are included.
- **Shared maths:** bot space, part transforms (yaw, pitch, roll), corners, bounds, distance to a part, and mirroring across the centre line.
- **Per-part physics:** mass, hit points and armour from a part's size, material and settings, plus SoftBody dent parameters for armour.
Used by `bots.design` (whole-bot physics), `editor.session`, the assembler, the builder screens and the damage system.
# editor.session
The bot being built in the garage, and every edit to it. It holds one live v2 design per peer and provides:
- part operations: add, remove, set a field, translate, duplicate, mirror a part, unlink a twin, replace the whole design, and set the name, number or paint;
- mirror symmetry with linked twins across the centre line;
- snapping;
- continuous drags recorded as a single undo step;
- undo and redo (up to 100 steps);
- selection;
- change listeners;
- a cached `bots.design` derive of the live design.
Both the 3D build view (`editor/`) and the garage panels (`screens/`) edit the design only through this module, so every surface shares one history and one selection.
# screens.garageArt
Draws the ROBOT MAKER as one widget tree in the broadcast look of `screens.art` — Anton type, black trimmed panels, hazard-yellow selection, a white ring for the keyboard/pad cursor.
- `build(m, view)` → `(tree, layout)`. The view comes from `screens.BroadcastScreens` (design, stats, every zone's rows from `screens.garage`, cursor, toast, menu/sheet state). Every chip, card, swatch, colour picker and numeric field carries the `screens.garage` action id it runs; ids follow `gar-<zone>-<rowKey>[-i<col>]`, inputs `gar-in-*`.
- **Landscape**: toolbar across the top (◀ TITLE, UNDO/REDO with counts, SELECT/MOVE/ROTATE/SCALE, MIRROR, SNAP and its steps, TEST DRIVE, BUILDS ▾, FIGHT! which shows the first problem while illegal), parts palette on the left (category chips, part cards with shape pictogram, name, blurb, default weight, count on the bot), PART / BOT / OPPONENT panel on the right, the stats strip along the bottom (weight bar against 250 lb stacked by category with legend, speed/accel/turn, CoM, battery vs need and run factor, each weapon, rating bars, the issues list), the bot's name and the view presets over the build view, and the BUILDS menu as a drop-down panel.
- **Portrait** (phone): two-row toolbar, a compact stats strip (tap for the full numbers and issues), the build view, and a bottom sheet with PARTS / INSPECT / BOT / RIVAL tabs that collapses to its tab bar.
- `layout(m, g)` gives every box, `rects` (what the 3D view must not take the pointer in) and `frame` (the centre of the free view, for the camera's build shot via `Rules.state().shotFrame`).