⚠️ Beta State

PyBevy is in an early and experimental stage. The API is incomplete, subject to breaking changes without notice, and you should expect bugs. Many features are still under development.

Window Configuration

Set window title, resolution, fullscreen mode, and exit behavior.

Introduction

By default, pybevy opens a window with a default title and resolution. You can customize this by configuring WindowPlugin inside DefaultPlugins.

Key types:

  • Window: Window properties (title, resolution, mode).
  • WindowPlugin: Plugin that creates the window.
  • WindowMode: Windowed, borderless fullscreen, or exclusive fullscreen.
  • WindowResolution: Logical and physical resolution with DPI handling.
from pybevy.prelude import *
from pybevy.window import Window, WindowPlugin, WindowResolution, WindowMode, MonitorSelection

Custom Window Title and Resolution

Override the WindowPlugin inside DefaultPlugins using .set().

def setup(commands: Commands, meshes: ResMut[Assets[Mesh]], materials: ResMut[Assets[StandardMaterial]]):
    commands.spawn(Camera3d(), Transform.from_xyz(0.0, 5.0, 10.0).looking_at(Vec3.ZERO, Vec3.Y))
    commands.spawn(DirectionalLight(illuminance=5000.0), Transform.IDENTITY.looking_at(Vec3(-1.0, -1.0, -1.0), Vec3.Y))
    commands.spawn(
        Mesh3d(meshes.add(Cuboid.from_length(2.0))),
        MeshMaterial3d(materials.add(Color.srgb(0.2, 0.6, 0.8))),
        Transform.from_xyz(0.0, 1.0, 0.0),
    )

Toggling Fullscreen at Runtime

Query the Window component on the primary window entity to change its mode.

def toggle_fullscreen(
    keyboard: Res[ButtonInput],
    query: Query[Mut[Window]],
):
    if keyboard.just_pressed(KeyCode.F11):
        for window in query:
            if window.mode == WindowMode.Windowed():
                window.mode = WindowMode.BorderlessFullscreen(MonitorSelection.Primary())
            else:
                window.mode = WindowMode.Windowed()

Running the App

The DefaultPlugins.set(WindowPlugin(...)) pattern replaces the default window configuration while keeping all other default plugins intact.

@entrypoint
def main(app: App) -> App:
    return (
        app
        .add_plugins(DefaultPlugins().build().set(WindowPlugin(
            primary_window=Window(
                title="My PyBevy Game",
                resolution=WindowResolution(1280, 720),
            ),
        )))
        .add_systems(Startup, setup)
        .add_systems(Update, toggle_fullscreen)
    )
 
if __name__ == "__main__":
    main().run()

Press F11 to toggle between windowed and borderless fullscreen.

Other useful Window fields include:

  • resizable: Allow the user to resize the window.
  • decorations: Show or hide the title bar.
  • cursor_visible: Hide the cursor for FPS-style games.