# 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.

# hero.module The hero — the thing the player is in **Hero Line Wars: Emberfront**. This module attaches to the **live local player's avatar** (`layers.active.players.localPlayer.avatar`), the clone the engine makes of the scene's `HeroPrototype` when a peer joins. It never builds a second rig. ## What it does | | | |---|---| | **Move** | Retunes the avatar's `CharacterController` to `Rules.K.hero.moveSpeed`, and clamps the body into the ember lane band every frame with `Rules.clampToLane`. The lava rift and the canyon walls are hard bounds. The clamp is pulled `EDGE_INSET` metres inside the band: the lane shelf ends on exactly the band's line, and a capsule standing with its centre on the last inch of that ledge falls off and wedges inside the shelf's own collider, pushing at full speed against a velocity of zero with nothing in the game able to free it. A hero found under the floor anyway is set back on top of it. | | **Turn** | The stock controller strafes without ever turning, so the hero would keep facing one way forever. Each frame the body is turned to face its own velocity. | | **Swing** | `attack` — left mouse / right trigger / the on-screen **Attack** button. Resolved through `Creeps.damageInArc` on `K.hero.attack` (damage, cooldown, range, arc). Held, it keeps swinging on the cooldown. | | **Cleave** | `Q` / gamepad north / the **Cleave** button. A radial burst through `Creeps.damageInRadius` on `K.hero.abilities.cleave`. | | **Surge** | `E` / left shoulder / the **Surge** button. A dash: `moveSpeed × speedMult` for `duration`, with an ember trail riding the body. | | **Live and die** | Damage in from the creeps slice, out-of-combat regeneration, death, and a respawn at `K.points.emberSpawn` after `K.hero.respawnSeconds`. | Every effect it spawns — spark bursts, light flashes, the surge trail — is a `temporary` entity with a time-to-live this module counts down and despawns, so nothing it makes reaches a scene save and nothing outlives `stop()`. ## Controls The three combat controls live in `/zero/source/game/hero_controls.inputMap`, each carrying keyboard, gamepad and touch. Movement and the camera come from the engine's own `default` map, which the avatar's `CharacterController` activates; this map composes beside it in its own `hero` group and suppresses nothing. ## What other slices call ```lua local Hero = require("game.hero") Hero.damage(amount, opts?) -> boolean -- the creeps slice's hook. `opts` is -- free-form metadata for the feed. -- false while dead or the match is over. -- `applyDamage` / `takeDamage` are aliases. Hero.position() -> { x, y, z }? -- where to march at, or nil while unbound Hero.avatar() -> EntityProxy? Hero.isAlive() -> boolean Hero.tryAttack() / Hero.tryCleave() / Hero.trySurge() -> boolean -- the same three actions without a keyboard, for a HUD button or a test. ``` ## What the HUD reads Kept current every frame: ```lua Hero.health Hero.maxHealth Hero.alive Hero.respawnIn Hero.cooldowns.cleave Hero.cooldowns.surge -- seconds left, 0 = ready Hero.cooldownMax.cleave Hero.cooldownMax.surge -- what to divide by for a bar Hero.surgeActive -- seconds of dash left ``` ## Events it emits On `Rules.bus`: `heroDamaged { lane, health, max, amount, source }`, `heroDied { lane }`, `heroRespawned { lane }`, `abilityUsed { lane, ability, hits? }` — `ability` is `"attack"`, `"cleave"` or `"surge"`. ## What binding also sets up Three things are applied once, the first time the live avatar resolves, and left alone afterwards so anything the player does with them stands. - **The camera framing.** The stock `orbital_follow` rings frame a conversation — head height, four metres out — which in this canyon puts the eye at the hero's ankles and fills the screen with basalt. `CAMERA` replaces all three rings with a raised chase shot that sees a stretch of lane ahead, and `CAMERA_HEADING` aims the opening shot into the oncoming column rather than at the nexus behind. The player still orbits and zooms from there. - **The lantern.** A warm point light named `hero_lantern` that rides the hero. The canyon is lit by the rift alone, which leaves the lane floor and everything standing on it reading as pure black from the chase camera. The lamp keeps the hero, the ground and whatever walked into range legible without lifting the ambient over the whole canyon. It is `temporary`, there is only ever one, and a reloaded copy of this module adopts the existing one rather than hanging a second light on the body. - **The plate.** Every `SkinnedModel` under the body is put into `art/hero_emberplate.material`, because the avatar the engine mints for a joining peer wears a stock skin that reads as a pale mannequin standing in a volcano. The field is assigned directly rather than through `appearance.swapMaterials`: that tool is an authoring one and marks what it touched with an outline, which on the player's own body is a blue ring that never leaves. ## Lifecycle `start()` / `update(dt)` / `stop()`, called by the scene entrypoint. `start()` is idempotent, and tolerates being called before the avatar clone exists — `update` keeps asking every half second until it is there. `update` also re-arms the slice if it finds itself disarmed, which is what a hot reload of this file leaves behind: fresh module locals, a false `running` flag, and an entrypoint still ticking the same table.

# game.creeps — everything that marches The monsters. This module spawns them at the gates, walks them down their lane, stops them to swing at whoever is standing in the way, kills them for bounty, and leaks them into the nexus at the far end. ```lua local Creeps = require("game.creeps") ``` ## What a creep is A creep is an entity hierarchy: a bare root that carries the march, a handful of `Model` parts hung off it that give the tier its silhouette, and a floating health bar. The root's scale is the tier's `scale` from `Rules.K.creeps`, so a Magma Colossus is the same blueprint blown up. Every part is `temporary`, so no creep is ever written into the saved scene. The four tiers read apart at a glance, by size, shape and colour: | Tier | Silhouette | |---|---| | `emberling` | knee-high glowing blob on two stubs, bright orange | | `hound` | long, low, four-legged, spined, crimson | | `brute` | broad hunched biped, dark, molten chest and flank seams | | `colossus` | towering black figure, crowned, with a furnace for a heart | ## The wave On `waveTick`, every lane's `sendQueue` is drained into the **foe's** lane — that is the whole game — and `Rules.K.match.freeCreepsPerWave` baseline creeps are added to each lane so a lane nobody is buying into still has something walking down it. The baseline tier escalates with the wave number, slowly enough that a defended lane is never drowned in creeps it did not earn. The whole batch is released from the gate one creep at a time, so a wave streams out instead of appearing in a lump. ## March, fight, die, leak A creep walks from its gate toward its nexus at `def.speed`, weaving gently around its own line. A defender standing in front of it within reach stops it, and it swings on its tier's cadence. Every player south of the lava rift defends ember and every player north of it defends ash — one player, two, or none, no lane-ownership lookup needed. Killed, it pays `Rules.grant(byLane, def.bounty)` and sinks. Leaked, it calls `Rules.leak(lane, def.leak)` and the nexus takes the lives. Emits `creepSpawned`, `creepKilled`, `creepLeaked` on the rules bus. ## The contract the hero calls These four are fixed. `by` is the **attacking** lane (`"ember"` for the local player) — a hero only hits the creeps marching down its own lane, which is also the lane whose bounty it collects. ```lua Creeps.damageInArc(origin, forward, range, arcDegrees, amount, by) -> hitCount Creeps.damageInRadius(origin, radius, amount, by) -> hitCount Creeps.nearest(position, lane) -> creep? Creeps.countIn(lane) -> number ``` `origin` / `forward` / `position` take a `{x, y, z}` record, a three-element array, or an entity position proxy — all three read the same. ## Reading the live set `Creeps.live` is every live creep, newest last. Each entry carries at least `{ id, def, lane, entity, health, maxHealth }`; `lane` is the lane it is **marching down**, so `"ember"` means it threatens the ember nexus. ```lua Creeps.roster() -- Rules.K.creeps, in cost order Creeps.spawnNow(lane, creepId, at?) -- one creep now, optionally partway down ``` ## How creeps hurt the hero A creep hands damage to `game.hero` through the first of `applyDamage`, `damage`, `takeDamage` or `hurt` that the hero slice exposes, and falls back to the `health` / `alive` fields the spec pins if none of them is there.