npm package: @ironm00n/nbt-ts
Description: An easy to use encoder and decoder for the NBT format
Author: Janis Pritzkau
Latest version: 1.4.1

# @ironm00n/nbt-ts

[![npm](https://img.shields.io/npm/v/@ironm00n/nbt-ts.svg)](https://www.npmjs.com/package/@ironm00n/nbt-ts)
[![downloads](https://img.shields.io/npm/dm/@ironm00n/nbt-ts.svg)](https://www.npmjs.com/package/@ironm00n/nbt-ts)

An easy to use encoder and decoder for the [NBT format](https://wiki.vg/NBT).

NBT compound tags are represented as plain JavaScript objects. The `Byte`, `Short`,
`Int` and `Float` number types are wrapped in custom classes since JavaScript
does not support them directly.

Node 10.4 or higher is required for BigInts, which are used to represent 64 bit integers.

## Usage

```js
import { encode, decode, Byte, Short, Int, Float } from "@ironm00n/nbt-ts";

const buffer = encode("root", {
	byte: new Byte(-1),
	short: new Short(65535),
	int: new Int(-2147483648),
	long: 0x7fffffffffffffffn,
	float: new Float(0.75),
	double: 0.1 + 0.2,
	string: "Hello world",
	list: ["item 1", "item 2"],
	compound: {
		byteArray: Buffer.from([0x80, 0x40, 0x20]),
		// Int8Array does work here too
		intArray: new Int32Array([1, 2, 3, 4]),
		longArray: new BigInt64Array([1n, 2n, 3n, 4n]),
	},
});

decode(Buffer.from("02000973686F7274546573747FFF", "hex"));
// → { name: 'shortTest', value: Short { value: 32767 }, length: 14 }

// Encode unnamed tag
encode(null, "a");
// → <Buffer 08 00 01 61>

// Decode unnamed tag
decode(Buffer.from("08000161", "hex"), { unnamed: true });
// → { name: null, value: 'a', length: 4 }
```

Note that the `encode` function accepts both unsigned numbers such as `255` and signed
numbers like `-1` which are essentially the same in the case of a 8 bit integer.
However when decoded, they will always have the signed representation. If you want
to convert a number to the unsigned representation, you might do something like this:

```js
value & 0xff; // for bytes
value & 0xffff; // for shorts
value >>> 0; // for ints
BigInt.asUintN(64, value); // for longs
// or
value & 0xffffffffffffffffn;
```

## SNBT

The NBT format also has a more user-friendly variant in plain text. This format
is referred to as **SNBT**, short for **stringified NBT**.
Here are all the types represented in SNBT:

```
{
    byte: 1b, short: 1s, int: 1, long: 1l,
    float: 0.5f, double: 0.5,
    string: "Hello world",
    list: [{}, {}],
    compound: {
        byteArray: [B; 128, 64, 32],
        intArray: [I; 1, 2, 3, 4],
        longArray: [L; 1, 2, 3, 4]
    }
}
```

Here is an example how you can stringify or parse SNBT:

```js
import { stringify, parse } from "ironm00n/nbt-ts";

const tag = parse(`{'Flying' :1b , unquoted: hello} `);
// → { Flying: Byte { value: 1 }, unquoted: 'hello' }

stringify(tag);
// → '{Flying:1b,unquoted:"hello"}'
```

## Changes in this fork

- Added support for indexed arrays in SNBT

## Related projects

- [`mc-chat-format`](https://github.com/janispritzkau/mc-chat-format).
  Converts and formats Minecraft's JSON Chat components.
- [`mcproto`](https://github.com/janispritzkau/mcproto) (Minecraft protocol implementation)
- [`rcon-client`](https://github.com/janispritzkau/rcon-client)