sindoring/open-wc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor(M03): extract WMO render build planner

Browse Source
This commit is contained in:
sindoring
2026-07-17 00:47:54 +04:00
parent e420a8724f
commit 3a6b1d306d
9 changed files with 490 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules/README.md
+1
View File
@@ -21,6 +21,7 @@
| 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) |
| WMO placement registry | Implemented extraction | [`wmo-placement-registry.md`](wmo-placement-registry.md) |
| WMO render build step planner | Implemented extraction | [`wmo-render-build-step-planner.md`](wmo-render-build-step-planner.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) |
docs/modules/wmo-render-build-step-planner.md
+185
View File
@@ -0,0 +1,185 @@
# WMO Render Build Step Planner
## Metadata
| Field | Value |
|---|---|
| Status | Implemented |
| Target/work package | M03 / `M03-RND-WMO-RENDER-BUILD-PLANNER-001` |
| Owners | Pure mesh-first WMO render-group cursor decision |
| Last verified | Worktree `work/sindo-main-codex/m03-wmo-render-build-planner`, 2026-07-17 |
| Profiles/capabilities | Lightweight WMO render-cache path; profile-independent |
## Purpose
Select exactly one next lightweight WMO render build operation from mesh and
MultiMesh counts/cursors. The planner makes the ordering and cursor transition
testable without loading a WMO, creating a Node or consuming a frame budget.
## Non-goals
- Own render Resources, Nodes, materials, jobs, queues or permits.
- Read WMO arrays, create group instances or adopt cursors in a job.
- Change group ordering, names, transforms, shadows or visibility.
- Load, validate, version or persist a WMO cache.
- Implement portals, rooms, doodad semantics or WMO visual parity.
## Context and boundaries
```mermaid
flowchart LR
Cache[WMOStreamingResource arrays] --> Loader[StreamingWorldLoader]
Job[Loader mesh/MultiMesh cursors] --> Loader
Loader --> Planner[WmoRenderBuildStepPlanner]
Planner --> Step[Operation + selected index + next cursors]
Step --> Loader
Loader --> Material[Material refresh]
Loader --> Node[MeshInstance3D or MultiMeshInstance3D]
Loader --> Budget[RenderBudgetScheduler permit]
```
The planner depends only on `RefCounted`, integers, `StringName` and a fresh
Dictionary result. Node, Resource, Mesh, MultiMesh, RID, SceneTree, files,
threads, locks, caches, gameplay, network and editor UI are forbidden.
## Public API
| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|---|---|---|---|---|
| `OPERATION_MESH` | Constant | Identifies one mesh-group operation | Immutable | None |
| `OPERATION_MULTIMESH` | Constant | Identifies one doodad MultiMesh-group operation | Immutable | None |
| `OPERATION_COMPLETE` | Constant | Identifies exhausted mesh and MultiMesh ranges | Immutable | None |
| `plan_step(mesh_count, mesh_index, multimesh_count, multimesh_index)` | Pure query | Select one operation, selected index and next cursors | Any thread; caller-owned result | No clamp/error branch; raw integer comparisons are preserved |
## Inputs and outputs
| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|---|---|---|---|---|---|
| Input | Mesh array count and current mesh cursor | Loader resource/job adapter | Planner | Integer values | One call |
| Input | MultiMesh array count and current MultiMesh cursor | Loader resource/job adapter | Planner | Integer values | One call |
| Output | `mesh`, `multimesh` or `complete` operation | Planner | Loader materializer/cancellation branch | Immutable `StringName` | One call |
| Output | Selected index | Planner | Loader Resource array access | Integer value | One operation |
| Output | Next mesh and MultiMesh cursors | Planner | Loader job adoption | Fresh Dictionary values | Until adopted/discarded |
The planner retains no input or output. Scene-tree mutation, material refresh,
job writes, permit consumption and cancellation are loader side effects.
## Data flow
```mermaid
flowchart TD
Input[Counts and cursors] --> MeshRemaining{mesh index < mesh count?}
MeshRemaining -->|yes| MeshStep[mesh at mesh index; increment mesh cursor]
MeshRemaining -->|no| MultiRemaining{MultiMesh index < MultiMesh count?}
MultiRemaining -->|yes| MultiStep[MultiMesh at its index; increment MultiMesh cursor]
MultiRemaining -->|no| Complete[complete; keep both cursors]
```
## Lifecycle/state
The planner is stateless. State belongs to the loader job. Repeated loader calls
advance through `mesh` steps, then `multimesh` steps, then `complete`. Planner
construction, cancellation, map reset and shutdown require no cleanup.
## Main sequence
```mermaid
sequenceDiagram
participant Loader as StreamingWorldLoader
participant Planner as WmoRenderBuildStepPlanner
participant Scene as SceneTree
participant Budget as RenderBudgetScheduler
Loader->>Planner: plan_step(counts, cursors)
Planner-->>Loader: operation, selected index, next cursors
alt mesh or MultiMesh
Loader->>Loader: refresh material and create group Node
Loader->>Scene: attach Node and editor owner
Loader->>Loader: adopt returned cursor
Loader->>Budget: consume one WMO group permit
else complete
Loader->>Loader: cancel/remove job and queue key
end
```
## Ownership, threading and resources
- The planner owns only call-local scalar comparisons and the returned value map.
- The loader owns Resources, mesh arrays, build jobs/queue and cursor adoption.
- The loader creates and owns every MeshInstance3D/MultiMeshInstance3D and
performs material refresh and editor-owner assignment on the main thread.
- `RenderBudgetScheduler` owns permits; the planner neither reads nor consumes one.
- Pure calls are thread-safe because the planner has no mutable state.
## Errors, cancellation and recovery
| Failure/state | Detection | Behavior | Diagnostic | Recovery |
|---|---|---|---|---|
| Empty arrays | Both `0 < 0` comparisons false | Return `complete` | Contract verifier | Loader removes job |
| Cursor at/beyond count | Raw integer comparison | Skip that range | Contract verifier | Continue next range or complete |
| Negative cursor/count | Raw historical comparison | No clamp; select exactly as prior loader condition | Edge fixture | Caller should maintain valid job cursors |
| Missing/invalid Resource | Loader validation before planning | Loader cancels job | Existing shutdown/runtime diagnostics | Reload/requeue placement |
| Root freed | Loader validity check before planning | Loader cancels job | Runtime-cache shutdown verifier | Placement may rebuild later |
| Placement final release | Loader/registry lifecycle | Loader cancels queued build | Registry regression | Later placement starts at cursor zero |
## Configuration and capabilities
The planner has no setting or profile branch. `wmo_render_group_ops_per_tick`,
quality presets, shadow/visibility settings and cache limits remain loader-owned.
## Persistence, cache and migration
No data is persisted. WMO render resource format/version, cache path and job
Dictionary fields are unchanged. No migration or cache rebuild is required.
## Diagnostics and observability
The planner emits no logs. Its verifier reports operation/cursor/source contracts
and bounded timing. Queue lengths, active WMO count and hitch sections remain in
existing loader/facade diagnostics.
## Verification
- `verify_wmo_render_build_step_planner.gd`: mesh-first order, cursor increments,
completion, empty and raw negative integer behavior, fresh results, loader
delegation, dependency boundary and 20,000-plan timing.
- WMO registry/resolver/material/shutdown plus renderer regressions verify the
unchanged ownership and surrounding runtime path.
- Fidelity evidence is exact extraction of existing mesh-before-MultiMesh and
one-index-per-permit behavior. No asset-backed build-12340 visual claim is made.
## Extension points
- WMO render build job/queue ownership may be extracted separately after a typed
cancellation and Resource lifetime contract exists.
- Materialization can later receive typed commands without changing this planner.
## Capability status
| Capability | Status | Evidence | Gap/next step |
|---|---|---|---|
| WMO render build step planning | Implemented | Pure contract/source/timing verifier | Asset-backed traversal p95/p99 pending |
| WMO build job/resource ownership | Partial | Existing loader/runtime regressions | Separate state/cancellation package |
| WMO visual/portal/material fidelity | Partial | Renderer baseline/material checks | Original-client paired evidence pending |
## Known gaps and risks
- Loader build jobs remain untyped Dictionaries.
- Resource array shape/length consistency remains a cache-builder invariant.
- No proprietary WMO corpus, traversal profile or paired client capture is part
of this extraction.
## Source map
| Path | Responsibility |
|---|---|
| `src/render/wmo/wmo_render_build_step_planner.gd` | Pure operation and cursor selection |
| `src/scenes/streaming/streaming_world_loader.gd` | Resource validation, jobs/queues, materialization, permits and cancellation |
| `src/tools/verify_wmo_render_build_step_planner.gd` | Contract, boundary and timing regression |
## Related decisions and references
- [`wmo-placement-registry.md`](wmo-placement-registry.md)
- [`wmo-placement-resolver.md`](wmo-placement-resolver.md)
- [`world-renderer.md`](world-renderer.md)
- [`../../RENDER.md`](../../RENDER.md)
- [`../../targets/roadmap/02-rendering-and-graphics.md`](../../targets/roadmap/02-rendering-and-graphics.md)
docs/modules/world-renderer.md
+13 -4
View File
@@ -7,7 +7,7 @@
| 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 packages; M03 WMO placement package |
| Owners | Renderer workstream / milestone integrator |
| Last verified | Worktree `work/sindo-main-codex/m03-wmo-placement-registry`, 2026-07-17 |
| Last verified | Worktree `work/sindo-main-codex/m03-wmo-render-build-planner`, 2026-07-17 |
| Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete |
## Purpose
@@ -58,6 +58,8 @@ flowchart LR
WmoPlacement --> Loader
Loader --> WmoRegistry[WmoPlacementRegistry]
WmoRegistry --> Loader
Loader --> WmoBuildStep[WmoRenderBuildStepPlanner]
WmoBuildStep --> Loader
Native --> Parsed[Parsed tile/model data]
Parsed --> Loader
Loader --> Scene[SceneTree nodes]
@@ -130,6 +132,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state
| `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 |
| `WmoPlacementRegistry.add_reference/release_reference/contains/active_count/diagnostic_snapshot/clear` | Internal WMO service | Owns placement-key to tile/global reference sets | Renderer main thread; map session | Empty/unknown/non-owner input is rejected without mutation |
| `WmoRenderBuildStepPlanner.plan_step` | Internal pure WMO service | Selects one mesh-first lightweight render-group operation and next cursors | Main/any thread; stateless | Raw integer comparisons are preserved without clamping |
Публичным contract не считаются `StreamingWorldLoader` methods/properties,
внутренние dictionaries, queues, job records и generated node names. Scene-owned
@@ -160,6 +163,7 @@ loader configuration remains transitional composition data, not a caller API.
| 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 |
| Internal WMO ownership | Resolved placement key and tile/global reference key | Loader / `WmoPlacementRegistry` | Loader create/retain/final-free decisions | Registry-owned String sets; detached diagnostics | Map session or final release |
| Internal WMO build step | Mesh/MultiMesh counts and job cursors | Loader / `WmoRenderBuildStepPlanner` | Loader materialization/cursor adapter | Fresh scalar Dictionary | One group operation |
| 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 |
@@ -210,7 +214,8 @@ flowchart TD
M2Batch --> M2
R --> WmoPlacement[WmoPlacementResolver]
WmoPlacement --> WmoRegistry[WmoPlacementRegistry]
WmoRegistry --> WMO
WmoRegistry --> WmoBuildStep[WmoRenderBuildStepPlanner]
WmoBuildStep --> WMO
R --> B[RenderBudgetScheduler permits]
B --> Terrain[Terrain attach/upgrade]
B --> M2[M2 group/MultiMesh attach]
@@ -334,8 +339,9 @@ sequenceDiagram
loader retains queue/resource transitions, cursor adoption and materialization.
- `WmoPlacementResolver` is stateless and owns only call-local cache-key,
identity and transform values. `WmoPlacementRegistry` owns only placement-key
reference sets. The loader retains the key-to-Node map, caches, jobs, queues,
resources, cancellation and every Node lifecycle action.
reference sets. `WmoRenderBuildStepPlanner` owns only a call-local operation
and cursor plan. The loader retains the key-to-Node map, caches, jobs, queues,
resources, cursor adoption, permits, cancellation and every Node lifecycle action.
- 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
@@ -431,6 +437,8 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
default/rotated/unclamped transforms, three consumers and bounded timing.
- WMO placement registry contract: first/idempotent/shared/non-owner/final/global
lifecycle, detached sorted diagnostics, source ownership and bounded timing.
- WMO render build step contract: mesh-before-MultiMesh order, one-index cursor
transition, completion/raw integer behavior, source ownership 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.
@@ -466,6 +474,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
| 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 | Asset-backed comparison pending |
| WMO placement registry | Implemented extraction | Scene-free ownership/lifecycle/source/timing contract | Build/resource state and asset-backed cross-tile corpus pending |
| WMO render build step planner | Implemented extraction | Scene-free order/cursor/source/timing contract | Job/resource ownership and asset-backed traversal p95/p99 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 |