cocos.cocosnode module

CocosNode: the basic element of cocos2d

class CocosNode

Bases: object

Cocosnode is the main element. Anything that gets drawn or contains things that gets drawn is a CocosNode. The most popular CocosNode are cocos.scene.Scene, cocos.layer.base_layers.Layer and cocos.sprite.Sprite.

The main features of a CocosNode are:

Some CocosNode provide extra functionality for them or their children.

Subclassing a CocosNode usually means (one/all) of:
  • overriding __init__ to initialize resources and schedule callbacks
  • create callbacks to handle the advancement of time
  • overriding draw() to render the node
add(child, z=0, name=None)

Adds a child and if it becomes part of the active scene, it calls its on_enter() method.

Parameters:
  • child (CocosNode) – object to be added
  • z (Optional[float]) – the child z index. Defaults to 0.
  • name (Optional[str]) – Name of the child. Defaults to None
Returns:

CocosNode – self

are_actions_running()

Determine whether any actions are running.

do(action, target=None)

Executes an Action. When the action is finished, it will be removed from the node’s actions container.

To remove an action you must use the do() return value to call remove_action().

Parameters:action (Action) – Action that will be executed.
Returns:Action – A clone of action
draw(*args, **kwargs)

This is the function you will have to override if you want your subclassed CocosNode to draw something on screen.

You must respect the position, scale, rotation and anchor attributes. If you want OpenGL to do the scaling for you, you can:

def draw(self):
    glPushMatrix()
    self.transform()
    # ... draw ..
    glPopMatrix()
get(name)

Gets a child given its name.

Parameters:name (str) – name of the reference to retrieve.
Returns:CocosNode – The child named ‘name’. Will raise an Exception if not present.

Warning

If a node is added with name, then removing it differently than by name will prevent the name to be recycled: attempting to add another node with this name will produce an Exception.

get_ancestor(klass)

Walks the nodes tree upwards until it finds a node of the class klass or returns None.

Returns:CocosNode or None
get_children()

Return a list with the node’s children, order is back to front.

Returns:list[CocosNode] – children of this node, ordered back to front.
get_local_inverse()

Returns an euclid.Matrix3 with the local inverse transformation matrix.

Returns:euclid.Matrix3
get_local_transform()

Returns an euclid.Matrix3 with the local transformation matrix

Returns:euclid.Matrix3
get_world_inverse()

returns an euclid.Matrix3 with the world inverse transformation matrix.

Returns:euclid.Matrix3
get_world_transform()

Returns an euclid.Matrix3 with the world transformation matrix

Returns:euclid.Matrix3
kill()

Remove this object from its parent, and thus most likely from everything.

on_enter()

Called every time just before the node enters the stage.

Scheduled calls and worker actions begin or continue to perform.

Good point to do push_handlers() if you have custom ones

Note

A handler pushed there is near certain to require a pop_handlers() in the on_exit() method (else it will be called even after being removed from the active scene, or if going on stage again it will be called multiple times for each event ocurrences).

on_exit()

Called every time just before the node leaves the stage.

Scheduled calls and worker actions are suspended, that is, they will not be called until an on_enter() event happens.

Most of the time you will want to pop_handlers() for all explicit push_handlers() found in meth:on_enter.

Consider to release here openGL resources created by this node, like compiled vertex lists.

pause()

Suspends the execution of actions.

pause_scheduler()

Time will stop for this node: scheduled callbacks will not be called, worker actions will not be called.

point_to_local(p)

returns an euclid.Vector2 converted to local space.

Parameters:p (Vector2) – Vector to convert.
Returns:Vector2p vector converted to local coordinates.
point_to_world(p)

Returns an euclid.Vector2 converted to world space.

Parameters:p (Vector2) – Vector to convert
Returns:Vector2p vector converted to world coordinates.
remove(obj)

Removes a child given its name or object

If the node was added with name, it is better to remove by name, else the name will be unavailable for further adds (and will raise an Exception if add with this same name is attempted)

If the node was part of the active scene, its on_exit() method will be called.

Parameters:obj (str or object) – Name of the reference to be removed or object to be removed.
remove_action(action)

Removes an action from the node actions container, potentially calling action.stop().

If action was running, Action.stop() is called. Mandatory interface to remove actions in the node actions container. When skipping this there is the posibility to double call the action.stop

Parameters:action (Action) – Action to be removed. Must be the return value for a do() call
resume()

Resumes the execution of actions.

resume_scheduler()

Time will continue/start passing for this node and callbacks will be called, worker actions will be called.

schedule(callback, *args, **kwargs)

Schedule a function to be called every frame.

The function should have a prototype that includes dt as the first argument, which gives the elapsed time, in seconds, since the last clock tick. Any additional arguments given to this function are passed on to the callback:

def callback(dt, *args, **kwargs):
    pass

This function is a wrapper to pyglet.clock.schedule. It has the additional benefit that all calllbacks are paused and resumed when the node leaves or enters a scene.

You should not have to schedule things using pyglet by yourself.

Parameters:
  • callback (a function) – The function to call each frame.
  • *args – Variable length argument list passed to the callback.
  • **kwargs – Arbitrary keyword arguments passed to the callback.
schedule_interval(callback, interval, *args, **kwargs)

Schedule a function to be called every interval seconds.

Specifying an interval of 0 prevents the function from being called again (see schedule() to call a function as often as possible).

The callback function prototype is the same as for schedule().

This function is a wrapper to pyglet.clock.schedule_interval. It has the additional benefit that all calllbacks are paused and resumed when the node leaves or enters a scene.

You should not have to schedule things using pyglet by yourself.

Parameters:
  • callback (a function) – The function to call when the timer elapsed.
  • interval (float) – The number of seconds to wait between each call.
  • *args – Variable length argument list passed to the callback.
  • **kwargs – Arbitrary keyword arguments passed to the callback.
stop()

Removes all actions from the running action list.

For each action running, the stop method will be called, and the action will be removed from the actions container.

transform()

Apply ModelView transformations.

You will most likely want to wrap calls to this function with glPushMatrix()/glPopMatrix()

unschedule(callback)

Remove a function from the schedule.

If the function appears in the schedule more than once, all occurances are removed. If the function was not scheduled, no error is raised.

This function is a wrapper to pyglet.clock.unschedule. It has the additional benefit that all calllbacks are paused and resumed when the node leaves or enters a scene.

You should not unschedule things using pyglet that where scheduled by schedule()/schedule_interval().

Parameters:callback (a function) – The function to remove from the schedule.
visit()

This function visits its children in a recursive way.

It will first visit the children that that have a z-order value less than 0.

Then it will call the draw() method to draw itself.

And finally it will visit the rest of the children (the ones with a z-value bigger or equal than 0)

Before visiting any children it will call the transform() method to apply any possible transformations.

walk(callback, collect=None)

Executes callback on all the subtree starting at self. returns a list of all return values that are not None.

Parameters:
  • callback (a function) – Callable that takes a CocosNode as an argument.
  • collect (list) – List of non-None returned values from visited nodes.
Returns:

list – The list of non-None return values.

actions = None

list of Action objects that are running

anchor

Anchor point of the object. Alias for transform_anchor Children will be added at this point and transformations like scaling and rotation will use this point as the center.

anchor_x

Anchor x value for transformations and adding children. Alias for transform_anchor_x

anchor_y

Anchor y value for transformations and adding children. Alias for transform_anchor_y

camera = None

eye, center and up vector for the Camera. gluLookAt() is used with these values. Default: FOV 60, center of the screen.

Note

The camera can perform exactly the same transformation as scale, rotation and the x, y attributes (with the exception that the camera can modify also the z-coordinate) In fact, they all transform the same matrix, so use either the camera or the other attributes, but not both since the camera will be overridden by the transformations done by the other attributes.

You can change the camera manually or by using the Camera3DAction action.

children = None

list of (int, child-reference) where int is the z-order, sorted by ascending z (back to front order)

children_names = None

dictionary that maps children names with children references

grid = None

the grid object for the grid actions. This can be a Grid3D or a TiledGrid3D object depending on the action.

is_running = None

whether of not the object is running

parent

The parent of this object.

Returns:CocosNode or None
position

The (x, y) coordinates of the object.

Type:tuple[int, int]
rotation

The rotation of this object in degrees. Defaults to 0.0.

Type:float
scale

The scaling factor of the object.

Type:float
scale_x

The scale x of this object.

Type:float
scale_y

The scale y of this object.

Type:float
scheduled_calls = None

list of scheduled callbacks

scheduled_interval_calls = None

list of scheduled interval callbacks

skip_frame = None

whether or not the next frame will be skipped

to_remove = None

list of Action objects to be removed

transform_anchor

Transformation anchor point. Children will be added at this point and transformations like scaling and rotation will use this point as its center.

transform_anchor_x = None

offset from (x,0) from where rotation and scale will be applied. Default: 0

transform_anchor_y = None

offset from (0,y) from where rotation and scale will be applied. Default: 0

visible = None

whether of not the object and his childrens are visible. Default: True

x

The x coordinate of the CocosNode

y

The y coordinate of the CocosNode