# cocos.cocosnode module

CocosNode: the basic element of cocos2d

class `CocosNode`

  Bases: `object`

  Cocosnode is the main element. Anything thats gets drawn or contains things that get drawn is a cocosnode. The most popular cocosnodes are scenes, layers and sprites.

  The main features of a cocosnode are:
    - They can contain other cocos nodes (add, get, remove, etc)
    - They can schedule periodic callback (schedule, schedule_interval, etc)
    - They can execute actions (do, pause, stop, etc)

  Some cocosnodes provide extra functionality for them or their children.

  Subclassing a cocosnode usually means (one/all) of:
    - overriding __init__ to initialize resources and schedule calbacks
    - 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 calls its on_enter method

    Parameters: | child : CocosNode object to be added z : float the z index of self name : str Name of the child
    Return type: | CocosNode instance
    Returns: | self

  `are_actions_running`()

    Determine whether any actions are running.

  `do`(action, target=None)

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

    Parameters: | action : an Action instance Action that will be executed.
    Return type: | Action instance
    Returns: | A clone of action

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

  `draw`(*args, **kwargs)

    This is the function you will have to override if you want your subclassed 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 : string name of the reference to be get
    Return type: | CocosNode
    Returns: | the child named ‘name’. Will raise Exception if not present

    Warning: if a node is added with name, then removed not by name, the name cannot be recycled: attempting to add other 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

    Return type: | CocosNode or None

  `get_children`()

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

    Return type: | list of CocosNode
    Returns: | childs of this node, ordered back to front

  `get_local_inverse`()

    returns an euclid.Matrix3 with the local inverse transformation matrix

    Return type: | euclid.Matrix3

  `get_local_transform`()

    returns an euclid.Matrix3 with the local transformation matrix

    Return type: | euclid.Matrix3

  `get_world_inverse`()

    returns an euclid.Matrix3 with the world inverse transformation matrix

    Return type: | euclid.Matrix3

  `get_world_transform`()

    returns an euclid.Matrix3 with the world transformation matrix

    Return type: | 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 begins or continues to perform

    Good point to do .push_handlers if you have custom ones Rule: a handler pushed there is near certain to require a .pop_handlers in the .on_exit method (else it will be called even after removed from the active scene, or, if going on stage again will be called multiple times for each event ocurrence)

  `on_exit`()

    Called every time just before the node leaves the stage

    scheduled calls and worker actions are suspended, that is, 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 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 passing 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

    Return type: | euclid.Vector2

  `point_to_world`(p)

    returns an euclid.Vector2 converted to world space

    Return type: | euclid.Vector2

  `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 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 : string 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 interfase 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

    Parameters: | callback : function The function to call each frame.

    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.

  `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.

    Parameters: | callback : function The function to call when the timer lapses. interval : float The number of seconds to wait between each call.

    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.

  `stop`()

    Removes all actions from the running action list

    For each action running the stop method will be called, and the action will be retired 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.

    Parameters: | callback : function The function to remove from the schedule.

    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 node.schedule/node.schedule_interface.

  `visit`()

    This function visits it’s 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 transformation.

  `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 : function callable, takes a cocosnode as argument collect : list list of visited nodes
    Return type: | list
    Returns: | the list of not-none return values

  `actions` = None

    list of Action objects that are running

  `anchor`

    Anchor point of the object. 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

  `anchor_y`

    Anchor y value for transformations and adding children

  `camera` = None

    eye, center and up vector for the Camera. gluLookAt() is used with these values. Default: FOV 60, center of the screen. IMPORTANT: 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.

    Type: | object

  `position`

    The (x, y) coordinates of the object.

    Type: | (int, int)

  `rotation`
  `scale`
  `scale_x`
  `scale_y`
  `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. Transformations like scaling and rotation will use this point as it’s 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 object

  `y`

    The y coordinate of the object