docs: add dedicated DASHBOARD_DEV.md and PLUGIN_DEV.md, simplify README & CONTRIBUTING

This commit is contained in:
2026-07-25 15:38:24 +08:00
parent a46e5d786d
commit 5e177f4514
4 changed files with 438 additions and 181 deletions
+2 -114
View File
@@ -80,120 +80,8 @@ python app.py
## 开发指南
### 自定义仪表盘格式
每个仪表盘是一个独立文件夹,放在 `dashboards/``data/dashboards/`
```
dashboards/my_dashboard/
├── manifest.json # 元信息
└── index.html # 完整独立页面 (含 WS 连接 + 数据绑定)
```
#### manifest.json
```json
{
"id": "my_dashboard",
"name": "我的仪表盘",
"category": "custom",
"description": "简短描述",
"author": "你的名字",
"version": "1.0.0",
"config": {
"icon": "🏎️",
"aspect_ratio": "16:9",
"render_mode": "contain"
}
}
```
#### index.html
完全独立的 HTML 页面。需包含:
- WebSocket 连接到 `ws://<host>/ws` 接收遥测数据
- `data-bind` 属性绑定数据字段(如 `data-bind="speed_kmh"`
- 比例约束渲染逻辑(参考内置仪表盘)
打包分发:将整个文件夹压缩为 zip,改后缀为 `.tsd`
### 自定义游戏插件
插件文件夹放在 `games/user/`
```
games/user/my_game/
├── manifest.json # 元信息
└── parser.py # 解析逻辑 (get_parser() + parse())
```
#### manifest.json
```json
{
"id": "my_game",
"name": "我的游戏",
"parser_type": "forza",
"description": "自定义游戏遥测",
"author": "你的名字",
"version": "1.0.0",
"default_port": 20777
}
```
#### parser.py
```python
import time
from server.telemetry.data import TelemetryData
def get_parser():
return MyGameParser()
class MyGameParser:
def game_id(self) -> str:
return "my_game"
def parse(self, data: bytes, addr: tuple) -> TelemetryData:
td = TelemetryData(game_id="my_game", timestamp=time.time())
td.raw = {"raw_hex": data.hex(), "length": len(data)}
# 解析你的游戏数据...
# td.speed_kmh = ...
# td.rpm = ...
# td.gear = ...
return td
```
打包分发:将文件夹压缩为 zip,改后缀为 `.tsp`,在设置页面导入。
### TelemetryData 可用字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `speed_kmh` | float | 速度 (km/h) |
| `speed_mph` | float | 速度 (mph) |
| `rpm` | float | 发动机转速 |
| `max_rpm` | float | 最大转速 |
| `gear` | int | 档位 (0=N, -1=R) |
| `throttle` | float | 油门 (0~1) |
| `brake` | float | 刹车 (0~1) |
| `clutch` | float | 离合 (0~1) |
| `handbrake` | float | 手刹 (0~1) |
| `steering` | float | 转向 (-1~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 | 原始数据 |
- [仪表盘开发指南](docs/DASHBOARD_DEV.md) — 创建自定义仪表盘主题
- [游戏插件兼容开发指南](docs/PLUGIN_DEV.md) — 为任意赛车游戏编写遥测解析器
## 项目结构