252 lines
11 KiB
Markdown
252 lines
11 KiB
Markdown
# M2 Mesh Resource Finalizer
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Implemented extraction |
|
|
| Target/work package | M03 / `M03-RND-M2-MESH-RESOURCE-FINALIZER-001` |
|
|
| Owners | Static M2 terminal Resource I/O, Mesh preparation and cache outcome |
|
|
| Last verified | Worktree `work/sindo-main-codex/m03-m2-mesh-resource-finalizer`, 2026-07-18 |
|
|
| Profiles/capabilities | Existing cached/static MultiMesh M2 path |
|
|
|
|
## Purpose
|
|
|
|
Drain static M2 ResourceLoader work and publish a prepared Mesh or missing-model
|
|
outcome without keeping terminal I/O and refresh logic in `StreamingWorldLoader`.
|
|
The same preparation method serves threaded and synchronous Mesh consumers.
|
|
|
|
## Non-goals
|
|
|
|
- Select cache candidates or admit threaded ResourceLoader requests.
|
|
- Own scheduler permits, prototype Nodes, MultiMeshes or SceneTree roots.
|
|
- Change first-Mesh traversal, refresh version, rebuild rules or raw parser.
|
|
- Merge static and animated terminal services through callbacks/frameworks.
|
|
- Change cache formats, profiles or visible output.
|
|
|
|
## Context and boundaries
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Observer[M2StaticBuildResourceObserver] --> Pipeline[M2MeshLoadPipelineState]
|
|
Loader[StreamingWorldLoader] --> Finalizer[M2MeshResourceFinalizer]
|
|
Pipeline --> Finalizer
|
|
ResourceLoader --> Finalizer
|
|
Finalizer --> Extractor[M2MeshResourceExtractor]
|
|
Finalizer --> Runtime[M2RuntimeMeshFinalizer]
|
|
Finalizer --> Raw[M2RawModelRepository]
|
|
Finalizer --> MeshCache[M2MeshResourceCacheState]
|
|
Finalizer --> Prototype[M2PrototypeCacheState]
|
|
```
|
|
|
|
## Public API
|
|
|
|
| Symbol | Kind | Purpose | Failure behavior |
|
|
|---|---|---|---|
|
|
| `poll_terminal_requests(pipeline, prototype_cache)` | I/O command | Move LOADED/FAILED records into completion FIFO | Invalid composition returns zero |
|
|
| `finalize_next_resource(pipeline, mesh_cache, prototype_cache, extracted_dir)` | I/O command | Pop one record and publish Mesh/missing outcome | Empty/invalid composition returns false |
|
|
| `prepare_mesh_for_runtime(path, mesh, extracted_dir)` | I/O preparation | Preserve current Mesh or load raw data and refresh stale Mesh | Null returns null |
|
|
| `load_threaded_get_status(path)` | I/O adapter | Production status query with injectable test seam | Returns ResourceLoader status |
|
|
| `load_threaded_get(path)` | I/O adapter | Production terminal Resource retrieval with injectable test seam | May return null |
|
|
|
|
## Inputs and outputs
|
|
|
|
| Direction | Data | Producer | Consumer | Ownership/lifetime |
|
|
|---|---|---|---|---|
|
|
| Input | Pending/finalize records | Mesh pipeline | Finalizer | Pipeline-owned copied Dictionaries |
|
|
| Input | Terminal Resource | ResourceLoader | Mesh extractor | Borrowed one operation |
|
|
| Input | Extracted/cached Mesh | Mesh extractor/loader consumer | Runtime preparation | Borrowed Resource reference |
|
|
| Input | Raw M2 Dictionary | Raw repository | Runtime finalizer | Call-local value |
|
|
| Output | Prepared Mesh | Runtime finalizer | Mesh cache/loader consumer | Resource reference |
|
|
| Output | Missing-model outcome | Finalizer | Prototype cache | Copied path; loader session |
|
|
| Output | Processed-record flag | Finalizer | Loader permit loop/tests | Boolean value |
|
|
|
|
## Data flow
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
Poll[Poll pending records in insertion order] --> Path{Resource path empty?}
|
|
Path -->|yes| Discard[Discard and mark missing]
|
|
Path -->|no| Status{LOADED or FAILED?}
|
|
Status -->|no| Pending[Keep pending]
|
|
Status -->|yes| Complete[Append completion FIFO]
|
|
Complete --> Permit[Loader consumes M2_MESH_FINALIZE permit]
|
|
Permit --> Pop[Pop oldest terminal record]
|
|
Pop --> Cached{Empty path or Mesh cached?}
|
|
Cached -->|yes| Skip[Finish one permit operation]
|
|
Cached -->|no| Loaded{Status LOADED?}
|
|
Loaded -->|no| Missing[Mark model missing]
|
|
Loaded -->|yes| Get[Get terminal Resource]
|
|
Get --> Extract[Extract first Mesh]
|
|
Extract --> Found{Mesh found?}
|
|
Found -->|no| Missing
|
|
Found -->|yes| Current{Refresh version current?}
|
|
Current -->|yes| Store[Store exact Mesh]
|
|
Current -->|no| Raw[Read raw M2 data]
|
|
Raw --> Refresh[Finalize/rebuild/fallback Mesh]
|
|
Refresh --> Store
|
|
```
|
|
|
|
## Lifecycle/state
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> Polling
|
|
Polling --> Pending: nonterminal status
|
|
Polling --> TerminalQueued: LOADED or FAILED
|
|
Polling --> Missing: empty Resource path
|
|
TerminalQueued --> Skipped: empty/cached record
|
|
TerminalQueued --> Missing: failed load or no Mesh
|
|
TerminalQueued --> Extracted: Mesh found
|
|
Extracted --> Current: refresh version current
|
|
Extracted --> Refreshing: stale Mesh
|
|
Refreshing --> Prepared: rebuild or fallback
|
|
Current --> Cached
|
|
Prepared --> Cached
|
|
Pending --> [*]
|
|
Skipped --> [*]
|
|
Missing --> [*]
|
|
Cached --> [*]
|
|
```
|
|
|
|
## Main sequence
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant L as StreamingWorldLoader
|
|
participant F as M2MeshResourceFinalizer
|
|
participant P as M2MeshLoadPipelineState
|
|
participant R as ResourceLoader
|
|
participant E as M2MeshResourceExtractor
|
|
participant N as M2RuntimeMeshFinalizer
|
|
participant C as M2MeshResourceCacheState
|
|
L->>F: poll_terminal_requests(P, prototype cache)
|
|
F->>R: load_threaded_get_status(path)
|
|
F->>P: complete terminal request
|
|
L->>L: consume M2_MESH_FINALIZE permit
|
|
L->>F: finalize_next_resource(...)
|
|
F->>P: pop oldest record
|
|
F->>R: load_threaded_get(path)
|
|
F->>E: extract_first_mesh(Resource)
|
|
F->>N: requires_raw_data_for_refresh(Mesh)
|
|
opt stale Mesh
|
|
F->>F: read raw M2 data
|
|
F->>N: finalize_mesh(...)
|
|
end
|
|
F->>C: store prepared Mesh
|
|
```
|
|
|
|
## Dependency diagram
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
Finalizer[M2MeshResourceFinalizer] --> ResourceLoader
|
|
Finalizer --> Pipeline[M2MeshLoadPipelineState]
|
|
Finalizer --> Extractor[M2MeshResourceExtractor]
|
|
Finalizer --> Runtime[M2RuntimeMeshFinalizer]
|
|
Finalizer --> Raw[M2RawModelRepository]
|
|
Finalizer --> MeshCache[M2MeshResourceCacheState]
|
|
Finalizer --> Prototype[M2PrototypeCacheState]
|
|
Loader[StreamingWorldLoader] --> Finalizer
|
|
Loader --> Scheduler[RenderBudgetScheduler]
|
|
Finalizer -. no dependency .-> Scheduler
|
|
Finalizer -. no dependency .-> MultiMesh
|
|
Finalizer -. no dependency .-> SceneTree
|
|
```
|
|
|
|
## Ownership, threading and resources
|
|
|
|
- All operations run synchronously on the renderer main thread.
|
|
- Pipeline owns pending/completion records; one permit pops one terminal record.
|
|
- Extractor owns temporary PackedScene instance cleanup and returns a Mesh reference.
|
|
- Runtime finalizer owns stale/current/rebuild/fallback rules; raw repository owns
|
|
only call-local native I/O.
|
|
- Mesh cache retains prepared Mesh references until final shutdown; prototype
|
|
cache retains missing-model paths.
|
|
- Service retains dependency references but no pending record, Resource, Mesh or
|
|
raw Dictionary between calls. Loader retains permits and materialization.
|
|
|
|
## Errors, cancellation and recovery
|
|
|
|
| Failure/state | Behavior | Recovery |
|
|
|---|---|---|
|
|
| Missing composition dependency | Return zero/false; preparation keeps Mesh where possible | Correct composition |
|
|
| Empty Resource path | Discard request and mark missing | Repair cache and restart session |
|
|
| Nonterminal status | Keep pending | Poll next tick |
|
|
| FAILED status | Pop and mark missing | Repair cache and restart session |
|
|
| Existing cached Mesh | Pop and skip terminal Resource get | None |
|
|
| Null/unsupported/no-Mesh Resource | Mark missing | Repair imported cache |
|
|
| Raw read/rebuild unavailable | Runtime finalizer marks/reuses original Mesh | Existing fallback |
|
|
| Tile cancellation | Shared cache work continues | Loader queue remains authoritative |
|
|
| Shutdown | Loader drains ResourceLoader before pipeline/cache clear | New loader starts empty |
|
|
|
|
## Configuration and capabilities
|
|
|
|
The service consumes the existing extracted directory. The scheduler retains
|
|
`m2_mesh_finalize_ops_per_tick`; material refresh version remains `2`.
|
|
|
|
## Persistence, cache and migration
|
|
|
|
No cache path, schema or version changes are introduced. Existing `.tscn/.glb`
|
|
Resources and in-memory refresh metadata remain compatible; no rebake is required.
|
|
|
|
## Diagnostics and observability
|
|
|
|
The service adds no log. Existing pending-plus-finalize metrics and refresh
|
|
metadata remain unchanged. Normalized relative path remains the correlation key.
|
|
|
|
## Verification
|
|
|
|
- Dedicated verifier covers status insertion order, empty-path discard, FIFO,
|
|
failed/cached/null outcomes, terminal get, exact Mesh identity, stale-only raw
|
|
read, exact finalizer arguments, cache adoption, source ownership and timing.
|
|
- Pipeline/cache/extractor/runtime-finalizer/raw-repository/prototype/shutdown,
|
|
facade, internal-access and baseline regressions protect adjacent behavior.
|
|
- Fidelity evidence is exact lifecycle/I/O extraction only; no private asset,
|
|
original-client visual, leak-pressure or p95/p99 claim is made.
|
|
|
|
## Extension points
|
|
|
|
Further extraction can move static prototype/material-source construction without
|
|
changing this terminal Resource contract. Animated finalization remains separate
|
|
because its candidate-before-material ordering and Node ownership differ.
|
|
|
|
## Capability status
|
|
|
|
| Capability | Status | Evidence | Gap/next step |
|
|
|---|---|---|---|
|
|
| Static terminal polling/load | Implemented extraction | Status/FIFO/load/source verifier | Asset-backed traversal pending |
|
|
| Mesh extraction/preparation/cache outcome | Implemented extraction | Identity/raw/finalizer/store verifier | Private leak/p95/p99 pending |
|
|
| Static MultiMesh materialization | Separate implemented service | Materializer verifier | GPU/asset-backed evidence pending |
|
|
|
|
## Known gaps and risks
|
|
|
|
- Terminal Resource get, extraction and stale rebuild remain synchronous main-thread work.
|
|
- Prepared Mesh cache remains unbounded until final shutdown.
|
|
- Private asset traversal, descriptor pressure, leak and p95/p99 evidence is absent.
|
|
|
|
## Source map
|
|
|
|
| Path | Responsibility |
|
|
|---|---|
|
|
| `src/render/m2/m2_mesh_resource_finalizer.gd` | Poll/load/extract/prepare/cache/missing service |
|
|
| `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending and completion FIFO ownership |
|
|
| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh and temporary-instance ownership |
|
|
| `src/render/m2/m2_runtime_mesh_finalizer.gd` | Refresh/rebuild/fallback rules |
|
|
| `src/render/m2/m2_raw_model_repository.gd` | Optional native raw M2 boundary |
|
|
| `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared Mesh ownership |
|
|
| `src/render/m2/m2_prototype_cache_state.gd` | Missing-model outcome ownership |
|
|
| `src/scenes/streaming/streaming_world_loader.gd` | Permit loop and materialization composition |
|
|
| `src/tools/verify_m2_mesh_resource_finalizer.gd` | Polling/preparation/boundary/timing regression |
|
|
|
|
## Related decisions and references
|
|
|
|
- [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md)
|
|
- [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md)
|
|
- [`m2-mesh-resource-extractor.md`](m2-mesh-resource-extractor.md)
|
|
- [`m2-runtime-mesh-finalizer.md`](m2-runtime-mesh-finalizer.md)
|
|
- [`m2-raw-model-repository.md`](m2-raw-model-repository.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)
|