NMS Block Entity

目的

繼承 NMS BlockEntity 實作自定義方塊實體，實現 NBT 讀寫、伺服器端 Tick 邏輯（BlockEntityTicker）、以及透過封包同步狀態至客戶端。

---

平台需求

• Paper 1.21.11 / 26.2（兩版皆經編譯驗證；版本差異以行尾 // @1.21.11: 標註）
• Paperweight userdev 2.0.0-beta.24+
• Mojang 官方名稱（Minecraft 26.1 起不再混淆）
• Java 21（1.21.11）／25（26.2）

---

產生的代碼

CustomBlockEntity.java

public class CustomBlockEntity extends BlockEntity {

    private int storedEnergy = 0;

    public CustomBlockEntity(BlockEntityType<?> type, BlockPos pos, BlockState state) {
        super(type, pos, state);
    }

    // 1.21.6+：序列化改用 ValueOutput / ValueInput
    @Override
    protected void saveAdditional(ValueOutput output) {
        super.saveAdditional(output);
        output.putInt("storedEnergy", storedEnergy);
    }

    @Override
    protected void loadAdditional(ValueInput input) {
        super.loadAdditional(input);
        storedEnergy = input.getIntOr("storedEnergy", 0);
    }

    @Override
    public ClientboundBlockEntityDataPacket getUpdatePacket() {
        return ClientboundBlockEntityDataPacket.create(this);
    }
}

BlockEntityHelper.java（工具類）

// 在指定位置取得自定義 BlockEntity
Optional<CustomBlockEntity> be = BlockEntityHelper.getCustom(location);

// 標記已修改（觸發 NBT 儲存與客戶端同步）
be.ifPresent(CustomBlockEntity::markDirtyAndSync);

---

執行緒安全

• 所有 BlockEntity 操作必須在主執行緒呼叫
• getUpdatePacket() 封包在 Netty IO 執行緒傳送，建構資料須在主執行緒完成