Crate ussr_nbt

Crate ussr_nbt 

Source
Expand description

§ussr-nbt

A very fast and versatile NBT library for Minecraft: Java Edition.

Some features of this library:

  • A borrow module for avoiding most allocations and all copying.
  • An API that differentiates between full (Nbt) and partial (Compound, Tag, List) NBT values.
  • Support for TAG_Long_Array introduced in Minecraft 1.12.
  • Support for the modified UTF-8 encoding of strings that Java uses.

§Usage

use std::net::TcpStream;

use ussr_nbt::owned::*;

fn main() {
    let mut conn: TcpStream = TcpStream::connect("127.0.0.1:25565").unwrap();
    let nbt: Nbt = Nbt::read(&mut conn).unwrap();
    println!("{nbt:#?}");
}

For more examples see the examples directory.

§Notes

  • Modified UTF-8 validation and conversion is not done during parsing.
  • Endianness is not swapped during parsing.
  • Bytes are unsigned.
  • When serializing, this library will only write up to i32::MAX elements for lists/arrays and up to u16::MAX bytes for strings. This is due to the fact that the NBT specification uses i32 for lengths of lists/arrays and u16 for lengths of strings.

§Roadmap

  • nbt! macro for constructing NBT values.
  • serde support.
  • Some macro for checking (and binding) NBT patterns.
  • SNBT formatting in Debug/Display.
  • Perhaps iterators for RawVec and RawSlice, although converting in bulk is more efficient.

§Performance comparison

Deserialization:

  1. simdnbt::borrow
  2. ussr-nbt::borrow
  3. simdnbt::owned
  4. ussr-nbt::owned
  5. shen-nbt5
  6. azalea-nbt
  7. graphite_binary

Serialization benchmarks violin plot

Serialization:

  1. simdnbt::owned
  2. azalea-nbt
  3. ussr-nbt::borrow
  4. ussr-nbt::owned*
  5. simdnbt::borrow*
  6. graphite_binary
  7. shen-nbt5

*Note: numbers 4 and 5 are very close.

Deserialization benchmarks violin plot

Plots are generated using criterion.

§Cargo features

For swapping endianness in bulk this library uses SIMD instructions. By default, it will detect CPU features and use the fastest available instruction set. However, if you disable the rt-cpu-feat feature, it will always use the fallback implementation, which is actually the most performant implementation if compiled with -C target-cpu=native. Note that this flag will make the resulting binary not be able to run on CPUs other than the one it was compiled on.

Modules§

borrow
This module contains the owned NBT implementation. It is significantly faster than the crate::owned module, but requires you to keep a reference to the data.
endian
Lazy wrappers around collections that contain information about endianness.
mutf8
Support for modified UTF-8 encoding of strings.
num
A trait for swapping the endianness of a number.
owned
This module contains the owned NBT implementation.

Structs§

ReadOpts
Options for reading NBT data.
WriteOpts
Options for writing NBT data.

Enums§

NbtReadError
Errors that can occur while reading NBT data.

Constants§

TAG_BYTE
TAG_BYTE_ARRAY
TAG_COMPOUND
TAG_DOUBLE
TAG_END
TAG_FLOAT
TAG_INT
TAG_INT_ARRAY
TAG_LIST
TAG_LONG
TAG_LONG_ARRAY
TAG_SHORT
TAG_STRING