Back to Details

pygame-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pygame Patterns Skill

Pygame 模式技能

Provides tested, verified pygame patterns from this project. Use when implementing new entities or systems to ensure consistency and correctness.
提供本项目中经过测试验证的Pygame模式。在实现新实体或系统时使用，以确保一致性和正确性。

Core Principles

核心原则

  1. Frame-Independent Movement: All movement uses delta_time for consistent speed regardless of framerate
  2. Verified Patterns Only: All patterns come from working code in this project
  3. Config-Driven: Use centralized config.py dataclasses, never hardcode values
  4. Angle Conventions: 0° = right, 90° = up, 180° = left, 270° = down (pygame Y-axis is inverted)
  1. 帧率无关移动：所有移动均使用delta_time，确保在不同帧率下速度一致
  2. 仅使用已验证模式：所有模式均来自本项目中可正常运行的代码
  3. 配置驱动：使用集中式config.py数据类，绝不硬编码值
  4. 角度约定：0°=右，90°=上，180°=左，270°=下（Pygame Y轴是反向的）

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)
请查看patterns/projectiles.md了解：
  • 在实体位置按指定方向生成抛射物
  • 帧率无关的抛射物移动（速度向量）
  • 圆形碰撞检测
  • 生命周期管理与销毁
  • 将角度转换为速度向量（适配Pygame Y轴）

Instructions

使用步骤

Step 1: Identify the Pattern Needed

步骤1：确定所需模式

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
确定哪种模式符合你的实现需求：
  • 抛射物系统：生成、移动、碰撞 → 使用projectiles.md
  • 实体移动：WASD控制、平滑旋转 → 查看player.py:129-155
  • 精灵加载：错误处理、降级方案 → 查看utils.py:10-27
  • 碰撞检测：基于圆形 → 查看game.py中的碰撞逻辑

Step 2: Reference the Pattern

步骤2：参考模式

Read the pattern documentation:
bash
Read .claude/skills/pygame-patterns/patterns/<pattern>.md
Or examine the existing implementation:
bash
Read src/entities/<entity>.py
阅读模式文档：
bash
Read .claude/skills/pygame-patterns/patterns/<pattern>.md
或查看现有实现：
bash
Read src/entities/<entity>.py

Step 3: Verify with Documentation

步骤3：通过文档验证

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
重要提示：在实现前，使用ref.tools验证Pygame API：
  • 查看pyproject.toml获取Pygame版本
  • 使用ref_search_documentation进行API验证
  • 确认函数签名和参数

Step 4: Apply the Pattern

步骤4：应用模式

Follow the pattern structure:
  1. Add config dataclass to src/config.py (no hardcoded values)
  2. Import necessary pygame modules
  3. Use delta_time for frame-independent calculations
  4. Add logging for entity lifecycle events
  5. Follow angle conventions (0° = right, pygame Y-inverted)
遵循模式结构：
  1. 向src/config.py中添加配置数据类（禁止硬编码值）
  2. 导入所需的Pygame模块
  3. 使用delta_time进行帧率无关计算
  4. 为实体生命周期事件添加日志
  5. 遵循角度约定（0°=右，Pygame Y轴反向）

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)
使用模式前：
  • 阅读模式文档
  • 若使用新函数，用ref.tools验证Pygame API
  • 确认配置值已在config.py中
  • 理解坐标系（Pygame Y轴反向）
  • 测试帧率无关性（应在任意FPS下正常工作）

Example Usage

使用示例

When implementing a projectile entity:
  1. Read the pattern:
    Read .claude/skills/pygame-patterns/patterns/projectiles.md
  2. 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
  3. Verify angle math:
    python
    # 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
实现抛射物实体时：
  1. 阅读模式： 
    Read .claude/skills/pygame-patterns/patterns/projectiles.md
2.遵循结构：
  • 在config.py中创建ProjectileConfig
  • 在实体位置按指定角度生成
  • 将角度转换为速度（cos/sin，Y轴取负）
  • 使用delta_time更新位置
  • 检查生命周期和碰撞
  1. 验证角度计算：
    python
    # 0°=右，90°=上（Pygame Y轴反向）
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
  • python-testing：用于为实体移动和碰撞生成测试
  • entity-builder：使用本技能指导实体生成模式
  • game-artist：使用模式进行精灵加载和旋转

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
已实现代码中的已验证模式:
  • 玩家旋转：src/entities/player.py:129-155（平滑旋转角度循环)
  • 精灵加载：src/utils.py:10-27错误处理降级方案)
  • 碰撞检测：基于圆形用于玩家-僵尸玩家-道具交互)
  • 帧率无关移动：所有实体均使用delta_time * speed
##质量标准
所有模式必须:
  • 具备帧率无关性使用delta_time)
  • 使用集中式配置无魔法数值) -包含实体事件日志 -正确处理Pygame Y轴反向问题 -已通过可运行代码验证

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
—