Add hot-update boot pipeline, UI bundles/atlas assets, and design docs.

Ignore AIClient/Library and AIClient/HybridCLRData permanently; include HybridCLR/YooAsset project setup and UI tooling. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-21 16:02:58 +08:00
parent f3f66ab063
commit b7a0bbcb89
279 changed files with 27332 additions and 14 deletions
@@ -0,0 +1,236 @@
+# Unity UI 组件设计原则
+
+> 本文档依据视觉基准图 `Doc/Design/ui_design.jpg` 提炼，定义本项目休闲卡通风格 UI 的统一设计语言与各类 UGUI 控件的设计规范。
+> 配套规范见 `Doc/Rule/UnityUIProject.md`、`Doc/Rule/UIGenerationRules.md` 与 `Doc/UI_Normal_Set.md` / `Doc/UI_Pic_Set.md`。
+> 通用控件切图位于 `AIClient/Assets/Bundles/UI/Texture/Common`。
+> 本项目为**竖屏**微信小游戏，设计分辨率 **1080×1920**（配色与控件形态仍以基准图为准；布局按竖屏适配）。
+
+---
+
+## 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`），默认字体思源黑体（待接入 `Assets/Bundles/UI/Font/`）。
+- **字号层级**（1080×1920 竖屏参考，可按视觉微调）：界面标题 40–48；区块标题 32–36；按钮文字 28–34；正文/列表 24–28；说明/次要 20–24；大数值 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/Bundles/UI/Texture/Common` 通用切图；缺图时用 gpt-image 按本风格生成到该目录（见 `ResourceCreate.md`）。
+- 新界面按 **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. 分辨率与适配
+
+- 设计分辨率 **1080×1920**（竖屏；`CanvasScaler` = ScaleWithScreenSize，referenceResolution `[1080,1920]`，Match = 0.5）。
+- 布局以锚点为主：全屏元素用拉伸锚点；角标/悬浮按钮锚到对应屏幕角；主面板居中。
+- 关键信息放安全区内，避免刘海/圆角遮挡；考虑长宽比从 4:3 到 20:9 的适配。
+- 重要图标与文字用 `None`/`High Quality` 压缩，避免边缘与文字出现压缩噪点。
+
+---
+
+## 10. 设计检查清单（提交前自检）
+
+- [ ] 配色取自第 2 节调色板，语义色使用正确（绿=主/蓝=次/橙=强调/红=危险）。
+- [ ] 控件有圆角 + 描边 + 高光 + 柔和阴影，风格与 `ui_design.jpg` 一致。
+- [ ] 可交互控件具备 Normal/Hover/Pressed/Disabled（必要时 Selected）状态。
+- [ ] 文字用 TMP；浅色字在复杂/高饱和/深底上加了深蓝灰描边；深浅对比充足。
+- [ ] 可拉伸控件设置了正确的九宫格 Border，任意尺寸不变形。
+- [ ] 间距为 8 的倍数；点击热区足够大。
+- [ ] referenceResolution = [1080,1920]，锚点适配多分辨率。
+- [ ] 复用 Common 通用切图；新图按本风格用 gptimage2 生成到对应目录。
@@ -0,0 +1,25 @@
+# 游戏服协议（M2 探测结论）
+
+Base: `https://game.xworld.ren`（Caddy → Kestrel）
+
+## HTTP
+
+| 方法 | 路径 | Body | 成功 | 失败 |
+| --- | --- | --- | --- | --- |
+| POST | `/register` | `{"username","password"}` | `{token,pid}` | `invalid_input` 等 |
+| POST | `/login` | `{"username","password"}` | `{token,pid}` | `invalid_credentials` |
+
+## WebSocket
+
+```
+wss://game.xworld.ren/ws?pid={pid}&token={token}
+```
+
+- 无 token → HTTP 401（握手阶段拒绝）
+- 连通后服务端可不主动推消息；客户端可用 WebSocket 协议层 KeepAlive
+- 应用层可发 `{"op":"hello",...}`（当前服可无应答）
+
+## 客户端
+
+- `HotUpdate.Net.AuthApi` / `GameNet` / `WsClient`
+- 编辑器自动 `guest_{deviceId}` 账号（PlayerPrefs 持久化 deviceId）
@@ -6,6 +6,11 @@
 | --- | --- |
 | `Tools/output/ui_simple_atlas_gpt.png` | UI Simple Set 图集；gpt-image-2.5 + 参考 `Doc/ui_design.jpg`；约 1254×1254；对应 `Doc/UI_Simple_Set.md` |
 | `Tools/output/ui_normal_atlas_gpt.png` | UI Normal Set 图集；gpt-image-2-vip、2048×2048、透明底 + 参考图；对应 `Doc/UI_Normal_Set.md` |
+| `AIClient/Assets/Bundles/UI/Texture/Common/*.png` | Normal 图集切出的 **38** 张 Common 单图；脚本 `Tools/slice_ui_normal_atlas.py` |
+| `AIClient/Assets/Bundles/UI/Font/siyuan_CN_Bold.otf` | 思源黑体 CN Bold 源字体 |
+| `AIClient/Assets/Bundles/UI/Font/siyuan_CN_Bold SDF.asset` | TMP 动态 SDF 字体资源；JSON→Prefab 默认使用；菜单 `Tools/UI/Ensure SiYuan TMP Font Asset` |
 | `Tools/output/male_explorer_test.png` | 男性探险者角色试做；项目文生图脚本 |
 | `Tools/output/male_explorer_cursor.png` | 男性探险者对照；Cursor GenerateImage |
-| `Doc/ui_design.jpg` | UI 视觉基准图；糖果休闲风控件参考 |
+| `Doc/ui_design.jpg` | UI 视觉基准图；糖果休闲风控件参考（`Doc/Design/ui_design.jpg` 为同内容副本） |
+| `Doc/UI_AutoGen_Overview.md` | UI 自动生成方案总览（JSON→Prefab + 图集） |
+| `Doc/UIPrefabCreater/UI_ConfirmDialog.json` | 竖屏确认弹窗样例 JSON；对应 Prefab 路径 `Assets/Bundles/UI/Prefab/UI_ConfirmDialog.prefab` |
@@ -0,0 +1,73 @@
+# UI 生成提示词（AI JSON 契约）
+
+> 可直接作为系统提示词。完整说明见 `Doc/Rule/UIGenerationRules.md`。
+
+你是本项目的 Unity UI 原型生成器。**唯一产物是一份 JSON**，写入 `Doc/UIPrefabCreater/{界面名}.json`，由编辑器转为 UGUI Prefab。不要输出 HTML、C#、Markdown 说明。JSON 必须符合 `JsonUIPrefabBuilder` 当前能力。
+
+## 1. 强制上下文
+
+- `Doc/Rule/UnityUIProject.md`
+- `Doc/Design/UI_Design_Principles.md`
+- `Doc/UI_Normal_Set.md`（或 `UI_Pic_Set.md`）
+- `Doc/UIPrefabCreater/UI_ConfirmDialog.json`
+- `AIClient/Assets/Editor/UI/JsonUIPrefabBuilder.cs`
+
+## 2. 唯一产物字段
+
+- `schemaVersion`: `1`
+- `prefabName` = 根节点 `name`
+- `prefabPath`: `Assets/Bundles/UI/Prefab/{prefabName}.prefab`
+- `description`: 用途、层级（HUD/Normal/Dialog/Tips）、绑定方式
+- `canvas.canvasScaler.referenceResolution`: **必须 `[1080, 1920]`**，`matchWidthOrHeight` 建议 `0.5`
+- `assets.sprites`: 短名 → `Assets/Bundles/UI/Texture/Common/{name}.png`（或业务子目录）
+- `nodes` / `bindings` / `events`
+
+## 3. 骨架
+
+```json
+{
+  "schemaVersion": 1,
+  "prefabName": "UI_Example",
+  "prefabPath": "Assets/Bundles/UI/Prefab/UI_Example.prefab",
+  "description": "Normal 层功能界面。竖屏。",
+  "canvas": {
+    "canvasScaler": {
+      "referenceResolution": [1080, 1920],
+      "matchWidthOrHeight": 0.5
+    }
+  },
+  "assets": { "sprites": {} },
+  "nodes": [],
+  "bindings": [],
+  "events": []
+}
+```
+
+## 4. 节点
+
+每节点：`name`、`parent`（根为 `null`）、`active`、`rect`、`components`。父节点必须先于子节点。竖屏布局：主面板居中；关键操作区偏下；安全区 ≥24。
+
+## 5. 支持组件
+
+Canvas、CanvasScaler、GraphicRaycaster、CanvasGroup、Image、TextMeshProUGUI、Button、Shadow、Outline、ScrollRect、RectMask2D、Mask、TMP_InputField、VerticalLayoutGroup、ContentSizeFitter、LayoutElement、MonoBehaviour。
+
+不要依赖未实现的 Toggle/Slider/Scrollbar/TMP_Dropdown/ScrollView 完成核心功能。
+
+## 6. 视觉
+
+- 糖果风：大圆角、描边、顶部高光；配色见 Design Principles。
+- 优先复用 Common 切图名（`ui_panel_*`、`btn_primary_*` 等）。
+- 可拉伸控件 `"imageType": "Sliced"`；图标 Simple。
+- 文字仅 `TextMeshProUGUI`；浅色字加 Outline/Shadow（`#102033` / `#0B1724`）。
+- 按钮优先 SpriteSwap；缺 hover 图可用 ColorTint。
+- 缺图时在 `description` 标明，按 `ResourceCreate.md` 生成并登记 `Doc/ResDesc_Picture.md`。
+
+## 7. 事件
+
+- `bindings`: 业务需访问的节点名。
+- `events`: `{ "name": "Example.Ok", "node": "Btn_Ok" }`；`onClick` 仅为标记。
+- 可选 `MonoBehaviour.typeName`（HotUpdate 程序集类型全名）。
+
+## 8. 输出前自检
+
+只输出 JSON；根唯一；`[1080,1920]`；Sprite 已登记；Sliced/TMP/bindings 合法。
@@ -0,0 +1,83 @@
+# UI 生成规则（AI JSON → Prefab）
+
+> AIGame 竖屏微信小游戏版。精简系统提示词见 `Doc/Rule/UIGenerationPrompt.md`。总览见 `Doc/UI_AutoGen_Overview.md`。
+
+## Part A - 流水线
+
+```text
+需求说明
+  -> AI 读规则/设计/切图清单/样例 JSON
+  -> 生成 Doc/UIPrefabCreater/{UIName}.json
+  -> Unity 获焦或菜单 Tools/UI/...
+  -> JsonUIPrefabBuilder 生成 Assets/Bundles/UI/Prefab/{UIName}.prefab
+  -> HotUpdate C# 按节点名 / bindings / events 接管
+```
+
+不使用 HTML 中间层。转换器：
+
+- `AIClient/Assets/Editor/UI/JsonUIPrefabBuilder.cs`
+- `AIClient/Assets/Editor/UI/JsonUIAutoConvert.cs`
+
+### 目录
+
+| 类型 | 路径 |
+| --- | --- |
+| JSON | `Doc/UIPrefabCreater/{UIName}.json` |
+| Prefab | `Assets/Bundles/UI/Prefab/{UIName}.prefab` |
+| 通用贴图 | `Assets/Bundles/UI/Texture/Common/` |
+| 业务贴图 | `Assets/Bundles/UI/Texture/<Module>/` |
+
+## Part B - AI 契约
+
+### 必读
+
+- `Doc/Rule/UnityUIProject.md`
+- `Doc/Design/UI_Design_Principles.md`
+- `Doc/UI_Normal_Set.md` 或 `Doc/UI_Pic_Set.md`
+- `Doc/UIPrefabCreater/UI_ConfirmDialog.json`（样例）
+- 转换器当前支持的组件（以代码为准）
+
+### 顶层字段
+
+`schemaVersion`（`1`）、`prefabName`、`prefabPath`、`description`、`canvas`、`assets`、`nodes`、`bindings`、`events`。
+
+`canvas.canvasScaler.referenceResolution` **必须为 `[1080, 1920]`**。
+
+### 命名
+
+英文节点：`UI_` / `Panel` / `Img_` / `Txt_` / `Btn_` / `Scroll_` / `Group_`。
+
+### 可生成组件
+
+Canvas、CanvasScaler、GraphicRaycaster、CanvasGroup、Image、TextMeshProUGUI、Button、Shadow、Outline、ScrollRect、RectMask2D、Mask、TMP_InputField、VerticalLayoutGroup、ContentSizeFitter、LayoutElement、MonoBehaviour。
+
+未完整实现（跳过/告警）：Toggle、TMP_Dropdown、Slider、Scrollbar、ScrollView（请用 ScrollRect）。
+
+### 按钮 / 列表模板
+
+- 按钮：`Image`（Sliced）+ `Button`（SpriteSwap：normal/pressed/disabled；无 hover 切图可用 ColorTint）。
+- 列表：`ScrollRect` → Viewport（RectMask2D）→ Content（VerticalLayoutGroup + ContentSizeFitter）→ Item_Template。
+
+## Part C - 接管与排错
+
+1. 确认自动转换开启，或执行 `Convert Changed JSON Prefabs Now`。
+2. 看 Console `[UIGen]` 日志。
+3. 打开 Prefab 核对层级/Sprite/文字。
+4. HotUpdate 挂控制器：`transform.Find` / 递归按名查找；`button.onClick.AddListener`。
+5. 资源加载走 YooAsset **异步**（见 `ProjectDesign.md` / `UnityUIProject.md`）。
+
+| 现象 | 处理 |
+| --- | --- |
+| JSON 不转换 | 获焦/手动菜单；确认 JSON 比 Prefab 新 |
+| referenceResolution 错误 | 改为 `[1080,1920]` |
+| 找不到 Sprite | 短名与 Common 切图一致；Texture Type=Sprite |
+| 文字不可读 | Outline/Shadow，色 `#102033` / `#0B1724` |
+
+### 提交前自检
+
+- JSON 在 `Doc/UIPrefabCreater`；唯一根节点；`prefabName` 一致。
+- 父先于子；Sprite 已登记；九宫格 `Sliced`；TMP；bindings/events 节点存在。
+
+## Part D - 后续
+
+优先补齐转换器：Toggle → Slider → Scrollbar → TMP_Dropdown。图集自动化见 `Doc/UI_Atlas_Pipeline.md`。
@@ -0,0 +1,58 @@
+# Unity UI 工程约定（AIGame）
+
+> 从 AIC# `UnityProject.md` 抽取 UI 相关条款，并按本仓库竖屏 / Bundles / YooAsset / HybridCLR 改写。
+
+## 环境
+
+- Unity：`2022.3.62f3`（`AIClient/ProjectSettings/ProjectVersion.txt`）
+- 客户端：`AIClient/`
+- 屏幕：**竖屏**；UI 设计分辨率 **`1080×1920`**
+- 资源包：YooAsset；业务代码：HybridCLR HotUpdate
+
+## 目录
+
+| 用途 | 路径 |
+| --- | --- |
+| 通用 UI 贴图 | `Assets/Bundles/UI/Texture/Common` |
+| 业务 UI 贴图 | `Assets/Bundles/UI/Texture/<Module>` |
+| UI Prefab | `Assets/Bundles/UI/Prefab` |
+| UI 字体 | `Assets/Bundles/UI/Font`（源文件 `siyuan_CN_Bold.otf`，TMP：`siyuan_CN_Bold SDF.asset`） |
+| JSON 描述 | 仓库根 `Doc/UIPrefabCreater` |
+| 热更 UI 脚本 | `Assets/HotUpdate/Scripts/UI` |
+| AOT 启动条 | `Assets/AOT/Scripts/UI`（仅补丁/启动，不放业务面板） |
+
+## UI 挂载层级
+
+运行时挂到 `UIRoot` 子节点（待实现时保持约定）：
+
+- **HUD** → **Normal** → **Dialog** → **Tips**（越上越前）
+
+## UI 制作流程
+
+1. 设计竖屏界面；优先复用 Common 切图（`Doc/UI_Normal_Set.md` / `UI_Pic_Set.md`）。
+2. 输出 `Doc/UIPrefabCreater/{UIName}.json`（契约见 `UIGenerationPrompt.md`）。
+3. Unity 获焦自动生成 Prefab，或菜单 `Tools/UI/...`。
+4. HotUpdate C# 接管：按名找节点，异步加载资源。
+5. 新贴图走 `ResourceCreate.md`，登记 `Doc/ResDesc_Picture.md`。
+
+## JSON → Prefab 要点
+
+- `referenceResolution`: `[1080, 1920]`
+- 文字：仅 TextMeshPro，默认字体 `Assets/Bundles/UI/Font/siyuan_CN_Bold SDF.asset`（由 `siyuan_CN_Bold.otf` 生成，动态图集）；浅色字描边/阴影非纯黑。
+- 九宫格：`imageType: Sliced`
+- 按钮：SpriteSwap 优先
+- `MonoBehaviour.typeName` 指向 HotUpdate 类型
+
+## 资源加载
+
+- **一律异步**（YooAsset）；禁止新写同步加载热更资源。
+- Prefab/贴图路径建议带 `Assets/Bundles/...`。
+
+## 与图集方案关系
+
+- 现阶段允许 Common 下单图 Sprite 直接被 Prefab 引用。
+- 目录级自动 SpriteAtlas / 打包绑定见 `Doc/UI_Atlas_Pipeline.md`（后续里程碑）。
+
+## Agent 边界
+
+遵守 `UNITY-GUIDE.md`：可直接改 JSON/MD/C#；不手改 `.prefab`/`.meta`；Prefab 由转换器或 Pipeline 生成。
@@ -0,0 +1,3 @@
+音效 → Stable Audio 3.0 Medium（6.5GB，380 秒长音频、支持 inpainting/续写/编辑），或 Small-SFX（2GB，快到飞起）+ GGUF 量化版批量刷变体
+BGM / 主题曲 → ACE-Step 1.5（人声+器乐通吃，Apache 2.0 可商用，还能 LoRA 锁风格）；想要 8-bit 复古/芯片音色就换 MusicGen-large
+批量刷音效变体 → AudioLDM-S（4GB，快且风格稳定）或 Stable Audio 3.0 Small-SFX GGUF
@@ -0,0 +1,273 @@
+{
+  "schemaVersion": 1,
+  "prefabName": "UI_ConfirmDialog",
+  "prefabPath": "Assets/Bundles/UI/Prefab/UI_ConfirmDialog.prefab",
+  "description": "Dialog 层通用确认弹窗（遮罩 + 弹窗底 + 标题/正文 + 取消/确定）。竖屏 1080x1920。运行时按 bindings/events 绑定 Txt_Title/Txt_Message/Btn_Cancel/Btn_Ok。",
+  "canvas": {
+    "canvasScaler": {
+      "referenceResolution": [1080, 1920],
+      "matchWidthOrHeight": 0.5
+    }
+  },
+  "assets": {
+    "sprites": {
+      "ui_overlay_dim": "Assets/Bundles/UI/Texture/Common/ui_overlay_dim.png",
+      "ui_panel_popup": "Assets/Bundles/UI/Texture/Common/ui_panel_popup.png",
+      "btn_primary_normal": "Assets/Bundles/UI/Texture/Common/btn_primary_normal.png",
+      "btn_primary_pressed": "Assets/Bundles/UI/Texture/Common/btn_primary_pressed.png",
+      "btn_primary_disabled": "Assets/Bundles/UI/Texture/Common/btn_primary_disabled.png",
+      "btn_secondary_normal": "Assets/Bundles/UI/Texture/Common/btn_secondary_normal.png",
+      "btn_secondary_pressed": "Assets/Bundles/UI/Texture/Common/btn_secondary_pressed.png",
+      "btn_close": "Assets/Bundles/UI/Texture/Common/btn_close.png"
+    }
+  },
+  "nodes": [
+    {
+      "name": "UI_ConfirmDialog",
+      "parent": null,
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0],
+        "anchorMax": [1, 1],
+        "offsetMin": [0, 0],
+        "offsetMax": [0, 0]
+      },
+      "components": [
+        { "type": "Canvas", "sortingOrder": 2000 },
+        {
+          "type": "CanvasScaler",
+          "referenceResolution": [1080, 1920],
+          "matchWidthOrHeight": 0.5
+        },
+        { "type": "GraphicRaycaster" }
+      ]
+    },
+    {
+      "name": "Img_Mask",
+      "parent": "UI_ConfirmDialog",
+      "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": "#FFFFFFCC"
+        }
+      ]
+    },
+    {
+      "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, 40],
+        "sizeDelta": [860, 520]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "ui_panel_popup",
+          "imageType": "Sliced",
+          "raycastTarget": true,
+          "color": "#FFFFFFFF"
+        }
+      ]
+    },
+    {
+      "name": "Btn_Close",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [1, 1],
+        "anchorMax": [1, 1],
+        "pivot": [1, 1],
+        "anchoredPosition": [-24, -24],
+        "sizeDelta": [72, 72]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "btn_close",
+          "imageType": "Simple",
+          "raycastTarget": true,
+          "color": "#FFFFFFFF"
+        },
+        {
+          "type": "Button",
+          "transition": "ColorTint",
+          "onClick": "Confirm.Close"
+        }
+      ]
+    },
+    {
+      "name": "Txt_Title",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 1],
+        "anchorMax": [1, 1],
+        "pivot": [0.5, 1],
+        "anchoredPosition": [0, -48],
+        "sizeDelta": [-120, 64]
+      },
+      "components": [
+        {
+          "type": "TextMeshProUGUI",
+          "text": "确认",
+          "fontSize": 48,
+          "fontStyle": "Bold",
+          "alignment": "Center",
+          "color": "#5A4632FF",
+          "raycastTarget": false
+        }
+      ]
+    },
+    {
+      "name": "Txt_Message",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0.5],
+        "anchorMax": [1, 0.5],
+        "pivot": [0.5, 0.5],
+        "anchoredPosition": [0, 24],
+        "sizeDelta": [-96, 160]
+      },
+      "components": [
+        {
+          "type": "TextMeshProUGUI",
+          "text": "确定要执行该操作吗？",
+          "fontSize": 32,
+          "alignment": "Center",
+          "color": "#33405EFF",
+          "raycastTarget": false
+        }
+      ]
+    },
+    {
+      "name": "Btn_Cancel",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0.5, 0],
+        "anchorMax": [0.5, 0],
+        "pivot": [1, 0],
+        "anchoredPosition": [-24, 40],
+        "sizeDelta": [280, 88]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "btn_secondary_normal",
+          "imageType": "Sliced",
+          "raycastTarget": true,
+          "color": "#FFFFFFFF"
+        },
+        {
+          "type": "Button",
+          "transition": "SpriteSwap",
+          "spritePressed": "btn_secondary_pressed",
+          "onClick": "Confirm.Cancel"
+        }
+      ]
+    },
+    {
+      "name": "Txt_Cancel",
+      "parent": "Btn_Cancel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0, 0],
+        "anchorMax": [1, 1],
+        "offsetMin": [0, 0],
+        "offsetMax": [0, 0]
+      },
+      "components": [
+        {
+          "type": "TextMeshProUGUI",
+          "text": "取消",
+          "fontSize": 34,
+          "fontStyle": "Bold",
+          "alignment": "Center",
+          "color": "#F6F8FFFF",
+          "raycastTarget": false
+        },
+        {
+          "type": "Outline",
+          "effectColor": "#102033AA",
+          "effectDistance": [1, -1]
+        }
+      ]
+    },
+    {
+      "name": "Btn_Ok",
+      "parent": "Panel",
+      "active": true,
+      "rect": {
+        "anchorMin": [0.5, 0],
+        "anchorMax": [0.5, 0],
+        "pivot": [0, 0],
+        "anchoredPosition": [24, 40],
+        "sizeDelta": [280, 88]
+      },
+      "components": [
+        {
+          "type": "Image",
+          "sprite": "btn_primary_normal",
+          "imageType": "Sliced",
+          "raycastTarget": true,
+          "color": "#FFFFFFFF"
+        },
+        {
+          "type": "Button",
+          "transition": "SpriteSwap",
+          "spritePressed": "btn_primary_pressed",
+          "spriteDisabled": "btn_primary_disabled",
+          "onClick": "Confirm.Ok"
+        }
+      ]
+    },
+    {
+      "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": 34,
+          "fontStyle": "Bold",
+          "alignment": "Center",
+          "color": "#F6F8FFFF",
+          "raycastTarget": false
+        },
+        {
+          "type": "Outline",
+          "effectColor": "#102033AA",
+          "effectDistance": [1, -1]
+        }
+      ]
+    }
+  ],
+  "bindings": ["Txt_Title", "Txt_Message", "Btn_Cancel", "Btn_Ok", "Btn_Close"],
+  "events": [
+    { "name": "Confirm.Ok", "node": "Btn_Ok" },
+    { "name": "Confirm.Cancel", "node": "Btn_Cancel" },
+    { "name": "Confirm.Close", "node": "Btn_Close" }
+  ]
+}
@@ -0,0 +1,46 @@
+# UI 图集自动化方案（AIGame 精简版）
+
+> 参考 AIC# `Unity_UI自动图集制作方案.md`。本仓库首期以 **目录约定 + 单图 Sprite + YooAsset** 为主；完整 SpriteAtlas 生成器作为后续里程碑。
+
+## 1. 目标
+
+- 美术/AI 把切图放入约定目录。
+- 导入为 `Sprite (2D and UI)`，关闭 mipmap。
+- Prefab / 运行时按 **Sprite 短名** 引用（与 JSON `assets.sprites` 一致）。
+- 后续：按子目录自动生成 `.spriteatlas`，构建时原图与图集同包。
+
+## 2. 目录
+
+```text
+AIClient/Assets/Bundles/UI/Texture/
+  Common/          # 通用控件（对应 UI_*_Set）
+  <Module>/        # 业务专用
+AIClient/Assets/Bundles/UI/Atlas/   # （后续）自动生成的 .spriteatlas
+```
+
+中间产物仍可先落在 `Tools/output/`，再导入 Bundles。
+
+## 3. 切图来源
+
+1. 选图集级别：`UI_Simple_Set` / `UI_Normal_Set` / `UI_Pic_Set`。
+2. `Tools/gpt_image_generate.py` 生成（>1K 用 `gpt-image-2-vip`，见 `ResourceCreate.md`）。
+3. 风格：`Doc/Design/UI_Design_Principles.md` + `ui_design.jpg`。
+4. 切片坐标以对应 `Doc/UI_*_Set.md` 为准；登记 `Doc/ResDesc_Picture.md`。
+
+## 4. 导入建议
+
+- Texture Type：`Sprite (2D and UI)`
+- Sprite Mode：单图 `Single`；整图集再切为 `Multiple`
+- Mesh Type：`Full Rect`（九宫格）
+- Alpha Is Transparency：开
+- 原图尽量不压缩；压缩留给图集/平台 override
+
+## 5. 后续里程碑（对齐 AIC#）
+
+1. `SpriteAtlasGenerator`：扫描 `Texture/UI` 子目录 → `Atlas/*.spriteatlas`
+2. `AtlasEnum` / 名字索引生成
+3. YooAsset 收集规则：图集与原图同组
+4. 运行时 `SetSprite(atlas, name)` API（HotUpdate）
+5. UI Prefab 依赖图集 JSON 审计
+
+在里程碑完成前，JSON→Prefab 流水线使用 **Common 单图路径** 即可闭环。
@@ -0,0 +1,65 @@
+# AIGame UI 自动生成方案总览
+
+> 参考 `AIC#Project/Client/Assets/Doc` 的 JSON→Prefab 与图集约定，按本仓库（竖屏微信小游戏、YooAsset、HybridCLR）落地。
+
+## 1. 两套互补流水线
+
+| 流水线 | 产物 | 文档 |
+| --- | --- | --- |
+| **A. JSON → Prefab** | 业务 UI Prefab | `Doc/Rule/UIGenerationRules.md`、`UIGenerationPrompt.md` |
+| **B. UI 图集 / 切图** | Common 控件贴图 +（后续）SpriteAtlas | `Doc/UI_*_Set.md`、`Doc/UI_Atlas_Pipeline.md` |
+
+风格与控件视觉：`Doc/Design/UI_Design_Principles.md` + `Doc/Design/ui_design.jpg`。
+
+## 2. 端到端流程（推荐）
+
+```text
+需求说明
+  -> Agent 读 UIGenerationPrompt + DesignPrinciples + UI_Normal_Set/UI_Pic_Set
+  -> 缺切图时：ResourceCreate.md 文生图（>1K 用 gpt-image-2-vip）→ Tools/output
+  -> 切图导入 Assets/Bundles/UI/Texture/Common（或业务子目录）
+  -> 写 Doc/UIPrefabCreater/{UIName}.json
+  -> Unity 获焦自动转换 / Tools/UI 菜单
+  -> 生成 Assets/Bundles/UI/Prefab/{UIName}.prefab
+  -> HotUpdate C# 按 bindings/events 接管
+  -> 登记 Doc/ResDesc_Picture.md（贴图）等
+```
+
+## 3. 本项目路径（与 AIC# 差异）
+
+| 用途 | AIGame 路径 |
+| --- | --- |
+| Unity 工程 | `AIClient/` |
+| UI JSON | `Doc/UIPrefabCreater/`（仓库根，不在 Assets 内） |
+| 通用贴图 | `AIClient/Assets/Bundles/UI/Texture/Common/` |
+| 业务贴图 | `AIClient/Assets/Bundles/UI/Texture/<Module>/` |
+| Prefab | `AIClient/Assets/Bundles/UI/Prefab/` |
+| 转换器 | `AIClient/Assets/Editor/UI/JsonUIPrefabBuilder.cs` |
+| 自动转换 | `AIClient/Assets/Editor/UI/JsonUIAutoConvert.cs` |
+| 热更 UI 代码 | `AIClient/Assets/HotUpdate/Scripts/UI/`（待扩展） |
+| 设计分辨率 | **竖屏 `[1080, 1920]`**（非参考项目的 2048×1024） |
+
+## 4. Unity 菜单
+
+- `Tools/UI/Generate Prefab From JSON...`
+- `Tools/UI/Generate All Prefabs From JSON`
+- `Tools/UI/Convert Changed JSON Prefabs Now`
+- `Tools/UI/Auto Convert JSON On Focus`（默认开启）
+
+Prefab / 导入设置须遵守 `UNITY-GUIDE.md`：Agent 不手改 `.prefab`，用本转换器或 Pipeline。
+
+## 5. 图集分级
+
+| 文档 | 用途 |
+| --- | --- |
+| `Doc/UI_Simple_Set.md` | 24 切片最小集 |
+| `Doc/UI_Normal_Set.md` | 38 切片常规集（推荐起步） |
+| `Doc/UI_Pic_Set.md` | ~48 切片完整常用集 |
+
+生成脚本与模型规则见 `ResourceCreate.md`。
+
+## 6. 首期不做 / 后续
+
+- 首期：JSON→Prefab + Common 切图目录约定；Sprite 可先单图导入。
+- 后续：按目录自动打 `.spriteatlas`、AtlasEnum、YooAsset 原图绑定（见 `Doc/UI_Atlas_Pipeline.md`）。
+- 转换器未实现：`Toggle` / `Slider` / `Scrollbar` / `TMP_Dropdown`（可用 Image+Button 骨架）。