Window and View

class arcade.NoOpenGLException[source]

Bases: Exception

Exception when we can’t get an OpenGL 3.3+ context

class arcade.Window(width: int = 1280, height: int = 720, title: str | None = 'Arcade Window', fullscreen: bool = False, resizable: bool = False, update_rate: float = 0.016666666666666666, antialiasing: bool = True, gl_version: tuple[int, int] = (3, 3), screen: Screen | None = None, style: str | None = None, visible: bool = True, vsync: bool = False, gc_mode: str = 'context_gc', center_window: bool = False, samples: int = 4, enable_polling: bool = True, gl_api: str = 'gl', draw_rate: float = 0.016666666666666666, fixed_rate: float = 0.016666666666666666, fixed_frame_cap: int | None = None)[source]

Bases: Window

A window that will appear on your desktop.

This class is a subclass of Pyglet’s Window class with many Arcade-specific features added.

Note

Arcade currently cannot easily support multiple windows. If you need multiple windows, consider using multiple views or divide the window into sections.

Parameters:
  • width (optional) – Window width. Defaults to 1280.

  • height (optional) – Window height. Defaults to 720.

  • title (optional) – The title/caption of the window

  • fullscreen (optional) – Should this be full screen?

  • resizable (optional) – Can the user resize the window?

  • update_rate (optional) – How frequently to run the on_update event.

  • draw_rate (optional) – How frequently to run the on_draw event. (this is the FPS limit)

  • fixed_rate (optional) – How frequently should the fixed_updates run, fixed updates will always run at this rate.

  • fixed_frame_cap (optional) – The maximum number of fixed updates that can occur in one update loop. defaults to infinite. If large lag spikes cause your game to freeze, try setting this to a smaller number. This may cause your physics to lag behind temporarily.

  • antialiasing (optional) – Use multisampling framebuffer (antialiasing)

  • samples – Number of samples used in antialiasing (default 4). Usually this is 2, 4, 8 or 16.

  • gl_version (optional) – What OpenGL version to request. This is (3, 3) by default and can be overridden when using more advanced OpenGL features.

  • screen (optional) – Pass a pyglet Screen to request the window be placed on it. See pyglet’s window size & position guide to learn more.

  • style (optional) – Request a non-default window style, such as borderless. Some styles only work in certain situations. See pyglet’s guide to window style to learn more.

  • visible (optional) – Should the window be visible immediately

  • vsync (optional) – Wait for vertical screen refresh before swapping buffer This can make animations and movement look smoother.

  • gc_mode (optional) – Decides how OpenGL objects should be garbage collected (“context_gc” (default) or “auto”)

  • center_window (optional) – If true, will center the window.

  • enable_polling (optional) – Enabled input polling capability. This makes the keyboard and mouse attributes available for use.

Raises:

NoOpenGLException – If the system does not support OpenGL requested OpenGL version.

activate() None[source]

Activate this window.

property background_color: Color

Get or set the background color for this window. This affects what color the window will contain when clear() is called.

Examples:

# Use Arcade's built in Color values
window.background_color = arcade.color.AMAZON

# Set the background color with a custom Color instance
MY_RED = arcade.types.Color(255, 0, 0)
window.background_color = MY_RED

# Set the background color directly from an RGBA tuple
window.background_color = 255, 0, 0, 255

# Set the background color directly from an RGB tuple
# RGB tuples will assume 255 as the opacity / alpha value
window.background_color = 255, 0, 0
property center: tuple[float, float]

Returns center coordinates of the window

Equivalent to (self.width / 2, self.height / 2).

center_window() None[source]

Center the window on your desktop.

property center_x: float

Returns the center x-coordinate of the window.

Equivalent to self.width / 2.

property center_y: float

Returns the center y-coordinate of the window.

Equivalent to self.height / 2.

clear(color: tuple[int, int, int] | tuple[int, int, int, int] | None = None, color_normalized: tuple[float, float, float, float] | None = None, viewport: tuple[int, int, int, int] | None = None) None[source]

Clears the window with the configured background color set through background_color.

Parameters:
  • color (optional) –

    Override the current background color with one of the following:

    1. A Color instance

    2. A 3 or 4-length RGB/RGBA tuple of byte values (0 to 255)

  • color_normalized (optional) – override the current background color using normalized values (0.0 to 1.0). For example, (1.0, 0.0, 0.0, 1.0) making the window contents red.

  • viewport (optional) – The area of the window to clear. By default, the entire window is cleared. The viewport format is (x, y, width, height).

close() None[source]

Close the Window.

property ctx: ArcadeContext

The OpenGL context for this window.

This context instance provides access to a powerful set of features for lower level OpenGL programming. It is also used internally by Arcade to manage OpenGL resources.

property current_camera: Projector

Get or set the current camera.

This represents the projector currently being used to define the projection and view matrices.

property current_view: View | None

The currently active view.

To set a different view, call show_view().

property default_camera: DefaultProjector

The default camera for the window.

This is an extremely simple camera simply responsible for maintaining the default projection and viewport.

property delta_time: float

Shortcut for the global clock’s delta_time.

dispatch_events() None[source]

Dispatch events

property fixed_delta_time: float

The configured fixed update rate

property fixed_time: float

Shortcut to the fixed clock’s time.

This is the time in seconds since the application started but updated at a fixed rate.

flip() None[source]

Present the rendered content to the screen.

This is not necessary to call when using the standard standard event loop. The event loop will automatically call this method after on_draw has been called.

Window framebuffers normally have a back and front buffer meaning they are “double buffered”. Content is always drawn into the back buffer while the front buffer contains the previous frame. Swapping the buffers makes the back buffer visible and hides the front buffer. This is done to prevent flickering and tearing.

This method also garbage collects OpenGL resources if there are any dead resources to collect.

get_location() tuple[int, int][source]

Get the current X/Y coordinates of the window.

get_size() tuple[int, int][source]

Get the size of the window.

get_system_mouse_cursor(name) MouseCursor[source]

Get the system mouse cursor

headless: bool

If True, the window is running in headless mode.

hide_view() None[source]

Hide the currently active view (if any).

This is only necessary if you don’t want an active view falling back to the window’s event handlers. It’s not necessary to call when changing the active view.

keyboard: pyglet.window.key.KeyStateHandler | None

A pyglet KeyStateHandler that can be used to poll the state of the keyboard.

Example:

if self.window.keyboard[key.SPACE]:
    print("The space key is currently being held down.")
maximize() None[source]

Maximize the window.

minimize() None[source]

Minimize the window.

mouse: pyglet.window.mouse.MouseStateHandler | None

A pyglet MouseStateHandler that can be used to poll the state of the mouse.

Example:

if self.window.mouse.LEFT:
    print("The left mouse button is currently being held down.")
print(
    "The mouse is at position "
    f"{self.window.mouse["x"]}, {self.window.mouse["y"]}"
)
on_action(action_name: str, state) None[source]

Called when an action is dispatched. This is related to the input manager / controller support.

Parameters:
  • action_name – The name of the action

  • state – The state of the action

on_draw() Literal[True] | None[source]

Override this function to add your custom drawing code.

This method is usually called 60 times a second unless another update rate has been set. Should be called after on_update().

This function should normally start with a call to clear() to clear the screen.

on_fixed_update(delta_time: float)[source]

Called for each fixed update. This is useful for physics engines and other systems that should update at a constant rate.

Parameters:

delta_time – Time interval since the last time the function was called in seconds.

on_key_press(symbol: int, modifiers: int) Literal[True] | None[source]

Called once when a key gets pushed down.

Override this function to add key press functionality.

Tip

If you want the length of key presses to affect gameplay, you also need to override on_key_release().

Parameters:
  • symbol – Key that was just pushed down

  • modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_key_release(symbol: int, modifiers: int) Literal[True] | None[source]

Called once when a key gets released.

Override this function to add key release functionality.

Situations that require handling key releases include:

  • Rhythm games where a note must be held for a certain amount of time

  • ‘Charging up’ actions that change strength depending on how long a key was pressed

  • Showing which keys are currently pressed down

Parameters:
  • symbol (int) – Key that was released

  • modifiers (int) – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_drag(x: int, y: int, dx: int, dy: int, buttons: int, modifiers: int) Literal[True] | None[source]

Called repeatedly while the mouse moves with a button down.

Override this function to handle dragging.

Parameters:
  • x – x position of mouse

  • y – y position of mouse

  • dx – Change in x since the last time this method was called

  • dy – Change in y since the last time this method was called

  • buttons – Which button is pressed

  • modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_enter(x: int, y: int) Literal[True] | None[source]

Called once whenever the mouse enters the window area on screen.

This event will not be triggered if the mouse is currently being dragged.

Parameters:
  • x – The x position the mouse entered the window

  • y – The y position the mouse entered the window

on_mouse_leave(x: int, y: int) Literal[True] | None[source]

Called once whenever the mouse leaves the window area on screen.

This event will not be triggered if the mouse is currently being dragged. Note that the coordinates of the mouse pointer will be outside of the window rectangle.

Parameters:
  • x – The x position the mouse entered the window

  • y – The y position the mouse entered the window

on_mouse_motion(x: int, y: int, dx: int, dy: int) Literal[True] | None[source]

Called repeatedly while the mouse is moving in the window area.

Override this function to respond to changes in mouse position.

Parameters:
  • x – x position of mouse within the window in pixels

  • y – y position of mouse within the window in pixels

  • dx – Change in x since the last time this method was called

  • dy – Change in y since the last time this method was called

on_mouse_press(x: int, y: int, button: int, modifiers: int) Literal[True] | None[source]

Called once whenever a mouse button gets pressed down.

Override this function to handle mouse clicks. For an example of how to do this, see Arcade’s built-in aiming and shooting bullets demo.

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

  • button

    What button was pressed. This will always be one of the following:

    • arcade.MOUSE_BUTTON_LEFT

    • arcade.MOUSE_BUTTON_RIGHT

    • arcade.MOUSE_BUTTON_MIDDLE

  • modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_release(x: int, y: int, button: int, modifiers: int) Literal[True] | None[source]

Called once whenever a mouse button gets released.

Override this function to respond to mouse button releases. This may be useful when you want to use the duration of a mouse click to affect gameplay.

Parameters:
  • x – x position of mouse

  • y – y position of mouse

  • button

    What button was hit. One of:

    • arcade.MOUSE_BUTTON_LEFT

    • arcade.MOUSE_BUTTON_RIGHT

    • arcade.MOUSE_BUTTON_MIDDLE

  • modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_scroll(x: int, y: int, scroll_x: float, scroll_y: float) Literal[True] | None[source]

Called repeatedly while a mouse scroll wheel moves.

Override this function to respond to scroll events. The scroll arguments may be positive or negative to indicate direction, but the units are unstandardized. How many scroll steps you receive may vary wildly between computers depending a number of factors, including system settings and the input devices used (i.e. mouse scrollwheel, touch pad, etc).

Warning

Not all users can scroll easily!

Only some input devices support horizontal scrolling. Standard vertical scrolling is common, but some laptop touch pads are hard to use.

This means you should be careful about how you use scrolling. Consider making it optional to maximize the number of people who can play your game!

Parameters:
  • x – x position of mouse

  • y – y position of mouse

  • scroll_x – Number of steps scrolled horizontally since the last call of this function

  • scroll_y – Number of steps scrolled vertically since the last call of this function

on_resize(width: int, height: int) Literal[True] | None[source]

Override this method to add custom actions when the window is resized.

An internal _on_resize is called first adjusting the viewport to the new size of the window so there is no need to call `super().on_resize(width, height)`.

Parameters:
  • width – New width of the window

  • height – New height of the window

on_update(delta_time: float) bool | None[source]

This method can be implemented and is reserved for game logic. Move sprites. Perform collision checks and other game logic. This method is called every frame before on_draw().

The delta_time can be used to make sure the game runs at the same speed, no matter the frame rate.

Parameters:

delta_time – Time interval since the last time the function was called in seconds.

property rect: Rect

Return a Rect describing the size of the window.

run(view: View | None = None) None[source]

Run the event loop. Optionally start with a specified view.

After the window has been set up, and the event hooks are in place, this is usually one of the last commands on the main program. This is a blocking function starting pyglet’s event loop meaning it will start to dispatch events such as on_draw and on_update.

Parameters:

view – The view to display when starting the run. Defaults to None.

set_caption(caption) None[source]

Set the caption/title of the window.

set_draw_rate(rate: float) None[source]

Set how often the on_draw function should be run. For example:

# Set the draw rate to 60 frames per second.
set.set_draw_rate(1 / 60)
set_exclusive_keyboard(exclusive=True) None[source]

Capture all keyboard input.

set_exclusive_mouse(exclusive=True) None[source]

Capture the mouse.

set_fullscreen(fullscreen: bool = True, screen=None, mode: ScreenMode | None = None, width: float | None = None, height: float | None = None) None[source]

Change the fullscreen status of the window.

In most cases you simply want:

# Enter fullscreen mode
window.set_fullscreen(True)
# Leave fullscreen mode
window.set_fullscreen(False)

When entering fullscreen mode the window will resize to the screen’s resolution. When leaving fullscreen mode the window will resize back to the size it was before entering fullscreen mode.

Parameters:
  • fullscreen (optional) – Should we enter or leave fullscreen mode?

  • screen (optional) – Which screen should we display on? See get_screens()

  • mode (optional) – The screen will be switched to the given mode. The mode must have been obtained by enumerating Screen.get_modes. If None, an appropriate mode will be selected from the given width and height.

  • width (optional) – Override the width of the window. Will be rounded to int.

  • height (optional) – Override the height of the window. Will be rounded to int.

set_location(x, y) None[source]

Set location of the window.

set_maximum_size(width: int, height: int) None[source]

Sets the maximum size of the window.

This will limit how large the window can be resized.

Parameters:
  • width – Maximum width

  • height – Maximum height

set_minimum_size(width: int, height: int) None[source]

Set the minimum size of the window.

This will limit how small the window can be resized.

Parameters:
  • width – Minimum width

  • height – Minimum height

set_mouse_platform_visible(platform_visible=None) None[source]

Warning

You are probably looking for set_mouse_visible()!

This is a lower level function inherited from the pyglet window.

For more information on what this means, see the documentation for pyglet.window.Window.set_mouse_platform_visible().

set_mouse_visible(visible: bool = True) None[source]

Set whether to show the system’s cursor while over the window

By default, the system mouse cursor is visible whenever the mouse is over the window. To hide the cursor, pass False to this function. Pass True to make the cursor visible again.

The window will continue receiving mouse events while the cursor is hidden, including movements and clicks. This means that functions like on_mouse_motion() and t’on_mouse_press() will continue to work normally.

You can use this behavior to visually replace the system mouse cursor with whatever you want. One example is a game character that is always at the most recent mouse position in the window.

Note

Advanced users can try using system cursor state icons

It may be possible to use system icons representing cursor interaction states such as hourglasses or resize arrows by using features :class:~arcade.Window inherits from the underlying pyglet window class. See the pyglet overview on cursors for more information.

Parameters:

visible – Whether to hide the system mouse cursor

set_size(width: int, height: int) None[source]

Resize the window.

Parameters:
  • width – New width of the window

  • height – New height of the window

set_update_rate(rate: float) None[source]

Set how often the on_update function should be dispatched. For example:

# Set the update rate to 60 times per second.
self.set_update_rate(1 / 60)
Parameters:

rate – Update frequency in seconds

set_visible(visible: bool = True)[source]

Set if the window should be visible or not.

Parameters:

visible (bool) – Should the window be visible?

set_vsync(vsync: bool) None[source]

Set if we sync our draws to the monitors vertical sync rate.

show_view(new_view: View) None[source]

Set the currently active view.

This will hide the current view and show the new view in the next frame.

This is not a blocking call. It will simply point to the new view and return immediately.

Calling this function is the same as setting the arcade.Window.current_view attribute.

Parameters:

new_view – The view to activate.

switch_to() None[source]

Switch the this window context.

This is normally only used in multi-window applications.

test(frames: int = 10) None[source]

Used by unit test cases. Runs the event loop a few times and stops.

Parameters:

frames – How many frames to run the event loop for.

property time: float

Shortcut to the global clock’s time.

This is the time in seconds since the application started.

use() None[source]

Make the window the target for drawing.

The window will always be the target for drawing unless offscreen framebuffers are used in the application.

This simply binds the window’s framebuffer.

property viewport: tuple[int, int, int, int]

Get/set the viewport of the window.

This will define what area of the window is rendered into. The values are x, y, width, height. The value will normally be (0, 0, screen width, screen height).

In most case you don’t want to change this value manually and instead rely on the cameras.

class arcade.View(window: Window | None = None, background_color: tuple[int, int, int] | tuple[int, int, int, int] | None = None)[source]

Bases:

A view is a way to separate drawing and logic from the window itself. Subclassing the window is very inflexible since you can’t easily switch your update and draw logic.

A view is a way to encapsulate that logic, so you can easily switch between different parts of your game. Maybe you have a title screen, a game screen, and a game over screen. Each of these could be a different view.

Parameters:

window (optional) – The window this view is associated with. If None, the current window is used. (Normally you don’t need to provide this).

property background_color: Color | None

Get or set the background color for this view. This affects what color the window will contain when clear() is called.

Examples:

# Use Arcade's built in Color values
view.background_color = arcade.color.AMAZON

# Set the background color with a custom Color instance
MY_RED = arcade.types.Color(255, 0, 0)
view.background_color = MY_RED

# Set the background color directly from an RGBA tuple
view.background_color = 255, 0, 0, 255

# Set the background color directly from an RGB tuple
# RGB tuples will assume 255 as the opacity / alpha value
view.background_color = 255, 0, 0
property center: tuple[float, float]

An alias for arcade.Window.center

property center_x: float

An alias for arcade.Window.center_x

property center_y: float

An alias for arcade.Window.center_y

clear(color: tuple[int, int, int] | tuple[int, int, int, int] | None = None, color_normalized: tuple[float, float, float, float] | None = None, viewport: tuple[int, int, int, int] | None = None) None[source]

Clears the window with the configured background color set through arcade.View.background_color.

Parameters:
  • color (optional) –

    override the current background color with one of the following:

    1. A Color instance

    2. A 3 or 4-length RGB/RGBA tuple of byte values (0 to 255)

  • color_normalized (optional) – Override the current background color using normalized values (0.0 to 1.0). For example, (1.0, 0.0, 0.0, 1.0) making the window contents red.

  • viewport (optional) – The viewport range to clear

property height: float

An alias for arcade.Window.height

on_draw() bool | None[source]

Override this function to add your custom drawing code.

This method is usually called 60 times a second unless another update rate has been set. Should be called after on_update().

This function should normally start with a call to clear() to clear the screen.

on_fixed_update(delta_time: float)[source]

Called for each fixed update. This is useful for physics engines and other systems that should update at a constant rate.

Parameters:

delta_time – Time interval since the last time the function was called in seconds.

on_hide_view() None[source]

Called once when this view is hidden.

on_key_press(symbol: int, modifiers: int) bool | None[source]

Called once when a key gets pushed down.

Override this function to add key press functionality.

Tip

If you want the length of key presses to affect gameplay, you also need to override on_key_release().

Parameters:
  • symbol – Key that was just pushed down

  • modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_key_release(_symbol: int, _modifiers: int) bool | None[source]

Called once when a key gets released.

Override this function to add key release functionality.

Situations that require handling key releases include:

  • Rhythm games where a note must be held for a certain amount of time

  • ‘Charging up’ actions that change strength depending on how long a key was pressed

  • Showing which keys are currently pressed down

Parameters:
  • _symbol – Key that was released

  • _modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_drag(x: int, y: int, dx: int, dy: int, _buttons: int, _modifiers: int) bool | None[source]

Called repeatedly while the mouse moves with a button down.

Override this function to handle dragging.

Parameters:
  • x – x position of mouse

  • y – y position of mouse

  • dx – Change in x since the last time this method was called

  • dy – Change in y since the last time this method was called

  • _buttons – Which button is pressed

  • _modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_enter(x: int, y: int) bool | None[source]

Called once whenever the mouse enters the window area on screen.

This event will not be triggered if the mouse is currently being dragged.

Parameters:
  • x – The x position the mouse entered the window

  • y – The y position the mouse entered the window

on_mouse_leave(x: int, y: int) bool | None[source]

Called once whenever the mouse leaves the window area on screen.

This event will not be triggered if the mouse is currently being dragged. Note that the coordinates of the mouse pointer will be outside of the window rectangle.

Parameters:
  • x – The x position the mouse entered the window

  • y – The y position the mouse entered the window

on_mouse_motion(x: int, y: int, dx: int, dy: int) bool | None[source]

Called repeatedly while the mouse is moving in the window area.

Override this function to respond to changes in mouse position.

Parameters:
  • x – x position of mouse within the window in pixels

  • y – y position of mouse within the window in pixels

  • dx – Change in x since the last time this method was called

  • dy – Change in y since the last time this method was called

on_mouse_press(x: int, y: int, button: int, modifiers: int) bool | None[source]

Called once whenever a mouse button gets pressed down.

Override this function to handle mouse clicks. For an example of how to do this, see Arcade’s built-in aiming and shooting bullets demo.

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

  • button

    What button was pressed. This will always be one of the following:

    • arcade.MOUSE_BUTTON_LEFT

    • arcade.MOUSE_BUTTON_RIGHT

    • arcade.MOUSE_BUTTON_MIDDLE

  • modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_release(x: int, y: int, button: int, modifiers: int) bool | None[source]

Called once whenever a mouse button gets released.

Override this function to respond to mouse button releases. This may be useful when you want to use the duration of a mouse click to affect gameplay.

Parameters:
  • x – x position of mouse

  • y – y position of mouse

  • button

    What button was hit. One of:

    • arcade.MOUSE_BUTTON_LEFT

    • arcade.MOUSE_BUTTON_RIGHT

    • arcade.MOUSE_BUTTON_MIDDLE

  • modifiers – Bitwise ‘and’ of all modifiers (shift, ctrl, num lock) active during this event. See Modifiers.

on_mouse_scroll(x: int, y: int, scroll_x: int, scroll_y: int) bool | None[source]

Called repeatedly while a mouse scroll wheel moves.

Override this function to respond to scroll events. The scroll arguments may be positive or negative to indicate direction, but the units are unstandardized. How many scroll steps you receive may vary wildly between computers depending a number of factors, including system settings and the input devices used (i.e. mouse scrollwheel, touch pad, etc).

Warning

Not all users can scroll easily!

Only some input devices support horizontal scrolling. Standard vertical scrolling is common, but some laptop touch pads are hard to use.

This means you should be careful about how you use scrolling. Consider making it optional to maximize the number of people who can play your game!

Parameters:
  • x – x position of mouse

  • y – y position of mouse

  • scroll_x – number of steps scrolled horizontally since the last call of this function

  • scroll_y – number of steps scrolled vertically since the last call of this function

on_resize(width: int, height: int) bool | None[source]

Override this method to add custom actions when the window is resized.

An internal _on_resize is called first adjusting the viewport to the new size of the window so there is no need to call `super().on_resize(width, height)`.

Parameters:
  • width – New width of the window

  • height – New height of the window

on_show_view() None[source]

Called once when the view is shown.

See also

on_hide_view()

on_update(delta_time: float) bool | None[source]

This method can be implemented and is reserved for game logic. Move sprites. Perform collision checks and other game logic. This method is called every frame before on_draw().

The delta_time can be used to make sure the game runs at the same speed, no matter the frame rate.

Parameters:

delta_time – Time interval since the last time the function was called in seconds.

property size: tuple[float, float]

An alias for arcade.Window.size

property width: float

An alias for arcade.Window.width

arcade.get_screens() list[Screen][source]

Return a list of screens. So for a two-monitor setup, this should return a list of two screens. Can be used with arcade.Window to select which window we full-screen on.

Returns:

List of screens, one for each monitor.

arcade.open_window(width: int, height: int, window_title: str | None = None, resizable: bool = False, antialiasing: bool = True, **kwargs) Window[source]

Shortcut for opening/creating a window with less options.

For a full set of window options, create a Window instance directly.

Parameters:
  • width – Width of the window.

  • height – Height of the window.

  • window_title – Title/caption of the window.

  • resizable – Whether the user can resize the window.

  • antialiasing – Whether to use antialiasing

  • **kwargs – Additional keyword arguments to pass to the window constructor.

arcade.get_display_size(screen_id: int = 0) tuple[int, int][source]

Return the width and height of a monitor.

The size of the primary monitor is returned by default.

Parameters:

screen_id – The screen number

Returns:

Tuple containing the width and height of the screen

arcade.get_window() Window[source]

Return a handle to the current window.

Returns:

Handle to the current window.

arcade.set_window(window: Window | None) None[source]

Set a handle to the current window.

Parameters:

window – Handle to the current window.

arcade.close_window() None[source]

Closes the current window, and then runs garbage collection. The garbage collection is necessary to prevent crashing when opening/closing windows rapidly (usually during unit tests).

arcade.run(view: View | None = None) None[source]

Run the main loop. Optionally start with a specified view.

After the window has been set up, and the event hooks are in place, this is usually one of the last commands on the main program. This is a blocking function starting pyglet’s event loop meaning it will start to dispatch events such as on_draw and on_update.

Parameters:

view – The view to display when starting the run. Defaults to None.

arcade.exit() None[source]

Exits the application.

arcade.start_render(pixelated=False, blend=True) None[source]

Start recording drawing functions into an offscreen buffer. Call arcade.finish_render() to stop recording. The start_render/finish_render calls can only be called once.

When running Arcade this buffer will be presented to the screen.

A few configuration options are available in this function.

Parameters:
  • pixelated – If True, the buffer will be be pixelated when resized. Otherwise, it will be smooth.

  • blend – If alpha blending

arcade.finish_render() None[source]

Stop recording drawing functions into an offscreen buffer. arcade.start_render() should be called before this function.

arcade.run() can be called after this function to present the buffer.

arcade.set_background_color(color: tuple[int, int, int, int]) None[source]

Set the color arcade.Window.clear() will use when clearing the window. This only needs to be called when the background color changes.

Note

A shorter and faster way to set background color is using arcade.Window.background_color.

Examples:

# Use Arcade's built in color values
arcade.set_background_color(arcade.color.AMAZON)

# Specify RGB value directly (red)
arcade.set_background_color((255, 0, 0))
Parameters:

color – List of 3 or 4 values in RGB/RGBA format.

arcade.schedule(function_pointer: Callable, interval: float)[source]

Schedule a function to be automatically called every interval seconds. The function/callable needs to take a delta time argument similar to on_update. This is a float representing the number of seconds since it was scheduled or called.

A function can be scheduled multiple times, but this is not recommended.

Warning

Scheduled functions should always be unscheduled using arcade.unschedule(). Having lingering scheduled functions will lead to crashes.

Example:

def some_action(delta_time):
    print(delta_time)

# Call the function every second
arcade.schedule(some_action, 1)
# Unschedule
Parameters:
  • function_pointer – Pointer to the function to be called.

  • interval – Interval to call the function (float or integer)

arcade.unschedule(function_pointer: Callable)[source]

Unschedule a function being automatically called.

Example:

def some_action(delta_time):
    print(delta_time)

arcade.schedule(some_action, 1)
arcade.unschedule(some_action)
Parameters:

function_pointer – Pointer to the function to be unscheduled.

arcade.schedule_once(function_pointer: Callable, delay: float)[source]

Schedule a function to be automatically called once after delay seconds. The function/callable needs to take a delta time argument similar to on_update. This is a float representing the number of seconds since it was scheduled or called.

Example:

def some_action(delta_time):
    print(delta_time)

# Call the function once after 1 second
arcade.schedule_one(some_action, 1)
Parameters:
  • function_pointer – Pointer to the function to be called.

  • delay – Delay in seconds

class arcade.Section(left: int | float, bottom: int | float, width: int | float, height: int | float, *, name: str | None = None, accept_keyboard_keys: bool | Iterable = True, accept_mouse_events: bool | Iterable = True, prevent_dispatch: Iterable | bool | None = None, prevent_dispatch_view: Iterable | bool | None = None, local_mouse_coordinates: bool = False, enabled: bool = True, modal: bool = False, draw_order: int = 1)[source]

Bases:

A Section represents a rectangular portion of the viewport Events are dispatched to the section based on it’s position on the screen.

A section can only be added to a single SectionManager.

Parameters:
  • left – the left position of this section

  • bottom – the bottom position of this section

  • width – the width of this section

  • height – the height of this section

  • name – the name of this section

  • accept_keyboard_keys (bool | Iterable) – whether this section captures keyboard keys through. keyboard events. If the param is an iterable means the keyboard keys that are captured in press/release events: for example: [arcade.key.UP, arcade.key.DOWN] will only capture this two keys

  • accept_mouse_events (bool Iterable) – whether this section captures mouse events. If the param is an iterable means the mouse events that are captured. for example: ['on_mouse_press', 'on_mouse_release'] will only capture this two events.

  • prevent_dispatch – a list of event names that will not be dispatched to subsequent sections. You can pass None (default) or {True} to prevent the dispatch of all events.

  • prevent_dispatch_view – a list of event names that will not be dispatched to the view. You can pass None (default) or {True} to prevent the dispatch of all events to the view.

  • local_mouse_coordinates – if True the section mouse events will receive x, y coordinates section related to the section dimensions and position (not related to the screen)

  • enabled – if False the section will not capture any events

  • modal – if True the section will be a modal section: will prevent updates and event captures on other sections. Will also draw last (on top) but capture events first.

  • draw_order – The order this section will have when on_draw is called. The lower the number the earlier this will get draw. This can be different from the event capture order or the on_update order which is defined by the insertion order.

accept_keyboard_keys: bool | Iterable

Arcade keyboard keys to accept.

accept_mouse_events: bool | Iterable

Arcade mouse events to accept.

block_updates: bool

if True ‘update’ and ‘on_update’ will not trigger in this section

property bottom: int | float

The bottom edge of this section

camera: Projector | None

optional section camera

property draw_order: int

Returns the draw order state The lower the number the earlier this section will get draw

property enabled: bool

Enables or disables this section

get_xy_screen_relative(section_x: int, section_y: int)[source]

Returns screen coordinates from section coordinates

Parameters:
  • section_x – The x position of the section

  • section_y – The y position of the section

get_xy_section_relative(screen_x: int, screen_y: int)[source]

returns section coordinates from screen coordinates

Parameters:
  • screen_x – The x position of the screen

  • screen_y – The y position of the screen

property height: int | float

The height of this section

property left: int | float

Left edge of this section

local_mouse_coordinates: bool

mouse coordinates relative to section

property modal: bool

Returns the modal state (Prevent the following sections from receiving input events and updating)

mouse_is_on_top(x: int, y: int) bool[source]

Check if the current mouse position is on top of this section

Parameters:
  • x – The x position of the mouse

  • y – The y position of the mouse

name: str | None

The name of this section

on_draw()[source]

Override this method with your custom drawing code.

on_hide_section()[source]

Called when the section is hidden

on_key_press(symbol: int, modifiers: int)[source]

Called when the user presses a key.

Parameters:
  • symbol – the key pressed

  • modifiers – the modifiers pressed

on_key_release(_symbol: int, _modifiers: int)[source]

Called when the user releases a key.

Parameters:
  • _symbol – the key released

  • _modifiers – the modifiers pressed

on_mouse_drag(x: int, y: int, dx: int, dy: int, _buttons: int, _modifiers: int)[source]

Called when the user moves the mouse with a button pressed.

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

  • dx – change in x position

  • dy – change in y position

on_mouse_enter(x: int, y: int)[source]

Called when the mouse enters the section

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

on_mouse_leave(x: int, y: int)[source]

Called when the mouse leaves the section

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

on_mouse_motion(x: int, y: int, dx: int, dy: int)[source]

Called when the user moves the mouse.

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

  • dx – change in x position

  • dy – change in y position

on_mouse_press(x: int, y: int, button: int, modifiers: int)[source]

Called when the user presses a mouse button.

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

  • button – the button pressed

  • modifiers – the modifiers pressed

on_mouse_release(x: int, y: int, button: int, modifiers: int)[source]

Called when the user releases a mouse button.

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

  • button – the button released

  • modifiers – the modifiers pressed

on_mouse_scroll(x: int, y: int, scroll_x: int, scroll_y: int)[source]

Called when the user scrolls the mouse wheel.

Parameters:
  • x – x position of the mouse

  • y – y position of the mouse

  • scroll_x – change in x position

  • scroll_y – change in y position

on_resize(width: int, height: int)[source]

Override this method with your custom resize code.

on_show_section()[source]

Called when the section is shown

on_update(delta_time: float)[source]

Override this method with your custom update code.

overlaps_with(section: Section) bool[source]

Checks if this section overlaps with another section

Parameters:

section – The section to check for overlap

property rect: Rect

The section rectangle of this view

property right: int | float

Right edge of this section

property section_manager: SectionManager | None

Returns the section manager this section is added to

should_receive_mouse_event(x: int, y: int) bool[source]

Check if the current section should receive a mouse event at a given position

Parameters:
  • x – The x position of the mouse

  • y – The y position of the mouse

property top: int | float

Top edge of this section

property view

The view this section is set on

property width: int | float

The width of this section

property window

The view window

class arcade.SectionManager(view: View)[source]

Bases:

This manages the different Sections a View has. Actions such as dispatching the events to the correct Section, draw order, etc.

Parameters:

view – the view this section manager belongs to

add_section(section: Section, at_index: int | None = None, at_draw_order: int | None = None) None[source]

Adds a section to this Section Manager Will trigger section.on_show_section if section is enabled

Parameters:
  • section – The section to add to this section manager

  • at_index – Inserts the section at that index for event capture and update events. If None at the end

  • at_draw_order – Inserts the section in a specific draw order. Overwrites section.draw_order

clear_sections() None[source]

Removes all sections and calls on_hide_section for each one if enabled

disable() None[source]

Disable all sections Disabling a section will trigger section.on_hide_section

disable_all_keyboard_events() None[source]

Removes the keyboard event handling from all sections

dispatch_keyboard_event(event: str, *args, **kwargs) bool | None[source]

Generic method to dispatch keyboard events to the correct sections

Parameters:
  • event – the keyboard event name to dispatch

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

dispatch_mouse_enter_leave_events(event_origin: str, x: int, y: int, *args, **kwargs) bool | None[source]

This helper method will dispatch mouse enter / leave events to sections based on ‘on_mouse_motion’ and ‘on_mouse_drag’ events. Will also dispatch the event (event_origin) that called this method

Parameters:
  • event_origin – The mouse event name that called this method. This event will be called here.

  • x – The x axis coordinate

  • y – The y axis coordinate

  • args – Any other position arguments that should be delivered to the dispatched event

  • kwargs – Any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

dispatch_mouse_event(event: str, x: int, y: int, *args, current_section: Section | None = None, **kwargs) bool | None[source]

Generic method to dispatch mouse events to the correct Sections

Parameters:
  • event – the mouse event name to dispatch

  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • current_section – the section this mouse event should be delivered to. If None, will retrieve all sections that should receive this event based on x, y coordinates

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

enable() None[source]

Registers event handlers to the window and enables all sections.

Enabling a section will trigger section.on_show_section

get_first_section(x: int, y: int, *, event_capture: bool = True) Section | None[source]

Returns the first section based on x,y position

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • event_capture – True will use event capture dimensions, False will use section draw size

Returns:

A section if match the params otherwise None

get_section_by_name(name: str) Section | None[source]

Returns the first section with the given name

Parameters:

name – The name of the section you want

Returns:

The first section with the provided name. None otherwise

get_sections(x: int, y: int, *, event_capture: bool = True) Generator[Section, None, None][source]

Returns a list of sections based on x,y position

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • event_capture – True will use event capture dimensions, False will use section draw size

Returns:

A generator with the sections that match the params

property has_sections: bool

Returns true if this section manager has sections

property is_current_view: bool

Returns if this section manager view is the current on the view window a.k.a.: is the view that is currently being shown

on_draw() bool[source]

Called on each event loop to draw.

It automatically calls camera.use() for each section that has a camera and resets the camera effects by calling the default SectionManager camera afterward if needed. The SectionManager camera defaults to a camera that has the viewport and projection for the whole screen.

This method will consume the on_draw event, to prevent further on_draw calls on the view.

on_key_press(*args, **kwargs) bool | None[source]

Triggers the on_key_press event on the appropriate sections or view

Parameters:
  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_key_release(*args, **kwargs) bool | None[source]

Triggers the on_key_release event on the appropriate sections or view

Parameters:
  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_mouse_drag(x: int, y: int, *args, **kwargs) bool | None[source]

This method dispatches the on_mouse_drag and also calculates if on_mouse_enter/leave should be fired.

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_mouse_enter(x: int, y: int, *args, **kwargs) bool | None[source]

Triggered when the mouse enters the window space Will trigger on_mouse_enter on the appropriate sections or view

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_mouse_leave(x: int, y: int, *args, **kwargs) bool | None[source]

Triggered when the mouse leaves the window space Will trigger on_mouse_leave on the appropriate sections or view

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_mouse_motion(x: int, y: int, *args, **kwargs) bool | None[source]

This method dispatches the on_mouse_motion and also calculates if on_mouse_enter/leave should be fired.

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_mouse_press(x: int, y: int, *args, **kwargs) bool | None[source]

Triggers the on_mouse_press event on the appropriate sections or view

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_mouse_release(x: int, y: int, *args, **kwargs) bool | None[source]

Triggers the on_mouse_release event on the appropriate sections or view

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_mouse_scroll(x: int, y: int, *args, **kwargs) bool | None[source]

Triggers the on_mouse_scroll event on the appropriate sections or view

Parameters:
  • x – the x axis coordinate

  • y – the y axis coordinate

  • args – any other position arguments that should be delivered to the dispatched event

  • kwargs – any other keyword arguments that should be delivered to the dispatched event

Returns:

EVENT_HANDLED or EVENT_UNHANDLED, or whatever the dispatched method returns

on_resize(width: int, height: int) bool[source]

Called when the window is resized.

Parameters:
  • width – the new width of the screen

  • height – the new height of the screen

on_update(delta_time: float) bool[source]

Called on each event loop.

Parameters:

delta_time – the delta time since this method was called last time

remove_section(section: Section) None[source]

Removes a section from this section manager

Parameters:

section – The section to remove

property sections: list[Section]

Property that returns the list of sections

sort_section_event_order() None[source]

This will sort sections on event capture order (and update) based on insertion order and section.modal.

sort_sections_draw_order() None[source]

This will sort sections on draw order based on section.draw_order and section.modal

arcade.get_pixel(x: int, y: int, components: int = 3) tuple[int, ...][source]

Given an x, y, will return a color value of that point.

Parameters:
  • x – x location

  • y – y location

  • components – Number of components to fetch. By default we fetch 3 3 components (RGB). 4 components would be RGBA.

arcade.get_image(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None, components: int = 4) Image[source]

Get an image from the screen.

Example:

# Create and image of the entire screen and save it to a file
image = arcade.get_image()
image.save('screenshot.png')
Parameters:
  • x – Start (left) x location

  • y – Start (bottom) y location

  • width – Width of image. Leave blank for grabbing the ‘rest’ of the image

  • height – Height of image. Leave blank for grabbing the ‘rest’ of the image

  • components – Number of components to fetch. By default we fetch 4 (4=RGBA, 3=RGB)