Pygame Patterns Skill

Provides tested, verified pygame patterns from this project. Use when implementing new entities or systems to ensure consistency and correctness.

Core Principles

• Frame-Independent Movement: All movement uses delta_time for consistent speed regardless of framerate

• Verified Patterns Only: All patterns come from working code in this project

• Config-Driven: Use centralized config.py dataclasses, never hardcode values

• Angle Conventions: 0° = right, 90° = up, 180° = left, 270° = down (pygame Y-axis is inverted)

Available Patterns

Projectiles

See patterns/projectiles.md for:

• Spawning projectiles at entity position with direction

• Frame-independent projectile movement (velocity vectors)

• Circle collision detection

• Lifetime management and despawning

• Converting angles to velocity vectors (accounting for pygame Y-axis)

Instructions

Step 1: Identify the Pattern Needed

Determine which pattern matches your implementation:

• Projectile system: spawning, movement, collision → Use projectiles.md

• Entity movement: WASD, smooth rotation → See player.py:129-155

• Sprite loading: error handling, fallbacks → See utils.py:10-27

• Collision detection: circle-based → See game.py collision logic

Step 2: Reference the Pattern

Read the pattern documentation:

Read .claude/skills/pygame-patterns/patterns/<pattern>.md

Or examine the existing implementation:

Read src/entities/<entity>.py

Step 3: Verify with Documentation

CRITICAL: Before implementing, verify pygame APIs with ref.tools:

• Check pyproject.toml for pygame version

• Use ref_search_documentation for API verification

• Confirm function signatures and parameters

Step 4: Apply the Pattern

Follow the pattern structure:

• Add config dataclass to src/config.py (no hardcoded values)

• Import necessary pygame modules

• Use delta_time for frame-independent calculations

• Add logging for entity lifecycle events

• Follow angle conventions (0° = right, pygame Y-inverted)

Pattern Verification Checklist

Before using a pattern:

• Read the pattern documentation

• Verify pygame APIs with ref.tools if using new functions

• Check that config values are in config.py

• Understand coordinate system (pygame Y-axis inverted)

• Test frame-independence (should work at any FPS)

Example Usage

When implementing a projectile entity:

Read the pattern:

Read .claude/skills/pygame-patterns/patterns/projectiles.md

Follow the structure:

• Create ProjectileConfig in config.py

• Spawn at entity position with angle

• Convert angle → velocity (cos/sin, negative Y)

• Update position with delta_time

• Check lifetime and collisions

Verify angle math:

0° = right, 90° = up (pygame Y is inverted)

angle_rad = math.radians(angle) velocity_x = math.cos(angle_rad) * speed velocity_y = -math.sin(angle_rad) * speed # negative for pygame

Integration with Other Skills

• python-testing: Use to generate tests for entity movement and collision

• entity-builder: Use this skill to inform entity generation patterns

• game-artist: Use patterns for sprite loading and rotation

Current Project Patterns

Verified patterns from implemented code:

• Player rotation: src/entities/player.py:129-155 (smooth rotation, angle wrap)

• Sprite loading: src/utils.py:10-27 (error handling, fallbacks)

• Collision detection: Circle-based (used in player-zombie and player-powerup)

• Frame-independent movement: All entities use delta_time * speed

Quality Standards

All patterns must:

• Be frame-independent (use delta_time)

• Use centralized config (no magic numbers)

• Include logging for entity events

• Handle pygame Y-axis inversion correctly

• Be verified from working code