Python Arcade Library

Common errors

• error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools"

  cause This error occurs on Windows when `pip install arcade` attempts to compile a dependency (like `pymunk`) from source, and the necessary C++ build tools are missing.
  fix Install 'Desktop development with C++' workload from Visual Studio Installer (Community edition is free), or specifically install 'Microsoft C++ Build Tools' from `https://visualstudio.microsoft.com/visual-cpp-build-tools/`.

• AttributeError: module 'arcade' has no attribute 'Scene'

  cause Users attempting to directly import `Scene` or other core classes that are meant to be inherited from `arcade.Window` or `arcade.View` (or were part of internal restructuring).
  fix Ensure you are using the correct object-oriented pattern, typically by subclassing `arcade.Window` or `arcade.View` for game states. If you're looking for a Scene *manager*, it's often built around `arcade.View` transitions.

• bash: arcade: command not found

  cause The `arcade` command (used to get environment info or run examples) or Python interpreter cannot find the installed `arcade` package. This often happens if a virtual environment is not activated or `arcade` was not installed successfully in the current environment.
  fix Activate your Python virtual environment (if using one). Re-run `pip install arcade` to ensure the library is correctly installed. Verify installation by running `python -c "import arcade; print(arcade.__version__)"`.

• Window not created yet. Call `arcade.open_window()` or subclass `arcade.Window` before using this function.

  cause An Arcade drawing or OpenGL-dependent function was called before an `arcade.Window` was created and made current. Many Arcade operations require an active OpenGL context.
  fix Ensure `arcade.open_window()` is called or an `arcade.Window` subclass is instantiated and `arcade.run()` is invoked before attempting drawing or other context-dependent operations. In object-oriented setup, ensure drawing/setup code runs within `__init__`, `setup()`, or `on_draw()` methods of your `arcade.Window` subclass.

Warnings

• breaking Arcade 3.x introduced significant breaking changes compared to 2.x, especially in GUI, Sprite, and drawing APIs. Key changes include removal of `Sprite.draw()`, `Sprite.on_update()` (now unified `update`), and `Sprite.set_position()`. The `arcade.draw` module was restructured into submodules.
  Fix: Consult the official migration guide for 3.x if upgrading from 2.x. Update code to use new `Sprite` methods (e.g., `update()` for logic), new drawing primitives (e.g., `arcade.gui` for UI components), and revised camera logic.
• gotcha Arcade requires OpenGL 3.3+ support, which means it will not run on environments like Raspberry Pi or Wayland without specific (and often complex) workarounds or hardware acceleration.
  Fix: Ensure your system's graphics drivers and hardware meet OpenGL 3.3+ requirements. For Linux, X11 is generally recommended over Wayland for best compatibility.
• gotcha Direct interaction with OpenGL objects (e.g., creating textures or buffers) from non-main threads can lead to errors, as OpenGL is not thread-safe. Python's garbage collector can sometimes trigger OpenGL object releases from other threads.
  Fix: Avoid manipulating OpenGL-related objects (like `arcade.gl.Texture`, `arcade.gl.Buffer`) from background threads. If using threads, ensure any OpenGL object creation/destruction happens on the main thread, or manage OpenGL garbage collection explicitly using `gc_mode='context_gc'` when creating `arcade.Window` and calling `ctx.gc()` manually.
• deprecated The `arcade.quick_run` function was removed as it had no useful purpose and encouraged less structured code.
  Fix: Replace calls to `arcade.quick_run()` with the standard `arcade.run()` function within an `arcade.Window` class structure, as shown in the quickstart example.

Install

• pip install arcade Install stable version
• pip install --pre arcade Install pre-release/development version

Imports

• arcade

  import arcade

• Window
  wrong:

  from arcade import Window
  class MyGame(Window): ...

  correct:

  import arcade
  class MyGame(arcade.Window): ...

  While 'from arcade import Window' works, the idiomatic and often safer way for Arcade classes is to use 'arcade.Window' to avoid name collisions and maintain clarity, especially for beginners.

Quickstart

This quickstart code initializes an Arcade window with a specified size and title, sets a background color, and then draws a red filled circle in the `on_draw` method. The `arcade.run()` call starts the game loop.

import arcade

SCREEN_WIDTH = 800
SCREEN_HEIGHT = 600
SCREEN_TITLE = "My Arcade Game"

class MyGame(arcade.Window):
    def __init__(self):
        super().__init__(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE)
        arcade.set_background_color(arcade.color.AMAZON)

    def on_draw(self):
        self.clear()
        arcade.draw_circle_filled(100, 100, 50, arcade.color.RED)

def main():
    game = MyGame()
    arcade.run()

if __name__ == "__main__":
    main()