Object3D

Scene graph object.

Node in the scene graph or “entity”. Consists of transformation and a reference to its parent object. Usually holds components and is accessible by components through object.

Objects are stored in a data oriented manner inside WebAssembly memory. This class is a JavaScript API wrapper around this memory for more convenient use in components.

Objects can be created and added to a scene through addObject on the scene.

.constructor(engine: WonderlandEngine, o: number) ⇒ Object3D 

ParamTypeDescription
engineWonderlandEngine
onumberObject id to wrap For performance reasons, please use wrapObject

.active 

0.8.5+

Disable/enable all components of this object.

.changed: boolean 

Whether given object’s transformation has changed.

.children: Object3D[] 

Children of this object.

Note: Child order is undefined. No assumptions should be made about the index of a specific object.

If you need to access a specific child of this object, you can use findByName.

When the object exists in the scene at editor time, prefer passing it as a component property.

.engine: WonderlandEngine 

Hosting engine instance.

.isDestroyed: boolean 

0.8.5+

true if the object is destroyed, false otherwise.

If erasePrototypeOnDestroy is true, reading a custom property will not work:

1engine.erasePrototypeOnDestroy = true;
2
3const obj = scene.addObject();
4obj.customParam = 'Hello World!';
5
6console.log(obj.isDestroyed); // Prints `false`
7obj.destroy();
8console.log(obj.isDestroyed); // Prints `true`
9console.log(obj.customParam); // Throws an error

.name: string 

Name of the object.

Useful for identifying objects during debugging.

.name 

Set the object’s name.

.objectId: number 

Object index in the manager.

.parent: null | Object3D 

Parent of this object or null if parented to root.

.parent 

Reparent object to given object.

Note: Reparenting is not trivial and might have a noticeable performance impact.

.rotationLocal: Float32Array 

0.8.5+

Local space rotation.

Deprecated: Please use getRotationLocal and setRotationLocal instead.

.rotationLocal 

0.8.5+

Set local space rotation.

Deprecated: Please use getRotationLocal and setRotationLocal instead.

.rotationWorld: Float32Array 

0.8.5+

Global / world space rotation

Deprecated: Please use getRotationWorld and setRotationWorld instead.

.rotationWorld 

0.8.5+

Set world space rotation.

Deprecated: Please use getRotationWorld and setRotationWorld instead.

.scalingLocal: Float32Array 

Local / object space scaling.

Deprecated: Please use setScalingLocal and getScalingLocal instead.

.scalingLocal 

0.8.5+

Set local space scaling.

Deprecated: Please use setScalingLocal and getScalingLocal instead.

.scalingWorld: Float32Array 

Global / world space scaling.

May recompute transformations of the hierarchy of this object, if they were changed by JavaScript components this frame.

Deprecated: Please use setScalingWorld and getScalingWorld instead.

.scalingWorld 

0.8.5+

Set world space scaling.

Deprecated: Please use setScalingWorld and getScalingWorld instead.

.transformLocal: Float32Array 

Local space transformation.

Deprecated: Please use setTransformLocal and getTransformLocal instead.

.transformLocal 

0.8.5+

Set local transform.

Deprecated: Please use setTransformLocal and getTransformLocal instead.

.transformWorld: Float32Array 

Global / world space transformation.

May recompute transformations of the hierarchy of this object, if they were changed by JavaScript components this frame.

Deprecated: Please use setTransformWorld and getTransformWorld instead.

.transformWorld 

0.8.5+

Set world transform.

Deprecated: Please use setTransformWorld and getTransformWorld instead.

.addComponent<T>(typeClass: ComponentConstructor, params: Record<string, any>) ⇒ null | T 

.addComponent(type: ‘collision’, params: Record<string, any>) ⇒ null | CollisionComponent

.addComponent(type: ’text’, params: Record<string, any>) ⇒ null | TextComponent

.addComponent(type: ‘view’, params: Record<string, any>) ⇒ null | ViewComponent

.addComponent(type: ‘mesh’, params: Record<string, any>) ⇒ null | MeshComponent

.addComponent(type: ‘input’, params: Record<string, any>) ⇒ null | InputComponent

.addComponent(type: ’light’, params: Record<string, any>) ⇒ null | LightComponent

.addComponent(type: ‘animation’, params: Record<string, any>) ⇒ null | AnimationComponent

.addComponent(type: ‘physx’, params: Record<string, any>) ⇒ null | PhysXComponent

.addComponent(type: string, params: Record<string, any>) ⇒ null | Component

Add component of given type to the object.

You can use this function to clone components, see the example below.

1 // Clone existing component (since 0.8.10)
2 let original = this.object.getComponent('mesh');
3 otherObject.addComponent('mesh', original);
4 // Create component from parameters
5 this.object.addComponent('mesh', {
6     mesh: someMesh,
7     material: someMaterial,
8 });

Returns: The component or null if the type was not found

ParamTypeDescription
typeClassComponentConstructor
paramsRecord<string, any>Parameters to initialize properties of the new component, can be another component to copy properties from.
Template ParamType Definition
Textends Component<1825>

.clone(parent: null | Object3D) ⇒ Object3D 

Clone this hierarchy into a new one.

Cloning copies the hierarchy structure, object names, as well as components.

JavaScript components are cloned using copy. You can override this method in your components.

Returns: The clone of this object.

ParamTypeDescription
parentnull | Object3DThe parent for the cloned hierarchy or null to clone into the scene root. Defaults to null.

.destroy() ⇒ void 

Destroy the object with all of its components and remove it from the scene

.equals(otherObject: undefined | null | Object3D) ⇒ boolean 

Checks equality by comparing whether the wrapped native object ids are equal.

Returns: Whether this object equals the given object.

ParamTypeDescription
otherObjectundefined | null | Object3DObject to check equality with.

.findByName(name: string, recursive: boolean) ⇒ Object3D[] 

0.8.5+

Search for descendants matching the name.

This method is a wrapper around findByNameDirect and findByNameRecursive.

Returns: An array of Object3D matching the name.

ParamTypeDescription
namestringThe name to search for.
recursivebooleanIf true, the method will look at all the descendants of this object. If false, this method will only perform the search in direct children.

.findByNameDirect(name: string) ⇒ Object3D[] 

0.8.5+

Search for all direct children matching the name.

Note: Even though this method is heavily optimized, it does perform a linear search to find the objects. Do not use in a hot path.

Returns: An array of Object3D matching the name.

ParamTypeDescription
namestringThe name to search for.

.findByNameRecursive(name: string) ⇒ Object3D[] 

0.8.5+

Search for all descendants matching the name.

Note: Even though this method is heavily optimized, it does perform a linear search to find the objects. Do not use in a hot path.

Returns: An array of Object3D matching the name.

ParamTypeDescription
namestringThe name to search for.

.getComponent<T>(typeOrClass: ComponentConstructor, index: number) ⇒ null | T 

.getComponent(type: ‘collision’, index: number) ⇒ null | CollisionComponent

.getComponent(type: ’text’, index: number) ⇒ null | TextComponent

.getComponent(type: ‘view’, index: number) ⇒ null | ViewComponent

.getComponent(type: ‘mesh’, index: number) ⇒ null | MeshComponent

.getComponent(type: ‘input’, index: number) ⇒ null | InputComponent

.getComponent(type: ’light’, index: number) ⇒ null | LightComponent

.getComponent(type: ‘animation’, index: number) ⇒ null | AnimationComponent

.getComponent(type: ‘physx’, index: number) ⇒ null | PhysXComponent

.getComponent(typeOrClass: string, index: number) ⇒ null | Component

Get a component attached to this object.

Returns: The component or null if there is no such component on this object

ParamTypeDescription
typeOrClassComponentConstructorType name. It’s also possible to give a class definition. In this case, the method will use the class.TypeName field to find the component.
indexnumber
Template ParamType Definition
Textends Component<1771>

.getComponents<T>(typeOrClass: ComponentConstructor) ⇒ T[] 

.getComponents(type: ‘collision’) ⇒ CollisionComponent[]

.getComponents(type: ’text’) ⇒ TextComponent[]

.getComponents(type: ‘view’) ⇒ ViewComponent[]

.getComponents(type: ‘mesh’) ⇒ MeshComponent[]

.getComponents(type: ‘input’) ⇒ InputComponent[]

.getComponents(type: ’light’) ⇒ LightComponent[]

.getComponents(type: ‘animation’) ⇒ AnimationComponent[]

.getComponents(type: ‘physx’) ⇒ PhysXComponent[]

.getComponents(type: null | string) ⇒ Component[]

Returns: All components of given type attached to this object.

Note: As this function is non-trivial, avoid using it in update() repeatedly, but rather store its result in init() or start()

Warning: This method will currently return at most 341 components.

ParamTypeDescription
typeOrClassComponentConstructorType name, pass a falsey value (undefined or null) to retrieve all. It’s also possible to give a class definition. In this case, the method will use the class.TypeName field to find the components.
Template ParamType Definition
Textends Component<1794>

.getForward<T>(out: T) ⇒ T 

Deprecated: Please use getForwardWorld instead.

ParamTypeDescription
outT
Template ParamType Definition
Textends NumberArray

.getForwardWorld<T>(out: T) ⇒ T 

Compute the object’s forward facing world space vector.

The forward vector in object space is along the negative z-axis, i.e., [0, 0, -1].

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 3 elements.
Template ParamType Definition
Textends NumberArray

.getPositionLocal<T>(out: T) ⇒ T 

.getPositionLocal() ⇒ Float32Array

Compute local / object space position from transformation.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 3 elements.
Template ParamType Definition
Textends NumberArray

.getPositionWorld<T>(out: T) ⇒ T 

.getPositionWorld() ⇒ Float32Array

Compute world space position from transformation.

May recompute transformations of the hierarchy of this object, if they were changed by JavaScript components this frame.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 3 elements.
Template ParamType Definition
Textends NumberArray

.getRight<T>(out: T) ⇒ T 

Deprecated: Please use getRightWorld instead.

ParamTypeDescription
outT
Template ParamType Definition
Textends NumberArray

.getRightWorld<T>(out: T) ⇒ T 

Compute the object’s right facing world space vector.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 3 elements.
Template ParamType Definition
Textends NumberArray

.getRotationLocal<T>(out: T) ⇒ T 

.getRotationLocal() ⇒ Float32Array

0.8.5+

Local space rotation.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 4 elements.
Template ParamType Definition
Textends NumberArray

.getRotationWorld<T>(out: T) ⇒ T 

.getRotationWorld() ⇒ Float32Array

0.8.5+

World space rotation.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 4 elements.
Template ParamType Definition
Textends NumberArray

.getScalingLocal<T>(out: T) ⇒ T 

.getScalingLocal() ⇒ Float32Array

0.8.5+

Local / object space scaling.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 3 elements.
Template ParamType Definition
Textends NumberArray

.getScalingWorld<T>(out: T) ⇒ T 

.getScalingWorld() ⇒ Float32Array

0.8.5+

World space scaling.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 3 elements.
Template ParamType Definition
Textends NumberArray

.getTransformLocal<T>(out: T) ⇒ T 

.getTransformLocal() ⇒ Float32Array

Local space transformation.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 8 elements.
Template ParamType Definition
Textends NumberArray

.getTransformWorld<T>(out: T) ⇒ T 

.getTransformWorld() ⇒ Float32Array

World space transformation.

Returns: The out parameter.

ParamTypeDescription
outTDestination array, expected to have at least 8 elements.
Template ParamType Definition
Textends NumberArray

.getTranslationLocal<T>(out: T) ⇒ T 

.getTranslationLocal() ⇒ Float32Array

Deprecated: Please use getPositionLocal instead.

ParamTypeDescription
outT
Template ParamType Definition
Textends NumberArray

.getTranslationWorld<T>(out: T) ⇒ T 

.getTranslationWorld() ⇒ Float32Array

Deprecated: Please use getPositionWorld instead.

ParamTypeDescription
outT
Template ParamType Definition
Textends NumberArray

.getUp<T>(out: T) ⇒ T 

Deprecated: Please use getUpWorld instead.

ParamTypeDescription
outT
Template ParamType Definition
Textends NumberArray

.getUpWorld<T>(out: T) ⇒ T 

Compute the object’s up facing world space vector.

Returns: The out parameter.

ParamTypeDescription
outTDestination array/vector, expected to have at least 3 elements.
Template ParamType Definition
Textends NumberArray

.lookAt(p: NumberArray, up: NumberArray) ⇒ Object3D 

Turn towards / look at target.

Rotates the object so that its forward vector faces towards the target position. The up vector acts as a hint to uniquely orient the object’s up direction. When orienting a view component, the projected up vector faces upwards on the viewing plane.

Returns: Reference to self (for method chaining).

ParamTypeDescription
pNumberArrayTarget position to turn towards, in world space.
upNumberArrayUp vector to align object with, in world space. Default is [0, 1, 0].

.resetPosition() ⇒ Object3D 

Reset local translation, keep rotation.

Note: To reset both rotation and translation, prefer resetTranslationRotation.

Returns: Reference to self (for method chaining).

.resetPositionRotation() ⇒ Object3D 

Reset local position and rotation to identity.

Returns: Reference to self (for method chaining).

.resetRotation() ⇒ Object3D 

Reset local rotation, keep translation.

Note: To reset both rotation and translation, prefer resetTranslationRotation.

Returns: Reference to self (for method chaining).

.resetScaling() ⇒ Object3D 

Reset local scaling to identity ([1.0, 1.0, 1.0]).

Returns: Reference to self (for method chaining).

.resetTransform() ⇒ Object3D 

Reset local transformation (translation, rotation and scaling) to identity.

Returns: Reference to self (for method chaining).

.resetTranslation() ⇒ Object3D 

Deprecated: Please use resetPosition instead.

.resetTranslationRotation() ⇒ Object3D 

Deprecated: Please use resetPositionRotation instead.

.rotate(q: Readonly<NumberArray>) ⇒ Object3D 

Deprecated: Please use rotateLocal instead.

ParamTypeDescription
qReadonly<NumberArray>

.rotateAxisAngleDeg(a: Readonly<NumberArray>, d: number) ⇒ Object3D 

Deprecated: Please use rotateAxisAngleDegLocal instead.

ParamTypeDescription
aReadonly<NumberArray>
dnumber

.rotateAxisAngleDegLocal(a: Readonly<NumberArray>, d: number) ⇒ Object3D 

Rotate around given axis by given angle (degrees) in local space.

Note: If the object is translated the rotation will be around the parent. To rotate around the object origin, use rotateAxisAngleDegObject

See: rotateAxisAngleRad

Returns: Reference to self (for method chaining).

ParamTypeDescription
aReadonly<NumberArray>Vector representing the rotation axis.
dnumberAngle in degrees.

.rotateAxisAngleDegObject(a: Readonly<NumberArray>, d: number) ⇒ Object3D 

Rotate around given axis by given angle (degrees) in object space.

See: rotateAxisAngleRadObject

Returns: Reference to self (for method chaining).

ParamTypeDescription
aReadonly<NumberArray>Vector representing the rotation axis.
dnumberAngle in degrees. Equivalent to prepending a rotation quaternion to the object’s local transformation.

.rotateAxisAngleRad(a: Readonly<NumberArray>, d: number) ⇒ Object3D 

Deprecated: Please use rotateAxisAngleRadLocal instead.

ParamTypeDescription
aReadonly<NumberArray>
dnumber

.rotateAxisAngleRadLocal(a: Readonly<NumberArray>, d: number) ⇒ Object3D 

Rotate around given axis by given angle (radians) in local space.

Note: If the object is translated the rotation will be around the parent. To rotate around the object origin, use rotateAxisAngleDegObject

See: rotateAxisAngleDeg

Returns: Reference to self (for method chaining).

ParamTypeDescription
aReadonly<NumberArray>Vector representing the rotation axis.
dnumberAngle in radians.

.rotateAxisAngleRadObject(a: Readonly<NumberArray>, d: number) ⇒ Object3D 

Rotate around given axis by given angle (radians) in object space Equivalent to prepending a rotation quaternion to the object’s local transformation.

See: rotateAxisAngleDegObject

Returns: Reference to self (for method chaining).

ParamTypeDescription
aReadonly<NumberArray>Vector representing the rotation axis
dnumberAngle in degrees

.rotateLocal(q: Readonly<NumberArray>) ⇒ Object3D 

Rotate by a quaternion.

Returns: Reference to self (for method chaining).

ParamTypeDescription
qReadonly<NumberArray>the Quaternion to rotate by.

.rotateObject(q: Readonly<NumberArray>) ⇒ Object3D 

Rotate by a quaternion in object space.

Equivalent to prepending a rotation quaternion to the object’s local transformation.

Returns: Reference to self (for method chaining).

ParamTypeDescription
qReadonly<NumberArray>the Quaternion to rotate by.

.scale(v: Readonly<NumberArray>) ⇒ Object3D 

Deprecated: Please use scaleLocal instead.

ParamTypeDescription
vReadonly<NumberArray>

.scaleLocal(v: Readonly<NumberArray>) ⇒ Object3D 

Scale object by a vector in object space.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>Vector to scale by.

.setDirty() ⇒ void 

Mark transformation dirty.

Causes an eventual recalculation of transformWorld, either on next getTranslationWorld, transformWorld or scalingWorld or the beginning of next frame, whichever happens first.

.setPositionLocal(v: Readonly<NumberArray>) ⇒ Object3D 

Set local / object space position.

Concatenates a new translation dual quaternion onto the existing rotation.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New local position array/vector, expected to have at least 3 elements.

.setPositionWorld(v: Readonly<NumberArray>) ⇒ Object3D 

Set world space position.

Applies the inverse parent transform with a new translation dual quaternion which is concatenated onto the existing rotation.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New world position array/vector, expected to have at least 3 elements.

.setRotationLocal(v: Readonly<NumberArray>) ⇒ Object3D 

Set local space rotation.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New world rotation array/vector, expected to have at least 4 elements.

.setRotationWorld(v: Readonly<NumberArray>) ⇒ Object3D 

Set local space rotation.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New world rotation array/vector, expected to have at least 4 elements.

.setScalingLocal(v: Readonly<NumberArray>) ⇒ Object3D 

Set local / object space scaling.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New local scaling array/vector, expected to have at least 3 elements.

.setScalingWorld(v: Readonly<NumberArray>) ⇒ Object3D 

Set World space scaling.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New world scaling array/vector, expected to have at least 3 elements.

.setTransformLocal(v: Readonly<NumberArray>) ⇒ Object3D 

Set local space rotation.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New local transform array, expected to have at least 8 elements.

.setTransformWorld(v: Readonly<NumberArray>) ⇒ Object3D 

Set world space rotation.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>New world transform array, expected to have at least 8 elements.

.setTranslationLocal(v: Readonly<NumberArray>) ⇒ Object3D 

Deprecated: Please use setPositionLocal instead.

ParamTypeDescription
vReadonly<NumberArray>

.setTranslationWorld(v: Readonly<NumberArray>) ⇒ Object3D 

Deprecated: Please use setPositionWorld instead.

ParamTypeDescription
vReadonly<NumberArray>

.toLocalSpaceTransform<T>(out: T, q: NumberArray) ⇒ T 

0.8.5+

Transform a world space dual quaternion into local space.

Returns: The out parameter.

ParamTypeDescription
outTOut transformation
qNumberArrayWorld space transformation, default out
Template ParamType Definition
Textends NumberArray

.toObjectSpaceTransform<T>(out: T, q: NumberArray) ⇒ T 

0.8.5+

Transform a world space dual quaternion into object space.

Returns: The out parameter.

ParamTypeDescription
outTOut transformation.
qNumberArrayWorld space transformation, default out
Template ParamType Definition
Textends NumberArray

.toWorldSpaceTransform<T>(out: T, q: NumberArray) ⇒ T 

0.8.5+

Transform an object space dual quaternion into world space.

Returns: The out parameter.

ParamTypeDescription
outTOut transformation.
qNumberArrayLocal space transformation, default out.
Template ParamType Definition
Textends NumberArray

.transformPointInverseLocal<T>(out: T, p: NumberArray) ⇒ T 

0.8.5+

Transform a point by this object’s inverse local transform.

Returns: The out parameter.

ParamTypeDescription
outTOut point.
pNumberArrayPoint to transform, default out.
Template ParamType Definition
Textends NumberArray

.transformPointInverseWorld<T>(out: T, p: NumberArray) ⇒ T 

0.8.5+

Transform a point by this object’s inverse world transform.

Returns: The out parameter.

ParamTypeDescription
outTOut point.
pNumberArrayPoint to transform, default out.
Template ParamType Definition
Textends NumberArray

.transformPointLocal<T>(out: T, p: NumberArray) ⇒ T 

0.8.5+

Transform a point by this object’s local transform.

Returns: The out parameter.

ParamTypeDescription
outTOut point.
pNumberArrayPoint to transform, default out.
Template ParamType Definition
Textends NumberArray

.transformPointWorld<T>(out: T, p: NumberArray) ⇒ T 

0.8.5+

Transform a point by this object’s world transform.

Returns: The out parameter.

ParamTypeDescription
outTOut point.
pNumberArrayPoint to transform, default out.
Template ParamType Definition
Textends NumberArray

.transformVectorInverseLocal<T>(out: T, v: NumberArray) ⇒ T 

0.8.5+

Transform a vector by this object’s inverse local transform.

Returns: The out parameter.

ParamTypeDescription
outTOut vector
vNumberArrayVector to transform, default out
Template ParamType Definition
Textends NumberArray

.transformVectorInverseWorld<T>(out: T, v: NumberArray) ⇒ T 

0.8.5+

Transform a vector by this object’s inverse world transform.

Returns: The out parameter.

ParamTypeDescription
outTOut vector.
vNumberArrayVector to transform, default out.
Template ParamType Definition
Textends NumberArray

.transformVectorLocal<T>(out: T, v: NumberArray) ⇒ T 

0.8.5+

Transform a vector by this object’s local transform.

Returns: The out parameter.

ParamTypeDescription
outTOut vector
vNumberArrayVector to transform, default out
Template ParamType Definition
Textends NumberArray

.transformVectorWorld<T>(out: T, v: NumberArray) ⇒ T 

0.8.5+

Transform a vector by this object’s world transform.

Returns: The out parameter.

ParamTypeDescription
outTOut vector
vNumberArrayVector to transform, default out
Template ParamType Definition
Textends NumberArray

.translate(v: Readonly<NumberArray>) ⇒ Object3D 

Deprecated: Please use translateLocal instead.

ParamTypeDescription
vReadonly<NumberArray>

.translateLocal(v: Readonly<NumberArray>) ⇒ Object3D 

Translate object by a vector in the parent’s space.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>Vector to translate by.

.translateObject(v: Readonly<NumberArray>) ⇒ Object3D 

Translate object by a vector in object space.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>Vector to translate by.

.translateWorld(v: Readonly<NumberArray>) ⇒ Object3D 

Translate object by a vector in world space.

Returns: Reference to self (for method chaining).

ParamTypeDescription
vReadonly<NumberArray>Vector to translate by.