arnaudrmt/SwiftNBT

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:

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.

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.

// 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.

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

Package Metadata

Repository: arnaudrmt/SwiftNBT

Stars: 0

Forks: 0

Open issues: 0

Default branch: main

Primary language: swift

License: MIT

Topics: api, gzip, ios, macos, minecraft, nbt, nbt-parser, spm, swift

README: README.md