快速开始

本指南将帮助你快速搭建 MSL 插件开发环境，并创建你的第一个插件。

什么是MSL

MinecraftServerListener（简称MSL）是一个基于 Node.js 的 Minecraft 外置框架，它可以用于编写插件。

MSL不是服务器核心，不能单独依靠MSL开服。若要开服，你必须先了解开服技术。

MSL的原理非常简单，当一个玩家进入服务器、退出服务器、发送消息、执行指令或者触发其它插件时，都会在服务器后台生成一条日志，该日志包含了操作的执行者、执行内容等信息。使用MSL启动mc服务器后，MSL就可以监听到这些日志，当日志的内容符合MSL或者MSL插件的解析规则时，就会触发插件。

MC后台还支持输入命令，那么msl插件就可以通过title tellraw等命令向玩家发送信息，或者通过ban banip等工具操作玩家，甚至可以通过eco（essentailsx插件提供）来操作玩家的经济。

以上的输入-输出机制，便是MSL工作的核心原理。

环境要求

兼容性提示

依据MSL的工作原理，我们认为MSL适配所有Minecraft服务器版本，并且支持非传统命令行环境（例如MCSManager、宝塔面板），但不保证MSL在这些环境下显示及运行完全正常。其次，MSL不建议在velocity上使用，你应该将其放在后端上。

服务端提示

虽然MSL支持原版客户端，但如果你需要开发CLI或者以/开头的指令的话，我们强烈建议你使用Paper/Bukkit/Spigot/Folia服务器端，通过一些技巧性的插件实现完美配合。具体见指令注册章节：指令注册。

MSL对环境要求极低，在开始之前，请确保你的系统已安装以下软件：

Node.js 14.0 或更高版本 https://nodejs.org/
一个 Minecraft 服务器（如原版、Paper、Spigot 等）

因为Node.js支持Windows/Linux/MacOS等全部系统，因此我们认为你可以在任何系统上运行MSL。

安装 MSL

1. 下载源代码

发行提示

MSL项目结构比较简洁，运行完全依赖其自身文件结构，因此不需要提供发行版。直接从Github上下载的项目.zip包即可运行。

打开https://github.com/imkysou/msl
点击绿色的“Code”按钮，点击”Download ZIP“按钮，然后即可下载源代码

2. 配置文件

配置提示

因为不同配置的MC服务端配置不同，例如在一些服务器上，玩家发送一条消息，后台日志格式可能为“[12:34:56 INFO]: <Steve> abc”，但另外的一些服务器上，可能显示为“[12:34:56 INFO]: [0/0 无公会][玩家] Steve: abc”。出于格式的不同，MSL无法自动确定哪些地方为玩家名、时间和消息内容，因此需要你手动指定正则表达式。不仅这样，即使使用其他同类型不同语言的输入-输出控制端也需经此步骤（例如MCDR）。

对于未接触过编程领域的服主来说可能手动编写正则表达式比较复杂，我们认为你完全可以通过AI助手帮助编写正则表达式。经过验证，Deepseek等AI助手编写的表达式均可符合要求。向AI助手咨询时需要注意提供完整的服务器日志（至少一整行，必须复制粘贴，不然有的空格可能你没打上）

编辑 config.js 文件，配置你的服务器信息：

javascript

module.exports = {
    /**
     * 是否开启调试模式，如果要开启，则使用debug: true，如果关闭，则使用debug: false
     * 开启后，玩家发送消息、执行指令都会触发调试信息，调试信息开头签名均为[MinecraftServerListener]
     */
    debug: true,
    api: {
        /**
         * HTTP API端口
         * 若你不明白该功能，请无需改动。
         */
        port: 30600,           // HTTP API 端口
        /**
         * HTTP API访问令牌
         * 若你不明白该功能，请无需改动
         */
        token: "your-api-token" // API 访问令牌
    },
    minecraft: {
        /**
         * Minecraft服务器IP地址
         */
        ip: "127.0.0.1:25565",
        /**
         * Minecraft服务器启动参数，如果有完整的路径，路径两端应当打双引号，例如启动命令为
         *   java -Xms2G -Xmx4G -jar D:\\server\\mc.jar
         * 则应当配置
         *   args: [
         *     `java`,
         *     `-Xms2G`,
         *     `-Xmx4G`,
         *     `-jar`,
         *     `"D:\\server\\mc.jar"`
         *   ]
         * 若你实在不明白如何使用，可以向AI咨询。
         * 
         * （所有反斜杠 \ 必须打两下，打成 \\）
         */
        args: [
            `java`,
            `-Dfile.encoding=UTF-8`,
            `-Dsun.stdout.encoding=UTF-8`,
            `-Dsun.stderr.encoding=UTF-8`,
            `-jar`,
            `server.jar`
        ],
        /**
         * Minecraft服务器目录，你的存档、日志文件都保存在该目录下。
         * 通常，此处写为你服务端jar所在文件夹。
         */
        cwd: "./server",
        autoRestart: {
            /**
             * 是否启用自动重启，若启用，设置为true，不启用，设置为false
             * 启用该功能后，服务器崩溃时将重新自动启动。
             * 注意：你如果使用stop命令手动停止服务器，该服务器将依然运行。
             */
            enable: true
        },
        /**
         * 日志解析正则表达式
         * 
         * 关于该部分的内容，请查看上面的 配置提示 部分，大部分插件运行失效的原因都是因为正则没配置好。
         */
        logRegexs: {
            // 玩家进入
            playerJoin: /^\[(\d{2}:\d{2}:\d{2}) INFO\]: (\S+) joined the game$/,
            playerQuit: /^\[(\d{2}:\d{2}:\d{2}) INFO\]: (\S+) left the game$/,
            playerSendMessage: /^\[(\d{2}:\d{2}:\d{2}) INFO\]: <(\S+)> (.+)$/,
            playerSendCommand: /^\[(\d{2}:\d{2}:\d{2}) INFO\]: (\S+) issued server command: \/(.+)$/
        }
    }
}

3. 启动 MSL

启动提示

因为MSL启动方式与mc服务器启动方式不同，你应当先让服务器管理或运维熟悉MSL启动方式。你也可以直接在msl根目录创建一个.bat文件，里面写上node index，每次启动MSL双击即可；
MSL启动后会自动拉起Minecraft服务器，你无需再额外启动Minecraft服务器；
Minecraft服务器自身提供的日志记录功能不会记录msl的运行日志（但仍然会记录mc运行日志），你可以通过一些插件解决这个问题;
即使MSL进程崩溃，Minecraft服务器也会继续运行。

在控制台（不是Minecraft服务器指令输入面板）中执行以下命令来启动MSL：

bash

node index.js

启动后，MSL 会自动加载 plugins 目录下的所有插件，并启动 Minecraft 服务器。

项目结构

了解 MSL 的项目结构有助于你更好地开发插件：

msl/
├── index.js            # 主程序入口
├── config.js           # 配置文件（需自行创建）
├── config.example.js   # 配置模板
├── .msl/
│   ├── pluginsLibs.js  # 插件 API 库
│   ├── pluginsLoader.js# 插件加载器
│   └── MSL_VERSION     # 版本信息
├── plugins/            # 插件目录
│   └── demo.js         # 示例插件
└── server/             # Minecraft 服务器目录
    └── server.jar      # 服务器核心

你的插件应当放在 plugins 目录下。有关插件开发，请查看后续章节。

如果要为插件创建配置文件，可以通过fs模块来创建，具体体系由插件自行灵活定义。

控制台命令

TIP

为确保安全性，msl命令能且只能在控制台使用，无法在MC服务器gui窗口或是游戏聊天框中使用。

MSL 提供了一系列控制台命令来管理服务器和插件：

命令	说明
`msl`	显示帮助信息
`msl help`	显示帮助信息
`msl version`	显示 MSL 版本此处显示.msl/MSL_VERSION中的内容
`msl reload`	重载所有插件不建议生产环境使用重载，由于sandbox机制的独特性可能造成内存泄漏以及事件重复（旧计时器将被卸载）
`msl stopmc`	停止 Minecraft 服务器这不会停止msl进程
`msl startmc`	启动 Minecraft 服务器插件不会重新加载
`msl disable_plugin all`	卸载所有插件已加载的插件将失效（不是从磁盘中卸载），不建议在生产环境中使用，由于sandbox机制的独特性可能造成内存泄漏以及事件重复（旧计时器将被卸载）
`msl disable_plugin <name>`	卸载指定插件指定的插件将被卸载，效果同上
`msl enable_plugin all`	加载所有插件
`msl enable_plugin <name>`	加载指定插件
`msl list_plugins`	列出所有插件及状态
`msl debug on`	开启调试模式
`msl debug off`	关闭调试模式
`msl debug`	查看当前调试状态

下一步

现在你已经完成了 MSL 的基本配置，接下来可以：

创建你的第一个插件 - 学习如何编写插件
调试插件 - 了解调试技巧和工具
事件机制 - 深入了解事件系统

快速开始 ​

什么是MSL ​

环境要求 ​

安装 MSL ​

1. 下载源代码 ​

2. 配置文件 ​

3. 启动 MSL ​

项目结构 ​

控制台命令 ​

下一步 ​