# 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`.
# 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.
# bots.fx
The bots' hit effects. `Fx.new()` gives each bot component its own pooled emitter: `fx:sparks(point, dirX, dirZ, strength)` throws a shower of hot orange-white spark-streak sprite cards (bots.textures.sparkStreak on the additive spark/sparkWhite materials, laid along their flight and turned to the camera) with a flash of point light at a weapon or hazard contact, `fx:smoke(on, anchor)` pours camera-facing black smoke-puff sprites (bots.textures.smokePuff on the multiply-blended smoke material, fading out by tint) off a destroyed bot, `fx:tick(dt)` advances them every frame. Pool entities are temporary and created on first use. Used by `bots.botcore` (weapon hits) and the HavocBot / RiptideBot components (hazard hits, destruction).