Class: World
Defined in: packages/core/src/ecs/world.ts:97
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 HTMLDivElement;
const world = await World.create(container, {
xr: { sessionMode: SessionMode.ImmersiveVR },
features: { enableLocomotion: true, enableGrabbing: true },
level: '/glxf/Composition.glxf'
});Extends
World
Constructors
Constructor
new World():
World
Defined in: packages/core/src/ecs/world.ts:136
Returns
World
Overrides
ElicsWorld.constructor
Other
_resolveLevelLoad()
_resolveLevelLoad: () =>
void
Defined in: packages/core/src/ecs/world.ts:111
Returns
void
activeLevel
activeLevel:
Signal<Entity>
Defined in: packages/core/src/ecs/world.ts:103
activeLevelId
activeLevelId:
string='level:default'
Defined in: packages/core/src/ecs/world.ts:104
assetManager
assetManager: typeof
AssetManager
Defined in: packages/core/src/ecs/world.ts:100
camera
camera:
PerspectiveCamera
Defined in: packages/core/src/ecs/world.ts:105
cameraEntity
cameraEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:106
input
input:
InputManager
Defined in: packages/core/src/ecs/world.ts:98
mcpRuntime?
optionalmcpRuntime:MCPRuntime
Defined in: packages/core/src/ecs/world.ts:115
MCP runtime for framework-specific tools. Set automatically during World.create().
player
player:
XROrigin
Defined in: packages/core/src/ecs/world.ts:99
playerEntity
playerEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:125
Entity wrapping the XROrigin Group (persistent, survives level changes).
playerHeadEntity
playerHeadEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:127
Entity wrapping the player head Group (persistent).
playerSpaceEntities
playerSpaceEntities:
object
Defined in: packages/core/src/ecs/world.ts:129
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:107
requestedLevelUrl
requestedLevelUrl:
string
Defined in: packages/core/src/ecs/world.ts:110
scene
scene:
Scene
Defined in: packages/core/src/ecs/world.ts:101
sceneEntity
sceneEntity:
Entity
Defined in: packages/core/src/ecs/world.ts:102
session
session:
XRSession
Defined in: packages/core/src/ecs/world.ts:108
visibilityState
visibilityState:
Signal<VisibilityState>
Defined in: packages/core/src/ecs/world.ts:109
xrDefaults
xrDefaults:
XROptions
Defined in: packages/core/src/ecs/world.ts:113
Default XR options used when calling World.launchXR without overrides.
createEntity()
createEntity():
Entity
Defined in: packages/core/src/ecs/world.ts:194
Returns
Entity
Overrides
ElicsWorld.createEntity
createTransformEntity()
createTransformEntity(
object?,parentOrOptions?):Entity
Defined in: packages/core/src/ecs/world.ts:198
Parameters
object?
Object3D
parentOrOptions?
Entity | { parent?: Entity; persistent?: boolean; }
Returns
Entity
destroy()
destroy():
void
Defined in: packages/core/src/ecs/world.ts:443
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:259
Returns
void
getActiveRoot()
getActiveRoot():
Object3D
Defined in: packages/core/src/ecs/world.ts:476
Returns
Object3D
getPersistentRoot()
getPersistentRoot():
Object3D
Defined in: packages/core/src/ecs/world.ts:480
Returns
Object3D
launchXR()
launchXR(
xrOptions?):void
Defined in: packages/core/src/ecs/world.ts:247
Parameters
xrOptions?
Partial<XROptions>
Returns
void
loadLevel()
loadLevel(
url?):Promise<void>
Defined in: packages/core/src/ecs/world.ts:252
Request a level change; LevelSystem performs the work and resolves.
Parameters
url?
string
Returns
Promise<void>
registerComponent()
registerComponent(
component):this
Defined in: packages/core/src/ecs/world.ts:471
Parameters
component
Component
Returns
this
Overrides
ElicsWorld.registerComponent
update()
update(
delta,time):void
Defined in: packages/core/src/ecs/world.ts:467
Parameters
delta
number
time
number
Returns
void
Overrides
ElicsWorld.update
create()
staticcreate(container,options?):Promise<World>
Defined in: packages/core/src/ecs/world.ts:505
Initialize a new WebXR world with renderer, scene, default systems, and optional level.
Parameters
container
HTMLDivElement
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:289
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:299
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:274
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:411
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:323
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:360
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:388
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.