Skip to content

Unify ECS queries, typed system parameters, and deferred schedules - #79

Merged
Milky2018 merged 10 commits into
mainfrom
milky/world-query-access
Nov 12, 2026
Merged

Milky2018 merged 10 commits into
mainfrom
milky/world-query-access

Conversation

@Milky2018

@Milky2018 Milky2018 commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Component access now requires a World or an opaque World-bound query, and ordinary systems declare their dependencies through typed parameters. Structural changes are queued through Commands and applied only when a complete ECS Schedule finishes. App execution and custom loops share this boundary; raw flushes and immediate entity mutation remain private.

fn setup(commands : @ecs.Commands) -> Unit {
  ignore(commands.spawn((Enemy(), Health(100))))
}

fn remove_dead(
  enemies : @ecs.Query[(Enemy, Health)],
  commands : @ecs.Commands,
) -> Unit {
  for entity, (_, health) in enemies {
    if health.value <= 0 {
      commands.delete(entity)
    }
  }
}

app
  .add_system(Startup, setup)
  .add_system(Update, @ecs.args2(remove_dead))

// Custom loops also execute complete schedules.
let schedule = @ecs.Schedule().add_system(@ecs.args2(remove_dead))
try! schedule.run(world)
  • Make ComponentStore private and remove global component accessors, key data access, exposed query storage, store-selected constructors, and SpawnDraft::add_to. World point access reads or replaces existing component values without changing layouts.
  • Unify Query2–Query5 into Query[Row], using Single for one component and flat tuples for two through eight. Use lazy iter/iter2 and ordinary for loops; remove the per-shape for_each callbacks. Scoped batches expose ReadColumn/WriteColumn for declared columns only. All operations apply structural filters consistently.
  • Add SystemParam with preparation once per registration and World, followed by fetching on each execution. Support Query, Commands, required/optional Res, Unit, tuples, custom parameter structs, Time, State, and NextState. Cached resource handles observe replacements. Cache parameter state in the World without retaining the user's system callback.
  • Use args0 and args2–args8 to adapt ordinary functions for system and condition registration. Replace add_query_system/query_system with add_system. World is not a SystemParam; callbacks needing the whole World use add_exclusive_system or System::exclusive explicitly.
  • Make System and Condition opaque descriptions and Schedule the reusable execution owner. Chain preserves ordered groups with one final flush; merge combines registrations into one ordering group. Composition and repeated App runs preserve registration parameter state. Move system-set ordering to ecs and rename application stage labels to app.Stage.
  • Keep App, registrations, and runtime plans opaque. State lifecycle systems accept the same injected parameters and adapters; whole-World lifecycle callbacks have explicit exclusive registration methods. Transition execution and its registry stay in internal/state_runtime.
  • Queue spawn/spawn1/spawn_prepared/spawn_draft and delete/despawn/respawn through Commands. Prepare spawn plans and drafts through commands.prepare_spawn()/draft(). Public ECS types remain in ecs with private World storage; there are no access tokens or public privileged execution bridges.
  • Schedule.run selects the World, runs conditions and systems, applies one frozen FIFO command batch, completes entity lifecycle changes, and restores the previous active World. It rejects nested execution, including across Worlds and from command callbacks, and execution during query batch callbacks. Commands added during command application wait for the next synchronization point.
  • Preserve App synchronization after Startup, First/PreUpdate, each complete fixed step, ordinary updates/observer dispatch/Last, and state exits/entries. Add the approved synchronization after RenderCleanup; there is no intermediate flush between the four render stages.
  • Migrate ordinary gameplay and interaction systems in Cards, Pixel Adventure, and Survivors to injected queries, resources, Commands, and clocks. Exclusive example registration remains at game/scene initialization. Movement, animation, UI, firing, collision-event, and progression helpers receive their concrete dependencies rather than passing World through every layer.
  • Add Query::set(entity, row) to replace an existing matching row without changing component layouts or invalidating iterators. It rejects foreign, deleted, missing, and filtered-out rows; narrower queries support replacement of individual value components.
  • Combine concrete dependencies in private CardsGame and SurvivorsUi parameters. Their prepared fetchers cache query/resource handles and obtain the current resource on each execution, so state-driven restarts and repeated App runs do not retain the previous session. They contain no World field.
  • Remove unused delta arguments from 18 parameterless engine systems and register them through args0 directly. Preserve the clock dependency for touch long-press processing. Mesh/text extraction uses joined rows for required components; dynamic animation callbacks retain their existing complete-World execution and snapshot behavior.
  • Preserve importer dependency order, pending-parent handling, LDtk construction-local deduplication, canceled-scene cleanup, deferred Tiled map initialization, and completed-audio deletion. Update guides, tutorials, changelog, interfaces, and independent-consumer checks.

Validation:

  • moon check --target all --deny-warn --warn-list +73: warning-free.
  • moon test --deny-warn --warn-list +73: 437 Wasm and 83 JS tests passed.
  • ECS tests on explicit JS and native targets: 79 passed on each.
  • python3 -m unittest discover -s tests -p 'test_*.py': 30 passed. Independent consumers verify removed/private APIs, rejected internal imports and World injection, complete scheduling, deferred traversal, invalidated iterators, and isolated missing-resource/state failures.
  • Gameplay regressions cover Cards resource refresh across Worlds/restarts, actual Survivors firing and state restart, and deferred Pixel Adventure apple collection. Point-write tests cover joined rows, filters, World isolation, missing columns, stale generations, and iterator validity.
  • Regression coverage includes args adapters, per-registration/per-World preparation, repeated App runs, filtered parameter construction, resource replacement/optional availability, injected clocks and state, grouped synchronization, render cleanup, reentry, and frozen command batches.
  • JS release builds, formatting, generated-source consistency, interface generation, and diff checks passed. Generator output and the published codegen pin remain unchanged at 0.40.0-beta3.

Recorded query benchmarks and reproduction commands remain in ECS benchmarks. Earlier measurements compare ordinary loops with scoped columns; they do not measure the subsequent system-parameter and gameplay migrations. Lazy rows still construct tuples and dispatch iterators. Browser FPS and WebGPU rendering were not measured.

This intentionally breaks the old component-access and system/execution APIs. Mutable component objects retain MoonBit reference semantics. Typed injection declares dependencies but does not add borrow checking or parallel scheduling; batch and schedule execution remain guarded at runtime.

CI uses only the latest MoonBit toolchain on Linux, macOS, and Windows. Remove the pre-release compatibility job and its contributor guidance. The workflow YAML parses successfully and diff checks pass.

@Milky2018 Milky2018 changed the title Require World-owned component access throughout Selene Require World-owned component access and unify typed queries Nov 12, 2026
@Milky2018 Milky2018 changed the title Require World-owned component access and unify typed queries Enforce World-owned queries and deferred ECS structural changes Nov 12, 2026
@Milky2018 Milky2018 changed the title Enforce World-owned queries and deferred ECS structural changes Unify ECS queries, typed system parameters, and deferred schedules Nov 12, 2026
@Milky2018
Milky2018 merged commit ce22b74 into main Nov 12, 2026
3 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