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