API Reference

Class List

pc.GraphNode

A hierarchical scene node.

Summary

Properties

childrenA read-only property to get the children of this graph node.[read only]
enabledEnable or disable a GraphNode.
forwardThe normalized local space negative Z-axis vector of the graph node in world space.[read only]
nameThe non-unique name of a graph node.
parentA read-only property to get a parent graph node[read only]
rightThe normalized local space X-axis vector of the graph node in world space.[read only]
rootA read-only property to get highest graph node from current node[read only]
tagsInterface for tagging graph nodes.
upThe normalized local space Y-axis vector of the graph node in world space.[read only]

Methods

addChildAdd a new child to the child list and update the parent value of the child node
findSearch the graph for nodes using a supplied method that implements test for seach.
findByNameGet the first node found in the graph with the name.
findByPathGet the first node found in the graph by its full path in the graph.
findByTagReturn all graph nodes that satisfy the search query.
findOneDepth first search the graph for nodes using suplied method to find first matching node.
getEulerAnglesGet the world space rotation for the specified GraphNode in Euler angle form.
getLocalEulerAnglesGet the rotation in local space for the specified GraphNode.
getLocalPositionGet the position in local space for the specified GraphNode.
getLocalRotationGet the rotation in local space for the specified GraphNode.
getLocalScaleGet the scale in local space for the specified GraphNode.
getLocalTransformGet the local transform matrix for this graph node.
getPathGets the path of the entity relative to the root of the hierarchy
getPositionGet the world space position for the specified GraphNode.
getRotationGet the world space rotation for the specified GraphNode in quaternion form.
getWorldTransformGet the world transformation matrix for this graph node.
insertChildInsert a new child to the child list at the specified index and update the parent value of the child node
isAncestorOfCheck if node is ancestor for another node.
isDescendantOfCheck if node is descendant of another node.
lookAtReorients the graph node so that the negative z axis points towards the target.
lookAt^2Reorients the graph node so that the negative z axis points towards the target.
removeChildRemove the node from the child list and update the parent value of the child.
reparentRemove graph node from current parent and add as child to new parent
rotateRotates the graph node in world space by the specified Euler angles.
rotateLocalRotates the graph node in local space by the specified Euler angles.
rotateLocal^2Rotates the graph node in local space by the specified Euler angles.
rotate^2Rotates the graph node in world space by the specified Euler angles.
setEulerAnglesSets the world space orientation of the specified graph node using Euler angles.
setEulerAngles^2Sets the world space orientation of the specified graph node using Euler angles.
setLocalEulerAnglesSets the local space rotation of the specified graph node using euler angles.
setLocalEulerAngles^2Sets the local space rotation of the specified graph node using euler angles.
setLocalPositionSets the local space position of the specified graph node.
setLocalPosition^2Sets the local space position of the specified graph node.
setLocalRotationSets the local space rotation of the specified graph node.
setLocalRotation^2Sets the local space rotation of the specified graph node.
setLocalScaleSets the local space scale factor of the specified graph node.
setLocalScale^2Sets the local space scale factor of the specified graph node.
setPositionSets the world space position of the specified graph node.
setPosition^2Sets the world space position of the specified graph node.
setRotationSets the world space rotation of the specified graph node using a quaternion.
setRotation^2Sets the world space rotation of the specified graph node using the 4 components of a quaternion.
syncHierarchyUpdates the world transformation matrices at this node and all of its descendants.
translateTranslates the graph node in world space by the specified translation vector.
translateLocalTranslates the graph node in local space by the specified translation vector.
translateLocal^2Translates the graph node in local space by the specified translation vector.
translate^2Translates the graph node in world space by the specified translation vector.

Details

Constructor

GraphNode()

Properties

pc.GraphNode[]children

A read-only property to get the children of this graph node.[read only]

Booleanenabled

Enable 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 / deactivate all the enabled children of the GraphNode.

pc.Vec3forward

The normalized local space negative Z-axis vector of the graph node in world space.[read only]

Stringname

The non-unique name of a graph node.

pc.GraphNodeparent

A read-only property to get a parent graph node[read only]

pc.GraphNoderoot

A read-only property to get highest graph node from current node[read only]

pc.Tagstags

Interface for tagging graph nodes. Tag based searches can be performed using the pc.GraphNode#findByTag function.

pc.Vec3up

The normalized local space Y-axis vector of the graph node in world space.[read only]

Methods

addChild(node)

Add a new child to the child list and update the parent value of the child node

var e = new pc.Entity(app);
this.entity.addChild(e);

Parameters

nodepc.GraphNodeThe new child to add

find(fn)

Search the graph for nodes using a supplied method that implements test for seach.

// finds all nodes that have model component and have `door` in their lower cased name
var doors = house.find(function(node) {
    return node.model && node.name.toLowerCase().indexOf('door') !== -1;
});

Parameters

fnfunctionMethod which is executed for each descendant node, to test if node satisfies search logic. Returning true from that method will include node into results.

Returns

pc.GraphNode[] An array of GraphNodes

findByName(name)

Get the first node found in the graph with the name. The search is depth first.

Parameters

nameStringThe name of the graph.

Returns

pc.GraphNode The first node to be found matching the supplied name.

findByPath(path)

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.

var path = this.entity.findByPath('child/another_child');

Parameters

pathStringThe full path of the pc.GraphNode.

Returns

pc.GraphNode The first node to be found matching the supplied path.

findByTag(query)

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

var animals = node.findByTag("animal");
// returns all graph nodes that tagged by `animal`
var birdsAndMammals = node.findByTag("bird", "mammal");
// returns all graph nodes that tagged by `bird` OR `mammal`
var meatEatingMammals = node.findByTag([ "carnivore", "mammal" ]);
// returns all assets that tagged by `carnivore` AND `mammal`
var meatEatingMammalsAndReptiles = node.findByTag([ "carnivore", "mammal" ], [ "carnivore", "reptile" ]);
// returns all assets that tagged by (`carnivore` AND `mammal`) OR (`carnivore` AND `reptile`)

Parameters

queryStringName of a tag or array of tags

Returns

pc.GraphNode[] A list of all graph nodes that match the query

findOne(fn)

Depth first search the graph for nodes using suplied method to find first matching node.

// find node that is called `head` and have model component
var head = player.find(function(node) {
    return node.model && node.name === 'head';
});

Parameters

fnfunctionMethod which is executed for each descendant node, to test if node satisfies search logic. Returning true from that method will stop search and return that node.

Returns

pc.GraphNode A single graph node.

getEulerAngles()

Get the world space rotation for the specified GraphNode in Euler angle form. The order of the returned Euler angles is XYZ. The value returned by this function should be considered read-only. In order to set the world-space rotation of the graph node, use pc.GraphNode#setEulerAngles.

var angles = this.entity.getEulerAngles(); // [0,0,0]
angles[1] = 180; // rotate the entity around Y by 180 degrees
this.entity.setEulerAngles(angles);

Returns

pc.Vec3 The world space rotation of the graph node in Euler angle form.

getLocalEulerAngles()

Get the rotation in local space for the specified GraphNode. The rotation is returned as eurler angles in a 3-dimensional vector where the order is XYZ. The returned vector should be considered read-only. To update the local rotation, use pc.GraphNode#setLocalEulerAngles.

var angles = this.entity.getLocalEulerAngles();
angles[1] = 180;
this.entity.setLocalEulerAngles(angles);

Returns

pc.Vec3 The local space rotation of the graph node as euler angles in XYZ order.

getLocalPosition()

Get the position in local space for the specified GraphNode. The position is returned as a 3-dimensional vector. The returned vector should be considered read-only. To update the local position, use pc.GraphNode#setLocalPosition.

var position = this.entity.getLocalPosition();
position[0] += 1; // move the entity 1 unit along x.
this.entity.setLocalPosition(position);

Returns

pc.Vec3 The local space position of the graph node.

getLocalRotation()

Get the rotation in local space for the specified GraphNode. The rotation is returned as a quaternion. The returned quaternion should be considered read-only. To update the local rotation, use pc.GraphNode#setLocalRotation.

var rotation = this.entity.getLocalRotation();

Returns

pc.Quat The local space rotation of the graph node as a quaternion.

getLocalScale()

Get the scale in local space for the specified GraphNode. The scale is returned as a 3-dimensional vector. The returned vector should be considered read-only. To update the local scale, use pc.GraphNode#setLocalScale.

var scale = this.entity.getLocalScale();
scale.x = 100;
this.entity.setLocalScale(scale);

Returns

pc.Vec3 The local space scale of the graph node.

getLocalTransform()

Get the local transform matrix for this graph node. This matrix is the transform relative to the node's parent's world transformation matrix.

var transform = this.entity.getLocalTransform();

Returns

pc.Mat4 The node's local transformation matrix.

getPath()

Gets the path of the entity relative to the root of the hierarchy

var path = this.entity.getPath();

Returns

String The path

getPosition()

Get the world space position for the specified GraphNode. The value returned by this function should be considered read-only. In order to set the world-space position of the graph node, use pc.GraphNode#setPosition.

var position = this.entity.getPosition();
position.x = 10;
this.entity.setPosition(position);

Returns

pc.Vec3 The world space position of the graph node.

getRotation()

Get the world space rotation for the specified GraphNode in quaternion form. The value returned by this function should be considered read-only. In order to set the world-space rotation of the graph node, use pc.GraphNode#setRotation.

var rotation = this.entity.getRotation();

Returns

pc.Quat The world space rotation of the graph node as a quaternion.

getWorldTransform()

Get the world transformation matrix for this graph node.

var transform = this.entity.getWorldTransform();

Returns

pc.Mat4 The node's world transformation matrix.

insertChild(node, index)

Insert a new child to the child list at the specified index and update the parent value of the child node

var e = new pc.Entity(app);
this.entity.insertChild(e, 1);

Parameters

nodepc.GraphNodeThe new child to insert
indexNumberThe index in the child list of the parent where the new node will be inserted

isAncestorOf()

Check if node is ancestor for another node.

if (body.isAncestorOf(foot)) {
    // foot is within body's hierarchy
}

Returns

Boolean if node is ancestor for another node

isDescendantOf()

Check if node is descendant of another node.

if (roof.isDescendantOf(house)) {
    // roof is descendant of house entity
}

Returns

Boolean if node is descendant of another node

lookAt(target, [up])

Reorients the graph node so that the negative z axis points towards the target.

var position = ... // get position from somewhere
// Look at a position, use default 'up' of [0,1,0]
this.entity.lookAt(position);
// Use a custom up value
this.entity.lookAt(position, this.entity.up);
// Specify position as elements
this.entity.lookAt(0, 0, 0);

Parameters

targetpc.Vec3The world space coordinate to 'look at'.
uppc.Vec3The up vector for the look at transform. If left unspecified, this is set to the world space y axis.

lookAt^2(tx, ty, tz, [ux], [uy], [uz])

Reorients the graph node so that the negative z axis points towards the target.

// Look at the world space origin, use default 'up' of [0,1,0]
this.entity.lookAt(0, 0, 0);
// Look at 10, 10, 10 with an inverted up value
this.entity.lookAt(10, 10, 10, 0, -1, 0);

Parameters

txNumberX-component of the world space coordinate to 'look at'.
tyNumberY-component of the world space coordinate to 'look at'.
tzNumberZ-component of the world space coordinate to 'look at'.
uxNumberX-component of the up vector for the look at transform. If left unspecified, this is set to the world space y axis.
uyNumberY-component of the up vector for the look at transform. If left unspecified, this is set to the world space y axis.
uzNumberZ-component of the up vector for the look at transform. If left unspecified, this is set to the world space y axis.

removeChild(node)

Remove the node from the child list and update the parent value of the child.

var child = this.entity.children[0];
this.entity.removeChild(child);

Parameters

nodepc.GraphNodeThe node to remove

reparent(parent, index)

Remove graph node from current parent and add as child to new parent

Parameters

parentpc.GraphNodeNew parent to attach graph node to
indexNumber(optional) The child index where the child node should be placed.

rotate(ex, ey, ez)

Rotates the graph node in world space by the specified Euler angles. Eulers are specified in degrees in XYZ order.

this.entity.rotate(0, 90, 0);

Parameters

exNumberRotation around world space X axis in degrees.
eyNumberRotation around world space Y axis in degrees.
ezNumberRotation around world space Z axis in degrees.

rotateLocal(ex, ey, ez)

Rotates the graph node in local space by the specified Euler angles. Eulers are specified in degrees in XYZ order.

this.entity.rotateLocal(0, 90, 0);

Parameters

exNumberRotation around local space X axis in degrees.
eyNumberRotation around local space Y axis in degrees.
ezNumberRotation around local space Z axis in degrees.

rotateLocal^2(rot)

Rotates the graph node in local space by the specified Euler angles. Eulers are specified in degrees in XYZ order.

var r = new pc.Vec3(0, 90, 0);
this.entity.rotateLocal(r);

Parameters

rotpc.Vec3Local space rotation (xyz) of graph node.

rotate^2(rot)

Rotates the graph node in world space by the specified Euler angles. Eulers are specified in degrees in XYZ order.

var r = new pc.Vec3(0, 90, 0);
this.entity.rotate(r);

Parameters

rotpc.Vec3World space rotation (xyz) of graph node.

setEulerAngles(ex, ey, ez)

Sets the world space orientation of the specified graph node using Euler angles. Angles are specified in degress in XYZ order.

this.entity.setEulerAngles(0, 90, 0);

Parameters

exNumberRotation around world space X axis in degrees.
eyNumberRotation around world space Y axis in degrees.
ezNumberRotation around world space Z axis in degrees.

setEulerAngles^2(angles)

Sets the world space orientation of the specified graph node using Euler angles. Angles are specified in degress in XYZ order.

var angles = new pc.Vec3(0, 90, 0);
this.entity.setEulerAngles(angles);

Parameters

anglespc.Vec3Euler angles in degrees (XYZ order).

setLocalEulerAngles(x, y, z)

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.entity.setLocalEulerAngles(0, 90, 0); // Set rotation of 90 degress around y-axis.

Parameters

xNumberrotation around x-axis in degrees.
yNumberrotation around y-axis in degrees.
zNumberrotation around z-axis in degrees.

setLocalEulerAngles^2(e)

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.

var angles = new pc.Vec3(0, 90, 0);
this.entity.setLocalEulerAngles(angles); // Set rotation of 90 degress around y-axis.

Parameters

epc.Vec3vector containing euler angles in XYZ order.

setLocalPosition(x, y, z)

Sets the local space position of the specified graph node.

this.entity.setLocalPosition(0, 10, 0);

Parameters

xNumberx-coordinate of local-space position.
yNumbery-coordinate of local-space position.
zNumberz-coordinate of local-space position.

setLocalPosition^2(pos)

Sets the local space position of the specified graph node.

var pos = new pc.Vec3(0, 10, 0);
this.entity.setLocalPosition(pos)

Parameters

pospc.Vec3position vector of graph node in local space.

setLocalRotation(q)

Sets the local space rotation of the specified graph node.

Parameters

qpc.Quatquaternion representing rotation of graph node in local space. var q = pc.Quat(); this.entity.setLocalRotation(q);

setLocalRotation^2(x, y, z, w)

Sets the local space rotation of the specified graph node.

// Set to the identity quaternion
this.entity.setLocalRotation(0, 0, 0, 1);

Parameters

xNumberX component of local space quaternion rotation.
yNumberY component of local space quaternion rotation.
zNumberZ component of local space quaternion rotation.
wNumberW component of local space quaternion rotation.

setLocalScale(x, y, z)

Sets the local space scale factor of the specified graph node.

this.entity.setLocalScale(10, 10, 10);

Parameters

xNumberx-coordinate of local-space scale.
yNumbery-coordinate of local-space scale.
zNumberz-coordinate of local-space scale.

setLocalScale^2(scale)

Sets the local space scale factor of the specified graph node.

var scale = new pc.Vec3(10, 10, 10);
this.entity.setLocalScale(scale);

Parameters

scalepc.Vec3xyz-scale of graph node in local space.

setPosition(x, y, z)

Sets the world space position of the specified graph node.

this.entity.setPosition(0, 10, 0);

Parameters

xNumberx-coordinate of world-space position.
yNumbery-coordinate of world-space position.
zNumberz-coordinate of world-space position.

setPosition^2(position)

Sets the world space position of the specified graph node.

var position = new pc.Vec3(0, 10, 0);
this.entity.setPosition(position);

Parameters

positionpc.Vec3world space position (xyz) of graph node.

setRotation(rot)

Sets the world space rotation of the specified graph node using a quaternion.

var q = new pc.Quat();
this.entity.setRotation(q);

Parameters

rotpc.QuatWorld space rotation (xyz) of graph node.

setRotation^2(x, y, z, w)

Sets the world space rotation of the specified graph node using the 4 components of a quaternion.

this.entity.setRotation(0, 0, 0, 1);

Parameters

xNumberX component of world space quaternion rotation.
yNumberY component of world space quaternion rotation.
zNumberZ component of world space quaternion rotation.
wNumberW component of world space quaternion rotation.

syncHierarchy()

Updates the world transformation matrices at this node and all of its descendants.

translate(x, y, z)

Translates the graph node in world space by the specified translation vector.

this.entity.translate(10, 0, 0);

Parameters

xNumberx-component of the translation vector.
yNumbery-component of the translation vector.
zNumberz-component of the translation vector.

translateLocal(x, y, z)

Translates the graph node in local space by the specified translation vector.

this.entity.translateLocal(10, 0, 0);

Parameters

xNumberx-component of the translation vector.
yNumbery-component of the translation vector.
zNumberz-component of the translation vector.

translateLocal^2(translation)

Translates the graph node in local space by the specified translation vector.

var t = new pc.Vec3(10, 0, 0);
this.entity.translateLocal(t);

Parameters

translationpc.Vec3The local space translation vector to apply.

translate^2(translation)

Translates the graph node in world space by the specified translation vector.

var t = new pc.Vec3(10, 0, 0);
this.entity.translate(t);

Parameters

translationpc.Vec3The world space translation vector to apply.