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 let blockLayer: BlockStorageLayer
+    public let 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
             }
@@ -26,7 +34,7 @@ struct MCSubChunkStorage {
         }
 
         @inline(__always)
-        func unsafeEnumerateColumnDescendingY(
+        internal func unsafeEnumerateColumnDescendingY(
             atLocalX localX: Int, localZ: Int, _ perform: (Int, CompoundTag) -> Bool
         ) {
             guard let baseIndex = MCSubChunk.linearIndex(localX, 0, localZ) else {
@@ -63,5 +71,113 @@ struct MCSubChunkStorage {
                 }
             }
         }
+
+        // MARK: - Public API for Palette Management and Block Placement
+
+        public mutating func ensurePaletteIndex(for block: CompoundTag) -> Int {
+            rebuildCacheIfNeeded()
+
+            let hash = blockHash(block)
+            if let candidates = paletteIndexCache[hash] {
+                for index in candidates {
+                    if palette[index] == block {
+                        return index
+                    }
+                }
+            }
+
+            // Not found, add to palette
+            let newIndex = palette.count
+            palette.append(block)
+            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 < palette.count else { return }
+
+            ensureBitWidthCanHold(paletteIndex)
+            writePaletteIndex(paletteIndex, atLinearIndex: linear)
+        }
+
+        // MARK: - Private Helpers
+
+        private func blockHash(_ block: CompoundTag) -> Int {
+            block.description.hashValue
+        }
+
+        private mutating func rebuildCacheIfNeeded() {
+            guard paletteIndexCache.isEmpty else { return }
+
+            var cache: [Int: [Int]] = [:]
+            for (index, block) in palette.enumerated() {
+                let hash = blockHash(block)
+                cache[hash, default: []].append(index)
+            }
+            paletteIndexCache = cache
+        }
+
+        private mutating func ensureBitWidthCanHold(_ index: Int) {
+            guard index >= (1 << bitWidth) else { return }
+
+            var newBitWidth = bitWidth
+            while index >= (1 << newBitWidth) {
+                newBitWidth += 1
+            }
+
+            repackIndices(to: newBitWidth)
+        }
+
+        private mutating func repackIndices(to newBitWidth: Int) {
+            guard newBitWidth != 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 = paletteIndex(at: linearIndex)
+                writePaletteIndex(existingIndex, atLinearIndex: linearIndex, using: newBitWidth, into: &newIndicesBytes)
+            }
+
+            bitWidth = newBitWidth
+            indicesBytes = newIndicesBytes
+            paletteIndexCache = [:]  // Invalidate cache after repack
+        }
+
+        private func paletteIndex(at linearIndex: Int) -> Int {
+            let valuesPerWord = 32 / bitWidth
+            let wordIndex = linearIndex / valuesPerWord
+            let indexInWord = linearIndex % valuesPerWord
+            let offset = indexInWord * bitWidth
+            let mask = (1 << bitWidth) - 1
+
+            return 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) {
+            writePaletteIndex(index, atLinearIndex: linear, using: bitWidth, into: &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()