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, the Jajce scaffold/navigation proof, and the mandatory architecture
gate below. See
[ADR 0001](decisions/0001-simulation-authority-boundary.md).

## 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.

**Status: complete.** All architecture-gate 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.
- `SimulationManager` owns resource records and all amount/reservation
  mutation; ResourceNode binds by stable ID as presentation and interaction
  geometry;
- an unload/rebind regression proves resource state remains authoritative while
  its scene node is absent.
- stable StringName IDs and validated custom resources define all current
  actions and professions;
- NPC duration/preference logic, resource target metadata, generation, and
  serialized references resolve through the definition registry.
- focused selection, execution, and target-resolution systems now own their
  respective rules;
- ActiveWorldAdapter supplies loaded-world facts, while WorldViewManager only
  supplies visual position and executes emitted travel requests.
- active movement synchronizes into authoritative NPC position state;
- persisted travel destinations let visuals unload/reload without changing
  actions, targets, reservations, positions, RNG state, or checksums.

The fixed-seed scenario runs without `main.tscn`, and visual lifecycle
invariance is covered headlessly. See
[the action system architecture](ACTION_SYSTEM_ARCHITECTURE.md),
[the simulation definitions](SIMULATION_DEFINITIONS.md) and
[the simulation state schema](SIMULATION_STATE_SCHEMA.md).

## 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;
- structured economic events as authoritative facts.

### 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;
- 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](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.

[Simulation scaling baseline 01](benchmarks/SIMULATION_SCALING_BASELINE_01.md)
sets the first local target at 600 data-only full-fidelity NPCs while preserving
deterministic state. [Baseline 02](benchmarks/SIMULATION_SCALING_BASELINE_02.md)
keeps identical final checksums after one reusable per-tick population view and
improves that case from 65.84 to 85.81 ticks per second. Revisit the target when
world presentation or LOD enters the measured workload.

[Loaded Resource Discovery 01](benchmarks/LOADED_RESOURCE_DISCOVERY_01.md)
proves the first real spatial consumer. Exact loaded-anchor resolution remains
near four inspected candidates from 18 through 1,800 resources, preserves every
linear selected-target checksum, and keeps persistent authority outside the
index.

## 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.

Completed after the architecture gate:

- location-based pantry state, NPC-carried food, and explicit
  deposit/withdraw/consume transactions;
- a headless conservation scenario covering the complete food loop;
- deterministic structured economic events for extraction, deposit,
  withdrawal, and consumption;
- persisted event identity/history and a visible carried-food prop derived
  from NPC inventory;
- a validated local quicksave with bounded file size, guarded slot names,
  atomic replacement recovery, F5/F9 controls, and active-visual rebuilding.
- an integrated Jajce beauty baseline with shaped Terrain3D data, a bounded
  six-layer palette, atmospheric lighting, shader water, foliage motion,
  building blockouts, and visible smoke/mist.
- definition-driven profession colors/props and a selected-NPC inspector fed
  by real decision branches, destinations, needs, and utility scores.

The first relationship consequence slice is complete:

- directed familiarity/trust records now live in a top-level relationship
  graph instead of NPC-local dictionaries;
- a successful known food-deposit event raises a hungry familiar NPC's trust
  and is retained as the exact causal event ID;
- that trust can redirect ordinary patrol work toward replenishing a low pantry
  for a starving acquaintance;
- the inspector displays the relationship values and completed event cause;
- schema migration, save/restore checksums, idempotence, and a neutral-control
  decision test cover the complete slice.

The first witnessed-knowledge slice is also complete:

- `KnownEventStateRecord` keeps per-NPC event references separate from
  objective event history;
- successful food deposits are known by their actor and nearby living NPCs at
  event-record time, while distant NPCs remain uninformed;
- two equally familiar guards with different evidence now gain different trust
  and choose helping versus ordinary patrol;
- the inspector resolves and displays the selected NPC's latest known fact;
- schema v6 migration, invalid-reference rejection, deterministic save/load,
  and proximity/idempotence tests cover the complete slice.

The first communicated-knowledge slice is complete:

- first acquisition is persisted as performed, witnessed, communicated, or
  legacy, with the direct speaker retained for communicated facts;
- a villager arriving beside an already-working villager at a shared
  non-storage activity can receive one newest direct fact within 2.5 metres;
- communication references the original immutable event, changes only the
  listener's knowledge/relationship consequence, and cannot relay a heard fact
  again in this bounded phase;
- the inspector names who communicated the fact, and schema-v6 migration,
  malformed-provenance rejection, event-history invariance, save/checksum, and
  informed-choice regressions cover the complete slice.

The first importance/retention slice is complete:

- acquisition ticks order facts by when an NPC learned them rather than by the
  objective event ID;
- a current relationship cause is lasting, while each NPC keeps at most three
  other recent facts;
- a deterministic daily-sized review forgets recent facts at least one day old
  without deleting objective event history or rolling back trust;
- communication prefers lasting direct evidence, and a source-method snapshot
  keeps listener provenance valid after the teller forgets;
- the inspector shows lasting/recent counts, while schema-v7 migration,
  boundary, capacity, cause-protection, save/checksum, and informed-choice
  regressions cover the slice.

The compact history/reaction slice is complete:

- the selected-person inspector separates lasting-first retained memories from
  the NPC's own objective event history and keeps both lists bounded;
- remembered facts show performed, witnessed, communicated, or legacy
  provenance without copying authoritative events into presentation state;
- a real trust change blooms once above its observer, remains visible in
  cinematic mode, and is never persisted or replayed after visual rebuild;
- ranking, forgetting/objective-history separation, observer-only routing,
  checksum neutrality, restore, cinematic, and death regressions cover the
  slice.

This completes the first bounded Milestone 6 evidence-to-choice presentation
path without claiming full belief simulation.

The first bounded Milestone 7 opportunity proof is complete:

- a positive NPC food withdrawal from `village_pantry`, combined with the
  pantry currently being empty, is the exact shortage evidence;
- the need opens only when a living critically hungry villager knows that
  event through performance, witnessing, or the existing one-hop
  communication contract;
- highest hunger and then lowest stable NPC ID select one interested villager,
  with at most one open pantry need;
- schema-v8 opportunity records retain stable NPC, event, storage, resource,
  and resolution IDs, and protect the trigger memory while the need is open;
- an exact later NPC food deposit or player resource extraction into the
  pantry resolves the same record through the real economy/event history;
- generation neither mutates the economy nor commands NPC work, and it adds no
  quest-only event, acceptance, reward, dialogue, multi-hop rumour, or generic
  quest framework.

The first build-in-public presentation checkpoint for that proof is also
complete:

- authoritative pantry food selects a physical empty, low, or stocked pantry
  arrangement instead of leaving a generic storage crate unchanged;
- only the interested villager shows a restrained empty-bowl concern cue;
- a real NPC deposit changes the pantry props, clears concern, and produces one
  brief refill response, while restore derives the stable presentation without
  replaying that transient effect;
- the repeatable runtime capture now includes an empty/restocked close pair in
  the established elevated third-person visual language.

The outcome-defined pantry-crisis demo loop is complete:

- `F11` reloads the authored seed and runs a measured 20–30 second cinematic
  sequence with the development UI hidden;
- a real final-food withdrawal and consumption leave the physical pantry empty
  and open the knowledge-gated need for its worried witness;
- a trusted acquaintance selects ordinary `gather_food`, reserves and visits a
  finite berry source, visibly carries its yield home, and autonomously selects
  the real pantry deposit;
- that exact deposit resolves the opportunity, restores the physical stock,
  clears concern, and triggers the existing refill response;
- restrained captions and a camera handoff clarify the three beats without
  replacing state-driven world cues, while a runtime validator measures the
  unassisted route and a headless scenario verifies its full event chain.

The second bounded Milestone 7 consumer is complete:

- patrol or study that loses its definition-backed wood cost at completion
  records one zero-transfer `task_blocked` fact with stable action, woodpile,
  wood, and required-amount fields, without applying the work effect;
- the performer and nearby witnesses retain that objective fact, and the
  performer becomes the interested party for one `supply_missing_wood` need;
- a real later NPC wood deposit or player tree extraction into the woodpile
  resolves the record through its exact existing event;
- interested-party death or evidence that remains unresolved for one simulated
  day invalidates the need deterministically, emits no quest-only fact, and
  releases the protected trigger memory;
- world schema v9, nested opportunity schema v2, wood-specific UI text, and
  focused headless/runtime regressions preserve the full open, resolved, and
  invalidated lifecycle;
- the two proven consumers now share `VillageOpportunitySystem` and the common
  lifecycle fields, while their evidence and care rules remain explicit.

The first bounded capable-helper query is complete:

- an open need derives at most one living helper who knows its exact trigger,
  has an existing familiar directed relationship with at least 0.6 trust toward
  the interested villager, and is not that villager;
- the helper must either carry enough matching inventory to reach the target or
  have a matching enabled, NPC-usable, sufficiently stocked finite resource
  that is not reserved by someone else;
- ready inventory wins first, followed by higher trust, matching gather
  profession, familiarity, and lowest stable NPC ID;
- `OpportunityHelperResult` exposes the exact opportunity, trigger, helper,
  action, inventory source or finite-source count, resource, relationship
  values, and concise reason without mutating RNG, tasks, reservations,
  resources, or persisted state;
- food and wood scenarios re-derive the same result after restore, and the
  village summary explains the current helper route from real simulation facts.

The first bounded autonomous helper consumer is complete:

- when an NPC becomes idle, `SimulationManager` re-derives the current helper
  and passes that ephemeral result into ordinary action selection;
- only the matching helper can select the reported gather/deposit action, and
  starvation, critical hunger, mourning, low energy, sleep, and meal behavior
  keep precedence;
- the resulting task uses the existing definition, target resolver, finite-node
  reservation, travel, extraction, inventory, and storage transaction paths;
- no helper assignment, acceptance, reward, opportunity-specific event, or RNG
  draw is added, while an in-progress ordinary task continues through the
  existing NPC save fields and task-start history;
- focused headless and Jajce runtime regressions prove autonomous selection,
  precedence, finite-source targeting, reservation, and restore-time re-query.

The first direct information-to-help path is complete:

- at an eligible shared activity, a speaker who performed or witnessed the
  active need's exact trigger discusses it before other retained direct facts;
- the transfer still references the original event, preserves the speaker and
  direct source method, stops after one hop, and creates no dialogue/event copy;
- a regression places a newer unrelated fact ahead under normal ranking, then
  proves active-need priority transfers only the trigger to the trusted capable
  listener;
- the newly informed villager is immediately re-derived as helper and, once
  idle, chooses the same ordinary autonomous gather/deposit path;
- a cardless warm-amber player HUD briefly shows the real need, named report,
  helper response, and resolution. It is signal-driven, survives debug-overlay
  hiding, and neither serializes nor replays after restore.

The bounded Milestone 7 player-response affordance is complete:

- an open need with no capable helper derives one ephemeral
  `OpportunityPlayerResponseResult` only when its real storage target has room
  and at least one matching enabled, stocked, player-usable finite source
  exists;
- the result exposes the ordinary gather action, resource, destination, source
  count, opportunity, and trigger IDs without selecting a waypoint, accepting a
  quest, drawing RNG, or mutating simulation state;
- the existing cardless village-whisper ribbon says `YOU CAN HELP` and explains
  the direct resource-to-storage interaction in one line, while the development
  summary exposes the exact derived route;
- knowledge, relationship, inventory, or village-resource changes track the
  derived route in both directions: a newly unassisted need can surface the
  hint once, a capable helper removes it immediately, and resolution or
  invalidation replaces it with the existing close beat;
- reserved resources remain honestly player-usable because the current player
  extraction contract does not consume NPC reservations, while disabled,
  depleted, wrong-resource, and capacity-blocked sources do not qualify;
- unit, headless lifecycle, restore/checksum, real player extraction, and Jajce
  runtime regressions cover the slice without persisting or replaying HUD state.

This completes the bounded Milestone 7 simulation-garden proof. A known and
cared-about shortage now produces an inspectable opportunity whose NPC and
player responses both use the originating resource, relationship, knowledge,
and event systems rather than quest-only duplicates.

The first Milestone 8 measurement slice is complete. A reusable schema-valid
headless fixture and CLI runner now measure three fresh deterministic samples
across 6, 60, and 600 NPCs plus 600 and 6,000 seeded event histories. The
reviewed Apple M1 Max baseline reaches 65.84 ticks per second at 600 NPCs, but
10x population from 60 to 600 costs about 24.4x per tick and creates 20,950
objective events over 200 measured ticks. The machine-readable samples,
workload exclusions, checksums, and local 50-ticks-per-second reference target
live in
[Simulation scaling baseline 01](benchmarks/SIMULATION_SCALING_BASELINE_01.md).

The first measured optimization is also complete. `SimulationPopulationView`
builds stable-ID all/living/starving indexes once per tick, refreshes them after
each interleaved NPC update, and serves relationship/action queries without
entering saved state. Every baseline-02 checksum exactly matches baseline 01.
The 600-NPC case falls from 15,187.74 to 11,654.10 microseconds per tick, a
23.3% improvement, while small fixtures expose the expected fixed dictionary
cost. See
[Simulation scaling baseline 02](benchmarks/SIMULATION_SCALING_BASELINE_02.md).

The first loaded-world spatial consumer is complete. `ActiveWorldAdapter` owns
a disposable 24 m horizontal grid of loaded finite `ResourceNode` anchors.
`ActionTargetResolver` expands through nearby ranges and stops only when
authoritative risk/comfort/priority bounds prove that no farther source can win.
Matched 18/180/1,800-source samples preserve every selected-target checksum;
the 1,800-source case falls from 6,448.00 to 46.94 microseconds per resolution.
Unload/rebind state authority, stable tie order, moved anchors, reservations,
player parity, and a deliberately far high-priority winner remain covered. See
[Loaded Resource Discovery 01](benchmarks/LOADED_RESOURCE_DISCOVERY_01.md).

The authored-watercourse slice is complete. `JajceWatercourse` now gives the
deterministic terrain generator and both water ribbons one shared profile; the
generated Terrain3D data contains an upper stream, raised waterfall shelf,
plunge basin, and curved downstream channel. A matched Metal capture records
the result, and the Terrain3D-derived navigation mesh was rebaked and validated
against required village/resource routes.

The first authored foliage/resource workflow is complete. One riverbank cluster
uses three intentional MultiMesh batches for 28 fern, flower, and stone
instances plus two decorative trees, while only an existing stable-ID berry and
tree are finite `ResourceNode` anchors. Both anchors preserve the save contract
of eighteen resources, sit above the carved channel, and expose separate
terrain-snapped approach points. A forced village query expands beyond the
initial 24 m range and selects the nested berry exactly by ID.

The first amount-derived resource presentation slice is complete. A shared
`ResourceAmountVisual` contract reads the loaded `ResourceNode`'s authoritative
amount and derives full, low, or depleted presentation without entering saved
state. Real player berry harvests remove fruit and leaf mass; real NPC wood
gathers thin the crown and ultimately leave a warm-cut stump. Restoring both
low and depleted snapshots rebinds the same nodes and reconstructs the same
visuals from `ResourceStateRecord.amount_remaining` alone.

The second authored foliage/resource workflow is complete. The existing
`tree_forest_grove_01` and `tree_forest_grove_02` anchors now form one bounded
forest edge with two decorative silhouette trees and 24 fern, mushroom, and
stone instances in three MultiMesh batches. Both stable IDs and definitions
remain authoritative, while village-facing interaction points sit beyond the
initial 24 m discovery radius and remain reachable on the Terrain3D-derived
navigation mesh. Real NPC depletion leaves the shared stump and restore
rebuilds the sparse standing tree from amount alone. The river and forest
clusters now share only the terrain-snap, bounded-instance, and anchor-layout
code proven by those two consumers.

The first identity-backed livestock slice is complete. Dunja has a stable
animal ID, simulation-owned position and hunger/feed state, and a loaded cozy
presentation whose persistent cue derives from that state. One exact operation
serves both NPC and player feeding, consumes real food from the actor's current
source, mutates only the target animal, and appends one economic fact.
World-schema v10 save/restore preserves the result without replaying the
transient response.

The first loaded-animal routine slice is complete. Dunja alternates between
stable shelter and pasture IDs without RNG; her exact target and current
position stay simulation-owned while the loaded scene follows the Jajce
navigation map. Schema-v11 mid-route restore preserves the checksum,
destination, and every NPC RNG stream. Unloading and re-instantiating the goat
scene retains that same travel state, arrival is exact, and hunger stops
movement before feeding.

The first multi-animal care slice is complete. Zora adds a second stable record,
loaded presentation, and private shelter while sharing Dunja's pasture. When
both goats are hungry, loaded target resolution chooses the nearest available
interaction point, two villagers can retain independent exact claims, and
feeding Zora leaves Dunja's hunger, feed history, and reservation untouched.
Schema-v11 restore preserves both claim pairings and checksum. Loaded routine
sites now distinguish private shelter ownership from shared species context
without adding that authored-world fact to saved simulation state.

The named-pair playtest gate exposed and closed its first embodied-use gap.
`PlayerInteractionResult` now derives one exact, ephemeral context from the
same priority and stable target used by `E`: named animal care, finite-resource
harvest, pantry eating, guard work, or study. A cardless bottom-center prompt
shows the action and real availability, remains visible in cinematic mode, and
briefly reports success or blockage. Restore clears transient feedback and
re-derives the current prompt without adding saved state or drawing RNG.

NPC animal care is now physically honest:
`village_pantry -> NPC inventory -> exact named goat`. A caretaker reserves the
goat before visiting the pantry, keeps that stable claim through both travel
legs, visibly carries the withdrawn unit, and consumes only carried inventory
at delivery. One-unit contention records the late shortfall and releases only
the losing claim. A post-pickup restore preserves the inventory, exact goat,
destination, event count, and final checksum without a new saved phase field
or RNG draw.

Player-facing villager inspection now advances Milestone 9 without stealing the
existing `E` action. A quiet cardless field note chooses the nearest loaded,
living villager with stable-ID tie order, then re-reads that NPC's authoritative
name, action, exact target, task state, and carried inventory. It includes the
latest decision reason only while that trace still matches the live action.
Presentation unload clears the note; restore reacquires the replacement NPC
record, re-derives every saved fact, and honestly awaits the next ephemeral
decision reason. The query and HUD add no mutation, RNG draw, or saved state.

The next bounded slice should move from observation to one honest social
affordance. When the nearby inspected villager is the interested person for an
open village opportunity, surface that exact need. Show the already-proven
finite-resource-to-storage route only when the authoritative player-response
query can currently derive it; otherwise name the capable helper or honestly
say why direct help is unavailable. Let the ordinary finite-resource harvest
resolve the need without adding a dialogue tree, quest acceptance, rewards, a
quest log, reputation, a generic conversation framework, or saved presentation
state in that slice.

The first bounded field-note opportunity surfacing slice is complete:

- `VillagerInspectionResult` now carries an optional read-only
  `VillagerOpportunityNote` that is present only when the inspected villager is
  the interested party of an open village opportunity;
- `VillagerOpportunityNote.derive` decides the honest help state from the
  existing authoritative queries: the derived player-response route wins, then
  the capable helper by name, then a real unavailable reason (need already met,
  storage has no room, no stocked source in reach, or no storage at all);
- the quiet `VillagerFieldNoteHud` shows a restrained `Need` line for exactly
  that note, coexists with the existing `E` prompt and cinematic mode, and
  re-derives it from live state without entering saves or drawing RNG;
- a real player finite-resource harvest resolves the same open
  `OpportunityStateRecord` through the existing economy/event history, and the
  need segment clears on the next refresh;
- unit, runtime, and query-neutrality checks cover the derive branches, the
  staged pantry-crisis surfacing, helper naming, ordinary harvest resolution,
  and the absence of saved presentation state.

Recently completed:

- `Jajce Villager Field Note 12`: a separate player-facing note selects the
  nearest loaded living villager and shows live name, action, task state, exact
  target, carried inventory, and a currently matching decision reason. It
  coexists with the `E` prompt, survives cinematic mode, clears on visual
  unload, and re-derives saved facts after restore without reviving transient
  reasoning or changing the schema.
- `Jajce Care Delivery 11`: NPC `feed_animal` is now one compound, two-leg
  action from the real pantry through caretaker inventory to the exact reserved
  goat. Carried presentation, ordered transfer facts, late contention,
  conservation, and post-pickup deterministic continuation are proven without
  a schema bump or generic job framework.
- `Jajce Context Action 10`: one ephemeral result now keeps the displayed `E`
  prompt and executed stable target aligned across existing player
  interactions. Named goat care shows exact pantry availability and transient
  success/blockage, survives cinematic mode, and re-derives after restore
  without persistent UI state.
- `Jajce Goat Pair 09`: named goat Zora adds a second independent animal
  record and private shelter while sharing Dunja's pasture. Stable nearest
  targeting, simultaneous exact reservations, isolated feed mutation and
  events, deterministic routine ownership, and active-claim save/restore prove
  the multi-animal contract without a schema bump or herd system.
- `Jajce Dunja Habitat 08`: the first deterministic animal routine alternates
  shelter and pasture through real loaded navigation, preserves exact
  mid-route state across save/restore and presentation unload/reload, stops
  when hungry, bends grass while moving, and colocates goat-owned assets in a
  focused feature folder.
- `Jajce Goat 07`: named goat Dunja proves stable animal identity, exact
  pantry-conserving NPC/player feeding, deterministic hunger and save/restore,
  loaded target reservation, a state-derived hungry cue, and a transient cozy
  response that never enters persisted state.
- `Jajce Forest Edge 06`: two existing deep-forest tree IDs now anchor a
  restrained four-tree silhouette with 24 decorative understory instances.
  Both targets require expanded loaded-resource discovery, remain reachable,
  reuse amount-driven crowns/stumps, and preserve the eighteen-resource save
  contract through real NPC depletion and restore.
- `Jajce Resource States 05`: the authored river berry/tree now derive full,
  low, and depleted visuals from authoritative amounts. Player and NPC
  extraction drive the changes, save/restore reconstructs low and depleted
  states without visual save fields, and matched Metal frames record the berry
  thinning, sparse crown, fruitless remnant, and stump.
- `Jajce Resource Grove 04`: two existing river resources now live as nested
  stable-ID anchors inside a restrained decorative bank cluster. Twenty-eight
  understory instances use three MultiMesh batches, bespoke berry/tree visuals
  replace generic boxes, terrain-snapped approach points remain reachable, and
  a real far-source query proves parent-path-independent expanding discovery.
- `Jajce River 03`: deterministic Terrain3D generation now carves the upper
  stream, raised waterfall shelf, plunge basin, and curved downstream channel;
  shared watercourse geometry keeps both water ribbons aligned, soft masked
  mist replaces hard billboards, and the rebaked navigation mesh passes
  terrain-height and runtime resource-route checks.
- Loaded-resource spatial discovery: a resource-specific active-world grid
  preserves exact score winners and lifecycle authority while reducing the
  reviewed 1,800-anchor query from 6.45 ms to 46.94 µs.
- Shared population query view: one transient per-tick all/living/starving
  index replaces repeated scarce-food relationship scans, preserves exact
  checksums, and improves the reviewed 600-NPC workload by 23.3%.
- `Jajce Center 02`: matched before/after captures now document a larger summit
  citadel, cascading timber-plaster homes, terrain-following turquoise river,
  rock-framed waterfall, richer tree silhouettes, restrained conifer clusters,
  oversized butterflies, and short camera-local grass that bends around real
  player/NPC transforms without becoming simulation state.
- Deterministic simulation scaling baseline: schema-valid full-fidelity
  fixtures, a repeatable CLI runner, and a fast headless regression now record
  population throughput, phase timing, serialized-state growth, history
  retention, event growth, and deterministic checksums before optimization.
- Simulation responsibility cleanup: storage/inventory transactions now live
  in `VillageEconomy`, ordered history and rate queries live in
  `SimulationEventLog`, and `SimulationManager` exposes a shorter tick
  lifecycle while remaining the scene-tree façade. Dead prototype APIs and
  unused scene artifacts were removed, with the ownership map documented in
  `ARCHITECTURE_OVERVIEW.md`.
- `F10` cinematic/debug presentation toggle that hides development UI, world
  labels, and NPC name/profession labels without changing simulation state;
- `F12` repeatable simulation-garden demo reset by reloading the current scene
  with the same authored seed and starting state.
- Activity-site capacity enforcement for rest, study, and patrol target
  resolution, derived from NPC target claims rather than presentation-only
  counters.
- Terrain3D collision/navigation hardening began: scaffold and runtime tests
  now assert Terrain3D collision remains enabled, the hidden greybox ground no
  longer provides physics collision, and tested navigation routes stay close to
  the authored Terrain3D height field.
- The temporary greybox navigation source was replaced by a project-owned
  Terrain3D-derived navigation mesh resource generated by
  `tools/bake_jajce_navigation.gd`; route tests now also reject partial paths
  that do not reach their requested targets.
- `Jajce Lookdev 01` is captured and reviewed with a project-owned capture
  script and a daytime baseline image under `docs/baselines/`.
- `Simulation Garden 01` is captured and reviewed from `main.tscn` with paired
  debug/cinematic baselines that verify live NPC visuals in the Terrain3D-backed
  village.
- Runtime task glyphs preserve active NPC task intent in cinematic mode while
  leaving the simulation task state authoritative.
- Runtime first-read staging now includes a presentation camera preset and
  authored path strips that reveal the active village task loop.
- Landmark and work-site silhouette props make the ridge landmark, pantry,
  guard, study, and rest sites easier to identify without debug labels.
- Water and foreground silhouettes strengthened: river/waterfall shaders with
  multi-layer UV flow, fresnel edges, foam highlights, and sparkle; wider river
  and waterfall; fortress with crenellations, three turrets, and prominent
  ridge banner.
- Resource discovery expanded to 18 finite ResourceNodes across farming,
  deep-forest, river-bank, and mill-adjacent contexts with scored metadata.
- NPC schedules implemented: SLEEP/MEAL/WORK/DISCRETIONARY periods driven by
  simulation clock time-of-day. DayNightCycle synced to simulation clock. NPCs
  walk home to designated house positions at night, sleep to restore energy,
  eat at meal times, and work during the day. Starving NPCs always override
  sleep to seek food.
- Starvation balance reworked: hunger ~25/day, death threshold ~3 days of
  starvation (realistic ~6-7 day survival without food). Energy drain uses
  exact binary fractions for lossless JSON serialization.
- Wood inventory and woodpile storage: wood now follows the same
  gather→carry→deposit pattern as food. VillageWoodpile StorageNode receives
  wood deposits. Village wood syncs from storage. Economic events track all
  transfers. Patrol and study no longer produce benefits without paying their
  one-wood cost, and utility selection avoids those actions when wood is empty.
- Action completion costs are definition-backed: patrol and study share one
  stored-resource contract across selection and execution. The inspector shows
  readable unavailable reasons, and a late shortfall creates a persisted
  `task_blocked` fact with stable action/resource/requirement fields without
  applying the work effect.
- Structured event feed: EconomicEventRecord now supports narrative events
  (task started, NPC slept, NPC died) alongside economic transfers.
  Per-NPC event history with human-readable descriptions exposed in the
  inspector under a "Recent" timeline.

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.