完善样式系统与调试链路底座

2026-03-30 18:19:05 +08:00
parent 2c0fd4c549
commit 3b9117427e
40 changed files with 7526 additions and 389 deletions
--- a/doc/config-template-minimal-game.md
+++ b/doc/config-template-minimal-game.md
@@ -0,0 +1,201 @@
+# 游戏最小可跑配置模板
+
+本文档提供一份 **去掉大部分选配项之后，当前客户端可以直接跑起来的最小配置模板**。
+
+目标：
+
+- 给联调、后台、快速起新活动一个最小起步模板
+- 保证只填最必要字段时，也能正常进入地图、开始比赛、完成流程
+- 每个字段都带简要说明，方便直接照着改
+
+说明：
+
+- 本模板优先保证“能跑”
+- 默认以**顺序赛**作为最小示例
+- 如果要做积分赛，只需要替换少量字段
+
+---
+
+## 1. 最小模板
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.30",
+  "app": {
+    "id": "sample-minimal-001",
+    "title": "最小顺序赛示例"
+  },
+  "map": {
+    "tiles": "../map/lxcb-001/tiles/",
+    "mapmeta": "../map/lxcb-001/tiles/meta.json"
+  },
+  "playfield": {
+    "kind": "course",
+    "source": {
+      "type": "kml",
+      "url": "../kml/lxcb-001/10/c01.kml"
+    }
+  },
+  "game": {
+    "mode": "classic-sequential",
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 5
+    }
+  }
+}
+```
+
+---
+
+## 2. 字段说明
+
+### `schemaVersion`
+
+- 类型：`string`
+- 必填：是
+- 说明：配置结构版本
+- 当前建议值：`"1"`
+
+### `version`
+
+- 类型：`string`
+- 必填：是
+- 说明：配置版本号
+- 建议写法：日期或发布号，例如 `2026.03.30`
+
+### `app.id`
+
+- 类型：`string`
+- 必填：是
+- 说明：活动配置实例 ID
+- 用途：区分不同活动或不同配置版本
+
+### `app.title`
+
+- 类型：`string`
+- 必填：是
+- 说明：活动标题 / 比赛名称
+
+### `map.tiles`
+
+- 类型：`string`
+- 必填：是
+- 说明：地图瓦片根路径
+
+### `map.mapmeta`
+
+- 类型：`string`
+- 必填：是
+- 说明：地图 meta 文件路径
+
+### `playfield.kind`
+
+- 类型：`string`
+- 必填：是
+- 说明：空间对象类型
+- 最小顺序赛推荐值：`course`
+- 最小积分赛推荐值：`control-set`
+
+### `playfield.source.type`
+
+- 类型：`string`
+- 必填：是
+- 说明：空间底稿来源类型
+- 当前推荐值：`kml`
+
+### `playfield.source.url`
+
+- 类型：`string`
+- 必填：是
+- 说明：KML 文件路径
+
+### `game.mode`
+
+- 类型：`string`
+- 必填：是
+- 说明：玩法模式
+- 当前常用值：
+  - `classic-sequential`
+  - `score-o`
+
+### `game.punch.policy`
+
+- 类型：`string`
+- 必填：是
+- 说明：打点触发方式
+- 当前常用值：
+  - `enter-confirm`
+  - `enter`
+
+### `game.punch.radiusMeters`
+
+- 类型：`number`
+- 必填：是
+- 说明：打点判定半径，单位米
+- 建议默认值：`5`
+
+---
+
+## 3. 最小积分赛改法
+
+如果你要把这份最小模板改成积分赛，只需要改这几项：
+
+```json
+{
+  "playfield": {
+    "kind": "control-set",
+    "source": {
+      "type": "kml",
+      "url": "../kml/lxcb-001/10/c01.kml"
+    }
+  },
+  "game": {
+    "mode": "score-o",
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 5
+    }
+  }
+}
+```
+
+---
+
+## 4. 当前最小模板默认逻辑
+
+即使你没有填写下面这些字段，当前客户端也会按默认逻辑运行：
+
+- `map.declination`
+  - 默认按 `0` 处理
+- `map.initialView.zoom`
+  - 默认由客户端初始视口逻辑接管
+- `playfield.CPRadius`
+  - 默认按客户端内置值处理
+- `game.session.*`
+  - 使用玩法默认逻辑
+- `game.guidance.*`
+  - 使用当前默认引导逻辑
+- `game.visibility.*`
+  - 使用当前默认可见性逻辑
+- `resources.*`
+  - 使用默认资源 profile
+- `debug.*`
+  - 默认关闭
+
+---
+
+## 5. 适用场景
+
+这份模板适合：
+
+- 新活动快速起盘
+- 联调验证地图和 KML 是否正常
+- 后台先跑通配置装配链
+- 调试客户端主流程是否可进入
+
+如果要做正式项目，请继续参考：
+
+- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config-template-full-current.md)
+- [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config-option-dictionary.md)