aethelgard

Architecture, Engine & Language Choices

TL;DR

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.

Alternatives considered

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 one big idea: data-driven architecture

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

  1. Content never contains code. Only the tiny condition/effect language.
  2. Engine never contains story. No 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.
  3. Presentation never changes state. UI calls StoryEngine.choose(), never GameState.set_flag().
  4. One source of truth for flags. flags.json. Undeclared flags are errors in both the validator and the game.
  5. Godot runtime and tools/story.py implement the same rules. Change both together.

Repository layout

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://).

Save files

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.

Exporting builds — one gotcha

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

Suggested roadmap (first-game friendly)

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.