pygame-patterns

Pygame 模式技能

提供本项目中经过测试和验证的 pygame 模式。在实现新实体或系统时使用，确保一致性和正确性。

核心原则

1. 帧率无关的移动：所有移动都使用 delta_time，确保速度不受帧率影响
2. 仅使用已验证的模式：所有模式均来自本项目中的可运行代码
3. 由配置驱动：使用集中管理的 config.py 数据类，绝不硬编码数值
4. 角度约定：0° = 右，90° = 上，180° = 左，270° = 下（pygame 的 Y 轴方向相反）

可用模式

投射物

参见 patterns/projectiles.md，了解如何：

• 在实体位置沿指定方向生成投射物
• 实现帧率无关的投射物移动（速度向量）
• 检测圆形碰撞
• 管理生命周期并销毁投射物
• 将角度转换为速度向量（考虑 pygame 的 Y 轴方向）

说明

第 1 步：确定所需模式

确定哪种模式适用于你的实现：

• 投射物系统：生成、移动、碰撞 → 使用 projectiles.md
• 实体移动：WASD、平滑旋转 → 参见 player.py:129-155
• 精灵加载：错误处理、回退方案 → 参见 utils.py:10-27
• 碰撞检测：基于圆形 → 参见 game.py 中的碰撞逻辑

第 2 步：参考模式

阅读模式文档：

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

或查看现有实现：

Read src/entities/<entity>.py

第 3 步：对照文档验证

重要：实现之前，使用 ref.tools 验证 pygame API：

• 检查 pyproject.toml 中的 pygame 版本
• 使用 ref_search_documentation 验证 API
• 确认函数签名和参数

第 4 步：应用模式

遵循模式结构：

1. 在 src/config.py 中添加配置数据类（不使用硬编码数值）
2. 导入所需的 pygame 模块
3. 使用 delta_time 进行帧率无关的计算
4. 为实体生命周期事件添加日志记录
5. 遵循角度约定（0° = 右，pygame 的 Y 轴方向相反）

模式验证清单

使用模式之前：

• 阅读模式文档
• 如果使用新函数，则使用 ref.tools 验证 pygame API
• 检查 config.py 中是否包含配置值
• 理解坐标系（pygame 的 Y 轴方向相反）
• 测试帧率无关性（应能在任何 FPS 下正常运行）

使用示例

实现投射物实体时：

1. 阅读模式：

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

2. 遵循结构：

   • 在 config.py 中创建 ProjectileConfig
   • 在实体位置按指定角度生成
   • 将角度转换为速度（cos/sin，Y 取负值）
   • 使用 delta_time 更新位置
   • 检查生命周期和碰撞

3. 验证角度计算：

   # 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
   

与其他技能集成

• python-testing：用于为实体移动和碰撞生成测试
• entity-builder：使用此技能指导实体生成模式
• game-artist：使用这些模式加载和旋转精灵

当前项目模式

已从实现代码中验证的模式：

• 玩家旋转：src/entities/player.py:129-155（平滑旋转、角度循环处理）
• 精灵加载：src/utils.py:10-27（错误处理、回退方案）
• 碰撞检测：基于圆形（用于 player-zombie 和 player-powerup）
• 帧率无关的移动：所有实体均使用 delta_time * speed

质量标准

所有模式必须：

• 与帧率无关（使用 delta_time）
• 使用集中管理的配置（不使用魔法数字）
• 包含实体事件的日志记录
• 正确处理 pygame 的 Y 轴方向
• 根据可运行代码进行验证