fix: empty-path re-entrancy, retry_count reset, := to = for Variant

2026-07-03 18:51:13 +02:00
parent c6033b63fb
commit 41bfc8d90a
9 changed files with 2449 additions and 4 deletions
@@ -0,0 +1,590 @@
+# 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.
+
+## 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](RESOURCE_NODE_MIGRATION.md).
+
+### Learn
+
+- inventories and item stacks;
+- ownership, storage, reservations, and transactions;
+- production recipes;
+- world interaction points;
+- consistency and invariant testing.
+
+### Build
+
+Implement one honest food chain:
+
+```text
+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.
+
+Add wood only after 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](BUILD_IN_PUBLIC_PLAN.md).
+
+### 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?
+
+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
+
+The practical next sequence is:
+
+1. Add simulation controls and an NPC reason inspector.
+2. Add finite berry bushes and trees through the first `ResourceNode`.
+3. Migrate food target selection, reservation, depletion, and actual yield.
+4. Introduce an explicit deterministic simulation clock and seed.
+5. Replace remaining free-form task strings with action IDs/definitions.
+6. Separate action selection, action execution, and visual travel.
+7. Migrate wood and give the player the same extraction contract.
+8. Build the first location-based food storage/inventory.
+9. Make one NPC visibly gather, carry, store, retrieve, and eat food.
+10. Build the first attractive Terrain3D simulation-garden layout.
+11. Add simple stylized characters and profession readability.
+12. Add save/load before the mutable world state becomes substantially larger.
+
+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.