# arena
Emberfront itself — the rift canyon the match is fought in.
`arena.build()` raises the whole place from code: the two basalt lane shelves,
the river of exposed melt between them, the canyon walls and their broken rim,
the Nexus / Gate / Altar at each end, the eruption on the horizon, the light,
the falling ash and the embers climbing out of the rift. `arena.teardown()`
takes all of it away again.
Every dimension is read from `game.rules` (`K.arena`, `K.points`, `K.palette`),
so the canyon can never disagree with the lane the creeps march down. Nothing is
written into the scene file: each piece is spawned as a temporary entity under
one root named `EmberfrontArena`, and building twice leaves exactly one canyon.
The scene's six anchor entities — `EmberNexus`, `AshNexus`, `EmberGate`,
`AshGate`, `EmberAltar`, `AshAltar` — keep their authored transforms. `build()`
only takes their placeholder cubes off and raises a real structure on the spot,
so every other slice still finds the world by them.
## Surfaces
| Asset | What it is |
|---|---|
| `art/cinder_basalt.shader` | Procedural triplanar basalt: ash on the ledges, a crust that breaks into cracks, grain you only see up close. |
| `art/emberfront_lava.shader` | The melt. Flows along the canyon, crusts over as it cools, tears open along the shear. |
| `art/basalt_ground.material` | The lane shelves. |
| `art/basalt_cliff.material` | Walls, buttresses, talus, the mountain beyond. |
| `art/lava_flow.material` | The rift. |
| `art/dark_iron.material` | The worked metal of the structures. |
| `art/obsidian.material` | Cut stone: rift banks, plinths, standing stones. |
| `art/ember_core.material` / `art/ash_core.material` | The two sides' burning hearts — orange for Ember, violet for Ash. |
| `art/ash_mote.material` / `art/ember_mote.material` | What the falling ash and the rising embers are made of. |
## Air and grade
A `HeightFog` volume pools ash in the canyon and warms toward the sun. The
screen-space chain is `bloom` → `color_correction` → `tonemap` (ACES) →
`vignette`; `teardown()` removes all four.
# economy
The match director for **Hero Line Wars: Emberfront**. It owns the wave
clock, pays both lanes their income, decides who commands each lane, runs
the AI commander for any lane no human holds, and carries a live match
through a hot reload.
Started by `scenes/main.scene/entrypoint.luau` as the first play-mode
slice, because everything else keys off its clock.
## The wave clock
Every `Rules.K.match.waveSeconds` (18s):
1. `Rules.state.wave` goes up by one.
2. Each lane is paid its own `income` through `Rules.grant`.
3. `Rules.bus.emit("waveTick", { wave = n })` — the creeps slice drains
both `sendQueue`s on this event and adds the wave's free creeps.
`M.waveClock` counts down to the next tick and is mirrored onto
`Rules.state.waveClock`; the HUD reads either. A frame long enough to
span more than one tick pays every wave it crossed rather than losing
them.
Nothing else in the game may own this timer.
## The AI commander
A lane whose `owner` is `nil` is run by a commander with two duties.
**Buy.** Every `M.ai.decisionSeconds` it may buy one creep into the foe's
lane through `Rules.send`, out of a budget re-cut at each wave tick as a
fraction of its purse (`commitBase` + `commitPerWave` per wave). The
opening is deliberately gentle and the late game is not. Which tier it
buys depends on how the target lane is coping: it counts `creepKilled`
and `creepLeaked` there, and when creeps are walking in untouched it
floods whatever takes the most lives per gold, while against a lane that
clears its creeps it sends the heaviest thing it can afford.
**Hold.** An AI lane has no hero standing in it, so the commander fields
a champion at `M.guardPost(lane)` — `guard.standoff` metres in front of
its own nexus. Each frame it fights whatever creep has come closest to
that post, splashing what stands beside it, through
`Creeps.nearest` + `Creeps.damageInRadius`; the bounty goes to its own
lane. Its damage climbs `guard.dpsPerWave` every wave up to `guard.dpsMax`,
so early creeps die at the post and a long enough column walks past while
it works. Out-scaling that line is how a player takes the Ash Nexus down.
The ceiling is set against the hero: `K.hero.attack` is a fixed 34 every
0.55s — about 62 damage a second, and roughly 76 with cleave against a
pile — and it does not grow with the wave. A champion that climbed past
that forever would out-hold every lane a player can hold, in every match,
whatever the player did. So `guard.dpsMax` sits just above a hero's
output, and `guard.reach` is about a hero's swing, so a column has to be
met at the post rather than deleted from down the lane.
Every number the commander runs on is in `M.ai`, in one table, so the
whole difficulty curve is tunable without reading the code.
## Lane ownership
The local player always commands **ember** — `start()` claims it before
the live player entity has even resolved, so the AI can never take the
player's own lane. The entrypoint forwards `playerJoined` / `playerLeft`
here; the first player who is not this client takes **ash**, which stands
its commander down. When they leave, the commander picks the lane back up.
Each change emits `laneOwnerChanged { lane, owner }`.
## What other slices read
| Field | Meaning |
|---|---|
| `M.waveClock` | seconds to the next wave |
| `M.wave` | current wave number |
| `M.running` | the clock is live |
| `M.stats` | waves, income paid, AI sends and champion damage per lane, plus why the champion swung or held fire (`guardTicks` / `guardSwings` / `guardNoTarget` / `guardOutOfReach`) |
| `M.ai` | the whole difficulty curve |
| `M.guardPost(lane)` | where that lane's champion stands |
`M.tickWave()` forces one tick without waiting on the clock.
## Hot reload
Saving this file mid-match would otherwise stop the game: the module gets
fresh locals and its `running` flag goes false with nothing left to
restart it. Loading it while `Rules.state.phase == "running"` therefore
calls `M.resume()`, which rebuilds the commanders off `Rules.state` and
carries the match on. Bus subscriptions are registered through a list
kept on the bus itself, so a reloaded copy lifts the previous copy's
handlers off before adding its own.
# 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.
# game.hud — the Emberfront screen
Everything the player reads, and every button they press that is not the
hero's own controls. The HUD reads match state and calls `Rules.send`; it
never writes gold, lives or income, and it never touches another slice's
entities.
```luau
local Hud = require("game.hud")
Hud.start() -- register + show both screens, subscribe to the bus
Hud.update(dt) -- called every frame by the scene entrypoint
Hud.stop() -- remove the screens, unsubscribe, release the callback env
```
## The two screens
| Screen | Layer | Carries |
|---|---|---|
| `emberfront_hud` | 40 | both nexuses' lives, the treasury, the wave countdown, the SEND panel, the hero bar and ability chips, the battle log, the affordability toast |
| `emberfront_hud_cards` | 45 | the how-to-play card and the victory / defeat screen — shown only when one of them applies |
## Controls it owns
| Input | Effect |
|---|---|
| `1` `2` `3` `4` | `Rules.send("ember", <tier>)` — the tier in that row of `Rules.K.creeps` |
| click a SEND row | the same send; unaffordable rows are dimmed and carry no click |
| `F1` | toggle the how-to-play card (`Esc` closes it) |
| `Enter` | on the end card only — asks the match director for a new match |
The end card also carries a **PLAY AGAIN** button on the same path. Both are a
request, not an action: the HUD calls `game.economy`'s `restart()` and the
director decides what a fresh match means. Either is ignored while the match is
still running, and pressing both several times still produces exactly one new
match.
| click **TO THE LANE** | close the card |
A send that cannot be paid for raises a two-second toast naming the shortfall
rather than failing in silence.
## What it reads from the other slices
Both are read through a guarded `require`, so the HUD degrades to defaults
instead of taking the match down when a neighbour is mid-edit.
| Source | Field | Meaning |
|---|---|---|
| `game.rules` | `state.lanes.<lane>.lives / .gold / .income / .sent` | the two lane records |
| `game.rules` | `state.wave` `.phase` `.winner` | match progress |
| `game.economy` | `waveClock` | **seconds remaining** until the next wave tick (falls back to `Rules.state.waveClock`) |
| `game.hero` | `health` `maxHealth` `alive` | the health bar |
| `game.hero` | `respawnIn` | seconds until respawn, shown while `alive` is false |
| `game.hero` | `cooldowns.cleave` `.surge` | **seconds remaining**, `0` = ready — the chip fills back up as this counts down |
## Bus events it listens to
`creepKilled` `creepLeaked` `sendQueued` `waveTick` `heroDied` `heroRespawned`
feed the battle log. `matchStarted` opens the how-to card, `matchOver` fills the
screen with victory or defeat.
## How it stays cheap
`update` builds one short signature string per frame from the values that would
change a pixel — lives, gold, income, wave, phase, the countdown to a tenth, hero
health to the point, each cooldown to a tenth, the length of the feed — and only
rebuilds the tree when that string moves. A still HUD costs a string compare.
The cards screen has its own signature and is hidden outright when neither card
applies, so the full-screen overlay never sits invisible over the game.
## Surviving a hot reload
A hot reload swaps every local in `init.luau` for a fresh one while the scene
entrypoint keeps ticking the same module table, so `update` would find itself
un-mounted and go dark for the rest of the session. It re-mounts instead. The
bus subscription list is parked on `Rules.bus` — the one table a reload of this
file leaves alone — so the new incarnation can unsubscribe the handlers the old
one registered rather than leaving two generations listening.
# 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.