跳到正文
本頁目錄

LeviLamina 模組 API:世界、方塊與物品

LeviLamina C++ mod 中如何獲取 BlockSource(替代 LL2 的 block.getBlockSource()),並按維度 ID + BlockPos 獲取方塊/方塊實體?

每個維度對應一個 BlockSource。已有玩家/實體時直接從 Actor 取:actor.getDimensionBlockSource()(或 actor.getDimension().getBlockSourceFromMainChunkSource(),getDimension() 返回引用,用 . 調用)。只有維度 ID 時從 Level 取維度:Level::getDimension(dimId) 返回 WeakRef<Dimension>,需要先 lock() 並判空(維度未加載時為空):

cpp
if (auto dim = ll::service::getLevel()->getDimension(dimId).lock()) {
    auto& bs = dim->getBlockSourceFromMainChunkSource();
    Block const& block = bs.getBlock(pos);
    BlockActor* be = bs.getBlockEntity(pos);
}

不想判空可改用 Level::getOrCreateDimension(dimId)(同樣返回 WeakRef,需要 lock())。獲取 BlockActor 後先判空,用 getType() 判斷類型,向下轉型用 static_cast 而不是 reinterpret_cast。儘量走原版途徑獲取對象,少依賴 ll::service 的全局接口;也不建議照抄 LSE 中的歷史遺留寫法。

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

基岩版磁石指針(lodestone compass)物品中只存了追蹤 ID(trackingId),沒有座標,C++ mod 中如何獲取它指向的磁石座標?

基岩版不像 Java 版把座標寫進指針 NBT,而是存一個 PositionTrackingId,座標由位置追蹤數據庫 PositionTrackingDB 管理。服務端可通過 level.getPositionTrackerDBServer() 拿到 PositionTrackingDB::PositionTrackingDBServer,再調用 findTracker(id, &record) 查詢,得到的 PositionTrackingDB::TrackingRecord 中 mPosition(BlockPos)和 mDimensionType 即為磁石座標與維度。相關頭文件在 LeviLamina 的 src/mc/world/level/position_trackingdb/ 下。注意 LodestoneCompassItem::getPositionTrackingId 當前為 MCNAPI(不可用),需要自行從物品 NBT 讀取追蹤 ID,或到 mcapi-requests 申請導出。

適用版本:LeviLamina 當前版本(服務端)

新版 BDS 中 Block::isSolid 沒了(被內聯),C++ mod 裡該怎麼判斷方塊是否為實心(solid)?

可以直接讀取方塊緩存的組件數據:block.mCachedComponentData->mIsSolid(LegacyScriptEngine 也是這樣實現的);也可以讀取方塊類型上的 block.getBlockType().mSolid。當前 LeviLamina 中 Block::_isSolid() 已重新導出為 MCAPI,也可直接調用。

由於 Mojang 每個版本改編譯選項,總會有函數被內聯或恢復;遇到被內聯的函數,可以先去 LSE 源碼裡搜一下是否已有實現可參考。

適用版本:LeviLamina 26.60.x

BDS 1.21.100 / LeviLamina 1.5 起 BlockLegacy 類找不到了,改成什麼了?

Mojang 將 BlockLegacy 改名為 BlockType,代碼中改用 BlockType(頭文件 mc/world/level/block/BlockType.h)即可。注意不要與枚舉 SharedTypes::v1_21_20::JigsawStructure::ProcessorRule::BlockType(mc/deps/shared_types/v1_21_20/structure/BlockType.h)混淆。

適用版本:LeviLamina 1.5(BDS 1.21.100)及以上

BlockSource::setBlock 的 updateFlags 參數現在只是 int,以前的 enum BlockUpdateFlags 完整定義在哪?

當前 LeviLamina 的 BDS 頭文件中沒有 BlockUpdateFlag(s) 枚舉,setBlock 等函數的 updateFlags 只是 int,沒有官方完整定義。社區代碼中常用 3(相當於舊的 BlockUpdateFlag::All,即通知鄰居 + 同步網絡)。

適用版本:LeviLamina 26.x

C++ mod 中判斷一個實體是否為怪物(希望對 addon 自定義生物也生效),應該用 hasCategory 還是 hasFamily?

推薦用 Actor::hasFamily(HashedString const&) 判斷 family:怪物為 "monster",動物為 "animal",非生物為 "inanimate"。family 來自實體定義中的 minecraft:type_family,因此 addon 生物只要作者在 type_family 中加了 monster 等就能被識別;若沒加則無法通過此方式攔截。LSE 插件可藉助 LRCA 等方式判斷。

C++ mod 中如何判斷某個區塊是否已加載?

使用 ChunkSource 上的 std::shared_ptr<LevelChunk> getAvailableChunk(ChunkPos const& cp)(LeviLamina 以 LLAPI 實現),返回 nullptr 即表示該區塊未加載或尚未加載完成(狀態未到 ChunkState::Loaded)。ChunkSource 沒有 getAvailableChunkAt,按方塊座標查詢時先轉換:region.getChunkSource().getAvailableChunk(ChunkPos{blockPos})。也可以用 BlockSource::hasChunk(ChunkPos const&, bool serverSideOnly) 或 BlockSource::getChunkAt(BlockPos const&)(返回 LevelChunk*)判斷。

適用版本:LeviLamina 26.60.x

C++ mod 開發中如何判斷一個箱子能否被打開?在哪個類裡找對應函數?

在 ChestBlockActor 類(mc/world/level/block/actor/ChestBlockActor.h)中。當前頭文件裡對應的函數是 virtual bool _canOpenThis(BlockSource& region) const;(例如頂部有遮擋時返回 false)。查找時在頭文件中搜索英文函數名,注意不要找錯類。

適用版本:LeviLamina 26.60.x

C++ mod 裡怎麼從 Explosion 類拿到爆炸源實體?mSourceID 每次爆炸都不一樣。

Explosion::mSourceID 就是爆炸源實體的 ActorUniqueID,不同爆炸源對應不同的值是正常的。它是 ll::TypedStorage<8, 8, ActorUniqueID>,取值用 *explosion.mSourceID 或 .get(),再交給 Level::fetchEntity 取實體:Actor* src = level.fetchEntity(*explosion.mSourceID, false);(第二個參數 getRemoved 表示是否也返回已移除的實體)。返回 nullptr 說明沒有源實體或該實體已不存在。

適用版本:LeviLamina 26.60.x

C++ 中 Vec3 座標是單精度還是雙精度?

單精度。LeviLamina 中的 Vec3 繼承自 ll::math::floatN3<Vec3>,分量是 float。基岩版座標用 float,所以座標很遠(如百萬格外)時會丟失精度;Java 版用的是 double。

LeviLamina C++ 中如何獲取世界重生點(world spawn)?獲取到的 Y 值為 32767 或 X/Z 為 -2147483648 是怎麼回事?

世界重生點只有一個且在主世界,不屬於 Dimension;它保存在 level.dat(LevelData)中。當前版本的頭文件裡可以通過 ll::service::getLevel()->getSharedSpawnPos() 獲取(返回 BlockPos const&,LSE 創建模擬玩家時也是用它取出生點)。

如果沒用過 /setworldspawn,Y 通常是 32767;存檔尚未完成加載時 X、Z 可能是 -2147483648(INT_MIN)。BDS 自己使用時會自動尋找安全地面,所以 Y 不影響原版出生;自己拿來傳送等用途時需要自行尋找地面高度。DimensionConversionData 裡的 spawnpoint 是給末地傳送門用的,不是世界出生點。

適用版本:當前版本(服務端)

LeviLamina C++ 插件能否獲取未加載區塊中某座標的方塊類型?

區塊未加載時拿不到,需要先把區塊加載。可以用 ChunkSource 的 getOrLoadChunk(ChunkPos const&, ChunkSource::LoadMode, bool readOnly) 手動加載,但有用戶實測,手動加載的區塊若尚未生成地形,取到的方塊全是 air;需要地形已生成的數據時,可用常加載區(tickingarea)或讓玩家/假人過去加載區塊後再讀取。

適用版本:當前版本(服務端)。未能從源碼或文檔中直接證實,僅供參考。

LeviLamina C++ 模組中如何獲取所有已加載實體?MC API 裡實體類叫什麼,繼承關係是怎樣的?

可以參考 LSE 的實現:ll::service::getLevel()->getEntities() 返回 std::vector<OwnerPtr<EntityContext>> const&,遍歷時先判斷 i.has_value() && i.tryUnwrap().has_value(),再用 i.tryUnwrap().get() 拿到 Actor&。

BDS 中實體基類叫 Actor(沒有 Entity 類),Mob 繼承 Actor(生物),Player 繼承 Mob,ServerPlayer 繼承 Player。

LeviLamina mod 實現連鎖採集時,用 Block::playerDestroy + setBlock + neighborChanged 手動破壞方塊,導致木頭上的火把、藤蔓等附著方塊不正常掉落,應如何實現?

直接調用玩家的 GameMode::destroyBlock(BlockPos const& pos, uchar face) 破壞方塊(如 player.mGameMode->destroyBlock(pos, face)),玩家挖方塊走的就是這個函數,附著方塊掉落、方塊更新、工具耐久等由遊戲自行處理,無需手動 playerDestroy / setBlock / neighborChanged。

LeviLamina 頭文件中 Block 沒有可調用的 getRuntimeId,怎麼獲取方塊的 RuntimeId?

直接讀取 Block 的成員變量 mNetworkId(ll::TypedStorage<4,4,uint>,即方塊的網絡運行時 ID),例如 block.mNetworkId。

在 LeviLamina C++ mod 中如何主動加載指定位置的區塊(例如做隨機傳送前預加載目標區塊)?JS 插件有什麼辦法?

C++ 可以創建或使用 ChunkViewSource 並調用 ChunkViewSource::move,讓區塊源移動到目標範圍進行加載:以要加載的區塊為中心向外擴 3 個區塊(實際要加載 7x7 區塊,中心區塊才會完整加載/生成),然後等待加載完成,過程與玩家加載區塊類似。

注意當前頭文件中只有 move(BlockPos const& blockMin, BlockPos const& blockMax, bool isCircle, ChunkSourceViewGenerateMode, std::function<void(gsl::span<std::shared_ptr<LevelChunk>>)> add, float const* serverBuildRatio) 這個重載是可用的 MCAPI,其餘重載標記為 MCNAPI,不可直接調用。

JS(LSE)側沒有直接 API,可藉助 tickingarea 命令臨時添加常加載區域,或使用 iListenAttentively 的 LSE 導出插件(ila-lseexport)提供的能力。

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

在 LeviLamina C++ mod 中按區塊座標獲取區塊,用 getChunk / getChunkAt 拿不到(可能區塊未加載),應該用什麼 API?

BlockSource::getChunk 只返回已加載的區塊,未加載時返回空。可以用 ChunkSource 的 getOrLoadChunk(ChunkPos const& cp, ChunkSource::LoadMode lm, bool readOnly)(LoadMode 有 None、Deferred),它會在需要時加載區塊;只想查已存在的區塊可用 getExistingChunk。ChunkPos 可以直接用座標構造。頭文件見 LeviLamina 倉庫 src/mc/world/level/chunk/ChunkSource.h。

注意區塊加載可能是異步的,需要完整加載時可參考 ChunkViewSource 方式。

適用版本:LeviLamina 1.x 及以上

在 LeviLamina C++ 插件中如何移除/自定義實體受傷後的無敵幀?

Actor 類下有成員 mInvulnerableTime(TypedStorage<int>),在受傷後把它設為 0 即可去掉無敵幀(也可設為自定義值),例如 actor.mInvulnerableTime = 0;(TypedStorage 需通過 get() / 賦值訪問)。如果追求極致性能,可以直接 patch 掉遊戲中設置該值的代碼。

適用版本:LeviLamina 1.x 及以上(字段隨 BDS 版本可能變化)

在 LeviLamina mod 中如何判斷某個方塊/物品屬於某個類(如門、潛影盒、告示牌)?能用虛函數表(vftable)比較嗎?

不要用虛表判斷:BDS 沒有 RTTI,LeviLamina 也不保證保留 vtable 符號;自己 new 出來的派生類虛表也不是 BDS 的,虛表不能用來判斷任何東西。

應使用方塊自身的類型/ID 判斷:參考 VanillaBlockTypeIds(src/mc/world/level/block/VanillaBlockTypeIds.h)比較方塊類型名,或看基類;帶方塊實體的(潛影盒、告示牌)可用 BlockType::getBlockEntityType() 判斷 BlockActorType;若想兼容自定義方塊,可用 block.getTypeName() 判斷名稱(如是否以 _door 結尾)或判斷組件。

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

在 LeviLamina mod 中如何獲取 BDS 的刷怪器(spawner),以統計哪些生物計入全局刷怪上限或讀取刷怪計數?

通過 ll::service::getLevel()->mMobSpawner(或 Level::getSpawner())拿到 Spawner,再 static_cast 成 BedrockSpawner 即可訪問其成員;刷怪計數相關邏輯可從 ActorSpawnRuleGroup 入手研究。注意逆向得到的生物池枚舉順序可能有誤,pool_name 需自行校正。

適用版本:LeviLamina 當前版本

在 LeviLamina mod 中能否在世界生成階段(區塊地形生成/裝飾時)調用 getOrLoadChunk 加載區塊?

不能。在世界生成過程中(如 IFeature::place、BiomeDecorationSystem::decorateLargeFeature 等函數內部)調用 ChunkSource::getOrLoadChunk 會導致死循環,應避免在這些 hook 里加載區塊。

適用版本:LeviLamina 當前版本(BDS 原版行為)。未能從源碼或文檔中直接證實,僅供參考。

在 LeviLamina mod 裡實現雙開門聯動時,把獲取到的門方塊當 Block 調用(如 getStates)導致崩潰,怎麼正確判斷雙開門另一半的位置?

DoorBlock 繼承自 BlockType(舊稱 BlockLegacy),是方塊類型而不是方塊實例 Block,不能把它當 Block 使用,否則會崩潰。

應通過方塊實例(Block)讀取方塊狀態:用下半門的朝向狀態和上半門的 door_hinge_bit 確定雙開門另一半的位置;也可直接使用 DoorBlock::getDir(region, pos) 和 DoorBlock::hasRightHinge(region, pos)。這比遍歷四個方向更好。

適用版本:LeviLamina 當前版本

在 LeviLamina 頭文件裡找不到與區塊(chunk)相關的 API,應該用哪些類?LSE(LegacyScriptEngine)有區塊相關 API 嗎?

C++ 側區塊相關的類主要是 ChunkSource 和 LevelChunk(mc/world/level/chunk/ChunkSource.h、LevelChunk.h)。LSE 沒有專門的區塊 API(只有 player.refreshChunks() 之類的零散接口),像給假人補區塊加載這類需求需要用 C++ 原生 mod 實現。

適用版本:LeviLamina 當前版本;LegacyScriptEngine 當前版本

在 mod 中對動力鐵軌上的礦車調用 getPosDelta(),向量長度為 2.06 格/gt,而不是預期的約 0.4,為什麼?

getPosDelta() 不是當前 tick 與上一 tick 的位置差,而是實體當前的運動向量(StateVectorComponent::mPosDelta,給它加值實體會隨之移動),礦車速度上限等可能硬編碼在原版代碼裡。可參考 https://github.com/killcerr/MinecartSpeedPlus/blob/main/src/MinecartSpeedPlus.cpp 的實現。

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

在原生 mod 裡調用底層 API 把圖片生成為地圖(地圖畫)時,怎樣才能不受 parentMapId 判斷的影響?

據地圖畫插件的開發經驗:調用底層 API 生成地圖時,把地圖數據(MapItemSavedData)的 scale(mScale)設為最大值,就不會再去判斷 parentMapId(mParentMapId)。

適用版本:LeviLamina 原生 mod,依賴 BDS 內部地圖邏輯。未能從源碼或文檔中直接證實,僅供參考。

想修改生物血量,通過 setNbt 修改 Attributes 裡的血量會導致進程直接退出,有更直接的辦法嗎?

不必改 NBT,直接操作屬性即可。當前寫法:通過實體的 AttributesComponent 或 Actor::getAttributes() 拿到 BaseAttributeMap,再調用 setMaxValue/setCurrentValue,例如:

cpp
actor.getAttributes()->setMaxValue(SharedAttributes::HEALTH(), value);

或參考 LSE:

cpp
if (auto c = actor.getEntityContext().tryGetComponent<AttributesComponent>())
  c->mAttributes->setMaxValue(SharedAttributes::HEALTH(), value);

改當前血量用 setCurrentValue。

用 LeviLamina 能否把世界生成為虛空(類似空島)?

可以用 MoreDimensions 的多維度 API 創建虛空維度:CustomDimensionManager::addSimpleDimension(name, seed, GeneratorType::Void)(MoreDimensions 測試中有 custom_dim:new_void_type 示例)。若想主世界虛空但保留結構,可在虛空維度基礎上自行實現結構生成,或 hook 地形生成相關函數(原版有 VoidGenerator)。也可參考現成插件:https://github.com/ZGDD-BE/VoidWorldGenerator

適用版本:LeviLamina + MoreDimensions 當前版本