# 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` + Sprite 有效非零 `Border` + `Full Rect`；按钮状态图同样设置。Common 导入规则：`UiSpriteNineSliceRules.cs`；修复菜单：`Tools/UI/Apply Standard Control Nine-Slice`。
- 按钮：SpriteSwap 优先
- `MonoBehaviour.typeName` 指向 HotUpdate 类型
- 安全区等通用基础组件可指向 AOT 类型；主界面顶部布局使用 `AOT.UI.UiSafeArea`，业务按钮避开摄像头与微信胶囊，背景保持全屏。
- 转换器遵循 `assets.sprites` 显式路径；`RawImage.material` 为序列化材质引用，禁止仅依赖 Shader.Find 保留业务预览 Shader。

## 资源加载

- **一律异步**（YooAsset）；禁止新写同步加载热更资源。
- Prefab/贴图路径建议带 `Assets/Bundles/...`。

## UI 风格

- 当前仅使用 Candy 糖果风；Studio / Mint 主题与停用的切换入口已删除。
- `BootSettings.UiTheme` / 远程 `version.json.uiTheme` 保留用于旧配置兼容，其他值回退 Candy。
- 业务按逻辑名异步打开：`UiManager.OpenAsync`。
- UI Prefab 与自动图集收集进 Art/UI，图片跟所属图集同包，字体作为 Prefab 依赖进入资源包。

## 与图集方案关系

- Prefab 继续直接引用单图 Sprite，JSON 路径与九宫格 Border 保持不变。
- 目录级自动 SpriteAtlas、YooAsset 同包及运行时异步绑定见 `Doc/UI_Atlas_Pipeline.md`。

## Agent 边界

遵守 `UNITY-GUIDE.md`：可直接改 JSON/MD/C#；不手改 `.prefab`/`.meta`；Prefab 由转换器或 Pipeline 生成。