feat: add block placement and palette indexing APIs to support subchunk editing

Author: yechentide

Sources/CoreBedrock/World/Block/MCSubChunkStorage.swift

@@ -2,19 +2,27 @@
 // Created by yechentide on 2025/09/19
 //
 
-struct MCSubChunkStorage {
-    let version: Int
-    let chunkY: Int8
+public struct MCSubChunkStorage {
+    public let version: Int
+    public let chunkY: Int8
 
-    let blockLayer: BlockStorageLayer
-    let liquidLayer: BlockStorageLayer
+    public private(set) var blockLayer: BlockStorageLayer
+    public private(set) var liquidLayer: BlockStorageLayer
 
-    struct BlockStorageLayer: PaletteReadable {
-        let bitWidth: Int
-        let palette: [CompoundTag]
-        let indicesBytes: [UInt8]
+    public struct BlockStorageLayer: PaletteReadable {
+        public var bitWidth: Int
+        public private(set) var palette: [CompoundTag]
+        public private(set) var indicesBytes: [UInt8]
+        private var paletteIndexCache: [Int: [Int]]
 
-        func paletteValue(at linearIndex: Int) -> CompoundTag? {
+        public init(bitWidth: Int, palette: [CompoundTag], indicesBytes: [UInt8]) {
+            self.bitWidth = bitWidth
+            self.palette = palette
+            self.indicesBytes = indicesBytes
+            self.paletteIndexCache = [:]
+        }
+
+        public func paletteValue(at linearIndex: Int) -> CompoundTag? {
             guard 0..<MCSubChunk.totalBlockCount ~= linearIndex else {
                 return nil
             }
@@ -63,5 +71,115 @@ struct MCSubChunkStorage {
                 }
             }
         }
+
+        // MARK: - Public API for Palette Management and Block Placement
+
+        public mutating func ensurePaletteIndex(for block: CompoundTag) -> Int {
+            self.rebuildCacheIfNeeded()
+
+            let hash = self.blockHash(block)
+            if let candidates = paletteIndexCache[hash] {
+                for index in candidates where self.palette[index] == block {
+                    return index
+                }
+            }
+
+            // Not found, add to palette
+            let newIndex = self.palette.count
+            self.palette.append(block)
+            self.paletteIndexCache[hash, default: []].append(newIndex)
+            return newIndex
+        }
+
+        public mutating func place(at localX: Int, localY: Int, localZ: Int, paletteIndex: Int) {
+            guard let linear = MCSubChunk.linearIndex(localX, localY, localZ) else { return }
+            guard paletteIndex < self.palette.count else { return }
+
+            self.ensureBitWidthCanHold(paletteIndex)
+            self.writePaletteIndex(paletteIndex, atLinearIndex: linear)
+        }
+
+        // MARK: - Private Helpers
+
+        private func blockHash(_ block: CompoundTag) -> Int {
+            block.description.hashValue
+        }
+
+        private mutating func rebuildCacheIfNeeded() {
+            guard self.paletteIndexCache.isEmpty else { return }
+
+            var cache: [Int: [Int]] = [:]
+            for (index, block) in self.palette.enumerated() {
+                let hash = self.blockHash(block)
+                cache[hash, default: []].append(index)
+            }
+            self.paletteIndexCache = cache
+        }
+
+        private mutating func ensureBitWidthCanHold(_ index: Int) {
+            guard index >= (1 << self.bitWidth) else { return }
+
+            var newBitWidth = self.bitWidth
+            while index >= (1 << newBitWidth) {
+                newBitWidth += 1
+            }
+
+            self.repackIndices(to: newBitWidth)
+        }
+
+        private mutating func repackIndices(to newBitWidth: Int) {
+            guard newBitWidth != self.bitWidth else { return }
+
+            let newValuesPerWord = 32 / newBitWidth
+            let newWordCount = (MCSubChunk.totalBlockCount + newValuesPerWord - 1) / newValuesPerWord
+            var newIndicesBytes = [UInt8](repeating: 0, count: newWordCount * 4)
+
+            for linearIndex in 0..<MCSubChunk.totalBlockCount {
+                let existingIndex = self.paletteIndex(at: linearIndex)
+                self.writePaletteIndex(
+                    existingIndex, atLinearIndex: linearIndex, using: newBitWidth, into: &newIndicesBytes
+                )
+            }
+
+            self.bitWidth = newBitWidth
+            self.indicesBytes = newIndicesBytes
+            self.paletteIndexCache = [:] // Invalidate cache after repack
+        }
+
+        private func paletteIndex(at linearIndex: Int) -> Int {
+            let valuesPerWord = 32 / self.bitWidth
+            let wordIndex = linearIndex / valuesPerWord
+            let indexInWord = linearIndex % valuesPerWord
+            let offset = indexInWord * self.bitWidth
+            let mask = (1 << self.bitWidth) - 1
+
+            return self.indicesBytes.withUnsafeBytes { rawBuffer in
+                let words = rawBuffer.baseAddress!.assumingMemoryBound(to: UInt32.self)
+                let word = UInt32(littleEndian: words[wordIndex])
+                return Int((word >> offset) & UInt32(mask))
+            }
+        }
+
+        private mutating func writePaletteIndex(_ index: Int, atLinearIndex linear: Int) {
+            self.writePaletteIndex(index, atLinearIndex: linear, using: self.bitWidth, into: &self.indicesBytes)
+        }
+
+        private func writePaletteIndex(
+            _ index: Int, atLinearIndex linear: Int, using bw: Int, into bytes: inout [UInt8]
+        ) {
+            let valuesPerWord = 32 / bw
+            let wordIndex = linear / valuesPerWord
+            let indexInWord = linear % valuesPerWord
+            let offset = indexInWord * bw
+            let mask = UInt32((1 << bw) - 1)
+
+            bytes.withUnsafeMutableBytes { rawBuffer in
+                let words = rawBuffer.baseAddress!.assumingMemoryBound(to: UInt32.self)
+                var word = UInt32(littleEndian: words[wordIndex])
+                word &= ~(mask << offset) // Clear bits
+                word |= UInt32(index) << offset // Set new bits
+                words[wordIndex] = word.littleEndian
+            }
+        }
     }
 }

Sources/CoreBedrock/World/Block/SubChunkParser.swift

@@ -19,16 +19,16 @@ import Foundation
  */
 // swiftlint:enable line_length
 
-struct SubChunkParser {
+public struct SubChunkParser {
     private let binaryReader: CBBinaryReader
     private let chunkY: Int8
 
-    init(data: Data, chunkY: Int8) {
+    public init(data: Data, chunkY: Int8) {
         self.binaryReader = CBBinaryReader(data: data)
         self.chunkY = chunkY
     }
 
-    func lightParse() throws -> MCSubChunkStorage? {
+    public func lightParse() throws -> MCSubChunkStorage? {
         let storageVersion = try binaryReader.readUInt8()
         return switch storageVersion {
         case 9: try self.parseV9Light()