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/README.md
+1
View File
@@ -15,6 +15,7 @@
| Third-person camera | Implemented | [`third-person-camera.md`](third-person-camera.md) |
| Character presentation | Implemented boundary / Partial fidelity | [`character-presentation.md`](character-presentation.md) |
| Renderer | Partial | [`world-renderer.md`](world-renderer.md), [`../../RENDER.md`](../../RENDER.md) |
| World entity presentation | Implemented boundary / Prototype visuals | [`world-entity-presentation.md`](world-entity-presentation.md) |
| Streaming target planner | Implemented | [`streaming-target-planner.md`](streaming-target-planner.md) |
| Render budget scheduler | Implemented | [`render-budget-scheduler.md`](render-budget-scheduler.md) |
| Network/session | Planned | [`../../targets/roadmap/03-network-and-session.md`](../../targets/roadmap/03-network-and-session.md) |
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)
docs/modules/world-renderer.md
+40 -6
View File
@@ -5,9 +5,9 @@
| Field | Value |
|---|---|
| Status | Partial |
| Target/work package | M00 baseline; `M01-RND-STREAMING-FOCUS-001`; `M01-QAR-SERVER-SPAWN-RENDERER-001`; `M03-RND-FACADE-001`; `M03-RND-STREAMING-PLANNER-001`; `M03-RND-SCHEDULER-001`; `M03-RND-INTERNAL-ACCESS-GATE-001`; `M03-RND-FACADE-GROUND-QUERY-001`; `M03-RND-FACADE-ENVIRONMENT-001` |
| Target/work package | M00 baseline; `M01-RND-STREAMING-FOCUS-001`; `M01-QAR-SERVER-SPAWN-RENDERER-001`; `M03-RND-FACADE-001`; `M03-RND-STREAMING-PLANNER-001`; `M03-RND-SCHEDULER-001`; `M03-RND-INTERNAL-ACCESS-GATE-001`; `M03-RND-FACADE-GROUND-QUERY-001`; `M03-RND-FACADE-ENVIRONMENT-001`; `M03-RND-FACADE-ENTITY-001` |
| Owners | Renderer workstream / milestone integrator |
| Last verified | Worktree `work/sindo-main-codex/m03-facade-environment`, 2026-07-16 |
| Last verified | Worktree `work/sindo-main-codex/m03-facade-entity`, 2026-07-16 |
| Profiles/capabilities | `Performance`, `Balanced`, `High`, `Custom`; Blizzlike fidelity incomplete |
## Purpose
@@ -49,6 +49,10 @@ flowchart LR
Facade --> SkyController[WowSkyController]
Sky[DBC sky/light data] --> SkyController
SkyController --> Scene
EntityState[Entity visual read model] --> EntitySnapshot[EntityPresentationSnapshot]
EntitySnapshot --> Facade
Facade --> EntityPresenter[WorldEntityPresenter]
EntityPresenter --> Scene
```
Allowed dependencies:
@@ -69,9 +73,9 @@ Forbidden dependencies:
## Public API
Runtime, capture and probe callers use `WorldRenderFacade` for focus, immutable
environment input, metrics and rendered-ground diagnostics. `StreamingWorldLoader`
and `WowSkyController` remain internal scene implementations while a later M03
package adds entity-visual commands.
environment/entity presentation input, metrics and rendered-ground diagnostics.
`StreamingWorldLoader`, `WowSkyController` and `WorldEntityPresenter` remain
internal scene implementations.
Gameplay modules and Godot `EditorPlugin` package sources are repository-gated
from externally reading/writing loader-private queue, task, cache and tile-state fields.
@@ -90,6 +94,11 @@ from externally reading/writing loader-private queue, task, cache and tile-state
| `WorldRenderFacade.apply_environment_snapshot` | Public command | Delegates exact world time to the scene-owned DBC sky controller | Main thread; snapshot remains caller-owned | Returns `false` for invalid input or missing/incompatible controller |
| `WorldRenderFacade.streaming_world_loader_path` | Internal adapter property | Resolves the existing implementation without exposing it to consumers | Main thread, scene lifetime | Missing method/path produces one diagnostic until recovery |
| `WorldRenderFacade.world_environment_controller_path` | Internal adapter property | Resolves the existing `WowSkyController` without exposing it to consumers | Main thread, scene lifetime | Missing method/path produces one diagnostic until recovery |
| `EntityPresentationSnapshot.create` | Immutable value factory | Validates contract-v1 identity, typed position, visual path, yaw, scale and visibility | Any thread; caller-owned | Stable invalid code; never mutates scene |
| `WorldRenderFacade.present_entity` | Public command | Idempotently creates/updates/replaces one session entity visual | Main thread/session | Returns false for invalid input, missing service or visual load/type failure |
| `WorldRenderFacade.remove_entity` | Public command | Removes one known session entity visual | Main thread/session | Invalid/unknown identity returns false |
| `WorldRenderFacade.entity_presentation_snapshot` | Public diagnostic query | Returns detached scalar entity inventory | Main thread/caller-owned copy | Missing/invalid service returns empty dictionary with diagnostic |
| `WorldRenderFacade.world_entity_presenter_path` | Internal adapter property | Resolves renderer-owned entity visual service | Main thread/scene lifetime | Missing methods/path produces one diagnostic until recovery |
| `camera_path` | Exported property | Camera used only by optional automatic overview positioning | Main thread, scene lifetime | Missing camera skips automatic positioning |
| `quality_preset` | Exported property | Applies renderer budgets/radii | Before/at runtime depending property | Invalid combination should be diagnosed |
| `runtime_stats_enabled` | Exported property | Enables periodic performance snapshot | Runtime mutable | Logging overhead only |
@@ -107,6 +116,8 @@ loader configuration remains transitional composition data, not a caller API.
| Input | Focus-source `NodePath` | Runtime/test scene composition | `WorldRenderFacade` source adapter | Scene-owned node, sampled position | Main thread/scene lifetime |
| Input | Ground-query `GodotWorldPosition` | Renderer probe/future adapter | `WorldRenderFacade` | Immutable caller-held value | One main-thread query |
| Input | `WorldEnvironmentSnapshot` | World-state/capture adapter | `WorldRenderFacade` / `WowSkyController` | Immutable caller-held value; not retained | One main-thread update |
| Input | `EntityPresentationSnapshot` | Future world-state/preview adapter | `WorldRenderFacade` / entity presenter | Immutable caller-held full visual snapshot | One main-thread present/update |
| Input | `EntityId` removal command | Future entity registry/adapter | `WorldRenderFacade` / entity presenter | Immutable session-local value | One main-thread removal |
| Input | Map/configuration | Scene/app/editor | `StreamingWorldLoader` | Caller config, copied/read | Main thread/session |
| Input | WDT/ADT/M2/WMO/BLP bytes | Extracted asset repository | Native loaders/builders | Loader result owns parsed data | Worker or controlled load |
| Input | Baked resources | Cache build tools | Streamer/builders | Shared immutable resource/cache entry | Session/cache lifetime |
@@ -118,6 +129,8 @@ loader configuration remains transitional composition data, not a caller API.
| Output | Detached renderer metrics | `WorldRenderFacade` | Capture/baseline tools | Caller-owned deep copy | On demand |
| Output | `RenderedGroundSample` | `WorldRenderFacade`/loaded terrain | Renderer diagnostics | Immutable caller-held value | One query |
| Output | Detached rendered-ground snapshot | `WorldRenderFacade` | Terrain-height probe | Caller-owned deep copy | One query |
| Output | Entity visual Node3D subtree | `WorldEntityPresenter` | SceneTree/viewport | Presenter-owned child | Until replace/remove/teardown |
| Output | Detached entity inventory | `WorldRenderFacade` | Diagnostics/tests | Caller-owned deep copy | One query |
| Output | Logs/diagnostics | Hitch/stat instrumentation | Logs/baseline tools | Immutable records | Periodic/frame |
| Test output | Diagnostic spawn marker and cold/warm PNGs | Checkpoint capture tool | Human/integrator review | SceneTree marker; `user://` files | One capture process |
@@ -160,6 +173,11 @@ flowchart TD
RF --> SkyController[WowSkyController]
DBC[Light/Area/Skybox DBC] --> SkyController
SkyController --> World
EntityReadModel[Entity visual read model] --> EntitySnapshot[EntityPresentationSnapshot]
EntitySnapshot --> RF
RF --> EntityPresenter[WorldEntityPresenter]
EntityAsset[PackedScene path] --> EntityPresenter
EntityPresenter --> World
Terrain --> World[Godot world]
M2 --> World
WMO --> World
@@ -218,6 +236,11 @@ sequenceDiagram
Source->>Facade: apply_environment_snapshot(exact time)
Facade->>Render: delegate to WowSkyController
Render->>Render: freeze local clock; retain DBC sampling/apply rules
Source->>Facade: present_entity(full visual snapshot)
Facade->>Render: delegate to WorldEntityPresenter
Render->>Render: create/update/replace owned entity root
Source->>Facade: remove_entity(EntityId)
Facade->>Render: detach and queue_free owned root
Stream->>Budget: shutdown: cancel permit issuance
Stream->>Worker: shutdown: wait for WorkerThreadPool tasks
Stream->>Stream: shutdown: finish registered ResourceLoader requests
@@ -236,6 +259,10 @@ sequenceDiagram
into its existing fixed-clock fields on the main thread.
- `WowSkyController` continues to own DBC sampling state and mutations of its
duplicated Godot `Environment`, sun, skybox node and world shader globals.
- `WorldEntityPresenter` owns one optional visual Node3D subtree per presented
`EntityId`; it owns no authoritative entity state and excludes the local player.
- Entity presentation snapshots remain caller-owned inputs. Detached diagnostics
expose only identity debug keys, paths and visibility, never Node/Resource/RID.
- Rendered-ground query results and diagnostic snapshots are caller-owned values;
the facade never returns Mesh, Node, tile-state or queue references.
- Loaded-mesh ground sampling is renderer diagnostics, not authoritative gameplay
@@ -264,6 +291,9 @@ sequenceDiagram
| Invalid metrics result | Facade return-type validation | Return empty caller snapshot | Facade error | Restore `Dictionary` implementation contract |
| Invalid environment time | Snapshot finite-value validation | Reject update; retain prior sky clock | `environment_time_not_finite` on invalid value | Supply a finite time snapshot |
| Missing environment controller | Facade path/method validation | Reject environment update; other facade APIs remain available | One facade diagnostic until recovery | Fix scene composition path/implementation |
| Invalid entity visual snapshot | Contract validation | Reject without scene mutation | Stable `entity_presentation_*` failure code | Repair adapter read model and resend |
| Missing/invalid entity visual asset | Resource existence/load/root check | New entity absent or prior replacement retained | Named presenter warning | Restore asset mapping and resend snapshot |
| Missing entity presenter | Facade path/method validation | Reject entity commands; other facade APIs remain available | One facade diagnostic until recovery | Fix runtime scene composition |
| No focus supplied | Refresh contract | No target recomputation; queues continue draining | `refresh_streaming_focus()` returns `false` | Supply player/editor/capture focus |
| Cache version mismatch | Required format constant | Reject stale cache/fallback | Version diagnostic | Rebuild matching cache |
| Worker failure | Task result/empty data | Skip/degrade affected asset | Queue/task warning | Retry/rebuild source |
@@ -344,8 +374,9 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
| Character presentation | Prototype | Character creator/player experiment | Full customization/equipment states |
| Camera-independent streaming focus | Implemented | Typed contract, two player-focused runtime scenes and three explicitly camera-focused diagnostic tools | Multi-focus/direction/velocity belong to planner extraction |
| Golden server-spawn visualization | Implemented | Pinned AzerothCore fixture, validated renderer manifest and diagnostic origin-marker capture at ADT `(32,48)`/MCNK `(3,12)` | No TrinityCore row or original-client visual-parity claim |
| Stable renderer facade | Partial | Facade contracts cover focus, environment time, metrics and loaded-mesh ground query | Entity visuals remain |
| Stable renderer facade | Implemented boundary / Partial fidelity | Facade contracts cover focus, environment, entity visuals, metrics and loaded-mesh ground query | Production consumers and fidelity remain |
| Environment snapshot input | Implemented boundary / Partial fidelity | Immutable time contract, facade/controller delegation and checkpoint migration | Weather/indoor state and paired zone-transition fidelity remain |
| Entity presentation commands | Implemented boundary / Prototype visuals | Versioned typed snapshot plus present/remove lifecycle and runtime service composition | Display/equipment/animation/effects and async scale path remain |
| Pure streaming target planner | Implemented | `M03-RND-STREAMING-PLANNER-001` asset-free contract/performance regression | Queue scheduling and loaded-tile LOD application remain in streamer |
| Bounded render budget scheduler | Implemented | `M03-RND-SCHEDULER-001` asset-free permit/cancellation/performance regression | Queue storage, worker concurrency and operation execution remain in streamer/services |
| Gameplay/editor/tool internal-access boundary | Implemented | Access gate scans gameplay, EditorPlugin packages and terrain probe against actual private streamer declarations | Add future renderer diagnostic tools explicitly to the protected list |
@@ -380,6 +411,8 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
|---|---|
| `src/render/world_render_facade.gd` | Stable caller boundary for typed focus/environment, detached metrics and rendered-ground queries |
| `src/render/environment/world_environment_snapshot.gd` | Immutable normalized world time input with explicit invalid state |
| `src/render/entities/entity_presentation_snapshot.gd` | Immutable contract-v1 entity visual input and validation |
| `src/render/entities/world_entity_presenter.gd` | Main-thread entity visual subtree ownership and lifecycle |
| `src/render/terrain/rendered_ground_sample.gd` | Immutable renderer-owned available/unavailable ground query result |
| `src/render/streaming/streaming_target_planner.gd` | Scene-free wanted/retained ADT target calculation |
| `src/render/streaming/streaming_target_policy.gd` | Immutable renderer radius/prefetch policy |
@@ -390,6 +423,7 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
| `src/tools/verify_streaming_focus.gd` | Headless contract, dependency and runtime/tool wiring regression |
| `src/tools/verify_world_render_facade.gd` | Focus/environment/metrics/ground delegation, snapshot isolation and consumer wiring regression |
| `src/tools/verify_world_environment_snapshot.gd` | Cold-start environment value normalization and invalid-input regression |
| `src/tools/verify_world_entity_presentation.gd` | Entity snapshot, create/update/replace/remove and ownership regression |
| `src/tools/verify_rendered_ground_sample.gd` | Cold-start renderer ground result invariant regression |
| `src/tools/verify_streaming_target_planner.gd` | Planner behavior, dependency and bounded timing regression |
| `src/tools/verify_render_budget_scheduler.gd` | Scheduler bounds, shared-lane priority, cancellation and timing regression |