fix: empty-path re-entrancy, retry_count reset, := to = for Variant
This commit is contained in:
@@ -0,0 +1,563 @@
|
||||
# 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.
|
||||
|
||||
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;
|
||||
- farm, forest, food, guard, study, and rest markers;
|
||||
- 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
|
||||
├── current flat World and NavigationRegion3D
|
||||
├── Player
|
||||
├── CameraRig
|
||||
├── SimulationManager
|
||||
├── WorldViewManager
|
||||
├── ActiveNPCs
|
||||
├── TaskZone markers
|
||||
├── WorldEnvironment
|
||||
└── UI
|
||||
```
|
||||
|
||||
The player and `WorldViewManager` reference the task markers through exported
|
||||
`NodePath` values. `NpcVisual` relies on the navigation map to reach those
|
||||
markers.
|
||||
|
||||
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
|
||||
│ ├── LegacyTaskMarkers temporary migration fallback
|
||||
│ │ ├── FarmZone fallback only
|
||||
│ │ ├── ForestZone fallback only
|
||||
│ │ ├── FoodZone
|
||||
│ │ ├── GuardZone
|
||||
│ │ ├── StudyZone
|
||||
│ │ └── RestZone
|
||||
│ ├── DirectionalLight3D
|
||||
│ └── WorldEnvironment
|
||||
├── Player
|
||||
├── CameraRig
|
||||
├── SimulationManager
|
||||
├── WorldViewManager
|
||||
├── ActiveNPCs
|
||||
└── UI
|
||||
```
|
||||
|
||||
`JajceWorld` should contain geography, world-object presentations, and temporary
|
||||
legacy interaction locations. It 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
|
||||
|
||||
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.
|
||||
|
||||
### Systems prerequisite — Migrate food and wood targets
|
||||
|
||||
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;
|
||||
- zone fallback with visible warnings.
|
||||
|
||||
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
|
||||
|
||||
Create `world/jajce/JajceWorld.tscn` with:
|
||||
|
||||
- Terrain3D and dedicated terrain data;
|
||||
- placeholder `WaterRoot`;
|
||||
- placeholder `VillageRoot`;
|
||||
- placeholder `FoliageRoot`;
|
||||
- a navigation region;
|
||||
- resource-node containers plus temporary fallback markers;
|
||||
- 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.
|
||||
|
||||
### Phase 2 — Greybox the hero composition
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
### 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 player and `WorldViewManager` fallbacks to markers under
|
||||
`JajceWorld/LegacyTaskMarkers`.
|
||||
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.
|
||||
|
||||
### Exit condition
|
||||
|
||||
The current three 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.
|
||||
|
||||
### 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`;
|
||||
- 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.
|
||||
|
||||
## Immediate implementation order
|
||||
|
||||
1. Capture the current flat-map baseline.
|
||||
2. Implement and validate ResourceNodes on the flat map.
|
||||
3. Migrate food and wood; keep remaining zones as logged fallbacks.
|
||||
4. Create `JajceWorld.tscn`.
|
||||
5. Create dedicated Terrain3D data under `terrain/jajce/`.
|
||||
6. Create `JajceLookdev.tscn` and its beauty camera.
|
||||
7. Sculpt the ridge, river valley, terraces, and waterfall drop.
|
||||
8. Place ResourceNodes and only the still-required legacy markers.
|
||||
9. Block out the fortress, houses, mill, and bridge.
|
||||
10. Run the early navigation spike.
|
||||
11. Establish terrain materials, lighting, water, mist, and foliage.
|
||||
12. Capture “Jajce Lookdev 01.”
|
||||
13. Instance `JajceWorld` into `main.tscn`.
|
||||
14. Reconnect fallbacks, rebake navigation, and regression-test the simulation.
|
||||
15. Add profession/readability presentation.
|
||||
16. 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.
|
||||
Reference in New Issue
Block a user