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:

1const parent = scene.addObject();
2parent.name = 'parent`';
3const child = scene.addObject(parent);
4child.name = 'child`';

• Object3D
  • .active
  • .changed
  • .children
  • .childrenCount
  • .engine
  • .isDestroyed
  • .name
  • .objectId
  • .parent
  • .rotationLocal
  • .rotationWorld
  • .scalingLocal
  • .scalingWorld
  • .scene
  • .transformLocal
  • .transformWorld
  • .addComponent<T>(typeClass, params) ⇒ T
  • .clone(parent) ⇒ Object3D
  • .destroy() ⇒ void
  • .equals(otherObject) ⇒ boolean
  • .findByName(name, recursive) ⇒ Object3D[]
  • .findByNameDirect(name) ⇒ Object3D[]
  • .findByNameRecursive(name) ⇒ Object3D[]
  • .getChildren(out) ⇒ Object3D[]
  • .getComponent<T>(typeOrClass, index) ⇒ null | T
  • .getComponents<T>(typeOrClass) ⇒ T[]
  • .getForward<T>(out) ⇒ T
  • .getForwardWorld<T>(out) ⇒ T
  • .getPositionLocal<T>(out) ⇒ T
  • .getPositionWorld<T>(out) ⇒ T
  • .getRight<T>(out) ⇒ T
  • .getRightWorld<T>(out) ⇒ T
  • .getRotationLocal<T>(out) ⇒ T
  • .getRotationWorld<T>(out) ⇒ T
  • .getScalingLocal<T>(out) ⇒ T
  • .getScalingWorld<T>(out) ⇒ T
  • .getTransformLocal<T>(out) ⇒ T
  • .getTransformWorld<T>(out) ⇒ T
  • .getTranslationLocal<T>(out) ⇒ T
  • .getTranslationWorld<T>(out) ⇒ T
  • .getUp<T>(out) ⇒ T
  • .getUpWorld<T>(out) ⇒ T
  • .lookAt(p, up) ⇒ Object3D
  • .resetPosition() ⇒ Object3D
  • .resetPositionRotation() ⇒ Object3D
  • .resetRotation() ⇒ Object3D
  • .resetScaling() ⇒ Object3D
  • .resetTransform() ⇒ Object3D
  • .resetTranslation() ⇒ Object3D
  • .resetTranslationRotation() ⇒ Object3D
  • .rotate(q) ⇒ Object3D
  • .rotateAxisAngleDeg(a, d) ⇒ Object3D
  • .rotateAxisAngleDegLocal(a, d) ⇒ Object3D
  • .rotateAxisAngleDegObject(a, d) ⇒ Object3D
  • .rotateAxisAngleRad(a, d) ⇒ Object3D
  • .rotateAxisAngleRadLocal(a, d) ⇒ Object3D
  • .rotateAxisAngleRadObject(a, d) ⇒ Object3D
  • .rotateLocal(q) ⇒ Object3D
  • .rotateObject(q) ⇒ Object3D
  • .scale(v) ⇒ Object3D
  • .scaleLocal(v) ⇒ Object3D
  • .setDirty() ⇒ void
  • .setPositionLocal(v) ⇒ Object3D
  • .setPositionWorld(v) ⇒ Object3D
  • .setRotationLocal(v) ⇒ Object3D
  • .setRotationWorld(v) ⇒ Object3D
  • .setScalingLocal(v) ⇒ Object3D
  • .setScalingWorld(v) ⇒ Object3D
  • .setTransformLocal(v) ⇒ Object3D
  • .setTransformWorld(v) ⇒ Object3D
  • .setTranslationLocal(v) ⇒ Object3D
  • .setTranslationWorld(v) ⇒ Object3D
  • .toLocalSpaceTransform<T>(out, q) ⇒ T
  • .toObjectSpaceTransform<T>(out, q) ⇒ T
  • .toString() ⇒ string
  • .toWorldSpaceTransform<T>(out, q) ⇒ T
  • .transformPointInverseLocal<T>(out, p) ⇒ T
  • .transformPointInverseWorld<T>(out, p) ⇒ T
  • .transformPointLocal<T>(out, p) ⇒ T
  • .transformPointWorld<T>(out, p) ⇒ T
  • .transformVectorInverseLocal<T>(out, v) ⇒ T
  • .transformVectorInverseWorld<T>(out, v) ⇒ T
  • .transformVectorLocal<T>(out, v) ⇒ T
  • .transformVectorWorld<T>(out, v) ⇒ T
  • .translate(v) ⇒ Object3D
  • .translateLocal(v) ⇒ Object3D
  • .translateObject(v) ⇒ Object3D
  • .translateWorld(v) ⇒ Object3D

.active 

Disable/enable all components of this object.

.changed: boolean 

Whether given object’s transformation has changed.

.children: Object3D[] 

Equivalent to getChildren.

Note: Prefer to use getChildren for performance.

.childrenCount: number 

The number of children of this object.

.engine: WonderlandEngine 

Hosting engine instance.

.isDestroyed: boolean 

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 

Local object id in the scene 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 

Local space rotation.

Deprecated: Please use getRotationLocal and setRotationLocal instead.

.rotationLocal 

Set local space rotation.

Deprecated: Please use getRotationLocal and setRotationLocal instead.

.rotationWorld: Float32Array 

Global / world space rotation

Deprecated: Please use getRotationWorld and setRotationWorld instead.

.rotationWorld 

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 

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 

Set world space scaling.

Deprecated: Please use setScalingWorld and getScalingWorld instead.

.scene: Prefab 

Scene instance.

.transformLocal: Float32Array 

Local space transformation.

Deprecated: Please use setTransformLocal and getTransformLocal instead.

.transformLocal 

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 

Set world transform.

Deprecated: Please use setTransformWorld and getTransformWorld instead.

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

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

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

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

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

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

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

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

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

.addComponent(type: string, params: Record<string, any>) ⇒ 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

.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.

.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 ids and not the JavaScript reference.

Deprecate: Use JavaScript reference comparison instead:

1const objectA = scene.addObject();
2const objectB = scene.addObject();
3const objectC = objectB;
4console.log(objectA === objectB); // false
5console.log(objectA === objectA); // true
6console.log(objectB === objectC); // true

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

Search for descendants matching the name.

This method is a wrapper around findByNameDirect and findByNameRecursive.

Returns: An array of Object3D matching the name.

.findByNameDirect(name: string) ⇒ Object3D[] 

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.

.findByNameRecursive(name: string) ⇒ Object3D[] 

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.

.getChildren(out: Object3D[]) ⇒ 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.

Note: When providing an output array, only this.childrenCount elements will be written. The rest of the array will not be modified by this method.

Returns: The out parameter.

.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

.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.

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

Deprecated: Please use getForwardWorld instead.

.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.

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

.getPositionLocal() ⇒ Float32Array

Compute local / object space position from transformation.

Returns: The out parameter.

.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.

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

Deprecated: Please use getRightWorld instead.

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

Compute the object’s right facing world space vector.

Returns: The out parameter.

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

.getRotationLocal() ⇒ Float32Array

Local space rotation.

Returns: The out parameter.

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

.getRotationWorld() ⇒ Float32Array

World space rotation.

Returns: The out parameter.

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

.getScalingLocal() ⇒ Float32Array

Local / object space scaling.

Returns: The out parameter.

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

.getScalingWorld() ⇒ Float32Array

World space scaling.

Returns: The out parameter.

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

.getTransformLocal() ⇒ Float32Array

Local space transformation.

Returns: The out parameter.

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

.getTransformWorld() ⇒ Float32Array

World space transformation.

Returns: The out parameter.

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

.getTranslationLocal() ⇒ Float32Array

Deprecated: Please use getPositionLocal instead.

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

.getTranslationWorld() ⇒ Float32Array

Deprecated: Please use getPositionWorld instead.

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

Deprecated: Please use getUpWorld instead.

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

Compute the object’s up facing world space vector.

Returns: The out parameter.

.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).

.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.

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

Deprecated: Please use rotateAxisAngleDegLocal instead.

.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).

.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).

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

Deprecated: Please use rotateAxisAngleRadLocal instead.

.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).

.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).

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

Rotate by a quaternion.

Returns: Reference to self (for method chaining).

.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).

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

Deprecated: Please use scaleLocal instead.

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

Scale object by a vector in object space.

Returns: Reference to self (for method chaining).

.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).

.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).

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

Set local space rotation.

Returns: Reference to self (for method chaining).

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

Set local space rotation.

Returns: Reference to self (for method chaining).

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

Set local / object space scaling.

Returns: Reference to self (for method chaining).

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

Set World space scaling.

Returns: Reference to self (for method chaining).

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

Set local space rotation.

Returns: Reference to self (for method chaining).

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

Set world space rotation.

Returns: Reference to self (for method chaining).

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

Deprecated: Please use setPositionLocal instead.

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

Deprecated: Please use setPositionWorld instead.

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

Transform a world space dual quaternion into local space.

Returns: The out parameter.

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

Transform a world space dual quaternion into object space.

Returns: The out parameter.

.toString() ⇒ string 

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

Transform an object space dual quaternion into world space.

Returns: The out parameter.

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

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

Returns: The out parameter.

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

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

Returns: The out parameter.

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

Transform a point by this object’s local transform.

Returns: The out parameter.

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

Transform a point by this object’s world transform.

Returns: The out parameter.

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

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

Returns: The out parameter.

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

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

Returns: The out parameter.

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

Transform a vector by this object’s local transform.

Returns: The out parameter.

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

Transform a vector by this object’s world transform.

Returns: The out parameter.

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

Deprecated: Please use translateLocal instead.

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

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

Returns: Reference to self (for method chaining).

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

Translate object by a vector in object space.

Returns: Reference to self (for method chaining).

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

Translate object by a vector in world space.

Returns: Reference to self (for method chaining).