234 lines
11 KiB
Markdown
234 lines
11 KiB
Markdown
# 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)
|