# 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`.
# ArenaSound
All of BATTLEBOX's sound, on the scene's `Sound` entity. It only listens to `game.rules` (events via `Rules.on("*")`, plus `Rules.bot(name).rpm` and bot positions every frame) and builds its emitters at play only, as temporary entities, so edit mode stays quiet.
- **Crowd**: `crowd_bed` loops all match (Ambient); it swells after hits and hazards, `crowd_swell` plays on big hits and `crowd_roar` + `library.crowd_cheer` on KO / decision.
- **Music**: `fight_track` (broadcast hard rock, loops) in `fight` / `free`, ducked under the announcer and faded on KO; `title_sting` on `title`.
- **Weapons and drive**: `disc_whine` follows HAVOC and `bar_whoosh` follows RIPTIDE as spatial loops whose pitch and volume track `rpm / maxRpm`; `motor_hum` per bot tracks its ground speed.
- **Hits**: on `hit` a metal clang (`library.ss_impacts_metal_1..3`, `bcd_steel_clang`) + `hit_grind` (+ `hit_crunch` above ~35% damage), scaled by damage/14, at the event `point`.
- **Hazards**: `hazard` plays `saw_screech` (floorSaw), `killsaw_rasp` (killSaw), `screwpit_grind` (screwPit, rate-limited), `hit_crunch` (pulverizer hit); `pulverize` plays `pulverizer_slam` at the hammer.
- **Announcer**: `ann_3/2/1` on the countdown ticks, `ann_fight` on `fight`, `ann_knockout` then `ann_<bot>_wins` on `ko`, `ann_decision` then the winner on `decision`, `ann_welcome` on `title`. `ko_bell` marks the end of a fight; `ui_confirm` plays on leaving the title, a rematch and `reset`.
Clips live in `sound/clips/` (generated with audio_gen). Levels are fields (`musicLevel`, `crowdLevel`, `spinLevel`, …), with the game's values as defaults.
# BroadcastScreens
Every screen on the scene's `Broadcast` entity, built from `screens.art` and `screens.garageArt`:
- **Title** — the chrome-and-hazard-yellow BATTLEBOX logo and ROBOT COMBAT ARENA over the live faceoff shot, a name plate for each corner (`Rules.displayName(slot)` in its design's primary paint, `YOUR BOT · #nn` / `OPPONENT · #nn`), and two hazard-striped buttons: **BUILD YOUR BOT** (`bb_garage`, G / pad Y / tap) and **FIGHT** (`bb_confirm`, Enter / pad A / tap).
- **Garage** (`bb_garage`, phase `garage`) — the robot maker's panels, `screens.garageArt.build` of the view assembled from `screens.garage`; every tap/drag/typed id (`g:*`) goes to `Garage.act`. It rebuilds on every garage change (at most 10/s while a gizmo or scrub drag runs), reports the panel rects and screen origin to `screens.garage` (the 3D view's pointer blocker), publishes the free view centre as `Rules.state().shotFrame`, commits a field when it loses the keyboard, and keeps the keyboard/pad cursor's row scrolled into view.
- **Test drive** (`bb_test`) — TEST DRIVE · <name> banner with the controls and a **◀ GARAGE** button (`bb_testend`).
- **Fight HUD** — each corner's health bar with a damage trail, named by `Rules.displayName` and trimmed in its design's primary paint (`Art.slotColor`), the match clock (red under 0:10), the build's primary weapon (part label, % of max RPM, or CHARGE for cycle weapons), drive status, 3-2-1-FIGHT! and the 10-count.
- **KNOCKOUT! / JUDGES' DECISION** — `<NAME> WINS`, the reason, judges' scorecards in each build's colours, YOU WIN / YOU LOSE, **GARAGE** and **REMATCH**.
Layout scales with `ui.screenSize()`; on a handheld the HUD status panels move under the health bars, and the garage switches to its portrait layout on a tall screen. A screen is rebuilt only when what it shows changes.
# ArenaCam
The broadcast camera behaviour. It is `Camera.behavior` on the player prototype's `CameraRig` (which also carries the scene's `AudioListener`), and follows `Camera.follow`, the local player's HAVOC.
- **chase** (default): `distance` 6 m behind and `height` 4 m above HAVOC along its smoothed heading, aimed `lookAhead` in front, about 35 degrees down: the gameplay reference's framing. It is clamped `ARENA.cameraInset` inside the walls so the shot is never taken through the polycarbonate.
- **faceoff**: a low front shot of both bots (title screen).
- **orbit**: a slow orbit of the shot focus (KO / decision).
- **garage**: the showroom shot of the bot on the garage turntable (the shot focus), from the arena's south side `garageDistance` m away and `garageHeight` m up (`garageTall*` on a portrait screen). The screens say where the layout leaves room for the bot with `Rules.state().shotFrame = { x, y, tall }` (0..1 screen fractions) and the shot aims off the bot so it lands there.
`Rules.kickCamera(strength)` shakes it and pushes it in, dying away in about half a second. `Rules.setShot` picks the shot. Needs a `Camera` on the same entity.
# RiptideBot
The AI corner (slot `RIPTIDE`). It drives whatever design stands there with the `bots.ai` brain:
- turns its weapon's face to the player wherever the weapon is mounted;
- hits and backs off with spinners, and fires cycle weapons in their strike zone;
- herds the player into hazards when it has no weapon;
- routes round hazards and rights itself.
It rebuilds on `"design"` events for its slot and at `"reset"`. It reacts to `"hazard"` knock-ups and to `"destroyed"`. Body logic is in `bots.botcore`. The inspector fields tune aggression, backoff, re-engage spin and the opening hold.
# MatchDirector
The match flow on the scene's `Broadcast` entity. In play it takes the phase from `free` to `title` (faceoff shot) and ticks `screens.match` every frame: the garage (build stand or turntable), test drives, 3-2-1 countdown, the 3:00 clock (chase shot), KNOCKOUT when a bot is destroyed or immobile for `KO_COUNT_SECONDS`, the judges' decision (`Rules.decide`) at 0:00, the orbit shot round the winner, and a rematch (`Rules.reset`) on confirm.
Controls, each map live only while its screen is up:
- `screens.menu` (title, KO, decision): `confirm` = FIGHT / REMATCH (Enter, pad A/Start, a FIGHT touch button), `garage` = BUILD YOUR BOT / GARAGE (G, pad Y).
- `screens.garageNav` (garage, and test drives for Esc / B): arrows / D-pad (hold-repeat) and the left stick walk the current panel (left/right steps a numeric field), Tab / Shift+Tab / LB / RB switch panel, Enter / A presses, Esc / B backs out (field → menu → pad view → title; ends a test drive), Ctrl+S saves, Ctrl+Enter / F5 / Start fights, pad Y hands the D-pad and shoulders to the 3D build view and back. While a garage field (`gar-in-*`) has the keyboard, keys type instead of navigating.
Edit mode never runs it, so the phase stays `free` there.
# arena.battlebox
The BattleBox arena, after `design/references/arena_battlebox.png`: a 16 x 16 m gunmetal diamond-plate floor (one world-space `arena.arenaFloor` surface that paints the orange/blue start squares, hazard-stripe edging, plate seams, skid and scorch marks itself) tiled around real recesses for the screw pit, two kill-saw slots and four floor-saw slits; scratched polycarbonate walls (`arena.arenaGlass`) on black steel posts and rails over a hazard-striped kick rail, with BATTLEBOX boards; four corner hydraulic pulverizers; floor saws, kill-saw blades and twin augers built as procedural meshes; raked stands with a crowd behind the glass; an overhead truss of hard white floods, magenta/cyan rim lights, volumetric haze and dark height fog.
The main scene places it once at the origin through a `SceneModule` component; editing this module rebuilds that placement. Positions come from `game.rules`. It attaches `arena.HazardRunner` to the `BattleBox` root, which animates the hazards and applies their damage in play. Input: `lights` (bring the light rig and haze; default on). Owned by the arena slice.
# bots.havocModel
HAVOC's look: the orange bolted wedge, the vertical titanium disc (entity `Disc`) and four wheels (`Wheel_FL/FR/RL/RR`). Placed as the `Visual` child of the HAVOC body under the player prototype. Origin on the floor, nose toward -Z, footprint from `game.rules` `BOT_SPECS.HAVOC`. Owned by the bots slice; the skeleton version is a blockout.
# HavocBot
The player's robot on HAVOC's body root (the player prototype's body). It drives whatever design the player built (`Rules.design("HAVOC")`), with tank controls from the `bots.havocDrive` input map on keyboard (WASD/arrows, Space), gamepad (left stick, A) and touch (stick, FIRE, Self-Right). `move.y` is throttle toward the nose and `move.x` turns.
Spinners spin up by themselves and bite on contact. The weapon button fires every charged cycle weapon (flipper, lifter, hammer, crusher) at once. Holding Self-Right for 1 s while upside-down flips the bot back over, if it has a self-righter, a dome or a working flipper.
It reacts to `"hazard"` knock-ups, `"destroyed"` (smokes and flips) and `"reset"` (back to the start square with every part restored), and rebuilds on every `"design"` event for its slot. Body logic is in `bots.botcore`.
# bots.riptideModel
RIPTIDE's look: the squat cobalt-blue box chassis, the horizontal steel bar on its hub (entity `Bar`, spins about +Y), front forks and four wheels (`Wheel_FL/FR/RL/RR`). Placed as the `Visual` child of the RIPTIDE root. Origin on the floor, forks toward -Z, footprint from `game.rules` `BOT_SPECS.RIPTIDE`. Owned by the bots slice; the skeleton version is a blockout.
# arena.HazardRunner
Runs the BattleBox's hazards in play. The `arena.battlebox` scene module attaches it to the `BattleBox` root it builds; it finds each hazard's moving parts by name under `Hazards/<id>` and animates them on the hazard's own cycle from `game.rules` (`Rules.HAZARDS`): floor-saw blades spin, kill-saw blades rise and sink on their 2 s cycle, the screw-pit augers counter-rotate, and the four corner pulverizers slam on a staggered 4 s cycle.
Damage follows the spec's Interfaces: each registered bot's position is tested with `Rules.hazardAt`; a hit calls `Rules.applyDamage(victim, damage, kind)` (credited to the opponent) at most once per hazard `cooldown` and fires `"hazard" { hazard, kind, victim, damage, point, knockUp }`. Every slam fires `"pulverize" { hazard }`. A bot over the screw pit gets `Rules.bot(name).stuck = true` and 3 damage per second; the runner clears the flag it set when the bot leaves. Fields: `sawRevsPerSecond`, `augerRevsPerSecond`, `pulverizerStagger` (defaults are the game's values).