Crate fastnbt

fastnbt aims for fast deserializing and serializing of NBT data from Minecraft: Java Edition. This format is used by the game to store various things, such as the world data and player inventories.

• For documentation and examples of serde (de)serialization, see ser and de.
• For a serde_json-like Value type see Value.
• To easily create values, see the nbt macro.
• For NBT array types see ByteArray, IntArray, and LongArray.
• For zero-copy NBT array types see borrow.

Both this and related crates are under one fastnbt Github repository.

[dependencies]
fastnbt = "2"

Byte, Int and Long array types

There are three array types in NBT. To capture these, use ByteArray, IntArray, and LongArray. In order to preserve the information from the original NBT, these NBT types do not (de)serialize straight from/into serde sequences like Vec. Without these types, it is not possible to tell if some data came from a NBT List or an NBT Array.

A limitation of these array types is that they cannot be used with serde’s untagged enums. If this is important to you please open an issue.

Use these in your own data structures. They all implement Deref for dereferencing into a slice`.

For versions that borrow their data, see borrow.

An example of deserializing a section of a chunk:

use fastnbt::LongArray;
use serde::Deserialize;

#[derive(Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct Section {
    pub block_states: Option<LongArray>,
    pub y: i8,
}

    let buf: &[u8] = unimplemented!("get a buffer from somewhere");
    let section: Section = fastnbt::from_bytes(buf).unwrap();
    let states = section.block_states.unwrap();

    for long in states.iter() {
        // do something
    }

Example: Player inventory

This example demonstrates printing out a players inventory and ender chest contents from the player dat files found in worlds.

Here we

• use serde’s renaming attributes to have rustfmt conformant field names,
• use lifetimes to save on some string allocations (see de for more info), and
• use the Value type to deserialize a field we don’t know the exact structure of.

 use std::borrow::Cow;
 use fastnbt::error::Result;
 use fastnbt::{from_bytes, Value};
 use flate2::read::GzDecoder;
 use serde::Deserialize;
 use std::io::Read;

 #[derive(Deserialize, Debug)]
 #[serde(rename_all = "PascalCase")]
 struct PlayerDat<'a> {
     data_version: i32,

     #[serde(borrow)]
     inventory: Vec<InventorySlot<'a>>,
     ender_items: Vec<InventorySlot<'a>>,
 }

 #[derive(Deserialize, Debug)]
 struct InventorySlot<'a> {
     // We typically avoid allocating a string here.
     // See `fastnbt::de` docs for more info.
     id: Cow<'a, str>,

     // Also get the less structured properties of the object.
     tag: Option<Value>,

     // We need to rename fields a lot.
     #[serde(rename = "Count")]
     count: i8,
 }

     let args: Vec<_> = std::env::args().skip(1).collect();
     let file = std::fs::File::open(args[0].clone()).unwrap();

     // Player dat files are compressed with GZip.
     let mut decoder = GzDecoder::new(file);
     let mut data = vec![];
     decoder.read_to_end(&mut data).unwrap();

     let player: Result<PlayerDat> = from_bytes(data.as_slice());

     println!("{:#?}", player);

Read based parser

A lower level parser also exists in the stream module that only requires the Read trait on the input. This parser however doesn’t support deserializing to Rust objects directly.

Modules

borrow

This module contains types enabling ‘zero-copy’ capture of the array NBT types. These types retain a reference to the input data when deserializing, meaning the input has to live as long as the deserialized object. This can be hard to manage, but offers potential performance improvements. Measure! Usually the dominating factor in deserialization is decompressing the NBT data.

de

This module contains a serde deserializer. It can do most of the things you would expect of a typical serde deserializer, such as deserializing into:

error

Contains the Error and Result type used by the deserializer.

ser

This module contains a serde serializer for NBT data. This should be able to serialize most structures to NBT. Use to_bytes or to_writer.

stream

Allows streaming of NBT data without prior knowledge of the structure.

Macros

nbt

Produce a Value using JSON/SNBT-like syntax.

Structs

ByteArray

NBT ByteArray that owns its data. This type preserves the exact NBT type when (de)serializing. This dereferences into a i8 slice, so should be usable basically anywhere a slice should be.

DeOpts

Options for customozing deserialization.

IntArray

NBT IntArray that owns its data. This type preserves the exact NBT type when (de)serializing. This dereferences into a i32 slice, so should be usable basically anywhere a slice should be.

LongArray

NBT LongArray that owns its data. This type preserves the exact NBT type when (de)serializing. This dereferences into a i64 slice, so should be usable basically anywhere a slice should be.

Enums

Tag

An NBT tag. This does not carry the value or the name of the data.

Value

Value is a complete NBT value. It owns its data. Compounds and Lists are resursively deserialized. This type takes care to preserve all the information from the original NBT, with the exception of the name of the root compound (which is usually the empty string).

Functions

from_bytes

Deserialize into a T from some NBT data. See the de module for more information.

from_bytes_with_opts

Similar to from_bytes but with options.

to_bytes

Serialize some T into NBT data. See the ser module for more information.

to_value

to_writer

Serialize some T into NBT data. See the ser module for more information.