225 lines
11 KiB
Markdown
225 lines
11 KiB
Markdown
# M2 Static Batch Materializer
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Implemented |
|
|
| Target/work package | M03 / `M03-RND-M2-STATIC-BATCH-MATERIALIZER-001` |
|
|
| Owners | Static M2 MultiMesh construction, render settings and attachment |
|
|
| Last verified | Worktree `work/sindo-main-codex/m03-m2-static-batch-materializer`, 2026-07-18 |
|
|
| Profiles/capabilities | Existing static M2 placement path |
|
|
|
|
## Purpose
|
|
|
|
Build and attach one static M2 `MultiMeshInstance3D` from an already prepared
|
|
Mesh and an ordered transform slice. The service preserves the existing
|
|
transform format, Mesh identity, batch name, visibility and shadow behavior.
|
|
|
|
## Non-goals
|
|
|
|
- Group placements, size batches or advance build-job cursors.
|
|
- Load, refresh, build or cache Mesh resources.
|
|
- Consume render permits, rotate queues or decide retries/cancellation.
|
|
- Assign Editor owners or release tile roots.
|
|
- Materialize animated instances or introduce spatial-cell batching.
|
|
|
|
## Context and boundaries
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Groups[Ordered transform group] --> Loader[StreamingWorldLoader build adapter]
|
|
MeshCache[Prepared Mesh cache] --> Loader
|
|
Planner[M2BuildBatchPlanner] --> Slice[Start and count]
|
|
Slice --> Loader
|
|
Loader --> Materializer[M2StaticBatchMaterializer]
|
|
Materializer --> Batch[Attached MultiMeshInstance3D]
|
|
Loader --> EditorOwner[Editor owner adapter]
|
|
```
|
|
|
|
Allowed dependencies are Godot `Mesh`, `MultiMesh`, `MultiMeshInstance3D`,
|
|
`GeometryInstance3D` and main-thread SceneTree APIs. Files, ResourceLoader,
|
|
workers, RenderingServer calls, caches, build jobs, scheduler policy, gameplay,
|
|
network and Editor ownership are forbidden.
|
|
|
|
## Public API
|
|
|
|
| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|
|
|---|---|---|---|---|
|
|
| `materialize_batch(parent, path, mesh, transforms, start, count, serial, visibility_end, visibility_margin, cast_shadows)` | Command/query | Create, configure and attach one static MultiMesh batch | Main thread; borrowed inputs, parent owns result | Invalid/empty input returns null; transform bounds are a caller precondition |
|
|
|
|
## Inputs and outputs
|
|
|
|
| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|
|
|---|---|---|---|---|---|
|
|
| Input | M2 parent root | Loader build job | Batch attachment | Borrowed Node3D | Tile/job lifetime |
|
|
| Input | Relative model path and serial | Loader build adapter | Batch node name | Copied values | One call |
|
|
| Input | Prepared static Mesh | M2 Mesh resource cache/finalizer | MultiMesh | Borrowed Resource; exact reference retained by MultiMesh | Cache and batch lifetimes |
|
|
| Input | Ordered transforms, start and count | Placement group and batch plan | MultiMesh transform buffer | Borrowed Array/scalars | One call |
|
|
| Input | Visibility end/margin and shadow flag | Renderer configuration | MultiMeshInstance3D properties | Copied scalars | One call |
|
|
| Output | Attached `MultiMeshInstance3D` | Materializer | Parent SceneTree and loader Editor-owner adapter | Parent-owned node/resource | Tile lifetime |
|
|
|
|
Side effects are MultiMesh allocation, transform-buffer mutation,
|
|
MultiMeshInstance3D allocation/configuration and SceneTree attachment. The
|
|
service retains no direct reference after return.
|
|
|
|
## Data flow
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
Validate[Validate parent, Mesh, transforms and count] --> MultiMesh[Allocate TRANSFORM_3D MultiMesh]
|
|
MultiMesh --> MeshIdentity[Assign exact prepared Mesh]
|
|
MeshIdentity --> Count[Set instance count]
|
|
Count --> Upload[Upload transforms start plus ordered batch offset]
|
|
Upload --> Node[Create named MultiMeshInstance3D]
|
|
Node --> Render[Apply shadow and optional visibility end/margin]
|
|
Render --> Attach[Attach once to supplied parent]
|
|
Attach --> Return[Return attached node]
|
|
Validate -->|invalid| Null[Return null without attachment]
|
|
```
|
|
|
|
## Lifecycle/state
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> Validating
|
|
Validating --> Rejected: invalid or empty input
|
|
Validating --> Building: valid slice
|
|
Building --> Configured: transforms and render properties set
|
|
Configured --> Attached: parent add_child
|
|
Rejected --> [*]
|
|
Attached --> [*]: parent/tile owner releases subtree
|
|
```
|
|
|
|
The `RefCounted` service is stateless; states describe a single call.
|
|
|
|
## Main sequence
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant L as StreamingWorldLoader
|
|
participant P as M2BuildBatchPlanner
|
|
participant M as M2StaticBatchMaterializer
|
|
participant R as M2 parent root
|
|
L->>P: plan_batch(transform count, offset, static limits)
|
|
P-->>L: start/count and cursor transition
|
|
L->>L: resolve prepared Mesh or rotate pending job
|
|
L->>M: materialize_batch(parent, Mesh, transform slice, render settings)
|
|
M->>M: allocate MultiMesh and upload ordered transforms
|
|
M->>R: add_child(MultiMeshInstance3D)
|
|
M-->>L: attached node
|
|
L->>L: assign optional Editor owner
|
|
```
|
|
|
|
## Dependency diagram
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
Loader[StreamingWorldLoader] --> Materializer[M2StaticBatchMaterializer]
|
|
Planner[M2BuildBatchPlanner] --> Loader
|
|
MeshState[M2MeshResourceCacheState] --> Loader
|
|
Materializer --> Engine[Mesh / MultiMesh / MultiMeshInstance3D]
|
|
Loader --> EditorOwner[Editor ownership]
|
|
Loader --> Scheduler[RenderBudgetScheduler]
|
|
Materializer -. no dependency .-> ResourceIO[ResourceLoader / files]
|
|
Materializer -. no dependency .-> BuildState[Build jobs / queues / caches]
|
|
```
|
|
|
|
## Ownership, threading and resources
|
|
|
|
- The caller borrows a prepared Mesh and transform Array for the synchronous call.
|
|
- The new MultiMesh retains the exact Mesh Resource reference.
|
|
- The new MultiMeshInstance3D retains the MultiMesh and transfers to the parent.
|
|
- Parent/tile teardown owns node and Resource release through the SceneTree.
|
|
- Loader assigns an Editor owner after successful attachment when configured.
|
|
- All Resource and SceneTree mutation is main-thread-only.
|
|
- No RID is acquired or released directly by this service.
|
|
|
|
## Errors, cancellation and recovery
|
|
|
|
| Failure | Detection | Behavior | Diagnostic | Recovery |
|
|
|---|---|---|---|---|
|
|
| Null parent or Mesh | Entry guard | Return null without allocation/attachment | Synthetic contract fixture | Correct build composition/cache state |
|
|
| Empty transforms or non-positive count | Entry guard | Return null | Synthetic contract fixture | Planner supplies non-empty slice |
|
|
| Invalid transform bounds | Caller precondition | Historical indexed access behavior remains | Build planner/source regression | Repair job cursor/group state |
|
|
| Mesh pending | Outside service | Loader rotates job without calling service | Existing build/cache diagnostics | Async completion retries job |
|
|
| Tile cancelled | Outside service | Loader cancels before materialization or releases parent later | Shutdown regression | Eligible tile may requeue |
|
|
|
|
The service does not swallow invalid bounds or silently clamp/reorder transforms,
|
|
because doing so would change the accepted build-planner contract.
|
|
|
|
## Configuration and capabilities
|
|
|
|
| Setting/capability | Default | Profile | Runtime mutable | Effect |
|
|
|---|---|---|---|---|
|
|
| Transform format | `MultiMesh.TRANSFORM_3D` | All | No | Preserves full 3D M2 placements |
|
|
| Static batch count | Loader `m2_multimesh_batch_size` through planner | Quality preset | Yes, between plans | Controls per-batch transform count |
|
|
| Visibility end/margin | Loader M2 range / chunk size | Quality preset | Yes, between calls | Applied only when end is positive |
|
|
| Shadow mode | Loader `m2_cast_shadows` | Quality preset | Yes, between calls | Selects ON/OFF casting setting |
|
|
|
|
## Persistence, cache and migration
|
|
|
|
No state is serialized and no cache/schema version changes. The service consumes
|
|
the accepted prepared Mesh cache contract; no rebake or migration is required.
|
|
|
|
## Diagnostics and observability
|
|
|
|
- The service emits no logs, metrics or debug views.
|
|
- Existing loader queue/hitch metrics continue to account for `m2build` work.
|
|
- Path/serial remain visible through the unchanged batch node name.
|
|
- Editor ownership remains observable through the existing loader adapter.
|
|
|
|
## Verification
|
|
|
|
- `verify_m2_static_batch_materializer.gd` covers invalid inputs, node naming,
|
|
exact Mesh identity, transform format/count, ordered slice source contract,
|
|
visibility, shadows, single attachment, ownership boundaries and timing.
|
|
- Build planner, Mesh cache/extractor/finalizer, prototype, animated materializer,
|
|
shutdown, materials, facade and internal-access regressions protect neighbors.
|
|
- The headless dummy renderer does not round-trip per-instance transforms through
|
|
`MultiMesh.get_instance_transform`; exact ordered upload is protected by the
|
|
source contract and render checkpoints remain the observable regression gate.
|
|
- Fidelity evidence is exact extraction only; no new build-12340 parity claim.
|
|
- Performance budget: 10,000 transform API writes under one second in headless.
|
|
|
|
## Extension points
|
|
|
|
Measured spatial-cell batching may later provide smaller transform slices while
|
|
reusing this materializer. A generic static/animated base class, async mutation
|
|
and callback framework are intentionally excluded.
|
|
|
|
## Capability status
|
|
|
|
| Capability | Status | Evidence | Gap/next step |
|
|
|---|---|---|---|
|
|
| Static M2 MultiMesh materialization | Implemented extraction | Synthetic node/resource/render/source/timing verifier | Asset-backed traversal pending |
|
|
| Transform ordering | Implemented extraction | Exact source contract and existing checkpoints | Headless per-instance getter unavailable |
|
|
| Editor persistence | Existing loader-owned | Source boundary and editor helper | Editor integration fixture remains separate |
|
|
| Spatial-cell batching | Planned | Renderer roadmap | Culling/performance design and evidence pending |
|
|
|
|
## Known gaps and risks
|
|
|
|
- Materialization remains synchronous main-thread work under the existing permit.
|
|
- MultiMesh transform upload timing in a headless dummy renderer does not measure GPU cost.
|
|
- No private asset traversal, visual comparison, descriptor-pressure, leak or p95/p99 run exists.
|
|
- Current model-path batching is not culling-driven spatial-cell batching.
|
|
|
|
## Source map
|
|
|
|
| Path | Responsibility |
|
|
|---|---|
|
|
| `src/render/m2/m2_static_batch_materializer.gd` | Static MultiMesh allocation, transform upload, render setup and attachment |
|
|
| `src/render/m2/m2_build_batch_planner.gd` | Static/animated batch count and cursor planning |
|
|
| `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared static Mesh reference ownership |
|
|
| `src/scenes/streaming/streaming_world_loader.gd` | Resource readiness, job/budget adapter and Editor ownership |
|
|
| `src/tools/verify_m2_static_batch_materializer.gd` | Node/resource/render/source/timing regression |
|
|
|
|
## Related decisions and references
|
|
|
|
- [`m2-build-batch-planner.md`](m2-build-batch-planner.md)
|
|
- [`m2-mesh-resource-cache-state.md`](m2-mesh-resource-cache-state.md)
|
|
- [`m2-animated-instance-materializer.md`](m2-animated-instance-materializer.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)
|