Class: World
Defined in: src/world/World.ts:27
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.planes and this.world.meshes.
Extends
Constructors
Constructor
new World():
World
Defined in: node_modules/@types/three/src/core/Object3D.d.ts:105
This creates a new Object3D object.
Returns
World
Inherited from
Properties
anchors?
optionalanchors:AnchorManager
Defined in: src/world/World.ts:57
editorIcon
editorIcon:
string='sensors'
Defined in: src/world/World.ts:35
faces?
optionalfaces:FaceRecognizer
Defined in: src/world/World.ts:82
The face landmark detection module instance. Null if not enabled.
humans?
optionalhumans:HumanRecognizer
Defined in: src/world/World.ts:77
The human recognition/pose module instance. Null if not enabled.
initializedPromise
readonlyinitializedPromise:Promise<void>
Defined in: src/world/World.ts:102
isXRScript
isXRScript:
boolean=true
Defined in: src/core/Script.ts:99
Inherited from
meshes?
optionalmeshes:MeshDetector
Defined in: src/world/World.ts:67
The mesh detection module instance. Null if not enabled.
objects?
optionalobjects:ObjectDetector
Defined in: src/world/World.ts:62
The object recognition module instance. Null if not enabled.
options
options:
WorldOptions
Defined in: src/world/World.ts:40
Configuration options for all world-sensing features.
planes?
optionalplanes:PlaneDetector
Defined in: src/world/World.ts:56
The plane detection module instance. Null if not enabled. Not recommended for anchoring.
segmentation?
optionalsegmentation:Segmenter
Defined in: src/world/World.ts:87
The semantic segmentation module instance. Null if not enabled.
sounds?
optionalsounds:SoundDetector
Defined in: src/world/World.ts:72
The sound detection module instance. Null if not enabled.
xb?
optionalxb:XBObjectOptions
Defined in: src/interaction/InteractionTypes.ts:34
Inherited from
dependencies
staticdependencies:object
Defined in: src/world/World.ts:28
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:189
Unimplemented placeholder. Does not place or anchor the object.
Parameters
_object
_reticle
Returns
void
Throws
Always throws an error because this method is not implemented.
dispose()
dispose():
void
Defined in: src/world/World.ts:303
Called when the script is removed from the scene. Opposite of init.
Returns
void
Overrides
init()
init(
__namedParameters):Promise<void>
Defined in: src/world/World.ts:110
Initializes the world-sensing modules based on the provided configuration. This method is called automatically by the XRCore.
Parameters
__namedParameters
camera
options
timer
waitFrame
Returns
Promise<void>
Overrides
initPhysics()
initPhysics(
_physics):void|Promise<void>
Defined in: src/core/Script.ts:118
Enables depth-aware interactions with physics. See /samples/advanced/ballpit
Parameters
_physics
Returns
void | Promise<void>
Inherited from
onHoverEnter()
onHoverEnter(
_event):void
Defined in: src/core/Script.ts:215
Called when a source starts hovering over this object.
Parameters
_event
The hover source, target, surface, and intersection.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onHoverExit()
onHoverExit(
_event):void
Defined in: src/core/Script.ts:221
Called when a source stops hovering over this object.
Parameters
_event
The hover source, target, surface, and intersection.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onHovering()
onHovering(
_event):void
Defined in: src/core/Script.ts:227
Called while a source hovers over this object.
Parameters
_event
The hover source, target, surface, and intersection.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onKeyDown()
onKeyDown(
_event):void
Defined in: src/core/Script.ts:158
Called on keyboard keypress.
Parameters
_event
Event containing .code to read the keyboard key.
Returns
void
Inherited from
onKeyUp()
onKeyUp(
_event):void
Defined in: src/core/Script.ts:159
Parameters
_event
Returns
void
Inherited from
onLongSelect()
onLongSelect(
_event):void
Defined in: src/core/Script.ts:152
Called when an object selection reaches the long-select delay.
Parameters
_event
Returns
void
Inherited from
onObjectGrabbing()
onObjectGrabbing(
_event):void
Defined in: src/core/Script.ts:253
Called every frame a hand is grabbing this object.
Parameters
_event
Returns
void
Inherited from
onObjectGrabEnd()
onObjectGrabEnd(
_event):void
Defined in: src/core/Script.ts:258
Called when a hand stops grabbing this object. This ends built-in direct-touch manipulation without ending contact.
Parameters
_event
Returns
void
Inherited from
onObjectGrabStart()
onObjectGrabStart(
_event):void
Defined in: src/core/Script.ts:249
Called when a hand starts grabbing this object (touching + pinching). A grab starts built-in direct-touch manipulation when enabled.
Parameters
_event
Returns
void
Inherited from
onObjectLongSelect()
onObjectLongSelect(
_event):void
Defined in: src/core/Script.ts:203
Called once when a captured selection is held for the long-select delay. Manipulation captures do not emit this callback.
Parameters
_event
The controller and completed hold duration.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onObjectManipulate()
onObjectManipulate(
_event):void
Defined in: src/core/Script.ts:209
Called for each phase of an automatic object manipulation. Call
event.stopPropagation() to stop bubbling. Calling preventDefault()
on a start event suppresses the automatic action.
Parameters
_event
Returns
void
Inherited from
onObjectSelectEnd()
onObjectSelectEnd(
_event):void
Defined in: src/core/Script.ts:196
Called when a source stops selecting the object this Script represents.
Parameters
_event
The completed state and end reason.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onObjectSelectStart()
onObjectSelectStart(
_event):void
Defined in: src/core/Script.ts:190
Called when a source starts selecting the object this Script represents.
Parameters
_event
event.target is the logical object and
event.source.controller identifies the controller.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onObjectTouchEnd()
onObjectTouchEnd(
_event):void
Defined in: src/core/Script.ts:244
Called when a hand's index finger stops touching this object. This ends the default selection lifecycle after the touch callback.
Parameters
_event
Returns
void
Inherited from
onObjectTouching()
onObjectTouching(
_event):void
Defined in: src/core/Script.ts:239
Called every frame that a hand's index finger is touching this object. The object remains selected during these frames unless touch selection was prevented when contact started.
Parameters
_event
Returns
void
Inherited from
onObjectTouchStart()
onObjectTouchStart(
_event):void
Defined in: src/core/Script.ts:233
Called when a hand's index finger starts touching this object.
Direct touch starts the object's selection lifecycle by default. Call
event.preventDefault() to handle contact without selecting.
Parameters
_event
Returns
void
Inherited from
onSelect()
onSelect(
_event):void
Defined in: src/core/Script.ts:144
Called whenever pinch / mouse click successfully completes, globally.
Parameters
_event
The interaction source and completed target.
Returns
void
Inherited from
onSelectEnd()
onSelectEnd(
_event):void
Defined in: src/core/Script.ts:138
Called whenever pinch / mouse click discontinues, globally.
Parameters
_event
The completed state and end reason.
Returns
void
Inherited from
onSelecting()
onSelecting(
_event):void
Defined in: src/core/Script.ts:149
Called whenever pinch / mouse click is happening, globally.
Parameters
_event
Returns
void
Inherited from
onSelectStart()
onSelectStart(
_event):void
Defined in: src/core/Script.ts:132
Called whenever pinch / mouse click starts, globally.
Parameters
_event
The interaction source and optional captured target.
Returns
void
Inherited from
onSimulatorStarted()
onSimulatorStarted():
void
Defined in: src/core/Script.ts:124
Returns
void
Inherited from
onSqueeze()
onSqueeze(
_event):void
Defined in: src/core/Script.ts:181
Called whenever gamepad trigger successfully completes, globally.
Parameters
_event
event.source.controller identifies the controller.
Returns
void
Inherited from
onSqueezeEnd()
onSqueezeEnd(
_event):void
Defined in: src/core/Script.ts:170
Called whenever gamepad trigger stops, globally.
Parameters
_event
event.source.controller identifies the controller.
Returns
void
Inherited from
onSqueezeStart()
onSqueezeStart(
_event):void
Defined in: src/core/Script.ts:165
Called whenever gamepad trigger starts, globally.
Parameters
_event
event.source.controller identifies the controller.
Returns
void
Inherited from
onSqueezing()
onSqueezing(
_event):void
Defined in: src/core/Script.ts:175
Called whenever gamepad is being triggered, globally.
Parameters
_event
Returns
void
Inherited from
onXRSessionEnded()
onXRSessionEnded():
void
Defined in: src/core/Script.ts:122
Returns
void
Inherited from
onXRSessionStarted()
onXRSessionStarted(
_session?):void
Defined in: src/core/Script.ts:121
Parameters
_session?
Returns
void
Inherited from
physicsStep()
physicsStep():
void
Defined in: src/core/Script.ts:119
Returns
void
Inherited from
placeOnHorizontalSurface()
placeOnHorizontalSurface(
objectToPlace,timeout,gridSteps):Promise<boolean>
Defined in: src/world/World.ts:266
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
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:227
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.
See /templates/03_spatial_placement/ for a complete placement example.
Parameters
objectToPlace
The object to position in the world.
controller
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:298
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:201
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?
The current XRFrame, containing environmental data.
Returns
void