Initial release 1.0.0: Complete NBT parsing and GZip support

Author: arnaudrmt

.gitignore

@@ -1,8 +1,23 @@
+# Xcode
 .DS_Store
-/.build
-/Packages
+*.swp
+*.lock
+*~.nib
+*.pbxuser
+*.mode1v3
+*.mode2v3
+*.perspectivev3
 xcuserdata/
 DerivedData/
-.swiftpm/configuration/registries.json
-.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
-.netrc
+build/
+*.moved-aside
+*.xccheckout
+*.xcworkspace
+!default.xcworkspace
+
+# Swift Package Manager
+.build/
+.swiftpm/
+
+# CocoaPods
+Pods/

Package.swift

@@ -16,7 +16,10 @@ let package = Package(
         // Targets are the basic building blocks of a package, defining a module or a test suite.
         // Targets can depend on other targets in this package and products from dependencies.
         .target(
-            name: "SwiftNBT"
+            name: "SwiftNBT",
+            linkerSettings: [
+                .linkedLibrary("z")
+            ]
         ),
         .testTarget(
             name: "SwiftNBTTests",

README.md

@@ -0,0 +1,126 @@
+<div align="center">
+
+![SwiftNBT Banner](https://placehold.co/800x200/F06292/FFFFFF?text=SwiftNBT&font=montserrat)
+
+![Swift](https://img.shields.io/badge/Swift-6.2+-orange?logo=swift&logoColor=white)
+![Platform](https://img.shields.io/badge/Platform-iOS%20|%20macOS%20|%20Linux-lightgrey)
+![License](https://img.shields.io/badge/License-MIT-yellow?logo=opensourceinitiative)
+
+</div>
+
+> ⚠️ **Compression & Linkage Notice**
+>
+> SwiftNBT utilizes the system native **zlib** library for maximum performance when handling GZip/Zlib compressed data (standard for Minecraft).
+>
+> **For Linux/Server-Side Swift:** Ensure `zlib1g-dev` is installed on your machine.
+> **For iOS/macOS:** It works out of the box using the system SDKs.
+
+**SwiftNBT** is a lightweight, zero-dependency (other than system zlib) parser for the **Named Binary Tag (NBT)** format used by Minecraft. It is designed to be robust, type-safe, and incredibly easy to use with modern Swift syntax.
+
+---
+
+## How to Use: Installation
+
+### Swift Package Manager (SPM)
+
+You can add SwiftNBT to your project via Xcode or your `Package.swift` file.
+
+**In `Package.swift`:**
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/arnaudrmt/SwiftNBT.git", from: "1.0.0")
+],
+targets: [
+    .target(
+        name: "YourTarget",
+        dependencies: ["SwiftNBT"]
+    )
+]
+```
+
+**In Xcode:**
+1. Go to **File > Add Package Dependencies...**
+2. Paste the repository URL.
+3. Select the version and add it to your target.
+
+---
+
+## API Usage Examples
+
+### 1. Parsing Raw Data (Base64 or Bytes)
+
+The most common use case is decoding a Base64 string that contains GZipped NBT data.
+
+```swift
+import SwiftNBT
+
+let base64String = "H4sIAAAAAAAA/..." // Your data
+guard let data = Data(base64Encoded: base64String) else { return }
+
+do {
+    // The parser automatically handles GZip decompression
+    let rootTag = try NBTParser.parse(data)
+    
+    print("Parsing successful!")
+    rootTag.printTree() // Debug helper to see the structure
+} catch {
+    print("Error: \(error)")
+}
+```
+
+### 2. Accessing Data (The Easy Way)
+
+Forget large `switch` statements. Use the built-in optional helpers and subscripts to navigate the NBT tree effortlessly.
+
+```swift
+// Accessing a nested path: root -> tag -> display -> Name
+if let itemName = rootTag["tag"]?["display"]?["Name"]?.string {
+    print("Item Name: \(itemName)")
+}
+
+// Accessing lists and arrays
+if let inventoryList = rootTag["i"]?.array {
+    for (index, item) in inventoryList.enumerated() {
+        let count = item["Count"]?.byte ?? 0
+        let id = item["id"]?.short ?? 0
+        
+        print("Slot \(index): ID \(id) x\(count)")
+    }
+}
+```
+
+### 3. Extracting Values
+
+SwiftNBT provides computed properties to safely cast values.
+
+```swift
+let tag: NBTTag = ...
+
+// Safe casting (returns nil if type mismatches)
+let myInt = tag.int       // Works for Byte, Short, and Int types
+let myDouble = tag.double // Works for Float and Double types
+let myString = tag.string
+```
+
+---
+
+## Features
+
+*   **Auto-Decompression:** Automatically detects and handles GZip and ZLib headers using the native system `zlib`, ensuring 100% compatibility with Minecraft data (RFC 1952).
+*   **Type Safety:** Built on a comprehensive `NBTTag` enum that strictly represents every Minecraft data type (Byte, Short, Int, Long, Float, Double, Arrays, Lists, Compounds).
+*   **Syntactic Sugar:** Navigate complex NBT trees effortlessly using dictionary-like subscripts (e.g., `tag["display"]["Name"]`) and safe optional casting.
+*   **Debug Tools:** Includes a handy `.printTree()` method to visualize the NBT structure hierarchy in the console.
+*   **Lightweight:** Zero external dependencies (other than system libraries), keeping your build times fast and binary size small.
+
+---
+
+## Contributing & Maintenance
+
+This library was built to provide a stable, long-term solution for the Swift Minecraft community. **It is here to stay and will be actively maintained.**
+
+We welcome contributions!
+*   **Found a bug?** Please open an [Issue](https://github.com/arnaudrmt/SwiftNBT/issues).
+*   **Have an improvement?** Feel free to fork the repo and submit a Pull Request.
+
+You don't have to worry about this library becoming deprecated or deleted; we depend on it for our own production apps.

Sources/SwiftNBT/Core/NBTParser.swift

@@ -0,0 +1,101 @@
+//
+//  File.swift
+//  SwiftNBT
+//
+//  Created by Arnaud on 28/11/2025.
+//
+
+import Foundation
+
+/// The main entry point for parsing NBT Data.
+public class NBTParser {
+    
+    /// Parses raw NBT data into an `NBTTag` structure.
+    /// Automatically handles GZip decompression if needed.
+    ///
+    /// - Parameter data: The raw data (can be Base64 decoded data, or raw bytes).
+    /// - Returns: The root `NBTTag` (usually a Compound).
+    /// - Throws: `NBTError` if parsing or decompression fails.
+    public static func parse(_ data: Data) throws -> NBTTag {
+        // 1. Attempt automatic GZip decompression
+        let rawData = try data.gunzipped()
+        
+        // 2. Start parsing stream
+        let stream = NBTStream(data: rawData)
+        return try parseRoot(stream: stream)
+    }
+    
+    // MARK: - Internal Parsing Logic
+    
+    private static func parseRoot(stream: NBTStream) throws -> NBTTag {
+        let typeId = try stream.readByte()
+        
+        if typeId == 0 { return .end } // Empty file
+        
+        // Root is always a named compound (ID 10)
+        if typeId != 10 {
+            throw NBTError.invalidFormat
+        }
+        
+        // Root tags have a name (often empty string), we consume it but don't store it here
+        _ = try stream.readString()
+        
+        return try readTagPayload(id: 10, stream: stream)
+    }
+    
+    private static func readTagPayload(id: UInt8, stream: NBTStream) throws -> NBTTag {
+        switch id {
+        case 1: return .byte(try stream.readInt8())
+        case 2: return .short(try stream.readInt16())
+        case 3: return .int(try stream.readInt32())
+        case 4: return .long(try stream.readInt64())
+        case 5: return .float(try stream.readFloat())
+        case 6: return .double(try stream.readDouble())
+            
+        case 7: // Byte Array
+            let length = try stream.readInt32()
+            var bytes: [Int8] = []
+            // Optimization: could read bytes in bulk, but loop is safer for endianness
+            for _ in 0..<length { bytes.append(try stream.readInt8()) }
+            return .byteArray(bytes)
+            
+        case 8: return .string(try stream.readString())
+            
+        case 9: // List
+            let elementTypeId = try stream.readByte()
+            let length = try stream.readInt32()
+            var list: [NBTTag] = []
+            for _ in 0..<length {
+                list.append(try readTagPayload(id: elementTypeId, stream: stream))
+            }
+            return .list(list)
+            
+        case 10: // Compound
+            var dict: [String: NBTTag] = [:]
+            while true {
+                let nextId = try stream.readByte()
+                if nextId == 0 { break } // Tag_End
+                
+                let name = try stream.readString()
+                let value = try readTagPayload(id: nextId, stream: stream)
+                dict[name] = value
+            }
+            return .compound(dict)
+            
+        case 11: // Int Array
+            let length = try stream.readInt32()
+            var ints: [Int32] = []
+            for _ in 0..<length { ints.append(try stream.readInt32()) }
+            return .intArray(ints)
+            
+        case 12: // Long Array
+            let length = try stream.readInt32()
+            var longs: [Int64] = []
+            for _ in 0..<length { longs.append(try stream.readInt64()) }
+            return .longArray(longs)
+            
+        default:
+            throw NBTError.unknownTagId(id)
+        }
+    }
+}

Sources/SwiftNBT/Core/NBTStream.swift

@@ -0,0 +1,74 @@
+//
+//  File.swift
+//  SwiftNBT
+//
+//  Created by Arnaud on 28/11/2025.
+//
+
+import Foundation
+
+/// Internal utility class to read binary data sequentially (Big Endian).
+internal class NBTStream {
+    private let data: Data
+    private var offset: Int = 0
+    
+    init(data: Data) {
+        self.data = data
+    }
+    
+    // MARK: - Core Reading
+    
+    func readByte() throws -> UInt8 {
+        guard offset < data.count else { throw NBTError.endOfStream }
+        let b = data[offset]
+        offset += 1
+        return b
+    }
+    
+    func readBytes(_ count: Int) throws -> Data {
+        guard offset + count <= data.count else { throw NBTError.endOfStream }
+        let sub = data.subdata(in: offset..<(offset + count))
+        offset += count
+        return sub
+    }
+    
+    // MARK: - Primitives (Big Endian)
+    
+    func readInt8() throws -> Int8 {
+        return Int8(bitPattern: try readByte())
+    }
+    
+    func readInt16() throws -> Int16 {
+        let data = try readBytes(2)
+        return Int16(bigEndian: data.withUnsafeBytes { $0.load(as: Int16.self) })
+    }
+    
+    func readInt32() throws -> Int32 {
+        let data = try readBytes(4)
+        return Int32(bigEndian: data.withUnsafeBytes { $0.load(as: Int32.self) })
+    }
+    
+    func readInt64() throws -> Int64 {
+        let data = try readBytes(8)
+        return Int64(bigEndian: data.withUnsafeBytes { $0.load(as: Int64.self) })
+    }
+    
+    func readFloat() throws -> Float {
+        let bits = try readInt32()
+        return Float(bitPattern: UInt32(bitPattern: bits))
+    }
+    
+    func readDouble() throws -> Double {
+        let bits = try readInt64()
+        return Double(bitPattern: UInt64(bitPattern: bits))
+    }
+    
+    func readString() throws -> String {
+        let length = try readInt16()
+        let data = try readBytes(Int(length))
+        guard let str = String(data: data, encoding: .utf8) else {
+            throw NBTError.invalidString
+        }
+        return str
+    }
+}

Sources/SwiftNBT/Core/NBTTag.swift

@@ -0,0 +1,43 @@
+//
+//  File.swift
+//  SwiftNBT
+//
+//  Created by Arnaud on 28/11/2025.
+//
+
+/// Represents a Minecraft Named Binary Tag (NBT).
+/// Reference: https://wiki.vg/NBT
+public enum NBTTag: Equatable {
+    case end
+    case byte(Int8)
+    case short(Int16)
+    case int(Int32)
+    case long(Int64)
+    case float(Float)
+    case double(Double)
+    case byteArray([Int8])
+    case string(String)
+    case list([NBTTag])
+    case compound([String: NBTTag])
+    case intArray([Int32])
+    case longArray([Int64])
+    
+    /// The official numeric ID of the tag used in the binary format.
+    internal var id: UInt8 {
+        switch self {
+        case .end: return 0
+        case .byte: return 1
+        case .short: return 2
+        case .int: return 3
+        case .long: return 4
+        case .float: return 5
+        case .double: return 6
+        case .byteArray: return 7
+        case .string: return 8
+        case .list: return 9
+        case .compound: return 10
+        case .intArray: return 11
+        case .longArray: return 12
+        }
+    }
+}