gamedev-the-steward/docs/LEARNING_ROADMAP.md

The Steward — Learning and Reusable-Systems Roadmap

Purpose

This project is both a playable prototype and an advanced Godot curriculum. The goal is not merely to accumulate features. It is to understand, implement, measure, and document systems that can form the foundation of a later production game.

The roadmap prioritizes:

• learning through complete vertical behaviors;
• separating simulation from presentation;
• repeatable experiments and measurements;
• systems that survive save/load and scale changes;
• visible results suitable for building in public;
• avoiding premature architecture that has not been tested by gameplay.

How to use this roadmap

Each milestone should produce five outcomes:

1. Concept learned — the Godot or simulation topic being studied.
2. Playable proof — behavior a player can observe or influence.
3. Reusable artifact — a system, pattern, benchmark, or tool.
4. Exit test — an objective condition for calling the milestone complete.
5. Retrospective — what worked, what failed, and what should change.

Do not advance because files exist. Advance when the exit test passes.

The current implementation has completed ResourceNode migration through player parity plus the minimal Jajce scaffold and navigation proof. The architecture gate below is now active and must pass before beauty production or broader simulation features. See ADR 0001.

Mandatory architecture gate

This gate sits between the first Jajce terrain/navigation proof and substantial beauty work, inventories, schedules, relationships, or population growth.

It requires:

• an explicit deterministic simulation clock;
• controlled, seedable random streams;
• a headless fixed-seed scenario runner and final-state checksum;
• versioned serializable records for current NPC, village, and resource state;
• authoritative resource amounts and reservations outside scene nodes;
• stable action/profession IDs and initial definitions;
• separate action selection, execution, target resolution, and visual travel;
• an active-world adapter for navigation facts and NPC position synchronization.

The gate is complete when the same scenario produces the same checksum without loading main.tscn, and loading or unloading a visual does not change authoritative NPC or resource state.

Current progress: the first two architecture slices are implemented:

• SimulationClock advances explicit fixed ticks while preserving remainder;
• NPC decisions and visual wander requests use controlled per-NPC random streams derived from an exported simulation seed;
• a headless scenario verifies same-seed equality, different-seed divergence, and a final-state checksum without loading main.tscn.
• versioned JSON records capture and restore current NPC, village, resource, clock, and RNG state;
• a save-at-tick-24 continuation test matches an uninterrupted 48-tick checksum and rejects unsupported schema versions.

The gate remains open. Scene-independent resource authority, stable definitions, responsibility separation, and visual load/unload invariance are still required. See the simulation state schema.

Three vertical slices

The long-term vision contains three major risks. Validate them separately before trying to combine the full game.

A. Simulation slice

A small village runs autonomously, exposes understandable decisions, creates history, and produces interesting failures without scripted quests.

B. Action slice

Movement, interaction, melee combat, companions, and small-group commands are fun in an isolated test environment.

C. World slice

One village, one route, and part of a town exchange people, goods, information, and conflict while the player moves between simulation fidelity levels.

The simulation garden is the first slice. A combat sandbox should begin before the simulation is “finished,” because combat feel is a separate high-risk problem.

Continuous learning practices

Keep a decision record

For meaningful architectural choices, record:

• problem;
• constraints;
• options considered;
• decision;
• consequences;
• conditions that would justify revisiting it.

This can later become a docs/decisions/ collection. Do not create records for trivial edits.

Maintain reproducible scenarios

Important behaviors should have fixed seeds and known initial state:

• normal village day;
• food shortage;
• blocked workplace;
• exhausted worker;
• path failure;
• NPC death;
• relationship conflict;
• migration or faction pressure.

Scenarios make debugging, videos, balancing, and performance comparisons easier.

Measure before optimizing

Maintain a small benchmark ledger:

Measurement	Example
Population	10, 100, 1,000, 10,000 data-only agents
Simulated duration	one day, season, or year
Wall-clock runtime	total and per simulated tick
Update count	decisions and scheduled events processed
Memory	state and history footprint
Active visuals	navigation/animation cost
Determinism	final-state checksum for a known seed

Pair systems with presentation

Every systems milestone should answer: “How can a viewer see this happening?” Every visual milestone should answer: “Which real state does this represent?”

Milestone 0 — Baseline and observability

Learn

• Godot project execution and scene-tree inspection;
• debugger, profiler, monitors, and remote scene tree;
• structured logging and debug overlays;
• establishing behavioral and performance baselines.

Build

• a simulation pause, single-step, speed control, and reset;
• selectable NPC debug panel;
• current need, task, task state, target, and task score display;
• deterministic scenario seed entry;
• concise event feed separate from verbose console logging;
• baseline performance capture for the existing three-NPC prototype.

Reusable artifact

A simulation debug console/overlay and scenario runner.

Exit test

From the running game, a developer can select any NPC and explain:

• what it is doing;
• why it selected that task;
• where it is going;
• when the task should complete;
• what state will change on completion.

The same seed and commands produce the same early simulation result.

Milestone 1 — Simulation/presentation boundaries

Learn

• Node, RefCounted, and Resource responsibilities;
• signals versus direct calls;
• dependency direction;
• scene composition;
• typed GDScript and stable identifiers.

Build

• explicit simulation clock outside frame-dependent rules;
• stable IDs for NPCs and locations;
• serializable state records separated from immutable definitions;
• an adapter interface between simulation and active visual NPCs;
• smaller managers with focused responsibilities;
• removal of direct task-string-to-marker coupling from the core.

Reusable artifact

A minimal headless-capable simulation kernel with a Godot presentation adapter.

Exit test

The village can advance without instantiating NpcVisual scenes. Loading or unloading an NPC visual does not change the authoritative NPC state.

Milestone 2 — Data-driven needs, professions, and actions

Learn

• custom Resource definitions;
• utility AI and consideration curves;
• action preconditions, effects, duration, and interruption;
• dependency injection through definitions;
• debugging decision scores.

Build

• need definitions;
• profession definitions;
• action definitions for eat, rest, gather food, gather wood, patrol, and study;
• target discovery independent of hard-coded scene paths;
• utility considerations with full reason traces;
• reservations so multiple NPCs do not unrealistically claim one resource or workstation;
• explicit task failure and replanning behavior.

Reusable artifact

A generic action-selection system that can evaluate defined actions against agent and world state.

Exit test

A new profession and action can be added primarily through definitions and a small effect implementation. The inspector shows the winning score and rejected alternatives. NPCs recover from invalid or unavailable targets.

Milestone 3 — One complete material economy

The staged replacement of abstract task zones begins with the ResourceNode migration plan.

Learn

• inventories and item stacks;
• ownership, storage, reservations, and transactions;
• production recipes;
• world interaction points;
• consistency and invariant testing;
• structured economic events as authoritative facts.

Build

Implement one honest food chain:

source -> gather/harvest -> carry -> store -> retrieve -> prepare/eat

Include:

• item definitions;
• personal and building inventories;
• location-based storage;
• physical carrying for active NPCs;
• abstract transfer for distant agents;
• reservation and cancellation;
• spoilage only if it improves the initial loop;
• player participation in the same resource rules;
• structured gather, transfer, consume, deny, and depletion events carrying stable actor, target, location, and resource IDs.

Wood extraction already exists. Do not build a deeper wood production chain until the food chain is coherent.

Reusable artifact

Inventory, reservation, transaction, and production primitives.

Exit test

Every consumed unit of food can be traced to a source and a sequence of actions. No resource is created or destroyed except through an explicit, inspectable rule. A shortage is visible before the aggregate UI reports it.

Milestone 4 — Attractive simulation garden

The detailed environment and public-demo sequence is maintained in the build-in-public visual slice plan.

Learn

• Terrain3D regions, sculpting, texturing, LOD, and instancing;
• environment lighting, fog, sky, and post-processing;
• modular scene construction;
• navigation generation and validation;
• water and vegetation presentation;
• performance budgets for environment art.

Build

• a compact Jajce-inspired valley composition;
• ridge landmark, river/waterfall feature, bridge, mill area, farm, forest, homes, and workplaces;
• warm painterly environment treatment;
• replace capsules with simple stylized, animation-ready characters;
• readable profession props/colors;
• day/night presentation;
• cinematic/debug display toggle;
• stable navigation across all required work routes.

Reusable artifact

A terrain/world-building pipeline and environment performance checklist.

Exit test

A short clip communicates the setting, player perspective, NPC professions, and one production loop without narration or console output. The environment stays inside the agreed frame-time and memory budget on the development machine.

Milestone 5 — Time, schedules, and persistence

Learn

• authoritative game time;
• calendar and scheduled events;
• serialization and schema versioning;
• save migration;
• restoring active scenes from data;
• deterministic random streams.

Build

• time-of-day and calendar;
• work, meal, sleep, and discretionary schedule blocks;
• simulation event queue;
• versioned save format;
• save/load for people, inventories, tasks, locations, and village state;
• state validation after loading;
• separate random streams where useful.

Reusable artifact

A versioned world-state persistence layer and simulation scheduler.

Exit test

Save during travel, work, eating, and sleep; reload each save; then verify that the simulation resumes coherently. A deterministic headless scenario retains the same checksum across repeated runs.

Milestone 6 — Events, memories, and relationships

Learn

• event sourcing concepts without overcommitting to full event sourcing;
• relationship graphs;
• knowledge versus objective truth;
• memory selection and decay;
• social utility considerations;
• tooling for history inspection.

Build

• structured world event records;
• actor, target, witness, location, cause, and consequence links;
• relationship dimensions such as familiarity, affection, trust, fear, obligation, and hostility;
• NPC knowledge of witnessed or communicated events;
• memory importance and retention rules;
• visible social reactions;
• person and settlement history views.

Reusable artifact

An event/history store and relationship system with query APIs.

Exit test

Two NPCs exposed to different evidence can hold different beliefs about the same event. Their future choices visibly differ because of those memories and relationships.

Milestone 7 — Rumours and emergent opportunities

Learn

• information propagation;
• query systems;
• narrative framing from structured facts;
• objective generation;
• consequence-aware quest state;
• natural-language presentation separated from authoritative state.

Build

• rumour creation and transmission;
• information accuracy, secrecy, and distortion rules;
• detection of unresolved conditions;
• interested-party and capable-helper queries;
• opportunity/quest records that reference real entities and events;
• multiple valid resolution paths;
• consequence application to the source systems;
• concise dialogue/event text templates.

Reusable artifact

An emergent opportunity generator built over world-state queries.

Exit test

A shortage, theft, injury, debt, or disappearance creates an opportunity only when someone knows and cares about it. Resolving it changes the originating people, resources, relationships, and history without spawning quest-only duplicates.

Milestone 8 — Scalable spatial simulation and LOD

Learn

• spatial partitioning;
• relevance and interest management;
• scheduled/batched updates;
• data layout and allocation profiling;
• active/abstract entity transitions;
• statistical aggregation boundaries.

Build

• spatial index for people, buildings, and events;
• active, local-abstract, distant-individual, and settlement-aggregate modes;
• promotion/demotion between modes;
• abstract travel and work resolution;
• background settlement updates;
• performance harness for increasing population and history;
• safeguards preserving named people and unresolved events.

Reusable artifact

A simulation-LOD framework with measured transition invariants.

Exit test

The benchmark can simulate a target large population faster than real time while a smaller active population remains fully represented. Moving an NPC between fidelity levels preserves identity, inventory, task, relationships, and important history.

Set the target population only after collecting baseline measurements.

Milestone 9 — Player interaction and social agency

Learn

• interaction targeting;
• context actions;
• UI state machines;
• dialogue presentation;
• reputation and permission systems;
• accessibility and feedback.

Build

• inspect people, storage, workplaces, and events;
• talk, trade, help, request, employ, threaten, or report where appropriate;
• priority influence through plausible institutions rather than omniscient sliders;
• reputation, authority, and social access;
• player participation in professions;
• feedback showing likely and actual consequences.

Reusable artifact

A context interaction framework connected to simulation actions and authority.

Exit test

The player can understand and resolve the simulation garden's food crisis in multiple systemic ways without using a developer menu.

Milestone 10 — Combat and companion sandbox

Begin this as a focused prototype before Milestones 6–9 are fully complete. Integrate it only after its fundamentals feel good.

Learn

• animation state machines and blending;
• hit detection and hurtboxes;
• root motion versus code-driven motion;
• input buffering;
• camera feedback;
• AI combat behavior;
• group commands and formations;
• combat profiling.

Build

• isolated combat test scene;
• responsive locomotion, attacks, defense, stagger, and recovery;
• clear targeting without excessive lock-on dependence;
• one companion with understandable autonomous behavior;
• a small command vocabulary;
• morale and retreat prototype;
• simulation consequences for injury, death, witnesses, and reputation.

Reusable artifact

A combatant state model, animation interface, damage/event model, and companion command layer.

Exit test

A short encounter is enjoyable when repeated without progression rewards. One companion can be directed without constant micromanagement, and combat outcomes produce valid world events.

Milestone 11 — Multiple settlements, factions, and mobility

Learn

• hierarchical simulation;
• settlement economies;
• faction goals and diplomacy;
• trade routes and migration;
• authority and governance;
• large-group command abstraction.

Build

• one village, one travel route, and one district or edge of the city;
• movement of goods, people, rumours, and threats;
• household and workplace membership;
• faction membership and offices;
• migration and recruitment;
• small-scale leadership progression;
• settlement and faction decision processes.

Reusable artifact

A regional simulation layer connecting local economies and social structures.

Exit test

An event in one settlement creates measurable consequences elsewhere through real movement or communication. The player can gain responsibility through systemic relationships and actions rather than a fixed promotion quest.

Milestone 12 — Integrated world slice

Learn

• production hardening;
• content pipelines;
• onboarding complex systems;
• balancing and telemetry;
• regression testing;
• profiling representative gameplay.

Build

• the simulation, action, and world slices connected;
• one coherent regional scenario;
• polished onboarding for observation, work, social interaction, and combat;
• save compatibility tests;
• performance budgets and regression scenarios;
• build-in-public demo mode;
• documented extraction boundaries for reusable systems.

Reusable artifact

A proven architecture and a set of tested subsystems ready to migrate or evolve into the production game.

Exit test

The player can begin as an ordinary person, form relationships, participate in the economy, encounter an emergent problem, fight or negotiate through it, and leave persistent consequences in another settlement.

Reuse checkpoints

At the end of each milestone, evaluate the system against this checklist:

• Does it run without the prototype's main scene?
• Are definitions separate from mutable state?
• Is state serializable and versioned where appropriate?
• Can it be tested with a fixed seed?
• Can presentation be replaced without rewriting its rules?
• Does it expose reason/debug information?
• Do measurements justify its complexity?
• Has at least one real gameplay feature exercised the API?
• Does persistent authority remain valid when its presentation node is absent?
• Can an active visual synchronize position without becoming the sole owner of location state?

Do not extract a plugin solely because a system might be reusable. Prefer a clear internal module until multiple real consumers establish a stable API.

Recommended implementation order from the current repository

Completed foundations:

• finite food and wood ResourceNode instances;
• NPC target selection, reservation, depletion, and authoritative yield;
• player parity through the same extraction contract;
• navigation-failure recovery and an initial headless contention scenario;
• executable flat-map baseline;
• 512 m Jajce Terrain3D seed, greybox landmarks, stable-ID resource placement, lookdev scene, and tested temporary navigation loop.

The practical next sequence is:

1. Move resource amount/reservation authority out of ResourceNode scenes and make unloaded resources remain in state.
2. Replace free-form task and profession strings with stable IDs and definitions.
3. Separate action selection, execution, target resolution, and visual travel; remove decision mutation from WorldViewManager.
4. Define active-position synchronization and prove visual unload/reload.
5. Pass the architecture gate's deterministic headless and unloaded-visual exit tests.
6. Build location-based food storage, inventory, and transactions.
7. Emit structured economic events while making one NPC visibly gather, carry, store, retrieve, and eat food.
8. Add save-slot persistence and explicit schema migrations before schedules or social state expand.
9. Resume Terrain3D sculpting, runtime integration, and the simulation-garden beauty pass.
10. Add stylized character and profession readability plus the reason inspector.

This order strengthens the simulation while regularly producing visible progress suitable for public development updates.

Subjects intentionally deferred

These are valuable future learning areas but should not distract from the first complete slices:

• multiplayer authority and replication;
• procedural terrain generation;
• machine-generated freeform dialogue;
• full historical demography;
• hundreds of item recipes;
• siege-scale combat;
• sophisticated market speculation;
• native GDExtension optimization;
• custom rendering technology.

Revisit them when a completed slice demonstrates a concrete need.