Inherits from CCResponder : NSObject
Conforms to CCSchedulerTarget
Declared in CCNode.h

Overview

CCNode is the base class for all objects displayed by Cocos2d. The nodes are hierachically organized in a tree, normally with a CCScene as its root node. Example of CCNode:s are CCSprite, CCScene and CCButton. The CCNode handles transformations, can have a content size and provides a coordinate system to its children. Any CCNode or subclass can handle user interaction, such as touches and mouse events, see the CCResponder for more information on this.

Coordinate System and Positioning

Coordinates in the CCNode coordinate system are by default set in points by the position property. The point measurement provides a way to handle different screen densities. For instance, on a retina display one point corresponds to two pixels, but on non-retina devices one point corresponds directly to one pixel.

By using the positionType property you can specify how a node’s position is interpreted. For instance, if you set the type to CCPositionTypeNormalized a position value of (0.5, 0.5) will place the node in the center of its parent’s container. The container is specified by the parent’s contentSize. It’s also possible to set positions relative to the different corners of the parent’s container. The CCPositionType has three components, xUnit, yUnit and corner. The corner can be any reference corner of the parent’s container and the xUnit and yUnit can be any of the following:

  • CCPositionUnitPoints - This is the default, the position value will be in points.
  • CCPositionUnitScaled - The position is scaled by the UIScaleFactor as defined by CCDirector. This is very useful for scaling up game play without changing the game logic. E.g. if you want to support both phones and tablets in native resolutions.
  • CCPositionUnitNormalized - Using the normalized type allows you to position object in relative to the parents container. E.g. it can be used to center nodes on the screen regardless of the device type your game is running on.

Similarily to how you set a node’s position and positionType you can also set it’s contentSize and contentSizeType. However, some classes doesn’t allow you to set these directly. For instance, the CCSprite sets its contentSize depending on the size of its texture and for descendants of CCControl you should set the preferredSize and preferredSizeType rather than changing their contentSize directly. The CCSizeType has two components widthUnit and heightUnit which can be any of the following:

  • CCSizeUnitPoints - This is the default, the size will be in points
  • CCSizeUnitScaled - The size is scaled by the UIScaleFactor.
  • CCSizeUnitNormalized - The content size will be set as a normalized value of the parent’s container.
  • CCSizeUnitInset - The content size will be the size of it’s parent container, but inset by a number of points.
  • CCSizeUnitInsetScaled - The content size will be the size of it’s parent container, but inset by a number of points multiplied by the UIScaleFactor.

Even if the positions and content sizes are not set in points you can use actions to animate the nodes. See the examples and tests for more information on how to set positions and content sizes, or use SpriteBuilder to easily play around with the settings. There are also more positioning options available by using CCLayout and CCLayoutBox.

Subclassing Notes

A common user pattern in building a Cocos2d game is to subclass CCNode, add it to a CCScene and override the methods for handling user input.

Debugging extensions of CCNode. They are available when the DEBUG macro is defined at compile time.

Tasks

Creating Nodes

Pausing and Hiding

Tagging and Setting User Object

Position and Size

Adding, Removing and Sorting Children

Scene Management

Physics

Actions

Scheduling Repeating Callbacks

Accessing Transformations and Matrices

Rendering (Used by Subclasses)

Debug Methods

NoARC Methods

CCPhysics Methods

Properties

anchorPoint

The anchorPoint is the point around which all transformations and positioning manipulations take place. It’s like a pin in the node where it is “attached” to its parent. The anchorPoint is normalized, like a percentage. (0,0) means the bottom-left corner and (1,1) means the top-right corner. But you can use values higher than (1,1) and lower than (0,0) too. The default anchorPoint is (0,0). It starts in the bottom-left corner. CCSprite and other subclasses have a different default anchorPoint.

@property (nonatomic, readwrite) CGPoint anchorPoint

Declared In

CCNode.h

anchorPointInPoints

The anchorPoint in absolute pixels. Since v0.8 you can only read it. If you wish to modify it, use anchorPoint instead.

@property (nonatomic, readonly) CGPoint anchorPointInPoints

Declared In

CCNode.h

animationManager

Returns the CCB Animation Manager of this node, or that of its parent.

@property (nonatomic, readonly) CCAnimationManager *animationManager

Declared In

CCNode.h

cascadeColorEnabled

CascadeColorEnabled causes changes to this node’s color to cascade down to it’s children. The new color is multiplied in with the color of each child, so it doesn’t bash the current color of those nodes. Opacity is unaffected by this property, see cascadeOpacityEnabled to change the alpha of nodes.

@property (nonatomic, getter=isCascadeColorEnabled) BOOL cascadeColorEnabled

Declared In

CCNode.h

cascadeOpacityEnabled

CascadeOpacity causes changes to this node’s opacity to cascade down to it’s children. The new opacity is multiplied in with the opacity of each child, so it doesn’t bash the current opacity of those nodes. Color is unaffected by this property, see cascadeColorEnabled for color tint changes.

@property (nonatomic, getter=isCascadeOpacityEnabled) BOOL cascadeOpacityEnabled

Declared In

CCNode.h

children

Array of child nodes.

@property (nonatomic, readonly) NSArray *children

Declared In

CCNode.h

color

Sets and returns the color (tint), alpha is ignored when setting.

@property (nonatomic, strong) CCColor *color

Declared In

CCNode.h

colorRGBA

Sets and returns the color (tint) with alpha.

@property (nonatomic, strong) CCColor *colorRGBA

Declared In

CCNode.h

contentSize

The untransformed size of the node in the unit specified by contentSizeType property. The contentSize remains the same no matter the node is scaled or rotated. contentSize is relative to the node.

@property (nonatomic, readwrite, assign) CGSize contentSize

Declared In

CCNode.h

contentSizeInPoints

The untransformed size of the node in Points. The contentSize remains the same no matter the node is scaled or rotated. contentSizeInPoints is affected by the contentSizeType and will be scaled by the [CCDirector sharedDirector].UIScaleFactor if the type is CCSizeUnitUIPoints.

@property (nonatomic, readwrite, assign) CGSize contentSizeInPoints

Declared In

CCNode.h

contentSizeType

Defines the contentSize type used for the widht and height component of the contentSize property.

@property (nonatomic, readwrite, assign) CCSizeType contentSizeType

Declared In

CCNode.h

displayedColor

Returns the displayed color.

@property (nonatomic, readonly) CCColor *displayedColor

Declared In

CCNode.h

displayedOpacity

Returns the displayed opacity.

@property (nonatomic, readonly) CGFloat displayedOpacity

Declared In

CCNode.h

name

A name tag used to help identify the node easily.

@property (nonatomic, strong) NSString *name

Declared In

CCNode.h

opacity

Sets and returns the opacity.

@property (nonatomic) CGFloat opacity

Discussion

Warning: If the the texture has premultiplied alpha then, the R, G and B channels will be modified. Values goes from 0 to 1, where 1 means fully opaque.

Declared In

CCNode.h

parent

A weak reference to the parent.

@property (nonatomic, readwrite, unsafe_unretained) CCNode *parent

Declared In

CCNode.h

paused

If paused, no callbacks will be called, and no actions will be run.

@property (nonatomic, assign) BOOL paused

Declared In

CCNode.h

physicsBody

The physics body (if any) that this node is attached to.

@property (nonatomic, strong) CCPhysicsBody *physicsBody

Declared In

CCNode.h

position

Position (x,y) of the node in the unit specified by the positionType property. The distance is measured from one of the corners of the node’s parent container, which corner is specified by the positionType property. Default setting is referencing the bottom left corner in points.

@property (nonatomic, readwrite, assign) CGPoint position

Declared In

CCNode.h

positionInPoints

Position (x,y) of the node in points from the bottom left corner.

@property (nonatomic, readwrite, assign) CGPoint positionInPoints

Declared In

CCNode.h

positionType

Defines the position type used for the position property. Changing the position type affects the meaning of the position, and allows you to change the referenceCorner, relative to the parent container. It allso allows changing from points to UIPoints. UIPoints are scaled by [CCDirector sharedDirector].UIScaleFactor. See “Coordinate System and Positioning” for more information.

@property (nonatomic, readwrite, assign) CCPositionType positionType

Declared In

CCNode.h

rotation

The rotation (angle) of the node in degrees. 0 is the default rotation angle. Positive values rotate node CW.

@property (nonatomic, readwrite, assign) float rotation

Declared In

CCNode.h

rotationalSkewX

The rotation (angle) of the node in degrees. 0 is the default rotation angle. Positive values rotate node CW. It only modifies the X rotation performing a horizontal rotational skew.

@property (nonatomic, readwrite, assign) float rotationalSkewX

Declared In

CCNode.h

rotationalSkewY

The rotation (angle) of the node in degrees. 0 is the default rotation angle. Positive values rotate node CW. It only modifies the Y rotation performing a vertical rotational skew.

@property (nonatomic, readwrite, assign) float rotationalSkewY

Declared In

CCNode.h

runningInActiveScene

Returns YES if the node is added to an active scene and neither it nor any of it’s ancestors is paused.

@property (nonatomic, readonly, getter=isRunningInActiveScene) BOOL runningInActiveScene

Declared In

CCNode.h

scale

The scale factor of the node. 1.0 is the default scale factor. It modifies the X and Y scale at the same time.

@property (nonatomic, readwrite, assign) float scale

Declared In

CCNode.h

scaleInPoints

The scaleInPoints is the scale factor of the node in both X and Y, measured in points. The scaleType indicates if the scaleInPoints will be scaled byt the UIScaleFactor or not. See “Coordinate System and Positioning” for more information.

@property (nonatomic, readonly) float scaleInPoints

Declared In

CCNode.h

scaleType

The scaleType defines scale behavior for this node. CCScaleTypeScaled indicates that the node will be scaled by [CCDirector sharedDirector].UIScaleFactor. This property is analagous to positionType. ScaleType affects the scaleInPoints of a CCNode. See “Coordinate System and Positioning” for more information.

@property (nonatomic, assign) CCScaleType scaleType

Declared In

CCNode.h

scaleX

The scale factor of the node. 1.0 is the default scale factor. It only modifies the X scale factor.

@property (nonatomic, readwrite, assign) float scaleX

Declared In

CCNode.h

scaleXInPoints

The scaleInPoints is the scale factor of the node in X, measured in points.

@property (nonatomic, readonly) float scaleXInPoints

Declared In

CCNode.h

scaleY

The scale factor of the node. 1.0 is the default scale factor. It only modifies the Y scale factor.

@property (nonatomic, readwrite, assign) float scaleY

Declared In

CCNode.h

scaleYInPoints

The scaleInPoints is the scale factor of the node in Y, measured in points.

@property (nonatomic, readonly) float scaleYInPoints

Declared In

CCNode.h

scene

The scene this node is added to, or nil if it’s not part of a scene.

@property (nonatomic, readonly) CCScene *scene

Declared In

CCNode.h

skewX

The X skew angle of the node in degrees. This angle describes the shear distortion in the X direction. Thus, it is the angle between the Y axis and the left edge of the shape The default skewX angle is 0. Positive values distort the node in a CW direction.

@property (nonatomic, readwrite, assign) float skewX

Declared In

CCNode.h

skewY

The Y skew angle of the node in degrees. This angle describes the shear distortion in the Y direction. Thus, it is the angle between the X axis and the bottom edge of the shape The default skewY angle is 0. Positive values distort the node in a CCW direction.

@property (nonatomic, readwrite, assign) float skewY

Declared In

CCNode.h

userObject

Similar to userData, but instead of holding a void* it holds an id.

@property (nonatomic, readwrite, strong) id userObject

Declared In

CCNode.h

visible

Whether of not the node is visible. Default is YES.

@property (nonatomic, readwrite, assign) BOOL visible

Declared In

CCNode.h

zOrder

The z order of the node relative to its “siblings”: children of the same parent.

@property (nonatomic, assign) NSInteger zOrder

Declared In

CCNode.h

Class Methods

node

Allocates and initializes a node. The node will be created as “autorelease”.

+ (id)node

Declared In

CCNode.h

Instance Methods

addChild:

Adds a child to the container with z-order as 0. If the child is added to a ‘running’ node, then ‘onEnter’ and ‘onEnterTransitionDidFinish’ will be called immediately.

- (void)addChild:(CCNode *)node

Parameters

node

CCNode to add as a child.

Declared In

CCNode.h

addChild:z:

Adds a child to the container with a z-order. If the child is added to a ‘running’ node, then ‘onEnter’ and ‘onEnterTransitionDidFinish’ will be called immediately.

- (void)addChild:(CCNode *)node z:(NSInteger)z

Parameters

node

CCNode to add as a child.

z

Z depth of node.

Declared In

CCNode.h

addChild:z:name:

Adds a child to the container with z order and tag. If the child is added to a ‘running’ node, then ‘onEnter’ and ‘onEnterTransitionDidFinish’ will be called immediately.

- (void)addChild:(CCNode *)node z:(NSInteger)z name:(NSString *)name

Parameters

node

CCNode to add as a child.

z

Z depth of node.

name

name tag.

Declared In

CCNode.h

boundingBox

Returns a “local” axis aligned bounding box of the node in points. The returned box is relative only to its parent. The returned box is in Points.

- (CGRect)boundingBox

Declared In

CCNode.h

convertToNodeSpace:

Converts a Point to node (local) space coordinates. The result is in Points.

- (CGPoint)convertToNodeSpace:(CGPoint)worldPoint

Parameters

worldPoint

World position in points.

Return Value

Local position in points.

Declared In

CCNode.h

convertToNodeSpaceAR:

Converts a Point to node (local) space coordinates. The result is in Points. Treats the returned/received node point as anchor relative.

- (CGPoint)convertToNodeSpaceAR:(CGPoint)worldPoint

Parameters

worldPoint

World position in points.

Return Value

Local position in points.

Declared In

CCNode.h

convertToWorldSpace:

Converts a Point to world space coordinates. The result is in Points.

- (CGPoint)convertToWorldSpace:(CGPoint)nodePoint

Parameters

nodePoint

Local position in points.

Return Value

World position in points.

Declared In

CCNode.h

convertToWorldSpaceAR:

Converts a local Point to world space coordinates.The result is in Points. Treats the returned/received node point as anchor relative.

- (CGPoint)convertToWorldSpaceAR:(CGPoint)nodePoint

Parameters

nodePoint

Local position in points.

Return Value

World position in points.

Declared In

CCNode.h

doesOpacityModifyRGB

Returns whether or not the opacity will be applied using glColor(R,G,B,opacity) or glColor(opacity, opacity, opacity, opacity).

- (BOOL)doesOpacityModifyRGB

Declared In

CCNode.h

draw:transform:

Override this method to draw your own node. You should use cocos2d’s GL API to enable/disable the GL state / shaders. For further info, please see ccGLstate.h. You shall NOT call [super draw];

- (void)draw:(CCRenderer *)renderer transform:(const GLKMatrix4 *)transform

Declared In

CCNode.h

getActionByTag:

Gets an action from the running action list given its tag.

- (CCAction *)getActionByTag:(NSInteger)tag

Parameters

tag

Tag to retrieve.

Return Value

the Action the with the given tag.

Declared In

CCNode.h

getChildByName:recursively:

Search through the children of the container for one matching the name tag. If recursive, it returns the first matching node, via a depth first search. Otherwise, only immediate children are checked.

- (CCNode *)getChildByName:(NSString *)name recursively:(bool)isRecursive

Parameters

name

Name tag.

isRecursive

Search recursively through children of children.

Return Value

Returns a CCNode, or nil if no marching nodes are found.

Declared In

CCNode.h

init

Initializes the node.

- (id)init

Declared In

CCNode.h

nodeToParentTransform

Returns the matrix that transform the node’s (local) space coordinates into the parent’s space coordinates. The matrix is in Pixels.

- (CGAffineTransform)nodeToParentTransform

Declared In

CCNode.h

nodeToWorldTransform

Returns the world affine transform matrix. The matrix is in Pixels.

- (CGAffineTransform)nodeToWorldTransform

Declared In

CCNode.h

numberOfRunningActions

Returns the numbers of actions that are running plus the ones that are schedule to run (actions in actionsToAdd and actions arrays). Composable actions are counted as 1 action. Example: If you are running 1 Sequence of 7 actions, it will return 1. If you are running 7 Sequences of 2 actions, it will return 7.

- (NSUInteger)numberOfRunningActions

Declared In

CCNode.h

onEnter

Event that is called every time the CCNode enters the ‘stage’. If the CCNode enters the ‘stage’ with a transition, this event is called when the transition starts. During onEnter you can’t access a sibling node. If you override onEnter, you shall call [super onEnter].

- (void)onEnter

Declared In

CCNode.h

onEnterTransitionDidFinish

Event that is called when the CCNode enters in the ‘stage’. If the CCNode enters the ‘stage’ with a transition, this event is called when the transition finishes. If you override onEnterTransitionDidFinish, you shall call [super onEnterTransitionDidFinish].

- (void)onEnterTransitionDidFinish

Declared In

CCNode.h

onExit

Event that is called every time the CCNode leaves the ‘stage’. If the CCNode leaves the ‘stage’ with a transition, this event is called when the transition finishes. During onExit you can’t access a sibling node. If you override onExit, you shall call [super onExit].

- (void)onExit

Declared In

CCNode.h

onExitTransitionDidStart

Callback that is called every time the CCNode leaves the ‘stage’. If the CCNode leaves the ‘stage’ with a transition, this callback is called when the transition starts.

- (void)onExitTransitionDidStart

Declared In

CCNode.h

parentToNodeTransform

Returns the matrix that transform parent’s space coordinates to the node’s (local) space coordinates. The matrix is in Pixels.

- (CGAffineTransform)parentToNodeTransform

Declared In

CCNode.h

physicsNode

Nearest CCPhysicsNode ancestor of this node, or nil if none. Unlike CCPhysicsBody.physicsNode, this will return a value before onEnter is called on the node.

- (CCPhysicsNode *)physicsNode

Declared In

CCPhysicsNode.h

removeAllChildren

Removes all children from the container forcing a cleanup.

- (void)removeAllChildren

Declared In

CCNode.h

removeAllChildrenWithCleanup:

Removes all children from the container and do a cleanup all running actions depending on the cleanup parameter.

- (void)removeAllChildrenWithCleanup:(BOOL)cleanup

Parameters

cleanup

Stops all scheduled events and actions.

Declared In

CCNode.h

removeChild:

Removes a child from the container forcing a cleanup. This method checks to ensure the parameter node is actually a child of this node.

- (void)removeChild:(CCNode *)child

Parameters

child

The child node to remove.

Declared In

CCNode.h

removeChild:cleanup:

Removes a child from the container. It will also cleanup all running and scheduled actions depending on the cleanup parameter. This method checks to ensure the parameter node is actually a child of this node.

- (void)removeChild:(CCNode *)node cleanup:(BOOL)cleanup

Parameters

node

The child node to remove.

cleanup

Stops all scheduled events and actions.

Declared In

CCNode.h

removeChildByName:

Removes a child from the container by name value forcing a cleanup.

- (void)removeChildByName:(NSString *)name

Parameters

name

Name of node to be removed.

Declared In

CCNode.h

removeChildByName:cleanup:

Removes a child from the container by name value. It will also cleanup all running actions depending on the cleanup parameter

- (void)removeChildByName:(NSString *)name cleanup:(BOOL)cleanup

Parameters

name

Name of node to be removed.

cleanup

Stops all scheduled events and actions.

Declared In

CCNode.h

removeFromParent

Remove itself from its parent node forcing a cleanup. If the node orphan, then nothing happens.

- (void)removeFromParent

Declared In

CCNode.h

removeFromParentAndCleanup:

Remove itself from its parent node. If cleanup is YES, then also remove all actions and callbacks. If the node orphan, then nothing happens.

- (void)removeFromParentAndCleanup:(BOOL)cleanup

Parameters

cleanup

Stops all scheduled events and actions.

Declared In

CCNode.h

runAction:

Executes an action, and returns the action that is executed. The node becomes the action’s target.

- (CCAction *)runAction:(CCAction *)action

Parameters

action

Action to run.

Return Value

An Action pointer

Declared In

CCNode.h

schedule:interval:

Schedules a custom selector with an interval time in seconds. If time is 0 it will be ticked every frame. In that case, it is recommended to override update: in stead. If the selector is already scheduled, then the interval parameter will be updated without scheduling it again.

- (CCTimer *)schedule:(SEL)s interval:(CCTime)seconds

Parameters

s

Selector to execute.

seconds

Interval between execution in seconds.

Return Value

A newly initialized CCTimer object.

Declared In

CCNode.h

schedule:interval:repeat:delay:

Schedules a custom selector with an interval time in seconds.

- (CCTimer *)schedule:(SEL)selector interval:(CCTime)interval repeat:(NSUInteger)repeat delay:(CCTime)delay

Parameters

selector

Selector to execute.

interval

Interval between execution in seconds.

repeat

Number of times to repeat.

delay

Initial delay in seconds.

Return Value

A newly initialized CCTimer object.

Declared In

CCNode.h

scheduleBlock:delay:

Schedules a block to run once, after a certain delay.

- (CCTimer *)scheduleBlock:(CCTimerBlock)block delay:(CCTime)delay

Parameters

block

Block to execute.

delay

Delay in seconds.

Return Value

A newly initialized CCTimer object.

Declared In

CCNode.h

scheduleOnce:delay:

Schedules a selector that runs only once, with a delay of 0 or larger.

- (CCTimer *)scheduleOnce:(SEL)selector delay:(CCTime)delay

Parameters

selector

Selector to execute.

delay

Initial delay in seconds.

Return Value

A newly initialized CCTimer object.

Declared In

CCNode.h

setOpacityModifyRGB:

Sets the premultipliedAlphaOpacity property.

- (void)setOpacityModifyRGB:(BOOL)boolean

Parameters

boolean

Enables or disables setting of opacity with color.

Discussion

If set to NO then opacity will be applied as: glColor(R,G,B,opacity);

If set to YES then opacity will be applied as: glColor(opacity, opacity, opacity, opacity );

Textures with premultiplied alpha will have this property by default on YES. Otherwise the default value is NO.

Declared In

CCNode.h

stopAction:

Removes an action from the running action list.

- (void)stopAction:(CCAction *)action

Parameters

action

Action to remove.

Declared In

CCNode.h

stopActionByTag:

Removes an action from the running action list given its tag.

- (void)stopActionByTag:(NSInteger)tag

Parameters

tag

Tag to remove.

Declared In

CCNode.h

stopAllActions

Removes all actions from the running action list

- (void)stopAllActions

Declared In

CCNode.h

transform:

Returns the 4x4 drawing transformation for this node. Really only useful when overriding visit:parentTransform:

- (GLKMatrix4)transform:(const GLKMatrix4 *)parentTransform

Declared In

CCNode.h

unschedule:

Unschedule a scheduled selector.

- (void)unschedule:(SEL)selector

Parameters

selector

Selector to unschedule.

Declared In

CCNode.h

unscheduleAllSelectors

Unschedule all scheduled selectors.

- (void)unscheduleAllSelectors

Declared In

CCNode.h

updateDisplayedColor:

Recursive method that updates display color.

- (void)updateDisplayedColor:(ccColor4F)color

Parameters

color

Color used for update.

Declared In

CCNode.h

updateDisplayedOpacity:

Recursive method that updates the displayed opacity.

- (void)updateDisplayedOpacity:(CGFloat)opacity

Parameters

opacity

Opacity to use for update.

Declared In

CCNode.h

viewDidResizeTo:

Invoked automatically when the OS view has been resized.

- (void)viewDidResizeTo:(CGSize)newViewSize

Discussion

This implementation simply propagates the same method to the children. Subclasses may override to actually do something when the view resizes.

Declared In

CCNode.h

visit

Calls visit:parentTransform using the current renderer and projection.

- (void)visit

Declared In

CCNode.h

visit:parentTransform:

Recursive method that visit its children and draw them.

- (void)visit:(CCRenderer *)renderer parentTransform:(const GLKMatrix4 *)parentTransform

Declared In

CCNode.h

walkSceneGraph:

Prints on the debug console the scene graph

- (void)walkSceneGraph:(NSUInteger)level

Parameters

level

Level of debug information.

Declared In

CCNode+Debug.h

worldToNodeTransform

Returns the inverse world affine transform matrix. The matrix is in Pixels.

- (CGAffineTransform)worldToNodeTransform

Declared In

CCNode.h