The GameEngine is the literal beating heart of ppb: It publishes the event queue, is the source of the Idle event, and is the root container of the object tree.

Some of the engine of the API is definitely intended for advanced users. Use the various methods of GameEngine with caution.

class ppb.GameEngine(first_scene: ~typing.Type | ~ppb.scenes.Scene, *, basic_systems=(<class ''>, <class ''>, <class ''>, <class ''>, <class 'ppb.assetlib.AssetLoadingSystem'>), systems=(), scene_kwargs=None, **kwargs)[source]#

The core component of ppb.

To use the engine directly, treat it as a context manager:

with GameEngine(Scene, **kwargs) as ge:
  • first_scene (Union[Type, scenes.Scene]) – A Scene type.

  • basic_systems (Iterable[systemslib.System]) – :class:systemslib.Systems that are considered the “default”. Includes: Renderer, Updater, EventPoller, SoundController, AssetLoadingSystem.

  • systems (Iterable[systemslib.System]) – Additional user defined systems.

  • scene_kwargs (Dict[str, Any]) – Keyword arguments passed along to the first scene.

  • kwargs – Additional keyword arguments. Passed to the systems.


Passing in your own basic_systems can have unintended consequences. Consider passing via systems parameter instead.

property current_scene#

The top of the scene stack.


The currently running scene.

Return type:



Iterate once.

If you’re embedding ppb in an external event loop call once per loop.


Loop forever.

If you’re embedding ppb in an external event loop you should not use this method. Call GameEngine.loop_once() instead.

on_quit(quit_event: Quit, signal: Callable[[Any], None])[source]#

Shut down the event loop.

Do not call this method directly. It is called by the GameEngine when a Quit event is fired.

on_replace_scene(event: ReplaceScene, signal)[source]#

Replace the running scene with a new one.

Do not call this method directly. It is called by the GameEngine when a ReplaceScene event is fired.

on_start_scene(event: StartScene, signal: Callable[[Any], None])[source]#

Start a new scene. The current scene pauses.

Do not call this method directly. It is called by the GameEngine when a StartScene event is fired.

on_stop_scene(event: StopScene, signal: Callable[[Any], None])[source]#

Stop a running scene. If there’s a scene on the stack, it resumes.

Do not call this method directly. It is called by the GameEngine when a StopScene event is fired.


Publish the next event to every object in the tree.

register(event_type: Type | ellipsis, callback: Callable[[], Any])[source]#

Register a callback to be applied to an event at time of publishing.

Primarily to be used by subsystems.

The callback will receive the event. Your code should modify the event in place. It does not need to return it.

  • event_type – The class of an event.

  • callback – A callable, must accept an event, and return no value.




Begin the main loop.

If you have not entered the GameEngine, this function will enter it for you before starting.


GameEngine(Scene, **kwargs).run()
signal(event, *, targets=None)[source]#

Add an event to the event queue.


You will rarely call this directly from a GameEngine instance. The current GameEngine instance will pass it’s signal method as part of publishing an event.

Events can be targetted–they will only be delivered to specific objects instead of the whole tree. Note that this might cause objects to receive an event if they are no longer part of the object tree.


Starts the engine.

Called by before GameEngine.main_loop().

You shouldn’t call this yourself unless you’re embedding ppb in another event loop.


Initialize the systems.