# M03-RND-FACADE-ENTITY-001 — World entity presentation commands ## 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: ## 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.