World
Reference documentation for the ECS World lifecycle, plugins, scenes, and resources.
Creating a World
Section titled “Creating a World”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 });World lifecycle
Section titled “World lifecycle”// Register components and pluginsworld.registerComponent(Transform, Velocity);world.addPlugin(MyPlugin);
// Mount starts the lifecycle: startup systems run, ticker startsawait world.mount();
// Pause/resumeawait world.pause();await world.continue();
// Unmountawait world.unmount(); // reloadable unloadawait world.unmount(false); // just stop (no unload)
// Permanently release world-owned stateawait world.dispose();Lifecycle methods
Section titled “Lifecycle methods”| Method | Description |
|---|---|
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>. |
Transition ordering and failures
Section titled “Transition ordering and failures”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.
Permanent disposal
Section titled “Permanent disposal”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.
Registering components and systems
Section titled “Registering components and systems”// 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 schedulesworld.registerSystem(Schedule.Update, [SystemA, SystemB]);
// Unregister a systemworld.unregisterSystem(MoveSystem);
// Register runtime-required componentsworld.registerRequiredComponents(Transform, Position, PreviousPosition);Scenes
Section titled “Scenes”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);| Member | Description |
|---|---|
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 / all | The 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.
What a Scene keeps to
Section titled “What a Scene keeps to”- 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
switchleaves the old level running, and its promise rejects withScene "…" 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 alsoScenePaused. - 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 thekeyits 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 afterresume()it goes on where it was. SceneUnloadedis triggered after a Scene is unloaded, with{ scene, source }: the Scene’s entity, gone by then, and the file it was loaded from.
IoC container and resources
Section titled “IoC container and resources”The World uses dependency injection for resource management.
Binding resources
Section titled “Binding resources”// Class binding (lazy singleton — instantiated on first .get())world.bindResource('myService', MyServiceClass);
// Factory bindingworld.bindResource('factory', (container) => new X(container.get('dep')));
// Instance binding (immediate)world.bindResource('config', { debug: true });Accessing resources
Section titled “Accessing resources”world.get('myService'); // from Worldresources.get('scheduler'); // from system update paramsType safety via module augmentation
Section titled “Type safety via module augmentation”declare module '@shell/ecs' { interface IocRegistry { myService: MyServiceClass; }}Built-in resources
Section titled “Built-in resources”| Key | Type | Description |
|---|---|---|
scheduler | Scheduler | Tick loop, system execution |
commands | Commands | Entity operations |
events | Events | Event system |
entities | Entities | Entity count, iteration |
components | Components | Component registry |
queries | QueryRegistry | Query creation |
archetypes | Archetypes | Archetype management |
scenes | SceneManager | The world’s Scenes |
ticker | Ticker | Frame loop |
lifecycle | LifeCycle | Mount/start/stop/unload |
mutationHooks | MutationHooks | Entity/component change callbacks |
Optional (manually bound, from @shell/serialization):
| Key | Type | Description |
|---|---|---|
serializer | SceneSerializer | Save/load/apply |
Utility
Section titled “Utility”| Method | Description |
|---|---|
world.toString() | Returns Shell ECS - version <VERSION> |
world.uid | Unique identifier for the world instance |