Events#
Events are the primary way objects in ppb communicate. This module contains the events defined by various systems in ppb.
To respond to an event your event handler should be snake_cased
on_event_name
and accept an event instance and a signal function as
parameters. Example:
class MySprite(Sprite):
def on_update(self, event: Update, signal):
. . .
The signal()
function accepts one parameter: an
instance of an event class. You are not limited to predefined event types, but
can provide arbitrary instances.
Events as defined here are dataclasses.dataclass()
, but ppb does
not expect dataclasses; they are just a simple way to quickly define new events.
The name of the handler will always be based on the name of the class, with the
TitleCase name of the class converted to on_event_name function. The instance
passed to signal()
will be passed to all the event
handlers as the event parameter.
Basic Events#
These events are the basic events you’ll want to build your games. You can make a variety of games using just them.
- class ppb.events.Update(time_delta: float, scene: Scene = None)[source]#
A simulation tick.
Respond via
on_update
to advance the simulation of your game objects. Movement and other things that happen “over time” are best implemented in your on_update methods.
- class ppb.events.PreRender(time_delta: float, scene: Scene = None)[source]#
The
Renderer
is preparing to render.PreRender
is called before every frame is rendered. Things that are strictly for display purposes (like the text of a score board or the position of the camera) should happenon_pre_render
.
- class ppb.events.ButtonPressed(button: MouseButton, position: Vector, scene: Scene = None)[source]#
A mouse button was pressed.
The button is a
MouseButton
instance.This represents the button in the active state. For acting when a button is released see
ButtonReleased
.
- class ppb.events.ButtonReleased(button: MouseButton, position: Vector, scene: Scene = None)[source]#
A mouse button was released.
The button is a
MouseButton
instance.This represents the button in the inactive state. For acting when a button is clicked see
ButtonPressed
.- button: MouseButton#
A mouse button: Primary, Secondary, or Tertiary
- position: Vector#
The game-world position of the event.
- class ppb.events.KeyPressed(key: KeyCode, mods: Set[KeyCode], scene: Scene = None)[source]#
A keyboard key was pressed.
The buttons are defined in
ppb.keycodes
.This represents the key entering an active state, to respond to when a key is released see
KeyReleased
.- key: KeyCode#
A
KeyCode
flag.
- class ppb.events.KeyReleased(key: KeyCode, mods: Set[KeyCode], scene: Scene = None)[source]#
A keyboard key was released.
The buttons are defined in
ppb.keycodes
.This represents the key entering an inactive state, to respond to when a key is pressed see
KeyPressed
.- key: KeyCode#
A
KeyCode
flag.
- class ppb.events.MouseMotion(position: Vector, delta: Vector, buttons: Collection[MouseButton], scene: Scene = None)[source]#
The mouse moved.
If something should be tracking the mouse, this is the event to listen to.
- buttons: Collection[MouseButton]#
The state of the mouse buttons.
- delta: Vector#
The change in position since the last
MouseMotion
event.
- position: Vector#
The game-world location of the mouse cursor.
Command Events#
These events are used in your code to achieve certain effects.
- class ppb.events.Quit(scene: Scene = None)[source]#
A request to quit the program.
Fired in response to a close request from the OS, but can be signaled from inside one of your handlers to end the program.
For example:
def on_update(self, event, signal): signal(Quit())
This will stop the engine.
Respond with
on_quit
to perform any shut down tasks (like saving data.)
- class ppb.events.StartScene(new_scene: Scene | Type[Scene], kwargs: Dict[str, Any] = None, scene: Scene = None)[source]#
An object requested a new scene to be started.
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}
Warning
In general, you should not respond to
StartScene
, if you want to respond to a new scene, seeSceneStarted
.
- class ppb.events.ReplaceScene(new_scene: Scene | Type[Scene], kwargs: Dict[str, Any] = None, scene: Scene = None)[source]#
An object requested a new scene to replace it.
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(ReplaceScene(MyScene(player=player))
signal(ReplaceScene(new_scene=ReplacementScene, kwargs={“player”: player}))
Warning
In general, you should not respond to
ReplaceScene
, if you want to respond to a new scene, seeSceneStarted
.
- class ppb.events.StopScene(scene: Scene = None)[source]#
An object has requested the current scene be stopped.
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 theSceneStopped
event.Warning
In general, you should not respond to
StopScene
, if you want to respond to a scene ending, seeSceneStopped
.
Scene Transition Events#
These are events triggered during 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: Scene = None)[source]#
A new scene has started running.
This is delivered to a Scene shortly after it starts.
Responding to SceneStarted is a good choice for
ppb.systems
that change behavior based on the running scene, or if you have start up work that requires the initial state to be set before it happens.The scene lifetime events happen in the following order:
Always:
SceneStarted
Optionally, Repeatable:
ScenePaused
Optionally, Repeatable:
SceneContinued
Optionally:
SceneStopped
- class ppb.events.ScenePaused(scene: Scene = None)[source]#
A scene that is running is being paused to allow a new scene to run.
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 aSceneContinued
event.A middle event in the scene lifetime, started with
SceneStarted
.
- class ppb.events.SceneContinued(scene: Scene = None)[source]#
A scene that had been paused has continued.
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
.
- class ppb.events.SceneStopped(scene: Scene = None)[source]#
A scene is being stopped and will no longer be available.
This is delivered to a scene and it’s objects when a
StopScene
orReplaceScene
event is sent to the engine.This is technically an optional event, as not all scenes in the stack will receive a
SceneStopped
event if aQuit
event was sent.This is the end of the scene lifetime, see
SceneStarted
.
Engine Events#
These are additional events from the engine mostly for advanced purposes.
- class ppb.events.Idle(time_delta: float, scene: Scene = None)[source]#
A complete loop of the
GameEngine
main loop has finished.This is an engine plumbing event to pump timing information to subsystems.