NMS Chunk Access

目的

透過 NMS LevelChunk、ChunkAccess、LevelChunkSection 直接讀寫方塊狀態與高度圖，繞過 Bukkit Chunk.getBlock() 的逐格開銷，實現高效能的大範圍方塊操作（如結構生成、地圖掃描）。

---

平台需求

• Paper 1.21 – 1.21.3
• Paperweight userdev 1.7.2+
• Mojang mappings（Paper 1.20.5+ 原生支援）
• Java 21

---

產生的代碼

ChunkAccessUtil.java

// 取得指定座標的 NMS BlockState（不觸發光照更新）
BlockState state = ChunkAccessUtil.getBlockState(world, blockPos);

// 直接設定 BlockState（繞過 Bukkit 事件）
ChunkAccessUtil.setBlockState(world, blockPos, Blocks.STONE.defaultBlockState());

// 讀取 WORLD_SURFACE 高度圖
int surfaceY = ChunkAccessUtil.getSurfaceHeight(chunk, x, z);

BulkBlockEditor.java（批次操作）

BulkBlockEditor editor = new BulkBlockEditor(level);

// 批次填充方塊（最小化客戶端更新）
for (BlockPos pos : positionList) {
    editor.setBlock(pos, Blocks.GLASS.defaultBlockState());
}

int count = editor.getPendingCount();  // 取得待提交數量
editor.commit();                       // 一次性推送所有區塊更新

---

執行緒安全

• ChunkAccessUtil 與 BulkBlockEditor 的所有操作必須在主執行緒呼叫
• 區塊讀取操作若區塊未載入，會觸發同步載入，可能造成短暫卡頓