LeviLamina 模組 API:玩家與實體
LeviLamina C++ mod 中按玩家存儲數據/唯一標識玩家,用 uuid、xuid 還是 realName 作為鍵?為什麼 LegacyMoney 用 xuid?
推薦用 UUID(Player::getUuid() 返回 mce::UUID)。開啟正版驗證(online-mode)時 UUID 固定不變、跨存檔一致;關閉正版驗證時 UUID 會隨機,但此時 xuid 本身也不可靠(離線時可能為空)。mce::UUID 由兩個 uint64 組成,比較和哈希比 xuid 字符串更快,可直接作 unordered_map 的鍵。不要用 realName(可改名)。LegacyMoney 用 xuid 是歷史遺留(legacy 兼容);已用 xuid 存數據的插件在開啟 online-mode 時可以不改。需要在 uuid 與 xuid 之間互查(如讀取 LegacyMoney 數據庫)時,可用 ll::service::PlayerInfo 的 fromUuid()/fromXuid()/fromName()。
原生 mod 如何實現虛擬容器/自定義箱子 GUI(如 Invsee 查看背包、快捷打開潛影盒)?LeviLamina 有現成接口嗎?
LeviLamina 沒有封裝虛擬容器接口,需要自己實現,常見思路:
- 最簡單:在玩家附近真實放置容器方塊並打開,關閉後移除。
- 全發包:用
UpdateSubChunkBlocksPacket發送假箱子方塊、BlockActorDataPacket更新其方塊實體 NBT、ContainerOpenPacket讓玩家打開界面,然後自行處理容器內容更新與所有物品請求(ItemStackRequest),離線玩家還需自己讀寫 NBT。 - 半發包:在服務端構造一個容器對象(
Container是抽象類,需用合適的派生類)並讓服務端認為玩家打開了它,同時給客戶端發包偽造方塊並打開,物品顯示/移動交給原版邏輯,只需負責打開和保存(需深入理解 MC 容器機制)。
客戶端一定會看到一個“假方塊”,這是原版客戶端的限制,除非客戶端也裝模組。也可以使用第三方前置(如 GMLIB)提供的虛擬容器 API。
適用版本:當前所有 LeviLamina 版本(服務端)
C++ mod 中如何獲取 ServerPlayer?Player 怎麼轉 ServerPlayer(dynamic_cast 不可用),ServerNetworkHandler::getServerPlayer 沒了怎麼辦?
如果只考慮服務端,Player 可直接 static_cast<ServerPlayer&>(player)。如果 mod 也會運行在客戶端(target_type=client),需要先判斷(如 player.isClientSide())再轉換。
在 ServerNetworkHandler 中按 NetworkIdentifier 獲取玩家時,用 _getServerPlayer(source, subId)(BDS 1.21.60 起 getServerPlayer 封裝已沒有)。
在 hook ServerNetworkHandler 繼承自 NetEventCallback 的虛函數(如各 handle(NetworkIdentifier const&, XxxPacket const&))時,hook 裡的 this 實際指向 NetEventCallback 子對象而不是 ServerNetworkHandler 起始地址,不要手動算偏移,用 hook 提供的 thisFor<NetEventCallback>() 得到正確的 ServerNetworkHandler*,再調用 _getServerPlayer(LeviLamina 自身的 PlayerJoinEvent / PlayerChatEvent 就是 thisFor<NetEventCallback>()->_getServerPlayer(identifier, packet.mSenderSubId))。
適用版本:BDS 1.21.60 及以上 / 當前 LeviLamina
C++ mod 中想修改玩家血量/最大生命值,但參考舊寫法調用的原版函數(如 AttributeHelper::setMaxValue 等)在新版 LeviLamina 中被標成 MCNAPI,編譯報警告/錯誤,怎麼辦?
MCNAPI 表示該原版函數在當前 BDS 中沒有可鏈接的符號(通常已被內聯),LeviLamina 頭文件裡把它標成 [[deprecated("This API is not available. Open an issue if you need it.")]],不能調用。做法:
- 改用其他可用的 API。修改屬性值可以用 LeviLamina 自己實現的
BaseAttributeMap輔助函數,例如actor.getAttributes()->setMaxValue(SharedAttributes::HEALTH(), value);、setCurrentValue(...)、setDefaultValue(...)(SharedAttributes::HEALTH()是靜態函數,返回血量Attribute);也可以用actor.getMutableAttribute(SharedAttributes::HEALTH())拿到屬性實例後直接改成員。 - 確實需要的原版函數,到 LeviLamina 提 issue 請求實現(不提通常不會加)。
- 也可以自己用特徵碼/偏移處理。
適用版本:LeviLamina 1.2.0 及以上(當前 v26.60.x 仍適用)
26.40 起 AddPlayerPacket 裡的 actorUniqueId 字段沒了,做假玩家/靈魂出竅(freecam)的 mod 該怎麼設置玩家的 ActorUniqueID?
AddPlayerPacket 裡原來的 AUID 本就是冗餘字段,客戶端實際使用的是能力數據裡的那個:設置 AddPlayerPacketPayload::mAbilitiesData(SerializedAbilitiesData)中的 ::ll::TypedStorage<8, 8, ::ActorUniqueID> mTargetPlayer 即可(見 LeviLamina src/mc/world/actor/SerializedAbilitiesData.h)。LeviLamina 26.40.5 起也為 AddPlayerPacket 提供了構造函數可直接使用。
適用版本:BDS 26.40 及以上 / LeviLamina 26.40 及以上(當前 26.60 仍適用)
BDS 1.21.132 起 ConnectionRequest 的 mLegacyMultiplayerToken 沒了,mod 如何獲取玩家 xuid、名稱等身份信息?
從 ServerNetworkHandler 獲取:其 mClients 中每個 Client 保存了 mPrimaryPlayerInfo(PlayerAuthenticationInfo)及 mSubClientPlayerInfo;也可以使用 ServerNetworkHandler 中帶 PlayerAuthenticationInfo 參數或返回值的函數。BDS 已經解析過 login chain,不需要自己從頭解析。ConnectionRequest 的驗證相關邏輯也在 ServerNetworkHandler 中。
適用版本:BDS 1.21.132 及以後對應的 LeviLamina(當前 v26.60.8 仍適用)
BDS 中玩家在打開工作臺等 UI 放入物品後強退會導致刷物品,原因是什麼?用 LeviLamina mod 如何修復?
原因:玩家數據讀取(Player::readAdditionalSaveData)時會嘗試把 UI 槽位(UIItems)裡的物品 add 回背包,失敗後不回溯,轉而嘗試 drop 物品,但此時玩家所在區塊尚未加載,drop 失敗,導致清除 UI 物品的代碼不觸發,從而複製物品。
修復思路:
- hook
Player::add(虛函數需用$add),但不要全局改寫,只在readAdditionalSaveData的調用上下文中修改其行為。 - 在
readAdditionalSaveData時先加載玩家所在區塊(例如ChunkSource::getOrLoadChunk),使 drop 能正常執行。
適用版本:依賴 BDS 原版行為,未確認當前 BDS 是否已修復。未能從源碼或文檔中直接證實,僅供參考。
BDS 中玩家相關類(SimulatedPlayer、ServerPlayer、Player 等)的繼承關係是怎樣的?
繼承鏈是 SimulatedPlayer → ServerPlayer → Player → Mob → Actor(Player 和 Actor 之間還有 Mob 這一層,Mob 是帶 AI 邏輯的生物,例如 aiStep)。客戶端對應的是 LocalPlayer(LocalPlayer → Player)。
C++ mod 中 ContainerID 是枚舉嗎?為什麼背包等容器的 ID 不固定?
ContainerID 是 enum class ContainerID : schar,但只給部分容器定義了固定值:None=-1、Inventory=0、Offhand=119、Armor=120、SelectionSlots=122、PlayerOnlyUi=124、Registry=125。其餘打開的容器界面(箱子、工作臺等)使用 First(1) ~ Last(100) 範圍內自增分配的 ID,所以不固定。
C++ 代碼 player.getOrCreateUniqueID() 返回 ActorUniqueID,這個 API 在哪裡有文檔?
這是 MC 本身的原生 C++ API,沒有官方文檔。要到 LeviLamina 提供的頭文件裡找:該函數聲明在 mc/world/actor/Actor.h(ActorUniqueID const& getOrCreateUniqueID() const;),Player 繼承自 Actor。平時直接在頭文件中搜索,或者依靠 IDE 自動補全。
LeviLamina / LSE 中有沒有讓玩家丟棄(丟出)物品的方法?
C++ mod 可以直接使用 Player::drop(ItemStack const& item, bool randomly)。LSE 腳本沒有原生的丟出物品接口,只能變通:先清除背包中的物品,再在玩家位置生成掉落物;或者使用第三方的 GMLIB-LegacyRemoteCallApi(通過 RemoteCall 導出了相關接口)。一般建議把需要的功能寫成 C++ mod,再通過 LegacyRemoteCall 暴露給 JS 插件。
LeviLamina C++ 插件中如何獲取玩家 UUID 的字符串形式?
使用 player.getUuid().asString():getUuid() 返回 mce::UUID const&,再調用 asString() 轉為字符串(mce::UUID 也支持顯式轉換 std::string(uuid))。
LeviLamina 中如何通過 xuid 獲取玩家對象?直接調用 Level::getPlayerByXuid 報錯/內存錯誤。
getPlayerByXuid 是 Level 的成員(虛)函數,不是靜態函數,不能自己聲明/構造 Level。應通過 LL 服務獲取全局 Level:ll::service::getLevel() 返回 optional_ref<Level>,需判空,例如:
if (auto level = ll::service::getLevel()) {
Player* p = level->getPlayerByXuid(xuid);
if (p) {
// ...
}
}適用版本:所有版本
LeviLamina 插件中如何實現生存模式下的飛行(類似生存飛行插件)?
調用 LeviLamina 提供的 Player::setAbility(AbilitiesIndex::MayFly, true)(關閉時傳 false)。當前實現中 setAbility 內部已經會同步 Canfly 標誌並向該玩家發送 UpdateAbilitiesPacket 和 UpdateAdventureSettingsPacket,無需再手動發包。如果是直接改 LayeredAbilities,則需要自己發送 UpdateAbilitiesPacket 才能在客戶端生效。LSE 中也有對應封裝。
LeviLamina 裡有沒有類似 LL2 的 giveItem 給玩家物品的接口?用 Player::add 加物品後背包會不會自動刷新?
LeviLamina 不提供 LL2 那種 giveItem 封裝,直接使用 Mojang 自帶的 API。Player::add(ItemStack&) 可以用,但不會刷新客戶端背包,加完後需要調用 refreshInventory()(Mob 上的 LL 擴展方法)讓客戶端同步。
更簡單的做法是直接用 LeviLamina 擴展的 Player::addAndRefresh(ItemStack& item),它內部就是 add 後再 refreshInventory,返回值表示物品是否全部給出(不反映刷新是否成功)。不建議照搬 LL2 的實現。
適用版本:LeviLamina 1.x 及以上(當前 v26.60.8 仍適用)
寫 native 隱身(vanish)mod 時,只攔截 AddActor 包為什麼已經看見該玩家的人仍然能看到他?
攔截 AddActor(玩家為 AddPlayer)包只能阻止之後的生成,已經加載了該玩家的客戶端不會自動移除該實體,需要主動向這些玩家發送 RemoveActorPacket 才能立即隱藏。可藉助 iListenAttentively 提供的事件減少手寫 hook。
未能從源碼或文檔中直接證實,僅供參考。
在 LeviLamina mod 中如何獲取實體的主手和副手物品?只找到了獲取護甲的函數。
在當前 LeviLamina 頭文件中,主手物品用 Actor::getCarriedItem()(虛函數),副手物品用 Actor::getOffhandSlot(),二者與 getArmor 一樣定義在 Actor 類中;Mob 類另有 getAllHandEquipment() 可一次取得所有手持裝備。查找時可在 Actor.h / Mob.h 中不區分大小寫搜索 carried / offhand。
適用版本:LeviLamina 當前版本
在 LeviLamina 中如何給玩家播放聲音?找不到能直接用的播放聲音數據包怎麼辦?
簡單做法是使用 Level(ILevel)上的 playSound 系列函數(例如 playSound(LevelSoundEvent, Vec3 const&, float volume, float pitch) 或 playSound(PlaySoundOptions const&))。
若要只發給某個玩家,可直接構造數據包發送,例如 PlaySoundPacket(...).sendTo(player);(Packet 自帶 sendTo(Player const&))。Packet 臨時對象按 RAII 自動析構,無需手動釋放。也可參考原版 playsound 指令的實現。
適用版本:LeviLamina 當前版本
在 LeviLamina 原生 mod 中,如何從服務端控制玩家快捷欄當前選中的格子(例如點擊第 9 格後切到第 1 格)?
BDS 的 Player 類有 setSelectedSlot(int slot) 函數(返回該格的 ItemStack const&),可設置玩家當前選中的快捷欄格子,頭文件為 mc/world/actor/player/Player.h。選中格由服務端發包同步給客戶端,因此 mod 可以實現。
適用版本:LeviLamina 當前版本
開發 LeviLamina mod 時,如何在玩家進服時異步執行檢查(如查詢雲黑名單)且不阻塞服務器,檢查通過後再放行?
BDS 本身有異步進服回調機制。在最新版本中,它位於 AsyncJoinTaskManager(ServerNetworkHandler::mAsyncJoinTaskManager):registerAsyncJoinCallback(callback),回調參數為 (NetworkIdentifier const&, PlayerAuthenticationInfo const&, SubClientId, std::shared_ptr<AsyncVerdictPromise>),由 handleAsyncJoinCallbacks 彙總結果,判定結果類型為 AsyncJoinAllow / AsyncJoinDeny。這些函數是 MCNAPI,需要自行定位/補全。Script API 中對應的是 AsyncPlayerJoinBeforeEvent。另一種做法是攔截數據包:先不向玩家發送 StartGamePacket,拿到檢查結果後再發送,未通過就發送踢出包。
適用版本:LeviLamina 當前版本
開發 mod 時如何判斷玩家是觸屏還是鍵鼠,以決定發表單還是容器 UI?
不要按操作系統判斷,應按玩家當前的輸入方式判斷:PlayerAuthInputPacket 的負載(PlayerAuthInputPacketPayload)裡有 mInputMode 字段(枚舉 InputMode:Mouse=1、Touch=2、GamePad=3),可以監聽/hook 該包取得;登錄時的 ConnectionRequest 中也帶有 currentInputMode。鍵鼠(Mouse)發容器界面,觸屏(Touch)發表單。注意玩家可以中途切換輸入方式,應以最近一次收到的值為準。
玩家在背包裡拖動或點擊物品是由哪個數據包控制的?怎麼知道操作的是哪個物品?
由 ItemStackRequestPacket(裡面是 ItemStackRequestBatch)控制,具體操作放在 ItemStackRequestAction 裡(有 take/place/swap/drop 等多種 ItemStackRequestActionType),物品堆棧通過唯一的 networkId 區分。PC 端點擊物品就會發包(物品從背包槽移到 CURSOR 光標槽),手機端只點擊不會發包。如果不想自己解析包,可以用 iListenAttentively 提供的 PlayerRequestItemActionBeforeEvent。
適用版本:當前 BDS / LeviLamina 版本
用 C++(LeviLamina mod)怎麼給背包裡指定物品設置自定義 lore?
拿到 ItemStack 後,調用 item.setCustomLore(std::vector<std::string>{...}) 設置 lore,調用 item.clearCustomLore() 清除,讀取用 getCustomLore()。可以參考 LSE 的實現:https://github.com/LiteLDev/LegacyScriptEngine/blob/develop/src/legacy/api/ItemAPI.cpp 中的 ItemClass::setLore。改完後調用 player.refreshInventory() 刷新玩家背包,客戶端才會顯示出來。
適用版本:當前 LeviLamina 版本