Mod 窗口开发规范

Framework 支持两种正式 Mod 窗口：Studio 内的原生 NGUI 窗口和基于 WebView2 的独立网页窗口。两种方案均可用于设置、结果展示和控制面板，按交互需求选择，同一 Mod 也可以组合使用。

项目	NGUI	WebView2
显示位置	Studio 现有 UIRoot 内	独立 Windows 窗口
内容开发	C# 与 Studio NGUI 控件；支持布局 JSON 导入	HTML / CSS / JavaScript
适用场景	需要贴合 Studio 视图和原生操作的工具	表单、报表和复杂网页交互
创建接口	StudioAPI.CreateWindow、ImportWindowLayout、ImportWindowLayoutJson	StudioAPI.CreateWebWindow
窗口类型	NativeModWindow / ImportedModWindow	ModWebWindow
业务通信	NGUI 回调直接调用 Studio API	双向 JSON；SDK 将网页消息派发到 Unity 主线程
关闭及重开	关闭按钮隐藏，Show() 重开；Dispose() 后重建	关闭窗口结束宿主，重开需重建；已就绪窗口用 Activate()
任务栏与 logo	没有独立任务栏项	独立任务栏项；SetIcon 支持 ICO / PNG
宿主依赖	Studio 自带 NGUI	Framework WebView2 宿主、.NET Framework 和 WebView2 Runtime

共同要求

• 在 Studio UI 和主窗口就绪后，从 Unity 主线程创建窗口，通常使用 Mods 菜单回调作为入口。
• 模型读取、修改和 Unity 对象操作在 Unity 主线程执行；耗时业务避免阻塞界面。
• 明确重复打开、用户关闭、模型切换和 Mod 卸载的行为。初始化时绑定事件，避免每次打开重复订阅；卸载时 Dispose 并清空窗口引用。
• 输入错误保留已填数据，状态和错误用文字表达，不能只靠颜色。长内容提供滚动，检查焦点、键盘、缩放和不同分辨率下的行为。
• 正式 Mod 窗口采用上述两种规范；OnGUI、GUI.Window、GUILayout 和独立 UGUI Canvas 不作为正式窗口方案。F10 的 IMGUI 覆盖层仅用于框架调试。

NGUI 规范

窗口复用 Studio 的 UIRoot、UICamera、UIPanel、字体和控件体系，不创建第二套事件相机，不修改共享资源。UI 创建、更新和销毁均在 Unity 主线程。

使用 CreateWindow 创建内容区域，或导入 Unity 导出的 .layout.json；布局导入属于 NGUI 方案。关闭按钮默认隐藏窗口，Show() 可再次打开。模态和输入区域需按 NGUI 规则处理焦点与工作区输入阻挡。

详细接口及规则见 NGUI 窗体 API 和 布局导入。

WebView2 规范

使用 CreateWebWindow，由 Framework 的独立 .NET WinForms STA 宿主加载本地 HTML 或 HTTP/HTTPS 页面。网页通过 window.chrome.webview.postMessage 发送消息，C# 在 MessageReceived 中处理；向网页发 JSON 前等待 Ready。

窗口保持无跨进程 Owner、有独立任务栏按钮，不自动跟随 Studio 最小化或保持在 Studio 上层。Studio HWND 用于验证宿主关联，不绑定为窗口 Owner；避免重新引入焦点切换卡顿。

Mod 的 owner GameObject 应保持激活，以便 Update 派发消息。用户关闭窗口时处理 Closed 并清空引用；显式 Close() / Dispose() 会取消待派发回调，不触发 Closed。Mod 卸载时主动 Dispose；owner 销毁和 Studio 退出也会清理宿主。

图标使用 SetIcon，资源路径以 Mod DLL 所在目录为基准。仅加载可信页面，解析并验证消息类型及业务参数，再操作 Studio 模型。分发 HTML/CSS/JS 和图标文件，部署配套 SDK 与完整 WebView2 宿主。

详细接口、双向消息、logo、Runtime 和部署要求见 WebView2 窗口规范。普通浏览器里的导出 HTML 报告是文件输出；只有由 Framework WebView2 宿主承载的页面属于这里的窗口方案。

验收

NGUI 检查窗口输入不会穿透工作区、显示/隐藏和缩放正确、反复打开无残留。WebView2 检查页面加载、焦点切换、双向消息、logo、关闭重建和 Runtime 缺失时的报错。两种方案都应验证模型切换、Mod 卸载和 Studio 退出的清理行为，源码检查和编译不能代替 Studio 内实际交互验收。