Class: World
Defined in: packages/core/src/ecs/world.ts:102
World is the root ECS container, Three.js scene/renderer owner, and XR session gateway.
Remarks
- Construct a world with World.create (recommended) which wires the renderer, scene, default systems (Input, UI, Audio, Level) and starts the render loop.
- The world exposes convenience handles like input, player (the persistent player/XR origin), and World.assetManager.
- Feature systems (Grabbing, Locomotion) are opt‑in via WorldOptions.features.
Example
import { World, SessionMode } from '@iwsdk/core';
const container = document.getElementById('scene-container') as HTMLElement;
const world = await World.create(container, {
xr: { sessionMode: SessionMode.ImmersiveVR },
features: { enableLocomotion: true, enableGrabbing: true },
level: '/scenes/main.iwsdk.scene.json'
});Extends
World
Constructors
Constructor
new World():
World
Defined in: packages/core/src/ecs/world.ts:155
Returns
World
Overrides
ElicsWorld.constructor
Other
_rejectLevelLoad()
_rejectLevelLoad: (
reason) =>void
Defined in: packages/core/src/ecs/world.ts:126
Parameters
reason
unknown
Returns
void
_resolveLevelLoad()
_resolveLevelLoad: () =>
void
Defined in: packages/core/src/ecs/world.ts:125
Returns
void
activeLevel
activeLevel:
Signal<Entity>
Defined in: packages/core/src/ecs/world.ts:112
activeLevelId
activeLevelId:
string='level:default'
Defined in: packages/core/src/ecs/world.ts:113
assetManager
assetManager: typeof
AssetManager
Defined in: packages/core/src/ecs/world.ts:105
assets
assets:
RenderableAssetRegistry
Defined in: packages/core/src/ecs/world.ts:107
Renderable assets registered by the application manifest.
camera
camera:
PerspectiveCamera
Defined in: packages/core/src/ecs/world.ts:114
cameraEntity
cameraEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:115
componentCatalog
componentCatalog:
SceneComponentCatalog
Defined in: packages/core/src/ecs/world.ts:109
Component definitions shared by scene validation and editor tooling.
input
input:
InputManager
Defined in: packages/core/src/ecs/world.ts:103
mcpRuntime?
optionalmcpRuntime:MCPRuntime
Defined in: packages/core/src/ecs/world.ts:130
MCP runtime for framework-specific tools. Set automatically during World.create().
player
player:
XROrigin
Defined in: packages/core/src/ecs/world.ts:104
playerEntity
playerEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:144
Entity wrapping the XROrigin Group (persistent, survives level changes).
playerHeadEntity
playerHeadEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:146
Entity wrapping the player head Group (persistent).
playerSpaceEntities
playerSpaceEntities:
object
Defined in: packages/core/src/ecs/world.ts:148
Entities for all XR input space Groups under the player rig (all persistent).
gripSpaces
gripSpaces:
object
gripSpaces.left
left:
Entity
gripSpaces.right
right:
Entity
head
head:
Entity
indexTipSpaces
indexTipSpaces:
object
indexTipSpaces.left
left:
Entity
indexTipSpaces.right
right:
Entity
raySpaces
raySpaces:
object
raySpaces.left
left:
Entity
raySpaces.right
right:
Entity
renderer
renderer:
WebGLRenderer
Defined in: packages/core/src/ecs/world.ts:116
requestedLevelDocument
requestedLevelDocument:
SceneDocument
Defined in: packages/core/src/ecs/world.ts:124
requestedLevelUrl
requestedLevelUrl:
string
Defined in: packages/core/src/ecs/world.ts:123
scene
scene:
Scene
Defined in: packages/core/src/ecs/world.ts:110
sceneEntity
sceneEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:111
session
session:
XRSession
Defined in: packages/core/src/ecs/world.ts:117
visibilityState
visibilityState:
Signal<VisibilityState>
Defined in: packages/core/src/ecs/world.ts:118
xrDefaults
xrDefaults:
XROptions
Defined in: packages/core/src/ecs/world.ts:128
Default XR options used when calling World.launchXR without overrides.
xrEnabled
xrEnabled:
boolean=true
Defined in: packages/core/src/ecs/world.ts:120
Whether this world was created with XR support enabled.
createEntity()
createEntity():
Entity
Defined in: packages/core/src/ecs/world.ts:218
Returns
Entity
Overrides
ElicsWorld.createEntity
createTransformEntity()
createTransformEntity(
object?,parentOrOptions?):Entity
Defined in: packages/core/src/ecs/world.ts:240
Parameters
object?
Object3D
parentOrOptions?
Entity | { parent?: Entity; persistent?: boolean; }
Returns
Entity
destroy()
destroy():
void
Defined in: packages/core/src/ecs/world.ts:570
Tear down the world: destroy all registered systems (running their cleanupFuncs), then run world-level teardown callbacks (stop the render loop, remove the window resize listener). After calling this the world instance should be discarded.
Returns
void
Remarks
Not invoked during normal single-world app usage (where the world lives for the page lifetime); provided so tests, hot-reload, and multi-world hosts can release the render loop, listeners, and per-system subscriptions instead of leaking them. Individual failures are caught so one bad teardown does not block the rest.
exitXR()
exitXR():
void
Defined in: packages/core/src/ecs/world.ts:376
Returns
void
getActiveRoot()
getActiveRoot():
Object3D
Defined in: packages/core/src/ecs/world.ts:603
Returns
Object3D
getPersistentRoot()
getPersistentRoot():
Object3D
Defined in: packages/core/src/ecs/world.ts:607
Returns
Object3D
getSceneEntity()
getSceneEntity(
nodeId):Entity
Defined in: packages/core/src/ecs/world.ts:332
Find the ECS entity that owns an authored scene node.
Parameters
nodeId
string
Returns
Entity
getSceneObject()
getSceneObject<
T>(nodeId):T
Defined in: packages/core/src/ecs/world.ts:297
Find an authored scene object by its stable scene node id.
Type Parameters
T
T extends Object3D<Object3DEventMap> = Object3D<Object3DEventMap>
Parameters
nodeId
string
Returns
T
launchXR()
launchXR(
xrOptions?):void
Defined in: packages/core/src/ecs/world.ts:350
Parameters
xrOptions?
Partial<XROptions>
Returns
void
loadLevel()
loadLevel(
url?):Promise<void>
Defined in: packages/core/src/ecs/world.ts:355
Request a native scene JSON level change; LevelSystem performs the work and resolves.
Parameters
url?
string
Returns
Promise<void>
loadSceneDocument()
loadSceneDocument(
document):Promise<void>
Defined in: packages/core/src/ecs/world.ts:366
Request an in-memory native scene document level load; LevelSystem performs the work and resolves.
Parameters
document
SceneDocument
Returns
Promise<void>
registerComponent()
registerComponent(
component):this
Defined in: packages/core/src/ecs/world.ts:598
Parameters
component
Component
Returns
this
Overrides
ElicsWorld.registerComponent
requireSceneEntity()
requireSceneEntity(
nodeId):Entity
Defined in: packages/core/src/ecs/world.ts:340
Find the ECS entity for an authored scene node or throw.
Parameters
nodeId
string
Returns
Entity
requireSceneObject()
requireSceneObject<
T>(nodeId):T
Defined in: packages/core/src/ecs/world.ts:321
Find an authored scene object or throw a node-oriented lookup error.
Type Parameters
T
T extends Object3D<Object3DEventMap> = Object3D<Object3DEventMap>
Parameters
nodeId
string
Returns
T
update()
update(
delta,time):void
Defined in: packages/core/src/ecs/world.ts:594
Parameters
delta
number
time
number
Returns
void
Overrides
ElicsWorld.update
create()
staticcreate(container,options?):Promise<World>
Defined in: packages/core/src/ecs/world.ts:632
Initialize a new WebXR world with renderer, scene, default systems, and optional level.
Parameters
container
HTMLElement
HTML container to which the renderer canvas will be appended.
options?
Runtime configuration, see WorldOptions.
Returns
Promise<World>
A promise that resolves to the initialized World.
Remarks
- This call enables the Input, UI and Audio systems by default.
- Use WorldOptions.features to enable Locomotion or Grabbing.
- If WorldOptions.level is provided, the LevelSystem will load it after assets are preloaded.
See
/getting-started/01-hello-xr
XR Runtime
xrFrame
Get Signature
get xrFrame():
XRFrame
Defined in: packages/core/src/ecs/world.ts:416
The current XRFrame for this animation-loop tick, or null outside XR. Use it for raw WebXR access such as frame.getViewerPose(...), frame.getHitTestResults(...), or frame.getDepthInformation(...).
Remarks
Read this synchronously inside an World.onXRFrame callback or a System update() — the frame object is only valid for the current tick and must not be retained across frames.
Returns
XRFrame
xrReferenceSpace
Get Signature
get xrReferenceSpace():
XRReferenceSpace
Defined in: packages/core/src/ecs/world.ts:426
The active XRReferenceSpace that IWSDK resolved for the session, or null outside XR. Pass it to XRHitTestResult.getPose(space) or XRFrame.getViewerPose(space) to obtain poses in the world's tracking space.
Returns
XRReferenceSpace
xrSession
Get Signature
get xrSession():
XRSession
Defined in: packages/core/src/ecs/world.ts:401
The active XRSession, or undefined outside XR. Alias of World.session, exposed for discoverability alongside World.xrFrame and World.xrReferenceSpace.
Remarks
Enable WebXR features your app needs (e.g. hit-test, depth sensing) via World.create(container, { xr: { features: { hitTest: true, depthSensing: true } } }). Once granted, they appear in world.xrSession.enabledFeatures.
Returns
XRSession
getHitTestResults()
getHitTestResults(
source):XRHitTestResult[]
Defined in: packages/core/src/ecs/world.ts:538
Read the hit-test results for a source from the current XRFrame. Returns an empty array when there is no active frame.
Parameters
source
XRHitTestSource
Returns
XRHitTestResult[]
onXRFrame()
onXRFrame(
callback): () =>void
Defined in: packages/core/src/ecs/world.ts:450
Register a callback that runs once per render-loop tick with the live XRFrame, without having to author a System. Useful for per-pixel world alignment, hit-test queries, depth sampling, and object-anchored overlays.
Parameters
callback
Invoked with (frame, delta, time) while an XR session is active.
Returns
An unsubscribe function; call it to stop receiving frames.
():
void
Returns
void
Example
const source = await world.requestHitTestSource({ space: world.xrReferenceSpace! });
const stop = world.onXRFrame((frame) => {
if (!source) return;
const [hit] = world.getHitTestResults(source);
const pose = hit?.getPose(world.xrReferenceSpace!);
// place a world-locked label at pose.transform.position ...
});requestHitTestSource()
requestHitTestSource(
options):Promise<XRHitTestSource>
Defined in: packages/core/src/ecs/world.ts:487
Request an XRHitTestSource on the active session. Requires the hit-test feature (enable via World.create(container, { xr: { features: { hitTest: true } } })).
Parameters
options
XRHitTestOptionsInit
Returns
Promise<XRHitTestSource>
The hit-test source, or undefined if there is no active session or the request is unavailable/unsupported. The underlying XRSession.requestHitTestSource rejects when the hit-test feature was not granted; that rejection is caught and surfaced as undefined (logged as a warning) so callers can await without their own try/catch.
requestHitTestSourceForTransientInput()
requestHitTestSourceForTransientInput(
options):Promise<XRTransientInputHitTestSource>
Defined in: packages/core/src/ecs/world.ts:515
Request an XRTransientInputHitTestSource (e.g. for screen taps or transient controllers). Requires the hit-test feature.
Parameters
options
XRTransientInputHitTestOptionsInit
Returns
Promise<XRTransientInputHitTestSource>
The transient hit-test source, or undefined if unavailable. As with World.requestHitTestSource, a rejection from the underlying WebXR call (e.g. feature not granted) is caught and surfaced as undefined.