Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/janispritzkau/nbt-ts
An easy to use encoder and decoder for the NBT format
https://github.com/janispritzkau/nbt-ts
decoder encoder javascript minecraft nbt typescript
Last synced: 5 days ago
JSON representation
An easy to use encoder and decoder for the NBT format
- Host: GitHub
- URL: https://github.com/janispritzkau/nbt-ts
- Owner: janispritzkau
- Created: 2019-08-06T08:23:09.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-11-16T17:19:25.000Z (about 1 year ago)
- Last Synced: 2025-01-11T18:14:18.587Z (13 days ago)
- Topics: decoder, encoder, javascript, minecraft, nbt, typescript
- Language: TypeScript
- Homepage:
- Size: 61.5 KB
- Stars: 27
- Watchers: 4
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# nbt-ts
> **⚠️ This library has not been maintained for some time. Please use it with caution or switch to another implementation!**
[](https://www.npmjs.com/package/nbt-ts)
[](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")
// →
// 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)