refactor(M03): extract WMO placement resolver

2026-07-17 00:22:53 +04:00
parent f01302fd44
commit 05e216a953
9 changed files with 530 additions and 32 deletions
@@ -19,6 +19,7 @@
 | M2 placement transform resolver | Implemented | [`m2-placement-transform-resolver.md`](m2-placement-transform-resolver.md) |
 | M2 placement grouper | Implemented extraction | [`m2-placement-grouper.md`](m2-placement-grouper.md) |
 | M2 build batch planner | Implemented extraction | [`m2-build-batch-planner.md`](m2-build-batch-planner.md) |
+| WMO placement resolver | Implemented extraction | [`wmo-placement-resolver.md`](wmo-placement-resolver.md) |
 | Third-person camera | Implemented | [`third-person-camera.md`](third-person-camera.md) |
 | Character presentation | Implemented boundary / Partial fidelity | [`character-presentation.md`](character-presentation.md) |
 | Renderer | Partial | [`world-renderer.md`](world-renderer.md), [`../../RENDER.md`](../../RENDER.md) |
@@ -0,0 +1,187 @@
+# WMO Placement Resolver
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Status | Implemented |
+| Target/work package | M03 / `M03-RND-WMO-PLACEMENT-RESOLVER-001` |
+| Owners | Pure WMO cache-key, placement-identity and world-transform rules |
+| Last verified | Worktree `work/sindo-main-codex/m03-wmo-placement-resolver`, 2026-07-17 |
+| Profiles/capabilities | Existing ADT/WDT WMO placement paths |
+
+## Purpose
+
+Provide one scene-free boundary for normalized WMO cache keys, MODF placement
+identity and world-space Godot transforms across render-cache, cached-scene and
+live-prototype instance paths.
+
+## Non-goals
+
+- Parse ADT/WDT or convert canonical WoW coordinates.
+- Own WMO registry references, tile state, jobs, queues or retries.
+- Load/validate cached scenes or lightweight render resources.
+- Create Nodes, Mesh/MultiMesh, materials or RIDs.
+- Implement portals, rooms, visibility, materials, doodads or WMO parity.
+
+## Context and boundaries
+
+```mermaid
+flowchart LR
+    Parsed[ADT/WDT WMO placement] --> Loader[StreamingWorldLoader adapter]
+    Loader --> Resolver[WmoPlacementResolver]
+    Resolver --> CacheKey[Normalized cache key]
+    Resolver --> Identity[Registry unique key]
+    Resolver --> Transform[World Transform3D]
+    CacheKey --> Cache[Loader WMO caches/requests]
+    Identity --> Registry[Loader WMO registry]
+    Transform --> RenderRoot[Lightweight render root]
+    Transform --> Scene[Cached scene instance]
+    Transform --> Live[Live prototype instance]
+```
+
+Allowed dependencies are Dictionary/String values and Godot `Vector3`, `Basis`
+and `Transform3D` math. Node, SceneTree, RenderingServer, ResourceLoader,
+WorkerThreadPool, mutexes, files, gameplay, network and editor UI are forbidden.
+
+## Public API
+
+| Symbol | Kind | Purpose | Thread/lifetime | Errors |
+|---|---|---|---|---|
+| `normalize_relative_path(relative_wmo_path)` | Pure query | Return lowercase slash-normalized cache/lookup key | Any thread; value result | Empty input returns empty |
+| `resolve_unique_key(placement, tile_key, placement_index)` | Pure query | Return positive UID identity or tile/index fallback | Any thread; value result | Missing/non-positive UID uses fallback |
+| `resolve_world_transform(placement)` | Pure query | Compose world-space position, Godot Euler rotation and uniform scale | Any thread; value result | Missing fields use zero/zero/one defaults; scale is not clamped |
+
+## Inputs and outputs
+
+| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
+|---|---|---|---|---|---|
+| Input | Relative WMO path | WDT/ADT name table | Path normalizer | Caller String | One call |
+| Input | Raw placement Dictionary | WDT global or ADT MODF parser result | Identity/transform queries | Read-only shallow value | One call |
+| Input | Tile key and placement index | Loader build job | Synthetic identity fallback | Copied scalar/String | Registry entry lifetime |
+| Output | Normalized relative path | Resolver | Render/scene cache and load-request maps | New String value | Request/cache lookup |
+| Output | `uid:*` or `tile:*:*` key | Resolver | Loader WMO registry/ref arrays | New String value | Until unregister/reset |
+| Output | World `Transform3D` | Resolver | Three WMO instance adapters | Value copy | Instance lifetime after assignment |
+
+The resolver retains no source Dictionary, output or engine resource.
+
+## Data flow
+
+```mermaid
+flowchart TD
+    Path[relative path] --> Slash[replace backslash with slash]
+    Slash --> Lower[lowercase entire key]
+    Placement[placement Dictionary] --> UID{unique_id > 0?}
+    UID -->|yes| UidKey[uid decimal]
+    UID -->|no| TileKey[tile key + placement index]
+    Placement --> Defaults[position/rotation/scale defaults]
+    Defaults --> Basis[Godot Basis.from_euler]
+    Basis --> Scale[unclamped uniform scale]
+    Scale --> World[world Transform3D]
+```
+
+## Lifecycle/state
+
+The resolver is stateless. Construction, world reset, map switch, cancellation
+and shutdown require no resolver operation.
+
+## Main sequence
+
+```mermaid
+sequenceDiagram
+    participant Loader as StreamingWorldLoader
+    participant Resolver as WmoPlacementResolver
+    participant Registry as Loader WMO registry/cache
+    participant Instance as Render/cached/live instance
+    Loader->>Resolver: normalize_relative_path(path)
+    Resolver-->>Loader: cache key
+    Loader->>Resolver: resolve_unique_key(placement, tile, index)
+    Resolver-->>Registry: identity adopted by loader
+    Loader->>Resolver: resolve_world_transform(placement)
+    Resolver-->>Loader: value Transform3D
+    Loader->>Instance: assign transform and attach/build
+```
+
+## Ownership, threading and resources
+
+- The resolver owns only call-local scalar/value calculations.
+- The loader owns WMO registry entries/ref sets, cache/load-request state, build
+  jobs/queues, resource fallback and cancellation.
+- The loader and builders own every Node/Mesh/MultiMesh/material/RID lifecycle.
+- Pure calls are thread-safe; current consumers execute on the main thread.
+
+## Errors, cancellation and recovery
+
+| Failure | Detection | Behavior | Diagnostic | Recovery |
+|---|---|---|---|---|
+| Empty path | Empty String | Empty normalized key | Contract fixture | Loader cache path rejects/degrades |
+| Missing/non-positive UID | Integer rule | Tile/index key prevents same-tile collisions | Contract fixture | Rebake old ADT cache to restore cross-tile UID dedupe |
+| Missing transform fields | Dictionary defaults | Zero position/rotation; scale one | Contract fixture | Repair parser/cache input |
+| Zero/negative scale | No historical clamp | Preserve zero/mirrored basis | Contract fixture | Preserve source behavior |
+| Resource missing/pending | Outside resolver | Loader retry/fallback path unchanged | Existing loader diagnostics | Restore cache/raw asset |
+| Tile unregister/reset | Outside resolver | Loader releases refs/nodes/jobs | Shutdown/registry regressions | New placements resolve afresh |
+
+## Configuration and capabilities
+
+The resolver introduces no setting or profile branch. WMO radii, visibility,
+shadow/occlusion flags, cache size limits and build budgets remain loader-owned.
+
+## Persistence, cache and migration
+
+No format is written. Existing WMO `.tscn`/lightweight render cache versions and
+ADT/WDT formats are unchanged. Older placement caches without positive UID retain
+the existing per-tile fallback and require no migration for this extraction.
+
+## Diagnostics and observability
+
+The resolver emits no logs. Its verifier records path/identity/transform/source
+contracts and bounded 20,000-triple timing. WMO queue/cache/instance metrics remain
+in the facade/loader diagnostic snapshot.
+
+## Verification
+
+- `verify_wmo_placement_resolver.gd`: slash/case/empty path, positive UID,
+  missing/zero/negative UID fallback, default and rotated/scaled transform,
+  unclamped scale, historical Node3D property equivalence, stateless results,
+  all loader adapters, dependency boundary
+  and bounded timing.
+- Existing WMO material/cache/shutdown and renderer baseline regressions remain
+  required alongside M2/terrain/facade/internal-access/coordinate gates.
+- Fidelity evidence is exact extraction of current placement rules. No new
+  original-client WMO visual/portal/material parity claim is made.
+
+## Extension points
+
+- A later package may extract WMO registry ownership/ref release using these
+  stable keys.
+- Render-group build cursor and resource-selection state require separate
+  lifecycle/cancellation contracts.
+
+## Capability status
+
+| Capability | Status | Evidence | Gap/next step |
+|---|---|---|---|
+| Consistent WMO placement identity/transform | Implemented extraction | Contract/source/timing verifier | Asset-backed placement comparison pending |
+| WMO registry/build services | Remains in loader | Existing runtime regressions | Stateful extraction pending |
+| Portals/rooms/material fidelity | Partial | M00 checkpoint/material evidence | Broader WMO implementation pending |
+
+## Known gaps and risks
+
+- Raw placement Dictionaries remain the parser/cache boundary.
+- Old caches without UID cannot dedupe one WMO across ADT tile boundaries.
+- WMO scale remains intentionally unclamped, including zero/negative input.
+- Asset-backed visual/p95/p99 evidence is unavailable in this package.
+
+## Source map
+
+| Path | Responsibility |
+|---|---|
+| `src/render/wmo/wmo_placement_resolver.gd` | Path, identity and transform rules |
+| `src/scenes/streaming/streaming_world_loader.gd` | Registry/cache/build/resource/Node ownership |
+| `src/tools/verify_wmo_placement_resolver.gd` | Contract, source and timing regression |
+
+## Related decisions and references
+
+- [`world-renderer.md`](world-renderer.md)
+- [`../../RENDER.md`](../../RENDER.md)
+- [`../../targets/roadmap/02-rendering-and-graphics.md`](../../targets/roadmap/02-rendering-and-graphics.md)
@@ -5,9 +5,9 @@
 | Field | Value |
 |---|---|
 | Status | Partial |
-| Target/work package | M00 baseline; `M01-RND-STREAMING-FOCUS-001`; `M01-QAR-SERVER-SPAWN-RENDERER-001`; M03 facade/planner/scheduler/internal-access/ground/environment/entity packages; M03 terrain packages; M03 M2 unique/transform/grouping/batch packages |
+| Target/work package | M00 baseline; `M01-RND-STREAMING-FOCUS-001`; `M01-QAR-SERVER-SPAWN-RENDERER-001`; M03 facade/planner/scheduler/internal-access/ground/environment/entity packages; M03 terrain packages; M03 M2 packages; M03 WMO placement package |
 | Owners | Renderer workstream / milestone integrator |
-| Last verified | Worktree `work/sindo-main-codex/m03-m2-build-batch-planner`, 2026-07-17 |
+| Last verified | Worktree `work/sindo-main-codex/m03-wmo-placement-resolver`, 2026-07-17 |
 | Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete |

 ## Purpose
@@ -54,6 +54,8 @@ flowchart LR
    M2Transform --> Loader
    Loader --> M2Batch[M2BuildBatchPlanner]
    M2Batch --> Loader
+    Loader --> WmoPlacement[WmoPlacementResolver]
+    WmoPlacement --> Loader
    Native --> Parsed[Parsed tile/model data]
    Parsed --> Loader
    Loader --> Scene[SceneTree nodes]
@@ -124,6 +126,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
 | `M2PlacementTransformResolver.resolve_basis/resolve_origin_offset` | Internal pure M2 service | Resolves regular and calibrated model-specific ADT placement transforms | Worker/main thread; stateless | Unknown paths use regular basis and zero offset |
 | `M2PlacementGrouper.group_placements` | Internal pure M2 service | Validates and groups ordered tile-local placement transforms by normalized path | Worker/main thread; stateless | Invalid variants/name IDs/empty paths are skipped |
 | `M2BuildBatchPlanner.plan_batch` | Internal pure M2 service | Selects static/animated batch count and next group cursor | Main/any thread; stateless | Non-positive selected limit clamps to one; empty range completes |
+| `WmoPlacementResolver.normalize_relative_path/resolve_unique_key/resolve_world_transform` | Internal pure WMO service | Resolves cache key, registry identity and world transform | Main/any thread; stateless | Missing UID uses tile/index fallback; transform fields use historical defaults |

 Публичным contract не считаются `StreamingWorldLoader` methods/properties,
 внутренние dictionaries, queues, job records и generated node names. Scene-owned
@@ -152,6 +155,7 @@ loader configuration remains transitional composition data, not a caller API.
 | Internal transform | Rotation/path/scale | Loader or grouper / `M2PlacementTransformResolver` | Group/placeholder/instance transforms | Value-only Basis/Vector3 | One placement |
 | Internal grouping | Tile origin, M2 names and placements | Loader / `M2PlacementGrouper` | Loader worker result/build job | Fresh Dictionary/Transform3D arrays | One grouping task |
 | Internal batch plan | Transform count/offset, path kind and limits | Loader / `M2BuildBatchPlanner` | Loader materialization/cursor adapter | Fresh scalar Dictionary | One build operation |
+| Internal WMO placement | Path, MODF placement, tile/index | Loader / `WmoPlacementResolver` | WMO caches, registry and three instance adapters | Value-only String/Transform3D | Lookup/placement lifetime |
 | Output | Desired tile/detail operations | Streamer plan application | Finalize queues | Loader-owned | Cross-frame |
 | Output | Terrain/M2/WMO/liquid instances | Loader/builders | Godot world/renderer | Loader/world owner | Main-thread attach |
 | Output | Detached renderer metrics | `WorldRenderFacade` | Capture/baseline tools | Caller-owned deep copy | On demand |
@@ -200,6 +204,8 @@ flowchart TD
    M2Transform[M2PlacementTransformResolver] --> M2Grouper
    M2Grouper --> M2Batch[M2BuildBatchPlanner]
    M2Batch --> M2
+    R --> WmoPlacement[WmoPlacementResolver]
+    WmoPlacement --> WMO
    R --> B[RenderBudgetScheduler permits]
    B --> Terrain[Terrain attach/upgrade]
    B --> M2[M2 group/MultiMesh attach]
@@ -321,6 +327,8 @@ sequenceDiagram
  The loader retains tasks, mutex/result queues, stale checks and build state.
 - `M2BuildBatchPlanner` is stateless and owns only call-local scalar plans. The
  loader retains queue/resource transitions, cursor adoption and materialization.
+- `WmoPlacementResolver` is stateless and owns only call-local cache-key,
+  identity and transform values. The loader retains WMO refs/caches/jobs/resources.
 - Rendered-ground query results and diagnostic snapshots are caller-owned values;
  the facade never returns Mesh, Node, tile-state or queue references.
 - Loaded-mesh ground sampling is renderer diagnostics, not authoritative gameplay
@@ -412,6 +420,8 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
  group order, local transforms, fresh output, source boundary and bounded timing.
 - M2 build batch contract: static/animated limit selection, clamp, remaining
  count, completion/cursor rules, source boundary and bounded timing.
+- WMO placement contract: cache-path normalization, positive/fallback identity,
+  default/rotated/unclamped transforms, three consumers and bounded timing.
 - Budget scheduler contract: exact lane exhaustion, shared chunk removal/create
  priority, independent lanes, frame reset, invalid limits, terminal cancellation,
  dependency boundaries and bounded permit timing without loading a world scene.
@@ -445,6 +455,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 | M2 placement transform resolver | Implemented extraction | Scene-free formula/source/timing contract across three consumers | Asset-backed visual recheck and general placement parity pending |
 | M2 placement grouper | Implemented extraction | Scene-free validation/order/transform/source/timing contract | Worker/build state, spatial cells and asset-backed p95/p99 remain pending |
 | M2 build batch planner | Implemented extraction | Scene-free limit/count/cursor/source/timing contract | Queue/resource state, spatial cells and asset-backed p95/p99 remain pending |
+| WMO placement resolver | Implemented extraction | Scene-free path/identity/transform/source/timing contract | Registry/build extraction and asset-backed comparison pending |
 | WMO rendering | Partial | Cached group rendering | Portals/rooms/material parity |
 | Liquids | Partial | MH2O/MLIQ paths | LiquidType/depth/shore fidelity |
 | Sky/light | Partial | DBC controller/logs | Zone transition paired validation |