Constructor
new GraphNode(nameopt)
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
name |
String |
<optional> |
The non-unique name of the graph node, default is "Untitled". |
Properties:
Name | Type | Description |
---|---|---|
name |
String | The non-unique name of a graph node. |
tags |
pc.Tags | Interface for tagging graph nodes. Tag based searches can be performed using the pc.GraphNode#findByTag function. |
- Source:
Members
(readonly) children :Array.<pc.GraphNode>
A read-only property to get the children of this graph node.
Type:
- Array.<pc.GraphNode>
- Source:
enabled :Boolean
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.
Type:
- Boolean
- Source:
(readonly) forward :pc.Vec3
The normalized local space negative Z-axis vector of the graph node in world space.
Type:
- Source:
(readonly) graphDepth :Number
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.
Type:
- Number
- Source:
(readonly) parent :pc.GraphNode
A read-only property to get a parent graph node
Type:
- Source:
(readonly) path :pc.GraphNode
A read-only property to get the path of the graph node relative to
the root of the hierarchy
Type:
- Source:
(readonly) right :pc.Vec3
The normalized local space X-axis vector of the graph node in world space.
Type:
- Source:
(readonly) root :pc.GraphNode
A read-only property to get highest graph node from current node
Type:
- Source:
(readonly) up :pc.Vec3
The normalized local space Y-axis vector of the graph node in world space.
Type:
- Source:
Methods
(private) _onHierarchyStateChanged(enabled)
Called when the enabled flag of the entity or one of its parents changes.
Parameters:
Name | Type | Description |
---|---|---|
enabled |
Boolean | true if enabled in the hierarchy, false if disabled. |
- Source:
addChild(node)
Add a new child to the child list and update the parent value of the child node
Parameters:
Name | Type | Description |
---|---|---|
node |
pc.GraphNode | The new child to add |
- Source:
Example
var e = new pc.Entity(app);
this.entity.addChild(e);
find(attr, valueopt) → {Array.<pc.GraphNode>}
Search the graph node and all of its descendants for the nodes that satisfy some search criteria.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
attr |
function | String | 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. | |
value |
Object |
<optional> |
If the first argument (attr) is a property name then this value will be checked against the value of the property. |
- Source:
Returns:
The array of graph nodes that match the search criteria.
- Type
- Array.<pc.GraphNode>
Examples
// Finds all nodes that have a 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;
});
// Finds all nodes that have the name property set to 'Test'
var entities = parent.find('name', 'Test');
findByName(name) → {pc.GraphNode}
Get the first node found in the graph with the name. The search
is depth first.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The name of the graph. |
- Source:
Returns:
The first node to be found matching the supplied name.
- Type
- pc.GraphNode
findByPath(path) → {pc.GraphNode}
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.
Parameters:
Name | Type | Description |
---|---|---|
path |
String | The full path of the pc.GraphNode. |
- Source:
Returns:
The first node to be found matching the supplied path.
- Type
- pc.GraphNode
Example
var path = this.entity.findByPath('child/another_child');
findByTag(query) → {Array.<pc.GraphNode>}
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
Parameters:
Name | Type | Description |
---|---|---|
query |
String | Name of a tag or array of tags |
- Source:
Returns:
A list of all graph nodes that match the query
- Type
- Array.<pc.GraphNode>
Examples
// Return all graph nodes that tagged by `animal`
var animals = node.findByTag("animal");
// Return all graph nodes that tagged by `bird` OR `mammal`
var birdsAndMammals = node.findByTag("bird", "mammal");
// Return all assets that tagged by `carnivore` AND `mammal`
var meatEatingMammals = node.findByTag([ "carnivore", "mammal" ]);
// Return all assets that tagged by (`carnivore` AND `mammal`) OR (`carnivore` AND `reptile`)
var meatEatingMammalsAndReptiles = node.findByTag([ "carnivore", "mammal" ], [ "carnivore", "reptile" ]);
findOne(attr, valueopt) → {pc.GraphNode}
Search the graph node and all of its descendants for the first node that satisfies some search criteria.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
attr |
function | String | 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. | |
value |
Object |
<optional> |
If the first argument (attr) is a property name then this value will be checked against the value of the property. |
- Source:
Returns:
A graph node that match the search criteria.
- Type
- pc.GraphNode
Examples
// Find the first node that is called `head` and has a model component
var head = player.findOne(function(node) {
return node.model && node.name === 'head';
});
// Finds the first node that has the name property set to 'Test'
var node = parent.findOne('name', 'Test');
forEach(callback, thisArgopt)
Executes a provided function once on this graph node and all of its descendants.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
callback |
function | The function to execute on the graph node and each descendant. | |
thisArg |
Object |
<optional> |
Optional value to use as this when executing callback function. |
- Source:
Example
// Log the path and name of each node in descendant tree starting with "parent"
parent.forEach(function (node) {
console.log(node.path + "/" + node.name);
});
getEulerAngles() → {pc.Vec3}
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.
- Source:
Returns:
The world space rotation of the graph node in Euler angle form.
- Type
- pc.Vec3
Example
var angles = this.entity.getEulerAngles(); // [0,0,0]
angles[1] = 180; // rotate the entity around Y by 180 degrees
this.entity.setEulerAngles(angles);
getLocalEulerAngles() → {pc.Vec3}
Get the rotation in local space for the specified GraphNode. The rotation
is returned as euler 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.
- Source:
Returns:
The local space rotation of the graph node as euler angles in XYZ order.
- Type
- pc.Vec3
Example
var angles = this.entity.getLocalEulerAngles();
angles[1] = 180;
this.entity.setLocalEulerAngles(angles);
getLocalPosition() → {pc.Vec3}
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.
- Source:
Returns:
The local space position of the graph node.
- Type
- pc.Vec3
Example
var position = this.entity.getLocalPosition();
position[0] += 1; // move the entity 1 unit along x.
this.entity.setLocalPosition(position);
getLocalRotation() → {pc.Quat}
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.
- Source:
Returns:
The local space rotation of the graph node as a quaternion.
- Type
- pc.Quat
Example
var rotation = this.entity.getLocalRotation();
getLocalScale() → {pc.Vec3}
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.
- Source:
Returns:
The local space scale of the graph node.
- Type
- pc.Vec3
Example
var scale = this.entity.getLocalScale();
scale.x = 100;
this.entity.setLocalScale(scale);
getLocalTransform() → {pc.Mat4}
Get the local transform matrix for this graph node. This matrix
is the transform relative to the node's parent's world transformation matrix.
- Source:
Returns:
The node's local transformation matrix.
- Type
- pc.Mat4
Example
var transform = this.entity.getLocalTransform();
getPosition() → {pc.Vec3}
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.
- Source:
Returns:
The world space position of the graph node.
- Type
- pc.Vec3
Example
var position = this.entity.getPosition();
position.x = 10;
this.entity.setPosition(position);
getRotation() → {pc.Quat}
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.
- Source:
Returns:
The world space rotation of the graph node as a quaternion.
- Type
- pc.Quat
Example
var rotation = this.entity.getRotation();
(private) getScale() → {pc.Vec3}
Get the world space scale for the specified GraphNode. The returned value
will only be correct for graph nodes that have a non-skewed world transform (a skew can
be introduced by the compounding of rotations and scales higher in the graph node
hierarchy). The value returned by this function should be considered read-only. Note
that it is not possible to set the world space scale of a graph node directly.
- Source:
Returns:
The world space scale of the graph node.
- Type
- pc.Vec3
Example
var scale = this.entity.getScale();
getWorldTransform() → {pc.Mat4}
Get the world transformation matrix for this graph node.
- Source:
Returns:
The node's world transformation matrix.
- Type
- pc.Mat4
Example
var transform = this.entity.getWorldTransform();
insertChild(node, index)
Insert a new child to the child list at the specified index and update the parent value of the child node
Parameters:
Name | Type | Description |
---|---|---|
node |
pc.GraphNode | The new child to insert |
index |
Number | The index in the child list of the parent where the new node will be inserted |
- Source:
Example
var e = new pc.Entity(app);
this.entity.insertChild(e, 1);
isAncestorOf(node) → {Boolean}
Check if node is ancestor for another node.
Parameters:
Name | Type | Description |
---|---|---|
node |
pc.GraphNode | Potential descendant of node. |
- Source:
Returns:
if node is ancestor for another node
- Type
- Boolean
Example
if (body.isAncestorOf(foot)) {
// foot is within body's hierarchy
}
isDescendantOf(node) → {Boolean}
Check if node is descendant of another node.
Parameters:
Name | Type | Description |
---|---|---|
node |
pc.GraphNode | Potential ancestor of node. |
- Source:
Returns:
if node is descendant of another node.
- Type
- Boolean
Example
if (roof.isDescendantOf(house)) {
// roof is descendant of house entity
}
lookAt(x, y, z, uxopt, uyopt, uzopt)
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.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
x |
pc.Vec3 | Number | 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. | ||
y |
pc.Vec3 | Number | If 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. | ||
z |
Number | z-component of the world-space coordinate to look at. | ||
ux |
Number |
<optional> |
0 | x-component of the up vector for the look at transform. |
uy |
Number |
<optional> |
1 | y-component of the up vector for the look at transform. |
uz |
Number |
<optional> |
0 | z-component of the up vector for the look at transform. |
- Source:
Examples
// Look at another entity, using the (default) positive y-axis for up
var position = otherEntity.getPosition();
this.entity.lookAt(position);
// Look at another entity, using the negative world y-axis for up
var 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);
removeChild(child)
Remove the node from the child list and update the parent value of the child.
Parameters:
Name | Type | Description |
---|---|---|
child |
pc.GraphNode | The node to remove. |
- Source:
Example
var child = this.entity.children[0];
this.entity.removeChild(child);
reparent(parent, index)
Remove graph node from current parent and add as child to new parent
Parameters:
Name | Type | Description |
---|---|---|
parent |
pc.GraphNode | New parent to attach graph node to |
index |
Number | (optional) The child index where the child node should be placed. |
- Source:
rotate(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding world-space rotation or rotation around world-space x-axis in degrees. | |
y |
Number |
<optional> |
Rotation around world-space y-axis in degrees. |
z |
Number |
<optional> |
Rotation around world-space z-axis in degrees. |
- Source:
Examples
// Rotate via 3 numbers
this.entity.rotate(0, 90, 0);
// Rotate via vector
var r = new pc.Vec3(0, 90, 0);
this.entity.rotate(r);
rotateLocal(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding local-space rotation or rotation around local-space x-axis in degrees. | |
y |
Number |
<optional> |
Rotation around local-space y-axis in degrees. |
z |
Number |
<optional> |
Rotation around local-space z-axis in degrees. |
- Source:
Examples
// Rotate via 3 numbers
this.entity.rotateLocal(0, 90, 0);
// Rotate via vector
var r = new pc.Vec3(0, 90, 0);
this.entity.rotateLocal(r);
setEulerAngles(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding eulers or rotation around world-space x-axis in degrees. | |
y |
Number |
<optional> |
rotation around world-space y-axis in degrees. |
z |
Number |
<optional> |
rotation around world-space z-axis in degrees. |
- Source:
Examples
// 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
var angles = new pc.Vec3(0, 90, 0);
this.entity.setEulerAngles(angles);
setLocalEulerAngles(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding eulers or rotation around local-space x-axis in degrees. | |
y |
Number |
<optional> |
rotation around local-space y-axis in degrees. |
z |
Number |
<optional> |
rotation around local-space z-axis in degrees. |
- Source:
Examples
// 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
var angles = new pc.Vec3(0, 90, 0);
this.entity.setLocalEulerAngles(angles);
setLocalPosition(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding local-space position or x-coordinate of local-space position. | |
y |
Number |
<optional> |
y-coordinate of local-space position. |
z |
Number |
<optional> |
z-coordinate of local-space position. |
- Source:
Examples
// Set via 3 numbers
this.entity.setLocalPosition(0, 10, 0);
// Set via vector
var pos = new pc.Vec3(0, 10, 0);
this.entity.setLocalPosition(pos)
setLocalRotation(x, yopt, zopt, wopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Quat | Number | quaternion holding local-space rotation or x-component of local-space quaternion rotation. | |
y |
Number |
<optional> |
y-component of local-space quaternion rotation. |
z |
Number |
<optional> |
z-component of local-space quaternion rotation. |
w |
Number |
<optional> |
w-component of local-space quaternion rotation. |
- Source:
Examples
// Set via 4 numbers
this.entity.setLocalRotation(0, 0, 0, 1);
// Set via quaternion
var q = pc.Quat();
this.entity.setLocalRotation(q);
setLocalScale(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding local-space scale or x-coordinate of local-space scale. | |
y |
Number |
<optional> |
y-coordinate of local-space scale. |
z |
Number |
<optional> |
z-coordinate of local-space scale. |
- Source:
Examples
// Set via 3 numbers
this.entity.setLocalScale(10, 10, 10);
// Set via vector
var scale = new pc.Vec3(10, 10, 10);
this.entity.setLocalScale(scale);
setPosition(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding world-space position or x-coordinate of world-space position. | |
y |
Number |
<optional> |
y-coordinate of world-space position. |
z |
Number |
<optional> |
z-coordinate of world-space position. |
- Source:
Examples
// Set via 3 numbers
this.entity.setPosition(0, 10, 0);
// Set via vector
var position = new pc.Vec3(0, 10, 0);
this.entity.setPosition(position);
setRotation(x, yopt, zopt, wopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Quat | Number | quaternion holding world-space rotation or x-component of world-space quaternion rotation. | |
y |
Number |
<optional> |
y-component of world-space quaternion rotation. |
z |
Number |
<optional> |
z-component of world-space quaternion rotation. |
w |
Number |
<optional> |
w-component of world-space quaternion rotation. |
- Source:
Examples
// Set via 4 numbers
this.entity.setRotation(0, 0, 0, 1);
// Set via quaternion
var q = pc.Quat();
this.entity.setRotation(q);
(private) syncHierarchy()
Updates the world transformation matrices at this node and all of its descendants.
- Source:
translate(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding world-space translation or x-coordinate of world-space translation. | |
y |
Number |
<optional> |
y-coordinate of world-space translation. |
z |
Number |
<optional> |
z-coordinate of world-space translation. |
- Source:
Examples
// Translate via 3 numbers
this.entity.translate(10, 0, 0);
// Translate via vector
var t = new pc.Vec3(10, 0, 0);
this.entity.translate(t);
translateLocal(x, yopt, zopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
x |
pc.Vec3 | Number | 3-dimensional vector holding local-space translation or x-coordinate of local-space translation. | |
y |
Number |
<optional> |
y-coordinate of local-space translation. |
z |
Number |
<optional> |
z-coordinate of local-space translation. |
- Source:
Examples
// Translate via 3 numbers
this.entity.translateLocal(10, 0, 0);
// Translate via vector
var t = new pc.Vec3(10, 0, 0);
this.entity.translateLocal(t);