docs: update README and CONTRIBUTING for new folder structure and .tsd/.tss/.tsp formats

2026-07-25 15:36:36 +08:00
parent 63e3c8d607
commit a46e5d786d
2 changed files with 190 additions and 143 deletions
@@ -8,15 +8,16 @@

 ## 功能特性

- **多游戏支持** —— 插件化架构，内置支持 Forza Horizon 4/5、Forza Motorsport、Assetto Corsa/ACC、F1、iRacing
- **社区扩展** —— 游戏插件可独立导入导出，方便社区贡献小众游戏支持
- **实时仪表盘** —— 速度表、转速表、档位指示器、圈速计时器等
- **场景模式** —— 多仪表盘布局组合，支持多比例画布切换
- **局域网共享** —— 仪表盘/场景生成独立链接，手机/平板/笔记本均可全屏访问
- **跨端自适应** —— 响应式布局，桌面侧边栏 / 平板折叠 / 手机底部导航
- **比例约束渲染** —— 每个仪表盘可指定渲染比例(auto/16:9/4:3/1:1)和渲染模式
- **主题切换** —— Xiaomi HyperOS (Miuix) 风格，支持日间/夜间模式
- **导出导入** —— 仪表盘主题和场景独立配置文件，社区友好
+- **多游戏支持** — 插件化架构，内置 Forza Horizon 4/5、Forza Motorsport、Assetto Corsa/ACC、F1、iRacing
+- **社区扩展** — 游戏插件可独立打包导入导出 (`.tsp`)，方便社区贡献小众游戏支持
+- **实时仪表盘** — 速度表、转速表、档位指示器、圈速计时器
+- **独立仪表盘** — 每个仪表盘是独立文件夹 (`manifest.json` + `index.html`)，启动自动扫描
+- **场景模式** — 多仪表盘布局组合，支持多比例画布切换
+- **局域网共享** — 仪表盘/场景生成独立链接，手机/平板/笔记本均可全屏访问
+- **跨端自适应** — 响应式布局：桌面侧边栏 / 平板折叠 / 手机底部导航
+- **比例约束渲染** — 仪表盘可指定比例 (`auto`/`16:9`/`4:3`/`1:1`) 和渲染模式 (`contain`/`cover`/`fill`/`center`)
+- **HyperOS 风格** — Miuix 设计语言，毛玻璃模糊效果，日间/夜间模式
+- **社区分发** — 仪表盘 `.tsd`、场景 `.tss`、插件 `.tsp` — zip 格式，便于分享

 ## 快速开始

@@ -25,75 +26,108 @@
 - Python 3.10+
 - pip

-### 安装运行
+### 运行

 ```bash
-# 克隆/下载项目
-cd Project/TurboSu
+git clone ssh://git@git.yeij.top:2222/AskaEth/TurboSu.git
+cd TurboSu

-# 创建虚拟环境
-python3 -m venv venv
-source venv/bin/activate
+# 一键启动 (自动创建 venv 并安装依赖)
+./run.sh

-# 安装依赖
+# 或手动启动
+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/` (社区)。

-游戏列表来自 `games/builtin/` (内置) 和 `games/user/` (社区插件)。
+### 2. 配置遥测输出

-### 2. 配置游戏遥测输出
-
-在各游戏中设置 UDP 数据输出：
+在各游戏中开启 UDP 数据输出功能：

 | 游戏 | 设置位置 | 端口 |
 |------|----------|------|
 | Forza Horizon 4/5 | 设置 → HUD与游戏 → 数据输出 | 20777 |
-| Forza Motorsport | 设置 → 游戏玩法 → UDP 数据输出 | 20777 |
-| Assetto Corsa | 内容管理器 → 设置 → 自定义UDP | 9996 |
+| Forza Motorsport | 设置 → 游戏玩法 → UDP数据输出 | 20777 |
+| Assetto Corsa | 内容管理器 → 自定义UDP | 9996 |
 | ACC | 设置 → 电子设备 → UDP | 20777 |
 | F1 24 | 设置 → 遥测设置 → UDP | 20777 |
 | iRacing | 选项 → 杂项 → 数据记录 | 20777 |

 ### 3. 浏览仪表盘

-点击侧边栏 "仪表盘" → 浏览/筛选 → 点击卡片在新标签打开。
+侧边栏 → 仪表盘 → 浏览/分类筛选 → 点击卡片在新标签打开全屏仪表盘。

-链接会自动复制，可在局域网设备(手机/平板)打开全屏显示。
+链接自动复制，局域网设备可直接访问。右键卡片可导出 `.tsd` 文件。

 ### 4. 创建场景

-侧边栏 → "场景" → 新建 → 编辑添加多个仪表盘 → 渲染。
+侧边栏 → 场景 → 新建场景 → 编辑添加多个仪表盘 → 选择画布比例 → 渲染。

-场景支持多个画布比例(16:9/4:3等)，渲染前选择。
+场景卡片支持导出 `.tss`，页面顶栏可导入。

 ### 5. 数据调试

-侧边栏 → "数据测试" → 查看解析后的实时数据和原始数据流。
+侧边栏 → 数据测试 → 实时查看解析字段和原始 JSON 数据流。

 ## 开发指南

-### 创建自定义游戏插件
+### 自定义仪表盘格式

-1. 在 `games/user/` 下创建文件夹，如 `games/user/my_game/`
-2. 创建 `manifest.json`:
+每个仪表盘是一个独立文件夹，放在 `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
 {
@@ -107,10 +141,9 @@ chmod +x run.sh
 }
 ```

-3. 创建 `parser.py`:
+#### parser.py

 ```python
-import struct
 import time
 from server.telemetry.data import TelemetryData

@@ -126,70 +159,102 @@ class MyGameParser:
    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 或点击设置 → 重新加载插件
+打包分发：将文件夹压缩为 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 | 原始数据 |

 ## 项目结构

 ```
 TurboSu/
-├── app.py                    # FastAPI 主入口
-├── config/settings.py        # 全局配置管理
+├── app.py                    # FastAPI 主入口 (lifespan)
+├── run.sh                    # 一键启动脚本
+├── requirements.txt
+├── config/settings.py        # 全局配置 (JSON 持久化)
 ├── server/
-│   ├── api.py                # REST API 路由
-│   ├── websocket.py          # WebSocket 实时推送
-│   ├── game_manager.py       # 游戏插件管理器
+│   ├── api.py                # REST API (状态/配置/CRUD/导入导出)
+│   ├── websocket.py          # WebSocket 广播 (30fps 限流)
+│   ├── game_manager.py       # 游戏插件发现/加载/导入导出(.tsp)
 │   └── telemetry/
-│       ├── data.py           # 遥测数据结构
-│       ├── listener.py       # UDP 监听器
-│       └── parsers/          # 内置解析器
+│       ├── data.py           # TelemetryData 27字段数据类
+│       ├── listener.py       # UDP 异步监听器
+│       └── parsers/          # 内置解析器 (base/forza/ac/acc/f1/iracing)
 ├── games/
-│   ├── builtin/              # 内置游戏插件 (7款)
-│   └── user/                 # 用户/社区插件
+│   ├── builtin/              # 7 款内置游戏插件
+│   │   ├── forza_horizon_5/  # manifest.json + parser.py
+│   │   ├── forza_horizon_4/
+│   │   ├── forza_motorsport/
+│   │   ├── assetto_corsa/
+│   │   ├── assetto_corsa_competizione/
+│   │   ├── f1_24/
+│   │   └── iracing/
+│   └── user/                 # 社区插件 (运行时安装)
+├── dashboards/               # 内置仪表盘 (4 款)
+│   ├── speedometer/          # manifest.json + index.html
+│   ├── tachometer/
+│   ├── gear_indicator/
+│   └── lap_timer/
 ├── models/
-│   ├── dashboard.py          # 仪表盘数据模型
-│   └── scene.py              # 场景数据模型
-├── dashboards/               # 内置仪表盘主题 (4款)
+│   ├── dashboard.py          # 仪表盘模型 + 自动扫描 + zip导入导出
+│   └── scene.py              # 场景模型 + 画布/布局 + zip导入导出
 ├── templates/
 │   ├── index.html            # 主 SPA 页面
-│   ├── dashboard.html        # 仪表盘渲染页
-│   └── scene.html            # 场景渲染页
+│   └── scene.html            # 场景渲染页 (iframe组合)
 ├── static/
 │   ├── css/
-│   │   ├── miuix.css         # HyperOS 样式框架
-│   │   └── main.css          # 布局样式
-│   └── js/                   # 前端 JavaScript 模块
-├── utils/logger.py           # 日志系统
-├── data/                     # 运行时数据存储
-├── logs/                     # 日志文件
-├── requirements.txt
-└── run.sh
+│   │   ├── 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
 ```

-## 仪表盘配置说明
+## 导入导出格式

-每个仪表盘主题的 `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 模式最大高度
-}
-```
+| 格式 | 后缀 | 本质 | 说明 |
+|------|------|------|------|
+| 仪表盘 | `.tsd` | zip | 含 `manifest.json` + `index.html` |
+| 场景 | `.tss` | zip | 含 `scene.json` |
+| 游戏插件 | `.tsp` | zip | 含 `manifest.json` + `parser.py` |

 ## 作者