# 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`).
# screens.turntable
The garage turntable's plate: dark brushed gunmetal steel, a little glossy so the showroom light runs across it. Used by `screens.match` on the temporary `GarageTurntable` entity it spawns in the garage.
# bots.botcore
The body of a corner robot, for any design built from parts. Every number comes from `Rules.stats(slot)`, and the look is built by `bots.assembler`.
- **Drive:** tank drive from the parts' derived speed, acceleration and turn. A side that lost wheels drives weaker and makes the bot pull. Lost batteries cut the power, and with none left nothing drives or spins.
- **Contact:** arena walls and bot-on-bot shoving use each bot's oriented footprint (its parts' bounds), not a circle.
- **Weapons:** every weapon part works on its own.
- Spinners spin up and down from where they are mounted. Vertical discs and drums bite with the front arc; horizontal spinners hit all round within their sweep at hub height.
- `bot:fire()` fires every charged cycle weapon at once (flipper, lifter, hammer, crusher). Hammers and crushers come down from above onto the top part under their tip.
- Spikes hit for `ramDamage` × closing speed × mass / 100 kg.
- **Hits:** each hit lands on the first surviving victim part the weapon meets, so armour in front of internals takes it. Damage is the weapon's damage × that part's `armorScale`, ×1.6 on batteries and receivers. It comes off the bot's health and the part's own hp (armour and structure parts absorb 30% into their hp).
- **Events:** `"hit"` carries `part`, `partType` and `weaponId`. `"partDamaged"` and `"partLost"` fire on part damage and loss. A lost receiver destroys the bot, and lost batteries lead to an immobile KO. A lost wheel weakens its side, a lost weapon stops, and a lost self-righter can't right the bot any more. `"reset"` restores every part.
- **Rules record:** writes `rpm` (the primary weapon), `weaponFraction`, `weapons[id] = { rpm, charge, lost }`, `partHp`, `immobileSeconds` and `flipped` to `Rules.bot(slot)` every frame.
- **Sim bodies:** `Core.newSim` makes a headless body that never touches the live match, used by `bots.fightsim`.
Used by `bots.HavocBot`, `bots.RiptideBot` and `bots.fightsim`. `Core.get(slot)` returns the live bot.
# screens.turntableRim
The garage turntable's glowing hazard-yellow rim (emissive), so the build reads as standing on a showroom stage. Used by `screens.match` on the temporary `GarageTurntable` entity.