Skip to content
Last Updated
Mar 28, 2025, 03:08

Game Data ​

npm versionDownloadsInstall sizenpmBuild Status

Provides functions to parse Minecraft game data like level data, server data.

Usage ​

Save/World Data Loading ​

Read the level info from a buffer.

ts
import { WorldReader, LevelDataFrame } from '@xmcl/game-data'
const worldSaveFolder: string;
const reader: WorldReader = await WorldReader.create(worldSaveFolder);
const levelData: LevelDataFrame = await reader.getLevelData();

Preview Read the region data, this feature is not tested yet, but the api will look like this

ts
import { WorldReader, RegionDataFrame, RegionReader } from "@xmcl/game-data";
const worldSaveFolder: string;
const reader: WorldReader = await WorldReader.create(worldSaveFolder);
const chunkX: number;
const chunkZ: number;
const region: RegionDataFrame = await reader.getRegionData(chunkX, chunkZ);

Some Important Concepts ​

These concept might help you to understand how to use the API.

Level ​

The metadata of one Minecraft save. It contains the info like when the world is created, what is the name of it, or other metadata.

In code, they are represented by LevelDataFrame.

Region ​

The Minecraft blocks data are stored in region file (.mca). One region contains 16 sections. Each section contains 16x16x16 blockstates, biome, entities, tileentities and other data.

For the Minecraft version < 1.13, the mca NBT data store the global blockstate ids in Data and Blocks fields.

For the Minecraft version >= 1.13, the mca NBT data store the local blockstate ids in BlockStates and a mapping to map the local blockstate ids to BlockState object.

In-Chunk Coord ​

One chunk (section) in region contains 4096 (16x16x16) blockstates, and they are indexed by [0, 4096). The mapping from x, y, z to index is (x, y, z) -> y << 8 | z << 4 | x.

Read and Write Server Info ​

ts
import { readInfo, writeInfo, ServerInfo } from "@xmcl/game-data";

const seversDatBuffer: Buffer; // this is the servers.dat under .minecraft folder
const infos: ServerInfo[] = await readServerInfo(seversDatBuffer);
const info: ServerInfo = infos[0];

// info.ip -> server ip
// info.name -> server name

🧾 Classes ​

🤝 Interfaces ​

🗃️ Namespaces ​

🏳️ Enums ​

🏭 Functions ​

getCoordFromIndex ​

ts
getCoordFromIndex(index: number): { x: number; y: number; z: number }

Get in-chunk coordination from chunk index

Parameters ​

  • index: number The index number in chunk

Return Type ​

  • { x: number; y: number; z: number }

Defined in: packages/game-data/level.ts:215

getIndexInChunk ​

ts
getIndexInChunk(x: number, y: number, z: number): ChunkIndex

Get chunk index from position. All x, y, z should be in range [0, 16)

Parameters ​

  • x: number The position x. Should be in range [0, 16)
  • y: number The position y. Should be in range [0, 16)
  • z: number The position z. Should be in range [0, 16)

Return Type ​

  • ChunkIndex

Defined in: packages/game-data/level.ts:207

readServerInfo ​

ts
readServerInfo(buff: Uint8Array): Promise<ServerInfo[]>

Read the server information from the binary data of .minecraft/server.dat file, which stores the local known server host information.

Parameters ​

  • buff: Uint8Array The binary data of .minecraft/server.dat

Return Type ​

  • Promise<ServerInfo[]>

Defined in: packages/game-data/serverDat.ts:30

readServerInfoSync ​

ts
readServerInfoSync(buff: Uint8Array): ServerInfo[]

Read the server information from the binary data of .minecraft/server.dat file, which stores the local known server host information.

Parameters ​

  • buff: Uint8Array The binary data of .minecraft/server.dat

Return Type ​

  • ServerInfo[]

Defined in: packages/game-data/serverDat.ts:51

writeServerInfo ​

ts
writeServerInfo(infos: ServerInfo[]): Promise<Uint8Array>

Write the information to NBT format used by .minecraft/server.dat file.

Parameters ​

  • infos: ServerInfo[] The array of server information.

Return Type ​

  • Promise<Uint8Array>

Defined in: packages/game-data/serverDat.ts:40

writeServerInfoSync ​

ts
writeServerInfoSync(infos: ServerInfo[]): Uint8Array

Write the information to NBT format used by .minecraft/server.dat file.

Parameters ​

  • infos: ServerInfo[] The array of server information.

Return Type ​

  • Uint8Array

Defined in: packages/game-data/serverDat.ts:61

⏩ Type Aliases ​

ChunkIndex ​

ts
ChunkIndex: number

The chunk index is a number in range [0, 4096), which is mapped position from (0,0,0) to (16,16,16) inside the chunk.

Defined in: packages/game-data/level.ts:197

LegacyRegionSectionDataFrame ​

ts
LegacyRegionSectionDataFrame: { Add: number[]; BlockLight: number[]; Blocks: number[]; Data: number[]; SkyLight: number[]; Y: number }

Defined in: packages/game-data/level.ts:580

NewRegionSectionDataFrame ​

ts
NewRegionSectionDataFrame: { block_states?: { data: bigint[]; palette: BlockStateData[] }; BlockLight: number[]; BlockStates?: bigint[]; Data: number[]; Palette?: BlockStateData[]; SkyLight: number[]; Y: number }

Defined in: packages/game-data/level.ts:588

RegionSectionDataFrame ​

ts
RegionSectionDataFrame: LegacyRegionSectionDataFrame | NewRegionSectionDataFrame

Defined in: packages/game-data/level.ts:600