0
# Pyglet 2.1.9 - Usage Specification
1

2
Cross-platform windowing and multimedia library for Python with OpenGL graphics, event handling, and audio/video playback.
3

4
**Installation:** `pip install pyglet`
5
**Requirements:** Python 3.8+, OpenGL 3.3+
6
**License:** BSD
7

8
## Quick Start
9

10
```python
11
import pyglet
12

13
window = pyglet.window.Window(800, 600)
14

15
@window.event
16
def on_draw():
17
    window.clear()
18

19
pyglet.app.run()
20
```
21

22
## Module Navigator
23

24
Use this guide to quickly find the right module for your task:
25

26
### I need to...
27

28
**Window & Display:**
29
- Create a window → [windowing.md](./windowing.md)
30
- Handle keyboard/mouse input → [windowing.md](./windowing.md)
31
- Go fullscreen, resize, multiple monitors → [windowing.md](./windowing.md)
32

33
**2D Graphics:**
34
- Draw sprites/images → [sprites-shapes.md](./sprites-shapes.md)
35
- Draw shapes (circles, rectangles, etc) → [sprites-shapes.md](./sprites-shapes.md)
36
- Batch rendering for performance → [sprites-shapes.md](./sprites-shapes.md)
37

38
**Text:**
39
- Render text labels → [text-rendering.md](./text-rendering.md)
40
- Load custom fonts → [text-rendering.md](./text-rendering.md)
41
- Editable text input → [text-rendering.md](./text-rendering.md)
42

43
**Images & Textures:**
44
- Load images (PNG, JPG, etc) → [images-textures.md](./images-textures.md)
45
- Work with textures → [images-textures.md](./images-textures.md)
46
- Animated GIFs → [images-textures.md](./images-textures.md)
47
- Texture atlases → [images-textures.md](./images-textures.md)
48

49
**Audio & Video:**
50
- Play sound effects → [audio-video.md](./audio-video.md)
51
- Stream music → [audio-video.md](./audio-video.md)
52
- 3D positional audio → [audio-video.md](./audio-video.md)
53

54
**Timing & Scheduling:**
55
- Game loop / event loop → [app-clock.md](./app-clock.md)
56
- Schedule functions → [app-clock.md](./app-clock.md)
57
- FPS-independent movement → [app-clock.md](./app-clock.md)
58

59
**Math:**
60
- Vector operations → [math.md](./math.md)
61
- Matrix transformations → [math.md](./math.md)
62
- Camera setup → [math.md](./math.md)
63
- Quaternion rotations → [math.md](./math.md)
64

65
**Input Devices:**
66
- Game controllers/gamepads → [input-devices.md](./input-devices.md)
67
- Joysticks → [input-devices.md](./input-devices.md)
68

69
**GUI:**
70
- Buttons, sliders, text entry → [gui.md](./gui.md)
71

72
**Resource Management:**
73
- Load assets from folders/ZIP → [resource-management.md](./resource-management.md)
74
- Automatic caching → [resource-management.md](./resource-management.md)
75

76
**3D:**
77
- Load 3D models → [3d-models.md](./3d-models.md)
78
- Custom OpenGL → [opengl.md](./opengl.md)
79
- Shaders → [graphics-rendering.md](./graphics-rendering.md)
80

81
## Core Patterns
82

83
### Pattern 1: Simple 2D Game
84

85
```python
86
import pyglet
87
from pyglet.window import key
88

89
# Setup
90
window = pyglet.window.Window(800, 600)
91
batch = pyglet.graphics.Batch()
92

93
# Load resources
94
player_img = pyglet.image.load('player.png')
95
player = pyglet.sprite.Sprite(player_img, x=400, y=300, batch=batch)
96

97
# Input
98
keys = key.KeyStateHandler()
99
window.push_handlers(keys)
100

101
# Update
102
def update(dt):
103
    speed = 200 * dt
104
    if keys[key.LEFT]: player.x -= speed
105
    if keys[key.RIGHT]: player.x += speed
106

107
pyglet.clock.schedule_interval(update, 1/60)
108

109
# Render
110
@window.event
111
def on_draw():
112
    window.clear()
113
    batch.draw()
114

115
pyglet.app.run()
116
```
117

118
### Pattern 2: Resource Loading
119

120
```python
121
import pyglet
122

123
# Set asset paths
124
pyglet.resource.path = ['assets/images', 'assets/sounds']
125
pyglet.resource.reindex()
126

127
# Load and cache automatically
128
player_img = pyglet.resource.image('player.png')
129
jump_sound = pyglet.resource.media('jump.wav', streaming=False)
130
```
131

132
### Pattern 3: Efficient Rendering
133

134
```python
135
# Always use batching for multiple objects
136
batch = pyglet.graphics.Batch()
137

138
# Use groups for layering
139
background = pyglet.graphics.Group(order=0)
140
foreground = pyglet.graphics.Group(order=1)
141

142
# Add objects to batch
143
bg_sprite = pyglet.sprite.Sprite(bg_img, batch=batch, group=background)
144
player = pyglet.sprite.Sprite(player_img, batch=batch, group=foreground)
145

146
# Draw everything at once
147
@window.event
148
def on_draw():
149
    window.clear()
150
    batch.draw()  # Single call renders all
151
```
152

153
## Decision Trees
154

155
### When to use streaming vs static loading?
156

157
```
158
Audio file size:
159
├─ < 1 MB (SFX)      → streaming=False
160
└─ > 1 MB (music)    → streaming=True
161
```
162

163
### How to handle input?
164

165
```
166
Input type:
167
├─ Continuous (movement)  → KeyStateHandler + schedule
168
├─ Discrete (jump, shoot) → @window.event on_key_press
169
└─ Game controller        → pyglet.input.get_controllers()
170
```
171

172
### When to use schedule() vs schedule_interval()?
173

174
```
175
Update type:
176
├─ Every frame (smooth animation)    → schedule(func)
177
├─ Fixed rate (physics, game logic)  → schedule_interval(func, 1/60)
178
└─ Occasional (spawn, autosave)      → schedule_interval(func, delay)
179
```
180

181
## Performance Best Practices
182

183
1. **Always use Batch** for multiple sprites/shapes - 10-100x faster
184
2. **Use Groups** to minimize OpenGL state changes
185
3. **Texture atlases** for sprite sheets - reduces texture binding
186
4. **streaming=False** for small audio, **True** for music
187
5. **Set visible=False** instead of deleting offscreen objects
188
6. **Preallocate objects** in init, don't create in update loop
189
7. **Use schedule_interval()** for physics (consistent timing)
190

191
## Common Pitfalls
192

193
1. **Origin is bottom-left** (not top-left) - y increases upward
194
2. **Always multiply by dt** for movement - ensures frame-rate independence
195
3. **Call window.clear()** in on_draw - forgetting causes artifacts
196
4. **Use batch.draw()** not sprite.draw() - individual draws are very slow
197
5. **Unschedule functions** when done - prevents memory leaks
198
6. **Color values are 0-255** (not 0.0-1.0 floats)
199
7. **Enable vsync** for smooth rendering - `Window(vsync=True)`
200

201
## Architecture Example
202

203
```python
204
import pyglet
205

206
class Game:
207
    def __init__(self):
208
        self.window = pyglet.window.Window(800, 600, vsync=True)
209
        self.batch = pyglet.graphics.Batch()
210
        self.keys = pyglet.window.key.KeyStateHandler()
211
        self.window.push_handlers(self.keys)
212

213
        # Setup
214
        self.load_resources()
215
        self.setup_entities()
216

217
        # Events
218
        self.window.event(self.on_draw)
219
        pyglet.clock.schedule_interval(self.update, 1/60)
220

221
    def load_resources(self):
222
        pyglet.resource.path = ['assets']
223
        pyglet.resource.reindex()
224
        # Load images, sounds, etc
225

226
    def setup_entities(self):
227
        # Create sprites, shapes, etc
228
        pass
229

230
    def update(self, dt):
231
        # Game logic
232
        pass
233

234
    def on_draw(self):
235
        self.window.clear()
236
        self.batch.draw()
237

238
    def run(self):
239
        pyglet.app.run()
240

241
if __name__ == '__main__':
242
    Game().run()
243
```
244

245
## Module Reference
246

247
| Module | Purpose | Link |
248
|--------|---------|------|
249
| `pyglet.app` | Event loop, application lifecycle | [app-clock.md](./app-clock.md) |
250
| `pyglet.window` | Window creation, input events | [windowing.md](./windowing.md) |
251
| `pyglet.sprite` | 2D sprite rendering | [sprites-shapes.md](./sprites-shapes.md) |
252
| `pyglet.shapes` | Geometric primitives | [sprites-shapes.md](./sprites-shapes.md) |
253
| `pyglet.image` | Image loading, textures | [images-textures.md](./images-textures.md) |
254
| `pyglet.text` | Text rendering, fonts | [text-rendering.md](./text-rendering.md) |
255
| `pyglet.media` | Audio/video playback | [audio-video.md](./audio-video.md) |
256
| `pyglet.graphics` | Low-level rendering, shaders | [graphics-rendering.md](./graphics-rendering.md) |
257
| `pyglet.math` | Vector/matrix math | [math.md](./math.md) |
258
| `pyglet.input` | Game controllers, joysticks | [input-devices.md](./input-devices.md) |
259
| `pyglet.gui` | UI widgets | [gui.md](./gui.md) |
260
| `pyglet.resource` | Resource management | [resource-management.md](./resource-management.md) |
261
| `pyglet.model` | 3D model loading | [3d-models.md](./3d-models.md) |
262
| `pyglet.gl` | OpenGL bindings | [opengl.md](./opengl.md) |
263
264
## Version Info
265

266
```python
267
import pyglet
268
print(pyglet.version)  # '2.1.9'
269
```
270

271
---
272

273
**Note for AI Agents:** This index is designed for quick navigation. For detailed API references, class signatures, and comprehensive examples, see the module-specific documentation files linked above.
274