# Architecture: Ghoul Rush core > Part of [AGENTS.md](../AGENTS.md) and the [Architecture index](./AGENTS-architecture.md): project guidance for AI coding agents. Ghoul Rush's shared core, drawing, weapons, story and sound files under `src/web-console/public/activities/ghoul-rush/`. The other games and the rules every game follows are in [Activities](./AGENTS-architecture-activities.md); Ghoul Rush is split over [core](./AGENTS-architecture-ghoul-core.md), [stages](./AGENTS-architecture-ghoul-stages.md) and [rides](./AGENTS-architecture-ghoul-rides.md). | File | Role | |---|---| | `public/activities/ghoul-rush/ghoul.js` | Ghoul Rush's public face and nothing else: it re-exports the parts below, so the page and the tests import from one place. Everything lives under `ghoul-rush/`: `core/` (the rules, rooms, run flow, power-ups, dice, bonus rounds), `arms/` (secondary weapons), `draw/` (shared drawing), `story/` (the intro story, stage and boss cards, game over), `sfx/` (shared sounds), `stages//` and `rides//` (each with its rules, art and sounds). | | `public/activities/ghoul-rush/core/ghoul-tables.js` | Ghoul Rush's numbers and tables: the shared timings and sizes, `PACKS` with every pack's monsters, bosses and hooks joined in, the seeded dice, and `roomFor`. Loads first and imports none of the other parts. | | `public/activities/ghoul-rush/core/ghoul-kit.js` | `KIT`, the helpers handed to the stage packs: one object `ghoul-play.js` fills as it loads, so a part that only passes it on has no load-order tie to the play loop. | | `public/activities/ghoul-rush/core/ghoul-planny.js` | The ground and Planny: surfaces, shelves, landing, and how he runs, jumps and falls. | | `public/activities/ghoul-rush/core/ghoul-monsters.js` | The monsters: spawning, how each kind moves, and what they throw. | | `public/activities/ghoul-rush/core/ghoul-fight.js` | Bosses and damage: a boss's fight and fall, hurting and killing a monster, losing a life. | | `public/activities/ghoul-rush/core/ghoul-play.js` | The play loop: `KIT` and `RUN_KIT`, the blaster and bolts, hits, stomps, timers, one slice of play, and `advance()`. | | `public/activities/ghoul-rush/core/ghoul-window.js` | The game's contract with the Activities page: `create`, keys and pointer, what events set off, `ROOM_MUSIC`, the view handed to the drawing. | | `public/activities/ghoul-rush/story/ghoul-ending.js` | The ending's four pages (lights out, the road, morning, final notice) and their rules in phase `ending`: a lockout, typing finished first, a minimum time per page, a one-second fire hold to skip, `skipEnding`; it wins the run once at its end (`won` with `n: round.winN`) | | `public/activities/ghoul-rush/story/ghoul-ending-draw.js` | `endingArt(d)` returns `{ card, react }`: four animated scenes in the story's layout; `react` answers only `endingPage` | | `public/activities/ghoul-rush/story/ghoul-sfx-ending.js` | `ENDING_SFX`: the ending's `ghoulEnding*` tones, the user's picks (wired by `wire-ending-sounds.cjs`), and its track `ghoulMarrowEnding` (`ENDING_TRACK`) | | `public/activities/ghoul-rush/draw/ghoul-draw.js` | Ghoul Rush's drawing: `drawScene(ctx, view)` from one view object `ghoul.js` refills each frame, in room units turned the right way up and scrolled by the camera: the strip above the field in the page's colors with the pills (laid out by `hudLayout`: the room, lives, the bonus, the chain with its window emptying, the key once held, the power-ups; a second row rather than run off the board, the rows centered in the strip), still layers `CHUNK` units of a room wide drawn off screen once per room and scale and copied each frame (a few kept; each room's look in fixed colors, `LOOKS`: wallpaper, moonlit windows, decor by room (portraits, bookcases, curtains, pots, ferns, rafters with cobwebs, headstones), wainscot, floorboards, pits, shelves, wall doors and loose boards), the crumbling boards, a wall door standing open, the chandeliers, the exit door (padlocked, then open and glowing), candy, power-ups and the key, the monsters (a zombie in a ragged shirt with mismatched eyes, lurching; a crawler's hand through the boards, then crawling; a bat with flapping wings; a sheet ghost fading in and out; a skeleton raising a bone; gourdlings), bones and shockwaves, the bosses (the Great Gourd with a carved glowing face and a red shadow where it will land; Old Rattlebones, drawn by `ghoul-bones-draw.js`) and the boss bar, Planny (his star eye in your highlight in every state, stick arms, one holding the flashlight blaster that flares as it fires, stepping, arms up in the air or cheering, spinning with an "o" when hit, slumped at the end, garlic circling him while he has some; arms and feet in `limbInk(look)`), the bolts, sparks, rings, floating words kept on the field by `labelSpot`, the chain's big number, banners (`BANNER_SHADE`) the stage pick (`drawPicker`: a card per stage offered with its picture, `drawStagePicture`, its first room's wall and moonlit window over its boss room's floor with its boss standing there drawn by the same `BOSS_ART` as in play, name, line and boss, the one picked out raised and edged in gold, `stageColor` its boss room's), and the start and end strip with the big final score and a dot per stage, lit in each cleared stage's color (gold for the record before a run); `react(e, kit)` turns each event into those effects and its blips, a monster's own sound through `VOICES` (each kind's tone in `ghoul-sfx.js` by act: `appear` (a runner's `warn`, a bat's `wake`, a wraith's `notice`), `climb`, `hop`, `growl`, `lunge`, `shriek`, `dive`, `spit`, `throw`, `hurt` (one every 140 ms), `die`, and a boss's `wake`, `hop`, `slam`, `windup`; a "throw" event names its thrower in `by` and a "spit" its spitter in `kind`); the stage packs' drawing (`ART`: an `outdoor` look draws its pack's backdrop instead of walls, graves for doors, and each pack's monsters, bosses, missiles, hazards and lights by kind; a pack may also draw `sky` (every frame, under the still layers, so its backdrop leaves the sky clear) and `moving` (what moves in its scenery, over the still layers)); `readColors(canvas)`, `contrast`, `lookOf`; decides nothing | | `public/activities/ghoul-rush/core/ghoul-rooms.js` | Ghoul Rush's rooms and stages as data (no imports): the long hall every run starts in (`ROOMS[0]`), then `STAGES` (each an id, title, line and four room ids, the last a boss's, checked at load; `stageById`, `roomById`), `FIELD_W`, `FIELD_H`, `FLOOR_Y`, `CEILING_Y`, `CHANDELIER_Y`, and per room its look, name and line, length, ground pieces (pits between, steps and walls), shelves (`crumble` kind), start, key, door, candy rows, power-ups, spawns (zombies, wall doors, crawlers' boards, bats, ghosts, skeletons), chandeliers and boss (`gourd`, `bones` or a pack's, the last room of its stage); a door's fifth entry names what comes out of it (rotters out of the Graveyard's graves) | | `public/activities/ghoul-rush/arms/ghoul-flare.js` | The Road Flare's rules (`useFlare`, `stepFlareFly`, `stepRoadFire`; no imports, handed the helpers by `ghoul-arms.js`): a lob that lands as a patch of fire, burns monsters on a tick, melts a Frozen Ghoul at once, shows a shade and melts the Widow's veil; never hurts Planny | | `public/activities/ghoul-rush/story/ghoul-story.js` | Ghoul Rush's intro story: the pages' text as data and the rules (lockout, reveal, skip) as plain functions over a round; drawn by `ghoul-story-draw.js`, sounded by `ghoul-sfx-story.js`, the lore bible in `prototypes/Ghoul-Rush-TODO.md` | | `public/activities/ghoul-rush/story/ghoul-story-draw.js` | The intro story's drawing (`storyArt(d)`): eight animated scenes in canvas shapes (the road, the house on the hill, the hunger, the long arms, the farthest rooms, why YOU, no way back, the door to The Long Hall) with the heading, the lines typing out, the page dots, the always-visible skip hint with its hold bar and the pulsing continue hint; drawn over the field while `round.phase === "story"`; reuses the intro card's helpers (`poly`, `dot`, `stroke`, `faint`, `flame`, `titleLayout`, `dropAt`); no gradients | | `public/activities/ghoul-rush/story/ghoul-sfx-story.js` | The intro story's own sounds as data (no imports): `STORY_SFX` tones for the pages' `cues` (wind, a bell, a heartbeat, a door creak, knocks, a whisper, the flashlight click, the page turn) and the `hums` drone under the whole story; merged by `ghoul-sfx.js` | | `public/activities/ghoul-rush/draw/ghoul-picker-draw.js` | The choice of stage, its drawing: `pickerArt(d)`, handed `ghoul-draw.js`'s helpers (`lookOf`, `label`, `roundRect`, `circle`, `BOSS_ART`, `drawGourdFire`, `GOLD`), returning `drawPicker` (a card per stage offered: its picture of its rooms with its boss standing there, its name, line and boss, the pick raised and edged in gold, and how to choose), `drawSelect` (the stage select for testing: every stage in a list, two columns past 8, the one picked out with its picture and a chip per room) and `stageColor` (a stage's boss room's color, also the tally dots'). Split from `ghoul-draw.js` to keep it under the 3,000-line cap | | `public/activities/ghoul-rush/core/ghoul-powers.js` | Ghoul Rush's power-ups and pickups (no imports: `ghoul.js` hands its rules a kit, `POWER_KIT`, of `landing` and the numbers they need): `POWERS` (each power-up's name, line, color, `ms` if timed, drop `weight`, and its rule, the Lantern's `dark`), `TIMED`, `PILL_WORDS`, `FLAP_CLEAR`, `HOURGLASS_MS`, `CANDY_POINTS`, `POWER_POINTS`, `CRYSTAL_POINTS`, `powerHere(round, kind)` (whether a power-up can turn up in the room as it is now; a new rule, such as a stage-only power-up, goes in `POWERS` and is checked here), `pickPower`, `applyPower(round, kind, kit)` (`ghoul.js` exports it bound to its kit as `applyPower(round, kind)`) and `pickups` (candy, placed and dropped power-ups, crystals up high and the key, taken by touch; drops fall and fade). Split from `ghoul.js` to keep it under the 3,000-line cap | | `public/activities/ghoul-rush/arms/ghoul-arms.js` | Ghoul Rush's secondary weapons (imports only `ghoul-powers.js`; a pack in `PACKS`, `ARMS`): the double tap (`pressFire`, `releaseFire`, called from the game's `key()` and `release()`, never from `round.input.fire`, so bots never throw), the bag `round.arms` (`useArm`, `armOnTop`: a ride room skips what needs a floor), each weapon's rule (a shot with `arm` through `moveShots`, or a hazard), and `armBossDamage` (scaled to depth, capped at `ARM_BOSS_SHARE` of a boss's hp a fight). Weapons' names, bundles and caps are in `POWERS` (`arm: true`, weight 0), the stage's own in `STAGE_ARMS`, the kill drop band in `armDrop`, all in `ghoul-powers.js`. | | `public/activities/ghoul-rush/arms/ghoul-arms-draw.js` | The weapons' art (`armsArt(d)`): their badges (`powers`), `hazards`, `shot` for one in flight, `pill` for the HUD's icon and count, `front` (stars over the dazed), `lights` and `react`. Dynamite's stick, blast and badge stay in `ghoul-mine-draw.js`. | | `public/activities/ghoul-rush/arms/ghoul-rockets.js` | The Bottle Rocket's rules, the common weapon every stage sells: one use lights three rockets, one ahead, one up and one behind | | `public/activities/ghoul-rush/arms/ghoul-rockets-draw.js` | The Bottle Rocket's drawing (`rocketArt(d)`): the muzzle's flash and smoke, the flared rocket on a stick with a glowing head, the fountain of sparks it sheds and the burst when it goes off | | `public/activities/ghoul-rush/arms/ghoul-pans.js` | The Cast-Iron Skillet's rules, the East Wing's weapon: three pans that circle Planny, then spiral outward until they are off screen | | `public/activities/ghoul-rush/arms/ghoul-sfx-arms.js` | The weapons' `tones` (`ARMS_SFX`), merged by `ghoul-sfx.js` like a stage's. A first pass, not yet picked by ear. | | `public/activities/ghoul-rush/core/ghoul-run.js` | Ghoul Rush's run flow (no imports: `ghoul.js` hands its rules `RUN_KIT`, the room and stage tables, the timings and the helpers that set a room up, and binds them): `newRound`, `setupRoom`/`resetRoom`, the stage pick (`stagesLeft`, `nextRoom`, `steerPick`, `pickStage`), the stage select for testing (`openSelect`, `steerSelect`, `takeSelect`: a practice round, `round.practice`, that keeps no best score or record), `camera`, `respawn`, `lockArena`, `clearRoom`, and a room's monster supply (`spawners`, `horde`, `hurry`). `ghoul.js` re-exports `newRound`, `stagesLeft`, `steerPick`, `pickStage`, `steerSelect` and `takeSelect`, and its game answers `stageSelect()`. Split from `ghoul.js` to keep it under the 3,000-line cap, with the same random draws in the same order | | `public/activities/ghoul-rush/core/ghoul-dice.js` | Ghoul Rush's Lucky die rules (no imports: `ghoul.js` hands them `DICE_KIT`): `MAX_DICE` (9, the most one bonus or ride pays; dice in hand have no limit), `ROLL_MS`, `TUMBLE_MS`, `SAVED_TIME_MS`, `markRest` (the last solid ground Planny stood on), `reviveSpot`, `beginRoll` (called by `lose` when `round.dice > 0` and not `round.infinite`: the round holds in the phase `ask` and asks "Use a Lucky Die?", the event `diceAsk`), `askStep`, `steerAsk`, `answerAsk` (Yes spends one die and holds in the phase `roll`; No keeps every die, the event `diceKeep`, and lets the loss go ahead; a press inside `ASK_GUARD_MS` is ignored so the key held at the death cannot answer), , `rollDice` (one die at a time from advance's `random`, events `diceStart`, `diceRoll`, `diceFace`, `diceSaved`, `diceFail`; a six revives with the Garlic shield and `SAFE_MS`, and blows apart every monster in view in a room without a boss (`diceBlast`, kills with `how: "luck"`, points but no drops); no six hands the loss back to `takeLife`) | | `public/activities/ghoul-rush/core/ghoul-bonus.js` | Ghoul Rush's bonus rounds, the rules (imports only `MAX_DICE`; no random numbers): a room with `bonus: true` (the Runaway Cart; the Carnival's dark ride is meant to follow) gets `round.bonusRound = { hearts, max, dice, over, won, perf }` on entering it (null elsewhere; `round.bonus` is already the time bonus score). A life lost in it is a heart lost through the same `lose`/`takeLife` (so Garlic, the safe moment and `round.infinite` work as ever; no Lucky die is rolled for a heart); the last heart gone calls `endBonus(round, false)` from `respawn` (no dice, no game over, the run's lives untouched), and a finish alive calls `endBonus(round, true)` from `clearRoom` (`diceFor`: `BONUS_FLOOR` 3 plus up to 6 by hearts, clean obstacles, acts and a steady hand, added to `round.dice`, which has no limit). A room's pack notes its performance in `bonusRound.perf` (`total`, `hits`, `acts`, `goal`, `steady`); both ends hold the phase "clear" for the card (`CARD_MS`, `CARD_LOST_MS`) and set `bonusRound.result`. Events `bonusStart`, `bonusEnd`; `heartsText(b)` is the HUD pill | | `public/activities/ghoul-rush/core/ghoul-bonus-draw.js` | The bonus rounds' art (`bonusArt(d, die)`): `card` ("BONUS CLEARED! +N LUCKY DICE" with the dice tumbling in, or the short "BONUS LOST"), `react` (the intro banner, the end, the hearts-left float) and `tick` (a click for each die landed) | | `public/activities/ghoul-rush/core/ghoul-dice-draw.js` | The Lucky die's art (`diceArt(d)`: the small drop, the rolling die on a panel placed away from Planny, the `ask` panel ("Use a Lucky Die?" with YES and NO, the lit one gold), the sweeping "LUCKY-SAVE" word, and `react` for the dice events, which plays `ghoulLuckySave` once on the revive) | | `public/activities/ghoul-rush/story/ghoul-gameover-draw.js` | The lost end screen's "G A M E - O V E R" (`gameOverBanner(d)`, `dropAt`): nine letters dropping in with a stagger and one bounce, then bobbing on a sine wave under a slow pulse, red and bone with a dark shadow, drawn above the score panel and never on a win. `ghoul.js` keeps ticking the clock on the lost end screen (`view.overMs`) and plays the mechanical laugh track there: `ghoulLaughTrack`, `ghoulLaughTrack2` and `ghoulLaughTrack3` in `ghoul-sfx.js`, one second apiece (a tone may not pass 1.2 s). | | `public/activities/ghoul-rush/story/ghoul-intros.js` | The stage intro cards' words and colors: `INTROS` per stage id (`title`, `palette` {a, b, glow}, `kicker`, 3 or 4 `lines` of flavor text at most `MAX_LINE` characters, `boss`), `introFor(id)`. Always addressed to YOU. A test fails for a stage in `STAGES` with no card. | | `public/activities/ghoul-rush/story/ghoul-intro-draw.js` | The intro card's drawing (`introArt(d)`, `titleLayout`, `dropAt`): the title's letters dropping in and glowing, one themed flourish per stage (frost crystals, bunting, pickaxe sparks, leaves, candle flames, ...), the lines fading in, the boss and the pulsing "Press any move key or fire to enter". Drawn over the field while `round.phase === "intro"`. The phase itself lives in `ghoul-run.js` (`startIntro`, `stepIntro`, `takeIntro`, `INTRO_MIN_MS` 1.2 s: any fresh move key, fire or a click moves on after it, repeats never, and the card never moves on by itself); the tone is `ghoulStageIntro`. | | `public/activities/ghoul-rush/story/ghoul-boss-intros.js` | The boss intro cards' words: `BOSS_INTROS` per boss id (`name`, which must equal the boss's `name` in its pack's `bosses` table, an `epithet` of at most `MAX_EPITHET` characters and an optional `accent` color), `bossIntroFor(id)`. A test fails for a boss room whose boss has no entry. | | `public/activities/ghoul-rush/story/ghoul-bossintro-draw.js` | The boss intro card's drawing (`bossIntroArt(d)`): a "BOSS FIGHT" title whose letters slam in with a screen shake and a heartbeat pulse, the boss drawn from its own art (`BOSS_ART`, the way the stage pick does) at a big scale in a spotlight on the stage's palette, its name, the epithet and the pulsing "Press any move key or fire to start the fight"; a boss whose art throws falls back to a silhouette. Drawn over the field while `round.phase === "bossintro"`. The phase lives in `ghoul-run.js` (`startBossIntro`, run by `enter` on every boss room, and `onCard`; it shares `introMs`, `stepIntro`, `takeIntro` and `INTRO_MIN_MS` with the stage card, and a respawn never shows it); the tone is `ghoulBossIntro`. | | `public/activities/ghoul-rush/draw/ghoul-monsters-draw.js` | The generic monsters' art (`monsterArt(d)`, no imports; `ghoul-draw.js` hands it its helpers `ellipse`, `circle`, `line`, `rotate`, `turned`, `eye` and the colors): `drawZombie`, `drawZombieKin`, `drawHuntsman`, `drawCrawler`, `drawBat`, `drawGhost`, `drawSkeleton`, `drawGourdling`, `drawHound`, `drawSpider`, `drawWraith`, `drawSpitter` and the missiles `drawBoneShape` and `drawGlob`. Split from `ghoul-draw.js` to keep it under the 3,000-line cap | | `public/activities/snake-sfx.js` · `public/activities/flock-sfx.js` · `public/activities/golf-sfx.js` · `public/activities/trails-sfx.js` · `public/activities/bugs-sfx.js` · `public/activities/drive-sfx.js` · `public/activities/stack-sfx.js` · `public/activities/bumper-sfx.js` · `public/activities/rapids-sfx.js` · `public/activities/fuse-sfx.js` · `public/activities/hop-sfx.js` · `public/activities/bounce-sfx.js` · `public/activities/ghoul-rush/sfx/ghoul-sfx.js` | each game's own sound effects as data, `{ tones, hums }` in the shapes `tones.js` documents, every name prefixed with the game id (`driveEngine`, `ghoulMoan`), merged and frozen by `tones.js`; no imports, but for `ghoul-sfx.js`, which merges each Ghoul Rush stage's own `ghoul-sfx-.js` into its `tones`, `hums` and `music`, and `snake-sfx.js`, which merges `snake-music.js` as its `music`; `trails-sfx.js` and `flock-sfx.js` have `songs` instead of `music` |