feat: author resource-aware riverbank grove

2026-07-17 13:57:57 +02:00
parent 145b90eb97
commit 04c5371b6b
23 changed files with 823 additions and 63 deletions
@@ -0,0 +1,76 @@
+# Jajce Resource Grove 04
+
+Captured: 2026-07-17
+
+## Files
+
+- [before overview](jajce_resource_grove_04_before.png)
+- [after overview](jajce_resource_grove_04_after.png)
+- `world/jajce/RiverbankResourceCluster.tscn`
+- `tests/jajce_resource_cluster_test.gd`
+
+The images use the same 1280×720 camera, fixed daylight value, warmup, and
+Metal renderer. The new cluster is on the right bank beside and beyond the
+bridge; the comparison intentionally keeps the broader citadel/waterfall
+composition unchanged.
+
+## Visual reduction
+
+The former river edge had one isolated deciduous tree and conifer, while two
+generic-box resource anchors sat separately from the foliage language. The
+after frame gathers that silhouette into one restrained bank mass:
+
+- 12 low-poly fern clumps;
+- 9 oversized warm flower heads;
+- 7 flattened bank stones;
+- 2 decorative silhouette trees; and
+- 2 finite anchors with distinct berry-patch and harvestable-tree visuals.
+
+The 28 understory details use three `MultiMeshInstance3D` batches. The berry
+visual adds five wind-reactive leaf clumps and eight deliberately readable
+berries. This is a bounded authored accent, not a world-wide scatter pass.
+
+## Authority and authoring contract
+
+`DecorativeInstances` contains no `ResourceNode` descendants. Its trees,
+ferns, flowers, and stones are transient presentation and never enter saves,
+checksums, reservations, or resource conservation.
+
+`ResourceAnchors` contains only `berry_bush_river_02` and
+`tree_river_resource_01`. These are the same existing IDs and definitions, now
+nested inside the authored cluster. `ResourceNode` registration and
+`ActiveWorldAdapter` discovery do not depend on a parent path, so simulation
+authority still binds exactly 18 resources.
+
+The visible plants sit on the raised Terrain3D bank. Each anchor has a separate
+approach marker snapped to the lower bank surface, keeping the visual context
+honest without asking NPCs to climb an unreachable slope. All required
+navigation routes reach those markers and remain close to Terrain3D height.
+
+## Far-discovery proof
+
+The berry interaction point is approximately 30.5 m from the village origin,
+beyond the adapter's initial 24 m query radius. The focused scenario first
+confirms ordinary nearby food remains available, then disables every other food
+source in authoritative state. `ActionTargetResolver` expands through more than
+one range pass and selects `berry_bush_river_02` by stable ID. The test also
+checks that direct and nested anchors produce the same 18-entry index.
+
+## Remaining work
+
+The resource-specific visuals currently identify finite sources but do not yet
+thin or change shape as their authoritative amount falls. The next vertical
+slice should show low/depleted berries and a stump or equivalent tree state
+after real NPC/player extraction, then verify save/load reconstructs the same
+visual from `ResourceStateRecord` without serializing presentation fields.
+
+## Capture command
+
+```bash
+HOME="$PWD/logs/quality/godot_profile" \
+APPDATA="$PWD/logs/quality/godot_profile" \
+LOCALAPPDATA="$PWD/logs/quality/godot_profile" \
+/Applications/Godot.app/Contents/MacOS/Godot \
+  --path "$PWD" --script res://tools/capture_jajce_lookdev.gd -- \
+  --output=res://docs/baselines/jajce_resource_grove_04_after.png
+```