# 贡献指南

感谢你对 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 格式

```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()` 函数，返回一个包含以下方法的对象：

```python
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 讨论新功能方向。

## 开发环境

```bash
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 许可下发布。