Guides
Guides
Start typing to search…

Nodes

This page will cover the functions for a general node be it a sprite or a label.

Pretty much everything in Cocos derives from nodes such as scenes and sprites. Cocos provides nodes with common functionality such as position, scale, z-index, rotation plus much more.

What this essentially means is that most of the objects you will add have similar functions hence they will be covered on this page.

Local Z-index - z-order relative to its siblings in the scene

/*
sets the local z-index (must by an integer)
nodes with a higher z-index appear above nodes with lower z-index's
*/
nodeName->setLocalZOrder( 5 );

// gets the local z-index value (returns an integer)
nodeName->getLocalZOrder( );
/*
sets the local z-index (must by an Number)
nodes with a higher local z-index appear above nodes with lower z-index's
*/
nodeName.setLocalZOrder( 5 );

// gets the local z-index value (returns a Number)
nodeName.getLocalZOrder( );

Global Z-index - defines the order in which the nodes are rendered

/*
sets the global z-index (must by an float)
nodes with a lower global z-index are rendered first
*/
nodeName->setGlobalZOrder( 5.0 );

// gets the global z-index value (returns an integer)
nodeName->getGlobalZOrder( );
/*
sets the global z-index (must by a Number)
nodes with a lower global z-index are rendered first
*/
nodeName.setGlobalZOrder( 5 );

// gets the global z-index value (returns a Number)
nodeName.getGlobalZOrder( );

Scale - scaling factor of the node and its children

// scaling factor that multiplies the width of the node and its children (takes a float)
nodeName->setScaleX( 0.5 );

// returns the scale factor in the x-axis (returns a float)
nodeName->getScaleX( );

// scaling factor that multiplies the height of the node and its children (takes a float)
nodeName->setScaleY( 0.5 );

// returns the scale factor in the y-axis (returns a float)
nodeName->getScaleY( );

// scaling factor that multiplies the z-axis of the node and its children (takes a float)
nodeName->setScaleZ( 0.5 );

// returns the scale factor in the z-axis (returns a float)
nodeName->getScaleZ( );

// scales the node in the x, y and z axis (take a float)
nodeName->setScale( 0.5 );

// returns the scale factor for the x and y axis if they are the same (returns a float)
nodeName->getScale( );

// scales the node's height and width (takes 2 floats)
nodeName->setScale( 0.5, 0.2 );
// scaling factor that multiplies the width of the node and its children (takes a Number)
nodeName.setScaleX( 0.5 );

// returns the scale factor in the x-axis (returns a Number)
nodeName.getScaleX( );

// scaling factor that multiplies the height of the node and its children (takes a Number)
nodeName.setScaleY( 0.5 );

// returns the scale factor in the y-axis (returns a Number)
nodeName.getScaleY( );

// scaling factor that multiplies the z-axis of the node and its children (takes a Number)
nodeName.setScaleZ( 0.5 );

// returns the scale factor in the z-axis (returns a Number)
nodeName.getScaleZ( );

// scales the node in the x, y and z axis (take a Number)
nodeName.setScale( 0.5 );

// returns the scale factor for the x and y axis if they are the same (returns a Number)
nodeName.getScale( );

// scales the node's height and width (takes 2 Numbers)
nodeName.setScale( 0.5, 0.2 );

Note: Default scale value is 1
Warning: Physics body doesn't support this

Position - position of the node

// set the node's position using a Vec2
nodeName->setPosition( Vec2( 50.0, 100.0 ) );

// get the node's position (returns a Vec2 &)
nodeName->getPosition( );

// get node position result x and y
result.x;
result.y;

// set the node's position using normalized coordinates (between 0 and 1)
nodeName->setNormalizedPosition( Vec2( 0.5, 0.7l ) );

// get the node's position using normalized coordinates
nodeName->getNormalizedPosition( );

// get node's normalized position result x and y
normalizedResult.x;
normalizedResult.y;

// set the node's position using 2 float values
nodeName->setPosition( 50.0, 100.0 );

// get the node's position but takes 2 float * paramaters instead of returning a value, the x and y positions are assigned to the parameters
float *x, *y;
sprite->getPosition( x, y );

// set the node's x and y positions individually (takes a float)
nodeName->setPositionX( 50.0 );
nodeName->setPositionY( 50.0 );

// get the node's x and y positions individually (returns a float)
nodeName->getPositionX( );
nodeName->getPositionY( );

// set the node's position but in 3D space using a Vec3
nodeName->setPosition( Vec3( 100.0, 200.0, 50.0 ) );

// get the node's 3D position (returns a Vec3)
nodeName->getPosition3D( );

// get node's position result x, y and z
result3D.x;
result3D.y;
result3D.y;

// set the node's z position using a float value
nodeName->setPositionZ( 50.0 );

// get the node's z position (returns a float)
nodeName->getPositionZ( );
// set the node's position
nodeName.setPosition( cc.p( 50, 100 ) );

// get the node's position (returns a cc.Point)
nodeName.getPosition( );

// get node position result x and y
result.x;
result.y;

// set the node's position using 2 Numbers
nodeName.setPosition( 50.0, 100.0 );

// set the node's x and y positions individually (takes a Number)
nodeName.setPositionX( 50.0 );
nodeName.setPositionY( 50.0 );

// get the node's x and y positions individually (returns a Number)
nodeName.getPositionX( );
nodeName.getPositionY( );

Skewing - distorts/stretches the node by skewing the angles in degrees

// skew the node's angles (takes a float value)
nodeName->setSkewX( 10.0 );
nodeName->setSkewY( 10.0 );

// get the node's skew angles (returns a float value)
nodeName->getSkewX( );
nodeName->getSkewY( );
// skew the node's angles (takes a Number)
nodeName.setSkewX( 10.0 );
nodeName.setSkewY( 10.0 );

// get the node's skew angles (returns a Number)
nodeName.getSkewX( );
nodeName.getSkewY( );

Warning: Physics body doesn't support this

Anchor Point - anchorPoint is the point around which all transformations and positioning manipulations take place essentially like a pin

// set the node's anchor point using a Vec2 &
nodeName->setAnchorPoint( Vec2( 0.5, 0.5 ) );

// get the node's anchor point (returns a Vec2 &)
nodeName->getAnchorPoint( );

// get the node's anchor point in pixels (returns a Vec2 &)
nodeName->getAnchorPointInPoints( );
// set the node's anchor point using a cc.p
nodeName.setAnchorPoint( cc.p( 0.5, 0.5 ) );

// get the node's anchor point (returns a cc.Point)
nodeName.getAnchorPoint( );

// get the node's anchor point in pixels (returns a cc.Point)
nodeName.getAnchorPointInPoints( );

Warning: If node has a physics body, the anchor point must be in the middle, you can't change this to another value.

Content Size - sets the untransformed size of the node

// set the node's content size (takes a Size & parameter)
nodeName->setContentSize( Size( 30.0, 90.0 ) );

// get the node's content size (returns a Size &)
nodeName->getContentSize( );
// set the node's content size (takes a cc.size parameter)
nodeName.setContentSize( cc.size( 30.0, 90.0 ) );

// get the node's content size (returns a cc.size)
nodeName.getContentSize( );

Visibility - sets whether or not the node is visible

// set the node's visibility (takes a bool, true is visible and false is invisible)
nodeName->setVisible( true );

// get the node's visibility status (returns a bool)
nodeName->isVisible( );
// set the node's visibility (takes a Boolean, true is visible and false is invisible)
nodeName.setVisible( true );

// get the node's visibility status (returns a Boolean)
nodeName.isVisible( );

Rotation - sets the rotation (angle) of the node in degrees

// set the node's rotation (takes a float value)
nodeName->setRotation( 45.0 );

// get the node's rotation (returns a float value)
nodeName->getRotation( );

// set 3D rotation (takes a Vec3 &)
nodeName->setRotation3D( Vec3( 45.0, 125.0, 20.0 ) );

// get the 3D rotation (returns a Vec3 &)
nodeName->getRotation3D( );
// set the node's rotation (takes a Number)
nodeName.setRotation( 45.0 );

// get the node's rotation (returns a Number)
nodeName.getRotation( );

Note: 0 is the default rotation angle.

Note: Positive values rotate node clockwise, and negative values for anti-clockwise.

Skew Rotation - to be used in conjunction with skewing

// set the node's skew rotation angles (takes a float)
nodeName->setRotationSkewX( 40.0 );
nodeName->setRotationSkewY( 60.0 );

// get the node's skew rotation angles (returns a float)
nodeName->getRotationSkewX( );
nodeName->getRotationSkewY( );
// set the node's skew rotation angles (takes a Number)
nodeName.setRotationX( 40.0 );
nodeName.setRotationY( 60.0 );

// get the node's skew rotation angles (returns a Number)
nodeName.getRotationX( );
nodeName.getRotationY( );

Tag and Name - used to identify a node

// set the node's tag (takes an integer)
nodeName->setTag( 5 );

// get the node's tag (returns an integer)
nodeName->getTag( );

// set the node's name (takes a String)
nodeName->setName( "Name" );

// get the node's tag (returns a String)
nodeName->getName( );
// set the node's tag (takes a Number)
nodeName.setTag( 5 );

// get the node's tag (returns a Number)
nodeName.getTag( );

// set the node's name (takes a String)
nodeName.setName( "Name" );

// get the node's name (returns a String)
nodeName.getName( );

Node's Scene - get the node that the scene belongs to

// returns the node that the Scene belongs to
// if the node doesn't belong to any scene then 'nullptr' is returned
nodeName->getScene( );
// no JavaScript equivalent

Bounding Box - rectangular box that contains the node

// get the node's bounding box (returns a Rect)
nodeName->getBoundingBox( );
// get the node's bounding box (returns a cc.Rect)
nodeName.getBoundingBox( );

Actions - actions allow a node's properties to be manipulated

// run an Action (plus return the Action that is executed)
nodeName->runAction( actionToRun );

// stops all the running actions
nodeName->stopAllActions( );

// stop a particular action
nodeName->stopAction( actionToStop );

// stop an action based on it's tag (takes an integer)
nodeName->stopActionByTag( 5 );

// retrieves a running action based on it's tag (returns an integer)
nodeName->getActionByTag( );
// run an cc.Action (plus return the cc.Action that is executed)
nodeName.runAction( actionToRun );

// stops all the running actions
nodeName.stopAllActions( );

// stop a particular cc.Action
nodeName.stopAction( actionToStop );

// stop an cc.Action based on it's tag (takes a Number)
nodeName.stopActionByTag( 5 );

// retrieves a running cc.Action based on it's tag (returns a Number)
nodeName.getActionByTag( );

Note: Every action will be covered in a separate section.

Physics Body - physics body allow collisions to take place

// set the physics body for the node (takes a PhysicsBody *)
nodeName->setPhysicsBody( physicsBody );

// get the node's physics body (returns a PhysicsBody *)
nodeName->getPhysicsBody( );

Opacity And Colour - the visibility and colour of the node

// set the node's opacity (takes a GLubyte ranging between 0 and 255, 0 being invisible and 255 fully visible)
nodeName->setOpacity( 100 );

// get the node's opacity (returns a GLubyte)
nodeName->getOpacity( );

// set the node's colour (takes a Color3B)
nodeName->setColor( color3BObject );

// get the node's colour (returns a Color3B)
nodeName->getColor( );
// set the node's opacity (takes a Number ranging between 0 and 255, 0 being invisible and 255 fully visible)
nodeName.setOpacity( 100 );

// get the node's opacity (returns a Number)
nodeName.getOpacity( );

// set the node's colour (takes a cc.Color)
nodeName.setColor( new cc.Color(red, green, blue, alpha) );

// get the node's colour (returns a cc.Color)
nodeName.getColor( );

Here are all the different permutations the setColor method can take.

nodeName->setColor( Color3B::BLACK );

nodeName->setColor( Color3B::BLUE );

nodeName->setColor( Color3B::GRAY );

nodeName->setColor( Color3B::GREEN );

nodeName->setColor( Color3B::MAGENTA );

nodeName->setColor( Color3B::ORANGE );

nodeName->setColor( Color3B::RED );

nodeName->setColor( Color3B::WHITE );

nodeName->setColor( Color3B::YELLOW );

// Red, Green and Blue values range between 0 and 255
nodeName->setColor( Color3B( Red, Green, Blue ) );

Adding A Node To A Scene - there are several different way of adding

// add a node with a z-index of 0
this->addChild( nodeName );

// add a node with a custom z-index value (takes an integer)
this->addChild( nodeName, 2 );

// add a node with a custom z-index value and a tag (takes 2 integers)
this->addChild( nodeName, 2, 65 );

// add a node with a custom z-index value and a name (takes an integer and a string)
this->addChild( nodeName, 2, "Name of node" );

// get node by tag that has been previously added (returns a Node *)
this->getChildByTag( 2 );

// get node by name that has been previously added (returns a Node *)
this->getChildByName( "Name of node" );
// add a node with a z-index of 0
this.addChild( nodeName );

// add a node with a custom z-index value (takes a Number)
this.addChild( nodeName, 2 );

// add a node with a custom z-index value and a tag (takes 2 Numbers)
this.addChild( nodeName, 2, 65 );

// get node by tag that has been previously added (returns a Node)
this.getChildByTag( 2 );

// get node by name that has been previously added (returns a Node)
this.getChildByName( "Name of node" );

Note: Use the keyword'this' only if the node is being added within a scene otherwise use the layer name.

Removing A Node - there are different methods for removing nodes

// removes the node from it's parent, cleans up all running actions aswell
nodeName->removeFromParent( );

// removes the node from it's parent and you can specify if you want any running actions to be cleaned up
nodeName->removeFromParentAndCleanup( false );

// remove a particular node from it's container, cleans up all running actions aswell
this->removeChild( nodeName );

// remove a particular node from it's container, the second parameter is optional to specify if the node's running actions should be cleaned up
this->removeChild( nodeName, false );

// remove a node from it's container based on the node's tag, cleans up all running actions aswell
this->removeChildByTag( 6 );

// remove a node from it's container based on the node's tag, the second parameter is optional to specify if the node's running actions should be cleaned up
this->removeChildByTag( 6, false );

// remove a node from it's container based on the node's name, cleans up all running actions aswell
this->removeChildByName( "Name of node" );

// remove a node from it's container based on the node's name, the second parameter is optional to specify if the node's running actions should be cleaned up
this->removeChildByName( "Name of node", false );

// remove all the children (node's) from the container
this->removeAllChildren( );

// remove all the children (node's) from the container and specify if you want the node's running actions to be cleaned up
this->removeAllChildrenWithCleanup( false )
// removes the node from it's parent, cleans up all running actions aswell
nodeName.removeFromParent( );

// removes the node from it's parent and you can specify if you want any running actions to be cleaned up
nodeName.removeFromParentAndCleanup( false );

// remove a particular node from it's container, cleans up all running actions aswell
this.removeChild( nodeName );

// remove a particular node from it's container, the second parameter is optional to specify if the node's running actions should be cleaned up
this.removeChild( nodeName, false );

// remove a node from it's container based on the node's tag, cleans up all running actions aswell
this.removeChildByTag( 6 );

// remove a node from it's container based on the node's tag, the second parameter is optional to specify if the node's running actions should be cleaned up
this.removeChildByTag( 6, false );

// remove all the children (node's) from the container
this.removeAllChildren( );

// remove all the children (node's) from the container and specify if you want the node's running actions to be cleaned up
this.removeAllChildrenWithCleanup( false )

Note: Use the keyword'this' only if the node is being added within a scene otherwise use the layer name.

Updated about 2 months ago