Engine

Engine

Engine(
    name: str,
    pipeline: Pipeline,
    *,
    size: IntVector2 = None,
    display: int = 0,
    icon: pygame.Surface = None,
    settings_persistent: bool = True,
    debug: bool = False
)

Game Engine

Instantiates a game engine that handles all backend code for running games.

PARAMETER	DESCRIPTION
name	The name of the engine window. TYPE: str
pipeline	The pipeline library the engine should use. TYPE: Pipeline
size	The X and Y sizes for the game window - If None, defaults to 0, 0 values. TYPE: IntVector2 DEFAULT: None
display	The index of the display/monitor for the rendering screen. TYPE: int DEFAULT: 0
icon	The image/surface of the game window icon. TYPE: pygame.Surface DEFAULT: None
settings_persistent	If the engine should read and write the internal wame.settings.Settings object persistently, otherwise persistency will be controlled by the developer. TYPE: bool DEFAULT: True
debug	If the debug mode should be enabled - Allows debug logs to be shown. TYPE: bool DEFAULT: False

RAISES	DESCRIPTION
RuntimeError	If more than one instance of wame.engine.Engine is created during runtime. If an unsupported wame.pipeline.Pipeline is set as the pipeline.
TypeError:	If the provided context is not of type Context.

settings instance-attribute

settings: Settings = Settings(json.load(file), self)

The settings that the engine renders/runs the game with

background_color property

background_color: ColorRGB

The background/screen color of the engine.

delta_time property

delta_time: float

Time since the last frame was rendered.

fps property

fps: float

Frames per second of the engine.

mouse_locked property

mouse_locked: bool

If the mouse is locked to the engine window.

mouse_visible property

mouse_visible: bool

If the mouse is visible.

pipeline property

pipeline: Pipeline

The current pipeline of the engine.

running property

running: bool

If the engine is still running the game loop.

scene property

scene: Union[Scene, None]

The currently active scene - None if not running.

scenes property

scenes: dict[str, Scene]

The ID: Scene mapping of all registered scenes.

screen property

screen: pygame.Surface

The screen/window the Engine is handling.

quit

quit() -> None

Stops the engine and cleans up.

register_scene

register_scene(
    name: str, scene: Scene, overwrite: bool = False
) -> None

Register a scene to the engine.

PARAMETER	DESCRIPTION
name	The unique name used to lookup and manipulate this scene. TYPE: str
scene	The scene to register. TYPE: Scene
overwrite	If the unique name is already used, overwrite it, else throw an error. TYPE: bool DEFAULT: False

RAISES	DESCRIPTION
RuntimeError	If the unique name already exists and overwriting is not enabled.
TypeError	If the provided name is not a str. If the provided overwrite is not a bool.

register_scenes

register_scenes(
    scenes: dict[str, Scene], overwrite: bool = False
) -> None

Register a set of scenes to the engine.

PARAMETER	DESCRIPTION
scenes	The name-scene pairs to register. TYPE: dict[str, Scene]
overwrite	If any unique name is already used, overwrite it, else throw an error. TYPE: bool DEFAULT: False

RAISES	DESCRIPTION
RuntimeError	If any unique name already exists and overwriting is not enabled.
TypeError	If the provided scenes mapping is not a dict. If the provided overwrite is not a bool.

register_scenes_from_folder

register_scenes_from_folder(
    folder: str, overwrite: bool = False
) -> None

Register all Scene objects within all files in a folder to the engine.

PARAMETER	DESCRIPTION
folder	The folder to register scenes from. TYPE: str
overwrite	If any unique name is already used, overwrite it, else throw an error. TYPE: bool DEFAULT: False

RAISES	DESCRIPTION
RuntimeError	If the folder path provided does not exist or if the folder path does not direct to a folder. If any unique name already exists and overwriting is not enabled.
TypeError	If the provided folder is not a str. If the provided overwrite is not a bool.

Tip

If you plan on bundling this game into an executable file: Continue to use this method, but also include the raw scene program files in the folder provided as well as the .exe file OR manually register each scene. This is because to bundle Python into executable files, there must be a direct reference to dependencies. Hotloading scenes has no direct reference.

Note

Folder must be in the same directory as your project. The engine will only walk through the files in this folder, not any subdirectories. All unique scene names will be generated from the Scene subclass names themselves:

class MyScene(wame.Scene):
    ...

Will generate unique name "My" and can be used to set the scene later on.

class MainMenuScene(wame.Scene):
    ...

Will generate unique name "MainMenu" and can be used to set the scene later on.

And so forth...

set_background

set_background(color: ColorRGB) -> None

Set the background color of the engine rendering scene.

PARAMETER	DESCRIPTION
color	The background color to apply to all scenes. TYPE: ColorRGB

RAISES	DESCRIPTION
TypeError	If the provided color is not an RGB-supported type (like tuple or ColorRGB).

set_game_loop_enabled

set_game_loop_enabled(enabled: bool) -> None

Set the engine to continuously run the game loop or poll it manually using .step_game_loop.

PARAMETER	DESCRIPTION
enabled	If the game loop should continuously run. TYPE: bool

RAISES	DESCRIPTION
TypeError	If the provided value is not a bool.

Warning

If disabled, this will disable the fixed update functionality of the Engine and Scene objects.

set_mouse_visible

set_mouse_visible(state: bool = True) -> None

Set if the mouse should be visible or hidden.

PARAMETER	DESCRIPTION
state	If the mouse should be visible or hidden. TYPE: bool DEFAULT: True

RAISES	DESCRIPTION
TypeError	If the provided state is not a bool.

set_mouse_locked

set_mouse_locked(state: bool = False) -> None

Set if the mouse should be immovable.

PARAMETER	DESCRIPTION
state	If the mouse should be locked or not. TYPE: bool DEFAULT: False

RAISES	DESCRIPTION
TypeError	If the provided state is not a bool.

set_pipeline

set_pipeline(pipeline: Pipeline) -> None

Set the rendering pipeline that the engine should use.

PARAMETER	DESCRIPTION
pipeline	The rendering pipeline to switch to. TYPE: Pipeline

RAISES	DESCRIPTION
RuntimeError	If the pipeline tries to switch during runtime.
TypeError	If the provided pipeline isn't a Pipeline object.

set_scene

set_scene(name: str, *args, **kwargs) -> None

Switch the engine to another scene and clean up the previous (if any).

PARAMETER	DESCRIPTION
name	The unique name of the scene to switch to (must be previously registered). TYPE: str
args	Any data you wish to pass to the scene instance. TYPE: Any DEFAULT: ()
kwargs	Any data you wish to pass to the scene instance. TYPE: dict[str, Any] DEFAULT: {}

RAISES	DESCRIPTION
RuntimeError	If a scene with the name doesn't exist. If the desired scene is already set as the active scene.
TypeError	If the provided name is not a str.

set_update_interval

set_update_interval(interval: Interval) -> None

Set the amount of time (in seconds) that has to elapse before a fixed update call to a Scene is called.

PARAMETER	DESCRIPTION
interval	The amount of seconds to elapse for each fixed update call. TYPE: Interval

RAISES	DESCRIPTION
TypeError	If the interval provided is not an Interval, float, or int.

start

start() -> None

Starts the engine.

Warning

This is a blocking call. No code below will execute until the engine has stopped running.

RAISES	DESCRIPTION
RuntimeError	If the engine is started without a scene registered and set.

step_game_loop

step_game_loop() -> None

Poll the game loop to run a cycle (update/render) - Only use when game loop is disabled with .set_game_loop_enabled(False).