# rules <!-- zero:scaffolded-readme --> <!-- Replace the line below with what this module provides and who consumes it, then delete both comment lines. --> TODO: describe this module.

# CombatCamera The fight camera, for a 1080x1440 portrait frame. A landscape follow rig puts a 15.5 m boss half off the top of a 3:4 screen, so this one does not pick a distance and hope. Every frame it takes the two extremes the shot must contain — the Emberward's feet and the crown of the saint's bell — aims at the ANGULAR midpoint between them, and grows the stand-off until that half-angle fits inside the frame on both axes. The eye rises as the shot pulls back, so a wide stand-off looks down at the basin and up at the saint rather than crawling along the floor. The portrait shape then carries the composition: the player low, the saint towering up the tall axis. Measured live at 15.5 m: a stand-off of 8.9 m puts the Emberward's feet at -0.89 of the half-frame and the crown of the bell at +0.68, with the horizontal spread well inside — both bodies held, neither on the border. ## Modes - **Locked on** — stands on the line behind the player away from the saint and holds both bodies. Look input swings it off that line by at most `orbitLimit` and eases back. - **Free** — an ordinary orbit around the player. - **Yielding** — while `Rules.state.mode` is `title`, `intro`, `victory` or `defeat` it writes no pose at all: the staging slice drives the camera there. ## Screen shake It is the consumer of the `shake` event: `Rules.shake(amplitude, duration)` from anywhere adds trauma, trauma decays, and the offset is trauma squared, so a light hit is a nudge and the Quench is felt. Sampled from layered sines so it is smooth at any frame rate. ## Reading it back `:framing()` reports mode, the solved distance, the camera and aim points, the orbit offset, live trauma and the shake displacement the last pose actually carried — the numbers behind the shot, without a screenshot. `:kick(amplitude, duration)` shakes it directly and `:calm()` drops everything still ringing, which is what a cut to a new shot wants. Attached by `Emberward`, which sets `Camera.behavior`. The follow target comes from the standard `Camera.follow` slot.

# game/combat/fight Stateless helpers shared by `Emberward.component` and `CombatCamera.component`. - `Fight.damp(current, goal, tau, dt)` — frame-rate independent approach. - `Fight.xyz(p)` — read any position-ish value as three numbers. - `Fight.horizDist(a, b)` / `Fight.yawTo(a, b)` / `Fight.angleDelta(from, to)`. - `Fight.yawQuat(yaw)` — a rotation about +Y as the array a transform takes. - `Fight.inArc(origin, yaw, target, arcDegrees, range)` — cone + range test. - `Fight.newShake()` / `Fight.addShake(s, amp, dur)` / `Fight.sampleShake(s, dt, scale)` — trauma-based screen shake, sampled from layered sines so it stays smooth. Yaw is measured about +Y from world +Z: forward is `(sin yaw, 0, cos yaw)`, so a yaw of `0` faces the saint down the arena's +Z axis.

# SlagSaint The mind of the thing in the basin. Attach it to `boss_root`; the scene's `BattleBoot` does that automatically the moment this component exists. The saint takes its turn. It announces every blow at least eight tenths of a second before it throws it, it tracks the Emberward, its poise breaks when it is punished hard enough, and it thanks her when it dies. ## The cycle ``` idle ──▶ tell ──▶ strike ──▶ recover ──▶ idle ▲ │ └──────── stagger ◀── poise 0 ───────────┘ │ shift ◀── health crosses 62% / 24% │ dead ◀── health 0 ``` * **idle** — waits out this phase's `attackInterval`, turns toward the player, and from phase 2 walks in when she is further away than 7.5 metres. It does not walk in phase 1: it is still bolted to the basin. * **tell** — the wind-up. Never shorter than 0.8s, whatever the phase. The threatened area is drawn on the floor (see `boss/telegraph`), the saint coils back and leans away, and the core in its chest swells. * **strike** — the release. Raises `boss:strike`, lunges, flashes the tell. `double_stomp` lands twice. * **recover** — the punish window, 0.7 to 1.45 seconds depending on how big the blow was. * **stagger** — 5.5 seconds with the core exposed. The Quench lands here. * **shift** — 2.5 seconds of phase transition; interrupts anything. Interrupts run in priority order: death beats a phase change beats a stagger. A parry interrupts a wind-up outright. ## What it raises `boss:telegraph` `boss:strike` `boss:poise` `boss:stagger:begin` `boss:stagger:end` `boss:defeated` `battle:victory` `battle:defeat` `camera:beat` `hit` `shake` `hitstop` `ui:prompt` `vo` `sfx`, and `phase:changed` through `Rules.setPhase`. `boss:strike` carries more than the contract's `{ move, origin }` — it also carries `damage`, `range`, `arc`, `phase` and `inside` (whether the player was in the threatened area on the frame it landed), so the combat slice can resolve the hit without re-deriving the geometry. ## What it consumes `boss:damaged` is the damage channel. If the payload carries `health`, that number is adopted; otherwise `amount` is subtracted. Either way the hit wears down `Rules.state.boss.damage` — the named `part` takes the brunt and every part takes a little, so by the end the saint is visibly a wreck. Send `poise` explicitly to control the meter; without it the poise cost is inferred from how big the hit was. `player:parry` rings the bell: 30 poise, damage on `headBell`, and it interrupts whatever the saint was winding up. `player:died` and `mode:changed` do the obvious things. Returning the mode to `title` or `intro` resets the fight to full health in phase 1, which is what a retry needs. ## State it writes `Rules.state.boss.health` `.poise` `.staggered` `.coreExposed` `.telegraphing` `.move` `.damage`, plus one key this slice adds: * **`Rules.state.boss.stance`** — `"kneeling"`, `"standing"`, `"unshuttered"` or `"dead"`. The art slice can read it instead of deriving the pose from the phase index. ## Fields | field | default | what it does | |---|---|---| | `showTells` | `true` | draw the threatened area during a wind-up | | `aggression` | `1.0` | multiplies the gap between attacks; above 1 is slower | | `autoStartSeconds` | `16` | if no staging slice exists, start the fight anyway after this long | | `verbose` | `false` | log each decision | ## Methods ```lua local saint = entity.find("boss_root").component.get("SlagSaint") saint:status() -- everything about the fight, including `read` saint:moves() -- every move available now, with its tell sentence saint:hurt(24, "legs") -- deal damage the way combat would, events and all saint:ring() -- a perfect parry, without hands on a keyboard saint:quench() -- the critical; only lands while the core is exposed saint:cast("bell_toll") -- force the next wind-up saint:restart() -- full health, phase 1, damage cleared ``` `status().read` is the sentence a player should be able to say out loud during the current wind-up. If it does not match what you can see happening, the telegraph is broken. ## Standing alone The saint is playable without its neighbours. If the `Emberward` component is not in the world it resolves its own blows against the player, and if the `Director` is not in the world it starts the fight itself after `autoStartSeconds`. Both checks are by existence, so neither fires once the real slice lands.