Skip to content

World

Reference documentation for the ECS World lifecycle, plugins, scenes, and resources.

import { World } from '@shell/ecs';
const world = new World();

Set the world’s immutable fixed timestep at construction. The value is in milliseconds and defaults to 1000 / 60:

const world = new World({ fixedTimestepMs: 1000 / 120 });
// Register components and plugins
world.registerComponent(Transform, Velocity);
world.addPlugin(MyPlugin);
// Mount starts the lifecycle: startup systems run, ticker starts
await world.mount();
// Pause/resume
await world.pause();
await world.continue();
// Unmount
await world.unmount(); // reloadable unload
await world.unmount(false); // just stop (no unload)
// Permanently release world-owned state
await world.dispose();
MethodDescription
mount()Prepare systems, start ticker, and run lifecycle. Returns Promise<void>.
pause()Sleep the lifecycle. Returns Promise<void>.
continue()Resume the lifecycle. Returns Promise<void>.
unmount(reset?)true (default) = full unload; false = just stop. Returns Promise<void>.
isMounted()Returns whether the world is currently mounted.
clear()Remove all entities, destroy systems and observers, and reset prepared state. Returns Promise<void>.
dispose()Permanently unload and release world-owned registrations and resources. Returns Promise<void>.

Lifecycle calls execute in invocation order and cannot interleave phases. Adjacent identical transitions share one promise while in flight. Lifecycle state advances only after every callback for the current phase succeeds, so a failed startup leaves the world unmounted and a failed unload retains the previous successful step. Both operations can be retried. Callback side effects that completed before a failure are not rolled back.

unmount() is reloadable; dispose() is permanent. Disposal unregisters the world’s systems and observers, removes scheduler hooks and owner activation, releases lifecycle subscriptions, disposes its entity registry, and disposes the resources it owns. Repeated disposal is safe, but a disposed world cannot be mounted or configured again.

// Pre-register components (useful for editors or deserialization)
world.registerComponent(Transform, Velocity);
// Use each system's builder schedule (or Update by default)
world.registerSystem(MoveSystem);
world.registerSystem(SystemA, SystemB);
// Explicit schedules override builder schedules
world.registerSystem(Schedule.Update, [SystemA, SystemB]);
// Unregister a system
world.unregisterSystem(MoveSystem);
// Register runtime-required components
world.registerRequiredComponents(Transform, Position, PreviousPosition);

A level, a shop or a menu is a Scene: an entity of the one world that owns the entities loaded from its scene file and those spawned while it is the active Scene. Unloading it despawns what it owns. Queries stay world-wide; the inScene(scene) query filter keeps one to a Scene’s entities. A game reads scene files through a SceneLoader of @shell/serialization.

import { SceneLoader } from '@shell/serialization';
new SceneLoader(world);
const scenes = world.get('scenes');
await scenes.load('/assets/scenes/shared.scene.json', { persistent: true });
const level = await scenes.switch('/assets/scenes/level-1.scene.json');
// A shop over the level, which stands still behind it and is still drawn. The level is paused
// first: until then its systems run with the shop the active Scene, and spawn into it.
scenes.pause(level);
const shop = await scenes.load('/assets/scenes/shop.scene.json');
// …
scenes.unload(shop);
scenes.resume(level);
MemberDescription
scenes.load(source, options?)Reads the file and adds its entities as a new Scene. persistent keeps it across switches.
scenes.switch(source, options?)Reads the file, then between two ticks unloads every Scene that is not persistent and adds it.
scenes.unload(scene)Despawns what the Scene owns, then the Scene, and triggers SceneUnloaded.
scenes.pause(scene) / resume()Stops and restarts the Scene’s systems and simulation; it is still drawn.
scenes.move(entity, scene)Moves a root, with its children, to another Scene.
scenes.within(scene, spawn)The entities spawn makes go to the named Scene.
scenes.active / shared / allThe Scene spawns go to, the first persistent one, and every Scene in load order.
scenes.of(entity)The Scene an entity belongs to, if any.
scenes.keyOf(scene)What a system’s .scene(key) names it by: its file’s key, or its file name.

Both load and switch take the file’s contents as data instead of reading it. A startup system registered as .forEachScene() runs again when each Scene’s load ends, before the next frame; one with .scene(keys) only when a Scene of its keys has loaded.

  • Scenes loaded together never share a UID. Loading always spawns new entities. load() refuses a file with a UID that an entity of the world already has, before anything of it is spawned. switch() leaves out the Scenes it unloads: two levels may use the same UID, and a level switched for itself (a restart) is loaded anew, but a level and the shared scene may not.
  • A refused file changes nothing. A version too new, a field of the wrong type, or a reference that would not resolve once the old level is gone is found before anything is unloaded. A refused switch leaves the old level running, and its promise rejects with Scene "…" cannot be loaded: ….
  • A level may refer to the shared scene’s entities by UID, in an entity field. The reference is resolved as the level loads, so load the shared scene first.
  • Ownership follows the parent. An entity parented under another Scene’s entity moves to that Scene with its children. So scenes.move() moves a root: a child whose parent is in another Scene is refused, since the parent would take it along. Take it from its parent first (removeParent()).
  • What a Scene owns has InScene { scene }, and in a paused Scene also ScenePaused.
  • A paused Scene stops the systems that belong to it, as in Godot and Bevy. A system belongs to Scenes by their keys, Define.system().scene('level'), and runs only while a Scene of one of them is loaded and not paused; an observer with .scene() hears its events while one is loaded, paused or not. A Scene’s key is the key its file gives, which several files may share, or else its file name.
  • A system with no .scene() runs always and sees every entity, a paused Scene’s too: a count, a “none left” or a spawner that keeps a number of things sees the paused ones. The engine’s physics, animation and spatial systems hold a paused Scene’s entities themselves, and its Controls take no press. It stays on screen as it was, and after resume() it goes on where it was.
  • SceneUnloaded is triggered after a Scene is unloaded, with { scene, source }: the Scene’s entity, gone by then, and the file it was loaded from.

The World uses dependency injection for resource management.

// Class binding (lazy singleton — instantiated on first .get())
world.bindResource('myService', MyServiceClass);
// Factory binding
world.bindResource('factory', (container) => new X(container.get('dep')));
// Instance binding (immediate)
world.bindResource('config', { debug: true });
world.get('myService'); // from World
resources.get('scheduler'); // from system update params
declare module '@shell/ecs' {
interface IocRegistry {
myService: MyServiceClass;
}
}
KeyTypeDescription
schedulerSchedulerTick loop, system execution
commandsCommandsEntity operations
eventsEventsEvent system
entitiesEntitiesEntity count, iteration
componentsComponentsComponent registry
queriesQueryRegistryQuery creation
archetypesArchetypesArchetype management
scenesSceneManagerThe world’s Scenes
tickerTickerFrame loop
lifecycleLifeCycleMount/start/stop/unload
mutationHooksMutationHooksEntity/component change callbacks

Optional (manually bound, from @shell/serialization):

KeyTypeDescription
serializerSceneSerializerSave/load/apply
MethodDescription
world.toString()Returns Shell ECS - version <VERSION>
world.uidUnique identifier for the world instance