README.md

---
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](https://huggingface.co/Qwen/Qwen3-14B) | 14B |
| Scene & portrait paintings | [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/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](https://huggingface.co/datasets/Zhenzewu/rift-chronicles-tales):
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)](https://huggingface.co/spaces/build-small-hackathon/rift-chronicles/resolve/main/demo.mp4)
- 📣 Social post: [on X](https://x.com/chkehfjwjhc/status/2065155866458763756)
- 📜 **[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.*