Yei.J. (AskaEth)
201 lines
5.7 KiB
Markdown
201 lines
5.7 KiB
Markdown
# 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
|