feat: TurboSu initial release - racing telemetry dashboard
This commit is contained in:
Yei.J. (AskaEth)
@@ -0,0 +1,200 @@
|
||||
# TurboSu
|
||||
|
||||
赛车遥测仪表盘 — 基于 Web 的 B/S 架构外置仪表盘，支持多种赛车游戏遥测数据实时显示。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **多游戏支持** —— 插件化架构，内置支持 Forza Horizon 4/5、Forza Motorsport、Assetto Corsa/ACC、F1、iRacing
|
||||
- **社区扩展** —— 游戏插件可独立导入导出，方便社区贡献小众游戏支持
|
||||
- **实时仪表盘** —— 速度表、转速表、档位指示器、圈速计时器等
|
||||
- **场景模式** —— 多仪表盘布局组合，支持多比例画布切换
|
||||
- **局域网共享** —— 仪表盘/场景生成独立链接，手机/平板/笔记本均可全屏访问
|
||||
- **跨端自适应** —— 响应式布局，桌面侧边栏 / 平板折叠 / 手机底部导航
|
||||
- **比例约束渲染** —— 每个仪表盘可指定渲染比例(auto/16:9/4:3/1:1)和渲染模式
|
||||
- **主题切换** —— Xiaomi HyperOS (Miuix) 风格，支持日间/夜间模式
|
||||
- **导出导入** —— 仪表盘主题和场景独立配置文件，社区友好
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Python 3.10+
|
||||
- pip
|
||||
|
||||
### 安装运行
|
||||
|
||||
```bash
|
||||
# 克隆/下载项目
|
||||
cd Project/TurboSu
|
||||
|
||||
# 创建虚拟环境
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 启动服务
|
||||
python app.py
|
||||
```
|
||||
|
||||
浏览器访问 `http://localhost:9527`
|
||||
|
||||
### 一键启动
|
||||
|
||||
```bash
|
||||
chmod +x run.sh
|
||||
./run.sh
|
||||
```
|
||||
|
||||
## 使用指南
|
||||
|
||||
### 1. 选择游戏
|
||||
|
||||
侧边栏 → "选择游戏" 下拉 → 点击你要玩的游戏。
|
||||
|
||||
游戏列表来自 `games/builtin/` (内置) 和 `games/user/` (社区插件)。
|
||||
|
||||
### 2. 配置游戏遥测输出
|
||||
|
||||
在各游戏中设置 UDP 数据输出：
|
||||
|
||||
| 游戏 | 设置位置 | 端口 |
|
||||
|------|----------|------|
|
||||
| Forza Horizon 4/5 | 设置 → HUD与游戏 → 数据输出 | 20777 |
|
||||
| Forza Motorsport | 设置 → 游戏玩法 → UDP 数据输出 | 20777 |
|
||||
| Assetto Corsa | 内容管理器 → 设置 → 自定义UDP | 9996 |
|
||||
| ACC | 设置 → 电子设备 → UDP | 20777 |
|
||||
| F1 24 | 设置 → 遥测设置 → UDP | 20777 |
|
||||
| iRacing | 选项 → 杂项 → 数据记录 | 20777 |
|
||||
|
||||
### 3. 浏览仪表盘
|
||||
|
||||
点击侧边栏 "仪表盘" → 浏览/筛选 → 点击卡片在新标签打开。
|
||||
|
||||
链接会自动复制，可在局域网设备(手机/平板)打开全屏显示。
|
||||
|
||||
### 4. 创建场景
|
||||
|
||||
侧边栏 → "场景" → 新建 → 编辑添加多个仪表盘 → 渲染。
|
||||
|
||||
场景支持多个画布比例(16:9/4:3等)，渲染前选择。
|
||||
|
||||
### 5. 数据调试
|
||||
|
||||
侧边栏 → "数据测试" → 查看解析后的实时数据和原始数据流。
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 创建自定义游戏插件
|
||||
|
||||
1. 在 `games/user/` 下创建文件夹，如 `games/user/my_game/`
|
||||
2. 创建 `manifest.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "my_game",
|
||||
"name": "我的游戏",
|
||||
"parser_type": "forza",
|
||||
"description": "自定义游戏遥测",
|
||||
"author": "你的名字",
|
||||
"version": "1.0.0",
|
||||
"default_port": 20777
|
||||
}
|
||||
```
|
||||
|
||||
3. 创建 `parser.py`:
|
||||
|
||||
```python
|
||||
import struct
|
||||
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
|
||||
```
|
||||
|
||||
4. 重启 TurboSu 或点击设置 → 重新加载插件
|
||||
|
||||
### 创建自定义仪表盘主题
|
||||
|
||||
在设置页面的仪表盘管理中创建，或直接编写配置文件。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
TurboSu/
|
||||
├── app.py # FastAPI 主入口
|
||||
├── config/settings.py # 全局配置管理
|
||||
├── server/
|
||||
│ ├── api.py # REST API 路由
|
||||
│ ├── websocket.py # WebSocket 实时推送
|
||||
│ ├── game_manager.py # 游戏插件管理器
|
||||
│ └── telemetry/
|
||||
│ ├── data.py # 遥测数据结构
|
||||
│ ├── listener.py # UDP 监听器
|
||||
│ └── parsers/ # 内置解析器
|
||||
├── games/
|
||||
│ ├── builtin/ # 内置游戏插件 (7款)
|
||||
│ └── user/ # 用户/社区插件
|
||||
├── models/
|
||||
│ ├── dashboard.py # 仪表盘数据模型
|
||||
│ └── scene.py # 场景数据模型
|
||||
├── dashboards/ # 内置仪表盘主题 (4款)
|
||||
├── templates/
|
||||
│ ├── index.html # 主 SPA 页面
|
||||
│ ├── dashboard.html # 仪表盘渲染页
|
||||
│ └── scene.html # 场景渲染页
|
||||
├── static/
|
||||
│ ├── css/
|
||||
│ │ ├── miuix.css # HyperOS 样式框架
|
||||
│ │ └── main.css # 布局样式
|
||||
│ └── js/ # 前端 JavaScript 模块
|
||||
├── utils/logger.py # 日志系统
|
||||
├── data/ # 运行时数据存储
|
||||
├── logs/ # 日志文件
|
||||
├── requirements.txt
|
||||
└── run.sh
|
||||
```
|
||||
|
||||
## 仪表盘配置说明
|
||||
|
||||
每个仪表盘主题的 `config.json` 支持以下渲染配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"aspect_ratio": "auto", // auto | 16:9 | 4:3 | 1:1 | 21:9
|
||||
"render_mode": "contain", // contain(留黑边) | cover(裁切) | fill(拉伸) | center(居中)
|
||||
"max_width": 1920, // center 模式最大宽度
|
||||
"max_height": 1080 // center 模式最大高度
|
||||
}
|
||||
```
|
||||
|
||||
## 作者
|
||||
|
||||
**Yei.J. (AskaEth)**
|
||||
|
||||
## 许可证
|
||||
|
||||
Apache License 2.0
|
||||
Reference in New Issue
Block a user