快速上手

这篇带你把第一个插件跑起来：它会注册一个自定义菜单项，并在屏幕上弹出一条 Toast。

1. 创建项目

新建一个 C# 类库项目：

目标框架：.NET Framework 4.7.2 或 .NET Standard 2.0
平台：x64
语言版本：C# 7.3 及以上

2. 引用程序集

插件项目至少要引用下面这些程序集：

程序集	位置	用途
`StudioSDK.dll`	`StudioModFramework/bin/` 或 `Studio_Data/Managed/`	SDK 核心接口与门面
`0Harmony.dll`	`StudioModFramework/deps/` 或 `Studio_Data/Managed/`	HarmonyX 补丁引擎
`UnityEngine.dll`	`Studio 2.0/Studio_Data/Managed/`	Unity 基础类（`MonoBehaviour`、`GameObject`）
`UnityEngine.CoreModule.dll`	`Studio 2.0/Studio_Data/Managed/`	Unity 核心模块
`Studio.dll`	`Studio 2.0/Studio_Data/Managed/`	Studio 原生 NGUI 类型与业务接口
`UnityEngine.IMGUIModule.dll`	`Studio 2.0/Studio_Data/Managed/`	仅供已有调试覆盖层使用，不得用于新建正式插件窗口

需要操作积木零件、模型树、相机或工程文件时，再按需引用：

Studio.dll —— Studio 核心控制器（BLStudio、TabbarManager、菜单控制）
Studio.DataModel.dll —— 模型数据结构（LDrawFile、LDrawModel、LDrawPart）
BrickLink.Studio.Common.Runtime.dll —— 通用积木与渲染定义

3. 写插件代码

csharp

using StudioMod.SDK;
using UnityEngine;

namespace MyFirstStudioMod
{
    // 1. 声明插件元数据特性
    [StudioPlugin(
        id: "com.example.helloworld",
        name: "Hello World 示例插件",
        version: "1.0.0",
        author: "DeveloperName",
        description: "这是我的第一个 Studio 2.0 插件"
    )]
    public class HelloWorldPlugin : StudioPlugin
    {
        // 2. 插件生命周期入口
        public override void OnLoaded()
        {
            Logger.Info("Hello World 插件已成功加载！");

            // 注册到顶部 "Mods" 菜单
            StudioAPI.RegisterMenuItem("点我弹出问候", OnMenuClicked);

            // 屏幕右上角显示 Toast
            StudioAPI.ShowToast("欢迎使用 Hello World 插件！", 4.0f,
                new Color(0.2f, 0.6f, 0.9f, 0.9f));
        }

        private void OnMenuClicked()
        {
            StudioAPI.ShowToast("你点击了自定义菜单项！");
            Logger.Info("菜单项被用户触发。");
        }

        // 3. 原生 Unity 帧循环（继承自 MonoBehaviour）
        void Update()
        {
            if (Input.GetKeyDown(KeyCode.F9))
            {
                StudioAPI.ShowToast("按下 F9 触发快捷动作");
            }
        }
    }
}

三个要点：

主类必须继承 StudioMod.SDK.StudioPlugin，并标记 [StudioPlugin(...)] 特性供 Loader 识别。
初始化逻辑写在 OnLoaded() 里——此时 Harmony 补丁已经自动注入完毕。
因为底层是 MonoBehaviour，Update、Start、协程都能直接用。

4. 编译

用 Visual Studio 正常生成即可，产物是 YourMod.dll。如果 Studio 不在默认目录，可在插件项目里指定：

xml

<Project>
  <PropertyGroup>
    <StudioManagedDir>D:\Studio 2.0\Studio_Data\Managed</StudioManagedDir>
  </PropertyGroup>
</Project>

5. 部署

把编译出的 YourMod.dll 放进以下任一路径：

全局目录：C:\Program Files\Studio 2.0\Mods\
用户目录：%LOCALAPPDATA%\Studio 2.0\Mods\

支持子目录组织，例如 Mods/YourMod/YourMod.dll；同目录下伴随的依赖 DLL 会被自动解析。

6. 验证

启动 Studio 2.0：

顶部工具栏 Help 右侧应该出现 Mods 菜单，里面有「点我弹出问候」。
按 F10 打开控制台，「已加载插件」页能看到你的插件、版本、作者与补丁数量。

没看到插件？去 F10 运行时控制台看「运行日志」页，加载异常会连堆栈一起打印出来。

下一步

插件生命周期 —— 搞清楚各个回调的调用时机
StudioAPI 门面 —— 能对 Studio 做什么
配置系统 —— 让插件可配置
Mod 窗口开发规范 —— NGUI / WebView2 两种正式窗口方案

快速上手 ​

1. 创建项目 ​

2. 引用程序集 ​

3. 写插件代码 ​

4. 编译 ​

5. 部署 ​

6. 验证 ​

下一步 ​