# CampaignHost
Draws and drives campaignKit for the local player. `campaignKit.api` spawns it on a temporary local entity when `Campaign.start` runs in play, so nothing is placed in a scene. Each frame it runs the director (flow, keys, music, move sounds), registers the director's screens (level select, results bar) and redraws them only when they were rebuilt; clicks on them land in its `onCallback` and go to the director. Needs no sibling components.
# api
campaignKit's front door. `Campaign.start(config)` gives a level-based game its whole shell from one config table, on the player's own machine: menusKit title, a level-select map (`map.style`: storybook, parchment, lanterns or list), a dialogueKit story beat before and after each level, the level itself (platformer3dKit by default, or your own runner), results with Next / Retry / map, a finale hook, credits, per-player pause and settings, per-level music and jump / land / checkpoint / death sounds. Call it in play from any script (a component's `update` is fine: a running config is left alone).
Also: `Campaign.status()`, `Campaign.on(evt, fn)` ("state", "level", "finish", "unlock"), `Campaign.go(screen, levelId)`, `Campaign.restart()`, `Campaign.finished(levelId, result)` for custom runners, `Campaign.setMapStyle(style)`, `Campaign.setSoundSet(set)`, `Campaign.sting(name)`, `Campaign.best(id)`, `Campaign.isUnlocked(id)`, `Campaign.catalogue()`. The config's fields are listed in the package README.
# director
The campaign's flow for the local player: title -> level select -> story beat -> level -> results (+ the after-level beat) -> Next / Retry / map, and after the last level the finale hook, the finale words and the credits. Handles the per-player pause (Escape / P), the map's keys (arrows / WASD, Enter, Esc) and clicks, the results bar ("map (M)" or "the ending (M)" under the runner's results card), saving progress and the unlock toast, and keeps the right music piece playing. It draws nothing itself: it keeps the trees of its screens in `Director.wanted()` and rebuilds them only when the focus, the progress or the screen size changes; `campaignKit.CampaignHost` registers them. Games use it through `campaignKit.api`.
# events
campaignKit's local signals for the rest of a game (mood, HUD, tests): `on("state", fn)` with `{ state, level }` (title, select, sendoff, playing, results, finale, credits), `on("level", fn)` when a level's story beat starts, `on("finish", fn)` with the run's result after progress is saved, `on("unlock", fn)` when a level opens, `on("*", fn)`, and `current()` for the last state. Everything is this machine's player only.
# looks
The look every campaign screen is drawn in: six built-in looks (parchment, cartoon, minimal, pixel, scifi, night) with colours, fonts, panel, button and backdrop tokens; a game picks one by name or overrides tokens with `{ base = "parchment", colors = { ... } }`. Helpers for screens (`label`, `button`, `panel`, `backdrop` with a painted picture), and `defineMenuTheme(name, look, { art, ornament, ornamentLit, glowAt })` / `defineDialogueStyle(name, look, overrides)`, which turn a campaign look into a matching menusKit look (painted title backdrop, carved buttons with ornaments) and dialogueKit style. Set through the config's `look`, `menuLook` and `dialogueLook`.
# maps
The level-select screens, one per `map.style`: **storybook** (the game's painted picture, `map.art`, with a glowing waystone and name tag per level at `map.spots`), **parchment** (an inked map on old paper: dashed trail between ink rings, legs walked in red ink, cleared stops crossed, a compass rose), **lanterns** (a string of lanterns across a starry night; each lights when its level is cleared, the chosen one sways) and **list** (number, name, best time and medal per row). Each shows lock, best time and medal per level and a card for the chosen level (swatch for its time of day, par, best, coins, medal, Play) in the campaign look. `Maps.build(w, h, view)` returns the widget tree; click ids are `Maps.ID_PLAY`, `Maps.ID_BACK`, `Maps.ID_LEVEL .. index`. `Maps.list()` describes the styles.
# medals
How a level's best tier (3 gold, 2 silver, 1 bronze) is drawn on the select screens, in four styles swapped by the config's `medal` setting: `disc` (polished metal disc with a star), `stars` (one to three stars), `ribbon` (rosette with tails) and `grade` (S / A / B badge). `Medals.configure(tiers)` renames or recolours the tiers (`config.medals`); `Medals.node(style, tier, size, look)` returns a widget node and `Medals.info(tier)` the tier's name and colours.
# progress
Each player's progress through the campaign's level list, on their own machine: `best(id)` (from the runner), `isUnlocked(id)` (first level always; the next once the one before has a best, or once saveKit unlocked it), `isCleared`, `furthest()` (Continue), `hasAny()`, `finished(id, info)` (saveKit finishLevel / coins stat / `open_<next>` event; returns a newly opened level), `sawFinale()`, `totals()` (medals, coins, cleared) and `nextOf`, `isLast`, `level`. Sets up saveKit's per-player profile with one unlock per level plus the game's own (`config.save`). Used by the director and the map screens; read it through `Campaign.progress`.
# runners
What plays a level for the campaign. `platformer3dKit` (the default) starts, stops and restarts platformer3dKit levels, reads each player's best, listens to its finish / results / level / restart / checkpoint / death events, holds its autoStart until the title is passed, finds each level's start (`Level_<id>`) and can hide Trapline's lives hearts (`livesHud = false`). A table `{ start, stop, restart, best?, startPoint?, phase? }` plugs in any other game's levels: call `Campaign.finished(levelId, { time, tier, coins, totalCoins })` when a run ends and the campaign keeps the best (in memory and saveKit) and shows a menusKit results screen with Next / Retry / map.
# sounds
The campaign's sound for the local player. Music per screen and per level through soundstage with `shared = false`, so two friends on different levels hear their own piece (`config.sounds.music = { title, select, finale, credits, levels = { [id] = clip } }`). Nine campaign sounds (jump, land, checkpoint, death, select, unlock, medal, clear, start) in four sets swapped by one setting, `sounds.set`: storybook, cartoon, retro (chipSfx 8-bit) and scifi, or none. `extra` adds the game's own stingers, `volume` sets loudness per sound, and jump / land are read from the local body's CharacterController each frame.
# checkpoint (cartoon)
campaignKit's `checkpoint` sound in the cartoon sound set: played for reaching a checkpoint. Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("checkpoint")`.
Generated from the description: "cartoon checkpoint reached, bright xylophone arpeggio up with a little ding, cheerful, short".
# clear (cartoon)
campaignKit's `clear` sound in the cartoon sound set: played for a level cleared (the run reaching the finish). Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("clear")`.
Generated from the description: "cartoon game clear sound effect, short".
# death (cartoon)
campaignKit's `death` sound in the cartoon sound set: played for the player being knocked out / falling into a hazard. Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("death")`.
Generated from the description: "cartoon game death sound effect, short".
# jump (cartoon)
campaignKit's `jump` sound in the cartoon sound set: played for the local player's jump. Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("jump")`.
Generated from the description: "cartoon game jump sound effect, short".
# land (cartoon)
campaignKit's `land` sound in the cartoon sound set: played for the local player landing (played louder for a harder landing). Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("land")`.
Generated from the description: "cartoon game land sound effect, short".
# medal (cartoon)
campaignKit's `medal` sound in the cartoon sound set: played for a medal won at the end of a run. Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("medal")`.
Generated from the description: "cartoon game medal sound effect, short".
# select (cartoon)
campaignKit's `select` sound in the cartoon sound set: played for moving the choice on the level select and opening a story beat. Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("select")`.
Generated from the description: "cartoon game select sound effect, short".
# start (cartoon)
campaignKit's `start` sound in the cartoon sound set: played for a level starting, as its story beat opens. Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("start")`.
Generated from the description: "cartoon game start sound effect, short".
# unlock (cartoon)
campaignKit's `unlock` sound in the cartoon sound set: played for a new level opening on the map. Picked by `sounds.set = "cartoon"` in a campaign config, or played by hand with `Campaign.sting("unlock")`.
Generated from the description: "cartoon game unlock sound effect, short".
# checkpoint (scifi)
campaignKit's `checkpoint` sound in the sci-fi sound set: played for reaching a checkpoint. Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("checkpoint")`.
Generated from the description: "scifi game checkpoint sound effect, short".
# clear (scifi)
campaignKit's `clear` sound in the sci-fi sound set: played for a level cleared (the run reaching the finish). Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("clear")`.
Generated from the description: "scifi game clear sound effect, short".
# death (scifi)
campaignKit's `death` sound in the sci-fi sound set: played for the player being knocked out / falling into a hazard. Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("death")`.
Generated from the description: "scifi game death sound effect, short".
# jump (scifi)
campaignKit's `jump` sound in the sci-fi sound set: played for the local player's jump. Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("jump")`.
Generated from the description: "scifi game jump sound effect, short".
# land (scifi)
campaignKit's `land` sound in the sci-fi sound set: played for the local player landing (played louder for a harder landing). Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("land")`.
Generated from the description: "scifi game land sound effect, short".
# medal (scifi)
campaignKit's `medal` sound in the sci-fi sound set: played for a medal won at the end of a run. Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("medal")`.
Generated from the description: "scifi game medal sound effect, short".
# select (scifi)
campaignKit's `select` sound in the sci-fi sound set: played for moving the choice on the level select and opening a story beat. Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("select")`.
Generated from the description: "scifi game select sound effect, short".
# start (scifi)
campaignKit's `start` sound in the sci-fi sound set: played for a level starting, as its story beat opens. Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("start")`.
Generated from the description: "scifi game start sound effect, short".
# unlock (scifi)
campaignKit's `unlock` sound in the sci-fi sound set: played for a new level opening on the map. Picked by `sounds.set = "scifi"` in a campaign config, or played by hand with `Campaign.sting("unlock")`.
Generated from the description: "scifi game unlock sound effect, short".
# checkpoint (storybook)
campaignKit's `checkpoint` sound in the storybook sound set: played for reaching a checkpoint. Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("checkpoint")`.
Generated from the description: "storybook game checkpoint sound effect, short".
# clear (storybook)
campaignKit's `clear` sound in the storybook sound set: played for a level cleared (the run reaching the finish). Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("clear")`.
Generated from the description: "storybook game clear sound effect, short".
# death (storybook)
campaignKit's `death` sound in the storybook sound set: played for the player being knocked out / falling into a hazard. Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("death")`.
Generated from the description: "storybook game death sound effect, short".
# jump (storybook)
campaignKit's `jump` sound in the storybook sound set: played for the local player's jump. Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("jump")`.
Generated from the description: "storybook game jump sound effect, short".
# land (storybook)
campaignKit's `land` sound in the storybook sound set: played for the local player landing (played louder for a harder landing). Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("land")`.
Generated from the description: "storybook game land sound effect, short".
# medal (storybook)
campaignKit's `medal` sound in the storybook sound set: played for a medal won at the end of a run. Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("medal")`.
Generated from the description: "storybook game medal sound effect, short".
# select (storybook)
campaignKit's `select` sound in the storybook sound set: played for moving the choice on the level select and opening a story beat. Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("select")`.
Generated from the description: "storybook game select sound effect, short".
# start (storybook)
campaignKit's `start` sound in the storybook sound set: played for a level starting, as its story beat opens. Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("start")`.
Generated from the description: "storybook game start sound effect, short".
# unlock (storybook)
campaignKit's `unlock` sound in the storybook sound set: played for a new level opening on the map. Picked by `sounds.set = "storybook"` in a campaign config, or played by hand with `Campaign.sting("unlock")`.
Generated from the description: "storybook game unlock sound effect, short".
# story
The story beats: a dialogueKit conversation before each level (`story.before`, e.g. `"intro_{level}"`), over its results card (`story.after`) and at the finale (`story.finale`), played for the local player only with the game's dialogue style. Conversations can be registered from the config (`story.conversations`). An optional story NPC (`story.npc = { model, entity, light }`) stands beside the player at the level start while they talk; it is a local entity per machine, so two players never see each other's scenes. A level with no conversation simply starts.
# campaignKitTests
Checks campaignKit's pieces without entering play: look tokens merge over a base look; every medal style draws every tier; each of the four map styles (storybook, parchment, lanterns, list) builds a screen with a marker per level plus Play and Back; unlocks follow the level list (first open, next opens on a best, Continue goes to the furthest, totals); a custom runner keeps only the best run; story ids by pattern, table and function; every sound set resolves and an unknown one is refused; events reach listeners; the director takes a config and swaps the map style with one setting. The full flow in play (title -> map -> story -> level -> results -> Next -> finale -> credits) is exercised by the Campaign Trail showcase and by Lantern Peak's end-to-end test, not here. Run: `tools.use("tests", "run", { suite = "campaignKitTests" })`.