render: extract WMO scene resource finalizer
This commit is contained in:
@@ -0,0 +1,233 @@
|
||||
# WMO Scene Resource Finalizer
|
||||
|
||||
## Metadata
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Implemented extraction |
|
||||
| Target/work package | M03 / `M03-RND-WMO-SCENE-RESOURCE-FINALIZER-001` |
|
||||
| Owners | Cached WMO PackedScene terminal polling, validation-probe lifetime and scene/missing publication |
|
||||
| Last verified | Worktree `work/sindo-main-codex/m03-wmo-scene-resource-finalizer`, 2026-07-18 |
|
||||
| Profiles/capabilities | Profile-independent cached WMO `.tscn` finalization |
|
||||
|
||||
## Purpose
|
||||
|
||||
Finalize pending cached WMO `.tscn` requests outside `StreamingWorldLoader`:
|
||||
poll terminal status, retrieve a PackedScene, instantiate one validation probe,
|
||||
apply existing WMOBuilder cache metadata rules, release the probe and publish
|
||||
either the exact scene or the historical missing outcome.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Select paths, measure file size or start ResourceLoader requests.
|
||||
- Instantiate placed WMO scenes or execute live WMOBuilder fallback.
|
||||
- Own cache lifetime, placements, build queues, permits or attached Nodes.
|
||||
- Change cache metadata/version rules, fallback order or visible behavior.
|
||||
|
||||
## Context and boundaries
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Loader[StreamingWorldLoader] -->|compose and tick| Finalizer[WmoSceneResourceFinalizer]
|
||||
Cache[WmoSceneResourceCacheState] -->|pending snapshot| Finalizer
|
||||
Finalizer --> ResourceLoader
|
||||
Finalizer --> Probe[Temporary Node3D probe]
|
||||
Probe --> Validator[WMOBuilder cache validator]
|
||||
Finalizer -->|PackedScene or missing| Cache
|
||||
Cache --> Fallback[Placed cached scene or live fallback]
|
||||
```
|
||||
|
||||
The service may depend on ResourceLoader, PackedScene/Node3D lifetime and the
|
||||
injected cache validator. FileAccess, size policy, placement, attached SceneTree,
|
||||
scheduler and application layers remain outside it.
|
||||
|
||||
## Public API
|
||||
|
||||
| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|
||||
|---|---|---|---|---|
|
||||
| `poll_terminal_requests(cache_state)` | Command/query | Poll every pending scene path once and publish terminal outcomes | Renderer main thread; stateless between calls | Null state returns zero; non-terminal retained |
|
||||
| `is_scene_cache_current(scene)` | Command/query | Instantiate, validate and release one probe | Renderer main thread; call-local Node | Null/no validator/wrong root/stale false |
|
||||
| `load_threaded_get_status(path)` | Boundary query | Read threaded status | Renderer main thread; injectable tests | ResourceLoader semantics |
|
||||
| `load_threaded_get(path)` | Boundary query | Retrieve terminal Resource | Renderer main thread; injectable tests | Null/wrong type rejected |
|
||||
|
||||
## Inputs and outputs
|
||||
|
||||
| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|
||||
|---|---|---|---|---|---|
|
||||
| Input | Detached normalized-path to `.tscn` path Dictionary | Scene cache state | Finalizer polling | Caller-owned copy | One pass |
|
||||
| Input | Opaque load status/terminal Resource | ResourceLoader | Finalizer | Value/borrowed Resource | One path |
|
||||
| Input | Cached WMO PackedScene | ResourceLoader | Probe validator | Borrowed reference | One completion |
|
||||
| Input | Metadata validator | Loader composition | Finalizer | Borrowed Object | Finalizer lifetime |
|
||||
| Output | Exact validated PackedScene | Finalizer | Scene cache state | Cache adopts strong reference | Until full clear |
|
||||
| Output | Missing transition | Finalizer | Scene cache state | Path-only state | Until transient clear |
|
||||
| Side effect | Temporary validation Node | PackedScene/finalizer | Validator | Finalizer-owned | Freed before return |
|
||||
|
||||
## Data flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Snapshot[Detached pending snapshot] --> Poll[Poll next status in insertion order]
|
||||
Poll --> Terminal{Loaded or failed?}
|
||||
Terminal -->|no| Retain[Retain pending]
|
||||
Terminal -->|failed| Missing[Complete missing]
|
||||
Terminal -->|loaded| Get[Get Resource]
|
||||
Get --> Type{PackedScene?}
|
||||
Type -->|no| Missing
|
||||
Type -->|yes| Instantiate[Instantiate one probe]
|
||||
Instantiate --> Root{Node3D root?}
|
||||
Root -->|no| FreeRejected[Free rejected Node] --> Missing
|
||||
Root -->|yes| Validate[WMOBuilder metadata validation]
|
||||
Validate --> Free[Free Node3D probe]
|
||||
Free --> Current{Current?}
|
||||
Current -->|yes| Adopt[Adopt exact PackedScene]
|
||||
Current -->|no| Missing
|
||||
```
|
||||
|
||||
## Lifecycle/state
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Polling
|
||||
Polling --> Pending: non-terminal
|
||||
Polling --> Probing: loaded PackedScene
|
||||
Polling --> Missing: failed/null/wrong type
|
||||
Probing --> Missing: wrong root or stale metadata
|
||||
Probing --> Cached: current metadata
|
||||
Probing --> Released: probe freed before outcome
|
||||
Released --> Missing
|
||||
Released --> Cached
|
||||
Pending --> Polling: later tick
|
||||
```
|
||||
|
||||
The finalizer retains no request or Node. Cache state owns Pending/Cached/Missing
|
||||
lifetime; every instantiated probe is synchronously released before return.
|
||||
|
||||
## Main sequence
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Loader as StreamingWorldLoader
|
||||
participant Finalizer as WmoSceneResourceFinalizer
|
||||
participant Cache as WmoSceneResourceCacheState
|
||||
participant RL as ResourceLoader
|
||||
participant Validator as WMOBuilder validator
|
||||
Loader->>Finalizer: poll_terminal_requests(Cache)
|
||||
Finalizer->>Cache: request_paths_snapshot()
|
||||
loop insertion-ordered paths
|
||||
Finalizer->>RL: load_threaded_get_status(path)
|
||||
alt failed
|
||||
Finalizer->>Cache: complete_request_as_missing(path)
|
||||
else loaded
|
||||
Finalizer->>RL: load_threaded_get(path)
|
||||
Finalizer->>Finalizer: instantiate Node3D probe
|
||||
Finalizer->>Validator: is_scene_cache_current(probe)
|
||||
Finalizer->>Finalizer: free probe
|
||||
Finalizer->>Cache: complete with exact scene or missing
|
||||
else non-terminal
|
||||
Finalizer->>Finalizer: retain request
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Dependency diagram
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
Loader[StreamingWorldLoader] --> Finalizer[WmoSceneResourceFinalizer]
|
||||
Loader --> Cache[WmoSceneResourceCacheState]
|
||||
Finalizer --> Cache
|
||||
Finalizer --> ResourceLoader
|
||||
Finalizer --> PackedScene
|
||||
Finalizer --> Node3D
|
||||
Finalizer --> Validator[WMOBuilder cache validator]
|
||||
Finalizer -. no dependency .-> FileAccess
|
||||
Finalizer -. no dependency .-> Placement
|
||||
Finalizer -. no dependency .-> Scheduler
|
||||
```
|
||||
|
||||
## Ownership, threading and resources
|
||||
|
||||
- Renderer main thread serializes polling, instantiation and cache publication.
|
||||
- Finalizer owns every call-local validation probe and frees it before return.
|
||||
- Non-Node3D rejected roots are also freed, closing the prior leak edge.
|
||||
- Cache state adopts accepted exact PackedScene references until full clear.
|
||||
- Loader owns admission/size policy, live fallback, placed Nodes and shutdown order.
|
||||
|
||||
## Errors, cancellation and recovery
|
||||
|
||||
| Failure/state | Detection | Behavior | Diagnostic | Recovery |
|
||||
|---|---|---|---|---|
|
||||
| Null cache state | Guard | Return zero | Contract verifier | Correct composition |
|
||||
| Non-terminal | Status | Retain pending | Pending count | Poll later |
|
||||
| Failed/null/wrong Resource | Status/type | Complete missing | Synthetic fixture | Reset/rebuild cache |
|
||||
| Non-Node3D root | Probe type | Free probe; complete missing | Type/lifetime fixture | Rebuild cache |
|
||||
| Stale metadata | Injected validator | Free probe; complete missing | Validation fixture | Rebuild/reset |
|
||||
| Shutdown | Loader lifecycle | Drain then clear cache | Shutdown verifier | New loader starts absent |
|
||||
|
||||
## Configuration and capabilities
|
||||
|
||||
The loader injects the existing WMOBuilder cache validator. `wmo_cache_dir`,
|
||||
`wmo_max_runtime_scene_mb`, debug logging, request timing and WMO budgets remain
|
||||
loader-owned. No setting, profile or cache version is added.
|
||||
|
||||
## Persistence, cache and migration
|
||||
|
||||
No data is serialized. Existing WMOBuilder metadata/version acceptance is called
|
||||
unchanged before adoption. The rejected-root lifetime fix needs no migration or
|
||||
rebake and does not alter accepted cache output.
|
||||
|
||||
## Diagnostics and observability
|
||||
|
||||
- Poll returns terminal completion count for tests/future metrics.
|
||||
- Existing pending count and renderer `wmobuild` metrics remain unchanged.
|
||||
- No logs are emitted; oversize debug logging remains at loader admission.
|
||||
- Normalized WMO relative path remains the correlation key.
|
||||
|
||||
## Verification
|
||||
|
||||
- `verify_wmo_scene_resource_finalizer.gd`: null/non-terminal, insertion order,
|
||||
failed/load boundary, null/wrong/non-Node3D/stale rejection, current exact
|
||||
identity, accepted/rejected probe release, source ownership and timing.
|
||||
- Scene cache, render finalizer/cache, WMO queue/planner/registry/resolver,
|
||||
shutdown, facade, internal-access and baseline regressions cover neighbors.
|
||||
- Fidelity evidence is exact orchestration extraction plus rejected-root leak
|
||||
repair; no asset-backed visual or original-client parity claim is made.
|
||||
|
||||
## Extension points
|
||||
|
||||
- Legal current/stale serialized `.tscn` fixtures can extend evidence unchanged.
|
||||
- Placed-scene preparation stays separate because it mutates an attached WMO
|
||||
instance rather than a call-local validation probe.
|
||||
|
||||
## Capability status
|
||||
|
||||
| Capability | Status | Evidence | Gap/next step |
|
||||
|---|---|---|---|
|
||||
| Cached WMO scene terminal polling | Implemented extraction | Status/order/source/timing verifier | Asset-backed traversal pending |
|
||||
| Probe validation/lifetime | Implemented extraction | Current/stale/type/free fixtures | Serialized fixture pending |
|
||||
| Scene/missing publication | Implemented extraction | Exact identity/negative fixtures | Asset-backed lifetime/leak run pending |
|
||||
| File-size admission/live fallback | Loader-owned | Existing scene-cache regressions | Separate extraction if justified |
|
||||
|
||||
## Known gaps and risks
|
||||
|
||||
- PackedScene instantiation/metadata validation remains synchronous main-thread work.
|
||||
- No proprietary WMO corpus, serialized stale/oversize fixture, long leak run,
|
||||
traversal p95/p99 or paired original-client capture is included.
|
||||
|
||||
## Source map
|
||||
|
||||
| Path | Responsibility |
|
||||
|---|---|
|
||||
| `src/render/wmo/wmo_scene_resource_finalizer.gd` | Terminal polling, probe validation/lifetime and publication |
|
||||
| `src/render/wmo/wmo_scene_resource_cache_state.gd` | Scene/missing/request ownership and resets |
|
||||
| `src/scenes/streaming/streaming_world_loader.gd` | Admission/size policy, live fallback and placed Node ownership |
|
||||
| `addons/mpq_extractor/loaders/wmo_builder.gd` | Existing cache metadata/version validation |
|
||||
| `src/tools/verify_wmo_scene_resource_finalizer.gd` | Terminal/probe/lifetime/source/timing regression |
|
||||
|
||||
## Related decisions and references
|
||||
|
||||
- [`wmo-scene-resource-cache-state.md`](wmo-scene-resource-cache-state.md)
|
||||
- [`wmo-render-resource-finalizer.md`](wmo-render-resource-finalizer.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)
|
||||
Reference in New Issue
Block a user