or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

3d-models.md app-clock.md audio-video.md graphics-rendering.md gui.md images-textures.md index.md input-devices.md math.md opengl.md resource-management.md sprites-shapes.md text-rendering.md windowing.md

IMPROVEMENTS.md tile.json

tessl/pypi-pyglet

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

Workspace: tessl
Visibility: Public
Created: about 2 months ago
Last updated: about 2 months ago
Describes: pkg:pypi/pyglet@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-pyglet@2.1.0

Pyglet 2.1.9 - Usage Specification

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

Installation: pip install pyglet Requirements: Python 3.8+, OpenGL 3.3+ License: BSD

Quick Start

import pyglet

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

@window.event
def on_draw():
    window.clear()

pyglet.app.run()

Module Navigator

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

I need to...

Window & Display:

Create a window → windowing.md
Handle keyboard/mouse input → windowing.md
Go fullscreen, resize, multiple monitors → windowing.md

2D Graphics:

Draw sprites/images → sprites-shapes.md
Draw shapes (circles, rectangles, etc) → sprites-shapes.md
Batch rendering for performance → sprites-shapes.md

Text:

Render text labels → text-rendering.md
Load custom fonts → text-rendering.md
Editable text input → text-rendering.md

Images & Textures:

Load images (PNG, JPG, etc) → images-textures.md
Work with textures → images-textures.md
Animated GIFs → images-textures.md
Texture atlases → images-textures.md

Audio & Video:

Play sound effects → audio-video.md
Stream music → audio-video.md
3D positional audio → audio-video.md

Timing & Scheduling:

Game loop / event loop → app-clock.md
Schedule functions → app-clock.md
FPS-independent movement → app-clock.md

Math:

Vector operations → math.md
Matrix transformations → math.md
Camera setup → math.md
Quaternion rotations → math.md

Input Devices:

Game controllers/gamepads → input-devices.md
Joysticks → input-devices.md

GUI:

Buttons, sliders, text entry → gui.md

Resource Management:

Load assets from folders/ZIP → resource-management.md
Automatic caching → resource-management.md

3D:

Load 3D models → 3d-models.md
Custom OpenGL → opengl.md
Shaders → graphics-rendering.md

Core Patterns

Pattern 1: Simple 2D Game

import pyglet
from pyglet.window import key

# Setup
window = pyglet.window.Window(800, 600)
batch = pyglet.graphics.Batch()

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

# Input
keys = key.KeyStateHandler()
window.push_handlers(keys)

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

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

# Render
@window.event
def on_draw():
    window.clear()
    batch.draw()

pyglet.app.run()

Pattern 2: Resource Loading

import pyglet

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

# Load and cache automatically
player_img = pyglet.resource.image('player.png')
jump_sound = pyglet.resource.media('jump.wav', streaming=False)

Pattern 3: Efficient Rendering

# Always use batching for multiple objects
batch = pyglet.graphics.Batch()

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

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

# Draw everything at once
@window.event
def on_draw():
    window.clear()
    batch.draw()  # Single call renders all

Decision Trees

When to use streaming vs static loading?

Audio file size:
├─ < 1 MB (SFX)      → streaming=False
└─ > 1 MB (music)    → streaming=True

How to handle input?

Input type:
├─ Continuous (movement)  → KeyStateHandler + schedule
├─ Discrete (jump, shoot) → @window.event on_key_press
└─ Game controller        → pyglet.input.get_controllers()

When to use schedule() vs schedule_interval()?

Update type:
├─ Every frame (smooth animation)    → schedule(func)
├─ Fixed rate (physics, game logic)  → schedule_interval(func, 1/60)
└─ Occasional (spawn, autosave)      → schedule_interval(func, delay)

Performance Best Practices

Always use Batch for multiple sprites/shapes - 10-100x faster
Use Groups to minimize OpenGL state changes
Texture atlases for sprite sheets - reduces texture binding
streaming=False for small audio, True for music
Set visible=False instead of deleting offscreen objects
Preallocate objects in init, don't create in update loop
Use schedule_interval() for physics (consistent timing)

Common Pitfalls

Origin is bottom-left (not top-left) - y increases upward
Always multiply by dt for movement - ensures frame-rate independence
Call window.clear() in on_draw - forgetting causes artifacts
Use batch.draw() not sprite.draw() - individual draws are very slow
Unschedule functions when done - prevents memory leaks
Color values are 0-255 (not 0.0-1.0 floats)
Enable vsync for smooth rendering - Window(vsync=True)

Architecture Example

import pyglet

class Game:
    def __init__(self):
        self.window = pyglet.window.Window(800, 600, vsync=True)
        self.batch = pyglet.graphics.Batch()
        self.keys = pyglet.window.key.KeyStateHandler()
        self.window.push_handlers(self.keys)

        # Setup
        self.load_resources()
        self.setup_entities()

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

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

    def setup_entities(self):
        # Create sprites, shapes, etc
        pass

    def update(self, dt):
        # Game logic
        pass

    def on_draw(self):
        self.window.clear()
        self.batch.draw()

    def run(self):
        pyglet.app.run()

if __name__ == '__main__':
    Game().run()

Module Reference

Module	Purpose	Link
`pyglet.app`	Event loop, application lifecycle	app-clock.md
`pyglet.window`	Window creation, input events	windowing.md
`pyglet.sprite`	2D sprite rendering	sprites-shapes.md
`pyglet.shapes`	Geometric primitives	sprites-shapes.md
`pyglet.image`	Image loading, textures	images-textures.md
`pyglet.text`	Text rendering, fonts	text-rendering.md
`pyglet.media`	Audio/video playback	audio-video.md
`pyglet.graphics`	Low-level rendering, shaders	graphics-rendering.md
`pyglet.math`	Vector/matrix math	math.md
`pyglet.input`	Game controllers, joysticks	input-devices.md
`pyglet.gui`	UI widgets	gui.md
`pyglet.resource`	Resource management	resource-management.md
`pyglet.model`	3D model loading	3d-models.md
`pyglet.gl`	OpenGL bindings	opengl.md

Version Info

import pyglet
print(pyglet.version)  # '2.1.9'

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.