超级马里奥点阵屏游戏

一个为36x28 RGB点阵屏设计的超级马里奥风格游戏，支持PS5手柄控制和实时串口数据传输。

项目特性

• 适配低分辨率：专门为36x28像素点阵屏优化的游戏画面
• PS5手柄控制：完整支持PS5 DualSense手柄输入
• 实时串口传输：将游戏画面实时传输到物理点阵屏硬件
• 图形化界面：PyQt5界面，可实时预览游戏画面和调试
• 模块化设计：清晰的代码结构，易于扩展和维护

系统要求

• Python 3.7+
• Linux/Windows/macOS
• PS5手柄（通过USB或蓝牙连接）
• 串口设备（用于连接点阵屏硬件）

安装依赖

pip install -r requirements.txt

依赖包说明

• pygame>=2.1.0 - PS5手柄输入处理
• pyserial>=3.5 - 串口通信
• PyQt5>=5.15.0 - 图形用户界面
• numpy>=1.21.0 - 数值计算和矩阵操作
• Pillow>=8.3.0 - 图像处理（可选）

使用方法

1. 启动游戏

cd code
python main.py

2. 连接设备

1. 连接PS5手柄：

   • USB连接：直接用USB线连接手柄到电脑
   • 蓝牙连接：在系统蓝牙设置中配对手柄

2. 连接串口设备：

   • 在GUI界面中选择正确的串口号
   • 设置合适的波特率（默认115200）
   • 点击"连接"按钮

3. 游戏控制

PS5手柄控制：

• 方向键/左摇杆：控制马里奥左右移动
• X键：跳跃
• □键：攻击/发射（如果有火花马里奥状态）

GUI控制：

• 开始游戏：启动或继续游戏
• 暂停游戏：暂停当前游戏
• 重置游戏：重新开始游戏
• 发送测试图案：向点阵屏发送彩虹测试图案

文件结构

code/
├── main.py                 # 主程序入口
├── config.py              # 配置文件
├── controller_handler.py   # PS5手柄控制处理
├── game_objects.py        # 游戏对象（马里奥、敌人、道具等）
├── level.py               # 游戏关卡管理
├── matrix_renderer.py     # 点阵屏渲染器
├── serial_transmitter.py  # 串口数据传输
├── gui_display.py         # PyQt5图形界面
├── requirements.txt       # 依赖列表
└── README.md             # 项目说明

配置说明

在 config.py 中可以调整以下参数：

显示配置

• MATRIX_WIDTH = 36 - 点阵屏宽度
• MATRIX_HEIGHT = 28 - 点阵屏高度
• GAME_FPS = 30 - 游戏帧率

游戏配置

• MARIO_SIZE = 2 - 马里奥角色大小
• MARIO_SPEED = 1 - 马里奥移动速度
• JUMP_STRENGTH = 3 - 跳跃力度
• GRAVITY = 0.2 - 重力加速度

串口配置

• SERIAL_PORT = '/dev/ttyUSB0' - 默认串口
• SERIAL_BAUDRATE = 115200 - 波特率
• SERIAL_TIMEOUT = 1 - 超时时间

串口数据格式

发送到点阵屏的数据包格式：

帧头(2字节) + 数据长度(2字节) + RGB数据(3024字节) + 校验和(1字节) + 帧尾(1字节)

• 帧头: 0xAA 0x55
• 数据长度: 3024字节（36×28×3）
• RGB数据: 按行排列的RGB像素数据
• 校验和: XOR校验
• 帧尾: 0x0D

游戏特性

已实现功能

• 马里奥角色移动和跳跃
• 重力系统和碰撞检测
• 敌人AI和交互
• 金币收集系统
• 分数和生命系统
• 关卡地形（地面、平台、砖块）
• 无敌状态和闪烁效果
• 相机跟随系统

计划功能

• 更多敌人类型
• 道具系统（蘑菇、火花等）
• 多关卡支持
• 背景音乐和音效
• 关卡编辑器

故障排除

手柄无法识别

1. 确认手柄已正确连接到系统
2. 检查pygame是否正确安装
3. 尝试重启应用程序

串口连接失败

1. 确认串口设备已连接
2. 检查串口权限（Linux下可能需要sudo或添加用户到dialout组）
3. 尝试不同的波特率设置
4. 确认串口未被其他程序占用

游戏画面卡顿

1. 降低游戏帧率（修改config.py中的GAME_FPS）
2. 关闭不必要的后台程序
3. 检查CPU使用率

开发和扩展

添加新的游戏对象

1. 在 game_objects.py 中继承 GameObject 类
2. 实现必要的方法（update, render等）
3. 在 level.py 中添加到关卡

修改渲染效果

1. 编辑 matrix_renderer.py 中的渲染逻辑
2. 调整颜色定义（config.py中的COLOR_*常量）
3. 添加新的视觉效果

自定义控制

1. 修改 controller_handler.py 中的按键映射
2. 在 config.py 中调整按键常量

许可证

本项目基于MIT许可证开源。

贡献

欢迎提交Issue和Pull Request来改进这个项目！

联系方式

如有问题或建议，请通过GitHub Issues联系。