# M03-RND-M2-ANIMATED-INSTANCE-MATERIALIZER-001

<!-- OPENWC_CLAIM:M03-RND-M2-ANIMATED-INSTANCE-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-animated-instance-materializer`
- Worktree: `C:\Users\sindo\open-wc-worktrees\m03-m2-animated-instance-materializer`

## Outcome

Extract main-thread animated M2 instance duplication, render-property application,
playback startup and batch attachment from `StreamingWorldLoader`.

## Non-goals

- Change build-job cursors, budgets, prototype selection or animation eligibility.
- Change animation selection, phase, native animator behavior or diagnostic text.
- Own Editor scene persistence, static MultiMesh materialization or tile cleanup.
- Change visible transforms, visibility ranges, shadows or placement ordering.

## Paths

- Exclusive: `src/render/m2/m2_animated_instance_materializer.gd`,
  `src/tools/verify_m2_animated_instance_materializer.gd`,
  `docs/modules/m2-animated-instance-materializer.md`, this claim
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`, M2 animation
  playback/finalizer/build/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

- Duplicate flags, names, transforms and input order remain unchanged.
- Visibility end/margin and shadow mode are applied recursively before attachment.
- Playback data copy/start delegates to the accepted playback controller contract.
- The batch is attached only when at least one duplicate succeeds.
- Loader retains diagnostic formatting/path normalization and Editor ownership.

## Dependencies

- Requires: accepted playback package on master `5b2d9f2`
- Blocks: further animated M2 build orchestration extraction
- External state: Godot Node duplication and SceneTree attachment remain main-thread APIs

## Verification

- Commands: dedicated duplication/order/render/playback/empty/source/timing verifier;
  M2 animated pipeline/finalizer/playback/prototype/build/shutdown/material/facade/
  internal-access/manifest regressions; docs/coordination/dry-run gates
- Fixtures: synthetic prototype trees with geometry, AnimationPlayer and native animator
- Fidelity evidence: exact transforms, flags, render settings, playback delegation and order
- Performance budget: 1,000 synthetic instances under 1 second

## Documentation deliverables

- Inline API docs
- Module spec with inputs/outputs, ownership and source map
- Data-flow, lifecycle/state, sequence and dependency diagrams
- Adjacent playback/finalizer/build/world-renderer/module-registry/RENDER updates

## Simplicity and naming

- Important name introduced: `M2AnimatedInstanceMaterializer`
- Simplest solution: synchronous main-thread RefCounted returning batch diagnostics
- Rejected complexity: signals, async queue, callbacks and generic scene factory
- Unavoidable complexity: imported AnimationPlayer and native animator paths coexist
- Measured optimization evidence: bounded synthetic batch materialization

## Status

- State: active
- Done: contract and ownership boundary
- Next: implementation, verification and documentation
- Blocked by:

## Handoff

- Commit:
- Results:
- Remaining risks:
- Documentation updated: