107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# M03-RND-M2-STATIC-BATCH-MATERIALIZER-001
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-M2-STATIC-BATCH-MATERIALIZER-001:sindo-main-codex:2026-07-20 -->
|
|
|
|
## Owner
|
|
|
|
- Agent ID: `sindo-main-codex`
|
|
- Target: M03 Renderer Facade and Safe Extraction
|
|
- Branch: `work/sindo-main-codex/m03-m2-static-batch-materializer`
|
|
- Worktree: `C:\Users\sindo\open-wc-worktrees\m03-m2-static-batch-materializer`
|
|
|
|
## Outcome
|
|
|
|
Extract main-thread static M2 `MultiMesh` construction, render-property setup
|
|
and batch attachment from `StreamingWorldLoader`.
|
|
|
|
## Non-goals
|
|
|
|
- Change M2 grouping, batch sizing, build cursors, budgets or retry behavior.
|
|
- Change Mesh loading, refresh, cache ownership or missing-model outcomes.
|
|
- Own animated M2 instances, Editor persistence or tile cleanup.
|
|
- Introduce spatial cells or change transform order, visibility or shadows.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/m2/m2_static_batch_materializer.gd`,
|
|
`src/tools/verify_m2_static_batch_materializer.gd`,
|
|
`docs/modules/m2-static-batch-materializer.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`, M2 build/
|
|
Mesh-cache/facade/internal-access/manifest verifiers and specs,
|
|
`docs/modules/world-renderer.md`, `docs/modules/README.md`, `RENDER.md`,
|
|
`targets/03-renderer-facade.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated resources/caches and proprietary corpus
|
|
|
|
## Contracts and data
|
|
|
|
- `MultiMesh.TRANSFORM_3D`, exact Mesh identity, instance count and transform
|
|
slice order remain unchanged.
|
|
- Batch node name remains model basename plus serial.
|
|
- Visibility end/margin and shadow setting remain exact renderer inputs.
|
|
- A valid batch attaches once to the supplied M2 parent and returns its node.
|
|
- Loader retains Editor-owner assignment, build cursor, budgets and retries.
|
|
|
|
## Dependencies
|
|
|
|
- Requires: accepted animated materializer package on master `86814de`
|
|
- Blocks: further M2 build-job orchestration extraction
|
|
- External state: Godot MultiMesh and SceneTree mutation remain main-thread APIs
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated invalid/name/mesh/count/order/render/attachment/source/timing
|
|
verifier; M2 build/cache/prototype/animated/shutdown/material/facade/internal-
|
|
access/manifest regressions; docs/coordination/dry-run gates
|
|
- Fixtures: synthetic ArrayMesh and ordered Transform3D slices
|
|
- Fidelity evidence: exact existing MultiMesh construction and render settings
|
|
- Performance budget: materialize 10,000 transforms under one second
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline API docs
|
|
- Module spec with inputs/outputs, ownership and source map
|
|
- Data-flow, lifecycle/state, sequence and dependency diagrams
|
|
- Adjacent build/cache/world-renderer/module-registry/RENDER updates
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important name introduced: `M2StaticBatchMaterializer`
|
|
- Simplest solution: synchronous main-thread RefCounted returning attached node
|
|
- Rejected complexity: signals, async queue, callbacks and generic materializer base
|
|
- Unavoidable complexity: MultiMesh is a Godot Resource owned through its node
|
|
- Measured optimization evidence: bounded synthetic transform upload
|
|
|
|
## Status
|
|
|
|
- State: ready for integration
|
|
- Done: materializer, loader adapter, verifier and required documentation
|
|
- Next: integrator merge and post-merge acceptance
|
|
- Blocked by:
|
|
|
|
## Handoff
|
|
|
|
- Commit: `252927d`
|
|
- Results: materializer passes 11 invalid/node/Mesh/render/attachment/source
|
|
cases and 10,000 transform API writes in 0.552 ms; all 51 autonomous headless
|
|
verifiers pass, while the proprietary ADT placement probe is unavailable
|
|
without `data/extracted`; checkpoint dry-run passes 7/7; documentation and
|
|
coordination gates pass; loader-private inventory remains 30.
|
|
- Remaining risks: headless dummy timing excludes GPU upload cost; private asset
|
|
traversal/visual comparison, spatial-cell culling, descriptor pressure, leaks
|
|
and p95/p99 remain unavailable; no original-client comparison is claimed.
|
|
- Documentation updated: inline API; `m2-static-batch-materializer.md` with
|
|
data-flow, lifecycle, sequence and dependency diagrams; build/cache/world-
|
|
renderer specs, module registry and `RENDER.md`.
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-M2-STATIC-BATCH-MATERIALIZER-001:252927d -->
|
|
|
|
## Integration
|
|
|
|
- Merge commit: `5e82daa`
|
|
- Post-merge results: static materializer `cases=11 instances=10000
|
|
elapsed_ms=1.327`; build/cache/animated materializer, shutdown, facade,
|
|
internal-access `30`, checkpoint dry-run `7/7`, documentation and coordination
|
|
gates passed.
|
|
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-STATIC-BATCH-MATERIALIZER-001:5e82daa -->
|