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: ppb.scenes.BaseScene = 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.-
scene
= None¶ The currently running scene.
-
time_delta
= None¶ Seconds since last Update
-
-
class
ppb.events.
PreRender
(time_delta: float, scene: ppb.scenes.BaseScene = 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
.-
scene
= None¶ The currently running scene.
-
time_delta
= None¶ Seconds since last PreRender.
-
-
class
ppb.events.
ButtonPressed
(button: ppb.buttons.MouseButton, position: ppb_vector.Vector, scene: ppb.scenes.BaseScene = 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: ppb.buttons.MouseButton, position: ppb_vector.Vector, scene: ppb.scenes.BaseScene = 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
.A mouse button: Primary, Secondary, or Tertiary
-
position
= None¶ The game-world position of the event.
-
scene
= None¶ The currently running scene.
-
class
ppb.events.
KeyPressed
(key: ppb.keycodes.KeyCode, mods: Set[ppb.keycodes.KeyCode], scene: ppb.scenes.BaseScene = 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
= None¶ A
KeyCode
flag.
-
mods
= None¶ A set of
KeyCodes
-
scene
= None¶ The currently running scene
-
-
class
ppb.events.
KeyReleased
(key: ppb.keycodes.KeyCode, mods: Set[ppb.keycodes.KeyCode], scene: ppb.scenes.BaseScene = 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
= None¶ A
KeyCode
flag.
-
mods
= None¶ A set of
KeyCodes
-
scene
= None¶ The currently running scene
-
-
class
ppb.events.
MouseMotion
(position: ppb_vector.Vector, delta: ppb_vector.Vector, buttons: Collection[ppb.buttons.MouseButton], scene: ppb.scenes.BaseScene = None)[source]¶ The mouse moved.
If something should be tracking the mouse, this is the event to listen to.
The state of the mouse buttons.
-
delta
= None¶ The change in position since the last
MouseMotion
event.
-
position
= None¶ The game-world location of the mouse cursor.
-
scene
= None¶ The currently running scene.
Command Events¶
These events are used in your code to achieve certain effects.
-
class
ppb.events.
Quit
(scene: ppb.scenes.BaseScene = 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.)-
scene
= None¶ The currently running scene.
-
-
class
ppb.events.
StartScene
(new_scene: Union[ppb.scenes.BaseScene, Type[ppb.scenes.BaseScene]], kwargs: Dict[str, Any] = None, scene: ppb.scenes.BaseScene = 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
.-
kwargs
= None¶ Keyword arguments to be passed to a scene type.
-
new_scene
= None¶ A
BaseScene
class or instance
-
scene
= None¶ The currently running scene.
-
class
ppb.events.
ReplaceScene
(new_scene: Union[ppb.scenes.BaseScene, Type[ppb.scenes.BaseScene]], kwargs: Dict[str, Any] = None, scene: ppb.scenes.BaseScene = 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
.-
kwargs
= None¶ Keyword arguments to be passed to a scene type.
-
new_scene
= None¶ A
BaseScene
class or instance
-
scene
= None¶ The currently running scene.
-
class
ppb.events.
StopScene
(scene: ppb.scenes.BaseScene = 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
= None¶ The scene that is stopping.
-
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: ppb.scenes.BaseScene = 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
-
scene
= None¶ The scene that is starting.
- Always:
-
class
ppb.events.
ScenePaused
(scene: ppb.scenes.BaseScene = 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
.-
scene
= None¶ The scene that has paused.
-
-
class
ppb.events.
SceneContinued
(scene: ppb.scenes.BaseScene = 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
.-
scene
= None¶ The scene that is resuming.
-
-
class
ppb.events.
SceneStopped
(scene: ppb.scenes.BaseScene = 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
.-
scene
= None¶ The scene that is stopping.
-
Engine Events¶
These are additional events from the engine mostly for advanced purposes.
-
class
ppb.events.
Idle
(time_delta: float, scene: ppb.scenes.BaseScene = None)[source]¶ A complete loop of the
GameEngine
main loop has finished.This is an engine plumbing event to pump timing information to subsystems.
-
scene
= None¶ The currently running scene.
-
time_delta
= None¶ Seconds since last Idle.
-