131 lines
6.6 KiB
Markdown
131 lines
6.6 KiB
Markdown
# M03-RND-FACADE-ENTITY-001 — World entity presentation commands
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-FACADE-ENTITY-001:sindo-main-codex:2026-07-18 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-facade-entity`
|
|
- Lease expires UTC: 2026-07-18
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Add immutable, versioned world-entity presentation input and stable facade
|
|
commands for idempotent present/update and removal, backed by a renderer-owned
|
|
scene service with explicit entity subtree ownership.
|
|
|
|
## Non-goals
|
|
|
|
- Define authoritative entity/gameplay/network state or allocate/map identities.
|
|
- Move the local player controller/presenters behind the world-entity service.
|
|
- Implement build-12340 display IDs, equipment, animation, effects or visibility rules.
|
|
- Add background loading, pooling, MultiMesh conversion or a generic ECS/framework.
|
|
- Change streamer queues, caches, world assets, baseline visuals or target status.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/entities/entity_presentation_snapshot.gd`,
|
|
`src/render/entities/world_entity_presenter.gd`,
|
|
`src/tools/verify_world_entity_presentation.gd`,
|
|
`src/tests/scenes/world_entity_visual_replacement_fixture.tscn`,
|
|
`docs/modules/world-entity-presentation.md`, this claim
|
|
- Shared/hotspots: `src/render/world_render_facade.gd`, both runtime streaming
|
|
scenes, `src/tools/verify_world_render_facade.gd`, `docs/modules/world-renderer.md`,
|
|
`docs/modules/README.md`, `RENDER.md`, `targets/03-renderer-facade.md`
|
|
- Reused unchanged: `EntityId`, `GodotWorldPosition`, existing asset-free
|
|
character presentation model fixture
|
|
- Generated/ignored: `.godot`, native DLL, generated resources, caches and
|
|
proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Contract version: `EntityPresentationSnapshot.CONTRACT_VERSION = 1`
|
|
- Snapshot: valid session-local `EntityId`, typed Godot world position, visual
|
|
PackedScene path, finite yaw radians, positive finite uniform scale and visibility
|
|
- Public API: `WorldRenderFacade.present_entity`, `remove_entity`,
|
|
`entity_presentation_snapshot`
|
|
- Presenter behavior: present is idempotent by entity key; same visual updates
|
|
transform/visibility, changed visual replaces the owned subtree; remove is explicit
|
|
- Schema/cache/coordinate contracts: no persisted schema or cache change
|
|
|
|
## Dependencies
|
|
|
|
- Requires: integrated M03 environment facade master `a85e416`, M01 identity and
|
|
coordinate contracts
|
|
- Blocks: completion of the first M03 facade checklist item and later entity renderer extraction
|
|
- External state: none; tests use a repository-owned asset-free PackedScene fixture
|
|
|
|
## Verification
|
|
|
|
- Commands: cold snapshot contract; presenter lifecycle/ownership regression;
|
|
facade delegation and runtime wiring; identity/coordinate/internal-access;
|
|
renderer manifest/shutdown/planner/scheduler/focus and repository gates
|
|
- Fixtures: invalid identity/position/yaw/scale/path, spawn, idempotent update,
|
|
visual replacement, missing asset, removal, detached diagnostic snapshot and teardown
|
|
- Fidelity evidence: no runtime commands are produced yet, so existing scene output
|
|
and seven baseline plans remain unchanged
|
|
- Performance budget: constant-time entity lookup; synchronous resource load only
|
|
on first presentation/visual replacement and explicitly excluded from hot-path acceptance
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline public API docs: snapshot, facade commands and presenter lifecycle
|
|
- Module specification: new world-entity-presentation specification
|
|
- Data-flow diagram: read model through facade into owned visual subtree
|
|
- Sequence/state/dependency diagrams: present/update/replace/remove/failure/teardown
|
|
- Source map/status updates: module registry, world renderer and `RENDER.md`
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names introduced: `EntityPresentationSnapshot`, `WorldEntityPresenter`,
|
|
`present_entity`, `remove_entity`
|
|
- Simplest considered solution: one immutable full visual snapshot and one
|
|
dictionary-owned Node3D presenter below an explicit scene service
|
|
- Rejected complexity/abstractions: ECS, event bus, command hierarchy, factory
|
|
registry, pooling, async loader framework or duplicate identity registry
|
|
- Unavoidable complexity and justification: renderer must own and deterministically
|
|
replace/free visual subtrees while authoritative state remains external
|
|
- Measured optimization evidence: no optimization claim; lifecycle is asset-free tested
|
|
|
|
## Status
|
|
|
|
- State: ready-for-review
|
|
- Done: immutable contract-v1 snapshot, presenter ownership lifecycle, facade
|
|
commands, runtime composition, asset-free regressions and module documentation
|
|
- Next: M03 integrator reviews and merges `1807c3a`
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-FACADE-ENTITY-001:1807c3a -->
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-FACADE-ENTITY-001:606770c -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `1807c3a`
|
|
- Results: facade now exposes idempotent `present_entity`, explicit
|
|
`remove_entity` and detached diagnostics. Both runtime scenes compose a
|
|
`WorldEntityPresenter` that owns one replaceable visual subtree per valid
|
|
session `EntityId`; local player and authoritative state remain separate.
|
|
- Verification: entity `snapshot_cases=8 lifecycle_cases=14 runtime_scenes=2`;
|
|
facade `delegation=9 entity_contract=6`; identities `5/5/6/5`; character
|
|
presentation `9/10/3/1`; coordinate boundary `files=119`; internal access
|
|
`43/7/9/1`; environment/ground/terrain, manifest `7/7`, shutdown, scheduler
|
|
(`20000` iterations), planner (`250` iterations), focus, editor parse, dry-run,
|
|
coordination, documentation and diff gates passed.
|
|
- Fidelity: runtime produces no world-entity commands yet, so all seven baseline
|
|
plans and existing player/world output remain unchanged. No build-12340
|
|
display, equipment, animation, effects or visibility parity claim is added.
|
|
- External/local inputs: ignored native DLL and generated ADT scripts supported
|
|
editor/dry-run only. Missing proprietary ADT/DBC/character corpus produced the
|
|
expected degraded diagnostics.
|
|
- Remaining risks: PackedScene create/replace loads synchronously and is not an
|
|
accepted network-scale hot path; resource paths are adapter inputs rather than
|
|
stable content IDs; animation/equipment/effects and scale profiling remain open.
|
|
- Documentation updated: new world-entity-presentation API/input-output/data-flow/
|
|
lifecycle/sequence/ownership/failure/configuration/migration/diagnostic/source-map
|
|
spec; world renderer, module registry and `RENDER.md` updated.
|
|
- Integration: accepted in master merge `606770c`; post-merge entity/facade,
|
|
character, internal-access, manifest, shutdown, scheduler and planner gates passed.
|