The root of the tree depicting the full content to be displayed. To change between scenes you use director.
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)
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)
The primary use is to provide a solid color background to a scene, also used to draw solid color rectangles.
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.
Coordinates a number of ScrollableLayer to do scroll and parallax so that the scroll don't goes out of the the world.
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 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
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.
Sprites allows to display an image in a rectangular area, which can be rotated, scaled and moved.
Animation as in cartoon style animation, that is, replacing the image fast enough to give the illusion of movement, can be accomplished by:
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)
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.
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
TODO: explain how to build custom cocosnode objects, how to use transform , etc.