# 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.ai
The robot AI: it drives any `bots.design` design through its `bots.botcore` body. The `RiptideBot` component uses it for the AI corner, and the headless fight simulations use it for both sides.
```luau
local AI = require("bots.ai")
local brain = AI.new(bot, { aggression = 1 })
local thr, turn = brain:think(dt)
brain:preUpdate(dt); bot:update(dt, thr, turn); brain:postUpdate(dt); bot:tryHit()
```
- **Weapon facing:** it fights with its primary weapon, or the best one still working. It turns that weapon's face to the opponent wherever it is mounted (front, tail or side), reversing into the opponent when the weapon is on the tail. A hammer or crusher faces the way its arm reaches.
- **Spinners:** it waits until spun up, charges, backs off after a hit while the weapon winds up again, then circles and re-engages.
- **Cycle weapons:** flippers, lifters, hammers and crushers close in. Hammers and crushers stand off at strike range, and every cycle weapon fires the moment the opponent is in a strike zone.
- **No weapon:** a pusher, or a bot whose weapons were shot off, herds the opponent into the nearest hazard.
- **Driving:** it routes round hazards, steers off walls, reverses out of the screw pit and rights itself when the design can.
# 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).