跳到正文
本頁目錄

LeviLamina 模組 API:其他 API

LeviLamina 原生 C++ mod 如何實現多語言(i18n):語言文件放哪、如何加載、如何使用 _tr?

做法與 LeviLamina 本體一致:代碼裡硬編碼英文(作為 key),再提供各語言的 json 翻譯文件,隨 mod 一起分發到 mod 目錄下的 lang/(如 lang/zh_CN.json,內容如 {"hello {}": "你好 {}"})。在 mod 的 load() 中調用 ll::i18n::getInstance().load(getSelf().getLangDir()) 加載(路徑為目錄時讀取其中所有 .json,文件名即語言代碼;也可傳單個 json 文件,此時頂層鍵為語言代碼)。使用:

cpp
#include "ll/api/i18n/I18n.h"
using namespace ll::i18n_literals;
int a = 114514;
"hello {}"_tr(a);

當默認語言(LeviLamina 配置 language,默認 "system" 跟隨系統)為 zh_CN 且已加載 zh_CN 翻譯時輸出“你好 114514”,未找到對應翻譯時原樣輸出“hello 114514”;也可用 "hello {}"_trl("zh_CN", a) 顯式指定語言。I18n.h 中還提供 LL_I18N_COLLECT_STRINGS 宏用於收集代碼裡所有 _tr 字符串,便於生成翻譯模板。打包時需確保 lang 目錄被一起復制到產物中:當前模板使用 levibuildscript 的 modpacker 規則(舊模板的 after_build.lua 已移除),而 modpacker 只會把 dll、pdb 和 manifest.json 複製到 bin/<modName>/,不會複製 lang 目錄,需要自己在 xmake.lua 里加 after_build 用 os.cp 複製,或發佈時手動放入 mod 目錄。

適用版本:LeviLamina 1.x 及以上(當前 v26.60.8)

LeviLamina 頭文件裡有些 enum 是空的、有些結構體(例如 getIconInfo 返回的 ResolvedItemIconInfo)只有構造函數沒有成員,正常嗎?需要自己補嗎?

正常。mc 頭文件由逆向自動生成。現在大部分類/結構體已經生成了成員佈局:已知類型的成員用 ::ll::TypedStorage<对齐, 大小, 类型> 聲明(如 ResolvedItemIconInfo 已有 mIconName、mIconFrame、mIconType 等完整成員),類型未知的用 ::ll::UntypedStorage<对齐, 大小>,可用 .as<T>() 按實際類型訪問;但仍有部分 enum 沒有枚舉值、部分類為空類({})。

遇到這些情況需要自己補全定義,可對照其他實現(如 Nukkit 系項目、協議文檔)或自行逆向。

適用版本:當前所有 LeviLamina 版本

LeviLamina 的 API 對裸指針有什麼約定?Player* 之類還能用嗎?可空的參數/返回值應該用什麼?

LeviLamina 自身 API 的輸入/返回不使用裸指針:原先的 Player* 等改為 Player& 等引用;可能為空的非擁有引用使用 optional_ref<T>(頭文件 mc/deps/core/utility/optional_ref.h,已由 mc/_HeaderOutputPredefine.h 引入,例如 ll::service::getLevel() 返回 optional_ref<Level>、PlayerInfo::fromXuid 返回 optional_ref<PlayerInfoEntry const>);由 LL 管理所有權的對象使用 std::shared_ptr / std::unique_ptr 等智能指針。

注意 mc 下逆向生成的原版函數簽名仍可能帶裸指針。

適用版本:LeviLamina 0.6 及以上至當前版本

C++ mod 中如何自己構造一個 ActorUniqueID?

ActorUniqueID 是隻有一個成員 int64 rawID 的聚合結構體,直接聚合初始化即可:auto id = ActorUniqueID{123};。ActorUniqueID{} 會把 rawID 置 0;注意 ActorUniqueID id; 不初始化 rawID。需要無效 ID 時可用 ActorUniqueID::INVALID_ID()。

C++ mod 開發中,如何從 ItemActor 得到 Actor?能否用 dynamic_cast?

ItemActor 公有繼承自 Actor,ItemActor* 本身就可以直接當作 Actor* 使用(隱式向上轉換),不需要額外轉換。BDS 沒有 RTTI,dynamic_cast 不能用。同理 ItemStack 繼承自 ItemStackBase,需要 ItemStackBase 的 API 直接傳 ItemStack 即可。

C++ 的 switch 不能直接對 std::string 做分支,開發 LeviLamina mod 時怎樣避免寫一堆 if-else?

先把字符串哈希成整數再 switch。LeviLamina 自帶 #include "ll/api/utils/HashUtils.h",其中的 ll::hash_utils::doHash(std::string_view) 是 constexpr;字面量運算符 "xxx"_h 是 consteval(位於命名空間 ll::literals::hash_literals),可以直接寫在 case 標籤裡:

cpp
using namespace ll::literals;
switch (ll::hash_utils::doHash(str)) {
case "foo"_h: ...; break;
case "bar"_h: ...; break;
}

標準庫的 std::hash<std::string>{}(str) 不是 constexpr,不能用在 case 標籤裡。

適用版本:LeviLamina 0.8 及以上

LL2(LiteLoaderBDS)中的 LLAPI(如 Block 相關接口、各類事件、NBT)在 LeviLamina 中還有嗎?怎麼找對應接口?

LL2 的 API 在 LeviLamina 中並沒有一一保留,而是重寫/直接使用 BDS 原生類(LSE 就是基於 LeviLamina 移植的),命名方式與 LL2 不同,可查 API 文檔 https://levimc.org/LeviLamina/api/(例如 Block 類);方塊可通過 BDS 自身的方塊註冊表獲取。LeviLamina 只提供基礎事件(見 src/ll/api/event),需要 LL2 那樣的全部事件可參考 LegacyScriptEngine 中整理好的 hook 實現(src/lse/events/*Hooks.cpp)。不建議照抄 LL2 代碼,參考 LSE 的實現更好。

LeviLamina 頭文件中有些函數的參數沒有名字(IDE 提示為空或只有一半參數名),是什麼原因?

這些通常是新版本 BDS 新增、尚未分析出參數含義的函數,頭文件為自動生成,所以沒有參數名。可以自己驗證參數作用後向 LeviLamina 反饋(提 issue),被採納後會加入自動生成數據,後續版本的頭文件就會帶上參數名。

適用版本:所有版本。未能從源碼或文檔中直接證實,僅供參考。

LeviLamina 頭文件中標記為 LLNDAPI 的函數是什麼意思?返回的 ll::Expected<> 有什麼用?

LLNDAPI 即 [[nodiscard]] LLAPI,表示返回值不應被丟棄。像 ll::i18n::load 這類返回 ll::Expected<>(Expected<void>)的函數,應檢查返回值,出錯時可通過 .error().log(logger) 輸出錯誤信息,例如:

cpp
if (auto res = ll::i18n::load(path); !res) res.error().log(getSelf().getLogger());

LeviLamina 頭文件中缺少需要的函數/符號/虛表,或者 mUnk 成員的類型不知道,該怎麼辦?

mUnk 成員的類型只能靠猜或用 IDA 等工具逆向分析。標記為 MCNAPI 的函數是尚未導出、不可調用的;缺少函數、符號或需要成員類型時,到 https://github.com/LiteLDev/mcapi-requests/issues/new 提交請求(附上缺失的符號)。提交前可先在在線文檔/最新頭文件中確認是否已恢復為 MCAPI。

LeviLamina 有沒有封裝好的獲取系統時間的函數?

有。頭文件 ll/api/utils/SystemUtils.h 中的 ll::sys_utils::getLocalTime()(命名空間 ll::inline utils::sys_utils,所以可直接寫 ll::sys_utils::)返回 ll::data::TmWithMs(std::tm + 毫秒),不需要自己封裝。當前版本仍存在該函數。

適用版本:LeviLamina 0.13 及以上

LeviLamina 的 i18n 翻譯字符串格式化語法是什麼?

使用 fmt::format 語法({} 佔位符、{0} 位置參數、具名參數、格式說明符等),例如 "key"_tr(arg1, arg2),翻譯文本中用 {} / {0} 引用參數。

適用版本:所有版本

在 LeviLamina 原生 mod 中如何計算兩個顏色的相似度(例如為地圖畫/像素畫匹配方塊顏色)?

LeviLamina 頭文件中的 mce::Color(現位於 src/mc/deps/core/math/Color.h)提供了 deltaE76 / deltaE94 / deltaE00 以及 distanceTo(等價於 deltaE00)等函數,會先把 sRGB 轉到線性、XYZ、Lab 色彩空間再計算色差,可直接調用,也可照著實現移植到其他語言。

做地圖畫時要取方塊的地圖色而不是方塊本身顏色:BlockType 有 getMapColor(BlockSource&, BlockPos const&, Block const&) 虛函數和 mMapColor 成員,可遍歷所有已註冊方塊獲取。取到的 8 位十六進制顏色最後兩位是透明度(ff),轉 RGB 時去掉。

適用版本:LeviLamina 當前版本

在 LeviLamina 頭文件中,斧頭物品對應的類是哪個?

斧頭是 HatchetItem(mc/world/item/HatchetItem.h);它繼承自 DiggerItem,搜索 DiggerItem 可以找到所有挖掘工具類物品。

適用版本:LeviLamina 當前版本

LeviLamina 新版頭文件中 mc/deps/json/JsonHelpers.h 找不到了,JsonHelpers 現在應該 include 哪個路徑?

改為 #include "mc/util/JsonHelpers.h"。頭文件位置變化時可直接在 LeviLamina 頭文件中搜索類名。

適用版本:LeviLamina 1.0.0 及以上

開發 LeviLamina C++ mod 時如何方便地讀取 Windows 註冊表?

可以用 xmake 引入第三方庫 WinReg(https://github.com/GiovanniDicanio/WinReg):在 xmake.lua 中 add_requires("winreg"),在 target 裡 add_packages("winreg"),代碼中 #include <WinReg/WinReg.hpp> 使用 winreg::RegKey,比直接調用 Win32 API 簡潔。

適用版本:當前所有版本(Windows 平臺)