game—main loop and world handling

Only one Game instance should ever exist, and it stores itself in conf.GAME. Start the game with run() and use the Game instance for changing worlds and handling the display.

run(*args, **kwargs)

Run the game.

Takes the same arguments as Game, with an optional keyword-only argument t to run for this many seconds.

class World(scheduler, evthandler, resources)

Bases: object

A world base class; to be subclassed.

Parameters:

• scheduler – the sched.Scheduler instance this world should use for timing.
• evthandler – the evt.EventHandler instance this world should use for input. Event names prefixed with _game are reserved.
• resources – the res.ResourceManager instance this world should use for loading resources.

id

A unique identifier used for some settings in conf.

This is a class property—it is independent of the instance.

A subclass may define an _id class attribute (not instance attribute). If so, that is returned; if not, world_class.__name__.lower() is returned.

scheduler = None

sched.Scheduler instance taken by the constructor.

evthandler = None

evt.EventHandler instance taken by the constructor.

graphics = None

gfx.GraphicsManager instance used for drawing by default (by, eg. entities).

display = None

gfx.GraphicsManager instance used as the world’s output to the screen. This is the same instance as graphics by default.

resources = None

res.ResourceManager instance taken by the constructor.

entities = None

set of Entity instances in this world.

id = 'world'

fps

The current draw rate, an average based on conf.FPS_AVERAGE_RATIO.

If this is less than conf.FPS, then we’re dropping frames.

For the current update FPS, use the Timer.current_fps of scheduler. (If this indicates the scheduler isn’t running at full speed, it may mean the draw rate is dropping to conf.MIN_FPS.)

init(*args, **kwargs)

Called when this first becomes the active world (before select()).

This receives the extra arguments passed in constructing the world through the Game instance.

select()

Called whenever this becomes the active world.

pause()

Called to pause the game when the window loses focus.

update()

Called every frame to makes any necessary changes.

draw()

Draw to the screen.

Returns:a flag indicating what changes were made: True if the whole display needs to be updated, something falsy if nothing needs to be updated, else a list of rects to update the display in.

This method should not change the state of the world, because it is not guaranteed to be called every frame.

quit()

Called when this is removed from the currently running worlds.

Called before removal—when Game.world is still this world.

add(*entities)

Add any number of Entity instances to the world.

An entity may be in only one world at a time. If a given entity is already in another world, it is removed from that world.

Each entity passed may also be a sequence of entities to add.

rm(*entities)

Remove any number of entities from the world.

Missing entities are ignored.

Each entity passed may also be a sequence of entities to remove.

use_pools(*pools)

Tell the resource manager that this world is using the given pools.

This means the resources in the pool will not be removed from cache until this world drops the pool.

drop_pools(*pools)

Stop using the given pools of the resource manager.

music_volume

The world’s music volume, before scaling.

This is actually conf.MUSIC_VOLUME, and changing it alters that value, and also changes the volume of currently playing music.

snd_volume

The world’s base sound volume.

This is actually conf.SOUND_VOLUME, and changing it alters that value, and also changes the volume of currently playing sounds.

play_music([group, ]loop=True[, cb])

Randomly play music from a group.

Parameters:

• group – music group to play from, as keys in conf.MUSIC; defaults to id, and then ‘’ (the root directory of conf.MUSIC_DIR) if there is no such group.
• loop – whether to play multiple tracks. If True, play random tracks sequentially until the active world changes, music from a different group is played, or the Pygame mixer is manually stopped. If a number, play that many randomly selected tracks (if falsy, do nothing).
• cb – a function to call when all the music has been played, according to the value of loop. Called even if no music is played (if there is none in this group, or loop is falsy).

Raises KeyError if the given group does not exist.

play_snd(base_id, volume=1)

Play a sound.

Parameters:

• base_id – the identifier of the sound to play (we look for base_id + i for a number i—there are as many sounds as set in conf.SOUNDS). If this is not in conf.SOUNDS, it is used as the whole filename (without '.ogg').
• volume – amount to scale the playback volume by.

pause_snds(*base_ids, exclude=False)

Pause sounds with the given IDs, else pause all sounds.

Parameters:

• base_ids – any number of base_id arguments as taken by play_snd(); if none are given, apply to all.
• exclude – if True, apply to all but those in base_ids.

unpause_snds(*base_ids, exclude=False)

Unpause sounds with the given IDs, else unpause all sounds.

Parameters:

• base_ids – any number of base_id arguments as taken by play_snd(); if none are given, apply to all.
• exclude – if True, apply to all but those in base_ids.

stop_snds(*base_ids, exclude=False)

Stop all playing sounds with the given IDs, else stop all sounds.

Parameters:

• base_ids – any number of base_id arguments as taken by play_snd(); if none are given, apply to all.
• exclude – if True, apply to all but those in base_ids.

scale_volume(vol)

Called to scale audio volumes before using them.

The result should be between 0 and 1. The default implementation does

(exp(conf.VOLUME_SCALING * vol) - 1) / (exp(conf.VOLUME_SCALING) - 1)

or no scaling if conf.VOLUME_SCALING is 0.

class Game(*args, **kwargs)

Bases: object

Handles worlds.

Takes the same arguments as create_world() and passes them to it.

world = None

The currently running world.

worlds = None

A list of previous (nested) worlds, most ‘recent’ last.

screen = None

The main Pygame surface.

resources = None

res.ResourceManager instance used for caching resources.

text_renderers = None

{name: renderer} dict of text.TextRenderer instances available for referral by name in the 'text' resource loader.

create_world(cls, *args, **kwargs) → world

Create a world.

Parameters:

• cls – the world class to instantiate; must be a World subclass.
• args – positional arguments to pass to the constructor.
• kwargs – keyword arguments to pass to the constructor.

Returns:

the created world.

A world is constructed by:

cls(scheduler, evthandler, *args, **kwargs)

where scheduler and evthandler are as taken by World (and should be passed to that base class).

start_world(*args, **kwargs)

Store the current world (if any) and switch to a new one.

Takes a World instance, or the same arguments as create_world() to create a new one.

Returns:the new current world.

switch_world(world, *args, **kwargs)

End the current world and start a new one.

Takes a World instance, or the same arguments as create_world() to create a new one.

Returns:the new current world.

get_worlds(ident, current = True) → worlds

Get a list of running worlds, filtered by identifier.

Parameters:

• ident – the world identifier (World.id) to look for.
• current – include the current world in the search.

Returns:

the world list, in order of time started, most recent last.

quit_world(depth = 1) → worlds

Quit the currently running world.

Parameters:depth – quit this many (nested) worlds. Returns:a list of worlds that were quit, in the order they were quit.

If this quits the last (root) world, exit the game.

refresh_display()

Update the display mode from conf.

toggle_fullscreen()

Toggle fullscreen mode.

minimise()

Minimise the display.

run([t])

Main loop.

Parameters:t – stop after this many seconds (else run forever).

quit()

Quit the game.

restart()

Restart the game.