diff --git a/RENDER.md b/RENDER.md index 217cf8f..71a41f5 100644 --- a/RENDER.md +++ b/RENDER.md @@ -38,6 +38,7 @@ Paired run 2026-07-11 подтвердил крупный coordinate/placement g - `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` - memoized billboard/UV-rotation decision for stale cached M2 runtime mesh refresh. - `src/render/m2/m2_mesh_load_pipeline_state.gd` - static M2 threaded-load request records, terminal statuses and completion-order finalize FIFO without I/O or Mesh ownership. - `src/render/m2/m2_mesh_resource_cache_state.gd` - normalized-path prepared static M2 Mesh references with final-shutdown lifetime. +- `src/render/m2/m2_mesh_resource_extractor.gd` - first-Mesh selection from direct/PackedScene/Node inputs with temporary instance cleanup. - `src/scenes/streaming/eastern_kingdoms_streaming.tscn` - текущая сцена для проверки Azeroth/Eastern Kingdoms. - `addons/mpq_extractor/loaders/adt_builder.gd` - сборка ADT terrain, control splat материалов и MH2O liquids. - `addons/mpq_extractor/loaders/m2_builder.gd` - сборка статического M2 mesh/material. @@ -1087,6 +1088,18 @@ $exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe' - Cache formats, refresh metadata, profiles and visible output are unchanged. Synthetic cache timing is not asset-backed memory/leak or p95/p99 evidence. +## 2026-07-17 M2 Mesh Resource Extractor + +- `M2MeshResourceExtractor` now selects the first Mesh from direct Mesh + Resources, temporary PackedScene instances and existing prototype/rebuild + Node subtrees using the prior depth-first child order. +- PackedScene extraction still instantiates exactly once and synchronously frees + the temporary root before returning the borrowed Mesh reference. +- `StreamingWorldLoader` still owns ResourceLoader I/O, raw M2 loading, + material refresh/rebuild, cache/missing adoption, permits and MultiMesh builds. +- Cache formats, traversal rules, profiles and visible output are unchanged. + Synthetic traversal timing is not asset-backed leak or p95/p99 evidence. + ## 2026-07-17 WMO Placement Resolver Extraction - `WmoPlacementResolver` now owns lowercase/slash cache-key normalization, diff --git a/coordination/claims/M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001.md b/coordination/claims/M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001.md index e0acc46..5e4e069 100644 --- a/coordination/claims/M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001.md +++ b/coordination/claims/M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001.md @@ -78,14 +78,23 @@ including temporary PackedScene instance cleanup, from `StreamingWorldLoader`. ## Status -- State: claimed -- Done: three first-Mesh call sites and temporary PackedScene lifecycle identified -- Next: implement extractor, migrate loader adapters, verify and document +- State: ready +- Done: extractor, three loader/test adapters, contract verifier and required documentation +- Next: integrator merge and post-merge smoke - Blocked by: ## Handoff -- Commit: -- Results: -- Remaining risks: -- Documentation updated: +- Commit: `7b0e1ea` +- Results: extractor passes direct/PackedScene/subtree/order/lifetime contracts + and 10,000 traversals in 39.243 ms; 36 headless renderer/coordinate + regressions pass; checkpoint dry-run passes 7/7; documentation and + coordination gates pass. +- Remaining risks: synchronous PackedScene instantiation remains behind the + existing permit; no private M2 corrupt-scene/traversal/leak/p95/p99 or + original-client comparison; material preparation remains loader-owned. +- Documentation updated: inline API; `m2-mesh-resource-extractor.md` with + data-flow, lifecycle, sequence and dependency diagrams; cache/pipeline specs, + module registry, `world-renderer.md` and `RENDER.md`. + + diff --git a/docs/modules/README.md b/docs/modules/README.md index 96811b9..7b0c3f8 100644 --- a/docs/modules/README.md +++ b/docs/modules/README.md @@ -24,6 +24,7 @@ | M2 runtime mesh rebuild classifier | Implemented extraction | [`m2-runtime-mesh-rebuild-classifier.md`](m2-runtime-mesh-rebuild-classifier.md) | | M2 mesh load pipeline state | Implemented extraction | [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md) | | M2 mesh resource cache state | Implemented extraction | [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md) | +| M2 mesh resource extractor | Implemented extraction | [`m2-mesh-resource-extractor.md`](m2-mesh-resource-extractor.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) | diff --git a/docs/modules/m2-mesh-load-pipeline-state.md b/docs/modules/m2-mesh-load-pipeline-state.md index 496fbef..72b68dd 100644 --- a/docs/modules/m2-mesh-load-pipeline-state.md +++ b/docs/modules/m2-mesh-load-pipeline-state.md @@ -86,7 +86,8 @@ flowchart TD FIFO --> Permit{Loader permit available?} Permit -->|no| FIFO Permit -->|yes| Pop[Pop oldest terminal record] - Pop --> Finalize[Loader gets Resource and adopts Mesh/missing state] + Pop --> Finalize[Loader gets Resource and delegates first-Mesh extraction] + Finalize --> Adopt[Loader prepares and adopts Mesh/missing state] ``` ## Lifecycle/state @@ -204,7 +205,8 @@ rebuild policy are unchanged; no migration or rebake is required. | Static M2 request/finalize state | Implemented extraction | Contract/source/timing verifier | Asset-backed long traversal pending | | ResourceLoader I/O | Existing loader-owned | Shutdown/material regressions | I/O adapter extraction optional | | Mesh cache | Implemented extraction | Mesh resource cache state verifier | Asset-backed memory/leak run pending | -| Mesh materialization | Existing loader-owned | Renderer/material tests | Separate finalizer extraction pending | +| First-Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending | +| Mesh materialization | Existing loader-owned | Renderer/material tests | Separate preparation finalizer pending | ## Known gaps and risks @@ -219,6 +221,7 @@ rebuild policy are unchanged; no migration or rebake is required. |---|---| | `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending records, terminal FIFO and metrics | | `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared static Mesh references and final clear | +| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene lifetime | | `src/scenes/streaming/streaming_world_loader.gd` | Cache path choice, I/O polling, permits and Mesh/missing adoption | | `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` | Downstream stale Mesh rebuild decision | | `src/tools/verify_m2_mesh_load_pipeline_state.gd` | Lifecycle/boundary/timing regression | diff --git a/docs/modules/m2-mesh-resource-cache-state.md b/docs/modules/m2-mesh-resource-cache-state.md index cef5f9c..def330e 100644 --- a/docs/modules/m2-mesh-resource-cache-state.md +++ b/docs/modules/m2-mesh-resource-cache-state.md @@ -33,7 +33,8 @@ flowchart LR Cache -->|cached Mesh or null| Loader Loader --> Pipeline[M2MeshLoadPipelineState] Pipeline --> IO[ResourceLoader] - IO --> Prepare[Loader extraction and runtime preparation] + IO --> Extract[M2MeshResourceExtractor] + Extract --> Prepare[Loader runtime preparation] Prepare --> Cache Loader --> Build[M2 MultiMesh materialization] ``` @@ -129,7 +130,8 @@ flowchart TB - Renderer main-thread adapters serialize every cache operation. - The cache owns normalized-path Strings and strong Mesh references. - Borrowed Mesh lookups do not transfer ownership or duplicate resources. -- The loader owns missing/prototype/animated state and all Nodes/MultiMeshes. +- `M2MeshResourceExtractor` owns first-Mesh selection and temporary PackedScene + instances. The loader owns missing/prototype/animated state and MultiMeshes. - The loader drains asynchronous work before the final cache clear. ## Errors, cancellation and recovery @@ -181,7 +183,8 @@ the historical Mesh cache had no queue contribution or log site. |---|---|---|---| | Prepared static M2 Mesh cache | Implemented extraction | Contract/source/timing verifier | Asset-backed memory/leak run pending | | M2 Mesh request lifecycle | Implemented extraction | Pipeline state verifier | ResourceLoader I/O remains loader-owned | -| M2 Mesh extraction/preparation | Existing loader-owned | Material/classifier regressions | Separate finalizer extraction next | +| M2 Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending | +| M2 Mesh preparation | Existing loader-owned | Material/classifier regressions | Separate finalizer extraction next | ## Known gaps and risks @@ -196,6 +199,7 @@ the historical Mesh cache had no queue contribution or log site. | Path | Responsibility | |---|---| | `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared Mesh references and final clear | +| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene lifetime | | `src/scenes/streaming/streaming_world_loader.gd` | Normalization, I/O, preparation, missing state and materialization | | `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending request and terminal finalize records | | `src/tools/verify_m2_mesh_resource_cache_state.gd` | Cache ownership/lifetime/boundary/timing regression | diff --git a/docs/modules/m2-mesh-resource-extractor.md b/docs/modules/m2-mesh-resource-extractor.md new file mode 100644 index 0000000..099f682 --- /dev/null +++ b/docs/modules/m2-mesh-resource-extractor.md @@ -0,0 +1,207 @@ +# M2 Mesh Resource Extractor + +## Metadata + +| Field | Value | +|---|---| +| Status | Implemented extraction | +| Target/work package | M03 / `M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001` | +| Owners | First-Mesh selection and temporary PackedScene instance lifetime | +| Last verified | Worktree `work/sindo-main-codex/m03-m2-mesh-resource-extractor`, 2026-07-17 | +| Profiles/capabilities | Static M2 threaded cache and synchronous raw/prototype fallback paths | + +## Purpose + +Select the first M2 Mesh from a direct Resource, PackedScene or existing Node +subtree while keeping traversal and temporary-node lifetime outside +`StreamingWorldLoader`. + +## Non-goals + +- Request/load Resources or choose cache paths. +- Load raw M2 data, refresh materials or rebuild Meshes. +- Own Mesh/prototype/missing caches or pending/finalize queues. +- Create MultiMeshes, attach Nodes or consume render permits. +- Change first-Mesh selection order or visible output. + +## Context and boundaries + +```mermaid +flowchart LR + Pipeline[M2 load pipeline] --> Loader[StreamingWorldLoader] + Loader --> Resource[Loaded Mesh or PackedScene Resource] + Resource --> Extractor[M2MeshResourceExtractor] + Extractor -->|first Mesh or null| Loader + Loader --> Prepare[Material refresh/rebuild] + Prepare --> Cache[M2MeshResourceCacheState] + Prototype[Existing M2 Node subtree] --> Extractor +``` + +The extractor may inspect `Resource`, `PackedScene`, `Node`, `MeshInstance3D` +and `Mesh` engine types. It has no ResourceLoader, filesystem, worker, cache, +scheduler, builder, gameplay, network or editor dependency. + +## Public API + +| Symbol | Kind | Purpose | Thread/lifetime | Errors | +|---|---|---|---|---| +| `extract_first_mesh(resource)` | Query with temporary ownership | Return direct Mesh or first Mesh from one PackedScene instance | Renderer main thread; temporary root freed before return | Null/unsupported/empty returns null | +| `find_first_mesh_in_subtree(root)` | Query | Return first Mesh in historical depth-first preorder | Renderer main thread; caller-owned subtree unchanged | Null/no Mesh returns null | + +## Inputs and outputs + +| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime | +|---|---|---|---|---|---| +| Input | Direct Mesh Resource | Loader threaded finalizer | Extractor | Borrowed Resource | One call | +| Input | PackedScene Resource | Loader threaded finalizer | Extractor | Borrowed scene; extractor owns temporary instance | Temporary root until return | +| Input | Existing prototype/rebuild Node subtree | Loader builder/fallback | Extractor | Borrowed Node tree | One traversal | +| Output | First Mesh reference | Extractor | Loader preparation/cache adapter | Borrowed exact reference | Cache may retain later | + +The only side effect is synchronous creation and immediate `free()` of a +temporary PackedScene instance. + +## Data flow + +```mermaid +flowchart TD + Input[Resource or Node subtree] --> Direct{Direct Mesh?} + Direct -->|yes| Return[Return exact Mesh] + Direct -->|no| Packed{PackedScene?} + Packed -->|yes| Instantiate[Instantiate temporary root] + Packed -->|no| Traverse[Traverse caller-owned subtree] + Instantiate --> TraverseTemp[Depth-first preorder traversal] + TraverseTemp --> Free[Free temporary root] + Free --> ReturnOrNull[Return first Mesh or null] + Traverse --> ReturnOrNull +``` + +## Lifecycle/state + +```mermaid +stateDiagram-v2 + [*] --> Stateless + Stateless --> TemporaryInstance: extract PackedScene + TemporaryInstance --> Traversing: instantiate succeeded + Traversing --> Stateless: free temporary root before return + Stateless --> Stateless: direct Mesh/subtree/invalid input +``` + +No state or Resource reference is retained between calls. + +## Main sequence + +```mermaid +sequenceDiagram + participant Loader as StreamingWorldLoader + participant Extractor as M2MeshResourceExtractor + participant Scene as PackedScene + Loader->>Extractor: extract_first_mesh(loaded Resource) + alt direct Mesh + Extractor-->>Loader: same Mesh reference + else PackedScene + Extractor->>Scene: instantiate() + Scene-->>Extractor: temporary root + Extractor->>Extractor: depth-first first-Mesh search + Extractor->>Extractor: temporary_root.free() + Extractor-->>Loader: Mesh or null + end + Loader->>Loader: prepare and cache Mesh or mark missing +``` + +## Dependency diagram + +```mermaid +flowchart TB + Loader[StreamingWorldLoader] --> Extractor[M2MeshResourceExtractor] + Extractor --> Types[Resource / PackedScene / Node / Mesh] + Loader --> Pipeline[M2MeshLoadPipelineState] + Loader --> Cache[M2MeshResourceCacheState] + Loader --> Classifier[M2RuntimeMeshRebuildClassifier] + Extractor -. no dependency .-> Pipeline + Extractor -. no dependency .-> Cache + Extractor -. no dependency .-> Classifier +``` + +## Ownership, threading and resources + +- The renderer main thread performs all traversal and PackedScene instantiation. +- Direct and subtree Mesh references are borrowed without duplication. +- A PackedScene temporary root is extractor-owned and synchronously freed. +- Existing prototype/rebuild subtrees remain caller-owned and are never mutated. +- Cache retention and Mesh material preparation remain loader/service concerns. + +## Errors, cancellation and recovery + +| Failure/state | Detection | Behavior | Diagnostic | Recovery | +|---|---|---|---|---| +| Null/unsupported Resource | Type guard | Return null | Contract verifier | Loader marks missing/falls back | +| PackedScene instantiate failure | Null root | Return null | Existing loader behavior | Rebuild cache/source | +| No Mesh in subtree | Traversal exhaustion | Return null | Contract verifier | Loader marks missing/falls back | +| Null MeshInstance Mesh | Null traversal result | Parent continues with later siblings | Order verifier | Normal sibling search | +| Shutdown/cancel | No retained state | No action | Ownership docs | Caller owns surrounding job | + +## Configuration and capabilities + +The module adds no settings or profile branches. Cache format order, material +refresh version, render permits and batching remain unchanged outside it. + +## Persistence, cache and migration + +The extractor is stateless and serializes nothing. Existing `.tscn`/`.glb` +formats, cache versions and rebuild metadata are unchanged; no migration or +rebake is required. + +## Diagnostics and observability + +The module emits no logs and retains no counters. Loader correlation remains the +normalized M2 path. Its verifier measures traversal time and temporary Node count. + +## Verification + +- `verify_m2_mesh_resource_extractor.gd`: direct/invalid Resources, depth-first + child order, null-Mesh sibling continuation, subtree ownership, PackedScene + exact Mesh identity, temporary Node release, source boundaries and 10,000 + bounded traversals. +- M2 pipeline/cache/classifier/material/shutdown/build regressions cover adjacent + behavior. No asset-backed visual parity claim is made. + +## Extension points + +- Material refresh/rebuild can become a separate finalizer consuming the Mesh + returned here and storing its result in `M2MeshResourceCacheState`. +- Broader generic scene traversal is intentionally excluded until another real + consumer requires the same exact contract. + +## Capability status + +| Capability | Status | Evidence | Gap/next step | +|---|---|---|---| +| Direct/PackedScene first-Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending | +| Prototype/rebuild subtree selection | Implemented extraction | Synthetic preorder verifier | Asset-backed M2 traversal pending | +| Material refresh/rebuild finalization | Existing loader-owned | Classifier/material regressions | Separate finalizer extraction next | + +## Known gaps and risks + +- PackedScene instantiation remains synchronous main-thread work behind the + existing finalize permit. +- The first Mesh rule intentionally ignores additional MeshInstances. +- No proprietary M2 corpus, corrupt cache, leak/descriptor-pressure, p95/p99 or + paired original-client capture is included. + +## Source map + +| Path | Responsibility | +|---|---| +| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh traversal and temporary PackedScene lifetime | +| `src/scenes/streaming/streaming_world_loader.gd` | ResourceLoader, preparation, caching, missing state and materialization | +| `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared Mesh retention | +| `src/tools/verify_m2_mesh_resource_extractor.gd` | Resource/order/lifetime/boundary/timing regression | + +## Related decisions and references + +- [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md) +- [`m2-mesh-load-pipeline-state.md`](m2-mesh-load-pipeline-state.md) +- [`m2-runtime-mesh-rebuild-classifier.md`](m2-runtime-mesh-rebuild-classifier.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) diff --git a/docs/modules/world-renderer.md b/docs/modules/world-renderer.md index aebca9e..b0ccf1f 100644 --- a/docs/modules/world-renderer.md +++ b/docs/modules/world-renderer.md @@ -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-m2-mesh-resource-cache`, 2026-07-17 | +| Last verified | Worktree `work/sindo-main-codex/m03-m2-mesh-resource-extractor`, 2026-07-17 | | Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete | ## Purpose @@ -135,6 +135,7 @@ from externally reading/writing loader-private queue, task, cache and tile-state | `M2RuntimeMeshRebuildClassifier` | Internal memoized M2 service | Detects billboard/UV-rotation metadata requiring stale cached-mesh rebuild | Renderer main thread; cached until reset | Invalid variants/indices skipped; first path decision wins | | `M2MeshLoadPipelineState` | Internal M2 async-state service | Owns static Mesh pending request records and terminal finalize FIFO | Renderer main thread; map/session | Empty/duplicate/unknown transitions rejected | | `M2MeshResourceCacheState` | Internal M2 Resource cache | Owns prepared static Mesh references by normalized path | Renderer main thread; final shutdown | Empty path/null Mesh rejected; same path replaces | +| `M2MeshResourceExtractor` | Internal M2 scene/resource service | Selects first Mesh from direct Resource, PackedScene or Node subtree | Renderer main thread; stateless except temporary instance | Invalid/no Mesh returns null; temporary PackedScene root freed | | `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 | @@ -375,8 +376,11 @@ sequenceDiagram terminal statuses and completion-order finalize FIFO. The loader retains cache path selection, ResourceLoader calls, permits, shared missing state and adoption. - `M2MeshResourceCacheState` owns prepared static Mesh references and releases - them at the existing final-shutdown site. The loader retains extraction, - material refresh/rebuild, missing/prototype state and materialization. + them at the existing final-shutdown site. The loader retains material + refresh/rebuild, missing/prototype state and materialization. +- `M2MeshResourceExtractor` owns depth-first first-Mesh selection and temporary + PackedScene instance destruction. The loader retains ResourceLoader I/O, + runtime preparation, cache/missing adoption and materialization. - 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 @@ -580,6 +584,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m | `src/render/m2/m2_runtime_mesh_rebuild_classifier.gd` | Billboard/UV-rotation stale cached-mesh rebuild decision and memoization | | `src/render/m2/m2_mesh_load_pipeline_state.gd` | Static M2 pending Resource paths, terminal statuses and finalize FIFO | | `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared static M2 Mesh references and final-shutdown release | +| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene instance lifetime | | `src/render/streaming/streaming_target_planner.gd` | Scene-free wanted/retained ADT target calculation | | `src/render/streaming/streaming_target_policy.gd` | Immutable renderer radius/prefetch policy | | `src/render/streaming/streaming_target_plan.gd` | Immutable planner result with read-only tile-key sets | @@ -597,6 +602,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m | `src/tools/verify_m2_runtime_mesh_rebuild_classifier.gd` | M2 rebuild predicate/cache/boundary/timing regression | | `src/tools/verify_m2_mesh_load_pipeline_state.gd` | Static M2 request/terminal/FIFO/boundary/timing regression | | `src/tools/verify_m2_mesh_resource_cache_state.gd` | Static M2 Mesh cache ownership/lifetime/boundary/timing regression | +| `src/tools/verify_m2_mesh_resource_extractor.gd` | M2 direct/PackedScene/subtree order/lifetime/boundary/timing regression | | `src/tools/verify_streaming_target_planner.gd` | Planner behavior, dependency and bounded timing regression | | `src/tools/verify_render_budget_scheduler.gd` | Scheduler bounds, shared-lane priority, cancellation and timing regression | | `src/tools/verify_renderer_internal_access.gd` | Gameplay/EditorPlugin/registered renderer-tool boundary gate derived from private streamer fields | diff --git a/src/render/m2/m2_mesh_resource_extractor.gd b/src/render/m2/m2_mesh_resource_extractor.gd new file mode 100644 index 0000000..79283da --- /dev/null +++ b/src/render/m2/m2_mesh_resource_extractor.gd @@ -0,0 +1,34 @@ +class_name M2MeshResourceExtractor +extends RefCounted + +## Selects the first Mesh from loaded M2 Resources or existing Node subtrees. +## The caller owns ResourceLoader I/O, cache adoption and material preparation. + + +## Returns the direct Mesh Resource or the first Mesh in a temporary PackedScene +## instance. The temporary instance is freed before this method returns. +func extract_first_mesh(resource: Resource) -> Mesh: + if resource is Mesh: + return resource as Mesh + if not (resource is PackedScene): + return null + var temporary_root := (resource as PackedScene).instantiate() + if temporary_root == null: + return null + var mesh := find_first_mesh_in_subtree(temporary_root) + temporary_root.free() + return mesh + + +## Returns the first MeshInstance3D Mesh in depth-first preorder. The subtree +## and Mesh ownership remain unchanged. +func find_first_mesh_in_subtree(root: Node) -> Mesh: + if root == null: + return null + if root is MeshInstance3D: + return (root as MeshInstance3D).mesh + for child in root.get_children(): + var mesh := find_first_mesh_in_subtree(child) + if mesh != null: + return mesh + return null diff --git a/src/render/m2/m2_mesh_resource_extractor.gd.uid b/src/render/m2/m2_mesh_resource_extractor.gd.uid new file mode 100644 index 0000000..b3c785f --- /dev/null +++ b/src/render/m2/m2_mesh_resource_extractor.gd.uid @@ -0,0 +1 @@ +uid://dea4gekrxshjf diff --git a/src/scenes/streaming/streaming_world_loader.gd b/src/scenes/streaming/streaming_world_loader.gd index 6d120f7..fc50c0b 100644 --- a/src/scenes/streaming/streaming_world_loader.gd +++ b/src/scenes/streaming/streaming_world_loader.gd @@ -69,6 +69,9 @@ const M2_MESH_LOAD_PIPELINE_STATE_SCRIPT := preload( const M2_MESH_RESOURCE_CACHE_STATE_SCRIPT := preload( "res://src/render/m2/m2_mesh_resource_cache_state.gd" ) +const M2_MESH_RESOURCE_EXTRACTOR_SCRIPT := preload( + "res://src/render/m2/m2_mesh_resource_extractor.gd" +) const STREAMING_TARGET_PLANNER_SCRIPT := preload("res://src/render/streaming/streaming_target_planner.gd") const STREAMING_TARGET_POLICY_SCRIPT := preload("res://src/render/streaming/streaming_target_policy.gd") const RENDER_BUDGET_SCHEDULER_SCRIPT := preload("res://src/render/streaming/render_budget_scheduler.gd") @@ -260,6 +263,7 @@ var _m2_runtime_mesh_rebuild_classifier := ( M2_RUNTIME_MESH_REBUILD_CLASSIFIER_SCRIPT.new() ) var _m2_mesh_resource_cache_state := M2_MESH_RESOURCE_CACHE_STATE_SCRIPT.new() +var _m2_mesh_resource_extractor := M2_MESH_RESOURCE_EXTRACTOR_SCRIPT.new() var _m2_mesh_load_pipeline_state := M2_MESH_LOAD_PIPELINE_STATE_SCRIPT.new() var _m2_animation_load_requests: Dictionary = {} var _m2_animation_finalize_queue: Array = [] @@ -4277,7 +4281,7 @@ func _drain_m2_mesh_loads() -> void: var path := String(pending.get("path", "")) var resource: Resource = ResourceLoader.load_threaded_get(path) - var mesh := _extract_first_mesh_from_m2_resource(resource) + var mesh := _m2_mesh_resource_extractor.extract_first_mesh(resource) if mesh != null: _m2_mesh_resource_cache_state.store_mesh( normalized_rel, @@ -4695,34 +4699,11 @@ func _rebuild_m2_mesh_from_data(data: Dictionary) -> Mesh: var prototype: Node3D = M2_BUILDER_SCRIPT.build(data, extracted_dir) if prototype == null: return null - var rebuilt := _find_first_mesh_recursive(prototype) + var rebuilt := _m2_mesh_resource_extractor.find_first_mesh_in_subtree(prototype) prototype.free() return rebuilt -func _extract_first_mesh_from_m2_resource(resource: Resource) -> Mesh: - if resource is Mesh: - return resource as Mesh - if resource is PackedScene: - var node := (resource as PackedScene).instantiate() - if node == null: - return null - var mesh := _find_first_mesh_recursive(node) - node.free() - return mesh - return null - - -func _find_first_mesh_recursive(node: Node) -> Mesh: - if node is MeshInstance3D: - return (node as MeshInstance3D).mesh - for child in node.get_children(): - var mesh := _find_first_mesh_recursive(child) - if mesh != null: - return mesh - return null - - func _get_or_load_m2_mesh(rel_path: String) -> Mesh: var normalized_rel := _normalize_m2_rel_path(rel_path) if _m2_mesh_resource_cache_state.has_mesh(normalized_rel): @@ -4730,7 +4711,7 @@ func _get_or_load_m2_mesh(rel_path: String) -> Mesh: var prototype: Node3D = _get_or_load_m2_prototype(rel_path) if prototype == null: return null - var mesh := _find_first_mesh_recursive(prototype) + var mesh := _m2_mesh_resource_extractor.find_first_mesh_in_subtree(prototype) if mesh != null and not normalized_rel.is_empty(): mesh = _prepare_m2_mesh_for_runtime(normalized_rel, mesh) _m2_mesh_resource_cache_state.store_mesh(normalized_rel, mesh) diff --git a/src/tools/verify_m2_mesh_resource_cache_state.gd b/src/tools/verify_m2_mesh_resource_cache_state.gd index d61fbd6..13667ac 100644 --- a/src/tools/verify_m2_mesh_resource_cache_state.gd +++ b/src/tools/verify_m2_mesh_resource_cache_state.gd @@ -94,7 +94,7 @@ func _verify_ownership_boundaries(failures: Array[String]) -> void: ) for retained_loader_rule in [ "ResourceLoader.load_threaded_get(path)", - "_extract_first_mesh_from_m2_resource(resource)", + "_m2_mesh_resource_extractor.extract_first_mesh(resource)", "_prepare_m2_mesh_for_runtime(normalized_rel, mesh)", "_m2_missing_cache[normalized_rel]", "_m2_scene_cache[normalized_rel]", diff --git a/src/tools/verify_m2_mesh_resource_extractor.gd b/src/tools/verify_m2_mesh_resource_extractor.gd new file mode 100644 index 0000000..dc760bb --- /dev/null +++ b/src/tools/verify_m2_mesh_resource_extractor.gd @@ -0,0 +1,185 @@ +extends SceneTree + +## Synthetic direct-Resource/PackedScene/subtree/order/lifetime/boundary/timing +## regression for first-Mesh extraction. + +const EXTRACTOR_SCRIPT := preload("res://src/render/m2/m2_mesh_resource_extractor.gd") +const EXTRACTOR_PATH := "res://src/render/m2/m2_mesh_resource_extractor.gd" +const LOADER_PATH := "res://src/scenes/streaming/streaming_world_loader.gd" + + +func _initialize() -> void: + var failures: Array[String] = [] + _verify_direct_and_invalid_resources(failures) + _verify_depth_first_subtree_order(failures) + _verify_packed_scene_mesh_and_temporary_lifetime(failures) + _verify_ownership_boundaries(failures) + var elapsed_milliseconds := _verify_bounded_timing(failures) + if not failures.is_empty(): + for failure in failures: + push_error("M2_MESH_RESOURCE_EXTRACTOR: %s" % failure) + quit(1) + return + print( + "M2_MESH_RESOURCE_EXTRACTOR PASS cases=10 iterations=10000 elapsed_ms=%.3f" + % elapsed_milliseconds + ) + quit(0) + + +func _verify_direct_and_invalid_resources(failures: Array[String]) -> void: + var extractor: RefCounted = EXTRACTOR_SCRIPT.new() + var direct_mesh := ArrayMesh.new() + _expect_same( + extractor.call("extract_first_mesh", direct_mesh), + direct_mesh, + "direct Mesh reference retained", + failures + ) + _expect_same(extractor.call("extract_first_mesh", Resource.new()), null, "unsupported Resource returns null", failures) + _expect_same(extractor.call("extract_first_mesh", null), null, "null Resource returns null", failures) + _expect_same(extractor.call("find_first_mesh_in_subtree", null), null, "null subtree returns null", failures) + + +func _verify_depth_first_subtree_order(failures: Array[String]) -> void: + var extractor: RefCounted = EXTRACTOR_SCRIPT.new() + var root := Node3D.new() + var first_branch := Node3D.new() + var second_branch := Node3D.new() + var first_mesh_instance := MeshInstance3D.new() + var second_mesh_instance := MeshInstance3D.new() + var first_mesh := ArrayMesh.new() + var second_mesh := ArrayMesh.new() + first_mesh_instance.mesh = first_mesh + second_mesh_instance.mesh = second_mesh + root.add_child(first_branch) + root.add_child(second_branch) + first_branch.add_child(first_mesh_instance) + second_branch.add_child(second_mesh_instance) + _expect_same( + extractor.call("find_first_mesh_in_subtree", root), + first_mesh, + "depth-first child order retained", + failures + ) + _expect_same(first_mesh_instance.get_parent(), first_branch, "subtree ownership unchanged", failures) + first_mesh_instance.mesh = null + _expect_same( + extractor.call("find_first_mesh_in_subtree", root), + second_mesh, + "null MeshInstance Mesh skipped by parent traversal", + failures + ) + root.free() + + +func _verify_packed_scene_mesh_and_temporary_lifetime(failures: Array[String]) -> void: + var extractor: RefCounted = EXTRACTOR_SCRIPT.new() + var source_root := Node3D.new() + var mesh_instance := MeshInstance3D.new() + var packed_mesh := ArrayMesh.new() + mesh_instance.mesh = packed_mesh + source_root.add_child(mesh_instance) + mesh_instance.owner = source_root + var packed_scene := PackedScene.new() + _expect_equal(packed_scene.pack(source_root), OK, "synthetic PackedScene packs", failures) + source_root.free() + var node_count_before := int(Performance.get_monitor(Performance.OBJECT_NODE_COUNT)) + var extracted_mesh: Mesh = extractor.call("extract_first_mesh", packed_scene) + var node_count_after := int(Performance.get_monitor(Performance.OBJECT_NODE_COUNT)) + _expect_same(extracted_mesh, packed_mesh, "PackedScene first Mesh retained", failures) + _expect_equal(node_count_after, node_count_before, "temporary PackedScene root freed", failures) + + +func _verify_ownership_boundaries(failures: Array[String]) -> void: + var extractor_source := FileAccess.get_file_as_string(EXTRACTOR_PATH) + var loader_source := FileAccess.get_file_as_string(LOADER_PATH) + _expect_true( + loader_source.contains("M2_MESH_RESOURCE_EXTRACTOR_SCRIPT.new()"), + "loader composes Mesh resource extractor", + failures + ) + _expect_false( + loader_source.contains("func _extract_first_mesh_from_m2_resource("), + "legacy Resource extractor removed", + failures + ) + _expect_false( + loader_source.contains("func _find_first_mesh_recursive("), + "legacy subtree extractor removed", + failures + ) + _expect_equal( + loader_source.count("_m2_mesh_resource_extractor.extract_first_mesh("), + 1, + "threaded Resource finalization delegates", + failures + ) + _expect_equal( + loader_source.count("_m2_mesh_resource_extractor.find_first_mesh_in_subtree("), + 2, + "rebuild and synchronous fallback delegate", + failures + ) + for retained_loader_rule in [ + "ResourceLoader.load_threaded_get(path)", + "_prepare_m2_mesh_for_runtime(normalized_rel, mesh)", + "_m2_mesh_resource_cache_state.store_mesh(", + "M2_BUILDER_SCRIPT.build(data, extracted_dir)", + "_m2_missing_cache[normalized_rel]", + ]: + _expect_true(loader_source.contains(retained_loader_rule), "loader retains %s" % retained_loader_rule, failures) + for forbidden_dependency in [ + "ResourceLoader.", + "FileAccess.", + "WorkerThreadPool.", + "M2Builder", + "_m2_mesh_resource_cache_state", + "_m2_missing_cache", + "MultiMesh", + ]: + _expect_false( + extractor_source.contains(forbidden_dependency), + "extractor omits %s ownership" % forbidden_dependency, + failures + ) + _expect_true(extractor_source.contains("temporary_root.free()"), "temporary root free remains explicit", failures) + + +func _verify_bounded_timing(failures: Array[String]) -> float: + var extractor: RefCounted = EXTRACTOR_SCRIPT.new() + var root := Node3D.new() + var branch := root + for _depth_index in range(8): + var child_branch := Node3D.new() + branch.add_child(child_branch) + branch = child_branch + var mesh_instance := MeshInstance3D.new() + mesh_instance.mesh = ArrayMesh.new() + branch.add_child(mesh_instance) + var started_microseconds := Time.get_ticks_usec() + for _iteration in range(10000): + extractor.call("find_first_mesh_in_subtree", root) + var elapsed_milliseconds := float(Time.get_ticks_usec() - started_microseconds) / 1000.0 + root.free() + _expect_true(elapsed_milliseconds < 1000.0, "10000 subtree lookups under 1 second", failures) + return elapsed_milliseconds + + +func _expect_true(condition: bool, label: String, failures: Array[String]) -> void: + if not condition: + failures.append(label) + + +func _expect_false(condition: bool, label: String, failures: Array[String]) -> void: + _expect_true(not condition, label, failures) + + +func _expect_equal(actual: int, expected: int, label: String, failures: Array[String]) -> void: + if actual != expected: + failures.append("%s expected=%d actual=%d" % [label, expected, actual]) + + +func _expect_same(actual: Variant, expected: Variant, label: String, failures: Array[String]) -> void: + if not is_same(actual, expected): + failures.append(label) diff --git a/src/tools/verify_m2_mesh_resource_extractor.gd.uid b/src/tools/verify_m2_mesh_resource_extractor.gd.uid new file mode 100644 index 0000000..4b9d452 --- /dev/null +++ b/src/tools/verify_m2_mesh_resource_extractor.gd.uid @@ -0,0 +1 @@ +uid://bgvidp5u31sud