Game Data

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

Usage

Save/World Data Loading

Read the level info from a buffer.

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

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

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

ServerInfoServersDataWorldReader

🤝 Interfaces

AdvancementDataFrameBlockStateDataItemStackDataFrameLevelDataFramePlayerDataFrameRegionDataFrameTileEntityDataFrame

🗃️ Namespaces

RegionReader

🏳️ Enums

GameType

🏭 Functions

getCoordFromIndex

getCoordFromIndex(index: number): Object

Get in-chunk coordination from chunk index

Parameters

• index: number The index number in chunk

Return Type

• Object

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

getIndexInChunk

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

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

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

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

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

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

LegacyRegionSectionDataFrame: Object

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

NewRegionSectionDataFrame

NewRegionSectionDataFrame: Object

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

RegionSectionDataFrame

RegionSectionDataFrame: LegacyRegionSectionDataFrame | NewRegionSectionDataFrame

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