feat: index loaded resource discovery

2026-07-17 00:34:30 +02:00
parent 2c88ed6ea8
commit 5356c34fd7
21 changed files with 1392 additions and 69 deletions
@@ -0,0 +1,82 @@
+# Loaded Resource Discovery 01
+
+## Question
+
+Can villagers resolve finite resource anchors spread across a larger Terrain3D
+world without scanning every loaded `ResourceNode`, while selecting exactly the
+same target as the existing distance/risk/comfort/priority score?
+
+## Reviewed workload
+
+- Godot: `4.7-stable (official)`;
+- host: Apple M1 Max, 64 GB;
+- benchmark seed: `17331`;
+- loaded resources: 18, 180, and 1,800;
+- 400 deterministic target resolutions per sample;
+- seven fresh timing samples per case;
+- 20 m horizontal source spacing with varied terrain-like height, safety risk,
+  comfort distance, discovery priority, and deterministic disabled sources;
+- each query performs the real availability check, score, reservation, and
+  release through `ActionTargetResolver` and `ResourceStateRecord`.
+
+The linear reference reproduces the previous `ResourceNode.get_all()` scan.
+The spatial path uses the production `ActiveWorldAdapter` and its 24 m
+resource-specific horizontal grid. Fixture construction, rendering, navigation
+pathfinding, simulation ticks, and serialization are excluded.
+
+## Results
+
+| Loaded anchors | Linear µs/query | Spatial µs/query | Speedup | Average inspected | Reduction |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 18 | 65.04 | 33.26 | 1.96x | 18 → 3.705 | 79.42% |
+| 180 | 589.03 | 38.83 | 15.17x | 180 → 4.375 | 97.57% |
+| 1,800 | 6,448.00 | 46.94 | 137.37x | 1,800 → 4.445 | 99.75% |
+
+Every spatial sample produced the same selected-target checksum as its linear
+reference. The raw samples are in
+[`loaded_resource_discovery_01.json`](loaded_resource_discovery_01.json).
+
+These are local workload measurements, not portable performance promises. The
+important shape is that ordinary local queries remain near four inspected
+anchors while the loaded set grows by 100x.
+
+## Exactness contract
+
+`ActionTargetResolver` queries successively larger grid radii. It may stop only
+when the best possible score of every farther anchor is strictly worse than the
+current winner. The lower bound uses the loaded action's authoritative maximum
+comfort distance, minimum safety risk, and maximum discovery priority. Stable
+registration order preserves the former first-loaded tie behavior.
+
+Unavailable, depleted, and reserved state remains authoritative in
+`ResourceStateRecord`; the grid indexes only loaded IDs, interaction positions,
+and disposable score bounds. Unloading removes an anchor without deleting its
+state. Rebinding the same ID or moving a loaded anchor refreshes the index.
+
+One focused regression also gives the farthest test source an extreme priority.
+The query expands beyond its local cells and selects that source exactly as the
+linear scan does, proving that the common local fast path is not a hard range
+cutoff.
+
+## Decision
+
+Keep the resource-specific grid inside `ActiveWorldAdapter`. It has one real
+consumer, preserves current gameplay, and directly supports larger authored
+source fields. Do not generalize it into a people/building/event index or a
+simulation-LOD framework yet.
+
+Terrain3D foliage instances remain decorative unless an intentional stable-ID
+`ResourceNode` anchor binds simulation-owned state. A later placement workflow
+can author those anchors alongside visual instancing without making every tree
+an authoritative resource.
+
+## Capture command
+
+```bash
+/Applications/Godot.app/Contents/MacOS/Godot \
+  --headless --path "$PWD" \
+  --script res://tools/benchmark_loaded_resource_discovery.gd -- \
+  --queries=400 --samples=7 \
+  --host-label=Apple_M1_Max_64_GB \
+  --output=res://docs/benchmarks/loaded_resource_discovery_01.json
+```