你的第一個腳本插件
完成本教程後,你的服務器會運行一個你用 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 模組。