跳到正文
本頁目錄

你的第一個 Android 原生模組

完成本教程後,你會擁有一個 Android 上 Minecraft 基岩版的原生模組:一個由官方模板構建的 C++ 庫,打包成 .levipack,導入手機上的 LeviLauncher,並在遊戲啟動時向 Android 日誌寫入你自己的一行文字。這個模組還有一個可以在 LeviLauncher 中修改的設置。

第一次大約需要一小時,大部分時間花在安裝 Android SDK 上。

Android,而不是 LeviLamina

Android 原生模組由 Android 版 LeviLauncher 通過 Preloader SDK(LiteLDev/preloader-android)加載,而不是由 LeviLamina 加載,並使用獨立的 pl:: API。模組的形態(load()、enable()、disable()、getSelf())與你的第一個 LeviLamina 模組相同。

你需要準備

  • 一臺 Windows、Linux 或 macOS 電腦,並安裝以下工具:
    • Android Studio,或者只裝它的命令行工具,用於獲取 Android SDK 和 NDK;
    • CMake 3.22 或更高版本,以及 Ninja;
    • PowerShell 7(在 Windows 上也可以用 Windows PowerShell);
    • 一個面向電腦本身的 C++ 編譯器:Windows 上是勾選了 使用 C++ 的桌面開發 的 Visual Studio,Linux 和 macOS 上是 GCC 或 Clang。構建時會在電腦上運行一個小程序,生成模組的默認配置;
    • Git。
  • 一部 ARM64 的 Android 手機(Android 9 或更高版本),裝有 Google Play 上的 Minecraft 和 Android 版 LeviLauncher:見在 Android 上玩模組。
  • 可選:Android 平臺工具(adb),並在手機上開啟 USB 調試,用於查看日誌。
  • C++ 基礎。

1. 安裝 SDK 和 NDK

  1. 在 Android Studio 中打開 Settings → Languages & Frameworks → Android SDK。在 SDK Platforms 中勾選 Android 9.0 (API 28)。在 SDK Tools 中勾選 Show Package Details,並在 NDK (Side by side) 下勾選 28.2.13676358。點擊應用。

  2. 記下頁面頂部的 Android SDK Location,例如 C:\Users\<you>\AppData\Local\Android\Sdk。

  3. 在新的終端中檢查其他工具:

    powershell
    cmake --version
    ninja --version

你應該看到 3.22 或更高的 CMake 版本、一個 Ninja 版本,並且 SDK 目錄中有文件夾 ndk\28.2.13676358。

2. 從模板創建倉庫

  1. 打開 levilauncher-android-mod-template,點擊 Use this template → Create a new repository,例如命名為 my-android-mod。

  2. 克隆它:

    powershell
    git clone https://github.com/<you>/my-android-mod
    cd my-android-mod
  3. 你應該看到 CMakeLists.txt、manifest.json.in、scripts\package.ps1,以及包含 MyMod.cpp、MyMod.h、Config.h 和 Config.cpp 的 src\mod\。

3. 給模組命名

打開 CMakeLists.txt。靠近頂部的幾項設置描述了你的模組,它們會填進模組的 manifest.json。修改它們:

cmake
set(MOD_ID "my_android_mod" CACHE STRING "LeviLauncher mod package directory name")
set(MOD_NAME "My Android Mod" CACHE STRING "LeviLauncher mod display name")
set(MOD_AUTHOR "<you>" CACHE STRING "LeviLauncher mod author")
set(MOD_VERSION "0.1.0" CACHE STRING "LeviLauncher mod version")
set(MOD_LIBRARY_NAME "my_android_mod" CACHE STRING "Native library name without lib prefix or .so suffix")
set(MOD_MINECRAFT_VERSIONS "[\"1.26.*\"]" CACHE STRING "Raw JSON array for manifest minecraft_versions")
  • MOD_ID 是模組在手機上的目錄名,也就是運行期模組 id。首次發佈後請保持不變:LeviLauncher 會把它用於路徑、Mod Menu 歸屬和用戶保存的設置。
  • MOD_NAME 是 LeviLauncher 顯示的名稱,也是你在 Android 日誌中的標籤。
  • MOD_MINECRAFT_VERSIONS 列出模組適配的遊戲版本;* 匹配版本的其餘部分。空列表 [] 表示所有版本。請確保它包含你手機上的 Minecraft 版本。

模板的 C++ 命名空間和類是 clange_me 和 ClangeMeMod。你以後可以重命名它們,本教程保持不變。

4. 寫下你的第一行

模板已經帶有類型化配置:src\mod\Config.h 中的結構體 ModConfig 會保存為模組的 config/config.json,模組啟用時會把其中的 message 寫入日誌。修改默認消息:

cpp
struct ModConfig {
    int version = 1;
    bool enabled = true;
    std::string message = "Hello from my first Android mod!";
};

打開 src\mod\MyMod.cpp 看看它在哪裡被使用。生命週期如下:

  1. load() 在模組加載時運行。模板在這裡創建數據和配置文件夾,並加載配置。
  2. enable() 在遊戲啟動前運行。它用 getSelf().getLogger().info(...) 寫出 Config message: <message>。
  3. disable() 在遊戲關閉時運行;unload() 在最終清理時運行。

src\main.cpp 末尾的 PL_REGISTER_MOD 註冊了模組唯一的長期存活實例。

5. 構建 .levipack

設置 SDK 位置,然後為 64 位 ARM 運行打包腳本:

Windows
$env:ANDROID_HOME = "C:/Users/<you>/AppData/Local/Android/Sdk"
./scripts/package.ps1 -Abi arm64-v8a

在 Windows 上,請在 Developer PowerShell for VS 中運行,這樣 CMake 才能找到電腦上的編譯器。第一次構建會下載 Preloader SDK 和幾個庫。

最後你應該得到文件 build-arm64-v8a\my_android_mod-0.1.0-arm64-v8a.levipack。.levipack 是一個 ZIP 文件,裡面是文件夾 my_android_mod\,包含 manifest.json、libmy_android_mod.so 和 config\。

讓 GitHub 來構建

模板在 .github\workflows\build.yml 中帶有工作流。推送後,倉庫的 Actions 標籤頁會構建 .levipack 文件並作為構件(artifact)提供;推送 v* 標籤還會把它們附加到發佈版本上。

6. 導入 LeviLauncher

  1. 用 USB 或任何你喜歡的方式,把 .levipack 複製到手機的 Download(下載)文件夾。

  2. 打開 LeviLauncher。在「啟動」頁面上,點擊「模組」卡片上的管理:會打開當前實例的「模組」頁面。

  3. 點擊添加模組,在文件選擇器中選擇你的 .levipack。你應該看到“成功處理 1 個模組文件”。(也可以在文件管理器中打開 .levipack,選擇用 LeviLauncher 打開。)

    LeviLauncher 的“模組”頁面,右上角的“添加模組”按鈕用來導入 .levipack 文件。

  4. 你應該在模組列表中看到 My Android Mod,版本為 0.1.0,開關已打開。

第一次在 Android 上用 LeviLauncher?在 Android 上玩模組會一步步帶你完成。

7. 確認它在運行

  1. 從 LeviLauncher 啟動遊戲。

  2. 用 USB 連接手機,在電腦上查看 Android 日誌:

    Windows
    adb logcat | Select-String "My Android Mod"

    你應該看到一行 Config message: Hello from my first Android mod!。

  3. 回到 LeviLauncher,打開你的模組的詳情。它現在有了配置:把 Message 改成別的內容並保存。再次啟動遊戲,日誌會顯示新的消息。

沒有 adb?第 3 步依然可行:配置之所以存在,正是因為你的模組運行了 load() 並保存了它。

你現在有了什麼

  • 一個 Android 原生模組倉庫,可以在電腦上和 GitHub 上構建出 .levipack。
  • 已安裝到 LeviLauncher 中的模組,它會寫入 Android 日誌,並帶有用戶可以修改的設置。

下一步