@lzimul/minecraft-mcp 1.0.0 → 1.0.2

package/build/tools/block-tools.js

@@ -1,17 +1,20 @@
 import * as z from 'zod/v4';
-import { getBlockByName } from '../data/blocks.js';
+import { WORLD_LIMITS } from '../config/world-limits.js';
 import { blockInfoSchema, toBlockInfo } from '../schemas/block-schema.js';
 import { horizontalCoordinate, verticalCoordinate } from '../schemas/coordinate-schema.js';
 import { dimensionSchema } from '../schemas/dimension-schema.js';
-import { getDimension } from '../world/world-state.js';
+import { toErrorMessage } from '../utils/error-message.js';
+import { formatStates } from '../world/block-states.js';
+import { parseBlockSpec } from '../world/block-spec.js';
 import { toolError } from './result.js';
-function rangeError(info, x, y, z) {
-    return toolError(`Coordinates (${x}, ${y}, ${z}) are out of range in ${info.displayName} (Y: ${info.minY} to ${info.maxY - 1}).`);
+const blockStatesSchema = z.record(z.string(), z.string());
+function rangeError(dimension, x, y, z) {
+    return toolError(`Coordinates (${x}, ${y}, ${z}) are out of range in ${dimension.displayName} (Y: ${dimension.minY} to ${dimension.maxY - 1}).`);
 }
-export function registerBlockTools(server) {
+export function registerBlockTools(server, world) {
     server.registerTool('getBlock', {
         title: 'Get Block',
-        description: 'Get the block at the given coordinates in the given dimension, including its properties (name, hardness, light level, etc.). Each dimension has its own world state; unmodified coordinates return air (minecraft:air).',
+        description: 'Get the block at the given coordinates in the given dimension, including its properties (name, hardness, light level, etc.) and its block states (for example facing=south). Each dimension has its own persisted world state; unmodified coordinates return air (minecraft:air).',
         inputSchema: z.object({
             x: horizontalCoordinate.describe('X coordinate (-30000000 to 30000000)'),
             y: verticalCoordinate.describe('Y coordinate, within the dimension height range'),
@@ -23,7 +26,8 @@ export function registerBlockTools(server) {
             y: z.number(),
             z: z.number(),
             dimension: z.string(),
-            block: blockInfoSchema
+            block: blockInfoSchema,
+            states: blockStatesSchema
         }),
         annotations: {
             readOnlyHint: true,
@@ -31,30 +35,37 @@ export function registerBlockTools(server) {
             openWorldHint: false
         }
     }, async ({ x, y, z, dimension: dimensionType }) => {
-        const dimension = getDimension(dimensionType);
-        if (!dimension.contains(x, y, z)) {
-            return rangeError(dimension.info, x, y, z);
-        }
-        const block = dimension.getBlock(x, y, z);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Block at (${x}, ${y}, ${z}) in ${dimension.info.displayName} is ${block.displayName} (${block.key})`
-                }
-            ],
-            structuredContent: {
-                x,
-                y,
-                z,
-                dimension: dimension.info.key,
-                block: toBlockInfo(block)
+        try {
+            const dimension = world.getDimension(dimensionType);
+            if (!dimension.contains(x, y, z)) {
+                return rangeError(dimension.info, x, y, z);
             }
-        };
+            const block = dimension.getBlock(x, y, z);
+            const states = dimension.getStates(x, y, z);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Block at (${x}, ${y}, ${z}) in ${dimension.info.displayName} is ${block.displayName} (${block.key})${formatStates(states)}`
+                    }
+                ],
+                structuredContent: {
+                    x,
+                    y,
+                    z,
+                    dimension: dimension.info.key,
+                    block: toBlockInfo(block),
+                    states
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`getBlock failed: ${toErrorMessage(error)}`);
+        }
     });
     server.registerTool('setBlock', {
         title: 'Set Block',
-        description: 'Place a block at the given coordinates in the given dimension and return the replaced block. Each dimension has its own world state. blockType is a block id such as "minecraft:stone" or "stone"; see the resource lzimul://minecraft/blocks for the full list.',
+        description: 'Place a block at the given coordinates in the given dimension and return the replaced block. Block states are supported: "minecraft:oak_stairs[facing=south,half=bottom]" or "oak_stairs[facing=south]". Each dimension has its own persisted world state; setting air removes the block. blockType is a block id such as "minecraft:stone" or "stone"; see the resource lzimul://minecraft/blocks for the full list.',
         inputSchema: z.object({
             x: horizontalCoordinate.describe('X coordinate (-30000000 to 30000000)'),
             y: verticalCoordinate.describe('Y coordinate, within the dimension height range'),
@@ -62,7 +73,8 @@ export function registerBlockTools(server) {
             blockType: z
                 .string()
                 .min(1)
-                .describe('Block id, such as "minecraft:stone"'),
+                .max(256)
+                .describe('Block id with optional states, such as "minecraft:stone" or "minecraft:oak_stairs[facing=south]"'),
             dimension: dimensionSchema.describe('Dimension: "overworld" (default), "the_nether" or "the_end"')
         }),
         outputSchema: z.object({
@@ -71,7 +83,9 @@ export function registerBlockTools(server) {
             z: z.number(),
             dimension: z.string(),
             block: blockInfoSchema,
-            previous: blockInfoSchema
+            states: blockStatesSchema,
+            previous: blockInfoSchema,
+            previousStates: blockStatesSchema
         }),
         annotations: {
             destructiveHint: true,
@@ -79,30 +93,53 @@ export function registerBlockTools(server) {
             openWorldHint: false
         }
     }, async ({ x, y, z, blockType, dimension: dimensionType }) => {
-        const dimension = getDimension(dimensionType);
-        if (!dimension.contains(x, y, z)) {
-            return rangeError(dimension.info, x, y, z);
+        try {
+            const dimension = world.getDimension(dimensionType);
+            if (!dimension.contains(x, y, z)) {
+                return rangeError(dimension.info, x, y, z);
+            }
+            const spec = parseBlockSpec(blockType);
+            if (!spec.ok) {
+                return toolError(spec.error);
+            }
+            const isAir = spec.block.key === 'minecraft:air';
+            const hasStates = Object.keys(spec.states).length > 0;
+            if (isAir && hasStates) {
+                return toolError('Air cannot carry block states. Use "minecraft:air" to remove a block.');
+            }
+            if (!isAir && !dimension.canSetBlock(x, y, z)) {
+                return toolError(`The ${dimension.info.displayName} world already holds the maximum of ${WORLD_LIMITS.maxModifiedBlocks} modified blocks. Remove blocks with "minecraft:air" before adding more.`);
+            }
+            const previousBlock = dimension.getBlock(x, y, z);
+            const previousStates = dimension.getStates(x, y, z);
+            dimension.setBlock(x, y, z, spec.block, spec.states);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`Block ${spec.block.key} was applied at (${x}, ${y}, ${z}) in ${dimension.info.displayName} but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Block set at (${x}, ${y}, ${z}) in ${dimension.info.displayName}: ${previousBlock.displayName} (${previousBlock.key})${formatStates(previousStates)} -> ${spec.block.displayName} (${spec.block.key})${formatStates(spec.states)}`
+                    }
+                ],
+                structuredContent: {
+                    x,
+                    y,
+                    z,
+                    dimension: dimension.info.key,
+                    block: toBlockInfo(spec.block),
+                    states: spec.states,
+                    previous: toBlockInfo(previousBlock),
+                    previousStates
+                }
+            };
         }
-        const block = getBlockByName(blockType);
-        if (!block) {
-            return toolError(`Unknown block "${blockType}". Use a block id such as "minecraft:stone"; see the resource lzimul://minecraft/blocks for the full list.`);
+        catch (error) {
+            return toolError(`setBlock failed: ${toErrorMessage(error)}`);
         }
-        const previous = dimension.setBlock(x, y, z, block);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Block set at (${x}, ${y}, ${z}) in ${dimension.info.displayName}: ${previous.displayName} (${previous.key}) -> ${block.displayName} (${block.key})`
-                }
-            ],
-            structuredContent: {
-                x,
-                y,
-                z,
-                dimension: dimension.info.key,
-                block: toBlockInfo(block),
-                previous: toBlockInfo(previous)
-            }
-        };
     });
 }

package/build/tools/index.js

@@ -1,6 +1,6 @@
 import { registerBlockTools } from './block-tools.js';
 import { registerItemTools } from './item-tools.js';
-export function registerTools(server) {
-    registerBlockTools(server);
+export function registerTools(server, world) {
+    registerBlockTools(server, world);
     registerItemTools(server);
 }

package/build/tools/item-tools.js

@@ -1,6 +1,7 @@
 import * as z from 'zod/v4';
 import { getItemByName } from '../data/items.js';
 import { itemInfoSchema, toItemInfo } from '../schemas/item-schema.js';
+import { toErrorMessage } from '../utils/error-message.js';
 import { toolError } from './result.js';
 export function registerItemTools(server) {
     server.registerTool('getItem', {
@@ -10,6 +11,7 @@ export function registerItemTools(server) {
             item: z
                 .string()
                 .min(1)
+                .max(256)
                 .describe('Item id, such as "minecraft:diamond_sword" or "diamond_sword"')
         }),
         outputSchema: z.object({
@@ -21,23 +23,28 @@ export function registerItemTools(server) {
             openWorldHint: false
         }
     }, async ({ item: itemId }) => {
-        const item = getItemByName(itemId);
-        if (!item) {
-            return toolError(`Unknown item "${itemId}". Use an item id such as "minecraft:diamond_sword"; see the resource lzimul://minecraft/items for the full list.`);
-        }
-        const durability = item.maxDurability
-            ? `, durability ${item.maxDurability}`
-            : '';
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `${item.displayName} (${item.key}): stack size ${item.stackSize}${durability}`
-                }
-            ],
-            structuredContent: {
-                item: toItemInfo(item)
+        try {
+            const item = getItemByName(itemId.trim().toLowerCase());
+            if (!item) {
+                return toolError(`Unknown item "${itemId}". Use an item id such as "minecraft:diamond_sword"; see the resource lzimul://minecraft/items for the full list.`);
             }
-        };
+            const durability = item.maxDurability
+                ? `, durability ${item.maxDurability}`
+                : '';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${item.displayName} (${item.key}): stack size ${item.stackSize}${durability}`
+                    }
+                ],
+                structuredContent: {
+                    item: toItemInfo(item)
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`getItem failed: ${toErrorMessage(error)}`);
+        }
     });
 }

package/build/utils/error-message.js

@@ -0,0 +1,25 @@
+const FALLBACK_MESSAGE = 'Unknown error';
+export function toErrorMessage(error) {
+    if (error === null || error === void 0) {
+        return FALLBACK_MESSAGE;
+    }
+    if (error instanceof Error) {
+        const message = error.message.trim();
+        return message.length > 0 ? message : error.name || FALLBACK_MESSAGE;
+    }
+    if (typeof error === 'string') {
+        return error.trim() || FALLBACK_MESSAGE;
+    }
+    if (typeof error === 'object') {
+        try {
+            const serialized = JSON.stringify(error);
+            return typeof serialized === 'string' && serialized !== '{}'
+                ? serialized
+                : FALLBACK_MESSAGE;
+        }
+        catch {
+            return FALLBACK_MESSAGE;
+        }
+    }
+    return String(error) || FALLBACK_MESSAGE;
+}

package/build/world/block-spec.js

@@ -0,0 +1,74 @@
+import { getBlockByName } from '../data/blocks.js';
+import { isSafeStateName, isSafeStateValue, normalizeStates } from './block-states.js';
+const SPEC = /^(?:([a-z0-9_.-]+):)?([a-z0-9_./-]+)(?:\[([^\]]*)\])?$/;
+const PROPERTY = /^([a-z0-9_]+)=([a-z0-9_.-]+)$/;
+const MAX_STATES = 32;
+export function parseBlockSpec(input) {
+    const spec = input.trim().toLowerCase();
+    const match = SPEC.exec(spec);
+    if (!match) {
+        return {
+            ok: false,
+            error: `Invalid block "${input}". Expected an id such as "minecraft:stone" or "minecraft:oak_stairs[facing=south]".`
+        };
+    }
+    const namespace = match[1];
+    const name = match[2];
+    const rawStates = match[3];
+    let block = getBlockByName(namespace ? `${namespace}:${name}` : name);
+    if (!block && !namespace) {
+        block = getBlockByName(`minecraft:${name}`);
+    }
+    if (!block) {
+        return {
+            ok: false,
+            error: `Unknown block "${input}". Use a block id such as "minecraft:stone"; see the resource lzimul://minecraft/blocks for the full list.`
+        };
+    }
+    const states = {};
+    if (typeof rawStates === 'string') {
+        if (rawStates.trim().length === 0) {
+            return {
+                ok: false,
+                error: `Empty block state list in "${input}". Use "minecraft:oak_stairs[facing=south]" or omit the brackets.`
+            };
+        }
+        for (const part of rawStates.split(',')) {
+            const property = PROPERTY.exec(part.trim());
+            if (!property) {
+                return {
+                    ok: false,
+                    error: `Invalid block state "${part.trim()}" in "${input}". Expected "property=value".`
+                };
+            }
+            const propertyName = property[1];
+            const propertyValue = property[2];
+            if (!isSafeStateName(propertyName)) {
+                return {
+                    ok: false,
+                    error: `Unsupported block state name "${propertyName}" in "${input}".`
+                };
+            }
+            if (!isSafeStateValue(propertyValue)) {
+                return {
+                    ok: false,
+                    error: `Unsupported block state value "${propertyValue}" for "${propertyName}" in "${input}".`
+                };
+            }
+            if (Object.hasOwn(states, propertyName)) {
+                return {
+                    ok: false,
+                    error: `Duplicate block state "${propertyName}" in "${input}".`
+                };
+            }
+            states[propertyName] = propertyValue;
+        }
+        if (Object.keys(states).length > MAX_STATES) {
+            return {
+                ok: false,
+                error: `Too many block states in "${input}" (max ${MAX_STATES}).`
+            };
+        }
+    }
+    return { ok: true, block, states: normalizeStates(states) };
+}

package/build/world/block-states.js

@@ -0,0 +1,43 @@
+export const EMPTY_BLOCK_STATES = Object.freeze({});
+const MAX_STATE_NAME_LENGTH = 64;
+const MAX_STATE_VALUE_LENGTH = 64;
+const SAFE_STATE_NAME = /^[a-z0-9_]+$/;
+const SAFE_STATE_VALUE = /^[a-z0-9_.-]+$/;
+const RESERVED_STATE_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+export function isSafeStateName(name) {
+    const normalized = name.toLowerCase();
+    return (normalized.length > 0 &&
+        normalized.length <= MAX_STATE_NAME_LENGTH &&
+        SAFE_STATE_NAME.test(normalized) &&
+        !RESERVED_STATE_NAMES.has(normalized));
+}
+export function isSafeStateValue(value) {
+    const normalized = value.toLowerCase();
+    return (normalized.length > 0 &&
+        normalized.length <= MAX_STATE_VALUE_LENGTH &&
+        SAFE_STATE_VALUE.test(normalized));
+}
+export function normalizeStates(states) {
+    if (!states) {
+        return EMPTY_BLOCK_STATES;
+    }
+    const entries = Object.entries(states)
+        .filter(([key, value]) => typeof value === 'string' &&
+        isSafeStateName(key) &&
+        isSafeStateValue(value))
+        .map(([key, value]) => [key.toLowerCase(), value.toLowerCase()])
+        .sort(([a], [b]) => a.localeCompare(b));
+    return Object.fromEntries(entries);
+}
+export function sameStates(a, b) {
+    const entries = Object.entries(a);
+    return (entries.length === Object.keys(b).length &&
+        entries.every(([key, value]) => b[key] === value));
+}
+export function formatStates(states) {
+    const entries = Object.entries(states).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0) {
+        return '';
+    }
+    return `[${entries.map(([key, value]) => `${key}=${value}`).join(',')}]`;
+}

package/build/world/simulated-dimension.js

@@ -1,5 +1,7 @@
 import { WORLD_LIMITS } from '../config/world-limits.js';
 import { getBlockByName, MINECRAFT_BLOCKS } from '../data/blocks.js';
+import { toErrorMessage } from '../utils/error-message.js';
+import { EMPTY_BLOCK_STATES, normalizeStates, sameStates } from './block-states.js';
 const AIR = getBlockByName('air') ?? MINECRAFT_BLOCKS[0];
 function coordinateKey(x, y, z) {
     return `${x},${y},${z}`;
@@ -7,8 +9,16 @@ function coordinateKey(x, y, z) {
 export class SimulatedDimension {
     info;
     blocks = new Map();
-    constructor(info) {
+    store;
+    writeDelayMs;
+    timer = null;
+    queue = Promise.resolve();
+    savePromise = null;
+    dirty = false;
+    constructor(info, store, writeDelayMs = 25) {
         this.info = info;
+        this.store = store;
+        this.writeDelayMs = writeDelayMs;
     }
     get modifiedBlockCount() {
         return this.blocks.size;
@@ -16,6 +26,24 @@ export class SimulatedDimension {
     get placedBlocks() {
         return [...this.blocks.values()];
     }
+    async load() {
+        const stored = await this.store.load(this.info.type);
+        let skipped = 0;
+        for (const placed of stored) {
+            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;
+            if (outOfRange || overLimit) {
+                skipped++;
+                continue;
+            }
+            this.blocks.set(key, placed);
+        }
+        if (skipped > 0) {
+            console.error(`[lzimul-minecraft-mcp] Skipped ${skipped} invalid block(s) while loading ${this.info.key}`);
+        }
+    }
     contains(x, y, z) {
         return (y >= this.info.minY &&
             y < this.info.maxY &&
@@ -24,13 +52,78 @@ export class SimulatedDimension {
             z >= WORLD_LIMITS.minHorizontal &&
             z <= WORLD_LIMITS.maxHorizontal);
     }
+    canSetBlock(x, y, z) {
+        return (this.blocks.has(coordinateKey(x, y, z)) ||
+            this.blocks.size < WORLD_LIMITS.maxModifiedBlocks);
+    }
     getBlock(x, y, z) {
         return this.blocks.get(coordinateKey(x, y, z))?.block ?? AIR;
     }
-    setBlock(x, y, z, block) {
+    getStates(x, y, z) {
+        return (this.blocks.get(coordinateKey(x, y, z))?.states ?? EMPTY_BLOCK_STATES);
+    }
+    setBlock(x, y, z, block, states = EMPTY_BLOCK_STATES) {
         const key = coordinateKey(x, y, z);
-        const previous = this.blocks.get(key)?.block ?? AIR;
-        this.blocks.set(key, { x, y, z, block });
+        const existing = this.blocks.get(key);
+        const previous = existing?.block ?? AIR;
+        const normalized = normalizeStates(states);
+        if (previous.key === block.key &&
+            sameStates(existing?.states ?? EMPTY_BLOCK_STATES, normalized)) {
+            return previous;
+        }
+        const isRemoval = block.key === AIR.key && Object.keys(normalized).length === 0;
+        if (!existing &&
+            !isRemoval &&
+            this.blocks.size >= WORLD_LIMITS.maxModifiedBlocks) {
+            throw new RangeError(`The ${this.info.displayName} world already holds the maximum of ${WORLD_LIMITS.maxModifiedBlocks} modified blocks.`);
+        }
+        if (isRemoval) {
+            this.blocks.delete(key);
+        }
+        else {
+            this.blocks.set(key, { x, y, z, block, states: normalized });
+        }
+        this.dirty = true;
+        this.scheduleFlush();
         return previous;
     }
+    async flush() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        while (this.savePromise !== null) {
+            await this.savePromise;
+        }
+        if (!this.dirty) {
+            await this.queue;
+            return;
+        }
+        this.dirty = false;
+        const snapshot = this.placedBlocks;
+        const run = this.queue.then(async () => {
+            await this.store.save(this.info.type, snapshot);
+        });
+        this.queue = run.catch(() => {
+            this.dirty = true;
+        });
+        this.savePromise = run;
+        try {
+            await run;
+        }
+        finally {
+            this.savePromise = null;
+        }
+    }
+    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)}`);
+            });
+        }, this.writeDelayMs);
+    }
 }

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

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+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;
+function warn(message) {
+    console.error(`[lzimul-minecraft-mcp] ${message}`);
+}
+export class FileWorldStore {
+    directory;
+    directoryReady = false;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async ensureDirectory() {
+        if (!this.directoryReady) {
+            await mkdir(this.directory, { recursive: true });
+            this.directoryReady = true;
+        }
+    }
+    fileFor(type) {
+        return path.join(this.directory, `${type}.json`);
+    }
+    async load(type) {
+        const file = this.fileFor(type);
+        let raw;
+        try {
+            const info = await stat(file);
+            if (info.size > MAX_SNAPSHOT_BYTES) {
+                await this.quarantine(file, `snapshot is larger than ${MAX_SNAPSHOT_BYTES} bytes`);
+                return [];
+            }
+            raw = await readFile(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw new Error(`Cannot read world snapshot ${file}: ${toErrorMessage(error)}`, { cause: error });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            await this.quarantine(file, 'invalid JSON');
+            return [];
+        }
+        if (!parsed || !Array.isArray(parsed.blocks)) {
+            await this.quarantine(file, 'missing blocks array');
+            return [];
+        }
+        if (parsed.blocks.length > WORLD_LIMITS.maxModifiedBlocks) {
+            await this.quarantine(file, `${parsed.blocks.length} blocks exceed the limit of ${WORLD_LIMITS.maxModifiedBlocks}`);
+            return [];
+        }
+        return parsed.blocks.flatMap(entry => {
+            const block = fromSerialized(entry);
+            if (block) {
+                return [block];
+            }
+            warn(`Skipped malformed block entry in ${file}`);
+            return [];
+        });
+    }
+    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}`);
+        }
+        const file = this.fileFor(type);
+        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 rename(temporary, file);
+        }
+        catch (error) {
+            this.directoryReady = false;
+            throw new Error(`Failed to write world snapshot ${file}: ${toErrorMessage(error)}`, { cause: error });
+        }
+    }
+    async quarantine(file, reason) {
+        const backup = `${file}.corrupt-${randomUUID()}`;
+        try {
+            await rename(file, backup);
+            warn(`World file ${file} is unusable (${reason}); moved it to ${backup}`);
+        }
+        catch (error) {
+            warn(`World file ${file} is unusable (${reason}); could not move it: ${toErrorMessage(error)}`);
+        }
+    }
+}

package/build/world/stores/index.js

@@ -0,0 +1,9 @@
+import { WORLD_STORAGE } from '../../config/storage.js';
+import { FileWorldStore } from './file-world-store.js';
+import { MemoryWorldStore } from './memory-world-store.js';
+export function createWorldStore() {
+    if (WORLD_STORAGE.kind === 'memory') {
+        return new MemoryWorldStore();
+    }
+    return new FileWorldStore(WORLD_STORAGE.directory);
+}

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

@@ -0,0 +1,14 @@
+import { WORLD_LIMITS } from '../../config/world-limits.js';
+export class MemoryWorldStore {
+    worlds = new Map();
+    async load(type) {
+        const stored = this.worlds.get(type);
+        return stored ? [...stored] : [];
+    }
+    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}`);
+        }
+        this.worlds.set(type, [...blocks]);
+    }
+}