0
# Arcade
1

2
A comprehensive Python 2D game development library that provides a complete framework for creating games, simulations, and interactive applications. Arcade offers modern OpenGL rendering, comprehensive sprite management, multiple physics engines, built-in GUI framework, and extensive drawing capabilities for both beginners and advanced developers.
3

4
## Package Information
5

6
- **Package Name**: arcade
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install arcade`
10
- **Version**: 3.3.2
11

12
## Core Imports
13

14
```python
15
import arcade
16
```
17

18
For specific functionality:
19

20
```python
21
from arcade import gui, math, color, key, types
22
from arcade.gl import Context, Buffer, Program
23
from arcade.camera import Camera2D
24
```
25

26
## Basic Usage
27

28
```python
29
import arcade
30

31
class GameWindow(arcade.Window):
32
    def __init__(self, width=800, height=600, title="Game"):
33
        super().__init__(width, height, title)
34
        arcade.set_background_color(arcade.color.AMAZON)
35
        
36
        # Initialize sprite lists
37
        self.player_list = None
38
        self.wall_list = None
39
        
40
    def setup(self):
41
        # Create sprite lists
42
        self.player_list = arcade.SpriteList()
43
        self.wall_list = arcade.SpriteList()
44
        
45
        # Create player sprite
46
        self.player_sprite = arcade.Sprite(":resources:images/animated_characters/female_adventurer/femaleAdventurer_idle.png", 0.5)
47
        self.player_sprite.center_x = 64
48
        self.player_sprite.center_y = 120
49
        self.player_list.append(self.player_sprite)
50
        
51
    def on_draw(self):
52
        self.clear()
53
        
54
        # Draw all sprite lists
55
        self.player_list.draw()
56
        self.wall_list.draw()
57
        
58
        # Draw some shapes
59
        arcade.draw_circle_filled(300, 300, 50, arcade.color.RED)
60
        arcade.draw_rectangle_filled(400, 300, 100, 80, arcade.color.BLUE)
61
        
62
    def on_key_press(self, key, modifiers):
63
        if key == arcade.key.UP:
64
            self.player_sprite.change_y = 5
65
        elif key == arcade.key.DOWN:
66
            self.player_sprite.change_y = -5
67
        elif key == arcade.key.LEFT:
68
            self.player_sprite.change_x = -5
69
        elif key == arcade.key.RIGHT:
70
            self.player_sprite.change_x = 5
71
            
72
    def on_key_release(self, key, modifiers):
73
        if key in (arcade.key.UP, arcade.key.DOWN):
74
            self.player_sprite.change_y = 0
75
        elif key in (arcade.key.LEFT, arcade.key.RIGHT):
76
            self.player_sprite.change_x = 0
77
            
78
    def on_update(self, delta_time):
79
        # Update sprite positions
80
        self.player_list.update()
81

82
# Create and run the game
83
def main():
84
    window = GameWindow()
85
    window.setup()
86
    arcade.run()
87

88
if __name__ == "__main__":
89
    main()
90
```
91

92
## Architecture
93

94
Arcade is built around several core architectural components:
95

96
### Artist Hierarchy
97
- **Window**: Main application window managing rendering context and game loop
98
- **View**: Scene management for different game states (menu, game, pause, etc.)
99
- **Scene**: Layer-based sprite list container for organizing game objects
100
- **Section**: Viewport subdivision for split-screen or UI panels
101

102
### Rendering Pipeline
103
- Modern OpenGL 3.3+ rendering through `arcade.gl` wrapper
104
- Efficient batch rendering with sprite lists and shape lists
105
- Texture atlas system for optimized GPU memory usage
106
- Camera system for view transformations and effects
107

108
### Game Object System
109
- **Sprite**: Individual game objects with position, rotation, texture, and hit boxes
110
- **SpriteList**: Optimized containers for managing groups of sprites
111
- **Physics Engines**: Multiple physics options from simple AABB to advanced Pymunk integration
112

113
This architecture enables Arcade to scale from simple educational projects to complex commercial games while maintaining performance and ease of use.
114

115
## Capabilities
116

117
### Core Graphics and Drawing
118

119
Comprehensive 2D drawing functions including filled shapes, outlines, lines, points, and texture rendering with support for colors, gradients, and batch operations.
120

121
```python { .api }
122
def draw_circle_filled(center_x: float, center_y: float, radius: float, color: arcade.types.Color) -> None: ...
123
def draw_rectangle_filled(center_x: float, center_y: float, width: float, height: float, color: arcade.types.Color) -> None: ...
124
def draw_line(start_x: float, start_y: float, end_x: float, end_y: float, color: arcade.types.Color, line_width: float = 1) -> None: ...
125
def draw_texture_rect(texture: arcade.Texture, rect: arcade.types.Rect, alpha: int = 255) -> None: ...
126
```
127

128
[Core Graphics and Drawing](./core-graphics.md)
129

130
### Sprite System and Collision Detection
131

132
Complete sprite management system with animated sprites, sprite lists, spatial indexing, and comprehensive collision detection for game object interactions.
133

134
```python { .api }
135
class Sprite:
136
    def __init__(self, filename: str = None, scale: float = 1, **kwargs): ...
137
    center_x: float
138
    center_y: float
139
    change_x: float
140
    change_y: float
141

142
class SpriteList:
143
    def __init__(self, **kwargs): ...
144
    def append(self, sprite: arcade.Sprite) -> None: ...
145
    def draw(self, **kwargs) -> None: ...
146
    def update(self) -> None: ...
147

148
def check_for_collision(sprite1: arcade.Sprite, sprite2: arcade.Sprite) -> bool: ...
149
def check_for_collision_with_list(sprite: arcade.Sprite, sprite_list: arcade.SpriteList) -> list: ...
150
```
151

152
[Sprite System and Collision Detection](./sprite-system.md)
153

154
### Window and Application Management
155

156
Window lifecycle management, view system for game states, sections for viewport management, and event handling for user input.
157

158
```python { .api }
159
class Window(pyglet.window.Window):
160
    def __init__(self, width: int = 800, height: int = 600, title: str = "Arcade Window", **kwargs): ...
161
    def on_draw(self) -> None: ...
162
    def on_update(self, delta_time: float) -> None: ...
163
    def on_key_press(self, key: int, modifiers: int) -> None: ...
164

165
class View:
166
    def __init__(self): ...
167
    def on_show_view(self) -> None: ...
168
    def on_hide_view(self) -> None: ...
169

170
def open_window(width: int, height: int, title: str = "Arcade Window") -> arcade.Window: ...
171
def run() -> None: ...
172
```
173

174
[Window and Application Management](./window-management.md)
175

176
### Physics Engines
177

178
Multiple physics engine options from simple AABB collision to advanced 2D physics simulation with Pymunk integration for realistic physics behavior.
179

180
```python { .api }
181
class PhysicsEngineSimple:
182
    def __init__(self, player_sprite: arcade.Sprite, walls: arcade.SpriteList): ...
183
    def update(self) -> None: ...
184

185
class PhysicsEnginePlatformer:
186
    def __init__(self, player_sprite: arcade.Sprite, platforms: arcade.SpriteList, gravity_constant: float = 0.5, ladders: arcade.SpriteList = None): ...
187
    def update(self) -> None: ...
188

189
class PymunkPhysicsEngine:
190
    def __init__(self, gravity: tuple = (0, -981)): ...
191
    def add_sprite(self, sprite: arcade.Sprite, **kwargs) -> None: ...
192
    def step(self, delta_time: float = 1/60) -> None: ...
193
```
194

195
[Physics Engines](./physics-engines.md)
196

197
### Texture Management
198

199
Texture loading, caching, atlas management, procedural texture generation, and sprite sheet handling for efficient graphics resource management.
200

201
```python { .api }
202
class Texture:
203
    def __init__(self, image: PIL.Image.Image, name: str = None): ...
204
    width: int
205
    height: int
206

207
def load_texture(file_path: str, **kwargs) -> arcade.Texture: ...
208
def make_circle_texture(diameter: int, color: arcade.types.Color) -> arcade.Texture: ...
209

210
class SpriteSheet:
211
    def __init__(self, file_path: str, sprite_width: int, sprite_height: int, **kwargs): ...
212
    def get_texture(self, x: int, y: int) -> arcade.Texture: ...
213
```
214

215
[Texture Management](./texture-management.md)
216

217
### Sound System
218

219
Audio playback with support for multiple formats, volume control, spatial audio, and sound effect management for immersive game experiences.
220

221
```python { .api }
222
class Sound:
223
    def __init__(self, file_path: str): ...
224
    def play(self, volume: float = 1.0, pan: float = 0.0, loop: bool = False) -> None: ...
225
    def stop(self) -> None: ...
226

227
def load_sound(file_path: str) -> arcade.Sound: ...
228
def play_sound(sound: arcade.Sound, volume: float = 1.0) -> None: ...
229
```
230

231
[Sound System](./sound-system.md)
232

233
### GUI Framework
234

235
Complete user interface framework with widgets, layouts, event handling, styling, and theming for creating game menus and interfaces.
236

237
```python { .api }
238
class UIManager:
239
    def __init__(self, window: arcade.Window = None): ...
240
    def add(self, widget: arcade.gui.UIWidget) -> None: ...
241
    def on_draw(self) -> None: ...
242

243
class UIFlatButton(arcade.gui.UIInteractiveWidget):
244
    def __init__(self, text: str, width: float = 100, height: float = 50, **kwargs): ...
245

246
class UIBoxLayout(arcade.gui.UILayout):
247
    def __init__(self, vertical: bool = True, **kwargs): ...
248
```
249

250
[GUI Framework](./gui-framework.md)
251

252
### Camera System
253

254
2D camera system with view transformations, viewport management, projection controls, and smooth camera movement for dynamic view control.
255

256
```python { .api }
257
class Camera2D:
258
    def __init__(self, viewport: arcade.types.Rect = None): ...
259
    def move_to(self, position: tuple, speed: float = 1.0) -> None: ...
260
    def use(self) -> None: ...
261
    position: arcade.math.Vec2
262
    zoom: float
263
```
264

265
[Camera System](./camera-system.md)
266

267
### Math Utilities and Types
268

269
Mathematical functions, vector operations, geometric utilities, color types, and game-specific calculations for game development.
270

271
```python { .api }
272
def get_distance(x1: float, y1: float, x2: float, y2: float) -> float: ...
273
def get_angle_degrees(x1: float, y1: float, x2: float, y2: float) -> float: ...
274
def lerp(a: float, b: float, t: float) -> float: ...
275

276
class Vec2:
277
    def __init__(self, x: float = 0, y: float = 0): ...
278
    x: float
279
    y: float
280

281
# Type definitions
282
RGB = tuple[int, int, int]
283
RGBA = tuple[int, int, int, int]
284
Point = tuple[float, float]
285
```
286

287
[Math Utilities and Types](./math-utilities.md)
288

289
### Specialized Features
290

291
Advanced features including particle systems, A* pathfinding, performance monitoring, tilemap support, and experimental rendering effects.
292

293
```python { .api }
294
class Emitter:
295
    def __init__(self, center_xy: tuple, emit_controller: arcade.EmitController, particle_factory: callable): ...
296
    def update(self) -> None: ...
297

298
def astar_calculate_path(start_point: tuple, end_point: tuple, barriers: arcade.AStarBarrierList, diagonal_movement: bool = True) -> list: ...
299

300
class PerfGraph:
301
    def __init__(self, width: int, height: int, graph_data: str): ...
302
    def draw(self) -> None: ...
303
```
304

305
[Specialized Features](./specialized-features.md)
306

307
## Types
308

309
### Core Types
310

311
```python { .api }
312
# Color types
313
RGB = tuple[int, int, int]
314
RGBA = tuple[int, int, int, int] 
315
RGBOrA = RGB | RGBA
316
Color = arcade.types.Color
317

318
# Geometry types  
319
Point = tuple[float, float]
320
Point2 = tuple[float, float]
321
Point3 = tuple[float, float, float]
322
PointList = list[Point]
323

324
# Rectangle types
325
class Rect:
326
    def __init__(self, x: float, y: float, width: float, height: float): ...
327
    x: float
328
    y: float  
329
    width: float
330
    height: float
331

332
class LRBT:
333
    def __init__(self, left: float, right: float, bottom: float, top: float): ...
334

335
class LBWH:
336
    def __init__(self, left: float, bottom: float, width: float, height: float): ...
337

338
# Vector types (from pyglet.math)
339
class Vec2:
340
    def __init__(self, x: float = 0, y: float = 0): ...
341
    x: float
342
    y: float
343

344
class Vec3:  
345
    def __init__(self, x: float = 0, y: float = 0, z: float = 0): ...
346
    x: float
347
    y: float
348
    z: float
349
```
350

351
### Constants
352

353
```python { .api }
354
# Mouse buttons
355
MOUSE_BUTTON_LEFT: int = 1
356
MOUSE_BUTTON_MIDDLE: int = 2
357
MOUSE_BUTTON_RIGHT: int = 4
358

359
# Sprite directions
360
FACE_LEFT: str = "left" 
361
FACE_RIGHT: str = "right"
362
FACE_UP: str = "up"
363
FACE_DOWN: str = "down"
364

365
# Version
366
VERSION: str = "3.3.2"
367
```