Class: World

Defined in: src/world/World.ts:26

Manages all interactions with the real-world environment perceived by the XR device. This class abstracts the complexity of various perception APIs (Depth, Planes, Meshes, etc.) and provides a simple, event-driven interface for developers to use this.world.depth.mesh, this.world.planes.

Extends

• Script

Constructors

Constructor

new World(): World

Defined in: node_modules/@types/three/src/core/Object3D.d.ts:98

This creates a new Object3D object.

Returns

World

Inherited from

Script.constructor

Properties

editorIcon

editorIcon: string = 'sensors'

Defined in: src/world/World.ts:34

---

faces?

optional faces: FaceRecognizer

Defined in: src/world/World.ts:80

The face landmark detection module instance. Null if not enabled.

---

humans?

optional humans: HumanRecognizer

Defined in: src/world/World.ts:75

The human recognition/pose module instance. Null if not enabled.

---

initializedPromise

readonly initializedPromise: Promise<void>

Defined in: src/world/World.ts:100

---

isXRScript

isXRScript: boolean = true

Defined in: src/core/Script.ts:54

Inherited from

Script.isXRScript

---

meshes?

optional meshes: MeshDetector

Defined in: src/world/World.ts:65

The mesh detection module instance. Null if not enabled.

---

objects?

optional objects: ObjectDetector

Defined in: src/world/World.ts:60

The object recognition module instance. Null if not enabled.

---

options

options: WorldOptions

Defined in: src/world/World.ts:39

Configuration options for all world-sensing features.

---

planes?

optional planes: PlaneDetector

Defined in: src/world/World.ts:55

The plane detection module instance. Null if not enabled. Not recommended for anchoring.

---

segmentation?

optional segmentation: Segmenter

Defined in: src/world/World.ts:85

The semantic segmentation module instance. Null if not enabled.

---

sounds?

optional sounds: SoundDetector

Defined in: src/world/World.ts:70

The sound detection module instance. Null if not enabled.

---

ux

ux: UX

Defined in: src/core/Script.ts:53

Inherited from

Script.ux

---

dependencies

static dependencies: object

Defined in: src/world/World.ts:27

camera

camera: typeof Camera = THREE.Camera

options

options: typeof WorldOptions = WorldOptions

timer

timer: typeof Timer = THREE.Timer

waitFrame

waitFrame: typeof WaitFrame = WaitFrame

Methods

anchorObjectAtReticle()

anchorObjectAtReticle(_object, _reticle): void

Defined in: src/world/World.ts:180

Places an object at the reticle.

Parameters

_object

Object3D

_reticle

Object3D

Returns

void

---

dispose()

dispose(): void

Defined in: src/core/Script.ts:196

Called when the script is removed from the scene. Opposite of init.

Returns

void

Inherited from

Script.dispose

---

init()

init(__namedParameters): Promise<void>

Defined in: src/world/World.ts:108

Initializes the world-sensing modules based on the provided configuration. This method is called automatically by the XRCore.

Parameters

__namedParameters

camera

Camera

options

WorldOptions

timer

Timer

waitFrame

WaitFrame

Returns

Promise<void>

Overrides

Script.init

---

initPhysics()

initPhysics(_physics): void | Promise<void>

Defined in: src/core/Script.ts:73

Enables depth-aware interactions with physics. See /demos/ballpit

Parameters

_physics

Physics

Returns

void | Promise<void>

Inherited from

Script.initPhysics

---

onHoverEnter()

onHoverEnter(_controller): boolean | void

Defined in: src/core/Script.ts:155

Called when the controller starts hovering over this object with reticle.

Parameters

_controller

Object3D

An XR controller.

Returns

boolean | void

Whether the event was handled. If true, the event will not bubble up.

Inherited from

Script.onHoverEnter

---

onHoverExit()

onHoverExit(_controller): boolean | void

Defined in: src/core/Script.ts:161

Called when the controller hovers over this object with reticle.

Parameters

_controller

Object3D

An XR controller.

Returns

boolean | void

Whether the event was handled. If true, the event will not bubble up.

Inherited from

Script.onHoverExit

---

onHovering()

onHovering(_controller): boolean | void

Defined in: src/core/Script.ts:167

Called when the controller hovers over this object with reticle.

Parameters

_controller

Object3D

An XR controller.

Returns

boolean | void

Whether the event was handled. If true, the event will not bubble up.

Inherited from

Script.onHovering

---

onKeyDown()

onKeyDown(_event): void

Defined in: src/core/Script.ts:110

Called on keyboard keypress.

Parameters

_event

KeyEvent

Event containing .code to read the keyboard key.

Returns

void

Inherited from

Script.onKeyDown

---

onKeyUp()

onKeyUp(_event): void

Defined in: src/core/Script.ts:111

Parameters

_event

KeyEvent

Returns

void

Inherited from

Script.onKeyUp

---

onObjectGrabbing()

onObjectGrabbing(_event): void

Defined in: src/core/Script.ts:187

Called every frame a hand is grabbing this object.

Parameters

_event

ObjectGrabEvent

Returns

void

Inherited from

Script.onObjectGrabbing

---

onObjectGrabEnd()

onObjectGrabEnd(_event): void

Defined in: src/core/Script.ts:191

Called when a hand stops grabbing this object.

Parameters

_event

ObjectGrabEvent

Returns

void

Inherited from

Script.onObjectGrabEnd

---

onObjectGrabStart()

onObjectGrabStart(_event): void

Defined in: src/core/Script.ts:183

Called when a hand starts grabbing this object (touching + pinching).

Parameters

_event

ObjectGrabEvent

Returns

void

Inherited from

Script.onObjectGrabStart

---

onObjectSelectEnd()

onObjectSelectEnd(_event): boolean | void

Defined in: src/core/Script.ts:149

Called when the controller stops selecting this object the script represents, e.g. View, ModelView.

Parameters

_event

SelectEvent

event.target holds its controller.

Returns

boolean | void

Whether the event was handled. If true, the event will not bubble up.

Inherited from

Script.onObjectSelectEnd

---

onObjectSelectStart()

onObjectSelectStart(_event): boolean | void

Defined in: src/core/Script.ts:142

Called when the controller starts selecting this object the script represents, e.g. View, ModelView.

Parameters

_event

SelectEvent

event.target holds its controller.

Returns

boolean | void

Whether the event was handled. If true, the event will not bubble up.

Inherited from

Script.onObjectSelectStart

---

onObjectTouchEnd()

onObjectTouchEnd(_event): void

Defined in: src/core/Script.ts:179

Called when a hand's index finger stops touching this object.

Parameters

_event

ObjectTouchEvent

Returns

void

Inherited from

Script.onObjectTouchEnd

---

onObjectTouching()

onObjectTouching(_event): void

Defined in: src/core/Script.ts:175

Called every frame that a hand's index finger is touching this object.

Parameters

_event

ObjectTouchEvent

Returns

void

Inherited from

Script.onObjectTouching

---

onObjectTouchStart()

onObjectTouchStart(_event): void

Defined in: src/core/Script.ts:171

Called when a hand's index finger starts touching this object.

Parameters

_event

ObjectTouchEvent

Returns

void

Inherited from

Script.onObjectTouchStart

---

onSelect()

onSelect(_event): void

Defined in: src/core/Script.ts:99

Called whenever pinch / mouse click successfully completes, globally.

Parameters

_event

SelectEvent

event.target holds its controller.

Returns

void

Inherited from

Script.onSelect

---

onSelectEnd()

onSelectEnd(_event): void

Defined in: src/core/Script.ts:93

Called whenever pinch / mouse click discontinues, globally.

Parameters

_event

SelectEvent

event.target holds its controller

Returns

void

Inherited from

Script.onSelectEnd

---

onSelecting()

onSelecting(_event): void

Defined in: src/core/Script.ts:104

Called whenever pinch / mouse click is happening, globally.

Parameters

_event

SelectEvent

Returns

void

Inherited from

Script.onSelecting

---

onSelectStart()

onSelectStart(_event): void

Defined in: src/core/Script.ts:87

Called whenever pinch / mouse click starts, globally.

Parameters

_event

SelectEvent

event.target holds its controller

Returns

void

Inherited from

Script.onSelectStart

---

onSimulatorStarted()

onSimulatorStarted(): void

Defined in: src/core/Script.ts:79

Returns

void

Inherited from

Script.onSimulatorStarted

---

onSqueeze()

onSqueeze(_event): void

Defined in: src/core/Script.ts:133

Called whenever gamepad trigger successfully completes, globally.

Parameters

_event

SelectEvent

event.target holds its controller.

Returns

void

Inherited from

Script.onSqueeze

---

onSqueezeEnd()

onSqueezeEnd(_event): void

Defined in: src/core/Script.ts:122

Called whenever gamepad trigger stops, globally.

Parameters

_event

SelectEvent

event.target holds its controller.

Returns

void

Inherited from

Script.onSqueezeEnd

---

onSqueezeStart()

onSqueezeStart(_event): void

Defined in: src/core/Script.ts:117

Called whenever gamepad trigger starts, globally.

Parameters

_event

SelectEvent

event.target holds its controller.

Returns

void

Inherited from

Script.onSqueezeStart

---

onSqueezing()

onSqueezing(_event): void

Defined in: src/core/Script.ts:127

Called whenever gamepad is being triggered, globally.

Parameters

_event

SelectEvent

Returns

void

Inherited from

Script.onSqueezing

---

onXRSessionEnded()

onXRSessionEnded(): void

Defined in: src/core/Script.ts:77

Returns

void

Inherited from

Script.onXRSessionEnded

---

onXRSessionStarted()

onXRSessionStarted(_session?): void

Defined in: src/core/Script.ts:76

Parameters

_session?

XRSession

Returns

void

Inherited from

Script.onXRSessionStarted

---

physicsStep()

physicsStep(): void

Defined in: src/core/Script.ts:74

Returns

void

Inherited from

Script.physicsStep

---

placeOnHorizontalSurface()

placeOnHorizontalSurface(objectToPlace, timeout, gridSteps): Promise<boolean>

Defined in: src/world/World.ts:259

Places an object onto a suitable horizontal plane in the environment. It prioritizes planes in front of the user, prefers tables/elevated surfaces over floors, and ensures the object does not intersect other existing objects or other planes in the scene. If placement fails in the current frame, it continues retrying frame-by-frame until the timeout is reached.

Parameters

objectToPlace

Object3D

The Three.js Object3D to place.

timeout

DurationLike = ...

Optional timeout duration as a Temporal.Duration or Temporal.DurationLike object (defaults to 500ms).

gridSteps

number = 9

Optional number of steps along each axis for grid sampling candidate positions (defaults to 5).

Returns

Promise<boolean>

A promise resolving to true if successfully placed, false otherwise.

---

placeOnSurface()

placeOnSurface(objectToPlace, controller): boolean

Defined in: src/world/World.ts:220

Performs a raycast from a controller against detected real-world surfaces (currently planes) and places a 3D object at the intersection point, oriented to face the user.

We recommend using /templates/3_depth/ to anchor objects based on depth mesh for mixed reality experience for accuracy. This function is design for demonstration purposes.

Parameters

objectToPlace

Object3D

The object to position in the world.

controller

Object3D

The controller to use for raycasting.

Returns

boolean

True if the object was successfully placed, false otherwise.

---

showDebugVisualizations()

showDebugVisualizations(visible): void

Defined in: src/world/World.ts:291

Toggles the visibility of all debug visualizations for world features.

Parameters

visible

boolean = true

Whether the visualizations should be visible.

Returns

void

---

update()

update(_timestamp, frame?): void

Defined in: src/world/World.ts:192

Updates all active world-sensing modules with the latest XRFrame data. This method is called automatically by the XRCore on each frame.

Parameters

_timestamp

number

The timestamp for the current frame.

frame?

XRFrame

The current XRFrame, containing environmental data.

Returns

void

Overrides

Script.update