Crate quartz_nbt

Provides support for encoding and decoding Minecraft’s NBT format. This crate supports both zlib and gz compression, and also provides tools for converting NBT data to stringified NBT (SNBT) and vice versa.

Basic Usage

The basic unit of NBT data is the NbtTag. Larger data structures are represented through a tree of compounds (hash maps) and lists (vecs) of NBT tags.

Creating NBT Data

let mut compound = NbtCompound::new();
compound.insert("foo", 123);
compound.insert("bar", -3.6f32);

let mut list = NbtList::with_capacity(3);
(1i64..=3).for_each(|x| list.push(x));
compound.insert("list", list);

*compound.get_mut::<_, &mut i32>("foo").unwrap() += 1;

assert!(matches!(compound.get::<_, i32>("foo"), Ok(124)));
assert!(compound.get::<_, f64>("bar").is_err());
assert!(compound.get::<_, &NbtTag>("list").is_ok());

Reading and Writing NBT

use quartz_nbt::io::{self, Flavor};
use std::io::Cursor;

let mut compound = NbtCompound::new();
compound.insert("foo", 123);
compound.insert("bar", -3.6f32);

let mut binary: Vec<u8> = Vec::new();
io::write_nbt(&mut binary, Some("root-tag"), &compound, Flavor::Uncompressed);

let read_compound = io::read_nbt(&mut Cursor::new(binary), Flavor::Uncompressed).unwrap();
assert_eq!(read_compound.1, "root-tag"); // The root tag's name is generally unused
assert_eq!(read_compound.0, compound);

Querying Tags

Generics are used to make the tag querying process as seamless as possible, however this allows for two types of errors to occur: missing tags (invalid key or index), and tag type mismatches. Thus, methods that would normally return an Option in std collection equivalents return a Result in this crate.

An error converting NBT tags directly into unwrapped values via TryFrom and TryInto is represented by an NbtStructureError. An error querying an NbtCompound or NbtList is represented by an NbtReprError, which is short for “NBT representation error.” See the error’s documentation for details.

use std::convert::TryFrom;

let tag1: NbtTag = vec![1i8, 2, 3].into();
let tag2: NbtTag = "abcde".into();

assert_eq!(Vec::<i8>::try_from(tag1).unwrap(), vec![1i8, 2, 3]);
assert!(i16::try_from(tag2).is_err()); // Type mismatch

let mut compound = NbtCompound::new();
compound.insert("foo", 123);
compound.insert("bar", -3.6f32);

assert!(compound.get::<_, i32>("fooz").is_err()); // Missing tag
assert!(compound.get::<_, i32>("bar").is_err()); // Type mismatch

Collection Types and Iteration

The NbtCompound and NbtList types are wrappers around HashMaps and Vecs respectively. Because NbtTags obscure the type of data actually stored, these wrappers provide utilities for unpacking tags into concrete types. If greater functionality is required, then the internal collection managed by these wrappers can be accessed through calls to as_ref and as_mut.

Lists

Minecraft’s NBT specification currently has special tags for arrays (or Vecs in rust) of i8, i32, and i64. Thus, vecs of these types can be directly converted into NbtTags. All other NBT-compatible types must be stored in an NbtList.

Obtaining the aforementioned special list types can be done through a regular query.

let mut compound = NbtCompound::new();
compound.insert("list", vec![10i32, 20, 30]);

compound.get_mut::<_, &mut [i32]>("list")
    .unwrap()
    .iter_mut()
    .for_each(|x| *x /= 10);

let list = compound.get::<_, &[i32]>("list");
assert!(list.is_ok());
assert_eq!(list.unwrap(), [1i32, 2, 3].as_ref());

Utility methods are provided for NBT lists to iterate over unpacked values. See iter_map and iter_mut_map.

let mut list = NbtList::new();
list.push("abc");
list.push("ijk");
list.push("xyz");

list.iter_mut_map::<&mut String>()
    .for_each(|s| s.unwrap().push('!'));

let mut iter = list.iter_map::<&str>();
assert!(matches!(iter.next(), Some(Ok("abc!"))));
assert!(matches!(iter.next(), Some(Ok("ijk!"))));
assert!(matches!(iter.next(), Some(Ok("xyz!"))));
assert!(matches!(iter.next(), None));

NBT lists can be created by cloning data from an iterator (or something which can be converted into an iterator) via clone_from.

let mut list1 = NbtList::new();
list1.push("abc");
list1.push("ijk");
list1.push("xyz");

let list2 = NbtList::clone_from(&["abc", "ijk", "xyz"]);

assert_eq!(list1, list2);

Compounds

NbtCompounds have the same set of utility functions as NbtLists, except for the obvious fact that compounds use string keys instead of indices. Similar to lists, compounds have iter_map and iter_mut_map utility functions, as well as a clone_from constructor. See the documentation for more details.

Stringified NBT (SNBT)

Minecraft also contains a string encoding of NBT data called SNBT. This encoding is basically an extension of JSON with stricter types and looser rules regarding string quotation. See the snbt module documentation for more details.

use quartz_nbt::snbt;

let tag: NbtTag = vec![10i8, 15, 20].into();
assert_eq!(tag.to_snbt(), "[B;10,15,20]");

let mut compound = NbtCompound::new();
compound.insert("short", -10i16);
compound.insert("string", "fizzbuzz");
compound.insert("array", vec![1i64, 1, 2, 3, 5]);

const SNBT: &str = "{short: -10s, string: fizzbuzz, array: [L; 1, 1, 2, 3, 5]}";

assert_eq!(compound, snbt::parse(SNBT).unwrap());

NBT Representation

The NbtRepr trait allows for custom types to be convertible into NbtTags by defining methods for writing and reading to and from an NbtCompound.

#[derive(Debug, PartialEq, Eq)]
struct Example {
    name: String,
    value: i32
}

impl NbtRepr for Example {
    fn read_nbt(&mut self, nbt: &NbtCompound) -> Result<(), NbtReprError> {
        self.name = nbt.get::<_, &str>("name")?.to_owned();
        self.value = nbt.get("value")?;
        Ok(())
    }

    fn write_nbt(&self, nbt: &mut NbtCompound) {
        nbt.insert("name", &self.name);
        nbt.insert("value", self.value);
    }
}

let ex1 = Example {
    name: "foo".to_owned(),
    value: 10
};

let mut nbt = NbtCompound::new();
nbt.insert("name", "foo");
nbt.insert("value", 10);

let mut ex2 = Example {
    name: "".to_owned(),
    value: 0
};
ex2.read_nbt(&nbt);

assert_eq!(ex1.to_nbt(), nbt);
assert_eq!(ex1, ex2);

Currently, implementing this trait only allows for basic conversion into NbtTags and construction of compounds and lists via the clone_from_repr methods in each. In the future, we plan to create a derive macro for this trait as well as to more thoroughly integrate its use into this crate.

Modules

io

Provides efficient serializer and deserializer implementations for arbitrary NBT tag trees. The functions in this module should be used for serializing and deserializing NbtCompounds over the utilities provided by serde.

serde

When the serde feature is enabled, this module provides Serializer and Deserializer implementations to link this crate into the serde data model.

snbt

Provides support for parsing stringified NBT data.

Macros

compound

A utility macro for constructing NbtCompounds.

Structs

NbtCompound

The NBT tag compound type which is essentially just a wrapper for a hash map of string keys to tag values.

NbtList

The NBT tag list type which is essentially just a wrapper for a vec of NBT tags.

NbtStructureError

An error associated with the structure of an NBT tag tree. This error represents a conflict between the expected and actual structure of an NBT tag tree.

Enums

NbtReprError

An error associated with the translation of a NBT representation to a concrete type. This can either be a structure error, meaning an error in the structure of the NBT tree, or a custom error, which could occur when converting a tag into a concrete type. Most of the conversion processes in this crate return a NbtStructureError when there is a type mismatch or missing tag.

NbtTag

The generic NBT tag type, containing all supported tag variants which wrap around a corresponding rust type.

Traits

NbtRepr

Defines a type which has a full representation as a NbtCompound.