stonecut-map-builder 0.0.0-stage → 0.1.0

package/dist/tools/files.js

@@ -0,0 +1,51 @@
+import { existsSync } from 'node:fs';
+import { z } from 'zod';
+import { listFiles, readServerFile, writeServerFile } from '../ops/files.js';
+import { serverPath } from '../ops/world.js';
+import { confirm, serverRelPath } from '../schemas.js';
+import { tool } from './define.js';
+export const fileTools = [
+    tool({
+        name: 'list_files',
+        title: 'List files in the server folder',
+        description: 'Lists files and folders inside the test server folder, for example world/datapacks, config or mods. Paths are relative to the server folder; nothing outside it can be listed.',
+        input: {
+            path: z.string().max(512).default('.').describe('Folder inside the server folder. Default the server folder itself.'),
+            depth: z.number().int().min(1).max(5).default(1).describe('How many levels deep. Default 1.'),
+        },
+        readOnly: true,
+        destructive: false,
+        idempotent: true,
+        run: async (a, ctx) => listFiles(ctx.server(), a.path, a.depth),
+    }),
+    tool({
+        name: 'read_file',
+        title: 'Read a file in the server folder',
+        description: 'Reads a file inside the test server folder: configs, datapack files, logs. Use encoding base64 for binary files. The RCON password in server.properties is hidden. Limited to maxFileBytes.',
+        input: {
+            path: serverRelPath,
+            encoding: z.enum(['text', 'base64']).default('text'),
+        },
+        readOnly: true,
+        destructive: false,
+        idempotent: true,
+        run: async (a, ctx) => readServerFile(ctx.server(), ctx.config, a.path, a.encoding),
+    }),
+    tool({
+        name: 'write_file',
+        title: 'Write a file in the server folder',
+        description: "Writes a file inside the test server folder, making folders as needed: datapacks (world/datapacks/...), configs, server.properties. Mods (.jar files and the mods folder) only if the person allowed it (allowModInstall). The world's chunk files, level.dat and eula.txt cannot be written. After writing server.properties the tool keeps RCON on 127.0.0.1. Use encoding base64 for binary files. Limited to maxFileBytes.",
+        input: {
+            path: serverRelPath,
+            content: z.string().describe('File content, as text or base64'),
+            encoding: z.enum(['text', 'base64']).default('text'),
+            overwrite: z.boolean().optional().describe('Replace a file that exists. Default false.'),
+            confirm,
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        needsOk: (a, ctx) => (a.overwrite && existsSync(serverPath(ctx.server(), a.path)) ? `replace the existing file ${a.path}` : null),
+        run: async (a, ctx) => writeServerFile(ctx.server(), ctx.config, a.path, a.content, a.encoding, a.overwrite ?? false),
+    }),
+];

package/dist/tools/schematic.js

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import { z } from 'zod';
+import { makeBox } from '../mc/box.js';
+import { serverPath } from '../ops/world.js';
+import { confirm, dimension, includeEntities, schemPath, skipBackup, vec3 } from '../schemas.js';
+import { tool } from './define.js';
+export const schematicTools = [
+    tool({
+        name: 'import_schematic',
+        title: 'Import a .schem into the world',
+        description: 'Pastes a Sponge schematic (.schem, version 2 or 3, as WorldEdit and most editors save) from the test server folder into the world with its lowest corner at origin, including chests, signs and other block data. include_air (default true) clears the area first so the result matches the file exactly. Snapshots the area first for undo. Entities in the file (item frames, paintings, armor stands, mobs, minecarts, boats) are summoned after the blocks, with fresh UUIDs; leads stay tied and riders stay seated. include_air also removes the entities already in the area. Limited to maxImportBlocks and maxEntities.',
+        input: {
+            file: schemPath,
+            origin: vec3.describe('Where the lowest corner goes [x, y, z]'),
+            include_air: z.boolean().default(true).describe('Clear the area first so air in the file replaces what is there. Default true.'),
+            include_entities: includeEntities,
+            dimension,
+            confirm,
+            skip_backup: skipBackup,
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        needsOk: (a) => `paste ${a.file} at ${a.origin.join(' ')}, replacing what is in that area`,
+        run: async (a, ctx) => {
+            const file = serverPath(ctx.server(), a.file);
+            if (!existsSync(file))
+                throw new Error(`No file at ${a.file}. Put the .schem inside the test server folder, for example in schematics/.`);
+            return ctx.world().importFile(file, a.origin, a.include_air, { dimension: a.dimension, ...(a.skip_backup ? { skipBackup: true } : {}) }, a.include_entities ?? ctx.config.includeEntities);
+        },
+    }),
+    tool({
+        name: 'export_schematic',
+        title: 'Export an area to .schem',
+        description: 'Saves the box from..to as a Sponge schematic (.schem) inside the test server folder, with block states and block data (chest contents, sign text). Version 3 (default) suits WorldEdit 7.3 and newer; use version 2 for older tools. The file can be pasted on any server with WorldEdit or a similar plugin. Entities whose position is inside the box (item frames, paintings, armor stands, mobs, minecarts, boats) are saved with all their data. Limited to maxImportBlocks and maxEntities.',
+        input: {
+            from: vec3,
+            to: vec3,
+            file: schemPath,
+            version: z.union([z.literal(2), z.literal(3)]).default(3).describe('Sponge schematic version, 3 (default) or 2'),
+            overwrite: z.boolean().optional().describe('Replace a file that exists. Default false.'),
+            include_entities: includeEntities,
+            dimension,
+            confirm,
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        needsOk: (a, ctx) => (a.overwrite && existsSync(serverPath(ctx.server(), a.file)) ? `replace the existing file ${a.file}` : null),
+        run: async (a, ctx) => {
+            const file = serverPath(ctx.server(), a.file);
+            if (existsSync(file) && !a.overwrite)
+                throw new Error(`${a.file} exists. Call again with overwrite: true to replace it.`);
+            if (!ctx.config.allowFileWrites)
+                throw new Error('File writes are turned off (allowFileWrites is false in the config).');
+            return ctx.world().exportFile(makeBox(a.from, a.to), file, a.version, a.dimension, a.include_entities ?? ctx.config.includeEntities);
+        },
+    }),
+];

package/dist/tools/server.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { makeBox } from '../mc/box.js';
+import { classifyReply } from '../rcon/rcon.js';
+import { inDimension } from '../ops/world.js';
+import { command, dimension, vec3 } from '../schemas.js';
+import { tool } from './define.js';
+export const serverTools = [
+    tool({
+        name: 'start_server',
+        title: 'Start the test server',
+        description: 'Starts the active test server in the background and waits until RCON answers (the first start makes the world and can take a minute or two). Before starting it puts back the settings the tool depends on: listen on 127.0.0.1 only, RCON on, no query port. The person then joins in Minecraft at localhost:<game port>.',
+        input: {},
+        readOnly: false,
+        destructive: false,
+        idempotent: true,
+        run: async (_a, ctx) => {
+            const s = ctx.server();
+            const r = await s.start();
+            return {
+                started: true,
+                seconds: r.seconds,
+                join_address: `localhost:${s.gamePort}`,
+                ...(r.fixed.length ? { settings_put_back: r.fixed } : {}),
+                tip: 'To let the person use commands in game, run_command "op <their Minecraft name>".',
+            };
+        },
+    }),
+    tool({
+        name: 'stop_server',
+        title: 'Stop the test server',
+        description: 'Stops the test server cleanly through RCON (the world is saved) and waits for it to exit. force: true ends the process if it does not answer; unsaved changes may then be lost.',
+        input: {
+            force: z.boolean().optional().describe('End the process if it does not answer on RCON. Default false.'),
+        },
+        readOnly: false,
+        destructive: false,
+        idempotent: true,
+        run: async (a, ctx) => {
+            const r = await ctx.server().stop(a.force ?? false);
+            return { stopped: true, ...r };
+        },
+    }),
+    tool({
+        name: 'restart_server',
+        title: 'Restart the test server',
+        description: 'Stops the server cleanly and starts it again, for example after changing server.properties, datapacks that need a restart, or mods.',
+        input: {},
+        readOnly: false,
+        destructive: false,
+        idempotent: false,
+        run: async (_a, ctx) => {
+            const s = ctx.server();
+            const st = await s.status();
+            const stopped = st.running ? await s.stop(false) : null;
+            const started = await s.start();
+            return { stop_seconds: stopped?.seconds ?? 0, start_seconds: started.seconds, join_address: `localhost:${s.gamePort}` };
+        },
+    }),
+    tool({
+        name: 'server_logs',
+        title: 'Read the server log',
+        description: 'The last lines of the server log (logs/latest.log), or of the console output if the server failed to start. Optional filter keeps only lines containing that text. The RCON password is hidden.',
+        input: {
+            lines: z.number().int().min(1).max(500).default(80).describe('How many lines. Default 80.'),
+            filter: z.string().max(200).optional().describe('Only lines containing this text (not case sensitive)'),
+        },
+        readOnly: true,
+        destructive: false,
+        idempotent: true,
+        run: async (a, ctx) => ({ lines: ctx.server().logs(a.lines, a.filter) }),
+    }),
+    tool({
+        name: 'run_command',
+        title: 'Run a server command',
+        description: 'Runs any Minecraft server command through RCON and returns the reply, for example gamerule, time, weather, summon, give, op, reload, function, scoreboard, team, tp, data. Commands from mods and datapacks work too. Give backup_area to snapshot an area first so undo can put it back; otherwise this cannot be undone.',
+        input: {
+            command,
+            backup_area: z.object({ from: vec3, to: vec3 }).optional().describe('Area this command may change; it is saved first so undo can restore it'),
+            dimension: dimension.describe('Dimension to run the command in (and of backup_area). Default overworld.'),
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: false,
+        run: async (a, ctx) => {
+            const w = ctx.world();
+            const opts = { dimension: a.dimension };
+            let undo = null;
+            const exec = async () => {
+                if (a.backup_area)
+                    undo = (await w.snapshot(makeBox(a.backup_area.from, a.backup_area.to), a.dimension, `command: ${a.command.slice(0, 60)}`, opts))?.id ?? null;
+                return (await ctx.server().connection()).command(inDimension(a.dimension, a.command.replace(/^\//, '')));
+            };
+            const reply = a.backup_area ? await w.withLoaded([makeBox(a.backup_area.from, a.backup_area.to)], a.dimension, exec) : await exec();
+            return { reply, looks_like: classifyReply(reply), undo };
+        },
+    }),
+];

package/dist/tools/setup.js

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+import { findJava } from '../mc/java.js';
+import { createServer, planSetup } from '../mc/setup.js';
+import { eulaAccepted, writeEula } from '../mc/testserver.js';
+import { EULA_URL } from '../mc/versions.js';
+import { listBackups } from '../ops/backup.js';
+import { tool } from './define.js';
+function showPlan(p) {
+    return {
+        plan_id: p.planId,
+        ready: p.ready,
+        folder: p.folder,
+        minecraft: p.minecraft,
+        loader: p.loader,
+        ...(p.loaderVersion ? { neoforge_version: p.loaderVersion, neoforge_is_beta: p.loaderIsBeta } : {}),
+        java: p.java
+            ? { needed: p.javaNeeded, using: p.java.path, version: p.java.version }
+            : { needed: p.javaNeeded, found: p.javaFound.map((j) => `${j.path} (Java ${j.major})`), missing: true, where_to_get_it: p.javaMissing },
+        downloads: p.downloads.map((d) => ({ what: d.what, from: d.source, url: d.url, checked_with: `${d.hash.algo} ${d.hash.value}`, ...(d.size ? { bytes: d.size } : {}) })),
+        game_port: p.gamePort,
+        rcon_port: p.rconPort,
+        memory_mb: p.memoryMb,
+        world_type: p.worldType,
+        eula: `The person must read and accept the Minecraft EULA themselves before the server can start: ${p.eulaUrl}`,
+        next: p.ready
+            ? 'Show this plan to the person: what gets downloaded, from where, the folder and the ports. Only if they say yes, call create_server with this plan_id and person_confirmed: true. The plan expires in 30 minutes.'
+            : `Java ${p.javaNeeded} or newer is missing. Tell the person where to get it (where_to_get_it), wait until they have installed it, then call plan_setup again. Do not install Java yourself unless they ask you to.`,
+    };
+}
+export const setupTools = [
+    tool({
+        name: 'status',
+        title: 'Status and settings',
+        description: 'Call this first. Shows the person\'s safety settings (config file, allowed server folders, size limits, file and mod rules), the active test server (version, folder, running or not, ports, EULA), Java found on this computer, the undo history and world backups.',
+        input: {},
+        readOnly: true,
+        destructive: false,
+        idempotent: true,
+        run: async (_args, ctx) => {
+            const c = ctx.config;
+            const s = ctx.current();
+            const settings = {
+                config_file: c.file,
+                config_file_exists: c.fileExists,
+                server_folders: c.serverFolders,
+                maxFillBlocks: c.maxFillBlocks,
+                maxReadBlocks: c.maxReadBlocks,
+                maxImportBlocks: c.maxImportBlocks,
+                maxFileBytes: c.maxFileBytes,
+                maxEntities: c.maxEntities,
+                includeEntities: c.includeEntities,
+                allowFileWrites: c.allowFileWrites,
+                allowModInstall: c.allowModInstall,
+                confirmDestructive: c.confirmDestructive,
+                autoBackup: c.autoBackup,
+                undoHistory: c.undoHistory,
+                rconAddress: c.rconAddress,
+            };
+            if (!s) {
+                const java = await findJava(c.javaPath ? [c.javaPath] : []);
+                return {
+                    settings,
+                    server: null,
+                    java_found: java.map((j) => `${j.path} (Java ${j.major})`),
+                    next: 'No test server yet. Ask the person which Minecraft version and which modpack (or plain vanilla) they use, recommend a separate test server, then call plan_setup.',
+                };
+            }
+            const st = await s.status();
+            return {
+                settings,
+                server: {
+                    folder: s.dir,
+                    minecraft: s.meta.minecraft,
+                    loader: s.meta.loader,
+                    ...(s.meta.loaderVersion ? { loader_version: s.meta.loaderVersion } : {}),
+                    running: st.running,
+                    rcon_connected: st.rcon,
+                    join_address: `localhost:${s.gamePort}`,
+                    rcon_port: s.meta.rconPort,
+                    eula_accepted: eulaAccepted(s.dir),
+                    java: s.meta.javaPath,
+                },
+                known_servers: ctx.knownServers(),
+                undo: ctx.world().undo.list().map((u) => ({ id: u.id, label: u.label, from: u.box.min, to: u.box.max, dimension: u.dimension, time: u.time })),
+                world_backups: listBackups(s),
+            };
+        },
+    }),
+    tool({
+        name: 'plan_setup',
+        title: 'Plan a test server (changes nothing)',
+        description: 'Looks up everything needed for a new local test server and changes nothing: the exact Minecraft (and NeoForge) version, which Java it needs and whether it is installed, every file that would be downloaded with its official source and hash, the folder and the ports. Show the result to the person and ask before create_server. Minecraft Java Edition 1.20.1 or newer.',
+        input: {
+            minecraft: z.string().min(1).max(20).describe('Minecraft version such as "1.21.11", or "latest" for the newest release'),
+            loader: z.enum(['vanilla', 'neoforge']).describe('vanilla, or neoforge for modpacks'),
+            name: z.string().min(1).max(40).default('test-server').describe('Folder name for the server. Default "test-server".'),
+            server_folder: z.string().optional().describe('Which allowed folder to put it in (see status). Default the first one.'),
+            game_port: z.number().int().min(1024).max(65535).optional().describe('Port to join on. Default: the first free port from 25565.'),
+            rcon_port: z.number().int().min(1024).max(65535).optional().describe('RCON port on 127.0.0.1. Default: the first free port from 25575.'),
+            memory_mb: z.number().int().min(1024).max(32768).optional().describe('Memory for the server. Default 2048 (vanilla) or 4096 (NeoForge).'),
+            world_type: z.enum(['flat', 'normal']).optional().describe('flat (default, good for building) or normal terrain'),
+            java_path: z.string().optional().describe('A specific java executable to use'),
+        },
+        readOnly: true,
+        destructive: false,
+        idempotent: true,
+        openWorld: true,
+        run: async (a, ctx) => {
+            const plan = await planSetup(ctx.config, {
+                minecraft: a.minecraft,
+                loader: a.loader,
+                name: a.name,
+                ...(a.server_folder ? { serverFolder: a.server_folder } : {}),
+                ...(a.game_port ? { gamePort: a.game_port } : {}),
+                ...(a.rcon_port ? { rconPort: a.rcon_port } : {}),
+                ...(a.memory_mb ? { memoryMb: a.memory_mb } : {}),
+                ...(a.world_type ? { worldType: a.world_type } : {}),
+                ...(a.java_path ? { javaPath: a.java_path } : {}),
+            });
+            for (const [id, p] of ctx.plans)
+                if (p.expires < Date.now())
+                    ctx.plans.delete(id);
+            ctx.plans.set(plan.planId, plan);
+            return showPlan(plan);
+        },
+    }),
+    tool({
+        name: 'create_server',
+        title: 'Create the planned test server',
+        description: 'Carries out a plan from plan_setup: makes the folder, downloads the server from the official source, checks every hash (nothing is kept if a hash is wrong), runs the NeoForge installer if chosen, and writes server.properties with RCON on 127.0.0.1 and a random password. Does not accept the EULA and does not start the server. Only call this after the person said yes to the plan.',
+        input: {
+            plan_id: z.string().uuid().describe('plan_id from plan_setup'),
+            person_confirmed: z.literal(true).describe('true only after you showed the person the plan (downloads, sources, folder, ports) and they said yes'),
+        },
+        readOnly: false,
+        destructive: false,
+        idempotent: false,
+        openWorld: true,
+        run: async (a, ctx) => {
+            const plan = ctx.plans.get(a.plan_id);
+            if (!plan)
+                throw new Error('Unknown or expired plan_id. Call plan_setup, show the person the plan, and use the new plan_id.');
+            const created = await createServer(plan);
+            ctx.plans.delete(a.plan_id);
+            ctx.setActive(created.folder);
+            return {
+                folder: created.folder,
+                minecraft: created.meta.minecraft,
+                loader: created.meta.loader,
+                downloaded: created.downloaded,
+                seconds: created.seconds,
+                next: `Show the person the Minecraft EULA (${EULA_URL}) and ask whether they accept it. Only if they say yes, call accept_eula with person_accepted: true. Then start_server.`,
+            };
+        },
+    }),
+    tool({
+        name: 'accept_eula',
+        title: 'Record that the person accepted the EULA',
+        description: `Writes eula=true for the active test server. Minecraft needs this to start. Only call it after you showed the person the Minecraft EULA (${EULA_URL}) and they said they accept it. Never accept it for them.`,
+        input: {
+            person_accepted: z.literal(true).describe('true only if the person read the EULA and said they accept it'),
+        },
+        readOnly: false,
+        destructive: false,
+        idempotent: true,
+        run: async (_a, ctx) => {
+            const s = ctx.server();
+            writeEula(s.dir, true);
+            return { folder: s.dir, eula_accepted: true, next: 'Call start_server.' };
+        },
+    }),
+    tool({
+        name: 'use_server',
+        title: 'Switch to another test server folder',
+        description: 'Makes another server folder the active one. It must be inside one of the allowed server folders in the person\'s config (see status). A server this tool did not make is adopted: the tool works out how to start it and keeps its settings, except that it always keeps RCON on 127.0.0.1.',
+        input: {
+            folder: z.string().min(1).describe('Full path of the server folder'),
+        },
+        readOnly: false,
+        destructive: false,
+        idempotent: true,
+        run: async (a, ctx) => {
+            const { server, adopted } = await ctx.adopt(a.folder);
+            return { folder: server.dir, adopted, loader: server.meta.loader, minecraft: server.meta.minecraft, eula_accepted: eulaAccepted(server.dir) };
+        },
+    }),
+];

package/dist/version.js

@@ -0,0 +1,2 @@
+export const VERSION = '0.1.0';
+export const SERVER_NAME = 'stonecut-map-builder';

package/dist/world/entities.js

@@ -0,0 +1,56 @@
+import { get, nbt, num } from '../nbt/nbt.js';
+import { readChunk, RegionError } from './region.js';
+export function entityPos(c) {
+    const p = c.value.get('Pos');
+    if (!p || p.type !== 'list' || p.value.length !== 3)
+        return null;
+    const v = p.value.map((t) => (t.type === 'double' || t.type === 'float' ? t.value : NaN));
+    return v.every(Number.isFinite) ? [v[0], v[1], v[2]] : null;
+}
+export function entityUuid(c) {
+    const u = get(c, 'UUID', 'intArray');
+    return u && u.value.length === 4 ? Array.from(u.value) : null;
+}
+/** A mob in its death animation is still saved for a moment; it is not part of the build. */
+function isDead(c) {
+    const health = num(c, 'Health');
+    return health !== undefined && health <= 0;
+}
+/** True when a position is inside the box, counting the whole of each edge block. */
+export function insideBox(p, box) {
+    return [0, 1, 2].every((i) => p[i] >= box.min[i] && p[i] < box.max[i] + 1);
+}
+export async function readEntities(dir, box) {
+    const out = [];
+    const regions = new Map();
+    for (let cx = Math.floor(box.min[0] / 16); cx <= Math.floor(box.max[0] / 16); cx++) {
+        for (let cz = Math.floor(box.min[2] / 16); cz <= Math.floor(box.max[2] / 16); cz++) {
+            const chunk = await readChunk(dir, regions, cx, cz);
+            if (!chunk)
+                continue;
+            const list = get(chunk, 'Entities', 'list');
+            if (!list)
+                continue;
+            for (const e of list.value) {
+                if (e.type !== 'compound')
+                    continue;
+                const id = get(e, 'id', 'string')?.value;
+                const pos = entityPos(e);
+                if (!id || !pos)
+                    throw new RegionError(`An entity in chunk ${cx},${cz} has no id or position`);
+                if (id === 'minecraft:player' || isDead(e) || !insideBox(pos, box))
+                    continue;
+                out.push({ id, pos, uuid: entityUuid(e), data: e });
+            }
+        }
+    }
+    return out;
+}
+/** Entities as schematic entries, with positions relative to the box's lowest corner. */
+export function toSchematicEntities(list, box) {
+    return list.map((e) => {
+        const data = nbt.compound(new Map(e.data.value));
+        data.value.delete('id');
+        return { id: e.id, pos: [e.pos[0] - box.min[0], e.pos[1] - box.min[1], e.pos[2] - box.min[2]], data };
+    });
+}

package/dist/world/region.js

@@ -0,0 +1,192 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { gunzipSync, inflateSync } from 'node:zlib';
+import { get, nbt, num, readNbt } from '../nbt/nbt.js';
+import { boxSize } from '../mc/box.js';
+// Reads blocks from the world's saved region files (Anvil format, Minecraft 1.18 and newer).
+// The server is asked to save first (save-all flush), so the files match the world. Read only.
+export const AIR = 'minecraft:air';
+const MAX_CHUNK_BYTES = 64 * 1024 * 1024;
+export class RegionError extends Error {
+}
+export function regionDir(worldDir, dimension, kind = 'region') {
+    const legacy = { overworld: kind, the_nether: join('DIM-1', kind), the_end: join('DIM1', kind) }[dimension];
+    const candidates = [join(worldDir, legacy), join(worldDir, 'dimensions', 'minecraft', dimension, kind)];
+    return candidates.find((c) => existsSync(c)) ?? candidates[0];
+}
+export function stateString(entry) {
+    const name = get(entry, 'Name', 'string')?.value;
+    if (!name)
+        throw new RegionError('Palette entry without a name');
+    const props = get(entry, 'Properties', 'compound');
+    if (!props || props.value.size === 0)
+        return name;
+    const parts = [...props.value.entries()]
+        .map(([k, v]) => `${k}=${v.type === 'string' ? v.value : String(v.value)}`)
+        .sort();
+    return `${name}[${parts.join(',')}]`;
+}
+/** Unpacks a section's block indices: 4096 entries, at least 4 bits each, entries never span two longs. */
+export function unpackIndices(data, paletteSize) {
+    const out = new Uint16Array(4096);
+    if (paletteSize <= 1 || !data)
+        return out;
+    const bits = Math.max(4, Math.ceil(Math.log2(paletteSize)));
+    const perLong = Math.floor(64 / bits);
+    const mask = (1n << BigInt(bits)) - 1n;
+    const need = Math.ceil(4096 / perLong);
+    if (data.length < need)
+        throw new RegionError(`Section data too short (${data.length} longs, need ${need})`);
+    for (let i = 0; i < 4096; i++) {
+        const word = BigInt.asUintN(64, data[Math.floor(i / perLong)]);
+        const v = Number((word >> BigInt((i % perLong) * bits)) & mask);
+        if (v >= paletteSize)
+            throw new RegionError('Section uses a palette index that does not exist');
+        out[i] = v;
+    }
+    return out;
+}
+/** The inverse of unpackIndices, used by tests to build region files. */
+export function packIndices(indices, paletteSize) {
+    const bits = Math.max(4, Math.ceil(Math.log2(paletteSize)));
+    const perLong = Math.floor(64 / bits);
+    const out = new BigInt64Array(Math.ceil(4096 / perLong));
+    const words = new Array(out.length).fill(0n);
+    for (let i = 0; i < 4096; i++) {
+        const w = Math.floor(i / perLong);
+        words[w] = words[w] | (BigInt(indices[i]) << BigInt((i % perLong) * bits));
+    }
+    words.forEach((w, i) => (out[i] = BigInt.asIntN(64, w)));
+    return out;
+}
+function decompress(kind, bytes) {
+    const opts = { maxOutputLength: MAX_CHUNK_BYTES };
+    if (kind === 1)
+        return gunzipSync(bytes, opts);
+    if (kind === 2)
+        return inflateSync(bytes, opts);
+    if (kind === 3)
+        return bytes;
+    if (kind === 4)
+        throw new RegionError('This world stores chunks with LZ4 (region-file-compression=lz4); set it back to deflate in server.properties');
+    throw new RegionError(`Unknown chunk compression ${kind}`);
+}
+export async function readChunk(dir, regions, cx, cz) {
+    const rx = Math.floor(cx / 32);
+    const rz = Math.floor(cz / 32);
+    const key = `${rx}.${rz}`;
+    if (!regions.has(key)) {
+        const file = join(dir, `r.${key}.mca`);
+        regions.set(key, existsSync(file) ? await readFile(file) : null);
+    }
+    const region = regions.get(key);
+    if (!region || region.length < 8192)
+        return null;
+    const slot = 4 * ((cx & 31) + (cz & 31) * 32);
+    const sector = (region[slot] << 16) | (region[slot + 1] << 8) | region[slot + 2];
+    if (sector === 0 || region[slot + 3] === 0)
+        return null;
+    const at = sector * 4096;
+    if (at + 5 > region.length)
+        throw new RegionError(`Region ${key} is cut short`);
+    const length = region.readUInt32BE(at);
+    const kind = region[at + 4];
+    let payload;
+    if (kind & 0x80) {
+        const external = join(dir, `c.${cx}.${cz}.mcc`);
+        if (!existsSync(external))
+            throw new RegionError(`Chunk ${cx},${cz} points to a missing ${external}`);
+        payload = await readFile(external);
+    }
+    else {
+        if (length < 1 || at + 4 + length > region.length)
+            throw new RegionError(`Chunk ${cx},${cz} is cut short`);
+        payload = region.subarray(at + 5, at + 4 + length);
+    }
+    return readNbt(decompress(kind & 0x7f, payload)).tag;
+}
+function isFull(chunk) {
+    const status = get(chunk, 'Status', 'string')?.value;
+    return status === undefined || status === 'minecraft:full' || status === 'full';
+}
+export async function readArea(dir, box) {
+    const [w, h, l] = boxSize(box);
+    const palette = [AIR];
+    const paletteIndex = new Map([[AIR, 0]]);
+    const blocks = new Uint32Array(w * h * l);
+    const blockEntities = [];
+    const missingChunks = [];
+    const regions = new Map();
+    let dataVersion = 0;
+    const [x0, y0, z0] = box.min;
+    const [x1, y1, z1] = box.max;
+    for (let cx = Math.floor(x0 / 16); cx <= Math.floor(x1 / 16); cx++) {
+        for (let cz = Math.floor(z0 / 16); cz <= Math.floor(z1 / 16); cz++) {
+            const chunk = await readChunk(dir, regions, cx, cz);
+            if (!chunk || !isFull(chunk)) {
+                missingChunks.push([cx, cz]);
+                continue;
+            }
+            dataVersion = Math.max(dataVersion, num(chunk, 'DataVersion') ?? 0);
+            const sections = get(chunk, 'sections', 'list');
+            if (!sections)
+                throw new RegionError(`Chunk ${cx},${cz} has no sections (worlds from Minecraft 1.18 or newer are supported)`);
+            for (const sec of sections.value) {
+                if (sec.type !== 'compound')
+                    continue;
+                const sy = num(sec, 'Y');
+                if (sy === undefined || sy * 16 > y1 || sy * 16 + 15 < y0)
+                    continue;
+                const states = get(sec, 'block_states', 'compound');
+                if (!states)
+                    continue;
+                const pal = get(states, 'palette', 'list');
+                if (!pal || pal.value.length === 0)
+                    continue;
+                const local = pal.value.map((e) => {
+                    const s = stateString(e);
+                    let i = paletteIndex.get(s);
+                    if (i === undefined) {
+                        i = palette.length;
+                        palette.push(s);
+                        paletteIndex.set(s, i);
+                    }
+                    return i;
+                });
+                const indices = unpackIndices(get(states, 'data', 'longArray')?.value, local.length);
+                const bx0 = Math.max(x0, cx * 16), bx1 = Math.min(x1, cx * 16 + 15);
+                const bz0 = Math.max(z0, cz * 16), bz1 = Math.min(z1, cz * 16 + 15);
+                const by0 = Math.max(y0, sy * 16), by1 = Math.min(y1, sy * 16 + 15);
+                for (let y = by0; y <= by1; y++) {
+                    for (let z = bz0; z <= bz1; z++) {
+                        for (let x = bx0; x <= bx1; x++) {
+                            const li = (((y & 15) * 16 + (z & 15)) * 16) + (x & 15);
+                            blocks[(x - x0) + (z - z0) * w + (y - y0) * w * l] = local[indices[li]];
+                        }
+                    }
+                }
+            }
+            const bes = get(chunk, 'block_entities', 'list');
+            for (const be of bes?.value ?? []) {
+                if (be.type !== 'compound')
+                    continue;
+                const bx = num(be, 'x'), by = num(be, 'y'), bz = num(be, 'z');
+                const id = get(be, 'id', 'string')?.value;
+                if (bx === undefined || by === undefined || bz === undefined || !id)
+                    continue;
+                if (bx < x0 || bx > x1 || by < y0 || by > y1 || bz < z0 || bz > z1)
+                    continue;
+                const data = nbt.compound(new Map(be.value));
+                for (const k of ['id', 'x', 'y', 'z', 'keepPacked'])
+                    data.value.delete(k);
+                const pos = [bx - x0, by - y0, bz - z0];
+                blockEntities.push({ pos, id, data });
+            }
+        }
+    }
+    return {
+        schematic: { width: w, height: h, length: l, offset: [0, 0, 0], dataVersion, palette, blocks, blockEntities },
+        missingChunks,
+    };
+}