feat: enable injecting generated items directly into player inventory

Author: yechentide

Sources/CoreBedrock/Error/ContainerInsertError.swift

@@ -0,0 +1,10 @@
+//
+// Created by yechentide on 2026/02/06
+//
+
+import Foundation
+
+public enum ContainerInsertError: Error, Equatable, LocalizedError {
+    case invalidPlayerNBT
+    case noAvailableSlot
+}

Sources/CoreBedrock/Utils/ChestEntityGenerator.swift

@@ -4,6 +4,8 @@
 
 // MARK: Temporarily disabled until rollback is implemented
 
+// swiftlint:disable line_length
+
 //public enum ChestEntityGenerator {
 //    private static let capacity = 27
 //
@@ -84,3 +86,5 @@
 //        }
 //    }
 //}
+
+// swiftlint:enable line_length

Sources/CoreBedrock/Utils/ItemGenerator.swift

@@ -73,7 +73,7 @@ public enum ItemGenerator {
         }
 
         if let blockMeta = meta.blockMeta {
-            let blockMetaTag = try CompoundTag([
+            let blockMetaTag = try CompoundTag(name: "Block", [
                 StringTag(name: "name", meta.type),
                 IntTag(name: "version", blockMeta.version),
                 CompoundTag(name: "states", blockMeta.states),

Sources/CoreBedrock/Utils/ItemInjector.swift

@@ -0,0 +1,64 @@
+//
+// Created by yechentide on 2026/02/06
+//
+
+import Foundation
+
+public struct ItemInjector {
+    public static func giveItemToPlayer(
+        item: CompoundTag, playerKey: Data, in world: LevelKeyValueStore
+    ) throws {
+        let playerTag = try loadPlayerTag(from: world, key: playerKey)
+        let inventory = try loadPlayerInventory(from: playerTag)
+
+        guard let slotIndex = firstAvailableSlot(in: inventory) else {
+            throw ContainerInsertError.noAvailableSlot
+        }
+
+        try place(item: item, into: inventory, at: slotIndex)
+
+        let newData = try playerTag.toData()
+        try world.putData(newData, forKey: playerKey)
+    }
+
+    private static func loadPlayerTag(
+        from world: LevelKeyValueStore,
+        key: Data
+    ) throws -> CompoundTag {
+        let data = try world.data(forKey: key)
+        let reader = CBTagReader(data: data)
+
+        guard let tag = try reader.readNext() as? CompoundTag else {
+            throw ContainerInsertError.invalidPlayerNBT
+        }
+        return tag
+    }
+
+    private static func loadPlayerInventory(
+        from playerTag: CompoundTag
+    ) throws -> ListTag {
+        guard let inventory = playerTag["Inventory"] as? ListTag else {
+            throw ContainerInsertError.invalidPlayerNBT
+        }
+        return inventory
+    }
+
+    private static func firstAvailableSlot(
+        in inventory: ListTag
+    ) -> Int? {
+        inventory.tags.firstIndex { slotTag in
+            slotTag["Count"]?.stringValue == "0"
+        }
+    }
+
+    private static func place(
+        item: CompoundTag,
+        into inventory: ListTag,
+        at index: Int
+    ) throws {
+        _ = item.remove(forKey: "Slot")
+        try item.append(ByteTag(name: "Slot", UInt8(index)))
+        inventory.tags[index].parent = nil
+        inventory.tags[index] = item
+    }
+}

Sources/CoreBedrock/Utils/MapArtGenerator.swift

@@ -3,25 +3,28 @@
 //
 
 import CoreGraphics
+import Foundation
 
 public enum MapArtGenerator {
     private static let tileSize = 128
 
-    /// Generates map art from an image and places it in a shulker box chest at the specified location.
+    /// Generates map art from an image, packs the maps into a shulker box,
+    /// and inserts it into the specified player's inventory.
+    ///
     /// - Parameters:
-    ///   - database: The level database to store map data and chest
-    ///   - image: The source image to convert to map art
-    ///   - x: X coordinate for the chest placement
-    ///   - y: Y coordinate for the chest placement
-    ///   - z: Z coordinate for the chest placement
-    ///   - shulkerBoxName: Optional name for the shulker box containing maps
-    /// - Throws: If image processing, map data generation, or placement fails
-    public static func generateAndPlace(
+    ///   - database: The level database used to store generated map data
+    ///   - image: The source image to convert into map art
+    ///   - playerKey: The database key identifying the target player
+    ///   - shulkerBoxName: Optional custom name for the shulker box containing the maps
+    ///
+    /// - Throws:
+    ///   - If map data generation or storage fails
+    ///   - If the player's inventory has no available slot
+    ///   - If the player's NBT data is invalid or cannot be parsed
+    public static func generateAndGiveToPlayer(
         database: LevelKeyValueStore,
         image: CGImage,
-        x: Int32,
-        y: Int32,
-        z: Int32,
+        playerKey: Data,
         shulkerBoxName: String? = nil
     ) throws {
         let (mapItems, mapDataDict) = try buildMapItemsAndData(image: image, database: database)
@@ -32,7 +35,7 @@ public enum MapArtGenerator {
                 try database.putData(entryData, forKey: lvdbKey.data)
             }
             let shulkerBox = try ShulkerNestingPacker.pack(items: mapItems, rootName: shulkerBoxName)
-            try ChestEntityGenerator.place(database: database, x: x, y: y, z: z, items: [shulkerBox])
+            try ItemInjector.giveItemToPlayer(item: shulkerBox, playerKey: playerKey, in: database)
         } catch {
             // Rollback map data on failure
             for lvdbKey in mapDataDict.keys {
@@ -122,6 +125,7 @@ public enum MapArtGenerator {
     /// - Throws: If unable to allocate the requested number of IDs
     private static func allocateMapIDs(in database: LevelKeyValueStore, count: Int) throws -> [Int64] {
         let iter = try database.makeIterator()
+        iter.moveToFirst()
         defer {
             iter.close()
         }
@@ -131,7 +135,7 @@ public enum MapArtGenerator {
         while ids.count < count {
             let keyData = LvDBKey.map(currentID).data
             iter.move(to: keyData)
-            if iter.currentKey != keyData {
+            if !(iter.isValid && iter.currentKey == keyData) {
                 ids.append(currentID)
             }
             currentID += 1