# 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`.
# editor.view
BATTLEBOX's 3D build view, the garage's robot maker. It shows the open `editor.session` design on a build stand in front of the screw pit. It edits that design only through the session. It uses `bots.assembler` (`build`, then `updatePart` / `addPart` / `removePart` per change) when available, and simple primitive stand-ins otherwise.
What it draws and does:
- **Stand:** a floor grid at 1, 5 or 10 cm by the move snap, the centre line and mirror plane, X/Y/Z axes and the size-limit box (`Parts.BOUNDS`).
- **Camera:** an orbit/pan/zoom camera, read by `game.ArenaCam`'s `build` shot. Presets are front, side, top, iso and back; `F` focuses the selection.
- **Placement:** `beginPlace(type)` shows a ghost of the new part that snaps flush onto the face under the pointer (ray against the parts' oriented boxes). Wheels go axle-out, plates lie flat and weapons face outward. With mirror mode on, the ghost's mirror twin shows too.
- **Selection:** click selects, Shift adds, and clicking empty space clears. Hover and selection get outlines.
- **Gizmos:** move (axis arrows and plane handles), rotate (yaw, pitch and roll rings, snapped by the session) and scale (local axis handles honouring `sizeRule`). Each drag is one session drag, so it is one undo step.
- **Overlays:** centre of mass, wheel ground contact, weapon strike zones and sweep circles, and problem (red) or warning (amber) parts from `stats.issues`.
- **Input:** mouse, touch (tap, one-finger orbit, two-finger pinch and pan) and gamepad (stick orbit, trigger zoom, D-pad nudge, shoulder rotate). Shortcuts come from `editor.buildView`.
The module header documents the whole API: `active`, `beginPlace`, `cancelPlace`, `placing`, `setTool`, `tool`, `setView`, `focus`, `hovered`, `hoveredHandle`, `dragging`, `setPointerBlocker`, `setPadEnabled`, `setOverlays`, `on`, `cameraPose`, `stats` and `toScreen`.
Hosted by the `editor.BuildView` component, which `game.ArenaCam` spawns while phase is `garage`. The garage panels (`screens/`) call the API.
# editor.BuildView
The host of the garage's 3D build view. While it lives it does three things: it attaches `editor.view` under its entity (stand, bot, gizmos and overlays become its children), activates the `editor.buildView` controls, and calls `View.tick(dt)` every frame. When it is destroyed it detaches the view and releases the controls.
`game.ArenaCam` spawns a temporary `BuildView` entity carrying it while the match phase is `garage`, and removes it when the garage closes, so nothing has to be placed in the scene.