BeatSaber-IPA-Reloaded 插件开发指南

概述

BeatSaber-IPA-Reloaded 是一个为音乐节奏游戏 Beat Saber 设计的插件加载框架。本文将详细介绍如何使用该框架开发自定义插件，从基础结构到高级配置管理，帮助开发者快速上手插件开发。

基础插件结构

一个最基本的插件类需要包含以下几个核心组件：

1. 日志系统：使用 IPA.Logging.Logger 记录插件运行信息
2. 插件声明：通过 [Plugin] 特性标记插件类
3. 初始化方法：使用 [Init] 特性标记初始化逻辑
4. 生命周期事件：通过 [OnStart] 和 [OnExit] 处理启动和退出逻辑

[Plugin(RuntimeOptions.SingleStartInit)]
public class Plugin
{
    [Init]
    public Plugin(Logger logger)
    {
        // 初始化代码
    }

    [OnStart]
    public void OnStart()
    {
        // 游戏启动时执行的代码
    }

    [OnExit]
    public void OnExit()
    {
        // 游戏退出时执行的代码
    }
}

插件清单文件

每个插件都需要一个清单文件(manifest.json)来描述插件的基本信息：

{
    "name": "示例插件",
    "id": "com.example.demo",
    "author": "开发者名称",
    "version": "1.0.0",
    "description": "这是一个示例插件",
    "gameVersion": "1.20.0",
    "dependsOn": {
        "BSIPA": "^4.0.0"
    }
}

关键字段说明：

• id: 插件唯一标识符，建议使用反向域名格式
• gameVersion: 必须精确匹配目标游戏版本
• version: 必须遵循语义化版本规范(SemVer)

清单文件需要嵌入到插件DLL中，可以通过项目文件配置实现：

<ItemGroup>
    <EmbeddedResource Include="manifest.json" />
</ItemGroup>

配置系统详解

BeatSaber-IPA-Reloaded 提供了强大的配置管理系统，支持自动加载、保存和热重载。

基础配置类

创建一个配置类来管理插件设置：

public class PluginConfig
{
    public static PluginConfig Instance { get; set; }
    
    public virtual int Setting1 { get; set; } = 10;
    public virtual float Setting2 { get; set; } = 0.5f;
}

初始化配置

在插件初始化时加载配置：

[Init]
public Plugin(Logger logger, Config config)
{
    PluginConfig.Instance = config.Generated<PluginConfig>();
}

高级配置特性

1. 非空配置项：使用 [NonNullable] 特性确保配置项不为null
2. 集合类型支持：使用转换器处理复杂类型
3. 自动保存：通过虚属性和Changed方法实现自动保存

public class PluginConfig
{
    [NonNullable]
    public virtual SubConfig SubSettings { get; set; } = new SubConfig();
    
    [UseConverter(typeof(ListConverter<string>))]
    public virtual List<string> StringList { get; set; } = new List<string>();
    
    protected virtual void Changed()
    {
        // 配置变更时自动调用
    }
    
    public virtual void OnReload()
    {
        // 配置重载时调用
    }
}

最佳实践

1. 内部类型保护：将配置类设为internal，并通过[assembly: InternalsVisibleTo]暴露给框架
2. 详细描述：使用Markdown文件存储插件描述，保持清单文件简洁
3. 版本兼容：严格遵循语义化版本控制，确保插件更新不会破坏兼容性

通过本文介绍的内容，开发者可以快速构建功能完善的Beat Saber插件，利用框架提供的强大功能简化开发流程，专注于插件核心功能的实现。