Yei.J. (AskaEth)
120 lines
2.9 KiB
Markdown
120 lines
2.9 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 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 许可下发布。
|