AIGame/Doc/UI_AutoGen_Overview.md

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 图集 / 切图	各目录切图 → 自动 SpriteAtlas → YooAsset 同包	Doc/UI_*_Set.md、Doc/UI_Atlas_Pipeline.md

风格与控件视觉：Doc/Design/UI_Design_Principles.md + Doc/Design/ui_design.jpg。

当前仅使用 Candy 糖果风。Studio / Mint 已按用户要求删除；保留旧 uiTheme 字段的读取兼容，其他值回退 Candy。当前主界面继续走 JSON→Prefab，详见 Doc/Design/UI/UI_Themes.md。

2. 端到端流程（推荐）

需求说明
  -> 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（默认开启）
• Tools/UI/Generate Sprite Atlases（手动校验；图片变更及 Art 构建前也会自动更新）

Prefab / 导入设置须遵守 UNITY-GUIDE.md：Agent 不手改 .prefab，用本转换器或 Pipeline。

标准控件底图必须同时满足 Sprite 非零 Border、Full Rect 和 JSON imageType: Sliced。Common 的 26 张标准控件由 UiSpriteNineSliceRules.cs 自动设置导入边界（按 Normal Set 设计尺寸换算到实际切图，含 2px 透明留边）；已有资源可用 Tools/UI/Apply Standard Control Nine-Slice 修复。转换器会拒绝标准控件的错误 Image 类型、缺失 Sprite 或无效 Border，省略类型时默认 Sliced。图标和插画仍按整图使用。新增标准控件时同步扩展切图清单及导入规则。

5. 图集分级

文档	用途
Doc/UI_Simple_Set.md	24 切片最小集
Doc/UI_Normal_Set.md	38 切片常规集（推荐起步）
Doc/UI_Pic_Set.md	~48 切片完整常用集

生成脚本与模型规则见 ResourceCreate.md。

6. 图集接入与剩余能力

• JSON→Prefab 继续引用原图 Sprite；按原图所在目录自动生成 Assets/Bundles/UI/Atlas/UI_*Atlas.spriteatlas，原图与图集同包，通过 atlasRequested 异步绑定（见 Doc/UI_Atlas_Pipeline.md）。
• 动态换图使用 UiManager.Instance.Atlases.SetSpriteAsync(image, "Common", "btn_primary_normal")；目录名作为索引，无需维护参考工程的业务 AtlasEnum。
• 转换器未实现：Toggle / Slider / Scrollbar / TMP_Dropdown（可用 Image+Button 骨架）。

7. 移动端安全区与角色预览

• UI_MainHUD.json 在 Layout_Top、Panel_Top、Layout_Bottom 和 Panel_Reconnect 上声明 AOT.UI.UiSafeArea。组件结合 Unity Screen.safeArea 与微信 getWindowInfo.safeArea、getMenuButtonBoundingClientRect，下移顶部控件到胶囊底部加 8 逻辑像素处，并避开底部手势区；背景仍为全屏铺满。
• UiSafeArea.jslib 使用微信逻辑像素归一化，与 Unity 物理像素/DPR 解耦；旧客户端回退 getSystemInfoSync 和胶囊行预留。AOT 组件独立保留在 Assets/AOT/link.xml，不会被 HybridCLR Gen All 覆盖。
• JSON→Prefab 解析优先使用 assets.sprites 中的明确路径，声明的 Sprite 缺失即生成失败；支持 Bg/ 等独立目录。当前营地背景为 Assets/Bundles/UI/Bg/home_camp.png，不属于图集输入目录。
• RawImage 支持 material、color、raycastTarget。ExplorerStage 明确引用 Assets/Bundles/UI/Material/HomeExplorerCutout.mat，材质和 Shader 随 Prefab 依赖进入 Art；运行时不再通过 Shader.Find 查找抠底着色器。材质不可用时隐藏角色预览，避免显示相机底色。
• 启动 GameplayBootstrap 只初始化 UI，不自动加载 测试场景/CaoCao 预览世界；角色相关资源和按玩法加载的战斗场景保留。
• 验证入口：Tools/verify_ui_safe_area.js；AIClient/AgentScripts/VerifyHomeMobileUi.cs 分步准备/启动/截图/恢复，避免长时间等待屏幕背缓冲。回执和普通屏、刘海屏、安卓长屏截图在 Tools/output/home_mobile/。