Introduction to cocos2d

In preparation for the pyweek I'm studying about the cocos2d library. cocos2d is a high-level framework that is good for game development since it provides good abstractions like Scenes, Layers, Sprites and Scene transitions. It gives you some default classes like ColorLayer and TiledLayer (rectangular and hexagonal) and a very good set of samples, but enough talking. I'll show how to initialize the library, create a sprite on the screen and control it with the arrow keys (it allows diagonal movements too :)
First install the cocos2d library (pre-requisites:pyglet 1.1.2 and python setuptools). Just go to the respective pages and follow the instructions. They are pretty clear, but if you need any help don't hesitate to ask.
Lets begin importing all the necessary stuff.

from cocos.director import *
from cocos.scene import *
from cocos.layer import *
from cocos.sprite import *

The director is the singleton class of cocos that controls the flow of your aplication. It can run scenes and change between them (among other tasks). Scenes are different parts of the game and layers are drawable parts of the screen that can be pilled up to form the visuals of the application. A simple example: a game could have 4 scenes (the menu, win, game over and the game itself) and each level could be a layer of the game scene. In our example we will have only one scene with one layer.
So we will create a ColorLayer, a type of layer that has a color background.

class TutorialLayer (ColorLayer):
  def __init__(self):
      super(TutorialLayer, self).__init__(0, 0, 100, 255)

Now we will instruct the director initialize and run a Scene object. Since there's only one scene in our application and it does not have any logic in it, we won't create a subclass of it, we will simply intanciate a new Scene and add our custom layer to it.

director.init()
director.run(Scene(TutorialLayer()))

Now run this code. You should see a 640x480 blue screen. We will ad now a sprite (a simple image that can do actions live move, rotate, etc) to it. Add this line in the __init__ method of the TutorialLayer (image here):

self.ship = Sprite('ship.png', position=(320,240))
self.add(self.ship)

If you run it you should see a ship in the center of the screen. Now were going to handle key events to finish our example. First we will let cocos know that our layer wants to receive events. To do this just add the following line below the class declaration:
is_event_handler = True
Now that we can receive events, we need to create a listener to the key press and key release functions and a character set to store wich characters are pressed. The event listener for the key press event is defined by the on_key_press(self, key, modifiers) function. The modifiers parameter shows if any modifier key like control or alt is pressed. A similar event is defined for the release of a key. First we will initialize our character pool in the constructor using

self.chars_pressed = set()

Then we add the on_key_press and on_key_release methods:

def on_key_press(self, key, modifiers):
  self.chars_pressed.add(key)

def on_key_release(self, key, modifiers):
  self.chars_pressed.remove(key)

What we do here is keep track of the currently pressed keys by storing them on a set. Now we just check if the keys are in our set in every frame. To do this we will schedule a function to be called every frame.

self.schedule(self.update)

And we will define the following constants:

LEFT = 65361
UP = 65362
RIGHT = 65363
DOWN = 65364

Now the the update method:

def update(self, dt):
  x, y = self.ship.position
  if LEFT in self.chars_pressed:
      x -= 2
  if UP in self.chars_pressed:
      y += 2
  if RIGHT in self.chars_pressed:
      x += 2
  if DOWN in self.chars_pressed:
      y -= 2
  self.ship.position = (x, y)

Notice that the (0,0) point of the screen is the left-bottom one. Now test the program and verify that the ship really moves in every direction, including diagonals. The complete file can be found here.
That's my introduction to cocos2d :) I hope you liked it. See you next time!