# TurboSu

赛车遥测仪表盘 — 基于 Web 的 B/S 架构外置仪表盘，支持多种赛车游戏遥测数据实时显示。

![License](https://img.shields.io/badge/license-Apache%202.0-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![Platform](https://img.shields.io/badge/platform-web%20%7C%20lan-brightgreen)

## 功能特性

- **多游戏支持** —— 插件化架构，内置支持 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