# Brief tour of built-in CocosNode subclasses

# Scene

The root of the tree depicting the full content to be displayed. To change between scenes you use director.

# TransitionScene

TransitionScene

Base class to implement a gradual change from one screen (scene) to other. Typical examples are fade in and fade out.

Cocos provides a bunch of ready made scene transitions (sample code in test/test_transition_*.py)

# Layer

Layer

Helps to organize the view in the depth axis. Subclasses often offer specialized services to the childs (like ScrollingManager), and can be used to build higher order functionality (like Menu)

# ColorLayer

ColorLayer

The primary use is to provide a solid color background to a scene, also used to draw solid color rectangles.

# MultiplexLayer

MultiplexLayer

Allows to show only one of his childs, and to select which one. An use case is when you want to show one of a number of menus.

# ScrollingManager

ScrollingManager

Coordinates a number of ScrollableLayer to do scroll and parallax so that the scroll don't goes out of the the world.

# ScrollableLayer

Used as childs of ScrollingManager, helps to manage scroll limits and parallax. You must set attributes px_with and px_height in a ScrollableLayer instance so restrictions in the scroll are enforced. If using parallax, it must be provided in the constructor.

# RectMapLayer and HexMapLayer

A tilemap is a world description where
  - the space is partitioned in a regular grid (rectangular or hexagonal in cocos)
  - it is known which associated image and game properties has each cell in the grid.

RectMapLayer and HexMapLayer are usually created by tiles.load, and they care to display the world and give access to the cells properties.

Examples are test/test_tiles.py and test/test_platformer.py

# InterpreterLayer

Used by director to show a python console that allows to inspect and modify the objects in the application using director. You don't instantiate manually an InterpreterLayer, simply press ctrl + i (cmd + i on mac) to toggle the layer's visibility.

# Sprite

Sprite

Sprites allows to display an image in a rectangular area, which can be rotated, scaled and moved.

## Animating a sprite

Animation as in cartoon style animation, that is, replacing the image fast enough to give the illusion of movement, can be accomplished by:

- using an animated .gif file as source for the image
- passing a pyglet.image.Animation as image, which collects a number of images
- have an array of images and let your code assign to the sprite image member

## Performance Considerations

Sprites are not suitable for effects that piles a lot of semitransparent images to render things like smoke or poisoning fog. Use particle systems or custom CocosNode s managing vertex lists for that.

If your scene has less than 25 sprites, you can add directly to the scene, like:

    class TLayer(cocos.layer.Layer):
        is_event_handler = True
        def __init__(self):
            cocos.layer.Layer.__init__(self)
            world_width, world_height = director.get_window_size()
            rand_color = [255, 0, 0]
            icolor = 0
            for i in range(qty_balls):
                ball = Ball((world_width*random.random(), world_height*random.random()), color=rand_color)
                rand_color[icolor] = random.randint(50, 255)
                icolor = (icolor + 1)%len(rand_color)
                self.add(ball)
    self.time = 0.0
    self.schedule(self.update)

When you have between 25 and 100 visible sprites, moving at each frame, you should add one or more BatchNode s at some level in the scene and add the sprites to them. Even only one batch can give you 4x fps:

    class TLayer(cocos.layer.Layer):
        is_event_handler = True
            def __init__(self):
                cocos.layer.Layer.__init__(self)
                batch = cocos.batch.BatchNode()
                self.add(batch) # we add a batch to the layer ...
                world_width, world_height = director.get_window_size()
                rand_color = [255, 0, 0]
                icolor = 0
                for i in range(100):
                    ball = Ball((world_width*random.random(), world_height*random.random()), color=rand_color)
                    rand_color[icolor] = random.randint(50, 255)
                    icolor = (icolor + 1)%len(rand_color)
                    batch.add(ball) # see ? we add sprites to the batch, not the layer
                self.batch = batch
                self.time = 0.0
                self.schedule(self.update)

With more than 100 visible, moving at each frame sprites, you will need to optimize further to run at 60 fps in weak hardware like netbooks, old desktops, cheap new desktops. You can look at cocos particle systems and the section graphics in pyglet programing guide for ideas.

For a ballpark data point, a 2008 low gamming spec machine (athon 5200, radeon 4650) gives:

    numballs    fps
        250     98
        500     54
        750     36

Notice that sprites out of view has a fraction of the cost that visible sprites: they are discarded at the openGL geometry stage (in most of openGL implementations)

# ParticleSystems

ParticleSystems

Certain effects are best rendered as a big number of translucent, colored images, by example explosions and smoke. Cocos provides the base class ParticleSystems to efficiently render those entities, and some specialized subclasses like Fireworks, Spiral, Meteor, Sun, Fire, Galaxy, Flower, Explosion, Smoke.

The most common method to customize particle systems is to subclass one of the cocos particle systems and modify some of the class members defining its behavior. If you change the particle texture remember to load it with pyglet.image.load, not pyglet.resource.image Of course, deeper customization can be achieved with subclassing and code customization.

Look at test/test_particle_*.py for smaple code.

# TextElement, Label, HTMLLabel, RichLabel

Overall opacity, Family and Font size can be specified for all.

TextElement: base class for all cocos text. Holds internally (member 'element') a suitable pyglet text object, providing the CocosNode interface and pyglet Batch to store parts. Features other than opacity and the common cocosnode ones should be accessed trough the instance.element.

Label: provide the most simple text display; color can also be set.

HTMLLabel: a slightly more powerful label, it can use mixed styles. Uses HTML syntax for text and styles; opacity as a whole can be set.

RichTextLabel: Allows rich text attributes.

Look for examples at test/test_label_*.py, test/test_htmllabel_*.py, test/test_rich_label.py

# Menu

Menu

- Does the layout of menu items
- Handles navigation between menu items
- Passes to the items the desired animation to play when the focus changes from one to another item

Look for examples at test/test_menu_*.py

# Menu items

MenuItem: A menu item that shows text

ImageMenuItem: A menu item that shows a image and optionally text

MultipleMenuItem: Allows to cycle trough a customizable list of options

ToggleMenuItem: Exposes a on/off selection

EntryMenuItem: Exposes a label and a text entry field

ColorMenuItem: Allows to select a color

Look at test/test_menu_items.py for sample code.

# Creating your CocosNode subclasses

TODO: explain how to build custom cocosnode objects, how to use transform , etc.