Theme:

Object3D

Base class for most scene objects. Provides transform hierarchy, visibility, and serialization.

Extends EventDispatcher.

Constructor

const obj = new Object3D();

Properties

  • id — Auto-incrementing integer ID (readonly)
  • uuid — UUID string (readonly)
  • name — Optional name string
  • parent — Parent Object3D (or null)
  • children — Array of child Object3Ds
  • position — Local position (Vector3)
  • rotation — Local rotation as Euler (syncs with quaternion)
  • quaternion — Local rotation as Quaternion (syncs with rotation)
  • scale — Local scale (Vector3, default (1, 1, 1))
  • matrix — Local transform matrix (Matrix4)
  • matrixWorld — World transform matrix (Matrix4)
  • visible — Whether to render (default true)
  • castShadow — Whether this object's renderable geometry casts shadows (default true); this is per object and is not inherited by children
  • animations — Array of AnimationClips
  • userData — Custom data object

Methods

Transform

  • applyMatrix4(matrix) — Apply matrix, decompose into position/rotation/scale
  • applyQuaternion(q) — Apply rotation
  • setRotationFromAxisAngle(axis, angle), setRotationFromEuler(euler), setRotationFromMatrix(m), setRotationFromQuaternion(q)
  • rotateOnAxis(axis, angle) — Rotate in local space
  • rotateOnWorldAxis(axis, angle) — Rotate in world space
  • rotateX(angle), rotateY(angle), rotateZ(angle)
  • translateOnAxis(axis, distance) — Translate along local axis
  • translateX(d), translateY(d), translateZ(d)
  • lookAt(x, y, z) or lookAt(vector3) — Face a point in world space

Space Conversion

  • localToWorld(vector) — Local → world
  • worldToLocal(vector) — World → local

Hierarchy

  • add(object, ...) — Add child(ren)
  • remove(object, ...) — Remove child(ren)
  • removeFromParent() — Remove self from parent
  • clear() — Remove all children
  • attach(object) — Add child while preserving world transform

Search

  • getObjectById(id), getObjectByName(name)
  • getObjectByProperty(name, value) — First match
  • getObjectsByProperty(name, value, result?) — All matches

World State

  • getWorldPosition(target), getWorldQuaternion(target), getWorldScale(target), getWorldDirection(target)
  • sync() — Queue transform and descendant render updates
  • setVisible(boolean) — Change visibility through Unia's scene-update path

Traversal

  • traverse(callback) — Visit all descendants

Matrix

  • updateMatrix() — Recompute local matrix from position/rotation/scale
  • updateMatrixWorld(force?) — Recompute world matrices for this and descendants
  • updateWorldMatrix(updateParents?, updateChildren?) — Selective update

After gameplay transform changes, call sync(). Matrix-update methods can recompute CPU matrices immediately, but they do not notify Unia's renderer or replace sync().

After changing castShadow, call sync() so the shadow renderer receives the new per-object value.

Unia's add() synchronizes a newly parented child and queues its subtree for rendering. Also call world.add(child) only when a late-added subtree has update/preUpdate callbacks or point/spot lights. Raycasting remains explicit through world.addRaycastable(mesh).

remove() and removeFromParent() only change the hierarchy. Use world.remove(object) to dispose a runtime subtree.

Serialization

  • toJSON(meta?) — Serialize to JSON
  • clone(recursive?) — Deep copy; always await the result because cloning can be asynchronous
  • copy(source, recursive?) — Copy values; the result may be asynchronous in Unia