Object3D

This class is a base class of every objects which can be added into scene tree for the 3d rendering. As a basic class, it has implemented event listening and serialization for every objects of scene. Each object has position, rotation and scale attribute to represent the spatial transform in a 3D coordinate.

Extends

• ElementEventDispatcher

Extended by

• Scene3D
• Camera3D
• Light
• Splat

Implements

• SerializerableDelegatedAsReference

Constructors

Constructor

new Object3D(): Object3D

Returns

Object3D

Overrides

ElementEventDispatcher.constructor

Properties

DefaultUp

static DefaultUp: Vector3

Every objects in 3D space must have a default up direction.

Default Value

Vector3(0, 1, 0)

---

id

id: number

Unique number for each object3D instance.

---

categoryId

categoryId: string

Reserved attribute

---

sourceType

sourceType: string

Record the object rendered as instance or other type.

---

scene

scene: Nullable<Scene3D>

The scene which this object belong to.

---

updateDirtyId

updateDirtyId: number

The number is the frame id which this object is changed or participates change of scene graph. If this value equals to frame id - 1,

Default Value

-1 means no change happen

---

name

name: string

The name of this object, it is empty if useless.

---

isObject3D

isObject3D: boolean

Used to check type of this or extended instance. This value should not be changed by user.

---

parent

parent: Nullable<Object3D>

Object’s parent node in the scene graph. An object can have at most one parent.

---

children

children: Object3D[]

Array with object’s children.

Remarks

See Group| Group for information on manually grouping objects.

---

up

up: Vector3

This is used by the lookAt method, for example, to determine the orientation of the result. Default is DefaultUp.

---

worldMatrixUpdateTimestamp

worldMatrixUpdateTimestamp: number

Record when this object’s world matrix last updated.

---

transformChanged

transformChanged: boolean

Record whether the object’s any attribute| attribute is updated.

---

visibleChanged

visibleChanged: boolean

---

matrixWorld

matrixWorld: Matrix4

The global transform of the object. If the Object3D has no parent, then it’s identical to the local transform matrix.

---

matrixWorldNeedsUpdate

matrixWorldNeedsUpdate: boolean

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

Default Value

false

---

netVisibility

netVisibility: boolean

Record if the object is really visible in rendering process. If the Object3D has no parent, it would be set by visible;

---

localMatrixNeedUpdate

localMatrixNeedUpdate: boolean

When this is set, it calculates the model matrix in that frame and resets this property to false.

Default Value

false

---

userData

readonly userData: Record<keyof any, any>

Inherited from

Camera3D.userData

---

_uuid

_uuid: any

Inherited from

ElementEventDispatcher._uuid

---

uuid

uuid: string

Inherited from

ElementEventDispatcher.uuid

---

_listeners

_listeners: Map<Symbol, Listener<never>[]>

Inherited from

ElementEventDispatcher._listeners

Accessors

layers

Get Signature

get layers(): Layers

Returns

Layers

Set Signature

set layers(v): void

Parameters

v

Layers

Returns

void

---

interactionLayers

Get Signature

get interactionLayers(): Layers | undefined

Returns

Layers | undefined

Set Signature

set interactionLayers(v): void

Parameters

v

Layers | undefined

Returns

void

---

groupLayer

Get Signature

get groupLayer(): Layers | undefined

Returns

Layers | undefined

Set Signature

set groupLayer(v): void

Parameters

v

Layers | undefined

Returns

void

---

position

Get Signature

get position(): Vector3

Returns

Vector3

Set Signature

set position(_position): void

A vector representing the object’s local position.

Parameters

_position

Vector3

Returns

void

---

rotation

Get Signature

get rotation(): Euler

Returns

Euler

Set Signature

set rotation(rotation): void

Object’s local rotation, in radians.

Parameters

rotation

Euler

Returns

void

---

quaternion

Get Signature

get quaternion(): Quaternion

Returns

Quaternion

Set Signature

set quaternion(_quaternion): void

Object’s local rotation as a Quaternion.

Remarks

See Quaternion for more details.

Parameters

_quaternion

Quaternion

Returns

void

---

scale

Get Signature

get scale(): Vector3

Returns

Vector3

Set Signature

set scale(_scale): void

The object’s local scale.

Default Value

Vector3( 1, 1, 1 )

Parameters

_scale

Vector3

Returns

void

---

matrix

Get Signature

get matrix(): Matrix4

The local transform matrix.

Returns

Matrix4

Set Signature

set matrix(value): void

Parameters

value

Matrix4

Returns

void

---

visible

Get Signature

get visible(): boolean

Object gets rendered if true.

Default Value

true

Returns

boolean

Set Signature

set visible(value): void

Parameters

value

boolean

Returns

void

---

businessTag

Get Signature

get businessTag(): string

Returns

string

Set Signature

set businessTag(v): void

Parameters

v

string

Returns

void

Inherited from

ElementEventDispatcher.businessTag

Methods

className()

className(): string

The name of instance’s class.

Returns

string

Implementation of

SerializerableDelegatedAsReference.className

---

destroy()

destroy(): void

Returns

void

Overrides

ElementEventDispatcher.destroy

---

freeGPU()

freeGPU(): void

Returns

void

---

syncData()

syncData(): void

Returns

void

---

updateVisibility()

updateVisibility(): boolean

Scene will check the object’s visibility in each render and make change netVisibility based on its and parent’s visible.

Returns

boolean

---

clearChangeMark()

clearChangeMark(): void

Set marks of change to false include attributeChanged| attribute, transform and visible.

Returns

void

---

setMatrixUpdated()

setMatrixUpdated(): void

If the local matrix is changed, use this method to manually refresh data in scene graph.

Returns

void

Tips

It’s better to use notifySceneChange() as an alternative.

---

notifySceneChange()

notifySceneChange(): void

Use this method to manually refresh data in scene graph and draw again. The engine may not notify every change of the scene. If any effect is not changed with the parameters, use this may solve.

Returns

void

---

setMatrixDirty()

setMatrixDirty(): void

If the local matrix or world matrix is changed, use this method to make engine refresh data in scene graph automatically. This method will set matrixWorldNeedsUpdate and localMatrixNeedUpdate to true.

Returns

void

---

updateWorldRenderData()

updateWorldRenderData(updateID): boolean

Change matrixWorldNeedsUpdate and worldMatrixUpdateTimestamp state. This method will refresh data of world matrix by updateMatrixWorld

Parameters

updateID

number

This number is used to identify the render.

Returns

boolean

---

isFlipped()

isFlipped(): boolean

If there are zero or two negative numbers in xyz, return false, otherwise return true.

Returns

boolean

---

localToWorld()

localToWorld(vector): Vector3

Converts the vector from local space to world space.

Parameters

vector

Vector3

A vector represents a position in local (object) coordinate.

Returns

Vector3

---

worldToLocal()

worldToLocal(vector): Vector3

Updates the vector from world space to local space.

Parameters

vector

Vector3

A vector in world coordinate.

Returns

Vector3

---

applyMatrix()

applyMatrix(matrix): void

Applies the matrix transform to the object and updates the object’s position, rotation and scale.

Parameters

matrix

Matrix4

A matrix represents the information of transform.

Returns

void

---

applyQuaternion()

applyQuaternion(q): this

Applies the rotation represented by the quaternion to the object.

Parameters

q

Quaternion

A Quaternion represents the information of rotation.

Returns

this

---

setRotationFromAxisAngle()

setRotationFromAxisAngle(axis, angle): void

Calls setFromAxisAngle( axis, angle ) on the Quaternion.

Parameters

axis

Vector3

A normalized vector in object space.

angle

number

Angle in radians.

Returns

void

---

setRotationFromEuler()

setRotationFromEuler(euler): void

Calls Quaternion.setRotationFromEuler| setRotationFromEuler(euler, true) on the Quaternion.

Parameters

euler

Euler

Euler angle specifying rotation amount.

Returns

void

---

setRotationFromMatrix()

setRotationFromMatrix(m): void

Calls setFromRotationMatrix(m) on the Quaternion.

Parameters

m

Matrix4

Euler angle specifying rotation amount.

Returns

void

---

setRotationFromQuaternion()

setRotationFromQuaternion(q): void

Copy the given quaternion to object’s quaternion.

Parameters

q

Quaternion

Euler angle specifying rotation amount.

Returns

void

---

rotateOnAxis()

rotateOnAxis(axis, angle): this

Rotate an object along an axis in object space. The axis is assumed to be normalized.

Parameters

axis

Vector3

A normalized vector in object space.

angle

number

Angle in radians.

Returns

this

---

rotateOnWorldAxis()

rotateOnWorldAxis(axis, angle): this

Rotate an object along an axis in world space. The axis is assumed to be normalized. Method Assumes no rotated parent.

Parameters

axis

Vector3

A normalized vector in object space.

angle

number

Angle in radians.

Returns

this

---

rotateX()

rotateX(angle): this

Rotates the object around x axis in local space.

Parameters

angle

number

The angle to rotate in radians.

Returns

this

---

rotateY()

rotateY(angle): this

Rotates the object around x axis in local space.

Parameters

angle

number

The angle to rotate in radians.

Returns

this

---

rotateZ()

rotateZ(angle): this

Rotates the object around x axis in local space.

Parameters

angle

number

The angle to rotate in radians.

Returns

this

---

translateOnAxis()

translateOnAxis(axis, distance): this

Translate an object by distance along an axis in object space. The axis is assumed to be normalized.

Parameters

axis

Vector3

A normalized vector in object space.

distance

number

The distance to translate.

Returns

this

---

translateX()

translateX(distance): this

Translates object along x axis in object space by distance units.

Parameters

distance

number

The distance to translate.

Returns

this

---

translateY()

translateY(distance): this

Translates object along y axis in object space by distance units.

Parameters

distance

number

The distance to translate.

Returns

this

---

translateZ()

translateZ(distance): this

Translates object along z axis in object space by distance units.

Parameters

distance

number

The distance to translate.

Returns

this

---

lookAt()

lookAt(_x): void

Rotates the object to face to a point in world space. This method does not support objects having non-uniformly-scaled parent(s)

Parameters

_x

Vector3

A vector representing position of target in world space.

Returns

void

---

lookAtLocalPoint()

lookAtLocalPoint(_x): void

Rotates the object to face a point in local space.

Parameters

_x

Vector3

A vector representing position of target in local space.

Returns

void

---

add()

add(o): this

Adds object as child of this object. An arbitrary number of objects may be added. Any current parent on an object passed in here will be removed, since an object can have at most one parent. The scene graph change will be immediately notify by engine after adding nodes.

Parameters

o

Object3D | Object3D[]

Parameter can be one object or objects array, all of them is added to this object.

Returns

this

---

remove()

remove(object): this

Remove the specified object form children.

Parameters

object

Object3D

The object which needs to be removed.

Returns

this

---

removeFromParent()

removeFromParent(): void

Returns

void

---

removeAllChildren()

removeAllChildren(): Object3D[]

Remove all children of this object.

Returns

Object3D[]

---

removeObjects()

removeObjects(objects): this

Remove all children in specified objects from this objects. Migrate from tools common

Parameters

objects

Object3D[]

An array of objects which need to be removed.

Returns

this

---

getObjectById()

getObjectById(id): Object3D

Searches through an object and its children, starting with the object itself, and returns the first with a matching id. Note that ids are assigned in chronological order: 1, 2, 3, …, incrementing by one for each new object.

Parameters

id

number

Unique number of the object instance.

Returns

Object3D

---

getObjectByName()

getObjectByName(name): Object3D

Searches through an object and its children, starting with the object itself, and returns the first with a matching name. Note that for most objects the name is an empty string by default. You will have to set it manually to make use of this method.

Parameters

name

string

String to match to the children’s Object3D.name property.

Returns

Object3D

---

getObjectByProperty()

getObjectByProperty(name, value): Object3D

Searches through an object and its children, starting with the object itself, and returns the first with a property that matches the value given.

Parameters

name

string

The property name to search for.

value

any

Value of the given property.

Returns

Object3D

---

getWorldPosition()

getWorldPosition(target): Vector3

Return a vector representing the position of the object in world space.

Parameters

target

Vector3

the result will be copied into this Vector3.

Returns

Vector3

---

getWorldQuaternion()

getWorldQuaternion(target): Quaternion

Return a quaternion representing the rotation of the object in world space.

Parameters

target

Quaternion

the result will be copied into this Quaternion.

Returns

Quaternion

---

getWorldScale()

getWorldScale(target): Vector3

Return a vector of the scaling factors applied to the object for each axis in world space.

Parameters

target

Vector3

the result will be copied into this Vector3.

Returns

Vector3

---

getWorldDirection()

getWorldDirection(target): Vector3

Return a vector representing the direction of object’s positive z-axis in world space.

Parameters

target

Vector3

the result will be copied into this Vector3.

Returns

Vector3

---

traverse()

traverse(callback): void

Execute the callback on this object and all descendants.

Parameters

callback

(object) => any

A function with as first argument an object3D object.

Returns

void

---

traverseWithChildrenSkip()

traverseWithChildrenSkip(callback): void

Execute the callback when return is false, stop traverse the object’s descendants.

Parameters

callback

(object) => boolean

A function with as first argument an object3D object, return boolean.

Returns

void

---

traverseVisible()

traverseVisible(callback): void

Execute the callback on this object and all descendants which is visible.

Parameters

callback

(object) => any

A function with as first argument an object3D object.

Returns

void

---

traverseAncestors()

traverseAncestors(callback): void

Execute the callback on this object and all ancestors.

Parameters

callback

(object) => any

A function with as first argument an object3D object.

Returns

void

---

updateMatrix()

updateMatrix(): void

Update the matrix local transform.

Returns

void

---

updateMatrixWorld()

updateMatrixWorld(force?): void

Update the object’s and its descendants’ matrix of global transform with. If the parameter or matrixWorldNeedsUpdate is true, matrix will not skip updates.

Parameters

force?

boolean

Whether or not force to updates the matrix.

Returns

void

---

updateWorldMatrix()

updateWorldMatrix(updateParents, updateChildren, force?): void

Update the object’s and its descendants’ matrix of global transform with. will update parent or children according to the parameters

Parameters

updateParents

boolean

update parents.

updateChildren

boolean

update children.

force?

boolean

Whether or not force to updates the matrix.

Returns

void

---

getLocalBounds()

getLocalBounds(localBox?): Box3

Get the whole bounding box of current object cover all children’s.

Parameters

localBox?

Box3

If this is not undefined, result will be stored to it.

Returns

Box3

---

getUUID()

getUUID(): string

Get UUID of this object instance. This value is automatically assigned, so this shouldn’t be edited.

Returns

string

Implementation of

SerializerableDelegatedAsReference.getUUID

---

serialize()

serialize(ctx): void

Store the attributes of this class into string as serializing format.

Parameters

ctx

Serializer

this parameter has not supported external Serializer yet. It may cause that this method can not be used directly.

Returns

void

Implementation of

SerializerableDelegatedAsReference.serialize

---

deserialize()

deserialize(ctx): void

Parse the data for this class from string according to serializing format.

Parameters

ctx

Deserializer

this parameter has not supported external Deserializer yet. It may cause that this method can not be used directly.

Returns

void

Implementation of

SerializerableDelegatedAsReference.deserialize

---

clone()

clone(recursive?): Object3D

Return a cloned instance of this class and optionally all descendants.

Parameters

recursive?

boolean

if true, descendants of the object are also cloned. Default is true.

Returns

Object3D

---

copy()

copy(source, recursive?): this

Copy the data to this object from source. This method need override in derived classes to copy extended data.

Parameters

source

Object3D

the data source.

recursive?

boolean

if true, descendants of the object are also cloned. Default is true.

Returns

this

---

markBusinessTag()

markBusinessTag(v): this

Parameters

v

string

Returns

this

Inherited from

ElementEventDispatcher.markBusinessTag

---

isDestroyed()

isDestroyed(): boolean

Returns

boolean

Inherited from

ElementEventDispatcher.isDestroyed

---

validate()

validate(): void

Returns

void

Inherited from

ElementEventDispatcher.validate

---

destroyAllResourcesOwned()

destroyAllResourcesOwned(): void

Returns

void

Inherited from

ElementEventDispatcher.destroyAllResourcesOwned

---

freeAllGpuResourceOwned()

freeAllGpuResourceOwned(): void

Returns

void

Inherited from

ElementEventDispatcher.freeAllGpuResourceOwned

---

on()

on<T>(_type, _listener): void

Adds a listener to an event type.

Type Parameters

T

T

Parameters

_type

EventType<T>

_listener

Listener<T>

Returns

void

Inherited from

ElementEventDispatcher.on

---

once()

once<T>(_type, _listener): void

Only active the listener one times and then off it| it.

Type Parameters

T

T

Parameters

_type

EventType<T>

_listener

Listener<T>

Returns

void

Inherited from

ElementEventDispatcher.once

---

has()

has<T>(_type, _listener): boolean

Checks if listener is added to an event type.

Type Parameters

T

T

Parameters

_type

EventType<T>

_listener

Listener<T>

Returns

boolean

Inherited from

ElementEventDispatcher.has

---

off()

off<T>(_type, _listener): void

Removes a listener from listening list.

Type Parameters

T

T

Parameters

_type

EventType<T>

_listener

Listener<T>

Returns

void

Inherited from

ElementEventDispatcher.off

---

emit()

Call Signature

emit(type): void

Active the event and call the registered listener.

Parameters

type

EventType<never>

Returns

void

Inherited from

ElementEventDispatcher.emit

Call Signature

emit<T>(type, payload): void

Type Parameters

T

T

Parameters

type

EventType<T>

payload

T

Returns

void

Inherited from

ElementEventDispatcher.emit

---

clearAllListeners()

clearAllListeners(): void

Removes all listeners from listening list.

Returns

void

Inherited from

ElementEventDispatcher.clearAllListeners