typescript.md

はじめに（TypeScript）

Node.js 20以上が必要です。ESM専用です。 型定義を同梱しています。TypeScriptから使う場合は、ビルドに使っている5.7以上を推奨します。

導入

Releasesからspring-nbt-library-<版>.tgzを落とします。 以下の<版>は、使うリリースの版（Releasesのタグ名から先頭のvを除いたもの）に読み替えてください。

npm install ./spring-nbt-library-<版>.tgz

これでnode_modulesへ入り、通常のパッケージと同じようにimportできます。 型定義（.d.ts）も含まれているので補完が効きます。

取り込み方は2通りあります。どちらでも構いません。

// まとめて取る
import { NbtCompound, RegionFile, BlockState } from "spring-nbt-library";

// レイヤごとに取る（他言語のモジュール構成に対応する）
import { NbtCompound } from "spring-nbt-library/nbt";
import { RegionFile } from "spring-nbt-library/anvil";
import { BlockState } from "spring-nbt-library/world";

package.jsonには次のように記録されます。

{
  "dependencies": {
    "spring-nbt-library": "file:spring-nbt-library-<版>.tgz"
  }
}

i64はbigint

TypeScriptのnumberは2^53を超える整数を表せません。 TAG_LongとTAG_Long_Arrayだけbigintを使います（adr/0007）。 他の整数型はnumberのままです。

compound.set("time", new NbtLong(449n));   // nを付ける

NBTファイルを読む

import { readFile, NbtCompound } from "spring-nbt-library";

// 圧縮方式（Gzip / Zlib / 無圧縮）は自動で判定される
const named = readFile("level.dat");
const data = named.tag.getCompound("Data");

console.log(data.getString("LevelName"));
console.log(data.getInt("DataVersion"));

型が違えばUNEXPECTED_TAG_TYPEの例外になります。 キーが無いかもしれないときはopt*を使います（無ければundefined）。

書く

import { writeFile, NamedTag, NbtCompound, NbtInt, NbtString, Compression } from "spring-nbt-library";

const root = new NbtCompound();
root.set("name", new NbtString("SpringNBTLibrary"));
root.set("count", new NbtInt(42));

writeFile("out.nbt", new NamedTag("", root), { compression: Compression.Gzip });

ワールドのブロックを読む

import { MinecraftWorld } from "spring-nbt-library";

const world = MinecraftWorld.open(worldPath);

try {
  const overworld = world.dimension("minecraft:overworld");

  if (overworld !== undefined) {
    // 絶対座標。リージョンとチャンクの解決は内部で行う
    const block = overworld.getBlock(100, 64, -200);
    console.log(String(block));   // minecraft:grass_block[snowy=false]
  }
} finally {
  world.close();
}

ブロックを書き換える

import { BlockState, MinecraftWorld } from "spring-nbt-library";

const world = MinecraftWorld.open(worldPath, { writable: true });

try {
  const overworld = world.dimension("minecraft:overworld")!;
  overworld.setBlock(100, 64, -200, BlockState.parse("minecraft:stone"));
  overworld.flush();   // ここで初めてディスクへ書かれる
} finally {
  world.close();
}

Minecraftを終了してから実行してください。 TypeScript版はNodeにファイルロックの手段が無いため、session.lockは確認しません（adr/0008）。 起動していないことは呼び出し側で保証してください。

ブロックを置き換えてもHeightmapsと光源は再計算されません（adr/0004）。

次に読むもの

• ガイド: 目的別の使い方
• API対応表: 他言語版との対応
• エラーと安全上限