StudioAPI 门面

StudioMod.SDK.StudioAPI 是 SDK 提供的静态入口类，封装了与 Studio 2.0 底层对象交互的高频操作。

模型与工程上下文

// 获取 Studio 主控制器单例 (BLStudio.Instance)
BLStudio studio = StudioAPI.StudioInstance;

// 获取当前正在编辑的 LDraw 工程文件（自动处理多标签页与打开状态）
LDrawFile currentFile = StudioAPI.CurrentFile;

// 获取当前激活的模型实体
LDrawModel activeModel = StudioAPI.ActiveModel;

if (activeModel != null)
{
    Logger.Info("当前模型名称: " + activeModel.ModelName);
}

原生菜单项扩展

Studio 2.0 启动后，框架会在顶部工具栏 Help 右侧自动注入一个原生的 Mods 下拉菜单，并深度兼容 Studio 的 NGUI 菜单项样式体系（支持主标题与右侧快捷键对齐）。

// 1. 标准注册菜单项
StudioAPI.RegisterMenuItem("导出当前模型数据", () =>
{
    var model = StudioAPI.ActiveModel;
    if (model == null)
    {
        StudioAPI.ShowToast("未检测到打开的模型！", 3f, Color.red);
        return;
    }
    // 执行自定义业务
});

// 2. 带快捷键提示文本的菜单项（快捷键右对齐显示在菜单右侧）
StudioAPI.RegisterMenuItem("快速导出零件清单", "Ctrl+Shift+E", () =>
{
    Logger.Info("执行快速导出...");
});

UI 增强特性

• 原生双标签排版：自动匹配 Studio 原生菜单预制体的 Text（主标题）与 ShortCutText（右侧快捷键）标签。
• 自动提取快捷键：若菜单名称格式为 "功能名 (F10)"，框架会自动解析并把 "F10" 提取为右侧快捷键展示。
• 动态宽度与边框自适应：根据最长文本内容与快捷键调整菜单项宽度（最小 200px），同步更新背景（background）与边框（border）尺寸，杜绝文字截断。
• 点击防抖保护：内置 0.35 秒点击防抖，防止误触双击导致重复执行耗时逻辑。

Mod 窗口

正式窗口支持 NGUI 和 WebView2 两种规范，见 Mod 窗口开发规范。两种方案的创建入口均在 Unity 主线程调用。

API	返回类型	用途
CreateWindow(owner, title, width, height)	NativeModWindow	创建 Studio 内 NGUI 窗口
ImportWindowLayout(owner, path) / ImportWindowLayoutJson(owner, json)	ImportedModWindow	导入 NGUI 布局数据
CreateWebWindow(owner, title, width, height, source)	ModWebWindow	创建独立 WebView2 窗口，source 为绝对 Uri

NGUI 窗口关闭后默认隐藏，可用 Show() 复用。WebView2 窗口使用 Ready、MessageReceived、Failed、Closed 事件；网页消息回调派发到 Unity 主线程，发送 JSON 前等待 Ready。SetIcon(path) 设置 ICO / PNG logo，已就绪窗口通过 Activate() 激活，关闭后需要重建。两种方案均需在 Mod 卸载时 Dispose。

具体示例见 NGUI 窗口规范 和 WebView2 窗口规范。

Toast 屏幕浮动提示

不需要创建复杂的 NGUI 控件，调用 ShowToast 即可在主界面右上角弹出半透明浮动提示：

// 默认绿色主题提示
StudioAPI.ShowToast("✔ 积木零件导出完毕！");

// 自定义时长与背景颜色
StudioAPI.ShowToast("⚠ 注意：发现冲突零件", 5.0f,
    new Color(0.85f, 0.45f, 0.1f, 0.95f));

窗口与布局

SDK 封装了三种在 Studio 里显示界面的方式：

方法	返回	用途
CreateWindow(owner, title, width, height)	NativeModWindow	原生 NGUI 窗口，自动挂到 Studio 现有的 UIRoot 下
ImportWindowLayout(owner, path) / ImportWindowLayoutJson(owner, json)	ImportedModWindow	从 JSON 布局批量创建窗口与具名控件
CreateWebWindow(owner, title, width, height, source)	ModWebWindow	WebView2 弹窗，内容用 HTML 渲染，独立进程 + 命名管道通信

// 原生 NGUI 窗口：Content 是挂载容器，坐标以 UI 单位计、Y 轴向上
var window = StudioAPI.CreateWindow(gameObject, "齿轮分析", 520, 360);
// 往 window.Content 里放 UILabel / UIButton 等原生控件

CreateWindow 要求宽高不小于 160 × 80 UI 单位。它内部自己解析 UICamera.mainCamera 与 UIRoot，所以不要再另建第二套事件相机。

线程与场景

CreateWebWindow 必须在 Unity 主线程调用，事件回调也会派发回主线程。CreateIMGUIInputRegion 用于给 IMGUI 窗口补一块 NGUI 命中区，只服务调试覆盖层这类场景。

全局业务事件

// Studio 启动就绪
StudioAPI.OnStudioReady += () =>
{
    Logger.Info("Studio 已完全就绪！");
};

// 模型保存成功（参数为保存的目标文件路径）
StudioAPI.OnModelSaved += (filePath) =>
{
    Logger.Info("用户保存了模型，路径为: " + filePath);
};

// 打开新模型
StudioAPI.OnModelOpened += (ldrawFile) =>
{
    Logger.Info("新模型文件已打开！");
};

事件订阅时机

这些是静态事件，在 OnLoaded() 里订阅，并在 OnUnloaded() 里退订，避免插件重载后重复触发。