Files
plan2code/.agents-docs/AGENTS-architecture-ghoul-core.md

19 KiB

Architecture: Ghoul Rush core

Part of AGENTS.md and the Architecture index: 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; Ghoul Rush is split over core, stages and rides.

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/<stage>/ and rides/<ride>/ (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-<stage>.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