From b50fae671a2f2aa949d48cccff48c47174c554d0 Mon Sep 17 00:00:00 2001 From: Rijad Zuzo Date: Sat, 4 Jul 2026 21:08:16 +0200 Subject: [PATCH] docs: mark Jajce scaffold proof complete --- docs/BUILD_IN_PUBLIC_PLAN.md | 55 +++++++++++++++++++++------------ docs/LEARNING_ROADMAP.md | 38 ++++++++++++----------- docs/PROJECT_CONTEXT.md | 42 ++++++++++++++++++++----- docs/RESOURCE_NODE_MIGRATION.md | 9 ++++-- 4 files changed, 98 insertions(+), 46 deletions(-) diff --git a/docs/BUILD_IN_PUBLIC_PLAN.md b/docs/BUILD_IN_PUBLIC_PLAN.md index 09aa766..3ee07e5 100644 --- a/docs/BUILD_IN_PUBLIC_PLAN.md +++ b/docs/BUILD_IN_PUBLIC_PLAN.md @@ -234,7 +234,7 @@ makes the world pleasant to inhabit and the people pleasant to watch. ## Implementation phases -### Phase 0 β€” Preserve and capture the baseline +### Phase 0 β€” Preserve and capture the baseline πŸ”Ά automated baseline complete Before replacing anything: @@ -252,6 +252,11 @@ This becomes both a regression reference and excellent before/after material. There is a reproducible baseline showing the existing flat prototype and its working behaviors. +`tests/flat_map_baseline_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 @@ -276,7 +281,7 @@ to be resource sources. 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 +### Phase 1 β€” Create the reusable world scaffold βœ… complete Create `world/jajce/JajceWorld.tscn` with: @@ -299,7 +304,11 @@ look-development scene. 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 +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: @@ -337,7 +346,12 @@ The final navigation bake still happens after terrain and props stabilize. One static frame contains the ridge landmark, roofs, river/waterfall, and village work area. A test agent can traverse the intended task loop. -### Systems gate β€” Harden simulation authority +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 ⏭ next After the scaffold, greybox, and navigation spike prove the world shape, pause visual production and complete the mandatory architecture gate from the @@ -567,21 +581,24 @@ The follow-up milestone is complete when: ## Immediate implementation order -1. Capture the current flat-map baseline. -2. Treat ResourceNode migration and player parity as complete. -3. Create `JajceWorld.tscn` and dedicated Terrain3D data. -4. Create `JajceLookdev.tscn` and its beauty camera. -5. Greybox the ridge, river valley, terraces, and waterfall drop. -6. Place ResourceNodes with stable IDs and only required activity markers. -7. Block out the fortress, houses, mill, and bridge. -8. Run the early navigation spike. -9. Pass the mandatory architecture gate before beauty production. -10. Establish terrain materials, lighting, water, mist, and foliage. -11. Capture β€œJajce Lookdev 01.” -12. Instance `JajceWorld` into `main.tscn`. -13. Reconnect activity markers, rebake navigation, and run regression scenarios. -14. Add profession/readability presentation and the reason inspector. -15. Capture β€œSimulation Garden 01.” +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. + +Next: + +1. Pass the mandatory architecture gate before beauty production. +2. Sculpt the Terrain3D ridge, river valley, terraces, and waterfall drop. +3. Establish terrain materials, lighting, water, mist, and foliage. +4. Capture β€œJajce Lookdev 01.” +5. Instance `JajceWorld` into `main.tscn`. +6. Reconnect activity markers, rebake navigation, and run regression scenarios. +7. Add profession/readability presentation and the reason inspector. +8. 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 diff --git a/docs/LEARNING_ROADMAP.md b/docs/LEARNING_ROADMAP.md index 7febc20..b29dce9 100644 --- a/docs/LEARNING_ROADMAP.md +++ b/docs/LEARNING_ROADMAP.md @@ -29,9 +29,10 @@ Each milestone should produce five outcomes: Do not advance because files exist. Advance when the exit test passes. The current implementation has completed ResourceNode migration through player -parity. Next, build only the minimal Jajce scaffold and navigation proof, then -pass the architecture gate below before beauty production or broader simulation -features. See [ADR 0001](decisions/0001-simulation-authority-boundary.md). +parity plus the minimal Jajce scaffold and navigation proof. The architecture +gate below is now active and must pass before beauty production or broader +simulation features. See +[ADR 0001](decisions/0001-simulation-authority-boundary.md). ## Mandatory architecture gate @@ -591,29 +592,30 @@ Completed foundations: - finite food and wood `ResourceNode` instances; - NPC target selection, reservation, depletion, and authoritative yield; - player parity through the same extraction contract; -- navigation-failure recovery and an initial headless contention scenario. +- navigation-failure recovery and an initial headless contention scenario; +- executable flat-map baseline; +- 512 m Jajce Terrain3D seed, greybox landmarks, stable-ID resource placement, + lookdev scene, and tested temporary navigation loop. The practical next sequence is: -1. Capture a reproducible flat-map baseline. -2. Create only the minimal `JajceWorld` scaffold, terrain greybox, navigation - spike, and stable-ID resource-placement proof. -3. Begin the architecture gate with deterministic clock/randomness, a headless +1. Begin the architecture gate with deterministic clock/randomness, a headless scenario runner, final-state checksums, and serializable state records. -4. Move resource amount/reservation authority out of `ResourceNode` scenes. -5. Replace free-form task and profession strings with stable IDs and +2. Move resource amount/reservation authority out of `ResourceNode` scenes. +3. Replace free-form task and profession strings with stable IDs and definitions. -6. Separate action selection, execution, target resolution, and visual travel; +4. Separate action selection, execution, target resolution, and visual travel; remove decision mutation from `WorldViewManager`. -7. Define active-position synchronization and prove visual unload/reload. -8. Pass the architecture gate's deterministic headless and unloaded-visual exit +5. Define active-position synchronization and prove visual unload/reload. +6. Pass the architecture gate's deterministic headless and unloaded-visual exit tests. -9. Build location-based food storage, inventory, and transactions. -10. Emit structured economic events while making one NPC visibly gather, carry, +7. Build location-based food storage, inventory, and transactions. +8. Emit structured economic events while making one NPC visibly gather, carry, store, retrieve, and eat food. -11. Add versioned save/load before schedules or social state expand. -12. Resume the attractive Terrain3D simulation-garden beauty pass. -13. Add stylized character and profession readability plus the reason +9. Add versioned save/load before schedules or social state expand. +10. Resume Terrain3D sculpting, runtime integration, and the simulation-garden + beauty pass. +11. Add stylized character and profession readability plus the reason inspector. This order strengthens the simulation while regularly producing visible diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index 6ab0c57..315e4df 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -2,7 +2,7 @@ > Agent-facing context for understanding the project quickly. > -> Snapshot basis: repository state after commit `0900022`, July 2026. Treat the +> Snapshot basis: repository state after commit `556d0fd`, July 2026. Treat the > code as the source of truth when this document and the implementation differ. See the [documentation map](README.md) for the authority and scope of each plan. @@ -191,6 +191,8 @@ non-resource tasks. The migration is documented in - **Language:** GDScript (`odig` analysis with warnings treated as errors) - **Main scene:** `res://main.tscn` - **Terrain:** Terrain3D 1.0.2 is installed and enabled +- **Jajce scaffold:** separate 512 m Terrain3D seed, greybox landmarks, stable + ResourceNode placement, lookdev camera, and temporary navigation spike - **Terrain compatibility floor:** Godot 4.4 according to the bundled extension - **Version control:** Git - **Primary branch:** `main` @@ -313,6 +315,24 @@ Storage, rest, study, and guard behavior should later migrate to target types that match their actual semantics rather than treating every usable object as a resource source. +### Jajce scaffold + +`world/jajce/JajceWorld.tscn` now provides a reusable environment scaffold +separate from `main.tscn`: + +- a centered 512 m flat Terrain3D seed split across four regions; +- dedicated terrain data and assets; +- greybox ridge, fortress, terraces, houses, mill, bridge, river, and waterfall; +- four ResourceNodes preserving the flat-map stable IDs; +- remaining food, guard, study, and rest activity markers; +- a temporary baked navigation loop with 24 tested routes; +- a look-development scene and camera. + +This is a placement and integration proof, not the final terrain composition. +`main.tscn` still runs the flat prototype. Terrain3D startup requires several +physics frames before reliable NavigationServer path queries; the scaffold test +captures that synchronization requirement. + ### Current UI A small village panel displays: @@ -447,8 +467,18 @@ NpcVisual navigates through the active world β”‚ β”œβ”€β”€ SimVillage.gd β”‚ └── SimulationManager.gd β”œβ”€β”€ tests/ +β”‚ β”œβ”€β”€ flat_map_baseline_test.gd +β”‚ β”œβ”€β”€ jajce_world_scaffold_test.gd β”‚ └── resource_node_player_parity_test.gd +β”œβ”€β”€ terrain/jajce/ Dedicated Terrain3D seed data and assets +β”œβ”€β”€ tools/ +β”‚ └── generate_jajce_terrain_seed.gd β”œβ”€β”€ world/ +β”‚ β”œβ”€β”€ jajce/ +β”‚ β”‚ β”œβ”€β”€ JajceWorld.tscn +β”‚ β”‚ β”œβ”€β”€ JajceLookdev.tscn +β”‚ β”‚ β”œβ”€β”€ jajce_world.gd +β”‚ β”‚ └── beauty_camera.gd β”‚ β”œβ”€β”€ resource_nodes/ β”‚ β”‚ β”œβ”€β”€ ResourceNode.gd β”‚ β”‚ β”œβ”€β”€ ResourceNode.gd.uid @@ -676,13 +706,11 @@ visual milestone should support or reveal actual simulation state. ## Immediate milestone: scaffold, architecture gate, then simulation garden -Food and wood migration on the flat test map is complete. The next visual step -is a deliberately minimal `JajceWorld` scaffold, greybox, navigation spike, and -resource-placement proof. Do not proceed directly from that proof into -open-ended beauty production. +Food and wood migration and the deliberately minimal `JajceWorld` scaffold, +greybox, navigation spike, and stable-ID placement proof are complete. Do not +proceed directly from that proof into open-ended beauty production. -After the scaffold proves terrain and navigation, complete the architecture -gate: +The architecture gate is now the active milestone: - deterministic clock and controlled random source; - fixed-seed headless scenarios with final-state checksums; diff --git a/docs/RESOURCE_NODE_MIGRATION.md b/docs/RESOURCE_NODE_MIGRATION.md index 9d52501..d9fd718 100644 --- a/docs/RESOURCE_NODE_MIGRATION.md +++ b/docs/RESOURCE_NODE_MIGRATION.md @@ -9,7 +9,7 @@ | **3** | Authoritative extraction on completion | βœ… Complete | | **4a** | Wood target selection (NPC) | βœ… Complete | | **4b** | Player parity (extraction contract) | βœ… Complete | -| **5** | Jajce world placement | ❌ Not started | +| **5** | Jajce world placement | πŸ”Ά Scaffold/navigation proof complete | | **6** | Remove remaining zone model | ❌ Not started | ### Key divergences from the original plan @@ -485,6 +485,11 @@ baseline. - use the old task zones only for rest, eat, patrol, and study; - verify target discovery does not rely on parent scene paths. +**Progress:** `556d0fd` adds the standalone Jajce scaffold, four stable-ID +resources, dedicated Terrain3D seed data, remaining activity markers, and 24 +headless navigation-route checks. Runtime `main.tscn` migration is intentionally +deferred until after the architecture gate, so this phase is not yet complete. + **Exit:** the existing food and wood loops work after moving from the flat map to Terrain3D. @@ -558,7 +563,7 @@ resource conservation through debug presentation. | 10 | Add navigation failure handling (replaces regression scenarios) | βœ… Done | `b8752f8` | | 11 | Migrate wood | βœ… Done | `c6033b6`, `8049c52` | | 12 | Give the player the same extraction path | βœ… Done | `326df51` | -| 13 | Continue with the Jajce world scaffold | ❌ Not started | β€” | +| 13 | Continue with the Jajce world scaffold | πŸ”Ά Placement proof done; runtime migration pending | `556d0fd` | ## Definition of done for the first migration