Private _aabbPrivate _childrenPrivate _dirtyPrivate _dirtyPrivate _dirtyPrivate _enabledRepresents enabled state of the entity. If the entity is disabled, the entity including all children are excluded from updates.
Private _enabledRepresents enabled state of the entity in the hierarchy. It's true only if this entity and all parent entities all the way to the scene's root are enabled.
Private _forwardPrivate _frozenMarks the node to ignore hierarchy sync entirely (including children nodes). The engine code automatically freezes and unfreezes objects whenever required. Segregating dynamic and stationary nodes into subhierarchies allows to reduce sync time significantly.
Private _graphPrivate _labelsPrivate _normalPrivate _parentPrivate _rightPrivate _scalePrivate _upPrivate _worldCached value representing the negatively scaled world transform. If the value is 0, this marks this value as dirty and it needs to be recalculated. If the value is 1, the world transform is not negatively scaled. If the value is -1, the world transform is negatively scaled.
Private eulerPrivate localPrivate localPrivate localPrivate localPrivate localThe non-unique name of a graph node. Defaults to 'Untitled'.
Private positionPrivate rotationInterface for tagging graph nodes. Tag based searches can be performed using the GraphNode#findByTag function.
Private worldEnable or disable a GraphNode. If one of the GraphNode's parents is disabled there will be no other side effects. If all the parents are enabled then the new value will activate or deactivate all the enabled children of the GraphNode.
A read-only property to get the depth of this child within the graph. Note that for performance reasons this is only recalculated when a node is added to a new parent, i.e. It is not recalculated when a node is simply removed from the graph.
A read-only property to get the path of the graph node relative to the root of the hierarchy.
Private _clonePrivate The cloned graph node to copy into.
Private _dirtifyPrivate _dirtifyPrivate _dirtifyPrivate _firePrivate Fires an event on all children of the node. The event name is fired on the first (root)
node only. The event nameHierarchy is fired for all children.
The name of the event to fire on the root.
The name of the event to fire for all descendants.
The parent of the node being added/removed from the hierarchy.
Private _notifyPrivate Graph node to update.
True if enabled in the hierarchy, false if disabled.
Private _onPrivate _onPrivate Called when a node is inserted into a node's child list.
The node that was inserted.
Private _preparePrivate Prepares node for being inserted to a parent node, and removes it from the previous parent.
The node being inserted.
Private _unfreezePrivate _updateAdd a new child to the child list and update the parent value of the child node. If the node already had a parent, it is removed from its child list.
The new child to add.
const e = new pc.Entity(app);
this.entity.addChild(e);
Destroy the graph node and all of its descendants. First, the graph node is removed from the hierarchy. This is then repeated recursively for all descendants of the graph node.
The last thing the graph node does is fire the destroy event.
const firstChild = graphNode.children[0];
firstChild.destroy(); // destroy child and all of its descendants
Search the graph node and all of its descendants for the nodes that satisfy some search criteria.
This can either be a function or a string. If it's a function, it is executed for each descendant node to test if node satisfies the search logic. Returning true from the function will include the node into the results. If it's a string then it represents the name of a field or a method of the node. If this is the name of a field then the value passed as the second argument will be checked for equality. If this is the name of a function then the return value of the function will be checked for equality against the valued passed as the second argument to this function.
Optional value: objectIf the first argument (attr) is a property name then this value will be checked against the value of the property.
The array of graph nodes that match the search criteria.
// Finds all nodes that have a model component and have 'door' in their lower-cased name
const doors = house.find(function (node) {
return node.model && node.name.toLowerCase().indexOf('door') !== -1;
});
// Finds all nodes that have the name property set to 'Test'
const entities = parent.find('name', 'Test');
Get the first node found in the graph by its full path in the graph. The full path has this form 'parent/child/sub-child'. The search is depth first.
The first node to be found matching the supplied path. Returns null if no node is found.
// String form
const grandchild = this.entity.findByPath('child/grandchild');
// Array form
const grandchild = this.entity.findByPath(['child', 'grandchild']);
Return all graph nodes that satisfy the search query. Query can be simply a string, or comma separated strings, to have inclusive results of assets that match at least one query. A query that consists of an array of tags can be used to match graph nodes that have each tag of array.
Rest ...args: anyA list of all graph nodes that match the query.
// Return all graph nodes that tagged by `animal`
const animals = node.findByTag("animal");
// Return all graph nodes that tagged by `bird` OR `mammal`
const birdsAndMammals = node.findByTag("bird", "mammal");
// Return all assets that tagged by `carnivore` AND `mammal`
const meatEatingMammals = node.findByTag(["carnivore", "mammal"]);
// Return all assets that tagged by (`carnivore` AND `mammal`) OR (`carnivore` AND `reptile`)
const meatEatingMammalsAndReptiles = node.findByTag(["carnivore", "mammal"], ["carnivore", "reptile"]);
Search the graph node and all of its descendants for the first node that satisfies some search criteria.
This can either be a function or a string. If it's a function, it is executed for each descendant node to test if node satisfies the search logic. Returning true from the function will result in that node being returned from findOne. If it's a string then it represents the name of a field or a method of the node. If this is the name of a field then the value passed as the second argument will be checked for equality. If this is the name of a function then the return value of the function will be checked for equality against the valued passed as the second argument to this function.
Optional value: objectIf the first argument (attr) is a property name then this value will be checked against the value of the property.
A graph node that match the search criteria. Returns null if no node is found.
// Find the first node that is called 'head' and has a model component
const head = player.findOne(function (node) {
return node.model && node.name === 'head';
});
// Finds the first node that has the name property set to 'Test'
const node = parent.findOne('name', 'Test');
Fire an event, all additional arguments are passed on to the event listener.
Name of event to fire.
Optional arg1: anyFirst argument that is passed to the event handler.
Optional arg2: anySecond argument that is passed to the event handler.
Optional arg3: anyThird argument that is passed to the event handler.
Optional arg4: anyFourth argument that is passed to the event handler.
Optional arg5: anyFifth argument that is passed to the event handler.
Optional arg6: anySixth argument that is passed to the event handler.
Optional arg7: anySeventh argument that is passed to the event handler.
Optional arg8: anyEighth argument that is passed to the event handler.
Self for chaining.
obj.fire('test', 'This is the message');
Executes a provided function once on this graph node and all of its descendants.
The function to execute on the graph node and each descendant.
Optional thisArg: objectOptional value to use as this when executing callback function.
// Log the path and name of each node in descendant tree starting with "parent"
parent.forEach(function (node) {
console.log(node.path + "/" + node.name);
});
Get the world space rotation for the specified GraphNode in Euler angle form. The rotation is returned as euler angles in a Vec3. The value returned by this function should be considered read-only. In order to set the world-space rotation of the graph node, use GraphNode#setEulerAngles.
The world space rotation of the graph node in Euler angle form.
const angles = this.entity.getEulerAngles();
angles.y = 180; // rotate the entity around Y by 180 degrees
this.entity.setEulerAngles(angles);
Get the rotation in local space for the specified GraphNode. The rotation is returned as euler angles in a Vec3. The returned vector should be considered read-only. To update the local rotation, use GraphNode#setLocalEulerAngles.
The local space rotation of the graph node as euler angles in XYZ order.
const angles = this.entity.getLocalEulerAngles();
angles.y = 180;
this.entity.setLocalEulerAngles(angles);
Get the position in local space for the specified GraphNode. The position is returned as a Vec3. The returned vector should be considered read-only. To update the local position, use GraphNode#setLocalPosition.
The local space position of the graph node.
const position = this.entity.getLocalPosition();
position.x += 1; // move the entity 1 unit along x.
this.entity.setLocalPosition(position);
Get the rotation in local space for the specified GraphNode. The rotation is returned as a Quat. The returned quaternion should be considered read-only. To update the local rotation, use GraphNode#setLocalRotation.
The local space rotation of the graph node as a quaternion.
const rotation = this.entity.getLocalRotation();
Get the scale in local space for the specified GraphNode. The scale is returned as a Vec3. The returned vector should be considered read-only. To update the local scale, use GraphNode#setLocalScale.
The local space scale of the graph node.
const scale = this.entity.getLocalScale();
scale.x = 100;
this.entity.setLocalScale(scale);
Get the world space position for the specified GraphNode. The position is returned as a Vec3. The value returned by this function should be considered read-only. In order to set the world-space position of the graph node, use GraphNode#setPosition.
The world space position of the graph node.
const position = this.entity.getPosition();
position.x = 10;
this.entity.setPosition(position);
Get the world space rotation for the specified GraphNode. The rotation is returned as a Quat. The value returned by this function should be considered read-only. In order to set the world-space rotation of the graph node, use GraphNode#setRotation.
The world space rotation of the graph node as a quaternion.
const rotation = this.entity.getRotation();
Test if there are any handlers bound to an event name.
The name of the event to test.
True if the object has handlers bound to the specified event name.
obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false
Insert a new child to the child list at the specified index and update the parent value of the child node. If the node already had a parent, it is removed from its child list.
The new child to insert.
The index in the child list of the parent where the new node will be inserted.
const e = new pc.Entity(app);
this.entity.insertChild(e, 1);
Check if node is ancestor for another node.
Potential descendant of node.
If node is ancestor for another node.
if (body.isAncestorOf(foot)) {
// foot is within body's hierarchy
}
Check if node is descendant of another node.
Potential ancestor of node.
If node is descendant of another node.
if (roof.isDescendantOf(house)) {
// roof is descendant of house entity
}
Reorients the graph node so that the negative z-axis points towards the target. This function has two valid signatures. Either pass 3D vectors for the look at coordinate and up vector, or pass numbers to represent the vectors.
If passing a 3D vector, this is the world-space coordinate to look at. Otherwise, it is the x-component of the world-space coordinate to look at.
Optional y: number | Vec3If passing a 3D vector, this is the world-space up vector for look at transform. Otherwise, it is the y-component of the world-space coordinate to look at.
Optional z: numberZ-component of the world-space coordinate to look at.
Optional ux: number = 0X-component of the up vector for the look at transform. Defaults to 0.
Optional uy: number = 1Y-component of the up vector for the look at transform. Defaults to 1.
Optional uz: number = 0Z-component of the up vector for the look at transform. Defaults to 0.
// Look at another entity, using the (default) positive y-axis for up
const position = otherEntity.getPosition();
this.entity.lookAt(position);
// Look at another entity, using the negative world y-axis for up
const position = otherEntity.getPosition();
this.entity.lookAt(position, pc.Vec3.DOWN);
// Look at the world space origin, using the (default) positive y-axis for up
this.entity.lookAt(0, 0, 0);
// Look at world-space coordinate [10, 10, 10], using the negative world y-axis for up
this.entity.lookAt(10, 10, 10, 0, -1, 0);
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Optional name: stringName of the event to unbind.
Optional callback: HandleEventCallbackFunction to be unbound.
Optional scope: objectScope that was used as the this when the event is fired.
Self for chaining.
const handler = function () {
};
obj.on('test', handler);
obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
Attach an event handler to an event.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
Can be used for removing event in the future.
obj.on('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
const evt = obj.on('test', function (a, b) {
console.log(a + b);
});
// some time later
evt.off();
Attach an event handler to an event. This handler will be removed after being fired once.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
obj.once('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
obj.fire('test', 1, 2); // not going to get handled
Remove the node from the child list and update the parent value of the child.
The node to remove.
const child = this.entity.children[0];
this.entity.removeChild(child);
Remove graph node from current parent and add as child to new parent.
New parent to attach graph node to.
Optional index: numberThe child index where the child node should be placed.
Rotates the graph node in world-space by the specified Euler angles. Eulers are specified in degrees in XYZ order. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the world-space rotation.
3-dimensional vector holding world-space rotation or rotation around world-space x-axis in degrees.
Optional y: numberRotation around world-space y-axis in degrees.
Optional z: numberRotation around world-space z-axis in degrees.
// Rotate via 3 numbers
this.entity.rotate(0, 90, 0);
// Rotate via vector
const r = new pc.Vec3(0, 90, 0);
this.entity.rotate(r);
Rotates the graph node in local-space by the specified Euler angles. Eulers are specified in degrees in XYZ order. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the local-space rotation.
3-dimensional vector holding local-space rotation or rotation around local-space x-axis in degrees.
Optional y: numberRotation around local-space y-axis in degrees.
Optional z: numberRotation around local-space z-axis in degrees.
// Rotate via 3 numbers
this.entity.rotateLocal(0, 90, 0);
// Rotate via vector
const r = new pc.Vec3(0, 90, 0);
this.entity.rotateLocal(r);
Sets the world-space rotation of the specified graph node using euler angles. Eulers are interpreted in XYZ order. Eulers must be specified in degrees. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the world-space euler rotation.
3-dimensional vector holding eulers or rotation around world-space x-axis in degrees.
Optional y: numberRotation around world-space y-axis in degrees.
Optional z: numberRotation around world-space z-axis in degrees.
// Set rotation of 90 degrees around world-space y-axis via 3 numbers
this.entity.setEulerAngles(0, 90, 0);
// Set rotation of 90 degrees around world-space y-axis via a vector
const angles = new pc.Vec3(0, 90, 0);
this.entity.setEulerAngles(angles);
Sets the local-space rotation of the specified graph node using euler angles. Eulers are interpreted in XYZ order. Eulers must be specified in degrees. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the local-space euler rotation.
3-dimensional vector holding eulers or rotation around local-space x-axis in degrees.
Optional y: numberRotation around local-space y-axis in degrees.
Optional z: numberRotation around local-space z-axis in degrees.
// Set rotation of 90 degrees around y-axis via 3 numbers
this.entity.setLocalEulerAngles(0, 90, 0);
// Set rotation of 90 degrees around y-axis via a vector
const angles = new pc.Vec3(0, 90, 0);
this.entity.setLocalEulerAngles(angles);
Sets the local-space position of the specified graph node. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the local-space position.
3-dimensional vector holding local-space position or x-coordinate of local-space position.
Optional y: numberY-coordinate of local-space position.
Optional z: numberZ-coordinate of local-space position.
// Set via 3 numbers
this.entity.setLocalPosition(0, 10, 0);
// Set via vector
const pos = new pc.Vec3(0, 10, 0);
this.entity.setLocalPosition(pos);
Sets the local-space rotation of the specified graph node. This function has two valid signatures: you can either pass a quaternion or 3 numbers to specify the local-space rotation.
Quaternion holding local-space rotation or x-component of local-space quaternion rotation.
Optional y: numberY-component of local-space quaternion rotation.
Optional z: numberZ-component of local-space quaternion rotation.
Optional w: numberW-component of local-space quaternion rotation.
// Set via 4 numbers
this.entity.setLocalRotation(0, 0, 0, 1);
// Set via quaternion
const q = pc.Quat();
this.entity.setLocalRotation(q);
Sets the local-space scale factor of the specified graph node. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the local-space scale.
3-dimensional vector holding local-space scale or x-coordinate of local-space scale.
Optional y: numberY-coordinate of local-space scale.
Optional z: numberZ-coordinate of local-space scale.
// Set via 3 numbers
this.entity.setLocalScale(10, 10, 10);
// Set via vector
const scale = new pc.Vec3(10, 10, 10);
this.entity.setLocalScale(scale);
Sets the world-space position of the specified graph node. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the world-space position.
3-dimensional vector holding world-space position or x-coordinate of world-space position.
Optional y: numberY-coordinate of world-space position.
Optional z: numberZ-coordinate of world-space position.
// Set via 3 numbers
this.entity.setPosition(0, 10, 0);
// Set via vector
const position = new pc.Vec3(0, 10, 0);
this.entity.setPosition(position);
Sets the world-space rotation of the specified graph node. This function has two valid signatures: you can either pass a quaternion or 3 numbers to specify the world-space rotation.
Quaternion holding world-space rotation or x-component of world-space quaternion rotation.
Optional y: numberY-component of world-space quaternion rotation.
Optional z: numberZ-component of world-space quaternion rotation.
Optional w: numberW-component of world-space quaternion rotation.
// Set via 4 numbers
this.entity.setRotation(0, 0, 0, 1);
// Set via quaternion
const q = pc.Quat();
this.entity.setRotation(q);
Translates the graph node in world-space by the specified translation vector. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the world-space translation.
3-dimensional vector holding world-space translation or x-coordinate of world-space translation.
Optional y: numberY-coordinate of world-space translation.
Optional z: numberZ-coordinate of world-space translation.
// Translate via 3 numbers
this.entity.translate(10, 0, 0);
// Translate via vector
const t = new pc.Vec3(10, 0, 0);
this.entity.translate(t);
Translates the graph node in local-space by the specified translation vector. This function has two valid signatures: you can either pass a 3D vector or 3 numbers to specify the local-space translation.
3-dimensional vector holding local-space translation or x-coordinate of local-space translation.
Optional y: numberY-coordinate of local-space translation.
Optional z: numberZ-coordinate of local-space translation.
// Translate via 3 numbers
this.entity.translateLocal(10, 0, 0);
// Translate via vector
const t = new pc.Vec3(10, 0, 0);
this.entity.translateLocal(t);
A hierarchical scene node.