跳到正文
本頁目錄

你的第一個 LeviLamina 模組

完成本教程後,你會擁有一個用 C++ 編寫的 LeviLamina 模組:它的倉庫由官方模組模板創建,在你的電腦上構建,並由你的服務器加載。模組啟動時會在服務器控制台輸出一行文字,還會添加一個 /hello 命令,向執行它的人打招呼。

第一次大約需要一小時,大部分時間花在安裝工具和等待第一次構建下載 LeviLamina 上。

你需要準備

  • 一臺 Windows 10 或 11 電腦(x64)。模組使用 Windows 工具構建。
  • C++ 基礎。如果你剛開始學 C++,可以從 cppreference.com 和 C++ Developer Roadmap 入手。
  • 一個 GitHub 賬號,用來從模板創建倉庫。
  • 一個裝有 LeviLamina 的服務器用於測試:見開你的第一個服務器。本教程使用 D:\servers\survival。

1. 安裝工具

按默認選項安裝以下軟件:

  1. Git。
  2. Visual Studio(免費的 Community 版即可)。在安裝程序中勾選工作負載 使用 C++ 的桌面開發:它會帶來 Windows SDK 和 C++ 庫。
  3. LLVM,選擇 LLVM-<version>-win64.exe 安裝程序。安裝時選擇把 LLVM 加入 PATH。模板使用 LLVM 的 clang-cl 編譯。
  4. xmake,LeviLamina 模組的構建工具。
  5. 可選,用於編輯代碼:Visual Studio Code,以及擴展 C/C++、XMake 和 clangd。

打開一個新的終端,檢查這些工具能否找到:

powershell
git --version
clang-cl --version
xmake --version

你應該看到三個版本號。如果某個命令提示無法識別,請重新安裝它並讓它把自己加入 PATH,然後再打開一個新終端。

2. 從模板創建倉庫

  1. 打開 LiteLDev/levilamina-mod-template,點擊 Use this template → Create a new repository。給倉庫起個名字,例如 my-mod;如果以後想發佈,請設為公開(public)。

    levilamina-mod-template 的 GitHub 頁面,右上角是綠色的“Use this template”按鈕。

  2. 把它克隆到存放項目的文件夾:

    powershell
    mkdir D:\projects
    cd D:\projects
    git clone https://github.com/<you>/my-mod
    cd my-mod
  3. 你應該看到 xmake.lua、lip.toml、manifest.json 等文件,以及包含 MyMod.cpp 和 MyMod.h 的 src\mod\ 文件夾。

3. 給模組命名

  1. 打開 xmake.lua。target 就是模組的名字:LeviLamina 會顯示它,模組的文件夾也以它命名。可以使用字母、數字和 -,不能有空格:

    lua
    target("my-mod") -- Change this to your mod name.

    本教程保留 my-mod。

  2. 在同一個文件中,固定構建所用的 LeviLamina 版本。它的前兩段版本號必須與服務器上的 LeviLamina 相同。要查看服務器的版本,在服務器文件夾中運行 lip list,它會顯示一行類似 github.com/LiteLDev/LeviLamina@26.60.3 的內容。然後寫:

    lua
    add_requires("levilamina 26.60.*", {configs = {target_type = get_config("target_type")}})
  3. 修改 LICENSE 中的版權人,或者換成你想用的許可證。模板本身使用 CC0,你可以自由選擇。

你也可以重命名 src\mod\ 中的命名空間 my_mod 和類 MyMod,本教程不需要這樣做。

4. 構建空模組

在寫代碼之前,先確認模板能構建。在倉庫文件夾中運行:

powershell
xmake f -y -p windows -a x64 -m release
xmake

第一條命令把構建配置為服務端模組(默認值;--target_type=client 構建客戶端模組)。第一次運行時它會下載 LeviLamina 及其依賴,需要幾分鐘。第二條命令進行編譯。

最後一行應該顯示 build ok,並且出現文件夾 bin\my-mod\,裡面有 my-mod.dll 和 manifest.json。

下載失敗

xmake 從 GitHub 下載包。如果你的網絡無法訪問 GitHub,請為 xmake 配置 GitHub 鏡像代理或 HTTP 代理,然後重新運行這兩條命令。如果 xmake 找不到你固定的 LeviLamina 版本,運行 xmake repo -u 更新包列表。

5. 添加日誌和命令

LeviLamina 會依次調用模組的三個階段:load()、enable() 和 disable()。在 load() 中只做與遊戲無關的工作,例如讀取配置文件:這時遊戲還沒有準備好。命令註冊和事件監聽要從 enable() 開始。

命令要在遊戲請求註冊時註冊,也就是 ServerCommandRegisterEvent 事件。把 src\mod\MyMod.cpp 的內容替換為:

cpp
#include "mod/MyMod.h"

#include "ll/api/command/CommandHandle.h"
#include "ll/api/command/CommandRegistrar.h"
#include "ll/api/event/EventBus.h"
#include "ll/api/event/command/ServerCommandRegisterEvent.h"
#include "ll/api/mod/RegisterHelper.h"
#include "mc/server/commands/CommandOrigin.h"
#include "mc/server/commands/CommandOutput.h"
#include "mc/server/commands/CommandPermissionLevel.h"
#include "mc/world/actor/player/Player.h"

namespace my_mod {

MyMod& MyMod::getInstance() {
    static MyMod instance;
    return instance;
}

bool MyMod::load() {
    getSelf().getLogger().debug("Loading...");
    return true;
}

bool MyMod::enable() {
    getSelf().getLogger().info("Hello from my first mod!");

    using namespace ll::event;
    EventBus::getInstance().emplaceListener<ServerCommandRegisterEvent>([](ServerCommandRegisterEvent&) {
        auto& command = ll::command::CommandRegistrar::getInstance(false) // false:服务端命令
                            .getOrCreateCommand("hello", "Says hello.", CommandPermissionLevel::Any);
        command.overload().execute([](CommandOrigin const& origin, CommandOutput& output) {
            auto* entity = origin.getEntity();
            if (entity == nullptr || !entity->isPlayer()) {
                output.success("Hello, console!"); // 由控制台或命令方块执行
                return;
            }
            auto* player = static_cast<Player*>(entity); // 安全:上面已检查 isPlayer()
            output.success("Hello, {}!", player->getRealName());
        });
    });
    return true;
}

bool MyMod::disable() {
    getSelf().getLogger().debug("Disabling...");
    return true;
}

} // namespace my_mod

LL_REGISTER_MOD(my_mod::MyMod, my_mod::MyMod::getInstance());

這段代碼做了什麼:

  • getLogger().info(...) 向服務器控制台輸出一行,並標上模組的名字。
  • emplaceListener 訂閱一個事件。模組被禁用時,LeviLamina 會自動移除監聽器。
  • getOrCreateCommand 創建 /hello;CommandPermissionLevel::Any 允許所有玩家執行(GameDirectors 則只允許管理員)。
  • overload().execute(...) 添加不帶參數的 /hello 重載,以及執行時運行的代碼。

遊戲類型沒有 RTTI

Minecraft 編譯時沒有運行時類型信息,因此不能對它的類使用 dynamic_cast。請先檢查類型(就像這裡的 isPlayer()),再使用 static_cast。

再次運行 xmake 構建。你應該再次看到 build ok。

6. 在服務器上加載模組

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

  2. 把 bin\my-mod 文件夾複製到服務器的 mods 文件夾,得到 D:\servers\survival\mods\my-mod\my-mod.dll:

    powershell
    Copy-Item -Recurse -Force bin\my-mod D:\servers\survival\mods\
  3. 按開你的第一個服務器中的方式啟動服務器,或在服務器文件夾中運行 lip run。

  4. 在 LeviLamina 加載模組的幾行之後,你應該看到一行帶有 [my-mod] 和 Hello from my first mod! 的輸出。

  5. 在服務器的輸入行中輸入 hello(控制台命令不帶 /)。你應該看到 Hello, console!。

  6. 從 Minecraft 加入服務器(地址 127.0.0.1,端口 19132),在聊天欄輸入 /hello。你應該看到 Hello, <你的名字>!。

以後每次修改:停止服務器,運行 xmake,重新複製文件夾,啟動服務器。

模組沒有加載時的錯誤碼

如果 LeviLamina 沒有加載 my-mod,而是報告 126 或 127 之類的錯誤,通常是因為模組所用的 LeviLamina 版本與服務器的不同。請檢查第 3 步固定的版本。LeviLamina 故障排除解釋了這些錯誤碼。

你現在有了什麼

  • 一個存放模組的 Git 倉庫,可以用 xmake 構建。
  • 一個輸出日誌並註冊命令的模組,已被你的服務器加載。
  • lip.toml 和 .github\workflows\ 中的發佈工作流,可以隨時發佈。

下一步