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; simulation authority is governed by ADR 0001.

Before runtime terrain integration, food and wood should migrate from abstract zones to actual finite world objects according to the ResourceNode migration plan. 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 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:

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:

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:

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:

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, 24 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. A cinematic/debug toggle and repeatable demo reset remain Phase 6 capture tooling.

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:

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

Next:

1. Capture and visually review “Jajce Lookdev 01.”
2. Add the cinematic/debug toggle and repeatable demo reset.
3. Capture “Simulation Garden 01.”

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.