A TypeScript library for working with NBT data
Contents
npm install @mcstatic/nbtsimport { read, readSync, write, writeSync, Tag } from '@mcstatic/nbts'The Named Binary Tag (NBT) file format is an extremely simple and efficient structured binary format used by the Minecraft game for a variety of things.
nbts currently only supports the NBT specification as used by Minecraft: Java Edition. The changes to the NBT specification in Minecraft: Bedrock Edition are not currently implemented.
The changes to Network NBT (Java Edition) made as of server protocol version 764 are also not currently implemented.
byte(value: number, name?: string): Tag<number>| Name | Type | Description |
|---|---|---|
| value | number | A single signed byte (-128 <= x < 128) |
| name | string? | The name of this tag |
short(value: number, name?: string): Tag<number>| Name | Type | Description |
|---|---|---|
| value | number | A single signed 16-bit integer (-32,768 <= x < 32,768) |
| name | string? | The name of this tag |
int(value: number, name?: string): Tag<number>| Name | Type | Description |
|---|---|---|
| value | number | A single signed 32-bit integer (-2,147,483,648 <= x < 2,147,483,648) |
| name | string? | The name of this tag |
long(value: bigint, name?: string): Tag<bigint>| Name | Type | Description |
|---|---|---|
| value | bigint | A single signed 64-bit integer (-9,223,372,036,854,775,808 <= x < 9,223,372,036,854,775,808) |
| name | string? | The name of this tag |
float(value: number, name?: string): Tag<number>| Name | Type | Description |
|---|---|---|
| value | number | A single-precision floating-point number |
| name | string? | The name of this tag |
double(value: number, name?: string): Tag<number>| Name | Type | Description |
|---|---|---|
| value | number | A double-precision floating-point number |
| name | string? | The name of this tag |
byteArray(value: Buffer, name?: string): Tag<Buffer>| Name | Type | Description |
|---|---|---|
| value | Buffer | A list of signed bytes (-128 <= x < 128) |
| name | string? | The name of this tag |
string(value: string, name?: string): Tag<string>| Name | Type | Description |
|---|---|---|
| value | string | A variable-length string |
| name | string? | The name of this tag |
list(value: Tag[], name?: string): Tag<Tag[]>| Name | Type | Description |
|---|---|---|
| value | Tag[] | A variable-length list of tags. All tags in the list must be the same type and must not be named. |
| name | string? | The name of this tag |
Tag.list([
Tag.float(123.456),
Tag.float(234.576),
Tag.float(345.678)
], 'list of floats')Tag.list([
Tag.list([
Tag.float(123.456),
Tag.float(234.576),
Tag.float(345.678)
]),
Tag.list([
Tag.string('this'),
Tag.string('is'),
Tag.string('a'),
Tag.string('list!')
])
], 'nested lists')compound(value: Tag[], name?: string): Tag<Tag[]>| Name | Type | Description |
|---|---|---|
| value | Tag[] | A variable-length list of tags. All tags in the list must be named, but can be different types. |
| name | string? | The name of this tag |
Tag.compound([
Tag.string('Bananarama', 'name')
], 'a simple compound tag')const root = Tag.compound([
Tag.string('Bananarama', 'name'),
Tag.byteArray(Buffer.from([1, 2, 3, 4, 5]), 'bytes'),
Tag.compound([
Tag.long(12345n, 'a long'),
Tag.longArray([12n, 34n, 56n], 'some longs'),
Tag.list([
Tag.string('this'),
Tag.string('is'),
Tag.string('a'),
Tag.string('list!')
], 'a list in a nested compound')
], 'a nested compound tag')
], 'hello world')intArray(value: number[], name?: string): Tag<number[]>| Name | Type | Description |
|---|---|---|
| value | number[] | A list of signed 32-bit integers (-2,147,483,648 <= x < 2,147,483,648) |
| name | string? | The name of this tag |
longArray(value: bigint[], name?: string): Tag<bigint[]>| Name | Type | Description |
|---|---|---|
| value | bigint[] | A list of signed 64-bit integers (-9,223,372,036,854,775,808 <= x < 9,223,372,036,854,775,808) |
| name | string? | The name of this tag |
When writing NBT data to a file, the root tag must be a COMPOUND tag.
Various output formats are supported, as detailed below in NBTWriteOptions.
write(root: Tag, options: NBTWriteOptions): Promise<void>writeSync(root: Tag, options: NBTWriteOptions): voidtype NBTWriteOptions = {
filename: string
format?: "nbt" | "snbt" | "json" | "js" | undefined
compress?: boolean | undefined
}| Name | Type | Description |
|---|---|---|
| filename | string | The path to write NBT data to |
| format | nbt, snbt, json, js | (Optional) The format of the data being read. If not provided, this will be inferred based on file extension. Defaults to nbt. |
| compress | boolean | (Optional) Whether to use gzip compression. Only used with nbt format. Defaults to true. |
read(filename: string, options?: NBTReadOptions): Promise<Tag>read(filename: string, options?: NBTReadOptions): Tagtype NBTReadOptions = {
format?: 'nbt' | 'json'
}| Name | Type | Description |
|---|---|---|
| format | nbt, snbt, json | (Optional) The format of the data being read. If not provided, this will be inferred from the file extension. Defaults to nbt if it cannot be inferred. |
The following are possible future enhancements to be made to nbts:
- Add support for reading snbt data
- Add support for protocol versions >= 764
- Add support for Minecraft: Bedrock Edition NBT data
- Add a command-line interface for converting files between NBT and other formats