README.md

metadata

title: Rift Chronicles 裂隙编年史
emoji: ⚔️
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 6.17.3
python_version: '3.12'
app_file: app.py
pinned: false
license: apache-2.0
short_description: AI-narrated Chinese fantasy RPG — code rules, model dreams
tags:
  - build-small-hackathon
  - thousand-token-wood
  - an-adventure-in-thousand-token-wood
  - off-brand
  - small-models
  - game
  - rpg
  - interactive-fiction
  - agent
  - qwen
  - track:wood
  - sponsor:modal
  - achievement:offgrid
  - achievement:offbrand
  - achievement:sharing
models:
  - Qwen/Qwen3-14B
  - Tongyi-MAI/Z-Image-Turbo

⚔️ 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

Role	Model	Params
Game master, NPCs & memory summaries	Qwen/Qwen3-14B	14B
Scene & portrait paintings	Tongyi-MAI/Z-Image-Turbo	6B

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. Create a hero (race + background), name them anything.
2. Tap a choice — or type anything (free input is fully supported; the referee decides what actually happens).
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 → — 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.