5 releases (3 stable)

new 2.0.0 Dec 2, 2024
1.1.0 Nov 19, 2023
1.0.0 Oct 27, 2023
0.2.0 Oct 21, 2023
0.1.0 Jul 2, 2023

#51 in Games

Download history 6/week @ 2024-09-23

264 downloads per month

MIT license

58KB
1K SLoC

mcnbt

Read and write NBT files.

docs.rs Crates.io Website

Installation

cargo add mcnbt

Examples

Reading NBT data.

use mcnbt::{ByteOrder, Tag};

let tag = Tag::from_bytes(
    include_bytes!("../examples/hello_world.nbt"), // file to read
    ByteOrder::BigEndian // Java Edition uses big endian byte order
);
println!("{:#?}", tag);

Writing NBT data.

use mcnbt::{ByteOrder, Tag};

let tag = mcnbt::nbt![
    Tag::Int(Some("foo".to_string()), 42),
    Tag::List(Some("bar".to_string()), vec![
        Tag::String(None, "Hello".to_string()),
        Tag::String(None, "World".to_string()),
    ]),
    Tag::ByteArray(Some("baz".to_string()), vec![
        -8,
        -6,
        -4,
        -2,
        0,
        2,
        4,
        6,
        8,
    ]),
];
println!("{:#?}", tag.to_bytes(ByteOrder::LittleEndian));

Using the CLI

cargo install mcnbt
Usage: nbt [OPTIONS] <path>

Arguments:
  <path>  The path to the NBT file

Options:
  -L, --little-endian  Use little endian byte order
  -h, --help           Print help
  -V, --version        Print version

Using the Web

The web directory conatains a web interface which uses mcnbt in the back-end. See it in action here.

Preview

Using serde

cargo add -F serde mcnbt
use mcnbt::Tag;
use serde_json::Value;

let data = Tag::Compound(
    Some("".to_string()),
    vec![
        Tag::String(
            Some("foo".to_string()),
            "Hello World".to_string()
        ),
        Tag::List(
            Some("bar".to_string()),
            vec![
                Tag::Byte(None, 1),
                Tag::Byte(None, 2),
                Tag::Byte(None, 3),
            ]
        )
    ]
);

assert_eq!(
    serde_json::to_string(&data).unwrap(),
    serde_json::to_string(
        &serde_json::json!({
            "type": "compound",
            "name": "",
            "payload": [
                {
                    "type": "string",
                    "name": "foo",
                    "payload": "Hello World"
                },
                {
                    "type": "list",
                    "name": "bar",
                    "payload": [
                        {
                            "type": "byte",
                            "name": null,
                            "payload": 1
                        },
                        {
                            "type": "byte",
                            "name": null,
                            "payload": 2
                        },
                        {
                            "type": "byte",
                            "name": null,
                            "payload": 3
                        }
                    ]
                }
            ]
        })
    ).unwrap()
);

Resources

Here are some websites explaining the NBT file format that have been used for the development of this library.

Contributing

Running Tests

cargo test --all-features
#          ^^^^^^^^^^^^^^ important

Dependencies

~0.4–1.3MB
~26K SLoC