Dungeon Crawler

A top-down, pixel-art dungeon crawler built with PixiJS and TypeScript. Procedurally generated rooms, real-time melee/ranged combat, fog of war, a locked boss room, a hidden button-puzzle treasure room — and a GameMaster: a mischievous, omnipotent god (random today, AI-driven tomorrow) that demands worship, blesses the faithful, and smites the defiant with live events. Pray to it by holding E.

Art: the 0x72 DungeonTileset II.

---

Running it

npm install
npm run dev            # start the Vite dev server (hot reload)
npm run build          # type-check (tsc -b) + production build to dist/
npm run lint           # eslint
npm run preview        # serve the production build
npm run test:deepgram  # verify the Deepgram (voice) token works
npm run test:ai        # run the Watcher→Hand LLM pipeline on sample lines

Open the printed localhost URL.

Voice + AI god (optional). To let the god hear and react to you, add keys to a git-ignored .env at the repo root:

DEEPGRAM_TOKEN=your_deepgram_key   # speech-to-text
OPENAI_TOKEN=sk-...                # the god's brain
OPENAI_MODEL=gpt-4o-mini           # optional, this is the default (cheap)

Verify them with npm run test:deepgram and npm run test:ai, restart the dev server, then in the browser console: gm.awaken() and press V to talk. (Tokens are inlined into the client build — fine for a local sandbox; use short-lived keys / a server for production. See ai/.)

To skip the console each run, flip the startup toggles in src/game/config.ts → GM:

export const GM = {
  autoAwaken: false,  // wake the OpenAI brain on boot (reacts to speech)
  autoListen: false,  // arm the mic — starts on your first click/keypress
  debugAI:    false,  // log every Watcher/Hand decision to the console
};

Controls

Input	Action
WASD / Arrow keys	Move (also sets aim/facing)
Space	Attack (hold to charge a bow)
E (hold)	Pray to the god — raises your favor
V	Toggle voice transcription (Deepgram mic; records the session)
1–9, 0	Select weapon slot
+ / -	Cycle to next / previous weapon
M	Reveal all fog of war
P	Toggle passive mode (enemies ignore you)
L	Toggle invincibility
Space (on death)	Restart

Clear every normal enemy to seal and reveal the boss corridor; find and press the red and blue floor buttons to open the secret treasure room.

---

Architecture

The codebase is a small, decoupled engine. Game rules live in systems, not in the loop, so new behaviour is added by writing a new system rather than editing the core.

src/
  core/        Engine, GameLoop, shared types (System, UpdateContext)
  events/      Type-safe EventBus (pub/sub)
  world/       World (entities + collision), Entity, Collision, WorldMap
  level/       Procedural LevelGenerator, room templates, SeededRandom
  render/      Renderer (Pixi app), Camera, SpriteAnimator
  input/       Keyboard + InputManager (abstract InputState)
  assets/      Tileset loader, grouping, animation slicing
  game/
    Game.ts          Composition root — wires everything together
    config.ts        Tuning constants (player, enemies, weapons, world)
    Player.ts        The player entity
    enemies/         Enemy base class + one class per enemy type
    weapons/         Weapon definitions, projectiles, weapon view
    items/           Coins, hearts, chest, buttons, doors, secret wall
    systems/         Movement, combat, enemy AI, fog, doors, drops, death…
    gm/              GameMaster — the "god" of live random / AI-driven events
      GameMaster.ts  System orchestrator: favor, prayer, commands, hazards, API
      actions.ts     Action vocabulary (ACTIONS) + self-describing schema
      effects.ts     Ticking hazards (bullets, bombs, lightning, spikes, auras…)
      library.ts     The built-in event deck (LIBRARY)
      command.ts     Command-string shorthand parser
      types.ts       Event / action / tone types
      index.ts       window.gm API + exposeGameMaster()

Core ideas:

• Engine loop — each frame the Engine builds an UpdateContext (dt, input, world, events) and runs every registered System, then lets each entity update + sync its view.
• EventBus — systems communicate through typed events (enemy:killed, boss:defeated, coin:collected, gm:cast, …) instead of referencing each other directly.
• Entities vs views — an entity owns its logical position; the engine syncs that onto its Pixi view every frame.

---

GameMaster (the god of live events)

The GameMaster ("GM") is a mischievous, omnipotent god that injects events into the running game — blessings, punishments, and chaos. It's designed so an external director (a developer at the console today, an LLM "god" tomorrow) can shape the experience at runtime, making each run unpredictable.

The god wants to be worshipped. The player prays by holding E, which raises their favor. The god issues commands ("slay three", "be still", "come to my altar"); obey before the deadline to be rewarded, defy it to be smitten by lightning. Its judge action rewards the faithful and punishes the defiant based on current favor.

It is just another System (so it ticks with everything else) and owns all transient hazards: enemy bullets, bombs, lightning, spikes, timed buffs, companions, divine commands, screen shake and the announcement banner.

Favor & prayer

• Favor ranges -100..100 (starts at 0). Holding E raises it; failing a command lowers it (and calls down a bolt).
• gm.favor() reads it; gm.onPray(cb) is the hook a future AI god reacts to — it fires repeatedly while the player prays and once when they release.
• Typed events are also emitted on the bus: gm:pray, gm:favor, gm:command, gm:betray, gm:cast.

Divine commands

{ type: 'command', kind, need, time } makes the god demand something with an on-screen prompt + countdown. Kinds:

kind	the player must…	need
pray	hold E for N seconds	seconds (default 3)
kill	slay N enemies	kills (default 3)
still	not move for N seconds	seconds (default 3)
reach	walk to the glowing altar marker	(n/a)

Success → favor up + heal + coins. Failure (deadline) → favor down + a tracked lightning bolt.

Betrayal

Companions are hittable by the player. Strike your own ally and it counts as betrayal: gm:betray fires, the wounded ally abandons you, and your favor drops. Striking down a guardian Angel is the gravest sin — favor crashes to the floor (-100) and the god answers with a tracked bolt. Subscribe with gm.onBetray(cb).

Event format

An event is plain, serialisable data: an ordered list of actions. Each action is a small, parameterised command. This declarative shape is easy to validate, log, compose and — crucially — generate with an AI.

{
  "id": "demonic_onslaught",
  "name": "Demonic Onslaught",   // shown on the banner
  "tone": "bad",                 // good | bad | neutral | chaos (banner colour)
  "actions": [
    { "type": "shake", "intensity": 8, "duration": 0.6 },
    { "type": "bullet_hell", "delay": 0.4, "at": "far_player",
      "count": 12, "pattern": "spiral", "damage": 1 }
  ]
}

• delay (seconds) staggers an action after the event is cast.
• at is the common position param (see below).
• All other fields are action-specific and read defensively with defaults, so partial/loose input never throws.

Positions (at): "player", "near_player", "far_player", "random", or explicit { "x": 120, "y": 200 }.

Driving it: the window.gm API

Everything funnels through a single live instance exposed on window.gm. Open the browser console while playing:

gm.help()                         // print a cheat-sheet
gm.random()                       // cast a weighted-random event from the deck
gm.list()                         // [{ id, name, tone }] of library events
gm.cast('bullet_hell')            // cast a library event by id
gm.cast({ name: 'Doom', tone: 'bad', actions: [          // inline JSON event
  { type: 'bomb', at: 'player', fuse: 2 },
  { type: 'bullet_hell', delay: 0.5, count: 14, pattern: 'spiral' }
]})
gm.run('horde 12; shake 9 0.7')   // command-string shorthand
gm.actions()                      // full action schema + params (for AIs)
gm.enemies()                      // spawnable enemy names
gm.favor()                        // devotion (-100..100)
gm.snapshot()                     // read game state (favor, mood, hp, transcript…)
gm.onPray(p => console.log(p))    // react to prayer (AI hook)
gm.onBetray(p => console.log(p))  // react to attacking an ally
gm.speak('Kneel.')                // the god speaks (executor AI's voice)
gm.hear('praise be to you')       // feed player speech in (Deepgram STT hook)
gm.mood(); gm.rollMood()          // read / randomise temperament
gm.connectWebSocket('ws://…')     // wire an external AI orchestrator

gm.cast(input) accepts any of: a library id, a full event object, a single action object, an array of actions, a JSON string of any of those, or a command-string. It returns false if the input can't be parsed.

Command-string shorthand

A terser format for manual use; it compiles to the same action directives. Statements are separated by ; or newlines: verb [positional…] [key=value…].

bomb fuse=1.5 radius=48
horde 12; shake 9 0.7
spawn BigDemon 3 hp=4 at=far_player
elite Ogre hp=10
spawn Imp x=120 y=200
companion Skelet duration=0      # a permanent pet
meteors count=8 spread=90
say "A giant blocks your path" tone=bad

x= / y= fold into an at: {x, y} position. Aliases exist: bullethell→bullet_hell, coins→loot, swarm→horde, champion/boss→elite, quake→shake, bolt/zap→lightning, pet/ally→companion, blink/tp→teleport, trial/demand/decree→command, meteor→meteors.

Action reference

Call gm.actions() for the authoritative, self-describing schema (types + defaults). Summary:

Action	Tone	What it does
spawn	bad	Spawn N of an enemy (enemy, count, hp/dmg/speed multipliers, scale, weapon)
horde	bad	Swarm of small fast enemies around you (count, speed)
elite	bad	One buffed, oversized champion (enemy, hp, dmg, scale)
bomb	bad	Fused bomb; AoE on detonation. Drops where it lands and stays (run!); pass stick: true for an unavoidable one (fuse, radius, damage, hurtsEnemies)
bullet_hell	bad	A stationary caster sprays bullet waves — kill it to stop the storm (caster, duration, rate, count, speed, damage, pattern, spin)
lightning	bad	Telegraphed divine bolt; track: true follows the player (at, damage, radius)
command	chaos	The god demands something — obey or be punished (kind, need, time, prompt)
judge	chaos	Reward the faithful / smite the defiant by favor (threshold, reward, punish)
spikes	bad	A patch of damaging floor spikes — step off them (size, duration, damage)
meteors	bad	Rain explosions across an area over time (count, spread, interval, radius, damage)
enrage	bad	Permanently buff every living enemy (speed, dmg)
slow	bad	Temporary movement-speed penalty (factor, duration)
damage	bad	Directly hurt the player (amount)
companion	good	Summon ally(ies) that follow you and fight hostiles (enemy, count, duration, dmg)
heal	good	Restore health (amount, or full: true)
shield	good	Grant temporary (yellow) shield hearts (amount)
loot	good	Scatter collectable coins (count)
hearts	good	Drop heart pickups (count)
haste	good	Temporary speed boost (factor, duration)
smite	good	Damage every enemy at once (damage)
explode	neutral	Instant AoE blast + flash + shake (radius, damage, hurtsEnemies, hurtsPlayer)
teleport	neutral	Blink the player to another location (at)
shake	neutral	Camera shake (intensity, duration)
say	neutral	Show a banner title-card (text, tone)
speak	chaos	The god's voice — bottom-screen dialogue (text, hold)
mood	neutral	Set/nudge/roll the god's temperament (kindness, chaos, sensitivity, nudge, roll)

Bullet patterns: ring, spiral, aimed, random.

Companions are friendly summons: they are not added to the hostile list, so your weapons and enemy AI ignore them; they chase and hit nearby enemies, otherwise they heel to you. duration: 0 makes a pet permanent.

Built-in event deck

gm.random() draws (weighted) from gm/library.ts. Current events:

• Hostile: bullet_hell, crossfire, bomb_drop, hot_potato, minefield, elite, horde, ambush, mimic, molasses, enrage, spike_trap
• Helpful: blessing, windfall, fairy_gift, haste, smite, companion, reinforcements
• Wild: earthquake, pandemonium, meteor_shower, blink, gauntlet
• The god speaks: commandment, trial_of_blood, be_still, pilgrimage (commands); judgement, wrath, judgement_day, the_faithless, divine_gift, guardian_angel

Letting an AI run it (the god): how & when to send updates

The whole integration is one function: window.gm.cast(json). The AI's job is to decide what JSON to send and when; the game does the rest. There are two halves — observe (read state) and act (cast events).

Observe — give the model context to decide:

• gm.snapshot() — a one-shot read of { favor, praying, player{hp,…}, enemies, companions, kills, command }.
• Event subscriptions (push): gm.onPray(cb), gm.onBetray(cb), and the bus events gm:favor, gm:command, gm:cast. You can also tap gameplay events (enemy:killed, player:died, boss:defeated, coin:collected).

Act — send an event whenever the god should intervene. Two common cadences:

1. Event-driven (reactive). Best fit for the god persona — react to what the player does:

   gm.onPray(({ favor }) => { if (favor > 60) gm.cast('divine_gift'); });
   gm.onBetray(() => gm.cast('wrath'));
   

2. Timed (a "director" loop). Every N seconds, snapshot → ask the model → cast its reply:

   setInterval(async () => {
     const reply = await askLLM(gm.snapshot(), gm.actions());
     gm.cast(reply);                 // a library id, a JSON event, or a command-string
   }, 12_000);
   

Where the AI runs. gm lives on window, so:

• In-page model / script: call gm.cast(...) directly.
• Server-side model: stream its output to the browser (WebSocket/SSE/fetch) and call gm.cast(payload) on each message. cast accepts a JSON string, so you can forward the model's raw text verbatim.

To stay in character, ground the model once with gm.actions() (vocabulary + params) and gm.enemies() (valid names), then let it compose primitives: demand prayer with a command, reward the faithful with divine_gift, and bury the defiant under a bullet-hell + tracked lightning — all without new code.

Voice → god: the multi-AI pipeline

The intended end state is a three-AI pipeline that lets the god react to what players actually say. Full design, wire protocol, and system prompts live in ai/; in brief:

player voice ─▶ (1) Deepgram STT ─▶ gm.hear(text)
                                       │ emits gm:transcript (in snapshot too)
                                       ▼
        (2) "The Watcher"  — judge/filter/mood: react? speak? intent?  (may ignore)
                                       │ natural-language intent
                                       ▼
        (3) "The Hand"     — executor: intent → gm.cast(JSON) / gm.speak / gm.run

The whole pipeline is implemented and runnable:

• The brain (OpenAI): gm.awaken() starts the in-browser Watcher→Hand loop — it reads gm:transcript + gm.snapshot(), decides whether/how to react on a cheap model (OPENAI_MODEL, default gpt-4o-mini), and applies the result (speak / mood / cast). gm.sleep() stops it. Pass gm.awaken({ debug: true }) (or call gm.debug(true)) to log every AI decision — the Watcher's react/reason/intent/mood and the Hand's cast — to the console. Try the models headless with npm run test:ai. Implementation: src/game/gm/godbrain.ts.
• STT (Deepgram): press V (or gm.listen()) to stream the mic to Deepgram; finals are fed into gm.hear automatically. gm.saveSession() downloads the recorded transcript + audio. Token comes from DEEPGRAM_TOKEN in .env; verify it with npm run test:deepgram. Implementation: src/game/gm/deepgram.ts.
• STT in (manual): gm.hear(text, speaker?) buffers speech into gm.snapshot() and emits gm:transcript.
• Mood: gm.mood() / setMood / nudgeMood / rollMood() — kindness, chaos, sensitivity (0..1) bias the Watcher's choices; rollMood() is the JS "dice".
• Voice out: gm.speak(text) is the god's on-screen voice (distinct from the say banner).
• Bridge: gm.connect(transport) / gm.connectWebSocket(url) stream a curated event feed + snapshots out and accept cast / speak / mood / exec / snapshot back. See the protocol + reference orchestrator in ai/README.md.
• Escape hatch: gm.exec(code) runs raw JS with gm in scope (sandbox-only; prefer structured commands).

Why split the brain in two? The Watcher decides whether to react (most chatter is ignored — gated by sensitivity) and sets the vibe; the Hand is a strict, schema-bound translator that only emits valid commands. Each stays focused and easy to validate.

Extending it

• New action: add a handler to ACTIONS in gm/actions.ts and a matching entry in ACTION_SPECS (so it shows up in gm.actions()).
• New event: add a GameEventDef to LIBRARY in gm/library.ts.
• New hazard: add an ActiveEffect in gm/effects.ts (it ticks each frame and is removed when update() returns false).

The GM shares the live enemies[] array (so AI/combat/collision pick up spawns automatically) and routes kills through CombatSystem.killEnemy (so drops and events fire exactly once). Player invincibility (L) still blocks bomb/bullet damage.