Module cocos.director

Singleton that handles the logic behind the Scenes

Director

Initializing

The director is the singleton that creates and handles the main Window and manages the logic behind the Scenes.

The first thing to do, is to initialize the director:

from cocos.director import *
director.init( list_of_arguments )

This will initialize the director, and will create a display area (a 640x480 window by default). The parameters that are supported by director.init() are the same parameters that are supported by pyglet.window.Window(), plus a few cocos exclusive ones.

director.init cocos exclusive parameters:
  • do_not_scale: Boleean. Defaults to False, when your app can think

    that the windows size dont change despite resize events. When True, your app must include logic to deal with diferent window sizes along the session.

  • audio_backend: one in ['pyglet','sdl']. Defaults to 'pyglet' for

    legacy support.

  • audio: None or a dict providing parameters for the sdl audio backend.
    • None: in this case a "null" audio system will be used, where all the sdl sound operations will be no-ops. This may be useful if you do not want to depend on SDL_mixer
    • A dictionary with string keys; these are the arguments for setting up the audio output (sample rate and bit-width, channels, buffer size). The key names/values should match the positional arguments of http://www.pygame.org/docs/ref/mixer.html#pygame.mixer.init
    • The default value is {}, which means sound enabled with default settings

director.init parameters passes to pyglet.window.Window (partial list):

  • fullscreen: Boolean. Window is created in fullscreen. Default is False
  • resizable: Boolean. Window is resizable. Default is False
  • vsync: Boolean. Sync with the vertical retrace. Default is True
  • width: Integer. Window width size. Default is 640
  • height: Integer. Window height size. Default is 480
  • caption: String. Window title.
  • visible: Boolean. Window is visible or not. Default is True.

The full list of valid video arguments can be found at the pyglet Window documentation:

Example:

director.init( caption="Hello World", fullscreen=True )

Running a Scene

Once you have initialized the director, you can run your first Scene:

director.run( Scene( MyLayer() ) )

This will run a scene that has only 1 layer: MyLayer(). You can run a scene that has multiple layers. For more information about Layers and Scenes refer to the Layers and Scene documentation.

cocos.director.Director

Once a scene is running you can do the following actions:

  • director.replace( new_scene ):

    Replaces the running scene with the new_scene You could also use a transition. For example: director.replace( SplitRowsTransition( new_scene, duration=2 ) )

  • director.push( new_scene ):

    The running scene will be pushed to a queue of scenes to run, and new_scene will be executed.

  • director.pop():

    Will pop out a scene from the queue, and it will replace the running scene.

  • director.scene.end( end_value ):

    Finishes the current scene with an end value of end_value. The next scene to be run will be popped from the queue.

Other functions you can use are:

  • director.get_window_size(): Returns an (x,y) pair with the _logical_ dimensions of the display. The display might have been resized, but coordinates are always relative to this size. If you need the _physical_ dimensions, check the dimensions of director.window
  • get_virtual_coordinates(self, x, y): Transforms coordinates that belongs the real (physical) window size, to the coordinates that belongs to the virtual (logical) window. Returns an x,y pair in logical coordinates.

The director also has some useful attributes:

  • director.return_value: The value returned by the last scene that called director.scene.end. This is useful to use scenes somewhat like function calls: you push a scene to call it, and check the return value when the director returns control to you.
  • director.window: This is the pyglet window handled by this director, if you happen to need low level access to it.
  • self.show_FPS: You can set this to a boolean value to enable, disable the framerate indicator.
  • self.scene: The scene currently active

Classes

  DefaultHandler

Variables

  director = Director()