117 lines
5.3 KiB
Markdown
117 lines
5.3 KiB
Markdown
# M03-RND-ADT-WATER-SCENE-FINALIZER-001 — ADT water scene finalizer
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-ADT-WATER-SCENE-FINALIZER-001:sindo-main-codex:2026-07-20 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-adt-water-scene-finalizer`
|
|
- Lease expires UTC: 2026-07-20
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract main-thread ADT water subtree construction, tile-root attachment and
|
|
optional recursive editor ownership from `StreamingWorldLoader` while retaining
|
|
the existing `ADTBuilder` geometry/material implementation.
|
|
|
|
## Non-goals
|
|
|
|
- Parse or reinterpret MH2O/MCLQ data.
|
|
- Own pending requests, WorkerThreadPool tasks or parsed-result delivery.
|
|
- Consume `WATER_FINALIZE` permits or validate tile/path/result staleness.
|
|
- Mark tile state `water_loaded` or choose whether water is enabled.
|
|
- Change liquid geometry, materials, coordinates, cache formats or profiles.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/liquid/adt_water_scene_finalizer.gd`,
|
|
`src/tools/verify_adt_water_scene_finalizer.gd`,
|
|
`docs/modules/adt-water-scene-finalizer.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
|
|
`src/tools/verify_adt_water_load_pipeline_state.gd`,
|
|
`docs/modules/adt-water-load-pipeline-state.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
|
|
|
|
- Empty water data or invalid tile root produces no Node and no scene mutation.
|
|
- Existing `ADTBuilder.build_tile_water_scene` remains the only geometry/material source.
|
|
- A non-empty built Water root is attached exactly once to the supplied tile root.
|
|
- Optional editor ownership is assigned recursively only when explicitly enabled
|
|
and an edited scene root is available.
|
|
- The returned Node is borrowed and remains owned by the tile SceneTree subtree.
|
|
|
|
## Dependencies
|
|
|
|
- Requires: accepted water pipeline package on current master `e1b2886`
|
|
- Blocks: further liquid finalization/material responsibility extraction
|
|
- External state: none; verification uses synthetic liquid dictionaries
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated empty/invalid/build/attach/editor-owner/source/timing
|
|
verifier; water pipeline, materials, shutdown, facade, internal-access,
|
|
manifest, documentation and coordination gates
|
|
- Fixtures: synthetic one-cell liquid mask/heights and temporary Node roots
|
|
- Fidelity evidence: exact existing ADTBuilder output and two attachment paths preserved
|
|
- Performance budget: 100 empty finalization attempts under 1 second
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline public API docs
|
|
- Module specification with inputs/outputs, ownership and source map
|
|
- Data-flow, lifecycle/state, main-thread sequence and dependency diagrams
|
|
- Water-pipeline, world-renderer, module registry and RENDER status updates
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names introduced: `AdtWaterSceneFinalizer`
|
|
- Simplest considered solution: one RefCounted with one explicit attach operation
|
|
- Rejected complexity/abstractions: generic scene finalizer, signals, callbacks,
|
|
builder interface, queue ownership or alternate liquid renderer
|
|
- Unavoidable complexity and justification: editor-persisted generated subtrees
|
|
require recursive owner assignment after SceneTree attachment
|
|
- Measured optimization evidence: bounded synthetic no-water loop
|
|
|
|
## Status
|
|
|
|
- State: accepted
|
|
- Done: stateless finalizer implemented; both loader water paths migrated;
|
|
synthetic scene/owner regression and required documentation added
|
|
- Next: continue liquid parsing/task execution extraction or another remaining M03 boundary
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-ADT-WATER-SCENE-FINALIZER-001:874fd0f -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `235be3a`
|
|
- Results: scene finalizer PASS (`cases=8`, `iterations=100`,
|
|
`elapsed_ms=0.042`; initial `0.024ms`); synthetic liquid produced one
|
|
four-vertex/six-index surface with tile attachment and recursive owner; water
|
|
pipeline (`119.648ms`), WMO/M2/terrain/facade/scheduler/streaming/coordinate,
|
|
materials, shutdown, internal-access `36` and 32 headless contract regressions
|
|
PASS; documentation and coordination gates PASS; checkpoint dry-run PASS `7/7`.
|
|
- Remaining risks: main-thread mesh/material construction remains synchronous
|
|
behind one existing permit; the Dictionary builder boundary remains untyped;
|
|
proprietary MH2O/MCLQ traversal/leak/p95/p99/original-client evidence is absent.
|
|
A verifier launched concurrently with the initial cold editor import observed
|
|
the pre-existing global-class cache race; serialized editor parse and shutdown
|
|
rerun passed, with only expected missing private asset diagnostics.
|
|
- Documentation updated: inline public API; new
|
|
`docs/modules/adt-water-scene-finalizer.md`; water-pipeline spec, module registry,
|
|
world renderer and `RENDER.md`; data-flow/state/sequence/dependency diagrams,
|
|
ownership, main-thread effects, failure/recovery, migration and source map included.
|
|
- Integration: merged as `874fd0f`; post-merge finalizer (`cases=8`,
|
|
`iterations=100`, `elapsed_ms=0.025`), water pipeline (`98.398ms`), shutdown,
|
|
renderer materials, facade, internal-access (`private_symbols=36`), `7/7`
|
|
manifest, documentation and coordination gates passed.
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-ADT-WATER-SCENE-FINALIZER-001:235be3a -->
|