gamedev-the-steward/docs/BUILD_IN_PUBLIC_PLAN.md

# The Steward — Build-in-Public Visual Slice Plan

## Purpose

This plan adapts the proposed “Jajce simulation garden” to the repository as it
exists now. It does not assume a blank project.

The immediate visual goal is to replace the flat prototype presentation with a
small, attractive, watchable environment while preserving the working NPC
simulation, player controls, UI, task lifecycle, and navigation behavior.

This is a scoped visual-production plan. Milestone order and architecture gates
are owned by [the learning roadmap](LEARNING_ROADMAP.md); simulation authority
is governed by [ADR 0001](decisions/0001-simulation-authority-boundary.md).

Before runtime terrain integration, food and wood should migrate from abstract
zones to actual finite world objects according to
[the ResourceNode migration plan](RESOURCE_NODE_MIGRATION.md). This prevents the
new environment from being authored around a zone model already marked for
removal.

The slice should make a viewer understand this promise quickly:

> A cozy Bosnian-inspired world where autonomous people visibly make decisions,
> work, struggle, and create stories.

This is not a plan to build the full city of Jajce. It is a plan to create one
strong visual composition that can host the current simulation and grow with
future systems.

## What already exists

Do not redo these tasks:

- Godot 4.7 project configuration;
- Terrain3D 1.0.2 installed and enabled;
- cross-platform Git configuration;
- working `main.tscn`;
- camera-relative player movement and elevated follow camera;
- three autonomous simulated NPCs;
- hunger, energy, starvation, death, task scoring, and task duration;
- task-change and village-change signals;
- visual NPC navigation and arrival reporting;
- finite berry/tree/animal-camp ResourceNodes plus typed food, guard, study,
  and rest world sites;
- aggregate village UI;
- initial tree assets;
- a baked navigation region for the current flat test area.

Terrain3D's bundled `demo/` directory and most of `addons/terrain_3d/` are
plugin content. They are references, not the game.

## Current architectural constraint

`main.tscn` currently owns several different concerns:

```text
Main
├── JajceWorld
├── Player
├── CameraRig
├── SimulationManager
├── WorldViewManager
├── ActiveNPCs
├── typed world sites inside JajceWorld/WorldObjects
├── WorldEnvironment
└── UI
```

The player still references interactable world sites through exported `NodePath`
values. `NpcVisual` relies on the navigation map to reach typed `ActivitySite`,
`StorageNode`, and `ResourceNode` interaction points.

Replacing the ground without respecting those references would break behavior
that already works.

## Adjusted scene strategy

Create a reusable environment scene and instance it into the existing runtime.
Keep game orchestration in `main.tscn`.

Target structure:

```text
Main
├── JajceWorld                         instanced environment
│   ├── TerrainRoot
│   │   └── Terrain3D
│   ├── WaterRoot
│   ├── VillageRoot
│   ├── FoliageRoot
│   ├── NavigationRegion3D
│   ├── WorldObjects
│   │   ├── ResourceNodes
│   │       ├── BerryBush instances
│   │       └── Tree instances
│   │   ├── StorageSites
│   │   │   └── VillagePantry
│   │   └── ActivitySites
│   │       ├── GuardPost
│   │       ├── StudyDesk
│   │       └── RestBench
│   ├── DirectionalLight3D
│   └── WorldEnvironment
├── Player
├── CameraRig
├── SimulationManager
├── WorldViewManager
├── ActiveNPCs
└── UI
```

`JajceWorld` should contain geography and world-object presentations. The former
legacy interaction locations now live as typed storage and activity sites under
`WorldObjects`; `JajceWorld` should not own `SimulationManager`, simulated NPC
data, player state, or UI.

Create a small look-development wrapper that instances the same world:

```text
JajceLookdev
├── JajceWorld
└── BeautyCameraRig
```

This provides a cinematic workbench without creating a second environment that
later has to be rebuilt for gameplay.

## Adjusted file structure

Follow the repository's existing feature-oriented layout. Do not create six
empty sub-scenes merely to match a theoretical architecture.

Start with:

```text
world/
└── jajce/
    ├── JajceWorld.tscn
    ├── JajceLookdev.tscn
    └── beauty_camera.gd

terrain/
└── jajce/
    ├── data/
    ├── materials/
    ├── textures/
    └── source/

assets/
└── jajce/
    ├── buildings/
    ├── foliage/
    ├── rocks/
    ├── props/
    ├── water/
    └── vfx/
```

Extract `JajceWater`, `JajceVillageBlockout`, or other components into their own
scenes only when they have meaningful internal behavior or are reused. Avoid
scaffolding an elaborate directory tree before assets exist.

## Visual target

Build a compressed, game-readable Jajce-inspired valley:

| Inspiration | First-slice interpretation |
| --- | --- |
| Hilltop fortress | One strong blockout silhouette on the ridge |
| Old town slope | Four to six house blocks following two terraces |
| Pliva/Vrbas water | One main river and a suggested secondary channel |
| Waterfall | Hero mesh/VFX feature visible from the main camera |
| Watermills | One working mill silhouette, with room for later expansion |
| Forested hills | Terrain3D foliage clusters and background tree masses |
| Agricultural outskirts | Existing farm and forest jobs integrated into terrain |
| Regional roads | One readable loop connecting world objects and legacy targets |

The fortress, waterfall, roofs, player, and at least two working NPCs should be
readable in one strong composition.

## Scope

### First terrain size

Start around **512 m × 512 m**. The playable and polished area can be smaller
inside it.

Do not begin at 1024 m simply because Terrain3D supports it. Expand only when
the current camera, navigation routes, and composition need more space.

### First material set

Use at most six terrain surfaces:

1. soft grass;
2. dirt path;
3. warm cliff stone;
4. wet riverbank stone;
5. forest floor;
6. compacted village ground.

The material set should establish large readable areas. Avoid high-frequency
photorealistic noise.

### First architecture set

Use:

- one fortress silhouette;
- four to six house blockouts;
- one mill;
- one bridge;
- a few fences, carts, sacks, logs, and work props.

Do not begin with 12–20 finished houses. The first shot needs composition, not
an asset catalog.

## Art direction rules

Translate the desired animated-film warmth into an original style:

Keep the gameplay camera as an elevated third-person/top-down player follow
with gentle dead-zone lag. This supports the cozy farm-builder read and lets
the player watch several villagers at once. Presentation presets may stage the
same camera for repeatable captures, but should not replace gameplay with a
free orbit or close over-the-shoulder view.

| Element | Direction |
| --- | --- |
| Terrain | Broad painterly color regions and exaggerated silhouettes |
| Grass | Soft masses and restrained sway, not dense visual noise |
| Trees | Rounded canopies, varied scale, simple readable trunks |
| Rocks | Chunky warm-gray forms with low-frequency detail |
| Buildings | Light plaster/stone, warm roofs, dark timber accents |
| Water | Turquoise/emerald body, strong foam shapes, soft reflection |
| Lighting | Warm sun, cool shadows, mild atmospheric haze |
| Characters | Simple proportions, clear profession colors and props |
| Motion | Wind, water, smoke, leaves, cloth, birds, and purposeful NPC travel |

Cozy presentation does not remove scarcity, death, conflict, or ambition. It
makes the world pleasant to inhabit and the people pleasant to watch.

## Implementation phases

### Phase 0 — Preserve and capture the baseline 🔶 automated baseline complete

Before replacing anything:

- run the current prototype;
- record a short baseline clip or screenshots;
- record the development machine's frame time and obvious scene statistics;
- verify all six task locations can be reached;
- verify starvation, work completion, and death still function;
- note current camera framing and movement feel.

This becomes both a regression reference and excellent before/after material.

### Exit condition

There is a reproducible baseline showing the existing flat prototype and its
working behaviors.

`tests/jajce_runtime_integration_test.gd` and
`docs/baselines/FLAT_MAP_BASELINE.md` establish the executable behavior
baseline. A visual before-clip and frame-time capture remain useful content work
but do not block the architecture gate.

### Systems prerequisite — Migrate food and wood targets ✅ complete

Implement and validate the first ResourceNodes on the current flat map before
moving the playable runtime onto Terrain3D:

- berry bushes for `gather_food`;
- trees for `gather_wood`;
- stable target IDs;
- nearest-available selection;
- single-user reservation;
- extraction after work completion;
- depletion and replanning;
- actual extracted amount applied to the village;
- player interaction through the same extraction contract.

Keep the other task zones temporarily. Rest, eating, study, and patrol will
eventually use activity, storage, or workstation targets rather than pretending
to be resource sources.

### Exit condition

Food and wood work without their zones during normal play, resource conservation
holds, and target failure does not leave a permanent reservation.

### Phase 1 — Create the reusable world scaffold ✅ complete

Create `world/jajce/JajceWorld.tscn` with:

- Terrain3D and dedicated terrain data;
- placeholder `WaterRoot`;
- placeholder `VillageRoot`;
- placeholder `FoliageRoot`;
- a navigation region;
- resource-node, storage-site, and activity-site containers;
- lighting and environment.

Create `JajceLookdev.tscn` that instances `JajceWorld` and adds a temporary
beauty camera.

Do not migrate `main.tscn` yet. Do not duplicate simulation scripts inside the
look-development scene.

### Exit condition

The same `JajceWorld` instance can open in the lookdev scene and can be instanced
under a temporary runtime test without errors.

Implemented in `556d0fd` with dedicated Terrain3D seed data, reusable world and
lookdev scenes, environment roots, stable-ID ResourceNodes, activity markers,
and a headless scaffold test.

### Phase 2 — Greybox the hero composition ✅ initial proof complete

Sculpt by hand before attempting GIS/DEM import:

- one dominant ridge;
- descending town terraces;
- main river valley;
- waterfall drop;
- lower pool;
- farm shelf;
- forest work area;
- a walkable road loop connecting world objects and remaining legacy locations.

Block out the fortress, houses, mill, bridge, and waterfall with primitives or
simple meshes.

Place the beauty camera early. Terrain should be judged through the intended
game and video cameras, not only from the editor's free camera.

### Navigation spike

Do an early rough navigation bake now. Do not wait until final art.

The purpose is to detect:

- slopes that are too steep;
- terraces that cannot connect;
- paths too narrow for agents;
- waterfall or river barriers that split required routes;
- terrain collision or navigation incompatibilities.

The final navigation bake still happens after terrain and props stabilize.

### Exit condition

One static frame contains the ridge landmark, roofs, river/waterfall, and
village work area. A test agent can traverse the intended task loop.

The initial proof uses primitive ridge, fortress, terrace, house, mill, bridge,
river, and waterfall silhouettes plus a temporary baked navigation loop. The
Terrain3D seed remains flat; sculpt refinement and the final bake resume only
after the architecture gate.

### Systems gate — Harden simulation authority ✅ complete

After the scaffold, greybox, and navigation spike prove the world shape, pause
visual production and complete the mandatory architecture gate from the
learning roadmap:

- deterministic clock and seeded randomness; ✅
- fixed-seed headless scenarios and final-state checksum; ✅
- versioned serializable NPC, village, resource, clock, and RNG records; ✅
- resource amount and reservation authority outside scene nodes; ✅
- stable action/profession IDs and initial definitions; ✅
- separate action selection, execution, target resolution, and visual travel; ✅
- explicit active-position synchronization. ✅

Do not solve this by moving simulation ownership into `JajceWorld`. The
environment remains a presentation and active-world query surface.

### Exit condition

The same scenario produces the same result without `main.tscn`; unloading a
visual does not change authoritative state; current resource and movement
behavior still pass regression tests.

Completed with deterministic continuation, simulation-owned resources,
definition-backed IDs, separated action responsibilities, active position
synchronization, and visual unload/reload invariance tests.

### Phase 3 — Establish the beauty baseline

Add only the highest-value presentation:

- six terrain materials;
- warm `WorldEnvironment`;
- directional light and atmospheric haze;
- simple river surface;
- waterfall body, foam, and mist;
- first foliage clusters using Terrain3D instancing where appropriate;
- restrained grass/tree motion;
- chimney smoke;
- slow beauty-camera drift.

Avoid expensive water, dense individual grass nodes, and elaborate weather at
this stage.

**Status: implementation complete.** The integrated world now has six
Terrain3D layers, shaped terrain data, warm sky/fog/shadows, shader-driven
river and waterfall surfaces, waterfall mist, authored building blockouts,
wind-reactive foliage, chimney smoke, and beauty-camera drift. Automated
coverage validates the texture contract, presentation nodes, terrain shape,
stable resources, and navigation. Clip capture and a visual performance review
remain presentation checkpoints rather than missing implementation.

`Jajce Center 02` adds the first reviewed composition pass beyond that baseline:
the summit citadel and residential roof amphitheater read as one center, the
waterfall feeds a Terrain3D-sampled turquoise ribbon, and bounded camera-local
grass, conifers, richer deciduous silhouettes, and oversized butterflies add
life without changing simulation authority. The matched review lives in
[`baselines/JAJCE_CENTER_02.md`](baselines/JAJCE_CENTER_02.md).

The world now also has a structural weak-PC contract. High restores that
authored look; Balanced is the runtime default at 85% 3D scale with ordinary
fog, shorter two-split shadows, roughly half the grass, fewer interactors, and
no volumetric fog; Low uses 70% 3D scale, one short shadow region, disables
glow/volumetric fog/color adjustment, and stops grass rendering and processing.
Use `-- --quality=high|balanced|low` for reproducible runs. Headless regression
proves the profiles are reversible, presentation-only, resource-isolated, and
warning-clean under Compatibility feature selection. This does not exercise a
real OpenGL GPU because headless Godot uses its dummy renderer. A representative
weak-PC High/Low capture with CPU/GPU p50/p95, memory, and draw statistics is
still required before claiming the visual frame-time exit condition.

### Exit condition

The lookdev scene can produce a compelling 10–20 second clip with no gameplay.
The environment remains within the recorded prototype's agreed performance
budget.

### Phase 4 — Integrate the existing game

Once the world composition is stable:

1. Instance `JajceWorld` into `main.tscn`.
2. Disable or remove the old flat world only after the new instance is present.
3. Place or move bushes and trees under
   `JajceWorld/WorldObjects/ResourceNodes` while preserving stable IDs.
4. Reconnect remaining non-resource activities as typed sites under
   `JajceWorld/WorldObjects`.
5. Bake navigation for the new walkable area.
6. Test each existing task from multiple spawn positions.
7. Verify task arrival still transitions from traveling to working.
8. Verify task completion still changes village state.
9. Verify depletion and reservations survive the scene migration.
10. Verify player interaction ranges still make sense at the new scale.
11. Verify dead NPC visuals do not block routes or retain reservations.
12. Compare performance and behavior against the Phase 0 baseline.

Do not move simulation ownership into `JajceWorld` to make wiring convenient.

**Status: runtime integration complete.** `main.tscn` now instances the reusable
world and points player/simulation adapters at its stable-ID resources, storage
site, and activity sites. The duplicate flat world objects were removed.
The runtime regression checks Terrain3D presence, 36 navigation routes, core
task execution, starvation/death, player extraction parity, reservations, and
NPC visual lifecycle. Terrain sculpting and presentation polish remain
separate work, not blockers for this wiring milestone.

### Exit condition

The current six NPCs and player can perform all existing prototype behaviors
inside the new terrain without regression.

### Phase 5 — Make the simulation readable on video

Add presentation for systems that already exist:

- simple stylized NPC placeholder instead of capsules;
- profession color/prop distinctions;
- compact task/need icon above selected or relevant NPCs;
- name labels when useful;
- an NPC reason inspector for development footage;
- visible food, logs, guard, study, rest, and eating props;
- cinematic/debug UI toggle;
- a scenario reset and fixed seed for repeatable clips.

Do not fake activity that contradicts simulation state. A farmer icon should
represent a real chosen task.

**Status: core readability complete.** Profession definitions now drive
distinct NPC colors and props, world labels identify each villager, and the
Tab-cycled inspector shows authoritative need values, task state, destination,
decision branch, and utility scores. The existing carried-food prop and village
panel expose immediate consequences. `F10` toggles the debug/cinematic
presentation layer, while `F12` reloads the current scene as a repeatable
simulation-garden demo reset. The capsule NPCs have now been replaced by
multi-part stylized villager placeholders with tunics, heads, hair, limbs,
feet, and state-driven walk motion. Carried wood displays as a log bundle from
authoritative inventory, matching the existing carried-food presentation.

### Exit condition

A viewer can distinguish at least three professions and understand one NPC's
need, destination, and consequence without reading console output.

### Phase 6 — Produce the first public demo sequence

Capture a short sequence with a clear story:

1. establish the valley and waterfall;
2. introduce one named NPC;
3. show the NPC choosing and traveling to work;
4. reveal the reason through a concise overlay;
5. show the work changing a real village resource;
6. end on either recovery or a visible shortage consequence.

The best first character is one of the existing named NPCs—Amina, Tarik, or
Jasmin—rather than an unnamed cinematic extra.

### Exit condition

The clip has an understandable beginning, decision, and consequence. It does not
depend on a voiceover to prove that the simulation is real.

**Status: complete.** `F11` reloads the fixed authored start and runs one
cinematic pantry-crisis story: a brief valley establishment, the empty pantry
and worried villager, a trusted helper's real finite-resource trip, visible
carrying, deposit, and physical recovery. Four short cardless captions fade over
the world while the camera hands off from the pantry to the helper. The same
withdrawal, consumption, extraction, and deposit records drive the need and its
resolution. `tools/validate_pantry_crisis_demo.gd` verifies that the unassisted
route completes inside the 20–30 second budget.

## Build-in-public content pillars

Rotate between four types of updates.

### 1. Transformation

Show visible before/after progress:

- flat test ground to Jajce-inspired valley;
- blockout waterfall to mist and foam;
- capsules to readable professions;
- empty paths to visible work traffic.

### 2. Tiny autonomous stories

Use one named NPC and one question:

- Why did Amina stop guarding?
- Can Tarik gather food before starvation?
- Why is Jasmin resting while the village is short on wood?
- What happens when the food route is blocked?

### 3. System under the beauty

Show a beautiful shot, then reveal the debug reason trace, event, or resource
flow that drives it.

### 4. Learning Godot publicly

Frame honest engineering lessons:

- Terrain3D sculpting and material mistakes;
- navigation problems caused by terrain;
- making NPC simulation deterministic;
- profiling foliage versus agent cost;
- separating simulation data from visual scenes.

## Short-form video template

For TikTok, Shorts, or brief social posts:

```text
0–2 s    Show the outcome or surprising NPC behavior
2–5 s    State one question
5–15 s   Show the cause unfolding
15–25 s  Reveal the systemic consequence
End      Show the next unresolved problem
```

Use captions and strong visual causality. Avoid opening with a long editor tour.

## Initial video backlog

1. **“I replaced my programmer map with a Bosnian-inspired valley.”**
2. **“This villager chose food over their profession—and here is why.”**
3. **“The village can starve without a scripted quest.”**
4. **“Every NPC physically walks to the work they selected.”**
5. **“One blocked path broke the village economy.”**
6. **“Making a Jajce-inspired waterfall in Godot Terrain3D.”**
7. **“The same scene in cinematic mode and simulation-debug mode.”**
8. **“Can three autonomous villagers survive this shortage?”**

Each video should correspond to real repository progress. Do not build isolated
visual tricks solely for a post unless they also support the intended game.

## Performance guardrails

- Record frame time before adding terrain.
- Treat Terrain3D instancing as the default for broad foliage where suitable.
- Avoid physics and navigation obstacles on distant decorative vegetation.
- Keep waterfall mist and smoke particle counts bounded.
- Use simple water before adding screen-space reflection or refraction.
- Test the gameplay camera, not only the beauty camera.
- Profile editor and exported builds separately when export work begins.
- Recheck navigation cost after every meaningful terrain expansion.
- Do not increase NPC population while diagnosing environment cost.

## Source-control guardrails

- Commit Terrain3D data and game-authored terrain assets.
- Continue ignoring `.godot/` and other imported caches.
- Keep Godot `.import` and `.uid` sidecars tracked.
- Do not modify or reformat the third-party Terrain3D addon incidentally.
- Keep lookdev assets under game-owned paths, not inside the addon.
- Make environment, integration, and simulation changes separate commits where
  practical.

## Definition of “Jajce Lookdev 01”

The adjusted first milestone is complete when:

- Terrain3D is used by `JajceWorld`; installation itself is already complete.
- One approximately 512 m terrain exists.
- Fortress ridge, town terraces, river valley, and waterfall drop are readable.
- Six or fewer terrain materials establish the major surfaces.
- One fortress, four to six houses, one mill, and one bridge are blocked out.
- River, waterfall foam, mist, warm lighting, and first foliage are present.
- A beauty camera produces a strong 10–20 second shot.
- A rough navigation test proves the main route is viable.
- The existing simulation has not yet been duplicated or moved.

## Definition of “Simulation Garden 01”

The follow-up milestone is complete when:

- `JajceWorld` is instanced in `main.tscn`;
- scattered food and wood ResourceNodes work in the terrain;
- remaining legacy task markers are reconnected;
- player movement and all existing interactions work;
- all three current NPCs navigate, work, eat, rest, starve, and die correctly;
- one NPC's decision is readable through in-game presentation;
- cinematic and debug views can show the same real scenario;
- a repeatable public-demo clip shows an autonomous cause and consequence;
- performance and navigation regressions are measured and documented.
- the mandatory architecture gate passes before final beauty integration.

## Immediate implementation order

Completed:

1. Executable flat-map baseline.
2. ResourceNode migration and player parity.
3. `JajceWorld`, dedicated 512 m Terrain3D seed, and lookdev camera.
4. Initial landmark greybox, stable-ID resources, activity markers, and
   navigation spike.
5. Architecture gate, food transactions/events, and validated quicksave.
6. `JajceWorld` runtime integration with bindings and regression coverage.
7. Bounded Jajce beauty baseline with six terrain layers, water, atmosphere,
   foliage motion, building blockouts, and smoke.
8. Base Terrain3D collision/navigation guardrails: runtime tests now keep
   Terrain3D collision enabled, keep the old greybox ground out of physics, and
   verify required navigation paths track the authored height field.
9. Terrain3D-derived playable-loop navigation: `JajceWorld` now uses an
   external baked navigation resource generated from Terrain3D source geometry,
   and runtime tests reject partial paths that do not reach their targets.
10. `Jajce Lookdev 01` capture and review: a reproducible capture tool writes
    the daytime lookdev baseline to `docs/baselines/jajce_lookdev_01.png`, and
    the review notes the current strengths and visual follow-ups.
11. `Simulation Garden 01` capture and review: a reproducible runtime capture
    tool writes debug and cinematic `main.tscn` baselines to `docs/baselines/`
    and verifies live NPC visuals in the terrain-backed village.
12. Runtime task glyphs: active NPCs now keep compact task-intent markers in
    cinematic mode while debug names, labels, and inspector UI remain optional.
13. Runtime first-read staging: the capture tool uses an explicit presentation
    camera preset, the gameplay camera supports the same staging API, and the
    village has authored dirt path strips for the current task loop.
14. Landmark and work-site silhouettes: the ridge landmark, pantry, guard post,
    study desk, and rest bench now have compact presentation props that remain
    readable in the runtime cinematic frame.

Completed:

15. Water and foreground silhouette strengthening: river/waterfall shaders
    now include multi-layer UV flow, fresnel edges, foam highlights, sparkle
    specular, and better color depth; the waterfall has distinct foam bands
    and rim transparency; mist particle count and spread increased; the river
    and waterfall widened; the fortress ridge landmark now has crenellations,
    a dedicated banner pole with larger banner, and three turrets for a more
    readable silhouette against the sky.
16. Stylized villager readability and VFX cleanup: NPCs now use compact
    multi-part silhouettes with state-driven walk motion and visible carried
    logs. Waterfall mist is anchored to the waterfall instead of the village
    origin, duplicate wind layers are separated, and Metal smoke/wind
    materials retain restrained transparency.
17. Coherent breeze pass: overlapping valley-wide white stroke/speck emitters
    were removed. Tree canopies now bend gently in one prevailing direction
    with stable per-tree phase and slow gust variation, while chimney smoke
    leans with the same breeze. Day/night lighting now follows the simulation
    clock even when the world initializes first, with the sunrise/sunset tints
    applied in the correct order. The gameplay camera remains unchanged.
18. Stylized player readability: the remaining gray player capsule is replaced
    by a compact multi-part figure with a warm scarf/satchel accent and
    velocity-driven walk motion. Collision, controls, and the elevated
    staggered follow camera remain unchanged.
19. Event-caused trust consequence: hungry familiar NPCs can gain directed
    trust from a real food-deposit event, retain that event as the inspectable
    cause, and redirect ordinary work to help a starving acquaintance. The
    state is versioned and deterministic rather than presentation-only flavor.
20. Calligraphic gust ambience: one terrain-aware controller now emits only
    two or three tapered sage/amber/aqua ribbons at a time, with long quiet
    intervals and a shared canopy/smoke direction. The shader draws each line
    head-to-tail like a soft brush mark; repeated bursts cannot stack into the
    old scratch/gnat field.
21. Witnessed event knowledge: objective food-deposit events create separate
    known-event references for their actor and nearby living NPCs. Knowledge
    gates trust, produces a real informed-versus-uninformed choice divergence,
    survives versioned save/load, and appears in the NPC inspector.
22. Co-worker fact communication: known-event records retain performed,
    witnessed, communicated, or legacy acquisition provenance. An arriving NPC
    can hear one direct fact from a nearby worker at the same non-storage
    activity; the inspector names the speaker, the original event is not
    replayed, and heard facts do not cascade yet.
23. Bounded memory retention: acquisition time now drives fact recency; current
    relationship causes remain lasting while each NPC keeps only three other
    recent facts. A deterministic daily-sized review fades old routine facts,
    conversations prefer lasting evidence, and the inspector shows both memory
    counts and the displayed fact's retention class.
24. Person history and trust blossom: the selected-NPC inspector now separates
    up to four lasting-first retained memories from three objective personal
    actions. A real evidence-caused trust gain produces one short amber blossom
    above its observer, including in cinematic mode, without persistent or
    simulation-owned animation state.
25. Knowledge-gated village need: a compact, cardless `Village need` line now
    shows the real pantry target, food progress, and interested villager. That
    person's inspector retains the open/resolved lifecycle and names the exact
    NPC or player supply actor. The repeatable debug capture stages this from
    live simulation state; world framing and the elevated follow camera remain
    unchanged.
26. Physical pantry crisis payoff: the pantry now replaces its inherited
    generic crate with empty, low, and stocked arrangements driven by real
    storage state. Only the interested villager receives a small state-derived
    concern cue; a real deposit clears it and briefly animates the refilled
    pantry. The capture tool writes an edit-ready empty/restocked close pair
    while leaving gameplay camera defaults and simulation authority unchanged.
27. Missing-wood village need: a real patrol/study shortfall now opens one
    wood-specific need from its structured `task_blocked` fact. NPC deposit and
    player tree-harvest resolutions use real economy history; interested-party
    death and one-day staleness close the need cleanly. The compact UI explains
    the blocked action without reusing the pantry's hunger cue.
28. Explainable capable helper: an open food or wood need now names one
    deterministic informed and trusted villager plus the ordinary gather or
    deposit action and real inventory/resource route that makes them capable.
    The result is re-derived after restore and does not assign work or alter the
    simulation.
29. Autonomous capable helper: the matching idle villager now consumes that
    ephemeral result through ordinary action selection after urgent self-care
    and sleep/meal precedence. Existing target resolution chooses and reserves
    the finite source, while no quest acceptance, reward, or helper assignment
    is introduced.
30. Village whisper: direct witnesses/performers now report the active need's
    exact trigger before unrelated facts at shared work, allowing a newly
    informed trusted helper to respond autonomously. One cardless warm-amber HUD
    ribbon gently rises, pulses, and fades through need, named report, response,
    and resolution beats while remaining separate from development overlays.
31. Player response whisper: when no capable helper exists, the same ribbon now
    derives one concise ordinary harvest route from current player-usable finite
    resources and the real pantry or woodpile. It clears when help emerges or
    the need closes, and adds no quest, waypoint, tracker, or saved UI state.
32. Deterministic scaling baseline: one schema-valid full-fidelity fixture now
    drives a repeatable CLI ledger and fast headless regression across rising
    NPC and event counts. The first reviewed capture sets a local 600-NPC target,
    records identical checksums across samples, and exposes repeated scarce-food
    population scans plus objective-event growth as the next measured work.
33. Shared population query view: stable-ID all/living/starving indexes are
    built once per deterministic tick and refreshed through interleaved NPC
    updates. Baseline 02 preserves every checksum and improves the 600-NPC case
    by 23.3% without simulation LOD.
34. `Jajce Center 02`: the reviewed matched capture strengthens the citadel,
    cascading homes, bridge, waterfall, terrain-following river, conifer/tree
    clusters, and ambient butterflies. Roughly 10,400 camera-local grass
    particles remain short and patchy and bend from real actor transforms.
35. Loaded-resource spatial discovery: `ActiveWorldAdapter` now indexes loaded
    stable-ID resource anchors in a resource-specific horizontal grid. Exact
    expanding queries preserve current scoring and selected targets while the
    reviewed 1,800-source case inspects about 4.4 candidates instead of 1,800.
36. `Jajce River 03`: the deterministic Terrain3D source now carves a raised
    waterfall shelf, upper stream, plunge basin, and curved downstream channel.
    Shared watercourse profiles keep generated terrain and both water ribbons
    aligned; softened foam/mist and a smaller rock frame make the falls part of
    the landform. A matched Metal capture records the change, and the rebaked
    navigation mesh passes terrain-height and runtime route checks.
37. `Jajce Resource Grove 04`: the right riverbank now groups 28 intentionally
    instanced fern/flower/stone details and two decorative trees around two
    existing finite resources. The berry and tree keep their stable IDs and
    metadata, use specific visuals instead of boxes, and remain reachable from
    separate terrain-snapped approach points. Matched captures and a focused
    scenario prove three-batch visual cost, nested discovery, and a forced
    query beyond the first 24 m range without changing the 18-resource state.
38. `Jajce Resource States 05`: a shared amount-derived presentation contract
    now gives that berry and tree honest full, low, and depleted states. Real
    player berry harvests thin fruit and leaves; real NPC wood gathers thin the
    crown and leave a stump. Low and depleted saves restore the same visuals
    using only `amount_remaining`, with matched Metal comparison frames.
39. `Jajce Forest Edge 06`: `tree_forest_grove_01` and
    `tree_forest_grove_02` now anchor a bounded forest-edge cluster beyond the
    first 24 m discovery pass. Two decorative trees plus 24 fern, mushroom, and
    stone instances stay presentation-only. Both finite trees remain reachable,
    deplete into shared stumps, restore from authoritative amount, and keep the
    world/save total at eighteen resources.
40. `Jajce Goat 07`: Dunja is the first identity-backed animal, with a stable
    goat ID, simulation-owned position and hunger, and a loaded cozy
    presentation with an honest hungry cue. NPC and player feeding share one
    exact target mutation backed by real food that changes only Dunja's state
    and emits one exact `animal_fed` fact. World-schema v10 save/restore
    preserves the result without replaying the transient feed response.
41. `Jajce Dunja Habitat 08`: a self-contained timber shelter and clover
    pasture now expose two stable routine sites in an open south-village
    clearing. Dunja alternates between them without RNG, follows the real
    Jajce navigation map, bends nearby grass, stops when hungry, and preserves
    exact mid-route state through schema-v11 restore and presentation
    unload/reload. The animal feature assets now live together under
    `world/animals/goat/`, while ignored docs no longer create import sidecars.
42. `Jajce Goat Pair 09`: Zora now joins Dunja as a second named, stable animal
    with an authored private shelter and deterministic access to the shared
    pasture. Simultaneous hunger selects the nearest available loaded goat,
    preserves two exact reservations through save/restore, and feeds only the
    named target. Private shelter ownership remains loaded-world context; no
    herd system, animal index, or schema bump was introduced.
43. `Jajce Context Action 10`: the existing `E` interactions now derive one
    exact ephemeral result shared by prompt and execution. A restrained,
    cardless bottom-center HUD names the nearest hungry goat, shows real pantry
    availability, reports success or blockage, remains visible in cinematic
    mode, and also covers existing resource, pantry, guard, and study actions.
    Restore discards transient feedback and re-derives context from live facts.
44. `Jajce Care Delivery 11`: NPC animal care now keeps one exact named-goat
    claim while walking first to the real pantry and then to that goat. Pantry
    pickup creates authoritative carried inventory and reveals the existing
    food sack; delivery consumes that unit and records the inventory-to-animal
    fact. One-unit contention, both route legs, and post-pickup continuation
    prove conservation without adding a saved phase field.
45. `Jajce Villager Field Note 12`: a quiet bottom-left field note now selects
    the nearest loaded living villager with stable-ID tie order and presents
    their authoritative name, current action and task state, exact target, and
    carried inventory. A decision reason appears only while it matches the live
    action; unload clears the note and restore re-derives saved facts while
    awaiting the next transient reason. The note coexists with the `E` prompt,
    remains in cinematic mode, and adds no saved state or simulation mutation.
46. `Jajce Field Note Need 13`: the same field note now surfaces the inspected
    villager's exact open village need, its real progress, and whichever
    authoritative response currently exists — the capable helper, the player
    finite-source route, or an honest unavailable state. A real player
    harvest-to-pantry deposit resolves it through the ordinary carry path
    without dialogue, acceptance, or quest state.
47. `Jajce Citizen Player 14`: the player becomes a citizen. A persisted
    `PlayerStateRecord` tracks hunger, energy, and carried inventory; gathering
    fills the pack, depositing restocks typed storage, and eating eases hunger.
    A bottom-center status line makes the loop readable, and nearby villagers
    witness and can trust a real pantry restock.
48. `Jajce Care Needs 15`: two more village needs join the family — a starving
    low-energy villager who cannot feed themselves (`feed_weak_villager`,
    resolved only when that villager eats) and a damaged roof after a low-safety
    night (`repair_home_roof`, resolved through the wood deposit path).
49. `Jajce Seasons 16`: a deterministic four-day seasonal cycle halves gather
    yields and pauses berry regrowth on the cold day, so the garden keeps
    producing real scarcity the player can help address.
50. Runtime health and weak-PC pass: the default Balanced presentation tier
    removes volumetric fog, halves grass density, lowers 3D scale, and shortens
    shadows; Low stops grass and costly effects while High remains reversible.
    UI/environment probes are rate-limited, failed creature paths back off,
    player resource prompts use the loaded-anchor grid, and simulation/combat
    ID callbacks use disposable indexes. Combat authority now enforces range,
    faction, unscaled player cooldown, recovery, melee approach, death ordering,
    and real pantry plunder. Benchmark workload v2 validates one combatant per synthetic
    NPC and records 90.63 ticks/s at 600 records with stable checksums.

Next:

1. Let finite berry sources that the player helps regrow feel owned: a bounded
   replanting interaction for depleted sources and, later, a planted resource
   that appears at a fixed plot after a deterministic delay.
2. Let population growth emerge from a built house: a new named villager arrives
   after a seeded delay and joins the profession registry, with arrival covered
   by the scaling fixture.
3. Add a market/traveler cadence so the returning player finds something new:
   a traveler who shares one rumour or a bounded food-for-wood exchange.

Do not start with GIS data, a full city, a large asset pack, or more NPC
mechanics. The next proof is a beautiful stage for the systems that already
exist.