Skip to content

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): 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

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: Object

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

NewRegionSectionDataFrame

ts
NewRegionSectionDataFrame: Object

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

RegionSectionDataFrame

ts
RegionSectionDataFrame: LegacyRegionSectionDataFrame | NewRegionSectionDataFrame

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

Released under the MIT License.