pyxel

name: pyxel description: Comprehensive Pyxel retro game engine development toolkit. Use when creating, modifying, or debugging Pyxel games, implementing game mechanics (collision detection, entity management, physics), working with sprites/tilemaps/sounds, or needing Pyxel API reference. Supports platformers, shooters, puzzle games, and custom game genres.

Pyxel Game Development

Pyxel is a retro game engine for Python inspired by PICO-8 and TIC-80. This skill provides comprehensive support for developing professional-quality Pyxel games.

Quick Start

Create a new Pyxel game project:

python scripts/create_project.py my_game [template]

Available templates:

minimal - Minimal boilerplate (default)
platformer - Side-scrolling platformer with physics
shooter - Top-down/scrolling shooter
puzzle - Grid-based puzzle game

All templates include:

Proper game structure with update/draw loop
Input handling (keyboard + gamepad)
Basic game objects and patterns
Commented TODOs for customization

Workflow Guide

1. Project Setup

Use create_project.py to initialize projects with appropriate templates:

# Minimal game
python scripts/create_project.py my_game minimal

# Platformer with physics
python scripts/create_project.py platformer_game platformer

# Shooter with bullets and enemies
python scripts/create_project.py space_shooter shooter

# Puzzle with grid
python scripts/create_project.py match_three puzzle

2. Implement Game Logic

Follow the patterns in references/patterns.md:

Common tasks:

Add collision detection → See Collision Detection
Manage entities (enemies, bullets) → See Entity Management
Implement scene transitions → See State/Scene Management
Add scrolling/camera → See Camera and Scrolling
Create animations → See Animation

3. Create Graphics and Audio

Use Pyxel Editor to create game assets:

# Create or edit resource file
pyxel edit assets/game.pyxres

Pyxel Editor modes:

Image Editor - Draw sprites and tiles (256x256 pixels, 3 banks)
Tilemap Editor - Arrange tiles for levels (256x256 tiles, 8 maps)
Sound Editor - Create sound effects (64 sounds, 4 channels)
Music Editor - Compose music tracks (8 music tracks)

Load resources in code:

pyxel.load("assets/game.pyxres")

4. Common Game Patterns

Collision Detection (AABB)

def check_collision(x1, y1, w1, h1, x2, y2, w2, h2):
    return (x1 < x2 + w2 and
            x1 + w1 > x2 and
            y1 < y2 + h2 and
            y1 + h1 > y2)

if check_collision(player.x, player.y, 8, 8, enemy.x, enemy.y, 8, 8):
    # Handle collision
    pass

Entity Management

# Update all entities
for entity in self.enemies:
    entity.update()

# Remove dead entities
self.enemies = [e for e in self.enemies if e.is_alive]

Scene/State Management

SCENE_TITLE = 0
SCENE_GAME = 1
SCENE_GAMEOVER = 2

def update(self):
    if self.scene == SCENE_TITLE:
        self.update_title()
    elif self.scene == SCENE_GAME:
        self.update_game()
    # ...

See references/patterns.md for more detailed patterns and examples.

API Reference

Quick Reference

Initialization:

pyxel.init(width, height, title="Game")
pyxel.run(update, draw)

Drawing:

pyxel.cls(col)                              # Clear screen
pyxel.rect(x, y, w, h, col)                 # Rectangle
pyxel.blt(x, y, img, u, v, w, h, colkey)    # Sprite
pyxel.text(x, y, text, col)                 # Text

Input:

pyxel.btn(key)      # Check if key is held
pyxel.btnp(key)     # Check if key was just pressed
pyxel.mouse_x       # Mouse X position
pyxel.mouse_y       # Mouse Y position

Audio:

pyxel.play(ch, snd)      # Play sound on channel
pyxel.playm(msc, loop=True)  # Play music

Complete API: See references/api.md for full documentation of all functions, classes, and constants.

Resources

References

api.md - Complete Pyxel API reference with all functions, classes, and constants
patterns.md - Common game development patterns including:
- Collision detection (AABB, circular, distance-based)
- Entity management and cleanup
- State/scene management
- Input handling (keyboard, gamepad, mouse)
- Camera and scrolling systems
- Animation techniques
- Performance optimization tips

Templates

Located in assets/templates/:

minimal.py - Minimal boilerplate for custom games
platformer.py - Side-scroller with gravity and jumping
shooter.py - Shooter with bullets, enemies, and combat
puzzle.py - Grid-based puzzle with cursor selection

Scripts

create_project.py - Generate new game projects with templates

Tips

Best Practices

Structure your code - Use classes for game objects (Player, Enemy, Bullet, etc.)
Separate concerns - Keep update logic and drawing separate
Use resources - Create sprites in Pyxel Editor instead of drawing shapes
Test collision - Visualize hitboxes during development with pyxel.rectb()
Limit entities - Cap bullets/enemies to prevent slowdown
Clean up - Remove off-screen or dead entities every frame

Common Pitfalls

Don't create new objects in draw() - Only update state in update()
Don't forget transparent color - Use colkey parameter in blt() for sprites
Don't mix coordinates - Camera affects drawing, use pyxel.camera() then reset for UI
Don't skip cleanup - Always remove dead entities to prevent memory issues

Debugging

# Show FPS and performance
# Press Alt+0 while running

# Visualize hitboxes
if DEBUG:
    pyxel.rectb(self.x, self.y, self.w, self.h, 8)

# Print to console
print(f"Player pos: ({self.x}, {self.y})")

Distribution

Package your game for distribution:

# Create distributable .pyxapp file
pyxel package game_dir main.py

# Run packaged game
pyxel play game.pyxapp

Pyxel Specifications

Display: 16 colors, customizable screen size
Images: 3 banks of 256x256 pixels
Tilemaps: 8 maps of 256x256 tiles (8x8 pixels each)
Audio: 4 channels, 64 sounds, 8 music tracks
Input: Keyboard, mouse, gamepad (up to 4 players)
Platforms: Windows, Mac, Linux, Web