A web-based roguelike deckbuilder where an LLM forges every run's cards, enemies, events, hazards, and even your character, while a validation pipeline keeps it all playable and fair.
You climb a seven-floor branching map each level: the run always opens with a combat, three middle floors each offer a fork (fight / event / wayshrine; 8 distinct routes per map), then an elite, a guaranteed wayshrine, and the Collector boss. Before you start you pick a difficulty temper (Embers / Forge / Inferno) and a hero: the classic Forgeborn, or an AI-forged character, optionally from your own concept ("a venom-blade assassin"), with a name, story, and a one-of-a-kind starter deck. Combat is a deterministic Slay-the-Spire-style deckbuilder: play cards, spend energy, manage block and a full status roster (Vulnerable, Weak, Frail, Strength, Dexterity, Poison, Regen, Metallicize, Ritual, Thorns). The UI shows the real post-buff/debuff numbers, color-coded, no mental math, and a deck overlay is one click away. Enemies raise Block and can bundle several actions into one telegraphed turn (strike and brace). It's an endless run: clearing the boss lets you descend to a deeper, harder level; the run only ends when you fall, and every run is logged to a personal history on the dashboard. From level 2 the boss room becomes a dare: face the forged boss, or The Unmade, a curated superboss far above every generated band (two actions every turn, always attacking, and an innate Ritual that grows its Strength every single turn, a clock that punishes slow decks). Its defeat grants a wish: describe the card you want in your own words and the forge produces three Ancient-rarity interpretations at whatever costs fit (0-3), the highest power band in the game. Out-of-scope wishes are translated to real mechanics, never broken cards.
Five kinds of gameplay content are generated by an LLM, live, during the run, and no two runs are the same:
- Reward cards: after each victory, three brand-new cards (names, flavor, mechanical effects, and an illustration: the LLM picks from 16 motifs rendered as parametric SVG; backgrounds are type-coded, Rares get gilt ornamentation, and Ancients get the most). Card types have enforced identities: only Attacks deal damage, only Skills brew poison, and the persistent buffs (Strength / Metallicize / Ritual / Regen / Thorns) live exclusively on Powers, which may roll any cost, with cheap ones budgeted leaner. Cards you pick or rate ≥4★ enter a cross-run library the forge can re-offer from in future runs (same rarity slot only, marked with a ★).
- Enemies: the foes you fight (HP + telegraphed intent patterns, including defend/Block turns and compound moves), forged per run, down to a structured appearance the LLM picks: a humanoid or non-humanoid archetype (hooded / bestial / skeletal / orb / swarm / serpent / ooze / construct) + palette, rendered as a parametric, idle-animated sprite with per-foe procedural variation so no two generated foes look alike. Combat is juiced with floating damage numbers, hit sparks, screen-shake, and status pop-ups.
- Events: between-combat scenes in nine style archetypes (shrine, gamble, forge ritual, wounded traveler, cursed relic, respite, and three playable mini-games: a wheel of fortune, a shell game, and bone dice; outcomes resolved by a seeded server-side roll, never the client). Plain events offer two real trade-off choices plus a walk-away; consequences span HP swings, permanent blessings (Strength / Dexterity / Thorns / Metallicize), and card-forging bargains (upgrade, Exhaust changes, cull a card, duplicate a card) that let you pick which deck card they reshape. One mini-game per map is guaranteed, and the player never sees the same event (or even the same mini-game kind) twice in a row.
- Room modifiers: the elite and boss fights carry a generated hazard: opening tweaks or ongoing rules the engine enforces each turn (attack limits, energy squeeze, HP drain, a foe that ramps Strength). Tier-gated and capped so you're never locked out.
- Characters: the optional forged hero: one LLM call invents the name, story, and a 10-card starter deck of 3-5 unique designs, validated per card and per deck so it changes the flavor without changing the power level.
All of it comes from the LLM provider you point it at — OpenAI, Claude
(Anthropic), DeepSeek, or Triton AI (UCSD) — through one OpenAI-compatible
client (LLM_PROVIDER in .env; defaults to Triton / Claude Sonnet 4.6).
Generation alone is the easy part: an LLM will happily hand you a
1-cost card that deals 40 damage, or a 900-HP boss. The point of the project is the pipeline that makes generated content actually playable and
fair: every content type runs through the same generate → validate → repair/reject
→ log loop, and an eval dashboard shows exactly what the AI produced and how often it
had to be repaired or rejected.
See DEMO.md.
The project's thesis is "generation as the point": the interesting artifact is not the card game, it's the pipeline that turns raw LLM output into validated, balanced, evaluable gameplay. Four design decisions carry that:
-
Backend-authoritative state. FastAPI owns all game state (HP, deck, RNG, combat) and is the only caller of the LLM. The React frontend is a pure view layer that POSTs actions and renders responses. This is what makes evaluation honest: every generation passes through one chokepoint that logs it, so the dashboard numbers can't drift from what the player actually saw.
-
Structured effects, not free text. A card is not a blob of prose. It is a typed
Cardwith aneffects: list[Effect]field whosekindis drawn from a fixed 8-value whitelist (deal_damage,gain_block,draw,gain_energy,apply_status,gain_status,lose_hp,heal). The deterministic combat engine executes those effects directly. No LLM in the combat hot path. The LLM writes names, flavor, and combinations of pre-defined effects; it cannot author executable game logic. -
One shared generation pipeline, five content types. Cards, enemies, events (including mini-games), room modifiers, and characters all run through the same loop (
ai/_generation.py:run_generation_loop):build prompt (with grounded few-shot) → LLM → parse → validate → verdict, retrying with the rejection reason fed back into the prompt and falling back to curated content only after three failures. A deck-aware director biases card generation toward what the deck lacks (anti-flooding). Enemies, events, and modifiers are pre-generated in the background at run start (stashed in arun_assetstable) so there's no wait when you reach them. -
Data-driven balance, not vibes. "Is this AI content balanced?" is answered by comparing it to real Slay the Spire data, not by a hand-wave (see Evaluation). The player-chosen difficulty moves the validation bands themselves: hard raises the enemy HP/damage envelope and tightens the reward-card budget, easy does the reverse, so the AI balances to the chosen difficulty, not around it.
Every generated candidate, of any type, runs a three-stage validator before a player ever sees it:
- Schema check: Pydantic parses the LLM's JSON into the target model (Card / enemy spec / event / modifier). Wrong shape → reject.
- Mechanic whitelist: only allowed primitives may appear: cards use the 8 effect kinds + 10 statuses under a type discipline (damage is Attack-only, poison Skill-only, persistent buffs Power-only; violations reject with feedback so the retry fixes the type; cosmetic picks like a card's art motif are normalized, never a rejection reason); enemies use attack/defend/debuff/buff intents (defend Block capped to the tier's damage band; a turn may bundle 1-2 actions, with at most one attack); events use a fixed consequence set (HP/max-HP, permanent blessings capped at 1-3, and card mods: at most one card-target per choice, no contradictions, and same-axis opposites like "+6 Max HP, −3 Max HP" merged to the net as a repair); mini-games need 3-6 weighted outcomes including at least one prize and one sting; modifiers use opening effects + ongoing rules, tier-gated with at most one rule each. Hallucinated mechanics → reject.
- Budget check: cards must score within their
(rarity, cost)power band. The band is rarity-aware: a floor pushes Uncommon/Rare cards into the upper part of the band (so a boss reward is a real upgrade, not a weak card that merely cleared the ~0 floor), and a monotonic ceiling keeps a Rare from ever being budgeted below a Common of the same cost. Too-strong cards are clamped down, too-weak-for-their-rarity cards boosted up. Enemies must sit in their tier's HP/damage threat band (shifted by the chosen difficulty); events and modifiers within magnitude caps. Forged characters add a deck-level budget: copies sum to exactly 10, costs 0-2, enough attacks and Block, and total deck power within ±15% of the classic starter. Ancient wish cards band above the monotonic Rare ceiling (×1.6, floor at 65%): strong by design, but still bounded. Effect pricing is curated where calibration is blind: healing restores persistent HP (block lasts one turn), so heal carries an enforced minimum weight of 2.4× block; before that fix the validator happily boosted a wish card to "Heal 44".
Each candidate gets one of three verdicts, all logged:
- accepted: in band, used as-is.
- repaired: numerically out of band but close; the offending amount is clamped into range and the diff recorded.
- rejected: structurally broken or far out of band. Triggers a retry (up to 3) with the reason fed back into the prompt; persistent failure → curated fallback.
Measured from the eval log (backend/rogueforge.db): 1,226 generations, 2,658
candidates across all five content types:
| Content type | Candidates | Accepted | Repaired | Rejected |
|---|---|---|---|---|
| Cards | 2,165 | 86% | 9% | 5% |
| Enemies | 231 | 90% | 8% | 2% |
| Room modifiers | 130 | 77% | 20% | 3% |
| Events | 125 | 96% | 0% | 4% |
| Characters | 7 | 0% | 100% | 0% |
| All | 2,658 | 86% | 9% | 5% |
(Characters read oddly at a glance: every forged deck so far had at least one card clamped into the Basic band, which marks the whole character "repaired." That's the per-deck budget doing its job, not failures.)
So across everything the AI produced, ~95% was served (accepted as-is or
rescued by an in-band clamp) and only ~5% thrown away. Cards, the hardest budget
to hit (tight (rarity, cost) bands), are where most repairs and rejections
land. The eval log also doubles as a debugging tool: it's what revealed
that every AI mini-game was once being schema-rejected over a single required
field.
The eval dashboard (/eval/* endpoints → frontend/src/pages/Dashboard.tsx,
reachable from the corner nav, auto-refreshing every 5 s) reads the log and shows:
total candidates & generation events, accept/repair/reject rates as a stacked
bar, a 16-bin power-score histogram color-coded by verdict, a per-content-type
breakdown (card / enemy / event / room_modifier / character), a Recent Repairs
panel that shows the exact clamp applied (e.g. deal_damage 14→13), recent
rejections with reasons, recent generation events with per-candidate verdict
pills and provenance chips (which event style was requested; which reward slot
came from the library), the Card Library (your cross-run collection with
origins and ratings), Runs by Temper (difficulty mix), player-rating stats,
Run History, and average latency + token usage per event.
Three kinds of data drive the project:
- Grounding / calibration corpora: three datasets parsed from the game by
nkhoit/spire-archiveand vendored underbackend/data/:sts1_cards.json(360 cards, 75 Ironclad),sts1_monsters.json(68 monsters),sts1_events.json(52 events). They serve as few-shot examples in the generation prompts (filtered to match the request) and to calibrate the card power budget:backend/calibrate.pygrid-searches scoring coefficients until ≥ 80 % of the real Ironclad cards land inside their own(rarity, cost)band (mean ± 2σ), writingbackend/data/balance_coefficients.json. The enemy threat budget is likewise anchored on the real monster HP/damage distribution. So "balanced" is defined empirically: generated content scores like real content of the same kind and tier. - Eval / outcome data: every generation (card, enemy, event, modifier,
character) is appended to
backend/rogueforge.db(SQLite:generation_events+candidate_records, pluscard_ratings,card_library,run_history, andrun_assets) and mirrored tobackend/rogueforge_events.jsonlforgrep. This is the empirical record the dashboard summarizes: what the AI produced and how the validator judged it. - Automated test data: 265 backend tests (
backend/tests/) cover the engine, every validator (card / enemy / event / mini-game / modifier / character), balance scoring, the director, the generators, the branching map, difficulty scaling, and the card library. End-to-end tests drive full runs against a mocked LLM returning scripted responses (valid, invalid, and fallback-triggering), so the whole pipeline is verified hermetically without hitting any provider. One opt-in live smoke test (pytest -m live) confirms the real endpoint.
Five AI-generated content types (cards, enemies, events, room modifiers, characters), each behind the same validate/repair/reject pipeline, plus a deck-aware run director, human-rating capture, and an eval dashboard.
- Branching route map: forking floors, a path-choose screen, a guaranteed pre-boss wayshrine.
- Difficulty selector (Embers / Forge / Inferno) that moves the AI balance bands themselves.
- Cross-run card library: loved (≥4★) cards return in future runs, rarity-matched.
- Card illustrations: LLM-chosen motifs, type-coded backgrounds, rarity-tiered ornamentation.
- AI-forged characters: name, story, and a unique starter deck, optionally from the player's own concept, under a deck-level power budget.
- Event styles + mini-games: nine archetypes including three playable gambles (wheel / cups / dice) with server-side seeded outcomes; richer consequences (thorns/metallicize blessings, cull/duplicate a card).
- The ultimate boss: from level 2, an opt-in superboss whose defeat grants a natural-language wish forged into Ancient-rarity cards.
- Endless mode: descend into deeper levels with scaled foes; runs logged to a history.
- Deeper combat: the full 10-status roster, enemy Block, compound enemy turns, and a combat UI that shows real post-buff/debuff damage and block.
- Rarity that means something: a rarity-aware power floor + monotonic ceiling so higher-rarity rewards are genuinely stronger; Innate cards; card type discipline (damage on Attacks, poison on Skills, persistent buffs on Powers).
265 backend tests pass; live provider smoke passes.
backend/: FastAPI + Pydantic + SQLAlchemy. Owns all game state and all LLM calls.rogueforge/game/: pure-data models, deterministic combat engine (status decay, enemy strength), curated enemy roster, events (including the curated mini-games + the weighted-roll resolver), room modifiers.rogueforge/ai/:_generation.py(the shared generate→validate→retry→fallback loop) plus per-content prompt/validator/generator triples for cards, enemies, events, modifiers, and characters; balance scoring; the deck-aware director.rogueforge/eval/: generation event logger (SQLite + JSONL tail).rogueforge/api/: FastAPI routes for runs (withBackgroundTasksso enemy/ event/modifier generation never blocks the player) and eval endpoints, including the branching-map path choice, mini-game play, and the cross-run card library.data/: vendored corpora (sts1_cards.json,sts1_monsters.json,sts1_events.json) +balance_coefficients.json(regenerable viamake calibrate).tests/: 265 unit + integration tests, plus an opt-in live provider smoke (pytest -m live).
frontend/: React 19 + TypeScript + Tailwind 3 + React Query. Pure view layer.src/pages/Run.tsx: title (difficulty + character forge) → combat → reward → path-choose → event/rest → card-select → descend → game-over / run-complete state machine, with the death-linger killing-blow presentation.src/pages/Dashboard.tsx: eval dashboard.src/components/: Card (combat-effective numbers + parametric art banner), Combat (room-modifier banner, attack-limit lockout, hit FX), RewardScreen (star rating + skip + library marker), EventScreen (choices + the three animated mini-games), CardSelectScreen, RestScreen, RunMap (forked floors as columns, walked path lit), DeckOverlay (🂠 Deck in the nav), EnemySprite, PlayerPanel (character name + temper badge), EnemyPanel.src/lib/combatMath.ts: mirrors the engine's damage/block formulas so the UI shows real post-buff/debuff numbers.
DEMO.md: build-from-source instructions, gameplay flow, troubleshooting, full API endpoint table.
- Slay the Spire card data:
nkhoit/spire-archive(parsed from the original game JAR). - LLM: pluggable via
LLM_PROVIDER— OpenAI, Claude (Anthropic), DeepSeek, or Triton AI (UCSD). Defaults to Triton, modelclaude-sonnet-4-6.