Skip to content

refactor: make runtime storage World-owned and generation-aware - #78

Merged
Milky2018 merged 2 commits into
mainfrom
milky/world-runtime-storage
Nov 12, 2026
Merged

Milky2018 merged 2 commits into
mainfrom
milky/world-runtime-storage

Conversation

@Milky2018

@Milky2018 Milky2018 commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Runtime subsystems retained World-specific state in global maps and exposed mutable entity-indexed caches. Give those resources World ownership, use slot-indexed runtime storage, and expose per-entity results and operations while retaining old generations long enough to release external resources.

Changes

  • Add EntityTable[T] with full entity-handle validation, insertion-ordered traversal, reusable entry storage, and explicit orphan-generation cleanup. Migrate UI, visibility, audio, physics, scene, animation, and related runtime data.
  • Move subsystem state, event bus storage, and event reader cursors into World resources. Merge duplicate UI node indices into their runtime records.
  • Keep subsystem runtime tables private. Read individual results through audio_sink(entity), scroll_position(entity), interaction(entity), visibility readers, and character controller readers. Use scroll, focus, audio, and respawn operations for writes.
  • Make AudioSink an opaque playback control handle. Copy scroll positions on input/output and character contact arrays on output. Hide the internal Focused and LdtkRespawn marker types.
  • Use arrays for animation graph/glTF node indices and spawn drafts, typed integer coordinate and generation-aware physics-handle keys, and sets for membership. Replace the fixed enemy lookup map with exhaustive matching.
  • Remove unnecessary snapshots and redundant morph-weight writebacks; filter removals in place or collect stale keys. Defer Pixel Adventure entity deletions through Commands and retain snapshots where callbacks can modify subscriptions or animations.
  • Update public interfaces, ECS documentation, examples, and Unreleased notes.

API changes

  • Read physics velocity with resolved_velocity(entity).
  • Replace subsystem store accessors with per-entity readers and operations, including set_scroll_position, is_focused, is_ldtk_respawn_requested, kinematic_character_controller_output, and kinematic_character_controller_collisions(entity).
  • Pending LDtk level IDs return a Set.
  • Animation graph nodes use an array; allocate nodes through graph methods.

The low-level EntityTable type remains shared between engine packages. Making ComponentStore private and completing the remaining system-to-Query migration are follow-up work.

Validation

  • moon check --target all --deny-warn --warn-list +73: warning-free.
  • moon test --deny-warn --warn-list +73: 389 Wasm and 80 JS tests passed.
  • Regression coverage includes World isolation, entity slot/generation reuse, orphan cleanup, loop-audio cleanup, Chicle node release, observer subscription changes, animation fades, negative grid coordinates, and public snapshot/control access.
  • moon build --target js --release --deny-warn --warn-list +73: all three web examples built.
  • moon fmt --check, moon info, pinned codegen --check on 422 source files, and git diff --check passed. Generated subsystem interfaces contain no EntityTable.

Performance

Storage microbenchmarks ran in JS and native release builds with 8,192 entities and 20 samples. Sparse cases store one entry per 16 entities.

Operation Map EntityTable
JS dense read/write 289.36 µs 107.37 µs
Native dense read/write 255.83 µs 166.02 µs
JS sparse sequential scan 3.23 µs 3.96 µs
Native sparse lookup 126.80 µs 124.96 µs

These measure storage operations, not game FPS or public snapshot-reader overhead. JS sparse scanning regressed slightly and native sparse lookup was approximately unchanged.

Reproduce with moon bench selene-core/src/ecs/entity_table_bench_wbtest.mbt --target js --release or --target native.

@Milky2018
Milky2018 merged commit 11c5005 into main Nov 12, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant