# nbt-ts

> An easy to use encoder and decoder for the NBT format

Latest version **1.3.6** (published 2023-11-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install nbt-ts
pnpm add nbt-ts
yarn add nbt-ts
bun add nbt-ts
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.6 |
| Published | 2023-11-16 |
| First published | 2019-03-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 49.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 28 |
| Author | Janis Pritzkau |
| Maintainers | janispritzkau |
| Keywords | nbt, minecraft, typescript, snbt |

## Links

- npm: https://www.npmjs.com/package/nbt-ts
- Repository: https://github.com/janispritzkau/nbt-ts
- Homepage: https://github.com/janispritzkau/nbt-ts#readme
- Issues: https://github.com/janispritzkau/nbt-ts/issues
- npm.io page: https://npm.io/package/nbt-ts

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.3.6 (latest) — 2023-11-16
- 2.0.2 (next) — 2021-07-31
- 1.3.5 — 2022-08-20
- 1.3.4 — 2021-07-31
- 2.0.1 — 2021-03-24
- 2.0.0 — 2021-03-24
- 1.3.3 — 2019-09-25
- 1.3.1 — 2019-09-11
- 1.3.0 — 2019-09-02
- 1.2.5 — 2019-09-01
- 1.2.4 — 2019-09-01
- 1.2.3 — 2019-08-25
- 1.2.2 — 2019-08-24
- 1.2.1 — 2019-08-24
- 1.2.0 — 2019-08-23
- … 12 more at https://npm.io/package/nbt-ts/versions

## README

# nbt-ts

> **⚠️ This library has not been maintained for some time. Please use it with caution or switch to another implementation!**

[![npm](https://img.shields.io/npm/v/nbt-ts.svg)](https://www.npmjs.com/package/nbt-ts)
[![downloads](https://img.shields.io/npm/dm/nbt-ts.svg)](https://www.npmjs.com/package/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
const { encode, decode, Byte, Short, Int, Float } = require("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
const { stringify, parse } = require("nbt-ts")

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

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

## 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)

---
_Source: https://npm.io/package/nbt-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._