Events

All game objects (the engine, scenes, sprites, systems, etc) receive events. Handlers are methods that start with on_, eg on_update, on_button_pressed.

The signature of these handlers are the same: (event, signal):

• event: An object containing all the properties of the event, such as the button pressed, the position of the mouse, the current scene
• signal: A callable that accepts an object, which will be raised as an event: signal(StartScene(new_scene=OtherScene()))

Engine Events

These are core events from hardware and the engine itself.

class ppb.events.Update(time_delta: float, scene: ppb.scenes.BaseScene = None)

Fired on game tick

class ppb.events.PreRender(scene: ppb.scenes.BaseScene = None)

Fired before rendering.

class ppb.events.Idle(time_delta: float, scene: ppb.scenes.BaseScene = None)

An engine plumbing event to pump timing information to subsystems.

class ppb.events.Render(scene: ppb.scenes.BaseScene = None)

Fired at render.

class ppb.events.ButtonPressed(button: ppb.buttons.MouseButton, position: ppb_vector.Vector, scene: ppb.scenes.BaseScene = None)

Fired when a button is pressed

class ppb.events.ButtonReleased(button: ppb.buttons.MouseButton, position: ppb_vector.Vector, scene: ppb.scenes.BaseScene = None)

Fired when a button is released

class ppb.events.KeyPressed(key: ppb.keycodes.KeyCode, mods: Set[ppb.keycodes.KeyCode], scene: ppb.scenes.BaseScene = None)

class ppb.events.KeyReleased(key: ppb.keycodes.KeyCode, mods: Set[ppb.keycodes.KeyCode], scene: ppb.scenes.BaseScene = None)

class ppb.events.MouseMotion(position: ppb_vector.Vector, screen_position: ppb_vector.Vector, delta: ppb_vector.Vector, buttons: Collection[ppb.buttons.MouseButton], scene: ppb.scenes.BaseScene = None)

An event to represent mouse motion.

API Events

These “events” are more for code to call into the engine.

class ppb.events.Quit(scene: ppb.scenes.BaseScene = None)

Fired on an OS Quit event.

You may also fire this event to stop the engine.

class ppb.events.StartScene(new_scene: Union[ppb.scenes.BaseScene, Type[ppb.scenes.BaseScene]], kwargs: Dict[str, Any] = None, scene: ppb.scenes.BaseScene = None)

Fired to start a new scene.

new_scene can be an instance or a class. If a class, must include kwargs. If new_scene is an instance kwargs should be empty or None.

Before the previous scene pauses, a ScenePaused event will be fired. Any events signaled in response will be delivered to the new scene.

After the ScenePaused event and any follow up events have been delivered, a SceneStarted event will be sent.

Examples:

• signal(new_scene=StartScene(MyScene(player=player))
• signal(new_scene=StartScene, kwargs={“player”: player}

class ppb.events.ReplaceScene(new_scene: Union[ppb.scenes.BaseScene, Type[ppb.scenes.BaseScene]], kwargs: Dict[str, Any] = None, scene: ppb.scenes.BaseScene = None)

Fired to replace the current scene with a new one.

new_scene can be an instance or a class. If a class, must include kwargs. If new_scene is an instance kwargs should be empty or None.

Before the previous scene stops, a SceneStopped event will be fired. Any events signaled in response will be delivered to the new scene.

After the SceneStopped event and any follow up events have been delivered, a SceneStarted event will be sent.

Examples:

• signal(new_scene=ReplaceScene(MyScene(player=player))
• signal(new_scene=ReplaceScene, kwargs={“player”: player}

class ppb.events.StopScene(scene: ppb.scenes.BaseScene = None)

Fired to stop a scene.

Before the scene stops, a SceneStopped event will be fired. Any events signaled in response will be delivered to the previous scene if it exists.

If there is a paused scene on the stack, a SceneContinued event will be fired after the responses to the SceneStopped event.

class ppb.events.PlaySound(sound: ppb.assets.Asset)

Fire to start a sound playing.

Scene Transition Events

These are events triggered about the lifetime of a scene: it starting, stopping, etc.

The scene property on these events always refers to the scene these are about–ScenePaused.scene is the scene that is being paused.

class ppb.events.SceneStarted(scene: ppb.scenes.BaseScene = None)

Fired when a scene starts.

This is delivered to a Scene shortly after it starts. The beginning of the scene lifetime, ended with SceneStopped, paused with ScenePaused, and resumed from a pause with SceneContinued.

class ppb.events.SceneStopped(scene: ppb.scenes.BaseScene = None)

Fired when a scene stops.

This is delivered to a scene and it’s objects when a StopScene or ReplaceScene event is sent to the engine.

The end of the scene lifetime, started with SceneStarted.

class ppb.events.ScenePaused(scene: ppb.scenes.BaseScene = None)

Fired when a scene pauses.

This is delivered to a scene about to be paused when a StartScene event is sent to the engine. When this scene resumes it will receive a SceneContinued event.

A middle event in the scene lifetime, started with SceneStarted.

class ppb.events.SceneContinued(scene: ppb.scenes.BaseScene = None)

Fired when a paused scene continues.

This is delivered to a scene as it resumes operation after being paused via a ScenePaused event.

From the middle of the event lifetime that begins with SceneStarted.