> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xneon.org/llms.txt
> Use this file to discover all available pages before exploring further.

# @xnlc/nbt: чтение и запись NBT-файлов Minecraft

> TypeScript-библиотека для работы с Named Binary Tag форматом Minecraft. Чтение и запись с автовыводом типов тегов, поддержка gzip/deflate.

`@xnlc/nbt` заменяет `prismarine-nbt` и предоставляет чистый TypeScript API для чтения и записи NBT-файлов Minecraft. Автоматически выводит тип тега по значению JavaScript при записи.

**Версия:** 1.0.1 | **Лицензия:** GPL-3.0 | **Реестр:** [git.xneon.org](https://git.xneon.org/api/packages/MAINER4IK/npm/)

## Установка

<CodeGroup>
  ```bash npm theme={null}
  npm install @xnlc/nbt
  ```

  ```bash pnpm theme={null}
  pnpm add @xnlc/nbt
  ```
</CodeGroup>

## Возможности

* Чтение NBT из Buffer с поддержкой сжатия (gzip, deflate)
* Запись NBT в Buffer с автовыводом типов тегов
* Поддержка всех типов NBT: Byte, Short, Int, Long, Float, Double, ByteArray, String, List, Compound, IntArray, LongArray
* Потоковое увеличение буфера при записи
* Простое API без внешних зависимостей

## Чтение NBT

```ts theme={null}
import { NBTReader } from "@xnlc/nbt";
import * as fs from "node:fs";

const buffer = fs.readFileSync("level.dat");
const reader = new NBTReader(buffer);

// level.dat сжат gzip
const data = reader.read({ compressed: "gzip" });
console.log(data.Data?.Player?.Pos); // [number, number, number]
```

### Параметры чтения

| Опция | Тип | Описание |
| - | - | - |
| `compressed` | `boolean \| "gzip" \| "deflate"` | Автоматически определяет gzip при `true`, явно укажите `"deflate"` для deflate |

Корневой тег всегда должен быть `TAG_Compound`. Если это не так, выбрасывается ошибка.

## Запись NBT

```ts theme={null}
import { NBTWriter } from "@xnlc/nbt";
import * as fs from "node:fs";

const writer = new NBTWriter();

const nbt = {
  Data: {
    DayTime: 1000,
    GameType: 1,
    LevelName: "My World",
    SpawnX: 0,
    SpawnY: 64,
    SpawnZ: 0,
    Hardcore: 0,
    version: 19133,
    DataVersion: 3465,
    // Long: bigint
    Time: 1000n,
    // Byte Array: массив чисел от -128 до 127
    HeightMap: new Array(256).fill(0),
    // Int Array
    ServerBrands: ["vanilla"],
    // List: { type, values }
    Sections: {
      type: 10, // TAG_Compound
      values: []
    }
  }
};

const buffer = writer.write(nbt, { compressed: "gzip" });
fs.writeFileSync("level.dat", buffer);
```

### Автовывод типов при записи

`NBTWriter` автоматически определяет тип NBT-тега по значению JavaScript:

| Значение JS | Условия | Тип NBT |
| - | - | - |
| `number` (целое) | -128 до 127 | `TAG_Byte` |
| `number` (целое) | -32768 до 32767 | `TAG_Short` |
| `number` (целое) | остальные | `TAG_Int` |
| `number` (дробное) | любое | `TAG_Float` |
| `bigint` | любое | `TAG_Long` |
| `string` | любое | `TAG_String` |
| `number[]` | все в диапазоне byte | `TAG_Byte_Array` |
| `number[]` | остальные | `TAG_Int_Array` |
| `bigint[]` | любые | `TAG_Long_Array` |
| `{ type, values }` | | `TAG_List` |
| `object` (остальные) | | `TAG_Compound` |

### Параметры записи

| Опция | Тип | Описание |
| - | - | - |
| `compressed` | `boolean \| "gzip" \| "deflate"` | Сжатие результата |
| `rootName` | `string` | Имя корневого тега (по умолчанию пустая строка) |

## Примеры использования

### Чтение servers.dat

Файл `servers.dat` в папке .minecraft хранит список серверов. Он записан в формате NBT без сжатия:

```ts theme={null}
import { NBTReader } from "@xnlc/nbt";
import * as fs from "node:fs";
import * as path from "node:path";

const serversDat = path.join(process.env.APPDATA, ".minecraft", "servers.dat");
const buffer = fs.readFileSync(serversDat);

const reader = new NBTReader(buffer);
const data = reader.read(); // без сжатия

const servers = data.servers.values; // NBTList
for (const server of servers) {
  console.log(`${server.name}: ${server.ip}`);
}
```

### Чтение level.dat

Файл `level.dat` хранит параметры мира и сжат с помощью gzip:

```ts theme={null}
import { NBTReader } from "@xnlc/nbt";
import * as fs from "node:fs";

const buffer = fs.readFileSync("saves/MyWorld/level.dat");

const reader = new NBTReader(buffer);
const data = reader.read({ compressed: "gzip" });

console.log("Имя мира:", data.Data?.LevelName);
console.log("Версия данных:", data.Data?.DataVersion);
console.log("Режим:", data.Data?.GameType);
console.log("Сложность:", data.Data?.Difficulty);
```

### Запись player.dat

```ts theme={null}
import { NBTWriter } from "@xnlc/nbt";

const writer = new NBTWriter();

const player = {
  Pos: [100.5, 64.0, -200.5],        // TAG_List Double (автовывод: Float)
  Rotation: [90.0, 0.0],              // TAG_List Float
  Health: 20,                          // TAG_Int
  HurtTime: 0,                         // TAG_Short (0 в диапазоне Short)
  OnGround: 1,                         // TAG_Byte
  Inventory: {
    type: 10,                          // TAG_Compound
    values: []
  }
};

// Явное указание типа: для Double используйте строки или другие методы
// Примечание: текущая версия выводит Float для дробных чисел

const buffer = writer.write(player, { compressed: "gzip", rootName: "" });
fs.writeFileSync("player.dat", buffer);
```

## Типы тегов

```ts theme={null}
import { TagType } from "@xnlc/nbt";

// Значения enum:
// TAG_End = 0, TAG_Byte = 1, TAG_Short = 2, TAG_Int = 3,
// TAG_Long = 4, TAG_Float = 5, TAG_Double = 6,
// TAG_Byte_Array = 7, TAG_String = 8, TAG_List = 9,
// TAG_Compound = 10, TAG_Int_Array = 11, TAG_Long_Array = 12
```

```ts theme={null}
import type { NBTValue, NBTCompound, NBTList } from "@xnlc/nbt";

// NBTValue = number | bigint | string | NBTValue[] | NBTList | { [key: string]: NBTValue } | null
// NBTCompound = { [key: string]: NBTValue }
// NBTList = { type: TagType, values: NBTValue[] }
```

<Note>
  В отличие от `prismarine-nbt`, `@xnlc/nbt` не использует дерево с именами и значениями. NBTCompound это обычный объект с ключами, а тип тега восстанавливается при записи по значению.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.