chronicle-forge 0.4.1

A history-creation RPG / reincarnation roguelite / AI-assisted world simulation.

Chronicle Forge

A history-creation RPG / reincarnation roguelite / AI-assisted world simulation.

You are the world's only reincarnator. When you die you reincarnate, but the world keeps running: NPCs, factions, and history continue. Your goal is not to save the world — it is to intervene in history and witness how your choices shape the future. The core experience is the traceable causal link between what you did and the history that resulted: "my actions created this history."

The world lives for a fixed span (200 years in production, 40 in dev/CI). On reaching the limit the game produces a Chronicle and an Ending classification.

Play now — one line, nothing to install

uvx chronicle-forge play --seed 42

That's the interactive game: pick a choice each season, die, reincarnate, and watch the history you caused unfold. (No uv? Then pipx install chronicle-forge or pip install chronicle-forge, and run chronicle-forge play --seed 42.)

No API key is required — the simulation is rules-only and fully deterministic by default. The optional AI narration (pip install "chronicle-forge[ai]") only adds prose; it never changes world state.

Quickstart — the one-way path

# 1) generate & witness a full world, deterministically, and save it
#    (drop --auto to make the choices yourself)
chronicle-forge play --seed 42 --auto --save run.recipe

# 2) explore the history your world produced (the P10–P14 read-model lenses)
chronicle-forge explore run.recipe                 # human-readable Markdown
chronicle-forge explore run.recipe --format json   # the stable read-model JSON

# 3) share it — a recipe replays byte-for-byte for anyone
chronicle-forge share run.recipe --export run.md
chronicle-forge play --replay run.recipe           # reproduces the exact transcript

The recipe is the save: a seed plus the ordered inputs. Because the engine is byte-deterministic, a recipe reconstructs its world (and transcript) exactly, on any machine, forever — that is the basis of both replay and sharing.

Example world (seed 42) — see it in 5 minutes

A complete, reproducible world generated by simulate_world(42) — rules-only, no AI:

Lives	Events	Heritage	Ending
3	77	8	Theocratic Age

A warrior's life seeds a school of thought; a merchant's life turns it into an institution; a priest's life carries it to a faith — and the world ends in a Theocratic Age you can trace, event by event, back to the very first life.

Open the demo bundle → docs/examples/seed42/ — start with story.md (each life traced Life → Seeds → Events → Heritage → Ending), then chronicle.md ("Why this Ending"), heritage.md, and the causal.dot graph.

Regenerate the demo bundle anytime:

python -m chronicle_forge.reporting 42

Architecture

Rules own truth, AI owns prose — state transitions are deterministic; the LLM only narrates and makes a few bounded decisions. The layers, from the frozen core outward:

• Engine — deterministic world generation, the causal-link core, the micro loop (a life) and macro loop (death → time-skip → history → reincarnation), all reproducible from the seed.
• Persistence — a run is a Recipe (seed + inputs); version-gated replay reconstructs the world byte-for-byte.
• Read-model lenses (P10–P14) — id-free, structured, hashable projections of a finished world: Observatory, WorldView, Narrative, Character, and Timeline.
• Application Layer (chronicle_forge.app, P15) — the single integration boundary that composes the above into play → save → explore → share.
• CLI (chronicle-forge) — a thin wrapper over the Application Layer; it parses arguments and renders output, and holds no game logic.

The full, design-locked specification lives in docs/design.md; the roadmap to v1.0 is in docs/design_release_roadmap.md.

Determinism

A seed + recipe reproduces a world — and its transcript — byte-for-byte. Everything non-deterministic (AI prose, when enabled) is a non-canonical side-channel: it is never recorded into a save and never participates in replay.

Development

pip install -e ".[dev]"   # editable install with pytest + black
pytest                    # runs the suite, including the frozen golden assertions
black src tests           # format

Copy .env.example to .env for the (optional) AI call sites; the core simulation runs rules-only without any API key.

License

MIT — see LICENSE.