MSL 插件开发文档

Appearance

API 概述 ​

MSL 提供了一套完整的插件 API，所有 API 都以 plugin_ 为前缀，在插件沙箱环境中自动注入，无需手动引入即可直接使用。

API 列表 ​

API说明
plugin_require引入 Node.js 模块
plugin_executeCommand执行 Minecraft 指令
plugin_startServer启动 Minecraft 服务器
plugin_forceStopServer强制停止服务器进程
plugin_registerCommand注册自定义指令
plugin_onEvent监听事件
plugin_triggerEvent触发自定义事件
plugin_log输出日志
plugin_generateOfflineUUID生成离线玩家 UUID
plugin_registerApi注册 HTTP API 端点
plugin_push & plugin_pull全局数据存储
plugin_getPluginsList获取插件列表

使用约定 ​

自动注入 ​

所有 plugin_* 函数在插件加载时自动注入到沙箱环境，无需任何引入操作：

javascript
// 直接使用，无需 require
plugin_log("INFO", "插件已加载");
plugin_executeCommand("say Hello");

沙箱环境 ​

插件运行在隔离的沙箱环境中，具有以下特点：

  1. 安全隔离：插件错误不会影响 MSL 主程序
  2. 资源追踪：事件监听器、指令、定时器等资源会被追踪，插件卸载时自动清理
  3. 受限访问：插件无法直接访问文件系统，需要通过 plugin_require 引入模块

错误处理 ​

MSL 会自动捕获插件中的错误，但建议在关键操作中添加错误处理：

javascript
plugin_onEvent("playerJoin", (time, player) => {
    try {
        // 你的代码
    } catch (error) {
        plugin_log("ERROR", `处理失败: ${error.message}`);
    }
});

调试模式 ​

开启调试模式后，所有 API 调用都会输出日志：

javascript
// 在 config.js 中设置
debug: true

// 或使用命令
msl debug on

类型定义 ​

以下是 API 参数和返回值的类型定义：

typescript
// 日志类型
type LogType = "INFO" | "WARN" | "ERROR";

// HTTP 方法
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";

// 插件列表
interface PluginsList {
    loaded: string[];    // 已加载的插件
    unloaded: string[];  // 未加载的插件
    all: string[];       // 所有插件
}

// HTTP 请求/响应对象（Node.js 原生）
interface IncomingMessage {
    method: string;
    url: string;
    headers: Record<string, string>;
    on(event: "data", listener: (chunk: Buffer) => void): void;
    on(event: "end", listener: () => void): void;
}

interface ServerResponse {
    writeHead(statusCode: number, headers?: Record<string, string>): void;
    end(data: string | Buffer): void;
}

下一步 ​

选择一个 API 查看详细文档，或者查看 新手指南 开始学习插件开发。