Lesson 3 / 6

2D UI 对象模型

用 HappyMahjong 真实链路讲清 Scene、UI Root、GameObject、Component、Prefab。只讲 2D UI，不进入 3D 世界。

建议时长 12–13 min适合产品 + 后台练习：画对象树

HappyMahjong 的 2D UI 现实

不要把 UIEventListener 误判成 NGUI： 当前新功能不按 NGUI 开发。NGUI 相关类/目录主要是兼容残留；UIEventListener 保留是因为点击绑定方便，Empty Click / EmptyClick 用来接收空白或遮罩点击。

UI 定位三栏：新手先看这三个地方

Hierarchy

AppMainScene LoadDll Canvas Camera

Scene / Game

启动画面 / 登录 UI / 弹窗

Inspector

Component Script Serialized Fields Object References

Hierarchy 是对象树，Scene/Game 是画面，Inspector 是组件和序列化引用。产品看入口，后台追脚本。

运行时对象从哪里来

AppMainScene含 LoadDll / Canvas / Camera
LoadDllLoadScenePrefab()
UIRootUI 根
AppMainRootAppRoot : ContextView
AppContext绑定模块

页面/弹窗不一定写死在当前 Scene 里，可能由资源加载和 Context 绑定出来。

这张图只用于定位，不要求新手理解热更和资源加载细节。Product 只需要知道“页面/弹窗不一定在当前 Scene 里”；Backend 只需要能追到“哪个 View / Mediator / Command 处理点击”。

四个必须会说的词

Scene

一个运行场景。对 2D 产品来说，经常近似理解为“启动环境 / 页面集合 / UI 流程入口”。文件通常是 `.unity`。

GameObject

对象容器。它本身功能很少，功能来自挂载的 Component。

Component

挂在 GameObject 上的功能模块。HappyMahjong 2D UI 常见有 UGUI 的 Canvas / Image / Button、项目保留的 UIEventListener、Empty Click 接收对象，以及自定义 MonoBehaviour。

Prefab

可复用对象模板。修改 Prefab 可能影响所有实例；让 agent 大规模手写 Prefab YAML 是高风险行为。

高频 2D UI 20%

大多数 2D UI 小需求不是新建系统，而是找对组件、沿用绑定、避免遮挡和布局问题。

组件 / 配置解决什么问题常见坑
CanvasUI 根和渲染层级。不要为小弹窗随手新建孤立 Canvas。
RectTransformUI 位置、尺寸、Anchor、Pivot。文案或按钮位置异常时先看 Anchor / Pivot。
Button / Toggle点击和勾选输入。绑定可能在 Inspector、代码或 UIEventListener 中。
Text / TMP_Text / Image文案、图标、状态显示。文案挤爆时先查 Layout，不要直接改 Prefab 层级。
CanvasGroup / Raycast Target点击是否能穿透或被阻挡。按钮点不到时优先查遮挡、blocksRaycasts、Raycast Target。
LayoutGroup / ContentSizeFitter列表、动态文案、自动布局。手动改位置可能和自动布局打架。

2D UI 修改的安全层次

层次例子新手 + agent 风险
普通 C# 逻辑输入校验、DTO 转 Model、Command 内部状态规则低；最适合 agent 和 Edit Mode Test。
View / Mediator 薄层按钮事件转发、读取输入框、渲染文本、dispatch 事件中；要检查生命周期、Inspector 引用和 Context 绑定。
Prefab / Scene 配置新增按钮、拖拽引用、调整层级高；优先人工编辑器操作或让 agent 输出步骤。
ProjectSettings / Packages升级 UI 包、改构建设置很高；一小时课内禁止。

HappyMahjong 推荐读法：StrangeIoC 链路

从按钮到业务的最短路径

{Module}View按钮 / UI 引用
{Module}Mediatordispatch 事件
{Module}Command执行业务
Service / ManagerTSDK / 网络
Model / UI状态 / 显示
{Module}Context   // 绑定 Model、Service、View → Mediator、事件 → Command
{Module}View      // UI View：接按钮 / UIEventListener / Empty Click，显示状态，dispatch View 事件
{Module}Mediator  // View 事件 → StrangeIoC 事件
{Module}Command   // 业务流程
{Module}Service   // 服务层
{Module}Model     // 状态

Why — 先从 *Context.cs 看绑定，再追 View → Mediator → Command → Service / Model，是 HappyMahjong 里最靠谱的读法。不管哪个模块，链路结构一致。

Presenter： 现场用选定功能所在模块展示真实的 Context / View / Mediator / Command / Service 文件。

课堂练习：画调用链

  1. 用现场选定的功能作为输入，让产品同学说验收标准。
  2. 让后台同学画路径：Button.onClick / UIEventListener / Empty Click → View → Mediator → Command → Service / Manager → TSDK / Network → Response → Model → UI。
  3. 让全员指出哪里可能不在代码里：按钮绑定、Prefab 引用、Inspector 字段。

Retrieval check

哪个改动最适合作为 agent 的第一批 Unity 任务？

Primary source

课后阅读 Unity 官方 Prefabs 文档。项目内优先读 Docs/02-systems/ui-system.md 和 Docs/01-flows/login-flow.md。课堂只需记住：Prefab 是模板，修改它会影响实例，agent 不应该无边界修改它。

Ask the agent: “请用文件路径列出这个 UI 功能涉及的 Scene / Prefab / Context / View / Mediator / Command / Service，不要修改。”