build-small-hackathon/rift-chronicles

⚔️ Rift Chronicles · 裂隙编年史

An endless fantasy RPG where the game master is a small model — but the dice never lie.

A full text-adventure RPG (PWA, installable on your phone): real combat, inventory, quests, gold, levelling — and every scene, choice, NPC and plot twist is written live by a small model. Remove the model and there is no game. Remove the code and there are no rules.

🎲 The core trick: code rules, model dreams

LLM game masters cheat: they forget your HP, invent gold, kill bosses with a typo. Rift Chronicles splits the job:

• —The model narrates — it returns strict JSON: narrative, choices, and proposed state_ops (damage, loot, quests, new NPCs...).
• —The code referees — every op is validated and clamped against the real game state (enemy stats are budgeted by player level; gold can't go negative; dead NPCs stay dead). Invalid output is bounced back to the model for self-correction.

So the story is infinite, but the game is fair.

🐜 Small models doing a big model's job

Total parameters are 14B + 6B = 20B, under the 32B cap.

Inference is self-hosted on a Modal vLLM endpoint (the hackathon's Modal credits at work), OpenAI-compatible, streamed end-to-end. The protocol still carries an importance tier per NPC (passer-by / key character), ready to fan out across model sizes. If image generation is ever unavailable, the game falls back to fully procedural canvas paintings — it degrades, never breaks.

📖 Every playthrough becomes a novel

Open the Tale panel and the bard (same 14B model) rewrites your raw adventure log into polished third-person prose, chapter by chapter — play the game, write a book. Copy it, or publish it to the community Tale Library, where everyone can read each other's adventures with Liya. The library itself is a public Hugging Face Dataset: community fiction, stored as a dataset, written by small models and the players together.

🎨 Off-Brand

The entire frontend is a hand-rolled Preact PWA (parchment UI, typewriter streaming, IndexedDB saves, offline shell) served through gr.Server — zero default Gradio UI.

🕹️ How to play

1. 1.Create a hero (race + background), name them anything.
2. 2.Tap a choice — or type anything (free input is fully supported; the referee decides what actually happens).
3. 3.Fight, loot, talk to NPCs (each has persistent memory & relationship).

Fully bilingual: the Space defaults to English — narrative, choices, items and combat all generated in English. 中文玩家可在建档页或设置中一键切回中文。

📺 Demo & links

• —🎬 Demo video: watch (1:15)
• —📣 Social post: on X
• —📜 [Read a full agent trace of one real session →](./TRACE.md) — context assembly, raw model JSON, validation verdicts, reducer effects, and the bard turning it all into a chapter
• —🧠 Architecture write-up: see repo README.md

Built solo (with Claude Code) for the Build Small Hackathon 2026, track: 🍄 An Adventure in Thousand Token Wood.