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:

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

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

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

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

Next:

1. Continue growing resource discovery with finite ResourceNode instances
   placed in meaningful contexts (from LEARNING_ROADMAP). See the roadmap
   for the next systems priority.

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.