LeviLamina 模組 API:數據、配置與多語言
LeviLamina 中 CompoundTag 舊的 getInt/getString 等取值函數不能用(曾被標記為 deprecated),現在應該怎麼讀取 NBT 值?
用下標或 at() 訪問,得到 CompoundTagVariant 後再取值:tag["key"] 或 tag.at("key")(維護者更推薦 operator[],可鏈式訪問嵌套,如 nbt["a"]["b"]["c"])。取值方式:數值類型用 tag["key"].get<int>() 或直接轉換 int{tag["key"]};字符串可直接轉換為 std::string const&(或 get_ref<std::string&>());要拿具體 Tag 類型用 tag["key"].get<IntTag>() / get<CompoundTag>() / get<ListTag>();判斷存在用 tag.contains("key") 或 contains("key", Tag::Type)。寫入可直接賦值:nbt["key"] = 1;、nbt["list"] = ListTag{1.0, 2.0};。更多用法參考 LeviLamina 倉庫測試代碼 src-test/server/TestNbt.cpp。
適用版本:LeviLamina 1.x 及以上(當前 v26.60.8)
使用 LeviLamina 的配置 API(ll::config::loadConfig / saveConfig)時,配置結構體有什麼要求?
配置結構體必須可反射(普通聚合結構體即可),並且必須包含一個整數類型的 version 字段(如 int version = 1;),否則不滿足 IsConfig 約束無法編譯。loadConfig 會比較文件中的 version 與結構體默認值:不一致或缺失時調用 updater(默認 defaultConfigUpdater:以當前結構體為底合併文件中的舊值)並返回 false,調用方可據此重新 saveConfig 寫回升級後的配置。如果不想要 version 字段,只能自己基於 ll::reflection::serialize/deserialize 另寫一套讀寫。
適用版本:LeviLamina 0.11 及以上至當前 v26.60.8
LeviLamina 中舊 LL2 的 PlayerInfoAPI / namedb(玩家名與 xuid/uuid 對應數據庫)在哪?能查詢離線玩家、遍歷全部玩家嗎?
對應功能叫 ll::service::PlayerInfo,頭文件 ll/api/service/PlayerInfo.h,基於 leveldb 存儲已知玩家的 UUID、XUID 與名稱。用 PlayerInfo::getInstance() 獲取實例,fromUuid / fromXuid / fromName 查詢單個玩家(返回 optional_ref<PlayerInfoEntry const>,離線玩家也可查到),entries() 返回生成器可遍歷全部記錄,erase(uuid) 刪除記錄。
腳本側 LSE 可用 data.getAllPlayerInfo() 獲取全部玩家信息。
適用版本:LeviLamina 0.9 及以上至當前版本
LeviLamina C++ mod 要保存玩家數據,有沒有內置數據庫?LiteLoaderBDS 時代自帶的 MySQL 庫(session.h)還在嗎?要用 MySQL 怎麼辦?
LeviLamina 不再內置舊 LiteLoaderBDS 的 MySQL/數據庫封裝(session.h)。簡單的本地存儲可用自帶的 ll::data::KeyValueDB(ll/api/data/KeyValueDB.h,基於 LevelDB);需要關係型數據庫時可在 mod 裡通過 xmake(add_requires)自行引入第三方庫,如 SQLite 或 MySQL 客戶端庫,並隨 mod 一起分發其動態庫。只有當網站、QQ 機器人等外部程序也要訪問數據時,才有必要上 MySQL 這類服務端數據庫。
腳本側 LSE 則自帶數據庫 API(DBSession,支持 SQLite 和 MySQL)。
適用版本:LeviLamina 0.x 至當前版本
LeviLamina C++ 插件開發中,有沒有類似 LLSE 那樣讀寫 JSON 的 API?
LeviLamina 提供配置文件 API(ll/api/Config.h 中的 ll::config::loadConfig / saveConfig,基於反射自動序列化,配置結構體需帶整數 version 字段)。如果只是普通的 JSON 讀寫或存數據,可以直接用 LeviLamina 依賴裡自帶的 nlohmann::json 庫(Config.h 本身就包含 nlohmann/json.hpp)。
LeviLamina 中如何獲取物品的 NBT,以及如何從 NBT 構造物品?
導出:ItemStack::save 現在需要一個 SaveContext,例如:
auto tag = item.save(*SaveContextFactory::createCloneSaveContext());它返回 std::unique_ptr<CompoundTag>,頭文件為 mc/world/item/SaveContextFactory.h。
從 NBT 構造:使用靜態函數 ItemStack::fromTag(CompoundTag const&)(或帶 ILevel& 的重載)。
BDS 原版已有完整的 NBT 讀寫接口,不再需要 LL2 那種層層封裝的 NBT API。以上適用於 save 需要 SaveContext 的 BDS 版本起。
LeviLamina 源碼中的 src/ll/api/reflection/Dispatcher.h 是做什麼用的?
ll::reflection::Dispatcher<Storage, Listener, CallInit> 是觀察者模式的封裝,主要給配置文件用:把配置字段包裝成 Dispatcher 後,每次對它賦值(包括反序列化讀取配置時)都會調用 listener.call(storage),從而在配置變化時自動執行邏輯;CallInit=true 時構造時也會調用一次。反射的序列化/反序列化對 Dispatcher 有專門支持。LeviLamina 自身配置就有用例:
ll::reflection::Dispatcher<bool, ForceEnableCheatCommands> forceEnableCheatCommands = true;適用版本:LeviLamina 1.x 及以上
LeviLamina 的 API 用的是哪個 JSON 庫?
用的是 nlohmann json(LL 的配置 API ll/api/Config.h 默認使用 nlohmann::ordered_json)。BDS 內部同時還有 rapidjson、jsoncpp。
適用版本:所有版本
LeviLamina 的 ll::config 讀取帶註釋的 JSON(jsonc)配置文件後,重啟服務器發現配置裡的註釋全部消失了,是不支持註釋嗎?
ll::config 基於 nlohmann::ordered_json:loadConfig 解析時會忽略註釋(能讀取帶註釋的文件),但不會保留註釋;常見寫法是 loadConfig 返回 false(版本不同/需更新)時再 saveConfig 回寫,或每次加載後都保存,此時由 nlohmann dump 生成的文件就不含註釋了。如需保留註釋,需要自己換用能保留註釋的 JSON/jsonc 庫或其他配置格式(如 TOML),或避免自動回寫。
適用版本:所有版本
LeviLamina 的反射/配置序列化中,可組合的 flag 枚舉(如 A|B)被序列化成空字符串,怎麼處理?
當前 LeviLamina 的反射已內置 flags 枚舉支持:序列化時,若 magic_enum 將其識別為 flags 枚舉,會用 magic_enum::enum_flags_name 輸出 "A|B",名稱為空則回退輸出底層整數;反序列化時同時嘗試 enum_cast 與 enum_flags_cast,支持 "A|B|C" 字符串。
關鍵是讓 magic_enum 把該枚舉識別為 flags:按 magic_enum 文檔特化 magic_enum::customize::enum_range<YourEnum>,並設置 static constexpr bool is_flags = true。
舊版本需要自己寫 format_as,用 enum_flags_name 並回退到 enum_integer。
適用版本:LeviLamina 26.60.x;舊版需自行實現 format_as
mod 中按數字物品 ID 判斷物品(如收納袋)可靠嗎?
不可靠,加載 Addons 後物品的數字 ID 可能變化。應使用物品類型名判斷,例如 item.getTypeName() == "minecraft:bundle",雖然字符串比較比 short 比較稍慢。
使用 ll::config::loadConfig 加載含 std::vector<int> 或 std::map 的配置結構體,修改 json 後讀到的值仍為空,是反射不支持嗎?
std::vector 等容器的反射是支持的(Deserialization.h 中走 ArrayLike 分支),std::map 等關聯容器也支持(Associative 分支),key 可以是字符串、enum(序列化為字符串)或特化了 ll::reflection::Serializer<T>::to_string / from_string 的類型。
讀到空值的真正原因是把 config 定義為頭文件裡的 static 全局變量:頭文件中的 static 變量在每個包含它的編譯單元裡各有一份副本,loadConfig 寫入的和別的文件讀取的不是同一個對象。應在頭文件用 extern 聲明、在一個 .cpp 中定義(或用 inline 變量)。
修改 config 結構後記得遞增 version。存儲自定義鍵值時,用 std::map<std::string, std::string> 之類的容器,而不是把 json 當 map 用。
適用版本:LeviLamina 0.10 及以上
原生 mod 中如何通過存檔數據讀取離線玩家的背包、末影箱、位置等信息,以及玩家名?
- 通過
ll::service::getDBStorage()讀取鍵"player_<uuid>"(DBHelpers::Category::All),得到一個CompoundTag,取其中的"ServerId"字符串。 - 以該 serverId 為 key、
DBHelpers::Category::Player從存檔數據庫讀出玩家 NBT(getCompoundTag),手動解析其中的背包、末影箱、位置等字段。
玩家名不在該 NBT 中,可用 ll::service::PlayerInfo::getInstance().fromUuid(uuid) 得到 name/xuid。可參考 LSE 中 getPlayerNbt / setPlayerNbt 的實現。
適用版本:LeviLamina 當前版本
在 LeviLamina C++ mod 中如何獲取 DBStorage 對象,而不必自己 hook 函數去拿?
通過 Level 拿到 LevelStorage:ll::service::getLevel()->getLevelStorage()。服務端上它的實際類型就是 DBStorage(class DBStorage : public LevelStorage),可以 static_cast<DBStorage&>(level.getLevelStorage()) 後使用。不推薦依賴第三方庫(如 GMLIB)hook 緩存的 DBStorage*。
適用版本:LeviLamina 1.x 及以上
在 LeviLamina C++ mod 中,用 std::format 拼接 SNBT 字符串(如 {Findable:0b,Items:[],id:Chest,isMovable:1b,x:8,y:66,z:-41})後調用 CompoundTag::fromSnbt,結果返回空,為什麼?
std::format / fmt::format 中的大括號是佔位符,字面的 { } 必須轉義成 {{ }},否則拼出來的 SNBT 不合法,fromSnbt 解析失敗返回空(fromSnbt 返回 optional/Expected,應檢查結果)。
建議直接用原始字符串字面量 R"(...)" 書寫 SNBT,或直接用 CompoundTag 的 API 按鍵值構造 NBT,不要用 format 拼 SNBT。NBT 用法可參考 LeviLamina 倉庫 src-test/server/TestNbt.cpp。toSnbt 支持多種 SnbtFormat 輸出選項(如 PrettyFilePrint、Jsonify 等)。
適用版本:當前所有 LeviLamina 版本
在 LeviLamina C++ mod 裡,ItemStack 指針怎麼轉成 ItemStackBase?需要 dynamic_cast 嗎?
ItemStack 公有繼承自 ItemStackBase,子類轉父類不需要 dynamic_cast(BDS 也沒有 RTTI):解引用後直接當 ItemStackBase& 用即可(隱式向上轉換),或顯式寫 static_cast<ItemStackBase&>(*item)。要複製物品可以用 ItemStack::clone() const。
適用版本:當前所有 LeviLamina 版本
在 LeviLamina C++ 中如何優雅地將 NBT(CompoundTag)與 JSON 互相轉換?
兩者無法完好無損地互轉:JSON 沒有 byte/short/int/float 等類型區分,NBT 字符串可以是任意二進制而 JSON 有限制。
若不在意這些,可用 toSnbt(SnbtFormat::Jsonify) 輸出 JSON 兼容格式(鍵加引號、類型信息以註釋形式保留),再用 JSON 庫解析;JSON 無法表示的二進制字符串會被轉成 base64(帶 /*BASE64*/ 標記)。反向可用 CompoundTag::fromSnbt 解析。
更推薦直接存 NBT,需要可視化時用 SNBT。
適用版本:當前所有 LeviLamina 版本
想往 BDS 存檔的 LevelDB 中寫入自定義數據(如地圖數字水印)並且不被 BDS 清理,直接用 Node.js 通用 leveldb 庫寫入後數據消失,應該怎麼做?
BDS 的 LevelDB 是 Mojang 修改過的版本(帶自有壓縮格式),通用 leveldb 庫默認不支持,外部寫入不可靠;BDS 本身不會主動刪除未知 key 的數據。在 mod 中可以用 LevelStorage 接口(mc/world/level/storage/LevelStorage.h)寫入自定義 key,例如 saveData(std::string const& key, std::string&& data, DBHelpers::Category category) 或 saveData(key, CompoundTag const&, category),讀取用 loadData/getCompoundTag;DBHelpers::Category 參數基本不影響實際存儲,真正起作用的是 key。若只是做水印,更穩妥的原版方式是給隱蔽位置的容器方塊或生物命名,名稱會保存在 NBT 中。
適用版本:當前 LeviLamina 版本