Develop
Develop
Select your platform

ECS World

World owns the ECS runtime, Three.js scene + renderer, input, player rig, and is the gateway to XR. IWSDK extends the base elics World with WebXR‑specific facilities.

World as coordinator (mental model)

The World is the bridge between:
  • ECS data (entities/components)
  • 3D rendering (Three.js scene/camera/renderer)
  • XR interaction (WebXR session via WebGLRenderer.xr)
  • Content pipeline (asset manager, GLXF levels)
Components ←→ Systems ←→ World ←→ Three.js/XR
                       └→ Assets/Levels

Creating a World

import { World, SessionMode } from '@iwsdk/core';

const container = document.getElementById('scene') as HTMLDivElement;
const world = await World.create(container, {
  xr: { sessionMode: SessionMode.ImmersiveVR },
  features: { enableLocomotion: true, enableGrabbing: true },
  level: '/glxf/Composition.glxf',
});

Scene and level roots

  • getActiveRoot() returns the current level root or scene root if no level.
  • getPersistentRoot() always returns the global scene root.
Use these roots when you attach Three.js nodes outside ECS.

Creating Entities

const e = world.createEntity(); // bare entity (no object3D, no Transform)
const t = world.createTransformEntity(); // entity + object3D + Transform
createTransformEntity(object?, parentOrOptions?) accepts:
  • an existing Object3D
  • { parent?: Entity; persistent?: boolean } to choose the scene vs level parent

Systems and Components

world.registerComponent(MyComponent);
world.registerSystem(MySystem);
IWSDK registers core systems for you (Input, Audio, UI). Optional features like locomotion/grabbing are enabled via World.create(..., { features }).

XR helpers

  • launchXR(overrides?) – explicitly request a session using defaults set at creation; pass partial overrides per-launch.
  • exitXR() – end the active session.
  • visibilityState: Signal<'non-immersive'|'hidden'|'visible'|'visible-blurred'>
Offering sessions (navigator.xr.offerSession) is managed by World.create via the xr.offer option:
World.create(container, {
  xr: {
    sessionMode: SessionMode.ImmersiveVR,
    // 'none' | 'once' | 'always'
    offer: 'once',
  },
});
IWSDK vs elics: IWSDK adds XR helpers, scene ownership, and level wiring on top of elics’ ECS core.

Update ordering and render loop

Each frame:
update visibilityState → world.update(delta,time) → renderer.render(scene,camera)
Within world.update, systems run by ascending priority. Use negative priorities for input/physics that must precede visual updates.

Levels

await world.loadLevel('/glxf/Cave.glxf');
The LevelSystem listens for requests and handles the load. When complete, the world’s activeLevel signal updates.
Did you find this page helpful?
Thumbs up icon
Thumbs down icon
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2025 Meta