sindoring/open-wc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(M03): add entity presentation facade

Browse Source
This commit is contained in:
sindoring
2026-07-16 01:11:58 +04:00
parent 3c5880f190
commit 1807c3a363
15 changed files with 829 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules/world-entity-presentation.md
+254
View File
@@ -0,0 +1,254 @@
# World Entity Presentation
## Metadata
| Field | Value |
|---|---|
| Status | Implemented boundary / Prototype visuals |
| Target/work package | M03 / `M03-RND-FACADE-ENTITY-001` |
| Owners | Renderer entity-presentation boundary and visual subtree lifecycle |
| Last verified | Worktree `work/sindo-main-codex/m03-facade-entity`, 2026-07-16 |
| Profiles/capabilities | Contract version 1; asset-free scene presentation only |
## Purpose
Accept immutable session-local entity visual snapshots through
`WorldRenderFacade`, create or update renderer-owned visual subtrees idempotently,
and remove them explicitly without making the renderer authoritative for entity,
gameplay, network or content state.
## Non-goals
- Allocate `EntityId` or map it to `WowGuid`, display ID or server entry.
- Present the separately composed local player through this service.
- Define build-12340 model, equipment, animation, effects or visibility rules.
- Own gameplay/world state, packet decoding, terrain or streaming decisions.
- Provide asynchronous loading, pooling, batching, persistence or cache formats.
## Context and boundaries
```mermaid
flowchart LR
WorldState[Future authoritative WorldState] --> Adapter[Entity presentation adapter]
Adapter --> Snapshot[EntityPresentationSnapshot v1]
Snapshot --> Facade[WorldRenderFacade]
Facade --> Presenter[WorldEntityPresenter]
Asset[PackedScene visual path] --> Presenter
Presenter --> Visual[Owned Node3D visual subtree]
LocalPlayer[Local player composition] -. separate boundary .-> Viewport[Rendered world]
Visual --> Viewport
```
Allowed dependencies:
- immutable M01 `EntityId` and `GodotWorldPosition` values;
- renderer-facing Godot transform and scene APIs;
- an explicit repository/resource path selected outside the renderer;
- `WorldRenderFacade` and main-thread runtime scene composition.
Forbidden dependencies:
- gameplay reducers, intents, combat/movement authority or entity allocation;
- packet codecs, GUID interpretation, server DB access or Content Project writes;
- streamer queues/tasks/caches, terrain query or camera/input state;
- hidden autoload, SceneTree group service lookup or persisted session IDs.
## Public API
| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|---|---|---|---|---|
| `EntityPresentationSnapshot.CONTRACT_VERSION` | Contract constant | Identifies additive snapshot contract version `1` | Compile/runtime constant | Incompatible changes require migration/ADR |
| `EntityPresentationSnapshot.create(...)` | Immutable value factory | Captures identity, typed position, visual path, yaw, scale and visibility | Any thread to construct; caller-owned | Invalid value carries stable `entity_presentation_*` failure code |
| `WorldRenderFacade.present_entity(snapshot)` | Command | Idempotently creates/updates/replaces one world visual | Main thread; world session | Returns `false` for invalid snapshot, missing service or failed scene creation |
| `WorldRenderFacade.remove_entity(entity_id)` | Command | Removes one known session visual | Main thread; world session | Returns `false` for invalid or unknown identity |
| `WorldRenderFacade.entity_presentation_snapshot()` | Diagnostic query | Returns detached scalar entity inventory | Main thread; caller-owned copy | Missing/invalid service returns empty snapshot with diagnostic |
| `WorldEntityPresenter.present_entity(snapshot)` | Internal service command | Owns visual load, attach, transform update and replacement | Main thread; service lifetime | Failed replacement retains prior valid subtree |
| `WorldEntityPresenter.remove_entity(entity_id)` | Internal service command | Detaches and schedules owned subtree deletion | Main thread | Unknown identity is unchanged/false |
## Inputs and outputs
| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|---|---|---|---|---|---|
| Input | Valid session-local `EntityId` | Future entity registry/adapter | Snapshot/presenter index | Immutable caller reference | One runtime session |
| Input | `GodotWorldPosition` | World-state presentation adapter | Snapshot/presenter transform | Immutable caller reference | One snapshot |
| Input | PackedScene resource path | Asset-selection adapter | Presenter | Copied string; resource remains Godot-owned | Until visual replacement |
| Input | Finite yaw radians, positive scale, visibility | Presentation adapter | Presenter | Scalar copies | One snapshot |
| Output | Owned Node3D subtree | Presenter | SceneTree/viewport | Presenter child ownership | Until replacement/removal/world teardown |
| Output | Detached inventory dictionary | Presenter/facade | Diagnostics/tests | Caller-owned deep copy | One query |
Side effects:
- synchronously loads a PackedScene only for first presentation or visual-path change;
- instantiates, attaches, transforms, detaches and queues visual Node3D subtrees;
- does not mutate authoritative state, streamer queues, caches, files, DB or network;
- does not retain caller snapshots after an entity entry is replaced or removed.
## Data flow
```mermaid
flowchart TD
ReadModel[Entity visual read model] --> Validate[Validate typed immutable snapshot]
Validate -->|invalid| Reject[Return false; no scene mutation]
Validate -->|valid| Lookup[Lookup by EntityId debug key]
Lookup -->|same visual path| Transform[Update world transform and visibility]
Lookup -->|new or changed path| Instantiate[Load and instantiate Node3D]
Instantiate -->|failure| Retain[Retain previous valid visual]
Instantiate -->|success| Replace[Detach old, attach replacement]
Replace --> Transform
Transform --> Inventory[Detached diagnostics]
Remove[remove_entity] --> Detach[Detach and queue_free owned root]
```
## Lifecycle/state
```mermaid
stateDiagram-v2
[*] --> Absent
Absent --> Presented: valid present + successful instantiate
Absent --> Absent: invalid/missing visual
Presented --> Presented: same-path snapshot update
Presented --> Replacing: changed visual path
Replacing --> Presented: replacement succeeds
Replacing --> Presented: replacement fails; retain old
Presented --> Absent: remove_entity
Presented --> [*]: world/service teardown
Absent --> [*]: world/service teardown
```
## Main sequence
```mermaid
sequenceDiagram
participant Adapter as World-state adapter
participant Facade as WorldRenderFacade
participant Presenter as WorldEntityPresenter
participant Loader as Godot ResourceLoader
participant Tree as SceneTree
Adapter->>Facade: present_entity(immutable snapshot)
Facade->>Presenter: present_entity(snapshot)
alt same identity and visual path
Presenter->>Tree: update transform/visibility
else new or changed visual
Presenter->>Loader: load PackedScene
Loader-->>Presenter: scene or failure
alt scene is valid Node3D
Presenter->>Tree: detach old, attach/configure new
else load/shape failure
Presenter-->>Facade: false; old visual retained
end
end
Adapter->>Facade: remove_entity(EntityId)
Facade->>Presenter: remove_entity(EntityId)
Presenter->>Tree: detach + queue_free owned root
```
## Ownership, threading and resources
- `EntityPresentationSnapshot` owns copied scalars/strings and immutable references
to caller-owned identity/position values; it owns no Node, Resource or RID.
- `WorldEntityPresenter` owns its dictionary and every visual root attached below it.
- A dictionary entry retains the latest snapshot only while the entity is presented;
diagnostics expose no Node, Resource or snapshot reference.
- Scene load, instantiation, transform mutation, replacement and removal are main-thread only.
- Successful replacement instantiates first, then detaches the previous root, so an
invalid/missing new asset cannot erase the last valid presentation.
- Parent SceneTree teardown owns attached children; `_exit_tree` drops the index so
no stale lookup survives world unload.
## Errors, cancellation and recovery
| Failure | Detection | Behavior | Diagnostic | Recovery |
|---|---|---|---|---|
| Invalid identity/type | Snapshot/service validation | Reject without mutation | `entity_presentation_invalid_entity_id` | Supply valid session `EntityId` |
| Non-finite position/yaw | Snapshot validation | Reject without mutation | Stable position/yaw failure code | Repair adapter read model |
| Empty path or invalid scale | Snapshot validation | Reject without mutation | Stable path/scale failure code | Supply valid visual descriptor |
| Missing/non-PackedScene asset | Resource existence/load check | New visual absent; old replacement retained | Named presenter warning | Restore asset mapping and resend snapshot |
| Non-Node3D scene root | Instance type check | Free invalid instance; retain old | Named presenter warning | Fix visual scene root |
| Unknown remove | Dictionary lookup | No mutation; return `false` | Caller command result | Reconcile registry/presentation lifecycle |
| World teardown | Scene lifecycle | SceneTree frees children; index clears | Shutdown regression | Recreate service with next world |
There is no background job to cancel. Synchronous asset load is an explicit
prototype limitation and must be replaced/budgeted before network-scale use.
## Configuration and capabilities
| Setting/capability | Default | Profile | Runtime mutable | Effect |
|---|---|---|---|---|
| Contract version | `1` | All | No | Identity/path/position/yaw/scale/visibility full snapshot |
| Present semantics | Idempotent by `EntityId` | Runtime/tools | No | Duplicate snapshots do not duplicate roots |
| Resource loading | Synchronous on create/replace | Prototype only | No | Not accepted as frame-critical production path |
| Local player | Separate composition | Current sandbox | No | Prevents facade service from owning gameplay player root |
## Persistence, cache and migration
- No snapshot, entity key or resource instance is persisted.
- `EntityId` remains session-local and must never enter content/cache schemas.
- Resource paths are current renderer adapter inputs, not stable content identity.
- Contract version 1 is additive. Changing identity lifetime, coordinate basis or
persisted representation requires a migration and ADR.
## Diagnostics and observability
- `entity_presentation_snapshot()` reports contract version, entity count and a
sorted list of `EntityId.to_debug_key`, visual path and visibility.
- The snapshot is deep-detached by the facade and contains no Node/Resource/RID.
- Load/type failures include the visual path but never proprietary bytes.
- Future performance telemetry should measure create/replace duration and active
entity/material/RID counts before introducing pooling or batching.
## Verification
- `src/tools/verify_world_entity_presentation.gd` covers eight value-contract and
fourteen lifecycle/ownership cases with repository-owned asset-free scenes.
- `src/tools/verify_world_render_facade.gd` covers command delegation, detached
diagnostics and both runtime scene service paths.
- Identity, coordinate, renderer-internal-access, shutdown, manifest, planner,
scheduler and documentation gates remain required.
- Fidelity boundary: runtime emits no entity commands yet, so existing seven
checkpoint scenes remain unchanged. No build-12340 display/animation parity is claimed.
## Extension points
- AssetRepository/display-ID adapter that produces validated visual descriptors.
- Async/budgeted load and main-thread finalize behind the same facade commands.
- Animation/equipment/effect snapshots after build-12340 fixtures define behavior.
- Spatial batching/MultiMesh only after profiling proves per-Node overhead.
- Entity registry adapter that maps `WowGuid` to session `EntityId` outside render.
## Capability status
| Capability | Status | Evidence | Gap/next step |
|---|---|---|---|
| Typed entity visual input | Implemented contract | Versioned immutable validation fixtures | Asset/display mapping not implemented |
| Present/update/remove lifecycle | Implemented boundary | Asset-free create/update/replace/remove tests | Network-scale async/budget path missing |
| Deterministic ownership | Implemented | One presenter-owned root per EntityId; teardown checks | RID/material budgets remain future work |
| WoW entity visual fidelity | Planned | No claim | Requires build-12340 display/equipment/animation fixtures |
## Known gaps and risks
- Synchronous PackedScene load may hitch and is not a production hot-path design.
- Resource path is renderer adapter data, not stable authored content identity.
- Full snapshots currently cover transform/visibility only, not animation/equipment/effects.
- One Node3D per entity is unprofiled at world scale; batching is deliberately deferred.
- The local player remains separately composed until gameplay/network architecture is ready.
## Source map
| Path | Responsibility |
|---|---|
| `src/render/entities/entity_presentation_snapshot.gd` | Immutable versioned entity visual input and validation |
| `src/render/entities/world_entity_presenter.gd` | Main-thread entity visual ownership and lifecycle |
| `src/render/world_render_facade.gd` | Stable public present/remove/diagnostic commands |
| `src/tools/verify_world_entity_presentation.gd` | Snapshot and scene lifecycle regression |
| `src/tests/scenes/character_presentation_model_fixture.tscn` | Primary asset-free visual fixture |
| `src/tests/scenes/world_entity_visual_replacement_fixture.tscn` | Replacement asset-free visual fixture |
| `src/scenes/streaming/*_streaming.tscn` | Runtime facade/service composition |
## Related decisions and references
- [`world-renderer.md`](world-renderer.md)
- [`domain-identities.md`](domain-identities.md)
- [`coordinate-mapping.md`](coordinate-mapping.md)
- [`../../targets/roadmap/02-rendering-and-graphics.md`](../../targets/roadmap/02-rendering-and-graphics.md)
- [`../ARCHITECTURE.md`](../ARCHITECTURE.md)
- [`../GODOT_BEST_PRACTICES.md`](../GODOT_BEST_PRACTICES.md)