Player Preview Render Cache And Keyed Entity Lifecycle

The player-preview render cache and keyed entity lifecycle keep scene, actor, mob, NPC, and effect visuals reusable without leaving ghost sprites or stale handles behind.

How It Works

Preview render asset cache scopes namespace loaded handles by scene and profile. Targeted invalidation and dependency polling decide when paths reload. Keyed entity reconcilers track root and child entities so visuals can be reused, reparented, or pruned when authored data changes.

Actor deltas can update a subset of visuals when the key and dependency signature are stable. Full rebuilds are reserved for structural changes.

How To Use It

Use normalized paths in cache keys. Prefer targeted path invalidation when a known asset changes and scope invalidation when a profile or scene changes. Use keyed entity helpers for actor visuals instead of manually spawning unmanaged child sprites.

Invariants

Every keyed visual must have an owner key. Child entities should be pruned when their key disappears. Dependency polling must detect hot reloads without rebuilding unrelated scopes. Full rebuilds must clear stale roots.

Debugging

Stale images usually mean path normalization or dependency polling failed. Missing hot reloads point to targeted invalidation. Ghost sprites mean a keyed child was spawned outside the reconciler or not pruned after a scene change.

Examples

If an NPC outfit changes but the old sprite remains, check the visual revision key and cache scope. If deleting an actor leaves children behind, inspect the keyed entity cleanup path rather than the sprite renderer.