feat: TurboSu initial release - racing telemetry dashboard

2026-07-25 15:23:40 +08:00
commit d61bb61a83
61 changed files with 5270 additions and 0 deletions
@@ -0,0 +1,119 @@
+# 贡献指南
+
+感谢你对 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 许可下发布。