cc.node.Node

cc.node.Node

As said on the node introduction cc.node.Node is the base object node in Cocos. V4 implementation is fully rewritten, but keeps a backwards compatible API as well as bring in some additions.

Transformation

The node object manages position, rotation and scale to draw itself on the screen. The following methods handle a Node's visual appearance. The visual properties apply from parent-to-children nodes.

• setContentSize( width, height )
• setPosition( x, y )
• setRotation( angle_in_degrees )
• setScale(x, [optional] y)
• setScaleX
• setScaleY
• setPositionAnchor( x, y )
• setTransformationAnchor( x, y )
• setAnchorPoint : sets both position and transformation anchors to the same point.
• setVisible( bool )

Appearance

A node can control its visual appearance with some feature. The following methods control transparency. Transparency can propagate to children by calling setGlobalAlpha in a Node.

• setOpacity( value_0_255 )
• setAlpha( normalized_value_0_1 )
• setGlobalAlpha( bool )

An important feature in V4 is that a node has a color, tinting and blending capabilities. For a base node, the Color is the fill color itself, but for a Sprite, the color is tint image color. These operations are controlled by the methods:

• setCompositeOperation( number ) // the number is an enumeration: cc.render.CompositeOperation
• setColor( r,g,b ) // normalized color components

Input

Nodes can have input routed to them, in a rich variety of different events for touch, mouse, multitouch, etc. Events can be enabled or disabled at will for a given node. It must explicitly enabled though. Input is controlled by a common Javascript idiom:

• addEventListener( event, callback )
• enableEvents( bool )
• enablePriorityEvents( enable:bool, priority:number )

Input will be routed to Nodes first for nodes that have input enabled with priority, and then, in an in-order traversal of the scene-graph order generated tree by calling enableEvents.

A Node can register interest for the following events:

• Mouse: mouseover, mouseout, mousedown, mouseup, mousemove, mousedrag, mouseclick, doubleclick.
• Touch: touchover, touchout, touchstart, touchmove, touchend.

The way for event callback registering will be:

/**
 *
 * @param event {string} a event name.
 * @param callback {function( e:{cc.event.MouseInputManagerEvent} )=>boolean} 
 *   a function that receives a MouseInputManagerEvent object and returns 
 *   a boolean. If returns true, the events is expected to propagate to 
 *   the next Node in the hierarchy (either priority or SceneGraphTree).  
 */
node.addEventListener( event, callback );

The events touchover and touchout, are Cocos2d specific. They are sent to nodes when there's an active touch event and it hovers a Node.

Naming and tagging

Naming and tagging is important for Node identification. These are the available methods:

• setName( name:string )
• setTag( tag:object )

Children management

Cocos2d is a scene graph and as such a Node can contain other Nodes. Children nodes are automatically kept sorted based on a z-index value which can be passed to some methods. Negative z-index values put nodes in-front of the children list. By default, a value of zero is set. Nodes sharing a z-index value will be sorted by creation time. Since Nodes can have actions and tasks associated with them, removing a child node is a tricky operation. For such, some methods have a cleanup flag, which will remove actions and tasks as well. Why is this optional ? Maybe you only want to connect a Node to another parent Node and not loss its actions. In V4 a new method: enumerateChildren has been added. This method traverses a Node matching Nodes names to a pattern which if passes, invokes the callback. The pattern can be recursive and have directory like traversal options.

The following methods handle children for a Node:

• addChild( node, [optional] localZOrder, [optional] tag )
• reorderChild( node, localZOrder )
• removeChild( node, [optional] cleanup )
• removeFromParent( [optional] cleanup )
• removeAllChildren()
• getChildren() => Array<Node>
• getRootNode()
• enumerateChildren( patternName:string, callback:EnumerateCallback )

Coordinate system

Every scene graph makes each Node to be considered an isolated coordinate system. This makes that regardless the transformation applied to a Node and its parents, the draw function act as if everything is axis aligned and positioned in 0,0 (basically abstracts you from the burden of maths). In this scenario, Cocos2d offers you methods to change values among different coordinate systems. These methods control such operations:

• getScreenPointInLocalSpace( point )
• calculateBoundingBox() // value will be stored in Node's _BBVertices and _AABB properties.
• isScreenPointInNode( point ) => bool

Actions

Actions change an arbitrary object's (or Node's) properties in a timely manner. These methods manage scheduling actions to a Node:

• startActionChain() // enables action chaining.
• runAction( action )
• stopActionByTag( tag )
• stopAllActions()

Scheduling Tasks

A node can schedule a period call to its update method. This method will receive the elapsed time between consecutive calls. It can be scheduled normally, or with priority, so that a given Node's update method can be called before others. Update method scheduler is managed by the methods:

• update( delta:number )
• scheduleUpdateWithPriority( priority : number )
• scheduleUpdate()
• unscheduleUpate()

Additionally, other tasks can be executed on the scheduler and bound to a Node. These method manage such features:

• schedule( callback_fn:SchedulerTaskCallback, interval:number, repeat:number=, delay:number= )
• scheduleOnce(callback_fn:SchedulerTaskCallback, delay:number)
• unschedule(callback_fn:SchedulerTaskCallback)
• unscheduleAllCallbacks()

The scheduled tasks can be paused and resumed too:

• pause()
• resume()

Drawing

All nodes have visual drawing capabilities. While the base Node type only draws a rectangle filled with the color set by calling setColor. It is important to note the draw method receives a RenderingContext object though which allows advanced drawing capabilities per Node. The RenderingContext is implemented in Canvas and WebGL and offers consistent rendering between both technologies. Building new types of Nodes will mostly be a matter of overriding the draw method:

• draw( ctx:RenderingContext )