| Decision | Choice | Why (for a first game) |
|---|---|---|
| Engine | Godot 4.7 (latest stable) | Free and open source (MIT), no royalties, ~150 MB download, excellent 2D + UI tools, built-in TileMapLayer for a tactical grid, exports to Windows/macOS/Linux/web/Steam Deck. |
| Game code | GDScript | Python-like, built into the editor, no compile step, the largest pool of beginner tutorials for Godot. |
| Narrative content | JSON files + a validator | Godot parses JSON natively. Nothing to install. The schema is ours, so it fits exactly our needs: flags, d20 checks, fail-forward, combat hand-off. |
| Tooling | Python 3 (stdlib only) — tools/story.py |
Validate, play in the terminal, fuzz-test and generate the Variable Tracker before you build any UI. |
| Option | Verdict |
|---|---|
| Unity (C#) | Powerful, but heavier, slower iteration and more boilerplate for a 2D narrative game. Good if you already know C#. |
| Ren’Py (Python) | Best-in-class for pure visual novels, but tactical grid combat would be a fight against the engine. |
| Ink / Yarn Spinner (narrative middleware) | Wonderful for writers. In Godot both integrations lean on C#/.NET, which adds setup pain to a first project. Keep the door open: if JSON authoring gets tedious, write an Ink → our-JSON compiler later. The engine never has to change, because it only reads the schema. |
| Dialogic 2 (Godot plugin) | Nice visual-novel editor, but its own state model would compete with our flag registry and dice rules. |
The engine is a player for story data. It doesn’t know who Aria is or what the Crown is.
┌──────────────────────── CONTENT (data — writers edit) ───────────────────────┐
│ content/flags.json the Variable Tracker: every flag, type, default │
│ content/rules.json dice, skills, romance & jealousy numbers │
│ content/characters.json speakers, names, colours │
│ content/story/**.json scenes → nodes → text / choices / checks / effects │
│ content/encounters/*.json fights (units, spawns, conditions) │
│ content/units.json monsters, villains, allies (hp, defense, damage) │
└──────────────────────────────────┬────────────────────────────────────────────┘
│ read at startup
┌──────────────────────── ENGINE (code — rarely changes) ──────────────────────┐
│ autoload/game_state.gd flags, save slots, notices, XP → level-ups, │
│ HP cap, jealousy │
│ autoload/dice.gd d20, advantage, dice notation (2d6+1) │
│ autoload/skirmish.gd interim turn-based combat │
│ autoload/story_engine.gd graph walker, checks, effects, hooks, │
│ Death's Door / level-up interrupts │
└──────────────────────────────────┬────────────────────────────────────────────┘
│ signals (node_entered, check_resolved, combat_requested)
┌──────────────────────── PRESENTATION (code + art — swap freely) ─────────────┐
│ ui/story_view.gd visual-novel screen, HUD, typewriter, choices │
│ ui/dice_overlay.gd the drawn, tumbling d20 (throw, land, maths, crits) │
│ ui/game_menu.gd title screen, pause menu, save/load slot screens │
│ ui/… atmosphere, portraits, transitions, toasts, sound │
│ combat/ (to build) top-down tactical grid │
│ assets/ portraits, backgrounds, sounds (fonts optional) │
└──────────────────────────────────────────────────────────────────────────────┘
Rules that keep it clean
if aria ... in GDScript. If you need new behaviour, add a generic feature (a new node key, a new @hook) and use it from data.StoryEngine.choose(), never GameState.set_flag().flags.json. Undeclared flags are errors in both the validator and the game.tools/story.py implement the same rules. Change both together.aethelgard/
├── README.md, CLAUDE.md, .gitignore, .gitattributes, .editorconfig
├── docs/
│ ├── VARIABLE_TRACKER.md ← generated: every flag + where it is set/read
│ ├── narrative/ ← the Narrative Bible (premise, acts, companions, sample scene)
│ └── design/ ← mechanics, schema, this file
├── tools/
│ └── story.py ← validate · tracker · play · fuzz · script
└── game/ ← THE GODOT PROJECT (open game/project.godot)
├── project.godot
├── content/ ← all narrative data (see above)
├── scenes/main.tscn ← boots the story view
├── tests/smoke_test.tscn ← headless auto-player (run after any .gd change)
├── tests/ui_smoke_test.tscn ← clicks through the real screen (run after any ui/*.gd change)
└── src/
├── autoload/ ← GameState, Dice, Skirmish, StoryEngine (always loaded)
├── ui/ ← story_view.gd + its pieces (dice, menus, sound…)
└── combat/ ← tactical combat (to build — see README there)
Why is content/ inside game/? Godot can only load files that live inside its project folder (res://).
Saves are JSON in Godot’s user:// folder (on macOS: ~/Library/Application Support/Godot/app_userdata/Aethelgard- The Shattered Crown/):
autosave.json (written when a new chapter begins), savegame.json (the quicksave, F5/F9) and save_slot_1.json … save_slot_5.json
(the number of slots is rules.json presentation.save_slots). Each holds every flag plus the scene/node and a small meta block
(place, chapter, level, HP, name, time) for the load screen. You can’t save mid-fight or while a reroll question is open,
because those moments can’t be rebuilt from flags alone. Loading a save from an older build keeps working as long as its scene and node still exist.
JSON files are not Godot resources, so exports skip them by default. In Project → Export → (preset) → Resources → “Filters to export non-resource files” add:
*.json
| Milestone | Goal | Done when |
|---|---|---|
| M0 — Today | Scaffold, Act 1 opening playable in terminal and Godot | validate and fuzz pass; F5 in Godot plays the Ossuary |
| M1 — Vertical slice of Act 1 | Write A1-2 → A1-4 in JSON; add @lock_crown_truth at the Bell Tower |
Fuzz reaches the Act 1 end with all three truths |
| M2 — Combat prototype | ✅ Turn-based skirmish (text). Next: grid movement + attack for the Ossuary fight, reading the same encounter/unit data | The grid scene calls StoryEngine.resolve_combat(outcome) |
| M3 — Look & feel | ✅ Portraits, scene backgrounds + particles, placeholder sounds, serif font, typewriter, animated choices, tumbling d20, chapter cards, title + pause menus, 5 save slots + autosave + quicksave. Next: real art per scene, recorded sound, music | A friend can play Act 1 without you explaining anything |
| M4 — Act 2 camp + one shard site | ✅ Romance stages, jealousy, Crossroads | One full romance arc to Kindling works |
| M5+ | ✅ Remaining shard sites, Act 3, and the follow-up quest The Thread Beyond (a4_01_sequel → a4_02_thread → a4_03_thread_end) |
— |
| Now | Godot playtest of the endgame (dev_act2:setup to reach it) and balance tuning. No story writing is pending |
The endgame plays well in Godot |
Resist building the combat system before M1. Story first; it tells you what combat needs to be.