115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# M03-RND-M2-PLACEMENT-GROUPER-001 — M2 placement grouper
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-M2-PLACEMENT-GROUPER-001:sindo-main-codex:2026-07-19 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-m2-placement-grouper`
|
|
- Lease expires UTC: 2026-07-19
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract pure ADT M2 placement validation, path normalization and local-transform
|
|
grouping from the worker callback into a scene-free service.
|
|
|
|
## Non-goals
|
|
|
|
- Change placement ordering, coordinate conversion, transform formulas or clamps.
|
|
- Move WorkerThreadPool tasks, mutex/result queues, tile state or retry behavior.
|
|
- Move build jobs, animation/mesh loading, caches, Nodes, MultiMesh or RIDs.
|
|
- Generalize grouping policy, change batching or add a dependency.
|
|
- Claim build-12340 placement or visual parity beyond preserved formulas.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/m2/m2_placement_grouper.gd`,
|
|
`src/tools/verify_m2_placement_grouper.gd`,
|
|
`docs/modules/m2-placement-grouper.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
|
|
`src/tools/verify_m2_placement_transform_resolver.gd`,
|
|
`docs/modules/m2-placement-transform-resolver.md`,
|
|
`docs/modules/world-renderer.md`, `docs/modules/README.md`, `RENDER.md`,
|
|
`targets/03-renderer-facade.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated ADT resources, caches and
|
|
proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Input: tile-local origin, MMDX name table and raw ADT M2 placement array
|
|
- Output: fresh Dictionary keyed by historically normalized relative M2 path;
|
|
each value is a fresh ordered Array of tile-local `Transform3D` values
|
|
- Invalid variants, out-of-range name IDs and empty paths are skipped
|
|
- Backslashes become slashes; lowercase `.mdx/.mdl` suffixes become `.m2`
|
|
- Transform basis/origin delegates to `M2PlacementTransformResolver`; final basis
|
|
scale retains the grouping-path clamp `max(scale, 0.0001)`
|
|
- Cache/schema/coordinate versions: unchanged
|
|
|
|
## Dependencies
|
|
|
|
- Requires: current master `c34e538`, `M2PlacementTransformResolver`
|
|
- Blocks: broader M2 worker/build decomposition
|
|
- External state: none; tests use synthetic names and placement dictionaries
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated invalid/name/path/group-order/default/transform/scale and
|
|
bounded timing verifier; loader source boundary; resolver/registry/dedupe plus
|
|
facade/internal-access/manifest/shutdown/documentation/coordination gates
|
|
- Fidelity evidence: exact loop rules and transform composition moved unchanged
|
|
- Performance budget: linear over placement count with fresh output containers;
|
|
no Node, Resource, RID, task, mutex, cache or file access
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline grouper API documentation
|
|
- New module spec with inputs/outputs, data-flow, lifecycle, ownership, failure,
|
|
performance, fidelity limitations and source map
|
|
- Transform resolver, renderer/module registry and `RENDER.md` updates
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important name: `M2PlacementGrouper`
|
|
- Simplest solution: one stateless `group_placements` query
|
|
- Rejected complexity: group/result classes, strategy interfaces, callbacks,
|
|
Resources, policies or generic spatial batching framework
|
|
- Unavoidable complexity: raw ADT dictionaries remain at the parser adapter
|
|
- Measured optimization evidence: bounded synthetic grouping loop
|
|
|
|
## Status
|
|
|
|
- State: accepted
|
|
- Done: pure grouper, worker adapter, regressions and documentation verified
|
|
- Next: M2 worker/build state extraction and spatial-cell evidence
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-M2-PLACEMENT-GROUPER-001:9df32d3 -->
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-PLACEMENT-GROUPER-001:f88bf97 -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `9df32d3` (`refactor(M03): extract M2 placement grouper`)
|
|
- Results: dedicated grouper PASS (`cases=9`, `iterations=100`,
|
|
`placements=256`, `elapsed_ms=67.736`); transform resolver PASS (`cases=9`,
|
|
`iterations=10000`, `elapsed_ms=28.571`); M2 registry/dedupe, terrain
|
|
cache/LOD/queue, facade, internal-access, manifest, shutdown, scheduler,
|
|
streaming planner/focus, terrain-query and coordinate-boundary suites PASS;
|
|
editor import parsed the project with only expected missing private corpus
|
|
diagnostics; documentation PASS (`module_specs=17`, `required_files=7`);
|
|
coordination PASS with 23 pre-existing expired M00/M01 warnings; checkpoint
|
|
dry-run planned `7/7`.
|
|
- Remaining risks: no private asset-backed traversal/visual comparison;
|
|
uppercase extension preservation is historical but inconsistent with the
|
|
resolver's case-insensitive exception matching; grouping remains model-path
|
|
based rather than spatial-cell based; worker/build state and p95/p99 remain.
|
|
- Documentation updated: inline public API; new
|
|
`docs/modules/m2-placement-grouper.md`; transform resolver module spec,
|
|
renderer module registry, `docs/modules/world-renderer.md` and `RENDER.md`.
|
|
- Integration: accepted in master merge `f88bf97`; post-merge grouper
|
|
(`cases=9`, `iterations=100`, `placements=256`, `elapsed_ms=67.104`),
|
|
transform resolver, registry, internal-access, facade, manifest,
|
|
documentation and coordination gates passed.
|