TurboSu/CONTRIBUTING.md

贡献指南

感谢你对 TurboSu 的关注！本指南将帮助你参与项目开发。

贡献方式

提交游戏插件

如果你想让 TurboSu 支持一款新的赛车游戏，只需创建一个游戏插件：

1. 在 games/user/ 下新建文件夹 (以游戏 ID 命名)
2. 编写 manifest.json (元信息) 和 parser.py (数据解析)
3. 提交 Pull Request 到 games/user/ 目录，或直接在设置页面通过 "导入插件" 安装

插件结构:

games/user/<game_id>/
├── manifest.json     # 游戏元信息
└── parser.py         # 解析逻辑

manifest.json 格式

{
    "id": "unique_game_id",
    "name": "游戏名称",
    "parser_type": "forza",
    "telemetry_format": "fh5",
    "description": "简短描述",
    "author": "你的名字",
    "version": "1.0.0",
    "default_port": 20777
}

parser.py 规范

必须实现 get_parser() 函数，返回一个包含以下方法的对象：

class MyParser:
    def game_id(self) -> str:
        """返回与 manifest.json 一致的 game id"""
        return "unique_game_id"

    def parse(self, data: bytes, addr: tuple) -> TelemetryData:
        """
        解析 UDP 数据包
        data: 原始字节数据
        addr: (host, port) 发送方地址
        返回: server.telemetry.data.TelemetryData 对象
        """

TelemetryData 可用字段

字段	类型	说明
speed_kmh	float	速度 (km/h)
speed_mph	float	速度 (mph)
rpm	float	发动机转速
max_rpm	float	最大转速
gear	int	当前档位 (0=N, 1-8, -1=R)
throttle	float	油门 (0-1)
brake	float	刹车 (0-1)
clutch	float	离合 (0-1)
handbrake	float	手刹 (0-1)
steering	float	转向 (-1 to 1)
lap_time	float	当前圈速 (秒)
best_lap	float	最佳圈速 (秒)
last_lap	float	上一圈速 (秒)
lap_number	int	圈数
fuel	float	燃油量
boost	float	涡轮增压值
horsepower	float	马力
torque	float	扭矩
position_x/y/z	float	车辆坐标
engine_temp	float	发动机温度
oil_temp	float	油温
raw	dict	原始数据 (自动记录)

提交仪表盘主题

1. 在 TurboSu 设置页面创建/编辑仪表盘
2. 导出为 JSON 文件
3. 提交到 dashboards/ 目录

报告 Bug

在 GitHub Issues 中提交，请包含：

• 操作系统和 Python 版本
• 错误日志 (logs/turbosu.log)
• 复现步骤

功能建议

欢迎提交 Issue 讨论新功能方向。

开发环境

cd Project/TurboSu
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py

代码规范

• Python 代码遵循 PEP 8
• 使用 utils.logger 进行日志记录（不要用 print）
• 前端 JS 使用模块化结构，文件放在对应目录下

许可证

贡献即表示同意你的代码在 Apache 2.0 许可下发布。