你的第一个脚本插件
完成本教程后,你的服务器会运行一个你用 JavaScript 编写的插件。它会问候每个加入的玩家,给他们显示一条欢迎提示,在他们脚下掉落一颗钻石,并添加一个控制台命令。插件运行在 LegacyScriptEngine(LSE)上,它让你用 JavaScript、Lua 或 Python 而不是 C++ 编写 LeviLamina 插件:不需要编译器,不需要构建,只要一个文本文件和一次重启。
大约需要二十分钟。
你需要准备
- 一个用
lip搭建、装有 LeviLamina 的服务器:见开你的第一个服务器。本教程使用D:\servers\survival。 - 一个文本编辑器。Visual Studio Code 是不错的选择,任何能保存纯文本的编辑器都可以。
- 能连到服务器的任意设备上的 Minecraft 基岩版,用来在游戏中看到问候。没有它也可以完成第 1 到 4 步。
你不需要精通 JavaScript:代码很短,并且会逐行解释。如果你从没写过,MDN 的 JavaScript 指南介绍了基础知识。
1. 安装 JavaScript 引擎
LSE 为每种语言提供一个包,称为变体。本教程使用 JavaScript 引擎 #quickjs。
-
如果服务器正在运行,先停止它。
-
在服务器文件夹中安装这个变体:
shellcd D:\servers\survival lip install github.com/LiteLDev/LegacyScriptEngine#quickjs -
运行
lip list。你应该看到github.com/LiteLDev/LegacyScriptEngine#quickjs及其版本,下面是它的依赖。
你也可以在 lip 的「获取模组」页安装它,见给服务器安装模组。
2. 创建插件文件夹
插件就是 mods 中的一个文件夹,里面有脚本和 manifest.json,和 C++ 模组一样。
-
创建文件夹
D:\servers\survival\mods\MyPlugin。 -
在其中创建
manifest.json,内容如下:json{ "entry": "main.js", "name": "MyPlugin", "type": "lse-quickjs", "dependencies": [ { "name": "legacy-script-engine-quickjs" } ] }entry是要运行的脚本。name是插件的名称,请与文件夹名保持一致。type指定由哪个引擎运行它:JavaScript 为lse-quickjs。其他引擎为lse-lua、lse-nodejs和lse-python。dependencies让 LeviLamina 先加载引擎。
-
在旁边创建一个空的
main.js。
plugins 和 mods 是同一个文件夹
LSE 启动时会把服务器的 plugins 文件夹做成指向 mods 的链接,所以 plugins\MyPlugin 就是同一个文件夹。如果你直接把单个旧版脚本(例如 MyPlugin.js)放进去,LSE 会在下次启动时为它创建文件夹和 manifest.json;再重启一次即可加载。
3. 让插件打个招呼
在 main.js 中写入:
log("MyPlugin is running!");log 向服务器控制台输出一行。你不需要导入或定义它:LSE 为每个脚本提供 log、mc 以及 API 中的其他对象。
启动服务器(在 lip 中选择启动服务器,或运行 lip run)。在 LeviLamina 加载模组的几行中,你应该看到一行 MyPlugin is running!。如果插件有错误,控制台会在那里显示错误和行号。
进行下一步之前,再次停止服务器。
4. 添加控制台命令
添加一个只有服务器控制台能执行的命令:
mc.regConsoleCmd("greet", "Greets someone from the console", (args) => {
log(`Hello, ${args[0] ?? "world"}!`);
});mc.regConsoleCmd 注册一个命令以及执行它时运行的函数。LSE 会把命令后面的内容拆分成 args。
启动服务器,在输入行中输入 greet Steve。你应该看到 Hello, Steve!。
5. 在玩家加入时问候
现在来响应一个游戏事件。每当事件发生,mc.listen 都会调用你的函数;onJoin 是玩家进入游戏的事件,你的函数会收到这个玩家:
mc.listen("onJoin", (player) => {
log(`${player.name} has joined the server.`);
player.sendToast("Welcome!", "Thanks for joining the server!");
const loginReward = mc.newItem("minecraft:diamond", 1);
mc.spawnItem(loginReward, player.pos);
});逐行说明:
log(...)把玩家的名字输出到控制台。player.sendToast(title, message)在玩家屏幕顶部显示一条提示。mc.newItem(name, count)创建一个物品堆:一颗钻石。mc.spawnItem(item, pos)把它掉落在玩家所在的位置。
现在你的 main.js 包含第 3、4、5 步的三部分。重启服务器,然后从 Minecraft 加入(在同一台电脑上:地址 127.0.0.1,端口 19132)。你应该看到:
- 控制台中出现
<你的名字> has joined the server.; - 游戏中出现提示 Welcome!,身旁的地上有一颗钻石。
小步前进
每次只改一处,重启,检查。出问题时,你就知道是哪次修改造成的。插件以及它调用的 API 的所有错误都会显示在服务器控制台中。
6. 获取编辑器提示(可选)
编辑器本身不认识 mc、log 等 API。legacy-script-engine-api 仓库提供了 JavaScript 和 TypeScript(以及 Python)的类型定义,可以带来自动补全和内联文档;请按它的 README 为你的编辑器配置。
你现在有了什么
- 服务器上的 LSE JavaScript 引擎。
- 插件
mods\MyPlugin:一个manifest.json和一个包含控制台命令与加入事件的main.js。 - 开发它的方式:编辑
main.js,重启服务器,查看控制台。
下一步
- 可以监听的所有事件:事件监听和玩家事件。
- 能对玩家做什么:玩家 API。
- 带参数和权限、也供玩家使用的命令:命令 API。
- 给玩家的对话框:表单 API。文件中的设置:配置文件 API。
- 完整的 API 和其他语言:LegacyScriptEngine API和语言支持。
- 常见问题:LegacyScriptEngine FAQ。
- 把插件作为
lip包分享:lip.toml 中的self资源会安装你仓库中的文件,用 lip 发布你的模组介绍了发布步骤。 - 需要更快的速度或访问游戏内部:你的第一个 LeviLamina 模组。