# 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:
    - They can contain other `CocosNode` (`add()`, `get()`, `remove()`, etc)
    - They can schedule periodic callback (`schedule()`, `schedule_interval()`, etc)
    - They can execute actions (`do()`, `pause()`, `stop()`, etc)

  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: | Vector2 – `p` vector converted to local coordinates.

  `point_to_world`(p)

    Returns an `euclid.Vector2` converted to world space.

    Parameters: | p (Vector2) – Vector to convert
    Returns: | Vector2 – `p` 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