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

1. •Structure your code - Use classes for game objects (Player, Enemy, Bullet, etc.)
2. •Separate concerns - Keep update logic and drawing separate
3. •Use resources - Create sprites in Pyxel Editor instead of drawing shapes
4. •Test collision - Visualize hitboxes during development with pyxel.rectb()
5. •Limit entities - Cap bullets/enemies to prevent slowdown
6. •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

External Resources

• •Official Pyxel Repository
• •Pyxel Examples
• •Pyxel Community Examples
• •Online Pyxel Editor