158 lines
6.3 KiB
Markdown
158 lines
6.3 KiB
Markdown
# TurboSu · 极速中枢
|
|
|
|
基于 Web 的 B/S 架构赛车遥测仪表盘，支持多种赛车游戏遥测数据实时显示。
|
|
社区市场在线分享仪表盘和场景。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 功能特性
|
|
|
|
- **多游戏支持** — 插件化架构，内置 Forza Horizon、Forza Motorsport、AC/ACC、F1、iRacing
|
|
- **8 款内置仪表盘** — 速度表、转速弧、档位指示器、圈速计时器、Forza 复合仪表、F1 复合仪表、G 力圆图、轮胎温度矩阵、换挡指示灯、手机竖屏仪表
|
|
- **场景编辑器** — 拖放式画布，自由组合多个仪表盘到同一画面
|
|
- **局域网共享** — 仪表盘/场景独立链接，手机/平板/笔记本均可全屏访问
|
|
- **比例约束渲染** — 仪表盘可指定比例和渲染模式
|
|
- **社区市场** — 在线分享仪表盘和场景，登录即上传，管理员审核发布
|
|
- **录制回放** — 录制原始 UDP 流，离线回放调试仪表盘
|
|
- **数据转发** — 原始 UDP 包转发到下游物理外设
|
|
- **HyperOS 风格** — Miuix 设计语言，日间/夜间模式，中英文切换
|
|
- **社区分发** — 仪表盘 `.tsd`、场景 `.tss`、插件 `.tsp` — zip 格式
|
|
|
|
## 快速开始
|
|
|
|
### 环境要求
|
|
|
|
- Python 3.10+
|
|
- pip
|
|
|
|
### 运行
|
|
|
|
```bash
|
|
git clone https://git.yeij.top/AskaEth/TurboSu.git
|
|
cd TurboSu
|
|
|
|
# 一键启动
|
|
./run.sh
|
|
|
|
# 或手动启动
|
|
python3 -m venv venv && source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
python app.py
|
|
```
|
|
|
|
浏览器访问 `http://localhost:9527`
|
|
|
|
## 使用指南
|
|
|
|
### 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. 浏览仪表盘
|
|
|
|
侧边栏 → 仪表盘 → 浏览/分类筛选 → 点击卡片在新标签打开全屏仪表盘。
|
|
|
|
链接自动复制，局域网设备可直接访问。右键卡片可导出 `.tsd` 文件。
|
|
|
|
### 4. 创建场景
|
|
|
|
侧边栏 → 场景 → 新建场景 → 编辑添加多个仪表盘 → 选择画布比例 → 渲染。
|
|
|
|
场景卡片支持导出 `.tss`，页面顶栏可导入。
|
|
|
|
### 5. 数据调试
|
|
|
|
侧边栏 → 数据测试 → 实时查看解析字段和原始 JSON 数据流。
|
|
|
|
## 开发指南
|
|
|
|
- [仪表盘开发指南](docs/DASHBOARD_DEV.md) — 创建自定义仪表盘主题 (.tsd)
|
|
- [游戏插件兼容开发指南](docs/PLUGIN_DEV.md) — 为任意赛车游戏编写遥测解析器 (.tsp)
|
|
- [Forza 数据包格式参考](docs/FH_DATA_FORMAT.md) — 官方 UDP 包 324 字节完整字段定义
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
TurboSu/
|
|
├── app.py # FastAPI 主入口 (lifespan)
|
|
├── run.sh # 一键启动脚本
|
|
├── requirements.txt
|
|
├── config/settings.py # 全局配置 (JSON 持久化)
|
|
├── server/
|
|
│ ├── api.py # REST API (状态/配置/CRUD/导入导出)
|
|
│ ├── websocket.py # WebSocket 广播 (30fps 限流)
|
|
│ ├── game_manager.py # 游戏插件发现/加载/导入导出(.tsp)
|
|
│ └── telemetry/
|
|
│ ├── data.py # TelemetryData 27字段数据类
|
|
│ ├── listener.py # UDP 异步监听器
|
|
│ └── parsers/ # 内置解析器 (base/forza/ac/acc/f1/iracing)
|
|
├── games/
|
|
│ ├── builtin/ # 7 款内置游戏插件
|
|
│ │ ├── forza_horizon/ # Forza Horizon 4/5 (合并)
|
|
│ │ ├── forza_horizon_6/ # Forza Horizon 6
|
|
│ │ ├── forza_motorsport/
|
|
│ │ ├── assetto_corsa/
|
|
│ │ ├── assetto_corsa_competizione/
|
|
│ │ ├── f1_24/
|
|
│ │ └── iracing/
|
|
│ └── user/ # 社区插件 (运行时安装)
|
|
├── dashboards/ # 内置仪表盘 (5 款)
|
|
│ ├── speedometer/ # 极速仪表 (auto 比例, 全兼容)
|
|
│ ├── tachometer/ # 转速表 (16:9, 全兼容)
|
|
│ ├── gear_indicator/ # 档位指示器 (1:1, R/N/1-8, 自适应映射)
|
|
│ ├── lap_timer/ # 圈速计时器 (4:3, Forza/F1)
|
|
│ └── forza_composite/ # Forza 复合仪表 (16:9, 仅Forza系列)
|
|
├── models/
|
|
│ ├── dashboard.py # 仪表盘模型 + 自动扫描 + zip导入导出
|
|
│ └── scene.py # 场景模型 + 画布/布局 + zip导入导出
|
|
├── templates/
|
|
│ ├── index.html # 主 SPA 页面
|
|
│ └── scene.html # 场景渲染页 (iframe组合)
|
|
├── static/
|
|
│ ├── css/
|
|
│ │ ├── miuix.css # HyperOS/Miuix 样式框架 (CSS变量+毛玻璃+主题)
|
|
│ │ └── main.css # 布局 + 跨端响应式 (3断点)
|
|
│ └── js/
|
|
│ ├── app.js / router.js # 应用入口 + Hash路由
|
|
│ ├── api.js / ws.js # API + WebSocket 客户端
|
|
│ ├── components/ # sidebar.js / topbar.js
|
|
│ ├── pages/ # home / dashboard / scene / debug / settings
|
|
│ └── utils/ # theme.js / toast.js
|
|
├── data/ # 运行时数据 (user dashboards, scenes, config)
|
|
├── logs/ # 日志 (轮转文件, 10MB x5)
|
|
├── README.md
|
|
└── CONTRIBUTING.md
|
|
```
|
|
|
|
## 导入导出格式
|
|
|
|
| 格式 | 后缀 | 本质 | 说明 |
|
|
|------|------|------|------|
|
|
| 仪表盘 | `.tsd` | zip | 含 `manifest.json` + `index.html` |
|
|
| 场景 | `.tss` | zip | 含 `scene.json` |
|
|
| 游戏插件 | `.tsp` | zip | 含 `manifest.json` + `parser.py` |
|
|
|
|
## 作者
|
|
|
|
**Yei.J. (AskaEth)**
|
|
|
|
## 许可证
|
|
|
|
Apache License 2.0
|