跳到正文
本頁目錄

你的第一個腳本插件

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

  1. 如果服務器正在運行,先停止它。

  2. 在服務器文件夾中安裝這個變體:

    shell
    cd D:\servers\survival
    lip install github.com/LiteLDev/LegacyScriptEngine#quickjs
  3. 運行 lip list。你應該看到 github.com/LiteLDev/LegacyScriptEngine#quickjs 及其版本,下面是它的依賴。

你也可以在 lip 的「獲取模組」頁安裝它,見給服務器安裝模組。

2. 創建插件文件夾

插件就是 mods 中的一個文件夾,裡面有腳本和 manifest.json,和 C++ 模組一樣。

  1. 創建文件夾 D:\servers\survival\mods\MyPlugin。

  2. 在其中創建 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 先加載引擎。
  3. 在旁邊創建一個空的 main.js。

plugins 和 mods 是同一個文件夾

LSE 啟動時會把服務器的 plugins 文件夾做成指向 mods 的鏈接,所以 plugins\MyPlugin 就是同一個文件夾。如果你直接把單箇舊版腳本(例如 MyPlugin.js)放進去,LSE 會在下次啟動時為它創建文件夾和 manifest.json;再重啟一次即可加載。

3. 讓插件打個招呼

在 main.js 中寫入:

js
log("MyPlugin is running!");

log 向服務器控制台輸出一行。你不需要導入或定義它:LSE 為每個腳本提供 log、mc 以及 API 中的其他對象。

啟動服務器(在 lip 中選擇啟動服務器,或運行 lip run)。在 LeviLamina 加載模組的幾行中,你應該看到一行 MyPlugin is running!。如果插件有錯誤,控制台會在那裡顯示錯誤和行號。

進行下一步之前,再次停止服務器。

4. 添加控制台命令

添加一個只有服務器控制台能執行的命令:

js
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 是玩家進入遊戲的事件,你的函數會收到這個玩家:

js
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);
});

逐行說明:

  1. log(...) 把玩家的名字輸出到控制台。
  2. player.sendToast(title, message) 在玩家屏幕頂部顯示一條提示。
  3. mc.newItem(name, count) 創建一個物品堆:一顆鑽石。
  4. 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,重啟服務器,查看控制台。

下一步