Window and View

arcade.close_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.create_orthogonal_projection

arcade.create_orthogonal_projection(left, right, bottom, top, near=1, far=- 1) pyglet.math.Mat4[source]

Creates an orthogonal projection matrix. Used internally with the OpenGL shaders.

Parameters
  • left (float) – The left of the near plane relative to the plane’s center.

  • right (float) – The right of the near plane relative to the plane’s center.

  • top (float) – The top of the near plane relative to the plane’s center.

  • bottom (float) – The bottom of the near plane relative to the plane’s center.

  • near (float) – The distance of the near plane from the camera’s origin. It is recommended that the near plane is set to 1.0 or above to avoid rendering issues at close range.

  • far (float) – The distance of the far plane from the camera’s origin.

Returns

A projection matrix representing the specified orthogonal perspective.

Return type

Mat4

arcade.exit

arcade.exit()[source]

Exits the application.

arcade.finish_render

arcade.finish_render()[source]

Swap buffers and displays what has been drawn. If programs use derive from the Window class, this function is automatically called.

arcade.get_display_size

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 (int) – The screen number

Returns

Tuple containing the width and height of the screen

Return type

tuple

arcade.get_projection

arcade.get_projection() pyglet.math.Mat4[source]

Returns the current projection matrix used by sprites and shapes in arcade.

This is a shortcut for `window.ctx.projection_2d_matrix.

Returns

Projection matrix

Return type

Mat4

arcade.get_scaling_factor

arcade.get_scaling_factor(window: Window = None) float[source]

Gets the scaling factor of the given Window. This is the ratio between the window and framebuffer size. If no window is supplied the currently active window will be used.

Parameters

window (Window) – Handle to window we want to get scaling factor of.

Returns

Scaling factor. E.g., 2.0 would indicate the framebuffer width and height being 2.0 times the window width and height. This means one “window pixel” is actual a 2 x 2 square of pixels in the framebuffer.

Return type

float

arcade.get_viewport

arcade.get_viewport() Tuple[float, float, float, float][source]

Get the current viewport settings.

Returns

Tuple of floats, with (left, right, bottom, top)

arcade.get_window

arcade.get_window() Window[source]

Return a handle to the current window.

Returns

Handle to the current window.

arcade.pause

arcade.pause(seconds: numbers.Number) None[source]

Pause for the specified number of seconds. This is a convenience function that just calls time.sleep()

Parameters

seconds (float) – Time interval to pause in seconds.

arcade.quick_run

arcade.quick_run(time_to_pause: numbers.Number)[source]

Only run the application for the specified time in seconds. Useful for unit testing or continuous integration (CI) testing where there is no user interaction.

Parameters

time_to_pause (Number) – Number of seconds to pause before automatically closing.

arcade.run

arcade.run()[source]

Run the main loop. 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.

arcade.schedule

arcade.schedule(function_pointer: Callable, interval: numbers.Number)[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 (Callable) – Pointer to the function to be called.

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

arcade.set_background_color

arcade.set_background_color(color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]]) None[source]

Specifies the background color of the window. This value will persist for every future screen clears until changed.

Parameters

color (Color) – List of 3 or 4 bytes in RGB/RGBA format.

arcade.set_viewport

arcade.set_viewport(left: float, right: float, bottom: float, top: float) None[source]

This sets what coordinates the window will cover.

Tip

Beginners will want to use Camera. It provides easy to use support for common tasks such as screenshake and movement to a destination.

If you are making a game with complex control over the viewport, this function can help.

By default, the lower left coordinate will be (0, 0), the top y coordinate will be the height of the window in pixels, and the right x coordinate will be the width of the window in pixels.

Warning

Be careful of fractional or non-multiple values!

It is recommended to only set the viewport to integer values that line up with the pixels on the screen. Otherwise, tiled pixel art may not line up well during render, creating rectangle artifacts.

Note

Window.on_resize calls set_viewport by default. If you want to set your own custom viewport during the game, you may need to over-ride this function.

For more advanced users: This functions sets the orthogonal projection used by shapes and sprites. It also updates the viewport to match the current screen resolution. window.ctx.projection_2d (projection_2d()) and window.ctx.viewport (viewport()) can be used to set viewport and projection separately.

Parameters
  • left (Number) – Left-most (smallest) x value.

  • right (Number) – Right-most (largest) x value.

  • bottom (Number) – Bottom (smallest) y value.

  • top (Number) – Top (largest) y value.

arcade.set_window

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

Set a handle to the current window.

Parameters

window (Window) – Handle to the current window.

arcade.start_render

arcade.start_render() None[source]

Clears the window. Can also be replaced with clear().

arcade.unschedule

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 (Callable) – Pointer to the function to be unscheduled.

arcade.NoOpenGLException

class arcade.NoOpenGLException[source]

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

arcade.View

class arcade.View(window: Optional[arcade.application.Window] = None)[source]

Support different views/screens in a window.

on_draw()[source]

Called when this view should draw

on_hide_view()[source]

Called when this view is not shown anymore

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

Override this function to add key press functionality.

Parameters
  • symbol (int) – Key that was hit

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

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

Override this function to add key release functionality.

Parameters
  • _symbol (int) – Key that was hit

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

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

Override this function to add mouse button functionality.

Parameters
  • x (float) – x position of mouse

  • y (float) – y position of mouse

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

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

  • _buttons (int) – Which button is pressed

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

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

Override this function to add mouse functionality.

Parameters
  • x (float) – x position of mouse

  • y (float) – y position of mouse

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

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

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

Override this function to add mouse button functionality.

Parameters
  • x (float) – x position of the mouse

  • y (float) – y position of the mouse

  • button (int) – What button was hit. One of: arcade.MOUSE_BUTTON_LEFT, arcade.MOUSE_BUTTON_RIGHT, arcade.MOUSE_BUTTON_MIDDLE

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

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

Override this function to add mouse button functionality.

Parameters
  • x (float) –

  • y (float) –

  • button (int) –

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

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

User moves the scroll wheel.

Parameters
  • x (int) –

  • y (int) –

  • scroll_x (int) –

  • scroll_y (int) –

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

Called when the window is resized while this view is active. on_resize() is also called separately. By default this method does nothing and can be overridden to handle resize logic.

on_show()[source]

Called when this view is shown and if window dispatches a on_show event. (first time showing window or resize)

on_show_view()[source]

Called when this view is shown

on_update(delta_time: float)[source]

To be overridden

update(delta_time: float)[source]

To be overridden

arcade.Window

class arcade.Window(width: int = 800, height: int = 600, title: str = 'Arcade Window', fullscreen: bool = False, resizable: bool = False, update_rate: Optional[float] = 0.016666666666666666, antialiasing: bool = True, gl_version: Tuple[int, int] = (3, 3), screen: Optional[pyglet.canvas.base.Screen] = None, style: Optional[str] = None, visible: bool = True, vsync: bool = False, gc_mode: str = 'context_gc', center_window: bool = False)[source]

The Window class forms the basis of most advanced games that use Arcade. It represents a window on the screen, and manages events.

Parameters
  • width (int) – Window width

  • height (int) – Window height

  • title (str) – Title (appears in title bar)

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

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

  • update_rate (float) – How frequently to update the window.

  • antialiasing (bool) – Should OpenGL’s anti-aliasing be enabled?

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

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

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

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

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

activate()[source]

Activate this window.

property background_color

Get or set the background color for this window.

If the background color is an RGB value instead of RGBA` we assume alpha value 255.

Type

Color

center_window()[source]

Center the window on the screen.

clear(color: Optional[Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]]] = None)[source]

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

Parameters

color (Color) – Optional color overriding the current background color

close()[source]

Close the Window.

property ctx: arcade.context.ArcadeContext

The OpenGL context for this window.

Type

arcade.ArcadeContext

property current_view: Optional[arcade.application.View]

This property returns the current view being shown. To set a different view, call the arcade.Window.show_view() method.

Return type

arcade.View

dispatch_events()[source]

Dispatch events

flip()[source]

Window framebuffers norally have a back and front buffer. This method makes the back buffer visible and hides the front buffer. A frame is rendered into the back buffer, so this method displays the frame we currently worked on.

This method also garbage collect OpenGL resources before swapping the buffers.

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

Return the X/Y coordinates of the window

Returns

x, y of window location

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

Get the size of the window.

Returns

(width, height)

get_system_mouse_cursor(name)[source]

Get the system mouse cursor

get_viewport() Tuple[float, float, float, float][source]

Get the viewport. (What coordinates we can see.)

hide_view()[source]

Hide the currently active view (if any) returning us back to on_draw and on_update functions in the window.

This is not necessary to call if you are switching views. Simply call show_view again.

maximize()[source]

Maximize the window.

minimize()[source]

Minimize the window.

on_draw()[source]

Override this function to add your custom drawing code.

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

Override this function to add key press functionality.

Parameters
  • symbol (int) – Key that was hit

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

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

Override this function to add key release functionality.

Parameters
  • symbol (int) – Key that was hit

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

on_mouse_drag(x: float, y: float, dx: float, dy: float, buttons: int, modifiers: int)[source]

Override this function to add mouse button functionality.

Parameters
  • x (float) – x position of mouse

  • y (float) – y position of mouse

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

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

  • buttons (int) – Which button is pressed

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

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

Override this function to add mouse functionality.

Parameters
  • x (float) – x position of mouse

  • y (float) – y position of mouse

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

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

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

Override this function to add mouse button functionality.

Parameters
  • x (float) – x position of the mouse

  • y (float) – y position of the mouse

  • button (int) – What button was hit. One of: arcade.MOUSE_BUTTON_LEFT, arcade.MOUSE_BUTTON_RIGHT, arcade.MOUSE_BUTTON_MIDDLE

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

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

Override this function to add mouse button functionality.

Parameters
  • x (float) –

  • y (float) –

  • button (int) –

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

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

User moves the scroll wheel.

Parameters
  • x (int) –

  • y (int) –

  • scroll_x (int) –

  • scroll_y (int) –

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

Override this function to add custom code to be called any time the window is resized. The main responsibility of this method is updating the projection and the viewport.

If you are not changing the default behavior when overriding, make sure you call the parent’s on_resize first:

def on_resize(self, width: int, height: int):
    super().on_resize(width, height)
    # Add extra resize logic here
Parameters
  • width (int) – New width

  • height (int) – New height

on_update(delta_time: float)[source]

Move everything. Perform collision checks. Do all the game logic here.

Parameters

delta_time (float) – Time interval since the last time the function was called.

run()[source]

Shortcut for arcade.run().

For example:

MyWindow().run()
set_caption(caption)[source]

Set the caption for the window.

set_exclusive_keyboard(exclusive=True)[source]

Capture all keyboard input.

set_exclusive_mouse(exclusive=True)[source]

Capture the mouse.

set_fullscreen(fullscreen: bool = True, screen: Optional[arcade.application.Window] = None, mode: Optional[pyglet.canvas.base.ScreenMode] = None, width: Optional[float] = None, height: Optional[float] = None)[source]

Set if we are full screen or not.

Parameters
  • fullscreen (bool) –

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

  • mode (pyglet.canvas.ScreenMode) – 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 (int) –

  • height (int) –

set_location(x, y)[source]

Set location of the window.

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

Wrap the Pyglet window call to set maximum size

Parameters
  • width (int) – width in pixels.

  • height (int) – height in pixels.

Raises ValueError

set_maximum_size(width, height)[source]

Set largest window size.

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

Wrap the Pyglet window call to set minimum size

Parameters
  • width (float) – width in pixels.

  • height (float) – height in pixels.

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

Set smallest window size.

set_mouse_platform_visible(platform_visible=None)[source]

This does something.

set_mouse_visible(visible: bool = True)[source]

If true, user can see the mouse cursor while it is over the window. Set false, the mouse is not visible. Default is true.

Parameters

visible (bool) –

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

Ignore the resizable flag and set the size

Parameters
  • width (int) –

  • height (int) –

set_update_rate(rate: float)[source]

Set how often the screen should be updated. For example, self.set_update_rate(1 / 60) will set the update rate to 60 fps

Parameters

rate (float) – Update frequency in seconds

set_viewport(left: float, right: float, bottom: float, top: float)[source]

Set the viewport. (What coordinates we can see. Used to scale and/or scroll the screen).

See arcade.set_viewport() for more detailed information.

Parameters
  • left (Number) –

  • right (Number) –

  • bottom (Number) –

  • top (Number) –

set_visible(visible: bool = True)[source]

Set if the window is visible or not. Normally, a program’s window is visible.

Parameters

visible (bool) –

set_vsync(vsync: bool)[source]

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

show_view(new_view: arcade.application.View)[source]

Select the view to show in the next frame. This is not a blocking call showing the view. Your code will continue to run after this call and the view will appear in the next dispatch of on_update/on_draw`.

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

Parameters

new_view (View) – View to show

switch_to()[source]

Switch the this window.

test(frames: int = 10)[source]

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

Parameters

frames (int) –

update(delta_time: float)[source]

Move everything. For better consistency in naming, use on_update instead.

Parameters

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

use()[source]

Bind the window’s framebuffer for rendering commands

arcade.get_screens

arcade.get_screens()[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.

Return type

List

arcade.open_window

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

This function opens a window. For ease-of-use we assume there will only be one window, and the programmer does not need to keep a handle to the window. This isn’t the best architecture, because the window handle is stored in a global, but it makes things easier for programmers if they don’t have to track a window pointer.

Parameters
  • width (Number) – Width of the window.

  • height (Number) – Height of the window.

  • window_title (str) – Title of the window.

  • resizable (bool) – Whether the window can be user-resizable.

  • antialiasing (bool) – Smooth the graphics?

Returns

Handle to window

Return type

Window