@lzimul/minecraft-mcp 1.0.3 → 1.0.5

package/build/world/entity-inventory.js

@@ -0,0 +1,101 @@
+import { getItemByName } from '../data/items.js';
+import { EInventorySection } from '../enums/inventory-section.enum.js';
+export const HOTBAR_SLOT_COUNT = 9;
+export const INVENTORY_SLOT_COUNT = 27;
+export const TOTAL_SLOT_COUNT = HOTBAR_SLOT_COUNT + INVENTORY_SLOT_COUNT;
+export function slotCount(section) {
+    return section === EInventorySection.Hotbar
+        ? HOTBAR_SLOT_COUNT
+        : INVENTORY_SLOT_COUNT;
+}
+export function isSlotInRange(section, slot) {
+    return Number.isInteger(slot) && slot >= 0 && slot < slotCount(section);
+}
+export function createEmptyInventory() {
+    return {
+        hotbar: Array.from({ length: HOTBAR_SLOT_COUNT }, () => null),
+        inventory: Array.from({ length: INVENTORY_SLOT_COUNT }, () => null)
+    };
+}
+export function normalizeItemStack(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const { item, count } = record;
+    if (typeof item !== 'string' ||
+        typeof count !== 'number' ||
+        !Number.isInteger(count) ||
+        count <= 0) {
+        return null;
+    }
+    const resolved = getItemByName(item.trim().toLowerCase());
+    if (!resolved || resolved.key === 'minecraft:air') {
+        return null;
+    }
+    return {
+        item: resolved.key,
+        count: Math.min(count, resolved.stackSize)
+    };
+}
+function normalizeSlotArray(value, length) {
+    const source = Array.isArray(value) ? value : [];
+    return Array.from({ length }, (_, index) => normalizeItemStack(source[index]));
+}
+export function normalizeInventory(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return createEmptyInventory();
+    }
+    const record = value;
+    return {
+        hotbar: normalizeSlotArray(record.hotbar, HOTBAR_SLOT_COUNT),
+        inventory: normalizeSlotArray(record.inventory, INVENTORY_SLOT_COUNT)
+    };
+}
+export function getInventorySlot(inventory, section, slot) {
+    return section === EInventorySection.Hotbar
+        ? inventory.hotbar[slot]
+        : inventory.inventory[slot];
+}
+export function withInventorySlot(inventory, section, slot, stack) {
+    if (section === EInventorySection.Hotbar) {
+        const hotbar = [...inventory.hotbar];
+        hotbar[slot] = stack;
+        return { ...inventory, hotbar };
+    }
+    const slots = [...inventory.inventory];
+    slots[slot] = stack;
+    return { ...inventory, inventory: slots };
+}
+export function sameItemStack(a, b) {
+    if (a === b) {
+        return true;
+    }
+    return a !== null && b !== null && a.item === b.item && a.count === b.count;
+}
+export function inventoryUsedSlots(inventory) {
+    let used = 0;
+    for (const stack of inventory.hotbar) {
+        if (stack !== null) {
+            used += 1;
+        }
+    }
+    for (const stack of inventory.inventory) {
+        if (stack !== null) {
+            used += 1;
+        }
+    }
+    return used;
+}
+export function sectionUsedSlots(inventory, section) {
+    const slots = section === EInventorySection.Hotbar
+        ? inventory.hotbar
+        : inventory.inventory;
+    let used = 0;
+    for (const stack of slots) {
+        if (stack !== null) {
+            used += 1;
+        }
+    }
+    return used;
+}

package/build/world/item-spec.js

@@ -0,0 +1,25 @@
+import { getItemByName } from '../data/items.js';
+const ITEM_SPEC = /^(?:([a-z0-9_.-]+):)?([a-z0-9_./-]+)$/;
+export function parseItemSpec(input) {
+    const spec = input.trim().toLowerCase();
+    const match = ITEM_SPEC.exec(spec);
+    if (!match) {
+        return {
+            ok: false,
+            error: `Invalid item "${input}". Expected an id such as "minecraft:diamond_sword" or "diamond_sword".`
+        };
+    }
+    const namespace = match[1];
+    const name = match[2];
+    let item = getItemByName(namespace ? `${namespace}:${name}` : name);
+    if (!item && !namespace) {
+        item = getItemByName(`minecraft:${name}`);
+    }
+    if (!item) {
+        return {
+            ok: false,
+            error: `Unknown item "${input}". Use an item id such as "minecraft:diamond_sword"; see the resource lzimul://minecraft/items for the full list.`
+        };
+    }
+    return { ok: true, item };
+}

package/build/world/simulated-dimension.js

@@ -1,20 +1,62 @@
+import { randomUUID } from 'node:crypto';
 import { WORLD_LIMITS } from '../config/world-limits.js';
 import { getBlockByName, MINECRAFT_BLOCKS } from '../data/blocks.js';
+import { getEntityTypeByName } from '../data/entities.js';
+import { EEntityKind } from '../enums/entity-kind.enum.js';
+import { EInventorySection } from '../enums/inventory-section.enum.js';
+import { EMoveDirection } from '../enums/move-direction.enum.js';
 import { toErrorMessage } from '../utils/error-message.js';
-import { EMPTY_BLOCK_STATES, normalizeStates, sameStates } from './block-states.js';
+import { logger } from '../utils/logger.js';
+import { EMPTY_BLOCK_STATES, isEmptyStates, normalizeStates, sameStates } from './block-states.js';
+import { createEmptyInventory, getInventorySlot, inventoryUsedSlots, isSlotInRange, sameItemStack, slotCount, withInventorySlot } from './entity-inventory.js';
 const AIR = getBlockByName('air') ?? MINECRAFT_BLOCKS[0];
+function directionDelta(direction) {
+    switch (direction) {
+        case EMoveDirection.Forward:
+            return { x: 0, y: 0, z: 1 };
+        case EMoveDirection.Back:
+            return { x: 0, y: 0, z: -1 };
+        case EMoveDirection.Left:
+            return { x: -1, y: 0, z: 0 };
+        case EMoveDirection.Right:
+            return { x: 1, y: 0, z: 0 };
+        case EMoveDirection.Up:
+            return { x: 0, y: 1, z: 0 };
+        case EMoveDirection.Down:
+            return { x: 0, y: -1, z: 0 };
+        default:
+            throw new Error(`Unknown movement direction "${direction}".`);
+    }
+}
 function coordinateKey(x, y, z) {
     return `${x},${y},${z}`;
 }
+function playerEntityType() {
+    const type = getEntityTypeByName('minecraft:player');
+    if (!type) {
+        throw new Error('The entity registry is missing minecraft:player.');
+    }
+    return type;
+}
+function compareEntityIds(a, b) {
+    if (a.id === b.id) {
+        return 0;
+    }
+    return a.id < b.id ? -1 : 1;
+}
 export class SimulatedDimension {
     info;
     blocks = new Map();
+    entities = new Map();
+    playersByName = new Map();
     store;
     writeDelayMs;
     timer = null;
     queue = Promise.resolve();
     savePromise = null;
     dirty = false;
+    sortedBlocksCache = null;
+    sortedEntitiesCache = null;
     constructor(info, store, writeDelayMs = 25) {
         this.info = info;
         this.store = store;
@@ -23,25 +65,81 @@ export class SimulatedDimension {
     get modifiedBlockCount() {
         return this.blocks.size;
     }
+    get entityCount() {
+        return this.entities.size;
+    }
+    get playerCount() {
+        return this.playersByName.size;
+    }
     get placedBlocks() {
         return [...this.blocks.values()];
     }
+    get sortedPlacedBlocks() {
+        if (!this.sortedBlocksCache) {
+            this.sortedBlocksCache = this.placedBlocks.toSorted((a, b) => a.x - b.x || a.y - b.y || a.z - b.z);
+        }
+        return this.sortedBlocksCache;
+    }
+    get placedEntities() {
+        return [...this.entities.values()];
+    }
+    get sortedPlacedEntities() {
+        if (!this.sortedEntitiesCache) {
+            this.sortedEntitiesCache = this.placedEntities.toSorted(compareEntityIds);
+        }
+        return this.sortedEntitiesCache;
+    }
     async load() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        await this.queue;
+        this.dirty = false;
         const stored = await this.store.load(this.info.type);
-        let skipped = 0;
-        for (const placed of stored) {
+        this.blocks.clear();
+        this.entities.clear();
+        this.playersByName.clear();
+        this.sortedBlocksCache = null;
+        this.sortedEntitiesCache = null;
+        let skippedBlocks = 0;
+        for (const placed of stored.blocks) {
             const key = coordinateKey(placed.x, placed.y, placed.z);
-            const isNew = !this.blocks.has(key);
             const outOfRange = !this.contains(placed.x, placed.y, placed.z);
-            const overLimit = isNew && this.blocks.size >= WORLD_LIMITS.maxModifiedBlocks;
+            const overLimit = !this.blocks.has(key) &&
+                this.blocks.size >= WORLD_LIMITS.maxModifiedBlocks;
             if (outOfRange || overLimit) {
-                skipped++;
+                skippedBlocks++;
                 continue;
             }
             this.blocks.set(key, placed);
         }
-        if (skipped > 0) {
-            console.error(`[lzimul-minecraft-mcp] Skipped ${skipped} invalid block(s) while loading ${this.info.key}`);
+        let skippedEntities = 0;
+        for (const entity of stored.entities) {
+            const duplicateId = this.entities.has(entity.id);
+            const outOfRange = !this.contains(entity.x, entity.y, entity.z) ||
+                entity.dimension !== this.info.type;
+            const overLimit = !duplicateId &&
+                this.entities.size >= WORLD_LIMITS.maxEntitiesPerDimension;
+            if (duplicateId || outOfRange || overLimit) {
+                skippedEntities++;
+                continue;
+            }
+            if (entity.kind === EEntityKind.Player) {
+                const playerName = entity.name.trim().toLowerCase();
+                if (this.playersByName.has(playerName)) {
+                    skippedEntities++;
+                    continue;
+                }
+                this.playersByName.set(playerName, entity);
+            }
+            this.entities.set(entity.id, entity);
+        }
+        if (skippedBlocks > 0) {
+            logger.warn(`Skipped ${skippedBlocks} invalid block(s) while loading ${this.info.key}`);
+        }
+        if (skippedEntities > 0) {
+            logger.warn(`Skipped ${skippedEntities} invalid entity/player record(s) while loading ${this.info.key}`);
         }
     }
     contains(x, y, z) {
@@ -56,12 +154,203 @@ export class SimulatedDimension {
         return (this.blocks.has(coordinateKey(x, y, z)) ||
             this.blocks.size < WORLD_LIMITS.maxModifiedBlocks);
     }
+    canAddEntity() {
+        return this.entities.size < WORLD_LIMITS.maxEntitiesPerDimension;
+    }
     getBlock(x, y, z) {
         return this.blocks.get(coordinateKey(x, y, z))?.block ?? AIR;
     }
     getStates(x, y, z) {
         return (this.blocks.get(coordinateKey(x, y, z))?.states ?? EMPTY_BLOCK_STATES);
     }
+    getBlockState(x, y, z) {
+        const placed = this.blocks.get(coordinateKey(x, y, z));
+        return placed
+            ? { block: placed.block, states: placed.states }
+            : { block: AIR, states: EMPTY_BLOCK_STATES };
+    }
+    getEntity(id) {
+        return this.entities.get(id);
+    }
+    findPlayer(name) {
+        return this.playersByName.get(name.trim().toLowerCase());
+    }
+    removeDuplicatePlayers(claimedNames) {
+        let removed = 0;
+        for (const entity of this.entities.values()) {
+            if (entity.kind !== EEntityKind.Player) {
+                continue;
+            }
+            const name = entity.name.trim().toLowerCase();
+            if (claimedNames.has(name)) {
+                this.entities.delete(entity.id);
+                this.playersByName.delete(name);
+                removed++;
+            }
+            else {
+                claimedNames.add(name);
+            }
+        }
+        if (removed > 0) {
+            this.sortedEntitiesCache = null;
+        }
+        return removed;
+    }
+    createEntity(type, name, x, y, z) {
+        if (type.name === 'player') {
+            throw new Error('Use createPlayer to create a player; createEntity only creates non-player entities.');
+        }
+        return this.addEntity(EEntityKind.Entity, type, name, x, y, z);
+    }
+    createPlayer(name, x, y, z) {
+        if (this.findPlayer(name)) {
+            throw new Error(`A player named "${name}" already exists in ${this.info.displayName}. Player names are case-insensitive.`);
+        }
+        return this.addEntity(EEntityKind.Player, playerEntityType(), name, x, y, z);
+    }
+    addEntity(kind, type, name, x, y, z) {
+        if (!this.canAddEntity()) {
+            throw new RangeError(`The ${this.info.displayName} world already holds the maximum of ${WORLD_LIMITS.maxEntitiesPerDimension} entities.`);
+        }
+        const entity = {
+            id: randomUUID(),
+            kind,
+            type,
+            name,
+            x,
+            y,
+            z,
+            dimension: this.info.type,
+            inventory: createEmptyInventory(),
+            createdAt: new Date().toISOString()
+        };
+        this.entities.set(entity.id, entity);
+        if (kind === EEntityKind.Player) {
+            this.playersByName.set(entity.name.trim().toLowerCase(), entity);
+        }
+        this.sortedEntitiesCache = null;
+        this.markDirty();
+        return entity;
+    }
+    setInventorySlot(id, section, slot, stack) {
+        const entity = this.entities.get(id);
+        if (!entity) {
+            throw new RangeError(`Unknown entity "${id}" in ${this.info.displayName}.`);
+        }
+        if (!isSlotInRange(section, slot)) {
+            throw new RangeError(`Slot ${slot} is out of range for the ${section} (0-${slotCount(section) - 1}).`);
+        }
+        const previous = getInventorySlot(entity.inventory, section, slot);
+        if (sameItemStack(previous, stack)) {
+            return { previous, entity };
+        }
+        const updated = {
+            ...entity,
+            inventory: withInventorySlot(entity.inventory, section, slot, stack)
+        };
+        this.entities.set(id, updated);
+        if (updated.kind === EEntityKind.Player) {
+            this.playersByName.set(updated.name.trim().toLowerCase(), updated);
+        }
+        this.sortedEntitiesCache = null;
+        this.markDirty();
+        return { previous, entity: updated };
+    }
+    deleteEntity(id) {
+        const entity = this.entities.get(id);
+        if (!entity) {
+            return;
+        }
+        this.entities.delete(id);
+        if (entity.kind === EEntityKind.Player) {
+            this.playersByName.delete(entity.name.trim().toLowerCase());
+        }
+        this.sortedEntitiesCache = null;
+        this.markDirty();
+        return entity;
+    }
+    clearInventory(id) {
+        const entity = this.entities.get(id);
+        if (!entity) {
+            throw new RangeError(`Unknown entity "${id}" in ${this.info.displayName}.`);
+        }
+        const clearedSlots = inventoryUsedSlots(entity.inventory);
+        if (clearedSlots === 0) {
+            return { clearedSlots, entity };
+        }
+        const updated = {
+            ...entity,
+            inventory: createEmptyInventory()
+        };
+        this.entities.set(id, updated);
+        if (updated.kind === EEntityKind.Player) {
+            this.playersByName.set(updated.name.trim().toLowerCase(), updated);
+        }
+        this.sortedEntitiesCache = null;
+        this.markDirty();
+        return { clearedSlots, entity: updated };
+    }
+    swapInventorySlots(id, fromSection, fromSlot, toSection, toSlot) {
+        const entity = this.entities.get(id);
+        if (!entity) {
+            throw new RangeError(`Unknown entity "${id}" in ${this.info.displayName}.`);
+        }
+        if (!isSlotInRange(fromSection, fromSlot)) {
+            throw new RangeError(`Slot ${fromSlot} is out of range for the ${fromSection} (0-${slotCount(fromSection) - 1}).`);
+        }
+        if (!isSlotInRange(toSection, toSlot)) {
+            throw new RangeError(`Slot ${toSlot} is out of range for the ${toSection} (0-${slotCount(toSection) - 1}).`);
+        }
+        const previousFrom = getInventorySlot(entity.inventory, fromSection, fromSlot);
+        const previousTo = getInventorySlot(entity.inventory, toSection, toSlot);
+        const sameSlot = fromSection === toSection && fromSlot === toSlot;
+        if (sameSlot || sameItemStack(previousFrom, previousTo)) {
+            return { previousFrom, previousTo, entity };
+        }
+        let inventory = withInventorySlot(entity.inventory, fromSection, fromSlot, previousTo);
+        inventory = withInventorySlot(inventory, toSection, toSlot, previousFrom);
+        const updated = { ...entity, inventory };
+        this.entities.set(id, updated);
+        if (updated.kind === EEntityKind.Player) {
+            this.playersByName.set(updated.name.trim().toLowerCase(), updated);
+        }
+        this.sortedEntitiesCache = null;
+        this.markDirty();
+        return { previousFrom, previousTo, entity: updated };
+    }
+    moveEntity(id, direction) {
+        const entity = this.entities.get(id);
+        if (!entity) {
+            throw new RangeError(`Unknown entity "${id}" in ${this.info.displayName}.`);
+        }
+        const delta = directionDelta(direction);
+        return this.setEntityPosition(id, entity.x + delta.x, entity.y + delta.y, entity.z + delta.z);
+    }
+    setEntityPosition(id, x, y, z) {
+        const entity = this.entities.get(id);
+        if (!entity) {
+            throw new RangeError(`Unknown entity "${id}" in ${this.info.displayName}.`);
+        }
+        if (!this.contains(x, y, z)) {
+            throw new RangeError(`Position (${x}, ${y}, ${z}) is out of range in ${this.info.displayName} (Y: ${this.info.minY} to ${this.info.maxY - 1}).`);
+        }
+        const previous = {
+            x: entity.x,
+            y: entity.y,
+            z: entity.z
+        };
+        if (entity.x === x && entity.y === y && entity.z === z) {
+            return { previous, entity };
+        }
+        const updated = { ...entity, x, y, z };
+        this.entities.set(id, updated);
+        if (updated.kind === EEntityKind.Player) {
+            this.playersByName.set(updated.name.trim().toLowerCase(), updated);
+        }
+        this.sortedEntitiesCache = null;
+        this.markDirty();
+        return { previous, entity: updated };
+    }
     setBlock(x, y, z, block, states = EMPTY_BLOCK_STATES) {
         const key = coordinateKey(x, y, z);
         const existing = this.blocks.get(key);
@@ -71,7 +360,7 @@ export class SimulatedDimension {
             sameStates(existing?.states ?? EMPTY_BLOCK_STATES, normalized)) {
             return previous;
         }
-        const isRemoval = block.key === AIR.key && Object.keys(normalized).length === 0;
+        const isRemoval = block.key === AIR.key && isEmptyStates(normalized);
         if (!existing &&
             !isRemoval &&
             this.blocks.size >= WORLD_LIMITS.maxModifiedBlocks) {
@@ -83,10 +372,14 @@ export class SimulatedDimension {
         else {
             this.blocks.set(key, { x, y, z, block, states: normalized });
         }
-        this.dirty = true;
-        this.scheduleFlush();
+        this.sortedBlocksCache = null;
+        this.markDirty();
         return previous;
     }
+    async readRaw() {
+        await this.flush();
+        return this.store.readRaw(this.info.type);
+    }
     async flush() {
         if (this.timer !== null) {
             clearTimeout(this.timer);
@@ -100,7 +393,10 @@ export class SimulatedDimension {
             return;
         }
         this.dirty = false;
-        const snapshot = this.placedBlocks;
+        const snapshot = {
+            blocks: this.sortedPlacedBlocks,
+            entities: this.sortedPlacedEntities
+        };
         const run = this.queue.then(async () => {
             await this.store.save(this.info.type, snapshot);
         });
@@ -115,14 +411,18 @@ export class SimulatedDimension {
             this.savePromise = null;
         }
     }
+    markDirty() {
+        this.dirty = true;
+        this.scheduleFlush();
+    }
     scheduleFlush() {
         if (this.timer !== null) {
             return;
         }
         this.timer = setTimeout(() => {
             this.timer = null;
-            void this.flush().catch((error) => {
-                console.error(`[lzimul-minecraft-mcp] Failed to persist ${this.info.key}: ${toErrorMessage(error)}`);
+            void this.flush().catch(error => {
+                logger.error(`Failed to persist ${this.info.key}: ${toErrorMessage(error)}`);
             });
         }, this.writeDelayMs);
     }

package/build/world/stores/file-world-store.js

@@ -3,11 +3,15 @@ import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { WORLD_LIMITS } from '../../config/world-limits.js';
 import { toErrorMessage } from '../../utils/error-message.js';
-import { fromSerialized, toSerialized } from './serialized-block.js';
-const FILE_FORMAT = 'lzimul-world/2';
-const MAX_SNAPSHOT_BYTES = 128 * 1024 * 1024;
+import { logger } from '../../utils/logger.js';
+import { fromSerialized } from './serialized-block.js';
+import { fromSerializedEntity } from './serialized-entity.js';
+import { MAX_SNAPSHOT_BYTES, serializeSnapshot } from './serialized-snapshot.js';
 function warn(message) {
-    console.error(`[lzimul-minecraft-mcp] ${message}`);
+    logger.warn(message);
+}
+function emptySnapshot() {
+    return { blocks: [], entities: [] };
 }
 export class FileWorldStore {
     directory;
@@ -31,13 +35,13 @@ export class FileWorldStore {
             const info = await stat(file);
             if (info.size > MAX_SNAPSHOT_BYTES) {
                 await this.quarantine(file, `snapshot is larger than ${MAX_SNAPSHOT_BYTES} bytes`);
-                return [];
+                return emptySnapshot();
             }
             raw = await readFile(file, 'utf8');
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                return [];
+                return emptySnapshot();
             }
             throw new Error(`Cannot read world snapshot ${file}: ${toErrorMessage(error)}`, { cause: error });
         }
@@ -47,42 +51,93 @@ export class FileWorldStore {
         }
         catch {
             await this.quarantine(file, 'invalid JSON');
-            return [];
+            return emptySnapshot();
         }
-        if (!parsed || !Array.isArray(parsed.blocks)) {
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            Array.isArray(parsed) ||
+            !Array.isArray(parsed.blocks)) {
             await this.quarantine(file, 'missing blocks array');
-            return [];
+            return emptySnapshot();
+        }
+        const stored = parsed;
+        if (stored.blocks.length > WORLD_LIMITS.maxModifiedBlocks) {
+            await this.quarantine(file, `${stored.blocks.length} blocks exceed the limit of ${WORLD_LIMITS.maxModifiedBlocks}`);
+            return emptySnapshot();
         }
-        if (parsed.blocks.length > WORLD_LIMITS.maxModifiedBlocks) {
-            await this.quarantine(file, `${parsed.blocks.length} blocks exceed the limit of ${WORLD_LIMITS.maxModifiedBlocks}`);
-            return [];
+        let serializedEntities = [];
+        if (typeof stored.entities !== 'undefined') {
+            if (!Array.isArray(stored.entities)) {
+                await this.quarantine(file, 'invalid entities array');
+                return emptySnapshot();
+            }
+            if (stored.entities.length > WORLD_LIMITS.maxEntitiesPerDimension) {
+                await this.quarantine(file, `${stored.entities.length} entities exceed the limit of ${WORLD_LIMITS.maxEntitiesPerDimension}`);
+                return emptySnapshot();
+            }
+            serializedEntities = stored.entities;
         }
-        return parsed.blocks.flatMap(entry => {
+        const blocks = [];
+        for (const entry of stored.blocks) {
             const block = fromSerialized(entry);
             if (block) {
-                return [block];
+                blocks.push(block);
+            }
+            else {
+                warn(`Skipped malformed block entry in ${file}`);
+            }
+        }
+        const entities = [];
+        for (const entry of serializedEntities) {
+            try {
+                const entity = fromSerializedEntity(entry, type);
+                if (entity) {
+                    entities.push(entity);
+                    continue;
+                }
+            }
+            catch {
+            }
+            warn(`Skipped malformed entity entry in ${file}`);
+        }
+        return { blocks, entities };
+    }
+    async readRaw(type) {
+        const file = this.fileFor(type);
+        try {
+            const info = await stat(file);
+            if (info.size > MAX_SNAPSHOT_BYTES) {
+                throw new RangeError(`World snapshot ${file} is larger than ${MAX_SNAPSHOT_BYTES} bytes`);
+            }
+            return await readFile(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return serializeSnapshot(type, emptySnapshot());
+            }
+            if (error instanceof RangeError) {
+                throw error;
             }
-            warn(`Skipped malformed block entry in ${file}`);
-            return [];
-        });
+            throw new Error(`Cannot read world snapshot ${file}: ${toErrorMessage(error)}`, { cause: error });
+        }
     }
-    async save(type, blocks) {
-        if (blocks.length > WORLD_LIMITS.maxModifiedBlocks) {
-            throw new RangeError(`World snapshot has ${blocks.length} blocks, above the limit of ${WORLD_LIMITS.maxModifiedBlocks}`);
+    async save(type, snapshot) {
+        if (snapshot.blocks.length > WORLD_LIMITS.maxModifiedBlocks) {
+            throw new RangeError(`World snapshot has ${snapshot.blocks.length} blocks, above the limit of ${WORLD_LIMITS.maxModifiedBlocks}`);
+        }
+        if (snapshot.entities.length > WORLD_LIMITS.maxEntitiesPerDimension) {
+            throw new RangeError(`World snapshot has ${snapshot.entities.length} entities, above the limit of ${WORLD_LIMITS.maxEntitiesPerDimension}`);
         }
         const file = this.fileFor(type);
+        const text = serializeSnapshot(type, snapshot);
+        const bytes = Buffer.byteLength(text, 'utf8');
+        if (bytes > MAX_SNAPSHOT_BYTES) {
+            throw new RangeError(`World snapshot for ${type} would be ${bytes} bytes, above the load limit of ${MAX_SNAPSHOT_BYTES} bytes. Remove blocks, block states or entities and retry.`);
+        }
         try {
             await this.ensureDirectory();
-            const sorted = blocks.toSorted((a, b) => a.x - b.x || a.y - b.y || a.z - b.z);
-            const payload = {
-                format: FILE_FORMAT,
-                dimension: `minecraft:${type}`,
-                updatedAt: new Date().toISOString(),
-                modifiedBlockCount: sorted.length,
-                blocks: sorted.map(toSerialized)
-            };
             const temporary = `${file}.tmp`;
-            await writeFile(temporary, `${JSON.stringify(payload)}\n`, 'utf8');
+            await writeFile(temporary, text, 'utf8');
             await rename(temporary, file);
         }
         catch (error) {