NMS Chunk Access

目的

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

---

平台需求

• 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）

---

產生的代碼

ChunkAccessUtil.java

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

// 直接設定 BlockState（繞過 Bukkit 事件；flags 3 = 更新鄰居 + 同步客戶端）
ChunkAccessUtil.setBlockState(location, Blocks.STONE.defaultBlockState(), 3);

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

BulkBlockEditor.java（批次操作）

BulkBlockEditor editor = new BulkBlockEditor(world);

// 批次填充方塊（最小化客戶端更新）
editor.fill(0, 64, 0, 15, 70, 15, Blocks.GLASS.defaultBlockState())
      .set(8, 71, 8, Blocks.GLOWSTONE.defaultBlockState());

int count = editor.pendingCount();  // 取得待提交數量
editor.commit(3);                   // 一次性推送（flags 3 = 更新鄰居 + 同步客戶端）

---

執行緒安全

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