java.md

はじめに（Java）

Java 21 (LTS)以上が必要です。

導入

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

Gradleならjarをlibs/へ置いて読み込みます。

dependencies {
    implementation files("libs/spring-nbt-library-<版>.jar")
}

Mavenならローカルリポジトリへ入れてから依存に書きます。

mvn install:install-file \
  -Dfile=spring-nbt-library-<版>.jar \
  -DgroupId=io.github.scriptarts \
  -DartifactId=spring-nbt-library \
  -Dversion=<版> -Dpackaging=jar

<dependency>
  <groupId>io.github.scriptarts</groupId>
  <artifactId>spring-nbt-library</artifactId>
  <version><版></version>
</dependency>

クラスパスへ直接置くこともできます。

java -cp spring-nbt-library-<版>.jar:. YourApp

NBTファイルを読む

import io.github.scriptarts.springnbt.nbt.*;
import java.nio.file.Path;

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

System.out.println(data.getString("LevelName"));
System.out.println(data.getInt("DataVersion"));

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

本ライブラリの例外SpringNbtExceptionは非検査例外です。 シグネチャを他言語版と揃えるため、検査例外は使いません（adr/0005）。

書く

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

NbtIo.writeFile(Path.of("out.nbt"), new NamedTag("", root),
        new NbtWriteOptions().setCompression(Compression.GZIP));

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

import io.github.scriptarts.springnbt.world.*;

try (MinecraftWorld world = MinecraftWorld.open(worldPath)) {
    Dimension overworld = world.dimension("minecraft:overworld");

    if (overworld != null) {
        // 絶対座標。リージョンとチャンクの解決は内部で行う
        BlockState block = overworld.getBlock(100, 64, -200);
        System.out.println(block);   // minecraft:grass_block[snowy=false]
    }
}

ブロックを書き換える

書き込みは明示的に許可したときだけ行えます。

WorldOpenOptions options = new WorldOpenOptions().setWritable(true);

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

Minecraftを終了してから実行してください。 起動中のワールドへ書き込むとデータがおかしくなります。 Java版はsession.lockを確認して防いでいます（adr/0008）。

ブロックを置き換えてもHeightmapsと光源は再計算されません（adr/0004）。 Chunk.clearHeightmaps() / invalidateLighting()でゲーム側に再計算させてください。

次に読むもの

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