UeObject3D

The base class for all 3D entities in Unique Engine. Inherits from UeTransform, and acts as a hierarchical scene graph node.

Constructor

new UeObject3D(data = {})

Inherits from UeTransform

Data parameters

Key	Type	Default	Description
name	string	""	Optional object name
visible	boolean	true	Visibility flag
parent	UeObject3D	undefined	Parent object in the hierarchy
renderOrder	number	0	Custom sort order for rendering
castShadow	boolean	false	Whether this object casts shadows
receiveShadow	boolean	false	Whether this object receives shadows
gmObject	string	undefined	GameMaker object name to instantiate (e.g. "objPlayer") when this object is created by UeProjectLoader
gmLayer	string	"Instances"	GameMaker layer name for the instantiation
prefab	UeObject3D	undefined	The original asset this object is an instance of (set automatically when dragging assets into a scene (Scene Editor)
sourcePath	string	undefined	The original external asset path this object belongs to (e.g. "models/car.glb")

Properties

Property	Type	Default	Description
isObject3D	boolean	true	Indicates that this is an Object3D
type	string	"Object3D"	Object type
id	number	(auto-generated)	Incremental object ID
uuid	string	(auto-generated)	Randomly generated unique identifier
name	string	""	Optional object name
visible	boolean	true	Visibility flag
parent	UeObject3D	undefined	Parent object in the scene graph
children	array	[]	Array of child objects
renderOrder	number	0	Overrides render sort when rendering
layers	UeLayers		Layers with membership set to layer 0 by default
userData	struct		A struct where to safely place custom related data for this entity
gmObject	string	undefined	GameMaker object name to instantiate with this 3D object
gmLayer	string	"Instances"	GameMaker layer name where the object will be instantiated
prefab	UeObject3D	undefined	Reference to the source prefab/asset this instance belongs to (Scene Editor)
instances	array	[]	List of all scene instances that reference this object as their prefab. Used for O(1) propagation
__localOverrides	struct		Map of field names marked as locally overridden ({ field: true }). Fields in this map are not overwritten by syncFromPrefab()
sourcePath	string	undefined	The file path of the source asset (e.g. GLTF/OBJ path)
onBeforeRender	method	void method	Function called before rendering this object
onAfterRender	method	void method	Function called after rendering this object
onBeforeShadow	method	void method	Function called before rendering this object to shadow map
onAfterShadow	method	void method	Function called after rendering this object to shadow map
frustumCulled	boolean	true	If true, only renders this object if within the camera frustum. Geometry needs to have a bounding sphere, otherwise the test will be skipped and the object will always be rendered
castShadow	boolean	false	If true, this object will cast shadows when shadow mapping is enabled
receiveShadow	boolean	false	If true, this object will receive shadows from shadow-casting lights
animations	array	[]	List of UeAnimation associated with this node

🔁 Inherited from UeTransform

This class inherits all transformation logic, including:

• .position, .rotation, .scale
• .setPosition(), .rotate(), .lookAt() etc.
• .matrix, .matrixWorld and update flags

🧩 Methods

add(...objects)

Adds one or more child objects. Accepts individual objects as arguments or an array of objects.

remove(child)

Removes a specific child from this object.

removeFromParent()

Removes this object from its parent.

clear()

Recursively removes all children from this object.

clone()

Returns a deep clone of this object.

traverse(callback)

Executes a function on this object and all children (recursively).

traverseVisible(callback)

Same as .traverse(), but skips invisible objects.

traverseAncestors(callback)

Executes a callback function on this object’s ancestors, from immediate parent up to the root. Useful for parent hierarchy inspection.

attach(child)

Adds child to this object while preserving the child’s world transform. Does not support non-uniformly scaled parents.

copy(source, recursive = true)

Copies properties from another UeObject3D. If recursive is true, also clones and adds the source’s children.

getObjectById(targetId)

Searches for and returns the first object with a matching .id in the entire hierarchy.

getObjectByName(name)

Searches for and returns the first object with a matching .name. Names are empty by default unless set manually.

getObjectByProperty(name, value)

Searches for and returns the first object in the hierarchy where object[name] === value.

getObjectsByProperty(name, value, optionalTarget = [])`

Same as getObjectByProperty, but collects all matching objects in the hierarchy. Optional array target can be passed for reuse.

Prefab & Override Methods

These methods support the Prefab Instance Override System. When an object is an instance (prefab != undefined), individual properties can be overridden locally while still inheriting non-overridden values from the source prefab.

setOverride(field)

Marks a field as locally overridden. The current value on the instance is kept, and future syncFromPrefab() calls will skip this field.

isOverridden(field)

Returns true if the given field is marked as overridden on this instance.

clearOverride(field)

Removes the override marker for a field without reverting its value.

clearAllOverrides()

Removes all override markers from this instance.

applyOverride(field)

Copies the instance's current value for field back onto the prefab source, then clears the override. Triggers propagatePrefabChanges() so all other instances of the same prefab are updated.

applyAllOverrides()

Applies every overridden field back to the prefab, then clears all overrides and propagates.

revertOverride(field)

Discards the instance's local value for field and restores it from the prefab source, then clears the override.

revertAllOverrides()

Reverts every overridden field back to the prefab value and clears all overrides.

syncFromPrefab(prefabSource)

Synchronizes all non-overridden properties from prefabSource onto this instance. Handles scalar fields, vec3 (position, scale), quaternion (rotation), material, and light-specific properties.

---

traverseChildren(callback)

Executes the callback on all children of this object (not on the object itself).

---

Events

The following events are automatically dispatched by UeObject3D:

• added – emitted on a child when it is added to a parent via .add(), .attach().
• childAdded – emitted on the parent when a child is added via .add(), .attach().
• removed – emitted on a child when it is removed from its parent via .clear(), .remove(), .removeFromParent().
• childRemoved – emitted on the parent when a child is removed via .clear(), .remove(), .removeFromParent().

🧠 Notes

All 3D objects in the scene (meshes, groups, lights, etc.) extend UeObject3D

When building a scene graph, you can nest children arbitrarily using .add() and traverse them for rendering or updates.

Globals

UE_OBJECT3D_DEFAULT_UP = vec3_create(0, 0, -1) Default up vector for objects (applied on the up property)

UE_OBJECT3D_DEFAULT_MATRIX_AUTO_UPDATE = true Default value for all new created objects

UE_OBJECT3D_DEFAULT_MATRIX_WORLD_AUTO_UPDATE = true Default value for all new created objects