Initial commit: Client Doc docs Server Tools

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-10 10:24:29 +08:00
commit 7e35d8da31
3374 changed files with 680813 additions and 0 deletions
@@ -0,0 +1,121 @@
+{
+  "schemaVersion": 1,
+  "prefabName": "UI_LobbyJoystick",
+  "prefabPath": "Assets/Game/Art/UI/Prefab/UI_LobbyJoystick.prefab",
+  "description": "Lobby virtual joystick HUD prefab. Runtime code attaches it to the lobby HUD canvas and refreshes the final lower-left layout from LobbyWorldController constants.",
+  "canvas": {
+    "canvasScaler": {
+      "referenceResolution": [2048, 1024],
+      "matchWidthOrHeight": 0.5
+    }
+  },
+  "assets": {
+    "sprites": {
+      "lobby_joystick_base": "Assets/Game/Art/UI/Texture/Common/lobby_joystick_base.png",
+      "lobby_joystick_ring": "Assets/Game/Art/UI/Texture/Common/lobby_joystick_ring.png",
+      "lobby_joystick_knob": "Assets/Game/Art/UI/Texture/Common/lobby_joystick_knob.png"
+    }
+  },
+  "nodes": [
+    {
+      "name": "UI_LobbyJoystick",
+      "parent": null,
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0],
+        "anchorMax": [0, 0],
+        "pivot": [0.5, 0.5],
+        "anchoredPosition": [208, 158],
+        "sizeDelta": [148, 148]
+      },
+      "components": [
+        {
+          "type": "CanvasGroup",
+          "alpha": 0.96,
+          "interactable": false,
+          "blocksRaycasts": false
+        }
+      ]
+    },
+    {
+      "name": "Base",
+      "parent": "UI_LobbyJoystick",
+      "active": true,
+      "rect": {
+        "anchorMin": [0.5, 0.5],
+        "anchorMax": [0.5, 0.5],
+        "pivot": [0.5, 0.5],
+        "anchoredPosition": [0, 0],
+        "sizeDelta": [148, 148]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "lobby_joystick_base",
+          "imageType": "Simple",
+          "preserveAspect": true,
+          "raycastTarget": false,
+          "color": "#FFFFFFFF"
+        },
+        {
+          "type": "Shadow",
+          "effectColor": "#06101F6B",
+          "effectDistance": [0, -7],
+          "useGraphicAlpha": true
+        }
+      ]
+    },
+    {
+      "name": "Ring",
+      "parent": "UI_LobbyJoystick",
+      "active": true,
+      "rect": {
+        "anchorMin": [0.5, 0.5],
+        "anchorMax": [0.5, 0.5],
+        "pivot": [0.5, 0.5],
+        "anchoredPosition": [0, 0],
+        "sizeDelta": [148, 148]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "lobby_joystick_ring",
+          "imageType": "Simple",
+          "preserveAspect": true,
+          "raycastTarget": false,
+          "color": "#FFFFFFFF"
+        }
+      ]
+    },
+    {
+      "name": "Knob",
+      "parent": "UI_LobbyJoystick",
+      "active": true,
+      "rect": {
+        "anchorMin": [0.5, 0.5],
+        "anchorMax": [0.5, 0.5],
+        "pivot": [0.5, 0.5],
+        "anchoredPosition": [0, 0],
+        "sizeDelta": [56, 56]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "lobby_joystick_knob",
+          "imageType": "Simple",
+          "preserveAspect": true,
+          "raycastTarget": false,
+          "color": "#FFFFFFFF"
+        },
+        {
+          "type": "Shadow",
+          "effectColor": "#06101F5C",
+          "effectDistance": [0, -5],
+          "useGraphicAlpha": true
+        }
+      ]
+    }
+  ],
+  "bindings": [],
+  "events": []
+}
@@ -0,0 +1,187 @@
+{
+  "schemaVersion": 1,
+  "prefabName": "UI_MiniGameResult",
+  "prefabPath": "Assets/Game/Art/UI/Prefab/UI_MiniGameResult.prefab",
+  "description": "小游戏通用结算弹窗(胜利/失败/平局 + 比分文本 + 确定)。自带 Canvas(sortingOrder 30000)覆盖在小游戏 UI 之上;由 MiniGameHost 运行时按名绑定 Txt_Title/Txt_Message/Btn_Ok,无 MonoBehaviour 控制器。",
+  "canvas": {
+    "canvasScaler": {
+      "referenceResolution": [2048, 1024],
+      "matchWidthOrHeight": 0.5
+    }
+  },
+  "assets": {
+    "sprites": {
+      "ui_overlay_dim": "Assets/Game/Art/UI/Texture/Common/ui_overlay_dim.png",
+      "ui_panel_popup": "Assets/Game/Art/UI/Texture/Common/ui_panel_popup.png",
+      "btn_primary_normal": "Assets/Game/Art/UI/Texture/Common/btn_primary_normal.png",
+      "btn_primary_hover": "Assets/Game/Art/UI/Texture/Common/btn_primary_hover.png",
+      "btn_primary_pressed": "Assets/Game/Art/UI/Texture/Common/btn_primary_pressed.png",
+      "btn_primary_disabled": "Assets/Game/Art/UI/Texture/Common/btn_primary_disabled.png"
+    }
+  },
+  "nodes": [
+    {
+      "name": "UI_MiniGameResult",
+      "parent": null,
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0],
+        "anchorMax": [1, 1],
+        "offsetMin": [0, 0],
+        "offsetMax": [0, 0]
+      },
+      "components": [
+        {
+          "type": "Canvas",
+          "sortingOrder": 30000
+        },
+        {
+          "type": "CanvasScaler",
+          "referenceResolution": [2048, 1024],
+          "matchWidthOrHeight": 0.5
+        },
+        {
+          "type": "GraphicRaycaster"
+        }
+      ]
+    },
+    {
+      "name": "Img_Mask",
+      "parent": "UI_MiniGameResult",
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0],
+        "anchorMax": [1, 1],
+        "offsetMin": [0, 0],
+        "offsetMax": [0, 0]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "ui_overlay_dim",
+          "imageType": "Simple",
+          "raycastTarget": true,
+          "color": "#FFFFFFFF"
+        }
+      ]
+    },
+    {
+      "name": "Panel",
+      "parent": "Img_Mask",
+      "active": true,
+      "rect": {
+        "anchorMin": [0.5, 0.5],
+        "anchorMax": [0.5, 0.5],
+        "pivot": [0.5, 0.5],
+        "anchoredPosition": [0, 0],
+        "sizeDelta": [680, 420]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "ui_panel_popup",
+          "imageType": "Sliced",
+          "raycastTarget": true,
+          "color": "#FFFFFFFF"
+        }
+      ]
+    },
+    {
+      "name": "Txt_Title",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 1],
+        "anchorMax": [1, 1],
+        "pivot": [0.5, 1],
+        "anchoredPosition": [0, -72],
+        "sizeDelta": [-96, 76]
+      },
+      "components": [
+        {
+          "type": "TextMeshProUGUI",
+          "text": "游戏结束",
+          "fontSize": 52,
+          "fontStyle": "Bold",
+          "alignment": "Center",
+          "color": "#102033FF"
+        }
+      ]
+    },
+    {
+      "name": "Txt_Message",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0],
+        "anchorMax": [1, 1],
+        "pivot": [0.5, 0.5],
+        "anchoredPosition": [0, -14],
+        "sizeDelta": [-112, -240]
+      },
+      "components": [
+        {
+          "type": "TextMeshProUGUI",
+          "text": "",
+          "fontSize": 34,
+          "alignment": "Center",
+          "color": "#2F4256FF"
+        }
+      ]
+    },
+    {
+      "name": "Btn_Ok",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0.5, 0],
+        "anchorMax": [0.5, 0],
+        "pivot": [0.5, 0],
+        "anchoredPosition": [0, 44],
+        "sizeDelta": [240, 84]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "btn_primary_normal",
+          "imageType": "Sliced",
+          "raycastTarget": true,
+          "color": "#FFFFFFFF"
+        },
+        {
+          "type": "Button",
+          "transition": "SpriteSwap",
+          "spriteHighlighted": "btn_primary_hover",
+          "spritePressed": "btn_primary_pressed",
+          "spriteDisabled": "btn_primary_disabled",
+          "onClick": "MiniGame.ResultConfirm"
+        }
+      ]
+    },
+    {
+      "name": "Txt_Ok",
+      "parent": "Btn_Ok",
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0],
+        "anchorMax": [1, 1],
+        "offsetMin": [0, 0],
+        "offsetMax": [0, 0]
+      },
+      "components": [
+        {
+          "type": "TextMeshProUGUI",
+          "text": "确定",
+          "fontSize": 36,
+          "fontStyle": "Bold",
+          "alignment": "Center",
+          "color": "#1F3A0EFF"
+        }
+      ]
+    }
+  ],
+  "bindings": ["Txt_Title", "Txt_Message"],
+  "events": [
+    { "name": "MiniGame.ResultConfirm", "node": "Btn_Ok" }
+  ]
+}
@@ -0,0 +1,235 @@
+# Unity UI 组件设计原则
+
+> 本文档依据视觉基准图 `Doc/Design/ui_design.jpg` 提炼，定义本项目休闲卡通风格 UI 的统一设计语言与各类 UGUI 控件的设计规范。
+> 配套规范见 `Client/Assets/Doc/Rule/UnityProject.md`（制作流程、JSON→Prefab 管线）与 `Doc/Design/UI_Pic_Set.md`（通用控件切图清单）。
+> 通用控件切图位于 `Assets/Game/Art/UI/Texture/Common`。
+
+---
+
+## 1. 总体视觉风格
+
+休闲、友好、明快的卡通糖果风（casual candy style），强调“圆润、厚实、有光泽、易读”：
+
+- **圆角厚实**：所有容器、按钮、控件均为大圆角矩形或胶囊形，无尖角；体块饱满，像玩具/糖果。
+- **描边收边**：控件外缘有一圈比主体更深的同色系描边（约 2–4px），让控件从背景中“跳”出来。
+- **顶部高光**：主体上半部有一道柔和的白色玻璃高光，营造塑料/糖果的反光质感。
+- **柔和投影**：控件下方有短距离、低透明度的柔和阴影（非硬黑边），增强层次。
+- **暖色容器 + 亮色控件**：面板多为奶油米色/浅蓝底，功能控件用高饱和糖果色点亮。
+- **图标拟物 + 描边**：业务图标为有体积感的拟物卡通图标，统一带深色描边与高光。
+
+设计目标：在手机小屏上**一眼可辨、点击区域明确、状态反馈清晰**。
+
+---
+
+## 2. 配色系统
+
+以下为基准图取色（十六进制为参考值，允许 ±5% 微调；实际以切图为准）。
+
+### 2.1 背景与容器
+
+| 用途 | 颜色 | 参考值 |
+| --- | --- | --- |
+| 全局背景 | 浅蓝白 | `#EAF3F8` |
+| 主面板底（奶油米） | 暖米色 | `#F6EBCF` |
+| 面板描边（暖棕） | 棕 | `#C89B5C` |
+| 浅蓝面板底 | 浅蓝 | `#DCEBF5` |
+| 内容卡片底 | 近白 | `#FBF6E9` |
+| 半透明遮罩 | 深蓝黑 | `#0B1724` @ 70–80% |
+
+### 2.2 功能色（按钮/状态）
+
+| 语义 | 主色 | 描边/按下态 | 用途 |
+| --- | --- | --- | --- |
+| 主操作 Primary | 草绿 `#7ED321` | 深绿 `#4E9A12` | 确定、开始、匹配等主行为 |
+| 次操作 Secondary | 天蓝 `#43B7F5` | 深蓝 `#1E84C8` | 取消、次要行为 |
+| 强调 Emphasis | 橙黄 `#FFB13C` | 深橙 `#E07C18` | 需要吸引注意但非危险 |
+| 危险 Danger | 珊瑚红 `#FF5B5B` | 深红 `#D63333` | 删除、退出、警告 |
+| 禁用 Disabled | 灰 `#B9C0C8` | 深灰 `#8A929B` | 不可点击 |
+| 选中高亮 | 亮绿 `#9EEB3B` | — | 选中态染色/描边 |
+
+### 2.3 文本色
+
+| 用途 | 颜色 | 参考值 |
+| --- | --- | --- |
+| 深色正文（浅底上） | 深棕/深蓝灰 | `#5A4632` / `#33405E` |
+| 浅色文字（按钮/深底上） | 近白 | `#F6F8FF` |
+| 次要说明文字 | 蓝灰 | `#B7C2D8` |
+| 数值高亮（金币/比分） | 金黄 | `#FFE27A` |
+| 文字描边（统一） | 深蓝/深灰 | `#102033` / `#0B1724`（**不使用纯黑**） |
+
+### 2.4 图标点缀色
+
+金币金 `#F5C033`、钻石蓝 `#46C8E6`、生命红 `#FF6B83`、能量绿 `#7ED321`、星黄 `#FFD54A`、防具蓝 `#5B8FE6`，整体保持高饱和、同族描边。
+
+---
+
+## 3. 形状语言（圆角 / 描边 / 高光 / 阴影）
+
+| 要素 | 规范 |
+| --- | --- |
+| 圆角 | 按钮/卡片圆角半径约为短边的 25–40%；胶囊控件（开关、进度条、滑条）为全圆端。 |
+| 描边 | 外描边宽度 2–4px，颜色为主体色加深约 20–30%；描边随控件等比，不随九宫格拉伸变形（见第 8 节）。 |
+| 高光 | 主体上半部一道柔和白色高光（透明度 30–60%），覆盖上 40% 区域，向下渐隐。 |
+| 阴影 | 投影偏移 `(0, -6 ~ -8)`，颜色 `#06101F` @ 70–80%，软边；用 UGUI `Shadow` 组件实现。 |
+| 内凹 | 进度条/滑条/输入框的“槽”为内凹深色底，填充为带高光的亮色，形成凹凸对比。 |
+
+---
+
+## 4. 字体与可读性
+
+- 统一使用 **TextMeshPro**（`TextMeshProUGUI` / `TMP_InputField` / `TMP_Dropdown`），默认字体思源黑体 CN Regular（`Assets/Game/Art/UI/Font/SourceHanSansCN-Regular.otf` 的 SDF 资源）。
+- **字号层级**（2048×1024 设计分辨率参考）：界面标题 36–40；区块标题 28–32；按钮文字 24–30；正文/列表 20–24；说明/次要 18–20；大数值（比分等）64–80。
+- **字重**：标题、按钮、状态、倒计时用 Bold；正文用 Regular。
+- **可读性**（与 `UnityProject.md` 第 38–40 条一致）：
+  - 浅色文字位于图片背景、高饱和按钮、半透明面板上时，**必须**加深蓝/深灰描边或阴影（`#102033` / `#0B1724`），描边宽度保持轻量，避免粗黑边弄脏画面。
+  - 普通正文、列表、输入框文本优先靠背景对比度保证可读，不默认加描边。
+  - 深底面板放浅色字、浅底面板放深色字；避免浅色字直接压在浅底上。
+
+---
+
+## 5. 各控件设计原则
+
+### 5.1 面板 / 弹窗 (Panel)
+
+- 结构：标题栏（深色木纹/蓝色横幅）+ 内容区（奶油米底）+ 操作区（底部按钮）。
+- 弹窗右上角固定圆形关闭按钮（红色 `btn_close`）；模态弹窗下方铺半透明遮罩拦截点击。
+- 切图：`ui_panel_main`（主窗）、`ui_panel_popup`（弹窗）、`ui_panel_content`（内容卡）、`ui_panel_header`（标题栏）、`ui_panel_tooltip`（提示），均为 **九宫格 Sliced**。
+- 内容区四周留白≥24px；标题居中或左对齐配图标。
+
+### 5.2 按钮 (Button)
+
+- 四种语义色：主(绿)/次(蓝)/强调(橙)/危险(红)，外形一致仅配色不同。
+- **必须实现完整状态**（`Button` + SpriteSwap，见第 7 节）：Normal / Highlighted(Hover) / Pressed / Disabled。
+- 按下态：颜色加深 + 视觉下沉（高光减弱、整体下移 1–2px 的观感）。
+- 文字白色 + 轻描边；带图标时图标在左、文字居中或图标在上文字在下。
+- 尺寸：主按钮高度≥72（设计分辨率），点击热区不小于可视区；小按钮成组排列。
+- 切图：`btn_primary_*`、`btn_secondary_*`、`btn_warning_*`、`btn_small_*`、圆形 `btn_close`/`btn_back`/`btn_home`。
+
+### 5.3 输入框 (TMP_InputField)
+
+- 浅蓝/白圆角底，内凹观感；左侧可选图标，右侧可选功能图标（编辑/搜索/清空）。
+- 必须声明 `placeholder`、`characterLimit`、`contentType`（密码用 `Password`）。
+- 占位符用次要蓝灰色 `#B7C2D8`；输入文本用深色，靠背景对比保证可读，不加描边。
+- 切图：`input_bg_normal` / `input_bg_focus` / `input_bg_error`，光标 `input_caret`。
+
+### 5.4 下拉框 (TMP_Dropdown)
+
+- 暖黄/白圆角底，右侧朝下三角箭头 `dropdown_arrow`。
+- 展开列表复用列表项样式（见 5.8）。切图 `dropdown_bg`。
+
+### 5.5 数值步进器 (Stepper)
+
+- 形式：`[ − ]  数值  [ + ]`，减号红圆按钮、加号绿圆按钮，中间数值居中。
+- 复用 `ico_minus`/`ico_plus` 圆形按钮 + 输入/显示框。
+
+### 5.6 进度条 (Progress)
+
+- 内凹深色底槽 + 高光亮色填充（绿/蓝/橙），全圆端胶囊形。
+- 左端可挂圆形图标徽章，填充上叠加数值文本（如 `350/500`、`80%`），文本白色加轻描边。
+- 切图：`progress_bg` + `progress_fill_*`，填充用 **Filled 或 Sliced**；脚本驱动时按 `sizeDelta.x` 或 `fillAmount` 改变。
+
+### 5.7 滑动条 (Slider)
+
+- 内凹轨道 + 亮色已填充段 + 圆形拖拽手柄（白/蓝带高光）。
+- 左侧图标说明（音量/音乐/亮度），右侧显示百分比。
+- 切图：`slider_track` / `slider_fill` / `slider_handle`。
+
+### 5.8 滚动列表与滚动条 (ScrollView / Scrollbar)
+
+- 列表项：奶油米圆角卡片，左图标 + 主标题 + 次要描述 + 右侧 chevron 箭头。
+- 列表项状态：普通 `ui_list_item_normal`、选中 `ui_list_item_selected`、禁用 `ui_list_item_disabled`（均九宫格）。
+- 滚动条：内凹轨道 `scrollbar_track_*` + 亮蓝滑块 `scrollbar_thumb_*`，全圆端。
+- 内容用 `VerticalLayoutGroup` + `ContentSizeFitter`，视口用 `RectMask2D` 裁剪。
+
+### 5.9 开关 / 勾选 / 单选 (Toggle / Checkbox / Radio)
+
+- 开关：胶囊轨道（开=绿 `toggle_bg_on` / 关=灰 `toggle_bg_off`）+ 白色圆形滑块 `toggle_knob`，配 开/关 文案。
+- 复选框：`checkbox_off` / `checkbox_on`（圆角方形 + 对勾）；单选：`radio_off` / `radio_on`（圆形 + 实心点）。
+
+### 5.10 页签 (Tab)
+
+- 选中态高亮（蓝）凸起 `tab_active`，未选中态浅色下沉 `tab_inactive`；选中页签与内容区无缝相连。
+- 分段控件用 `seg_left` / `seg_mid` / `seg_right` 拼接。
+
+### 5.11 角标 / 徽章 (Badge)
+
+- 图标按钮右上角红色圆形数字角标（未读/数量），切图 `ui_badge_alert`（红点/提醒）、`ui_badge_base`（普通）。
+- 角标数字白色加粗；红点用于“有更新”无数字场景。
+
+### 5.12 业务图标 (Icon)
+
+- 拟物卡通 + 统一深色描边 + 高光；尺寸基准 64×64，重要图标可放大。
+- 常用：货币 `ico_coin`、钻石 `ico_diamond`、生命 `ico_heart`、能量、星级 `ico_star`、防具 `ico_shield`、武器 `ico_sword`、背包 `ico_bag`、地图 `ico_map`、钥匙 `ico_key`、设置 `ico_settings` 等。
+- 图标槽/道具格用 `slot_empty` / `slot_selected` / `slot_locked`（九宫格）。
+
+### 5.13 资源/货币条 (Currency)
+
+- 形式：圆形货币图标 + 数值（金黄高亮）+ 末尾绿色加号按钮（前往充值/获取）。
+- 数值用千分位，居中垂直对齐图标。
+
+### 5.14 头像 / 玩家卡 (Avatar)
+
+- 圆形头像框 `avatar_frame` + 等级角标 + 昵称 + 经验进度条（如 `870/1500`）。
+
+### 5.15 底部导航 (Bottom Nav)
+
+- 一排图标按钮（首页/背包/任务/商店/设置），当前页高亮（凸起蓝底 + 图标点亮），其余浅色。
+- 当前项放大并加底色块区分。
+
+---
+
+## 6. 状态与反馈
+
+每个可交互控件至少定义以下状态，保证“可点、已选、不可点”一目了然：
+
+| 状态 | 表现 |
+| --- | --- |
+| Normal | 默认色 + 高光 + 描边 |
+| Highlighted/Hover | 整体提亮（更亮/更饱和） |
+| Pressed | 加深 + 下沉，高光减弱 |
+| Disabled | 去饱和转灰 + 降透明，无高光 |
+| Selected/Active | 选中色描边或染色（亮绿 `#9EEB3B`），或凸起 |
+
+- 按钮优先用 **SpriteSwap**（不同状态用不同切图）；无专用切图时退化为 ColorTint。
+- 选中反馈可叠加：背景换图 + 文字变色/加粗（如列表当前项）。
+- 关键操作（确定/危险）给与即时视觉与（可选）音效反馈。
+
+---
+
+## 7. 与 Unity 实现的衔接
+
+- 控件优先复用 `Assets/Game/Art/UI/Texture/Common` 通用切图；缺图时用 gptimage2 按本风格生成到该目录（见 `UnityProject.md` 第 6 条）。
+- 新界面按 **JSON→Prefab 管线**：在 `Doc/UIPrefabCreater/` 写界面描述 JSON，Unity 自动生成 Prefab（`UnityProject.md` 第 26–46 条）。
+- 文本控件统一 TextMeshPro；按钮 `transition` 优先 `SpriteSwap`；九宫格图片声明 `"imageType": "Sliced"`，进度填充可用 `"Filled"`。
+- 按钮 SpriteSwap 状态对应切图：`*_normal`(Target) / `*_hover`(Highlighted) / `*_pressed`(Pressed) / `*_disabled`(Disabled)。
+
+---
+
+## 8. 九宫格与间距
+
+- **九宫格 (Sliced)**：所有可拉伸容器（面板、按钮、输入框、进度条、列表项等）必须设置正确的 `Border`，保证圆角与描边在任意尺寸下不变形；`Border` 值参考 `Doc/UI_Pic_Set.md` 各切片。
+- 导入设置：Texture Type = `Sprite (2D and UI)`，勾选 `Alpha Is Transparency`，Mesh Type = `Full Rect`，Filter = Bilinear。
+- **间距节奏**：统一使用 8 的倍数（8 / 16 / 24 / 32）。控件内边距≥16，区块间距≥24，安全区四周≥24。
+- 切图四周保留约 2px 透明边，避免双线性采样串色（项目切图已统一处理）。
+
+---
+
+## 9. 分辨率与适配
+
+- 设计分辨率 **2048×1024**（`CanvasScaler` = ScaleWithScreenSize，referenceResolution `[2048,1024]`，Match = 0.5）。
+- 布局以锚点为主：全屏元素用拉伸锚点；角标/悬浮按钮锚到对应屏幕角；主面板居中。
+- 关键信息放安全区内，避免刘海/圆角遮挡；考虑长宽比从 4:3 到 20:9 的适配。
+- 重要图标与文字用 `None`/`High Quality` 压缩，避免边缘与文字出现压缩噪点。
+
+---
+
+## 10. 设计检查清单（提交前自检）
+
+- [ ] 配色取自第 2 节调色板，语义色使用正确（绿=主/蓝=次/橙=强调/红=危险）。
+- [ ] 控件有圆角 + 描边 + 高光 + 柔和阴影，风格与 `ui_design.jpg` 一致。
+- [ ] 可交互控件具备 Normal/Hover/Pressed/Disabled（必要时 Selected）状态。
+- [ ] 文字用 TMP；浅色字在复杂/高饱和/深底上加了深蓝灰描边；深浅对比充足。
+- [ ] 可拉伸控件设置了正确的九宫格 Border，任意尺寸不变形。
+- [ ] 间距为 8 的倍数；点击热区足够大。
+- [ ] referenceResolution = [2048,1024]，锚点适配多分辨率。
+- [ ] 复用 Common 通用切图；新图按本风格用 gptimage2 生成到对应目录。
@@ -0,0 +1,192 @@
+# Unity UI 2048x2048 图集切片规划
+
+## 1. 目标
+
+将一套常用 Unity UGUI 控件切图放入一张 `2048x2048` 贴图中，供 Sprite Editor 按坐标切片后在按钮、面板、输入框、进度条、滑动条、滚动列表、弹窗、图标等控件中复用。
+风格参考：Doc\Design\ui_design.jpg
+
+当前项目中没有独立的 UI 图集素材目录；已有代码和预制体主要用到 `Button`、`InputField`、`Slider`、`Image`、二维码/扫码入口、Lua UI 面板、滚动列表等控件。因此本图集按项目现有控件和后续常用 UI 控件做统一规划。
+
+## 2. 坐标规则
+
+- 图集尺寸：`2048x2048`。
+- 表中 `X`、`Y(左上)` 以图片左上角为原点，适合给美术和切图工具对齐。
+- `Unity Y(左下)` 以 Unity Sprite Editor 的左下角为原点，计算公式为：`2048 - Y(左上) - H`。
+- 所有切片之间保留至少 `8px` 间隔，降低双线性采样和 mipmap 边缘串色风险。
+- `9-slice` 切片需要在 Unity Sprite Editor 中设置 `Border`，格式为 `Left, Right, Top, Bottom`。
+- `simple` 切片不设置九宫格，按原始比例或等比缩放使用。
+
+## 3. 图集分区
+
+| 区域 | Y 范围 | 内容 |
+| --- | ---: | --- |
+| 面板与容器 | `0-640` | 主面板、弹窗、内容底、标题栏、列表项、遮罩、分割线、角标 |
+| 按钮与页签 | `648-832` | 主按钮、次按钮、小按钮、警告按钮、页签、分段控件、导航按钮 |
+| 输入与表单 | `840-920` | 输入框、下拉框、光标、搜索/清空/复制等输入辅助图标 |
+| 进度与滑动 | `928-1040` | 进度条、滑动条、滑块、加载帧 |
+| 开关与状态 | `1048-1112` | Toggle、Checkbox、Radio、状态图标 |
+| 菜单与业务图标 | `1120-1456` | 菜单、Toast、扫码框、服务器/聊天/背包等常用图标 |
+| 滚动条 | `976-1488` | 竖向/横向滚动条轨道与滑块 |
+| 预留 | `1464-2040` | 后续界面专用图、活动图标、品质框、特效帧 |
+
+## 4. 切片清单
+
+| 名称 | X | Y(左上) | W | H | Unity Y(左下) | 类型 | Border L,R,T,B | 用途 |
+| --- | ---: | ---: | ---: | ---: | ---: | --- | --- | --- |
+| `ui_panel_main` | 8 | 8 | 512 | 384 | 1656 | 9-slice | `48,48,48,48` | 主窗口/全屏面板底 |
+| `ui_panel_popup` | 528 | 8 | 384 | 256 | 1784 | 9-slice | `40,40,40,40` | 弹窗底 |
+| `ui_panel_content` | 920 | 8 | 384 | 256 | 1784 | 9-slice | `32,32,32,32` | 内容区/卡片底 |
+| `ui_panel_header` | 1312 | 8 | 512 | 96 | 1944 | 9-slice | `32,32,24,24` | 标题栏 |
+| `ui_panel_footer` | 1312 | 112 | 512 | 96 | 1840 | 9-slice | `32,32,24,24` | 底部操作栏 |
+| `ui_panel_tooltip` | 528 | 272 | 320 | 160 | 1616 | 9-slice | `28,28,28,28` | 提示框 |
+| `ui_list_item_normal` | 856 | 272 | 384 | 96 | 1680 | 9-slice | `24,24,20,20` | 列表项普通态 |
+| `ui_list_item_selected` | 1248 | 272 | 384 | 96 | 1680 | 9-slice | `24,24,20,20` | 列表项选中态 |
+| `ui_list_item_disabled` | 1640 | 272 | 384 | 96 | 1680 | 9-slice | `24,24,20,20` | 列表项禁用态 |
+| `ui_overlay_dim` | 920 | 376 | 256 | 256 | 1416 | simple | `0,0,0,0` | 半透明遮罩，可拉伸 |
+| `ui_divider_h` | 1184 | 376 | 512 | 16 | 1656 | simple | `0,0,0,0` | 横向分割线 |
+| `ui_divider_v` | 1704 | 376 | 16 | 256 | 1416 | simple | `0,0,0,0` | 竖向分割线 |
+| `ui_badge_base` | 1728 | 376 | 128 | 64 | 1608 | 9-slice | `24,24,20,20` | 普通角标 |
+| `ui_badge_alert` | 1864 | 376 | 128 | 64 | 1608 | 9-slice | `24,24,20,20` | 提醒/红点角标 |
+| `btn_primary_normal` | 8 | 648 | 256 | 96 | 1304 | 9-slice | `36,36,28,28` | 主按钮普通态 |
+| `btn_primary_hover` | 272 | 648 | 256 | 96 | 1304 | 9-slice | `36,36,28,28` | 主按钮悬停/选中态 |
+| `btn_primary_pressed` | 536 | 648 | 256 | 96 | 1304 | 9-slice | `36,36,28,28` | 主按钮按下态 |
+| `btn_primary_disabled` | 800 | 648 | 256 | 96 | 1304 | 9-slice | `36,36,28,28` | 主按钮禁用态 |
+| `btn_secondary_normal` | 1064 | 648 | 256 | 96 | 1304 | 9-slice | `36,36,28,28` | 次按钮普通态 |
+| `btn_secondary_pressed` | 1328 | 648 | 256 | 96 | 1304 | 9-slice | `36,36,28,28` | 次按钮按下态 |
+| `btn_warning_normal` | 1592 | 648 | 224 | 96 | 1304 | 9-slice | `36,36,28,28` | 警告按钮普通态 |
+| `btn_warning_pressed` | 1816 | 648 | 224 | 96 | 1304 | 9-slice | `36,36,28,28` | 警告按钮按下态 |
+| `btn_small_normal` | 8 | 752 | 192 | 72 | 1224 | 9-slice | `28,28,22,22` | 小按钮普通态 |
+| `btn_small_hover` | 208 | 752 | 192 | 72 | 1224 | 9-slice | `28,28,22,22` | 小按钮悬停态 |
+| `btn_small_pressed` | 408 | 752 | 192 | 72 | 1224 | 9-slice | `28,28,22,22` | 小按钮按下态 |
+| `btn_small_disabled` | 608 | 752 | 192 | 72 | 1224 | 9-slice | `28,28,22,22` | 小按钮禁用态 |
+| `tab_active` | 808 | 752 | 224 | 80 | 1216 | 9-slice | `32,32,24,24` | 页签激活态 |
+| `tab_inactive` | 1040 | 752 | 224 | 80 | 1216 | 9-slice | `32,32,24,24` | 页签未激活态 |
+| `seg_left` | 1272 | 752 | 160 | 80 | 1216 | 9-slice | `32,12,24,24` | 分段控件左段 |
+| `seg_mid` | 1440 | 752 | 160 | 80 | 1216 | 9-slice | `12,12,24,24` | 分段控件中段 |
+| `seg_right` | 1608 | 752 | 160 | 80 | 1216 | 9-slice | `12,32,24,24` | 分段控件右段 |
+| `btn_close` | 1776 | 752 | 80 | 80 | 1216 | simple | `0,0,0,0` | 关闭按钮 |
+| `btn_back` | 1864 | 752 | 80 | 80 | 1216 | simple | `0,0,0,0` | 返回按钮 |
+| `btn_home` | 1952 | 752 | 80 | 80 | 1216 | simple | `0,0,0,0` | 主页按钮 |
+| `input_bg_normal` | 8 | 840 | 384 | 80 | 1128 | 9-slice | `32,32,24,24` | 输入框普通态 |
+| `input_bg_focus` | 400 | 840 | 384 | 80 | 1128 | 9-slice | `32,32,24,24` | 输入框聚焦态 |
+| `input_bg_error` | 792 | 840 | 384 | 80 | 1128 | 9-slice | `32,32,24,24` | 输入框错误态 |
+| `dropdown_bg` | 1184 | 840 | 384 | 80 | 1128 | 9-slice | `32,32,24,24` | 下拉框底 |
+| `dropdown_arrow` | 1576 | 840 | 64 | 64 | 1144 | simple | `0,0,0,0` | 下拉箭头 |
+| `input_caret` | 1648 | 840 | 8 | 64 | 1144 | simple | `0,0,0,0` | 输入光标 |
+| `ico_keyboard` | 1664 | 840 | 64 | 64 | 1144 | simple | `0,0,0,0` | 键盘 |
+| `ico_search` | 1736 | 840 | 64 | 64 | 1144 | simple | `0,0,0,0` | 搜索 |
+| `ico_clear` | 1808 | 840 | 64 | 64 | 1144 | simple | `0,0,0,0` | 清空 |
+| `ico_copy` | 1880 | 840 | 64 | 64 | 1144 | simple | `0,0,0,0` | 复制 |
+| `ico_paste` | 1952 | 840 | 64 | 64 | 1144 | simple | `0,0,0,0` | 粘贴 |
+| `progress_bg` | 8 | 928 | 512 | 40 | 1080 | 9-slice | `20,20,12,12` | 进度条底 |
+| `progress_fill_blue` | 528 | 928 | 512 | 40 | 1080 | 9-slice | `20,20,12,12` | 蓝色进度填充 |
+| `progress_fill_green` | 1048 | 928 | 512 | 40 | 1080 | 9-slice | `20,20,12,12` | 绿色进度填充 |
+| `progress_fill_warn` | 1568 | 928 | 472 | 40 | 1080 | 9-slice | `20,20,12,12` | 警告进度填充 |
+| `slider_track` | 8 | 976 | 512 | 32 | 1040 | 9-slice | `16,16,10,10` | 滑动条轨道 |
+| `slider_fill` | 528 | 976 | 512 | 32 | 1040 | 9-slice | `16,16,10,10` | 滑动条填充 |
+| `slider_handle` | 1048 | 976 | 64 | 64 | 1008 | simple | `0,0,0,0` | 滑动条手柄 |
+| `scrollbar_track_v` | 1120 | 976 | 32 | 512 | 560 | 9-slice | `10,10,20,20` | 竖向滚动条轨道 |
+| `scrollbar_thumb_v` | 1160 | 976 | 32 | 128 | 944 | 9-slice | `10,10,20,20` | 竖向滚动条滑块 |
+| `scrollbar_track_h` | 1200 | 976 | 512 | 32 | 1040 | 9-slice | `20,20,10,10` | 横向滚动条轨道 |
+| `scrollbar_thumb_h` | 1720 | 976 | 128 | 32 | 1040 | 9-slice | `20,20,10,10` | 横向滚动条滑块 |
+| `loading_ring_0` | 1856 | 976 | 64 | 64 | 1008 | simple | `0,0,0,0` | 加载圆环帧 0 |
+| `loading_ring_1` | 1928 | 976 | 64 | 64 | 1008 | simple | `0,0,0,0` | 加载圆环帧 1 |
+| `toggle_bg_off` | 8 | 1048 | 112 | 56 | 944 | 9-slice | `28,28,18,18` | 开关关闭底 |
+| `toggle_bg_on` | 128 | 1048 | 112 | 56 | 944 | 9-slice | `28,28,18,18` | 开关开启底 |
+| `toggle_knob` | 248 | 1048 | 48 | 48 | 952 | simple | `0,0,0,0` | 开关滑块 |
+| `checkbox_off` | 304 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 复选框未选 |
+| `checkbox_on` | 376 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 复选框已选 |
+| `radio_off` | 448 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 单选框未选 |
+| `radio_on` | 520 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 单选框已选 |
+| `ico_check` | 592 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 对勾 |
+| `ico_lock` | 664 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 锁定 |
+| `ico_unlock` | 736 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 解锁 |
+| `ico_warning` | 808 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 警告 |
+| `ico_info` | 880 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 信息 |
+| `ico_plus` | 952 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 加号 |
+| `ico_minus` | 1024 | 1048 | 64 | 64 | 936 | simple | `0,0,0,0` | 减号 |
+| `slot_empty` | 1200 | 1048 | 96 | 96 | 904 | 9-slice | `20,20,20,20` | 物品格空态 |
+| `slot_selected` | 1304 | 1048 | 96 | 96 | 904 | 9-slice | `20,20,20,20` | 物品格选中态 |
+| `slot_locked` | 1408 | 1048 | 96 | 96 | 904 | 9-slice | `20,20,20,20` | 物品格锁定态 |
+| `avatar_frame` | 1512 | 1048 | 128 | 128 | 872 | 9-slice | `28,28,28,28` | 头像框 |
+| `rank_medal_1` | 1648 | 1048 | 80 | 80 | 920 | simple | `0,0,0,0` | 第一名徽章 |
+| `rank_medal_2` | 1736 | 1048 | 80 | 80 | 920 | simple | `0,0,0,0` | 第二名徽章 |
+| `rank_medal_3` | 1824 | 1048 | 80 | 80 | 920 | simple | `0,0,0,0` | 第三名徽章 |
+| `ico_coin` | 1912 | 1048 | 80 | 80 | 920 | simple | `0,0,0,0` | 货币图标 |
+| `menu_bg` | 8 | 1120 | 384 | 320 | 608 | 9-slice | `32,32,32,32` | 下拉菜单/右键菜单底 |
+| `menu_item_normal` | 400 | 1120 | 384 | 64 | 864 | 9-slice | `20,20,16,16` | 菜单项普通态 |
+| `menu_item_hover` | 400 | 1192 | 384 | 64 | 792 | 9-slice | `20,20,16,16` | 菜单项悬停态 |
+| `menu_item_disabled` | 400 | 1264 | 384 | 64 | 720 | 9-slice | `20,20,16,16` | 菜单项禁用态 |
+| `toast_bg` | 792 | 1120 | 320 | 96 | 832 | 9-slice | `32,32,24,24` | Toast 提示底 |
+| `notice_bg` | 792 | 1224 | 320 | 96 | 728 | 9-slice | `32,32,24,24` | 系统通知底 |
+| `drag_handle` | 792 | 1328 | 160 | 32 | 688 | simple | `0,0,0,0` | 拖拽把手 |
+| `qr_scan_frame` | 960 | 1328 | 128 | 128 | 592 | simple | `0,0,0,0` | 扫码框角标 |
+| `ico_server` | 1200 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 服务器 |
+| `ico_user` | 1272 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 玩家 |
+| `ico_chat` | 1344 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 聊天 |
+| `ico_mail` | 1416 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 邮件 |
+| `ico_settings` | 1488 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 设置 |
+| `ico_sound_on` | 1560 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 声音开启 |
+| `ico_sound_off` | 1632 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 声音关闭 |
+| `ico_scan` | 1704 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 扫码 |
+| `ico_refresh` | 1776 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 刷新 |
+| `ico_download` | 1848 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 下载/更新 |
+| `ico_upload` | 1920 | 1184 | 64 | 64 | 800 | simple | `0,0,0,0` | 上传 |
+| `ico_bag` | 1200 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 背包 |
+| `ico_item` | 1272 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 道具 |
+| `ico_sword` | 1344 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 武器 |
+| `ico_shield` | 1416 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 防具 |
+| `ico_map` | 1488 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 地图 |
+| `ico_star` | 1560 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 星级 |
+| `ico_heart` | 1632 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 生命/收藏 |
+| `ico_diamond` | 1704 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 钻石 |
+| `ico_key` | 1776 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 钥匙 |
+| `ico_clock` | 1848 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 时间 |
+| `ico_calendar` | 1920 | 1256 | 64 | 64 | 728 | simple | `0,0,0,0` | 日期 |
+| `reserved_large_0` | 8 | 1464 | 512 | 256 | 328 | simple | `0,0,0,0` | 大型活动/界面专用预留 |
+| `reserved_large_1` | 528 | 1464 | 512 | 256 | 328 | simple | `0,0,0,0` | 大型活动/界面专用预留 |
+| `reserved_icon_grid` | 1200 | 1336 | 784 | 192 | 520 | simple | `0,0,0,0` | 未来 64x64 图标网格预留 |
+
+## 5. 控件映射建议
+
+| Unity 控件 | 建议切片 |
+| --- | --- |
+| `Button` | `btn_primary_*`、`btn_secondary_*`、`btn_small_*`、`btn_warning_*` |
+| `InputField` / `TMP_InputField` | `input_bg_normal`、`input_bg_focus`、`input_bg_error`、`input_caret` |
+| `Slider` | `slider_track`、`slider_fill`、`slider_handle` |
+| `Scrollbar` | `scrollbar_track_v`、`scrollbar_thumb_v`、`scrollbar_track_h`、`scrollbar_thumb_h` |
+| `ScrollRect` 列表项 | `ui_list_item_normal`、`ui_list_item_selected`、`ui_list_item_disabled` |
+| 弹窗/面板 | `ui_panel_main`、`ui_panel_popup`、`ui_panel_content`、`ui_panel_header`、`ui_overlay_dim` |
+| Toggle/Checkbox/Radio | `toggle_*`、`checkbox_*`、`radio_*` |
+| 加载/热更新 | `progress_*`、`loading_ring_*`、`ico_download` |
+| 二维码/扫码 | `ico_scan`、`qr_scan_frame` |
+
+## 6. Unity UI 使用规则
+
+1. 与文字相关的 UI 控件统一使用 TextMeshPro 版本，例如 `TextMeshProUGUI`、`TMP_InputField`、`TMP_Dropdown`。
+2. 不再新增 Unity Legacy `Text`、`InputField`、`Dropdown` 控件，已有旧控件后续维护时应逐步替换为 TextMeshPro 对应控件。
+3. 动态文本、按钮文字、输入框占位符、列表项文字、弹窗正文、Toast 提示、系统通知等均按 TextMeshPro 字体资源和材质配置。
+4. 生成的节点都用英文
+
+## 7. Unity 导入设置
+
+1. Texture Type 设为 `Sprite (2D and UI)`。
+2. Sprite Mode 设为 `Multiple`。
+3. Mesh Type 设为 `Full Rect`，避免九宫格边缘被裁切。
+4. Filter Mode 建议 `Bilinear`；像素风 UI 可改为 `Point`。
+5. Compression 建议 `None` 或 `High Quality`，避免 UI 边缘和文字图标出现压缩噪点。
+6. 勾选 `Alpha Is Transparency`，保持透明边缘正确。
+7. 移动端若对内存敏感，可在图集最终稳定后再评估 ASTC/ETC2 压缩。
+
+## 8. 命名约定
+
+- 面板：`ui_panel_*`
+- 按钮：`btn_*`
+- 图标：`ico_*`
+- 输入：`input_*`
+- 进度：`progress_*`
+- 滑动条：`slider_*`
+- 滚动条：`scrollbar_*`
+- 预留：`reserved_*`
+
+Sprite 名称应与表中名称保持一致，Lua 或 C# 侧需要动态加载时直接使用该名称。