你的第一個 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
-
在 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。點擊應用。 -
記下頁面頂部的 Android SDK Location,例如
C:\Users\<you>\AppData\Local\Android\Sdk。 -
在新的終端中檢查其他工具:
powershellcmake --version ninja --version
你應該看到 3.22 或更高的 CMake 版本、一個 Ninja 版本,並且 SDK 目錄中有文件夾 ndk\28.2.13676358。
2. 從模板創建倉庫
-
打開 levilauncher-android-mod-template,點擊 Use this template → Create a new repository,例如命名為
my-android-mod。 -
克隆它:
powershellgit clone https://github.com/<you>/my-android-mod cd my-android-mod -
你應該看到
CMakeLists.txt、manifest.json.in、scripts\package.ps1,以及包含MyMod.cpp、MyMod.h、Config.h和Config.cpp的src\mod\。
3. 給模組命名
打開 CMakeLists.txt。靠近頂部的幾項設置描述了你的模組,它們會填進模組的 manifest.json。修改它們:
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 寫入日誌。修改默認消息:
struct ModConfig {
int version = 1;
bool enabled = true;
std::string message = "Hello from my first Android mod!";
};打開 src\mod\MyMod.cpp 看看它在哪裡被使用。生命週期如下:
load()在模組加載時運行。模板在這裡創建數據和配置文件夾,並加載配置。enable()在遊戲啟動前運行。它用getSelf().getLogger().info(...)寫出Config message: <message>。disable()在遊戲關閉時運行;unload()在最終清理時運行。
src\main.cpp 末尾的 PL_REGISTER_MOD 註冊了模組唯一的長期存活實例。
5. 構建 .levipack
設置 SDK 位置,然後為 64 位 ARM 運行打包腳本:
$env:ANDROID_HOME = "C:/Users/<you>/AppData/Local/Android/Sdk"
./scripts/package.ps1 -Abi arm64-v8aexport ANDROID_HOME="$HOME/Android/Sdk" # macOS:$HOME/Library/Android/sdk
pwsh ./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
-
用 USB 或任何你喜歡的方式,把
.levipack複製到手機的 Download(下載)文件夾。 -
打開 LeviLauncher。在「啟動」頁面上,點擊「模組」卡片上的管理:會打開當前實例的「模組」頁面。
-
點擊添加模組,在文件選擇器中選擇你的
.levipack。你應該看到“成功處理 1 個模組文件”。(也可以在文件管理器中打開.levipack,選擇用 LeviLauncher 打開。) -
你應該在模組列表中看到 My Android Mod,版本為
0.1.0,開關已打開。
第一次在 Android 上用 LeviLauncher?在 Android 上玩模組會一步步帶你完成。
7. 確認它在運行
-
從 LeviLauncher 啟動遊戲。
-
用 USB 連接手機,在電腦上查看 Android 日誌:
Windowsadb logcat | Select-String "My Android Mod"Linux 和 macOSadb logcat | grep "My Android Mod"你應該看到一行
Config message: Hello from my first Android mod!。 -
回到 LeviLauncher,打開你的模組的詳情。它現在有了配置:把 Message 改成別的內容並保存。再次啟動遊戲,日誌會顯示新的消息。
沒有 adb?第 3 步依然可行:配置之所以存在,正是因為你的模組運行了 load() 並保存了它。
你現在有了什麼
- 一個 Android 原生模組倉庫,可以在電腦上和 GitHub 上構建出
.levipack。 - 已安裝到 LeviLauncher 中的模組,它會寫入 Android 日誌,並帶有用戶可以修改的設置。
下一步
- 生命週期的細節:Mod API。
- 更多帶標題、描述和取值範圍的設置:Config API。
- 遊戲中的按鈕和開關:Mod Menu API。觸摸和按鍵:Input API。
- 改變遊戲的行為:Hook API、Signature API 和 Patch API。
- SDK 的頭文件和宏:SDK 頭文件與宏。
- 包含 Mod Menu、按鈕和圖片的完整示例:LiteLDev/LeviLauncher-Android 中的
examples/full-cpp-mod。 - 從玩家角度看 LeviLauncher 中的原生模組:模組與集成。