108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# M03-RND-WMO-RENDER-BUILD-QUEUE-001 — WMO render build queue
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-WMO-RENDER-BUILD-QUEUE-001:sindo-main-codex:2026-07-20 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-wmo-render-build-queue`
|
|
- Lease expires UTC: 2026-07-20
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract typed lightweight-WMO render build jobs and their FIFO key queue from
|
|
the loader while leaving all engine-object destruction and materialization in
|
|
the loader.
|
|
|
|
## Non-goals
|
|
|
|
- Queue-free Nodes or free Resources/RIDs.
|
|
- Move material refresh, Node creation, editor ownership or budget permits.
|
|
- Change duplicate enqueue, stale-key cleanup, cancel or clear ordering.
|
|
- Change placement, cache loading/versioning, transforms, shadows or visibility.
|
|
- Claim asset-backed WMO fidelity, leak acceptance or traversal p95/p99.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/wmo/wmo_render_build_job.gd`,
|
|
`src/render/wmo/wmo_render_build_queue.gd`,
|
|
`src/tools/verify_wmo_render_build_queue.gd`,
|
|
`docs/modules/wmo-render-build-queue.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
|
|
`docs/modules/wmo-render-build-step-planner.md`,
|
|
`docs/modules/world-renderer.md`, `docs/modules/README.md`, `RENDER.md`,
|
|
`targets/03-renderer-facade.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated ADT/WMO resources, caches
|
|
and proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Typed job: placement key, strong Node3D/Resource references and two cursors
|
|
- FIFO queue preserves duplicate key append and first-occurrence erase behavior
|
|
- Stale front keys remain observable for loader-compatible pop-and-continue
|
|
- Cancel releases the keyed job reference and first queued key only
|
|
- Clear releases every job/key reference idempotently; never frees engine objects
|
|
- Loader retains validity checks, planner invocation, cursor adoption,
|
|
materialization, permits, cancellation reactions and Node destruction
|
|
- Cache/schema/coordinate/profile versions: unchanged
|
|
|
|
## Dependencies
|
|
|
|
- Requires: current master `1e740aa`, accepted WMO build step planner
|
|
- Blocks: further WMO cache/load and materialization decomposition
|
|
- External state: none; verification uses synthetic Node3D/Resource instances
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated invalid/FIFO/duplicate/stale/cursor/cancel/clear/
|
|
diagnostics/source/timing verifier; WMO planner/registry/resolver/material/
|
|
shutdown plus M2/terrain/facade/internal-access/manifest/scheduler/streaming/
|
|
coordinate/docs/coord gates
|
|
- Fidelity evidence: exact current queue/dictionary behavior preserved
|
|
- Performance budget: 100 cycles over 256 jobs under 1 second
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline job/queue API documentation
|
|
- New module spec with inputs/outputs, data flow, state/sequence, ownership,
|
|
threading, failure/recovery, performance/fidelity limits and source map
|
|
- Build-step planner, renderer module registry, world renderer and RENDER updates
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names: `WmoRenderBuildJob`, `WmoRenderBuildQueue`
|
|
- Simplest solution: one typed record plus Dictionary/Array queue composition
|
|
- Rejected complexity: generic job scheduler, signals, callbacks, mutexes,
|
|
Resources as job records or engine lifetime callbacks
|
|
- Unavoidable complexity: duplicate keys can intentionally leave stale entries
|
|
- Measured optimization evidence: bounded synthetic enqueue/cancel/clear loop
|
|
|
|
## Status
|
|
|
|
- State: ready for integration
|
|
- Done: typed job/queue implemented; three clear sites, metrics, enqueue, drain and
|
|
cancel migrated; engine destruction/materialization retained in loader
|
|
- Next: integrator merge and post-merge verification
|
|
- Blocked by:
|
|
|
|
## Handoff
|
|
|
|
- Commit: `e1bb105`
|
|
- Results: queue PASS (`cases=11`, `iterations=100`, `elapsed_ms=59.874`);
|
|
WMO planner/registry/resolver/material/shutdown and 18 adjacent M2/terrain/
|
|
facade/scheduler/streaming/coordinate regressions PASS; documentation and
|
|
coordination gates PASS; checkpoint dry-run PASS `7/7`.
|
|
- Remaining risks: strong Node/Resource references require every loader cancel/
|
|
clear path; duplicate enqueue intentionally preserves stale FIFO keys; no
|
|
proprietary WMO corpus, original-client paired capture, leak run or traversal
|
|
p95/p99; dry-run reports expected missing ADT/DBC/character assets.
|
|
- Documentation updated: inline job/queue API;
|
|
`docs/modules/wmo-render-build-queue.md`, build-step planner spec, module
|
|
registry, world renderer and `RENDER.md`; data-flow/state/sequence diagrams,
|
|
ownership, threading, failure/recovery and source map included.
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-WMO-RENDER-BUILD-QUEUE-001:e1bb105 -->
|