Node

public class Node
Known Direct Subclasses

A Node represents a transformation within the scene graph's hierarchy. It can contain a renderable for the rendering engine to render.

Each node can have an arbitrary number of child nodes and one parent. The parent may be another node, or the scene.

Nested Classes

interface Node.OnTapListener Interface definition for a callback to be invoked when a node is tapped. 

Public Constructors

Node()
Create a node with no parent.

Public Methods

void
callOnHierarchy(Consumer<Node> consumer)
Traverse the hierarchy and call a method on each node (including this node).
Node
findInHierarchy(Predicate<Node> condition)
Traverse the hierarchy to find the first node (including this node) that meets a condition.
final Vector3
getBack()
Get the world-space back vector (+z) of this node.
CollisionShape
getCollisionShape()
Get the shape to use for collisions with this node.
final Vector3
getDown()
Get the world-space down vector (-y) of this node.
final Vector3
getForward()
Get the world-space forward vector (-z) of this node.
final Vector3
getLeft()
Get the world-space left vector (-x) of this node.
Light
getLight()
Get the current light, which is mutable.
final Vector3
getLocalPosition()
Get a copy of the nodes position relative to its parent (local-space).
final Quaternion
getLocalRotation()
Get a copy of the nodes rotation relative to its parent (local-space).
final Vector3
getLocalScale()
Get a copy of the nodes scale relative to its parent (local-space).
final String
getName()
Return the name of the node.
final Node
getParent()
If this Node has a parent, and that parent is a Node or Node subclass, then this function returns the parent as a Node.
Renderable
getRenderable()
Get the renderable to display for this node.
final Vector3
getRight()
Get the world-space right vector (+x) of this node.
final Scene
getScene()
Return the scene that this node is part of, null if it isn't part of any scene.
final Vector3
getUp()
Get the world-space up vector (+y) of this node.
final Vector3
getWorldPosition()
Get a copy of the nodes world-space position.
final Quaternion
getWorldRotation()
Get a copy of the nodes world-space rotation.
final Vector3
getWorldScale()
Get a copy of the nodes world-space scale.
final boolean
isActive()
A node is considered active if it meets ALL of the following conditions:
  • The node is part of a scene.
final boolean
isDescendantOf(NodeParent ancestor)
Recursively checks whether the given node parent is an ancestor of this node.
final boolean
isEnabled()
Get the enabled state of this node.
boolean
isTopLevel()
A node is considered top-level if it has no parent or if the parent is the scene.
final Vector3
localToWorldDirection(Vector3 direction)
Convert a direction from the local-space of this node to world-space.
final Vector3
localToWorldPoint(Vector3 point)
Convert a point in the local-space of this node to world-space.
void
onActivate()
Override to perform any setup that needs to occur when the node is activated.
void
onDeactivate()
Override to perform any setup that needs to occur when the node is deactivated.
void
onTap(HitTestResult hitTestResult, MotionEvent motionEvent)
boolean
onTouchEvent(HitTestResult hitTestResult, MotionEvent motionEvent)
Override to perform any logic that should occur when this node is touched.
void
onUpdate(FrameTime frameTime)
Override to perform any updates that need to occur before rendering each frame.
void
setCollisionShape(CollisionShape collisionShape)
Set the shape to used to detect collisions for this Node.
final void
setEnabled(boolean enabled)
Set the enabled state of this node.
void
setLight(Light light)
Set the Light to display.
void
setLocalPosition(Vector3 position)
Set the position of this node relative to its parent (local-space).
void
setLocalRotation(Quaternion rotation)
Set the rotation of this node relative to its parent (local-space).
void
setLocalScale(Vector3 scale)
Set the scale of this node relative to its parent (local-space).
final void
setLookDirection(Vector3 lookDirection)
Sets the direction that the node is looking at in world-space.
final void
setLookDirection(Vector3 lookDirection, Vector3 upDirection)
Sets the direction that the node is looking at in world-space.
final void
setName(String name)
Sets the name of this node.
void
setOnTapListener(Node.OnTapListener onTapListener)
Register a callback to be invoked when this node is tapped.
void
setParent(NodeParent parent)
Change the parent node of this node.
void
setRenderable(Renderable renderable)
Set the Renderable to display for this node.
void
setWorldPosition(Vector3 position)
Set the world-space position of this node.
void
setWorldRotation(Quaternion rotation)
Set the world-space rotation of this node.
void
setWorldScale(Vector3 scale)
Set the world-space scale of this node.
String
final Vector3
worldToLocalDirection(Vector3 direction)
Convert a direction from world-space to the local-space of this node.
final Vector3
worldToLocalPoint(Vector3 point)
Convert a point in world-space to the local-space of this node.

Protected Methods

final boolean
canAddChild(Node child, StringBuilder failureReason)
final void
onAddChild(Node child)
final void

Inherited Methods

Public Constructors

public Node ()

Create a node with no parent.

Public Methods

public void callOnHierarchy (Consumer<Node> consumer)

Traverse the hierarchy and call a method on each node (including this node). Traversal is depth first.

Parameters
consumer the method to call on each node

public Node findInHierarchy (Predicate<Node> condition)

Traverse the hierarchy to find the first node (including this node) that meets a condition. Once the predicate is met, the traversal stops. Traversal is depth first.

Parameters
condition predicate the defines the conditions of the node to search for.
Returns
  • the first node that matches the conditions of the predicate, otherwise null is returned

public final Vector3 getBack ()

Get the world-space back vector (+z) of this node.

Returns
  • a new vector that represents the node's back direction in world-space

public CollisionShape getCollisionShape ()

Get the shape to use for collisions with this node. If the shape is null and setRenderable(Renderable) is set, then getCollisionShape() is used to detect collisions for this Node.

Returns
  • represents a geometric shape, i.e. sphere, box, convex hull.

public final Vector3 getDown ()

Get the world-space down vector (-y) of this node.

Returns
  • a new vector that represents the node's down direction in world-space

public final Vector3 getForward ()

Get the world-space forward vector (-z) of this node.

Returns
  • a new vector that represents the node's forward direction in world-space

public final Vector3 getLeft ()

Get the world-space left vector (-x) of this node.

Returns
  • a new vector that represents the node's left direction in world-space

public Light getLight ()

Get the current light, which is mutable.

public final Vector3 getLocalPosition ()

Get a copy of the nodes position relative to its parent (local-space). If isTopLevel() is true, then this is the same as getWorldPosition().

Returns
  • a new vector that represents the node's local-space position

public final Quaternion getLocalRotation ()

Get a copy of the nodes rotation relative to its parent (local-space). If isTopLevel() is true, then this is the same as getWorldRotation().

Returns
  • a new quaternion that represents the node's local-space rotation

public final Vector3 getLocalScale ()

Get a copy of the nodes scale relative to its parent (local-space). If isTopLevel() is true, then this is the same as getWorldScale().

Returns
  • a new vector that represents the node's local-space scale

public final String getName ()

Return the name of the node. The default value is "Node".

public final Node getParent ()

If this Node has a parent, and that parent is a Node or Node subclass, then this function returns the parent as a Node. Returns null if the parent is a Scene, use getScene() to retrieve the parent instead.

Returns
  • the parent as a Node, if the parent is a Node.

public Renderable getRenderable ()

Get the renderable to display for this node.

Returns
  • renderable to display for this node

public final Vector3 getRight ()

Get the world-space right vector (+x) of this node.

Returns
  • a new vector that represents the node's right direction in world-space

public final Scene getScene ()

Return the scene that this node is part of, null if it isn't part of any scene. A node is part of a scene if its highest level ancestor is a Scene

public final Vector3 getUp ()

Get the world-space up vector (+y) of this node.

Returns
  • a new vector that represents the node's up direction in world-space

public final Vector3 getWorldPosition ()

Get a copy of the nodes world-space position.

Returns
  • a new vector that represents the node's world-space position

public final Quaternion getWorldRotation ()

Get a copy of the nodes world-space rotation.

Returns
  • a new quaternion that represents the node's world-space rotation

public final Vector3 getWorldScale ()

Get a copy of the nodes world-space scale. Some precision will be lost if the node is skewed.

Returns
  • a new vector that represents the node's world-space scale

public final boolean isActive ()

A node is considered active if it meets ALL of the following conditions:

  • The node is part of a scene.
  • the node's parent is active.
  • The node is enabled.
An active Node has the following behavior:

Returns
  • the node's active status

public final boolean isDescendantOf (NodeParent ancestor)

Recursively checks whether the given node parent is an ancestor of this node.

Parameters
ancestor the node parent to check
Returns
  • true if the node is an ancestor of this node

public final boolean isEnabled ()

Get the enabled state of this node. Note that a Node may be enabled but still inactive if it isn't part of the scene or if its parent is inactive.

Returns
  • the node's enabled status.
See Also

public boolean isTopLevel ()

A node is considered top-level if it has no parent or if the parent is the scene.

Returns
  • true if the node is top level

public final Vector3 localToWorldDirection (Vector3 direction)

Convert a direction from the local-space of this node to world-space. Not impacted by the position or scale of the node.

Parameters
direction the direction in local-space to convert
Returns
  • a new vector that represents the direction in world-space

public final Vector3 localToWorldPoint (Vector3 point)

Convert a point in the local-space of this node to world-space.

Parameters
point the point in local-space to convert
Returns
  • a new vector that represents the point in world-space

public void onActivate ()

Override to perform any setup that needs to occur when the node is activated. A Node is active if it's enabled, part of a scene, and its parent is active.

public void onDeactivate ()

Override to perform any setup that needs to occur when the node is deactivated. A Node is inactive if it's disabled, not part of a scene, or its parent is inactive.

public void onTap (HitTestResult hitTestResult, MotionEvent motionEvent)

Parameters
hitTestResult
motionEvent

public boolean onTouchEvent (HitTestResult hitTestResult, MotionEvent motionEvent)

Override to perform any logic that should occur when this node is touched. The way that touch events are propagated mirrors the way touches are propagated to Android Views. This is only called when the node is active.

When an ACTION_DOWN event occurs, that represents the start of a gesture. ACTION_UP or ACTION_CANCEL represents when a gesture ends. When a gesture starts, the following is done:

  • Call Node.onTouchEvent on the node that was touched as detected by scene.hitTest.
  • If Node.onTouchEvent returns false, recurse upwards through the node's parents and call Node.onTouchEvent until one of the node's returns true.
  • If every node returns false, the gesture is ignored and subsequent events that are part of the gesture will not be passed to any nodes.
  • If one of the node's returns true, then that node will consume all future touch events for the gesture.

Parameters
hitTestResult Represents the node that was touched, and information about where it was touched. On ACTION_DOWN events, getNode() will always be this node or one of its children. On other events, the touch may have moved causing the getNode() to change (or possibly be null).
motionEvent The motion event.
Returns
  • True if the event was handled, false otherwise.

public void onUpdate (FrameTime frameTime)

Override to perform any updates that need to occur before rendering each frame. This is only called when the node is active.

Parameters
frameTime provides time information for the current frame

public void setCollisionShape (CollisionShape collisionShape)

Set the shape to used to detect collisions for this Node. If the shape is not set and setRenderable(Renderable) is set, then getCollisionShape() is used to detect collisions for this Node.

Parameters
collisionShape represents a geometric shape, i.e. sphere, box, convex hull. If null, this node's current collision shape will be removed.

public final void setEnabled (boolean enabled)

Set the enabled state of this node. Note that a Node may be enabled but still inactive if it isn't part of the scene or if its parent is inactive.

Parameters
enabled the new enabled status of the node
See Also

public void setLight (Light light)

Set the Light to display. To use, first create a Light using Light.Builder. Set the parameters you care about and then attach it to the node using this function. A node may have a renderable and a light or just act as a Light.

Parameters
light Properties of the Light to render, pass null to remove the light.

public void setLocalPosition (Vector3 position)

Set the position of this node relative to its parent (local-space). If isTopLevel() is true, then this is the same as setWorldPosition(Vector3).

Parameters
position The position to apply.

public void setLocalRotation (Quaternion rotation)

Set the rotation of this node relative to its parent (local-space). If isTopLevel() is true, then this is the same as setWorldRotation(Quaternion).

Parameters
rotation The rotation to apply.

public void setLocalScale (Vector3 scale)

Set the scale of this node relative to its parent (local-space). If isTopLevel() is true, then this is the same as setWorldScale(Vector3).

Parameters
scale The scale to apply.
See Also

public final void setLookDirection (Vector3 lookDirection)

Sets the direction that the node is looking at in world-space. After calling this, getForward() will match the look direction passed in. World-space up (0, 1, 0) will be used to determine the orientation of the node around the direction.

Parameters
lookDirection a vector representing the desired look direction in world-space

public final void setLookDirection (Vector3 lookDirection, Vector3 upDirection)

Sets the direction that the node is looking at in world-space. After calling this, getForward() will match the look direction passed in. The up direction will determine the orientation of the node around the direction. The look direction and up direction cannot be coincident (parallel) or the orientation will be invalid.

Parameters
lookDirection a vector representing the desired look direction in world-space
upDirection a vector representing a valid up vector to use, such as Vector3.up()

public final void setName (String name)

Sets the name of this node. Nodes can be found using their names. Multiple nodes may have the same name, in which case calling findByName(String) will return the first node with the given name.

Parameters
name The name of the node.

public void setOnTapListener (Node.OnTapListener onTapListener)

Register a callback to be invoked when this node is tapped. If there is a callback registered, then touch events will not bubble to this node's parent. If the Node.onTouchEvent is overridden and super.onTouchEvent is not called, then the tap will not occur.

Parameters
onTapListener

public void setParent (NodeParent parent)

Change the parent node of this node. If set to null, this node will be detached from its parent. The local position, rotation, and scale of this node will remain the same. Therefore, the world position, rotation, and scale of this node may be different after the parent changes.

The parent may be another Node or a Scene. If it is a scene, then this Node is considered top level. getParent() will return null, and getScene() will return the scene.

Parameters
parent The new parent that this node will be a child of. If null, this node will be detached from its parent.

public void setRenderable (Renderable renderable)

Set the Renderable to display for this node. If setCollisionShape(CollisionShape) is not set, then getCollisionShape() is used to detect collisions for this Node.

Parameters
renderable Usually a 3D model. If null, this node's current renderable will be removed.

public void setWorldPosition (Vector3 position)

Set the world-space position of this node.

Parameters
position The position to apply.

public void setWorldRotation (Quaternion rotation)

Set the world-space rotation of this node.

Parameters
rotation The rotation to apply.

public void setWorldScale (Vector3 scale)

Set the world-space scale of this node.

Parameters
scale The scale to apply.
See Also

public String toString ()

public final Vector3 worldToLocalDirection (Vector3 direction)

Convert a direction from world-space to the local-space of this node. Not impacted by the position or scale of the node.

Parameters
direction the direction in world-space to convert
Returns
  • a new vector that represents the direction in local-space

public final Vector3 worldToLocalPoint (Vector3 point)

Convert a point in world-space to the local-space of this node.

Parameters
point the point in world-space to convert
Returns
  • a new vector that represents the point in local-space

Protected Methods

protected final boolean canAddChild (Node child, StringBuilder failureReason)

Parameters
child
failureReason

protected final void onAddChild (Node child)

Parameters
child

protected final void onRemoveChild (Node child)

Parameters
child

Send feedback about...