The MCWorld class provides comprehensive access to Minecraft Bedrock world files (.mcworld), including level data, chunks, entities, and pack references.
Constructor
The constructor is private. Use static factory methods to create instances.
Static Methods
MCWorld.ensureMCWorldOnFolder
(folder: IFolder, project?: Project, handler?: IEventHandler<MCWorld, MCWorld>) => Promise<MCWorld | undefined>
Creates or retrieves an MCWorld instance from a folder.const world = await MCWorld.ensureMCWorldOnFolder(worldFolder, project);
MCWorld.ensureOnFile
(file: IFile, project?: Project, handler?: IEventHandler<MCWorld, MCWorld>) => Promise<MCWorld | undefined>
Creates or retrieves an MCWorld instance from a .mcworld file.const world = await MCWorld.ensureOnFile(mcworldFile, project);
MCWorld.ensureOnItem
(projectItem: ProjectItem) => Promise<MCWorld | undefined>
Creates or retrieves an MCWorld instance from a project item.const world = await MCWorld.ensureOnItem(projectItem);
Properties
World name from levelname.txt or level.dat.console.log(world.name); // "My World"
world.name = "New Name";
levelData
WorldLevelDat | undefined
Level.dat data containing world settings, spawn location, and game rules.const spawn = world.levelData?.spawnX;
chunks
Map<number, Map<number, Map<number, WorldChunk>>>
Nested map structure: dimension -> X -> Z -> WorldChunk.const overworldChunks = world.chunks.get(0); // Overworld dimension
const chunk = world.chunks.get(0)?.get(5)?.get(10); // Chunk at (5, 10)
Total number of chunks loaded in this world.console.log(`World has ${world.chunkCount} chunks`);
LevelDB database containing world data.
X coordinate of world spawn point.
Y coordinate of world spawn point.
Z coordinate of world spawn point.
Minimum X coordinate (in blocks) of loaded chunks.
Maximum X coordinate (in blocks) of loaded chunks.
Minimum Z coordinate (in blocks) of loaded chunks.
Maximum Z coordinate (in blocks) of loaded chunks.
worldBehaviorPacks
IPackRegistration[] | undefined
Behavior packs attached to this world.
worldResourcePacks
IPackRegistration[] | undefined
Resource packs attached to this world.
actorsById
{ [identifier: string]: ActorItem }
Map of actors/entities by their unique identifier.
Loading Methods
loadMetaFiles
(force?: boolean) => Promise<void>
Loads world metadata files (level.dat, pack references, manifest).await world.loadMetaFiles();
loadLevelDb
(force?: boolean, options?: IWorldProcessingOptions) => Promise<boolean>
Loads the LevelDB database and parses chunk data.await world.loadLevelDb(false, {
maxNumberOfRecordsToProcess: 100000,
progressCallback: (phase, current, total) => {
console.log(`${phase}: ${current}/${total}`);
}
});
loadFromLevelDb
(levelDb: LevelDb, options?: IWorldProcessingOptions) => Promise<boolean>
Loads world data from an existing LevelDb instance.
Chunk Iteration
forEachChunk
(processor: (chunk: WorldChunk, x: number, z: number, dimension: number) => Promise<void>, options?: ForEachChunkOptions) => Promise<void>
Iterates over all chunks with optional memory optimization.await world.forEachChunk(
async (chunk, x, z, dimension) => {
console.log(`Processing chunk at (${x}, ${z}) in dimension ${dimension}`);
// Process chunk data
},
{
clearCacheAfterProcess: true, // Free memory after each chunk
dimensionFilter: 0, // Only process overworld
progressCallback: async (processed, total) => {
console.log(`Processed ${processed}/${total} chunks`);
}
}
);
clearCacheAfterProcess: Clears parsed data but keeps raw bytes (can re-parse)clearAllAfterProcess: Clears all data including raw bytes (cannot re-parse)dimensionFilter: Only process chunks in specific dimension (0=overworld, 1=nether, 2=end)progressCallback: Called periodically with progress updates
Memory Management
Clears parsed chunk data while preserving raw data for re-parsing.world.clearAllChunkCaches();
Clears raw LevelDB data to free memory. Cannot reload after this.world.clearLevelDbData();
Clears all chunk data. Cannot access chunks after this.world.clearAllChunkData();
Block Access
getBlock
(blockLocation: BlockLocation, dim?: number) => Block
Retrieves a block at the given location.const block = world.getBlock(new BlockLocation(100, 64, 200));
console.log(block.typeName); // "minecraft:stone"
getTopBlock
(x: number, z: number, dim?: number) => Block | undefined
Gets the topmost non-air block at coordinates.const topBlock = world.getTopBlock(100, 200);
getTopBlockY
(x: number, z: number, dim?: number) => number | undefined
Gets the Y coordinate of the topmost block.const height = world.getTopBlockY(100, 200);
Pack Management
ensureBehaviorPack
(packId: string, version: number[], packName: string, packPriority?: number) => boolean
Adds a behavior pack reference to the world.world.ensureBehaviorPack(
"550bbdd8-f6df-4d45-bc34-e8d6e2a15b8b",
[1, 0, 0],
"My Behavior Pack"
);
ensureResourcePack
(packId: string, version: number[], packName: string, packPriority?: number) => boolean
Adds a resource pack reference to the world.world.ensureResourcePack(
"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
[1, 0, 0],
"My Resource Pack"
);
getBehaviorPack
(packId: string) => IPackRegistration | undefined
Retrieves a behavior pack registration by UUID.
getResourcePack
(packId: string) => IPackRegistration | undefined
Retrieves a resource pack registration by UUID.
Saving
Saves all world metadata and settings.world.name = "Updated World Name";
world.spawnX = 0;
world.spawnY = 100;
world.spawnZ = 0;
await world.save();
getBytes
() => Promise<Uint8Array | undefined>
Gets the world as a byte array (.mcworld format).const bytes = await world.getBytes();
// Save bytes to file
syncFolderTo
(folder: IFolder) => Promise<void>
Syncs world contents to a target folder.await world.syncFolderTo(targetFolder);
Events
Fired when world metadata is loaded.world.onLoaded.subscribe((sender, world) => {
console.log(`World ${world.name} loaded`);
});
Fired when chunk data is fully loaded.world.onDataLoaded.subscribe((sender, world) => {
console.log(`Loaded ${world.chunkCount} chunks`);
});
onChunkUpdated
IEvent<MCWorld, WorldChunk>
Fired when a chunk is updated (e.g., newer data replaces old).world.onChunkUpdated.subscribe((sender, chunk) => {
console.log(`Chunk updated at (${chunk.x}, ${chunk.z})`);
});
Experiments
Whether Beta APIs experiment is enabled.world.betaApisExperiment = true;
deferredTechnicalPreviewExperiment
Whether Deferred Technical Preview experiment is enabled.
dataDrivenItemsExperiment
Whether Data Driven Items experiment is enabled.
Example: Loading and Analyzing a World
import { MCWorld } from '@minecraft/creator-tools';
async function analyzeWorld(worldFile: IFile) {
// Load the world
const world = await MCWorld.ensureOnFile(worldFile);
if (!world) {
console.error('Failed to load world');
return;
}
// Load chunk data with progress tracking
await world.loadLevelDb(false, {
progressCallback: (phase, current, total) => {
console.log(`${phase}: ${Math.round(current/total*100)}%`);
}
});
console.log(`World: ${world.name}`);
console.log(`Chunks: ${world.chunkCount}`);
console.log(`Bounds: (${world.minX}, ${world.minZ}) to (${world.maxX}, ${world.maxZ})`);
console.log(`Spawn: (${world.spawnX}, ${world.spawnY}, ${world.spawnZ})`);
// Analyze block types
const blockCounts = new Map<string, number>();
await world.forEachChunk(
async (chunk) => {
const types = chunk.countBlockTypes();
for (const [type, count] of types) {
blockCounts.set(type, (blockCounts.get(type) || 0) + count);
}
},
{ clearCacheAfterProcess: true }
);
console.log('Top 10 blocks:');
const sorted = [...blockCounts.entries()]
.sort((a, b) => b[1] - a[1])
.slice(0, 10);
for (const [type, count] of sorted) {
console.log(` ${type}: ${count.toLocaleString()}`);
}
// Free memory
world.clearLevelDbData();
}
Types
interface IWorldProcessingOptions {
maxNumberOfRecordsToProcess?: number;
progressCallback?: (phase: string, current: number, total: number) => void;
}
interface IRegion {
minX: number;
minZ: number;
maxX: number;
maxZ: number;
}
interface IPackRegistration {
pack_id: string;
version: number[];
priority?: number;
}