mca-json 1.0.0

package/src/lib/chunk.ts

@@ -0,0 +1,389 @@
+/**
+ * A Chunk is a 16 x 383 x 16 portion of a Minecraft world. It's stored as NBT
+ * data in sections of 16 blocks in the Y axis. The Y axis range is from -64 to
+ * 320.
+ *
+ * This class helps manipulate the chunk data.
+ */
+
+import { Block, BlockInstance } from '../block/block';
+import { BlockData } from './block-data';
+import { Coords2d, Coords3d } from '../types/coords';
+import { NbtBase } from '../nbt/nbt-base';
+import { NbtCompound } from '../nbt/nbt-compound';
+import { NbtInt } from '../nbt/nbt-int';
+import { NbtList } from '../nbt/nbt-list';
+import { NbtLong } from '../nbt/nbt-long';
+import { NbtLongArray } from '../nbt/nbt-long-array';
+import { NbtString } from '../nbt/nbt-string';
+import { NbtTagType } from '../nbt/nbt-tag-type';
+
+export class Chunk {
+    private dataVersion: number;
+    private parsedSections = new Map<NbtCompound, BlockData>();
+    private rootNbt: NbtCompound;
+
+    /**
+     * Constructs a new chunk object from a given NBT tag.
+     *
+     * @param root the NBT tag containing the chunk's data
+     */
+    constructor(root: NbtBase<any>) {
+        if (!this.isValidChunkRoot(root)) {
+            throw new Error('Invalid chunk root tag');
+        }
+
+        this.rootNbt = root;
+
+        // 1.2.1 does not have this tag.
+        this.dataVersion = root.findChild<NbtInt>('DataVersion')?.data ?? 0;
+    }
+
+    /**
+     * Gets the block entity list tag.
+     */
+    blockEntities(): NbtList<NbtCompound> | undefined {
+        return (
+            // 1.18+
+            this.rootNbt.findChild<NbtList<NbtCompound>>('block_entities') ||
+            // up to 1.17
+            this.rootNbt.findChild<NbtList<NbtCompound>>('Level/TileEntities')
+        );
+    }
+
+    /**
+     * Gets a block's entity data
+     */
+    blockEntityData(coords: Coords3d): NbtCompound | undefined {
+        return this.blockEntities()?.data.find((tag: NbtCompound) => {
+            const x = tag.findChild<NbtInt>('x');
+            const y = tag.findChild<NbtInt>('y');
+            const z = tag.findChild<NbtInt>('z');
+
+            return (
+                x?.data === coords[0] &&
+                y?.data === coords[1] &&
+                z?.data === coords[2]
+            );
+        });
+    }
+
+    /**
+     * Gets the chunk's location in chunk coordinates.
+     *
+     * Returns a tuple of the chunk's X and Z coordinates.
+     */
+    chunkCoordinates(): Coords2d | undefined {
+        const x =
+            // 1.18+
+            this.rootNbt.findChild<NbtInt>('xPos') ||
+            // up to 1.17
+            this.rootNbt.findChild<NbtInt>('Level/xPos');
+        const z =
+            // 1.18+
+            this.rootNbt.findChild<NbtInt>('zPos') ||
+            // up to 1.17
+            this.rootNbt.findChild<NbtInt>('Level/zPos');
+
+        if (typeof x?.data !== 'number' || typeof z?.data !== 'number') {
+            return;
+        }
+
+        return [x.data, z.data];
+    }
+
+    /**
+     * Returns a unique id for this chunk. It's just the chunk's X and Z
+     * coordinates in number of chunks from the world's origin.
+     */
+    chunkKey(): string | undefined {
+        const coords = this.chunkCoordinates();
+
+        if (!coords) {
+            return;
+        }
+
+        return `${coords[0]},${coords[1]}`;
+    }
+
+    /**
+     * Returns an instance of a block at a given location using world
+     * coordinates.
+     */
+    getBlock(coords: Coords3d): BlockInstance {
+        const sectionY = Math.floor(coords[1] / 16);
+        const sectionsTag = this.sectionsTag();
+
+        if (!sectionsTag) {
+            throw new Error('Invalid chunk - no sections found');
+        }
+
+        const section = sectionsTag.data.find(
+            (section) => this.sectionY(section) === sectionY
+        );
+
+        if (!section) {
+            throw new Error('Block not found in any sections');
+        }
+
+        const blockData = this.parseSection(section);
+        const [xWorld, zWorld] = this.worldCoordinates() || [0, 0];
+        const xChunk = coords[0] - xWorld;
+        const zChunk = coords[2] - zWorld;
+
+        if (xChunk < 0 || xChunk > 15) {
+            throw new Error('X coordinate out of bounds');
+        }
+
+        if (zChunk < 0 || zChunk > 15) {
+            throw new Error('Z coordinate out of bounds');
+        }
+
+        const index = blockData.chunkCoordinatesToIndex([
+            xChunk,
+            coords[1] % 16,
+            zChunk,
+        ]);
+        const name = blockData.getBlockByIndex(index);
+
+        return Block.create(name, coords, this.blockEntityData(coords));
+    }
+
+    /**
+     * Finds all blocks by a given name. Provides [X, Y, Z] real-world coordinates.
+     */
+    findBlocksByName(name: string): Coords3d[] {
+        const sectionsTag = this.sectionsTag();
+
+        if (!sectionsTag) {
+            return [];
+        }
+
+        return sectionsTag.data.flatMap((section) => {
+            const yWorld = this.sectionY(section, true);
+            const [xWorld, zWorld] = this.worldCoordinates() || [0, 0];
+            const palette = this.sectionPalette(section);
+
+            if (palette === undefined) {
+                return [];
+            }
+
+            // // If it's not in the palette, we can skip processing.
+            if (!this.paletteNameList(palette).includes(name)) {
+                return [];
+            }
+
+            const blockData = this.parseSection(section);
+
+            return blockData.findBlocksByName(name).map((index): Coords3d => {
+                const chunkCoordinates =
+                    blockData.indexToChunkCoordinates(index);
+
+                return [
+                    xWorld + chunkCoordinates[0],
+                    yWorld + chunkCoordinates[1],
+                    zWorld + chunkCoordinates[2],
+                ];
+            });
+        });
+    }
+
+    /**
+     * See how long the chunk has been inhabited. This number increases by 1
+     * for each game tick, which is 20 times per second when a player is
+     * nearby. It can also advance slowly when players are farther away.
+     *
+     * On newly created chunks, this value does not match what is expected. Use
+     * this with caution.
+     */
+    inhabitedTime(): bigint | undefined {
+        return (
+            // 1.18+
+            this.rootNbt.findChild<NbtLong>('InhabitedTime')?.data ||
+            // up to 1.17
+            this.rootNbt.findChild<NbtLong>('Level/InhabitedTime')?.data
+        );
+    }
+
+    /**
+     * Converts the chunk data to a JSON object.
+     */
+    toObject(): any {
+        return this.rootNbt.toObject();
+    }
+
+    /**
+     * Returns a list of unique block names in the chunk as a Set.
+     */
+    uniqueBlockNames(): Set<string> {
+        const sectionsTag = this.sectionsTag();
+
+        if (!sectionsTag) {
+            return new Set();
+        }
+
+        const names = sectionsTag.data.flatMap((section) => {
+            const palette = this.sectionPalette(section);
+
+            if (!palette) {
+                return [];
+            }
+
+            return this.paletteNameList(palette);
+        });
+
+        return new Set(names);
+    }
+
+    /**
+     * Gets the chunk's location in real-world coordinates.
+     *
+     * Returns a tuple of the starting block's world X and Z coordinates. The
+     * chunk contains the range from X to X+15 (going East), Y to Y+15 (going
+     * up), and Z to Z+15 (going South).
+     */
+    worldCoordinates(): Coords2d | undefined {
+        const result = this.chunkCoordinates();
+
+        if (!result) {
+            return;
+        }
+
+        return [result[0] * 16, result[1] * 16];
+    }
+
+    /**
+     * Checks if the given NBT tag is a valid chunk root tag.
+     * @param tag the tag to check.
+     */
+    private isValidChunkRoot(nbt: NbtBase<any>): nbt is NbtCompound {
+        return nbt.isCompound('');
+    }
+
+    /**
+     * Checks if the given NBT tag is a valid chunk section tag, containing a list of chunk sections.
+     */
+    private isValidChunkSection(
+        nbt: NbtBase<any>
+    ): nbt is NbtList<NbtCompound> {
+        if (!nbt.isList(NbtTagType.COMPOUND)) {
+            return false;
+        }
+
+        // Java uses "sections", unsure what uses "Sections"
+        if (nbt.name.toLowerCase() === 'sections') {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Returns a list of names within a palette tag.
+     */
+    private paletteNameList(palette: NbtBase<any>): string[] {
+        if (!palette.isList(NbtTagType.COMPOUND)) {
+            return [];
+        }
+
+        return (palette as NbtList<NbtCompound>).data.map((tag) => {
+            const name = tag.findChild<NbtString>('Name');
+
+            return name?.data ?? '';
+        });
+    }
+
+    /**
+     * Parses a section tag into BlockData.
+     *
+     * Uses a cached version if available;
+     */
+    private parseSection(section: NbtCompound): BlockData {
+        if (this.parsedSections.has(section)) {
+            return this.parsedSections.get(section)!;
+        }
+
+        const palette = this.sectionPalette(section);
+
+        if (!palette) {
+            throw new Error('Invalid chunk section - no palette found');
+        }
+
+        const blockStates = this.sectionBlockStates(section);
+
+        if (!blockStates) {
+            throw new Error('Invalid chunk section - no block states found');
+        }
+
+        const blockData = BlockData.fromPaletteBlockStates(
+            this.dataVersion,
+            palette,
+            blockStates
+        );
+        this.parsedSections.set(section, blockData);
+
+        return blockData;
+    }
+
+    /**
+     * Finds the BlockStates tag in a section.
+     */
+    private sectionBlockStates(section: NbtCompound): NbtLongArray | undefined {
+        return (
+            // 1.18+
+            section.findChild<NbtLongArray>('block_states/data') ||
+            // up to 1.17
+            section.findChild<NbtLongArray>('BlockStates')
+        );
+    }
+
+    /**
+     * Finds the block palette in a section.
+     */
+    private sectionPalette(
+        section: NbtCompound
+    ): NbtList<NbtCompound> | undefined {
+        return (
+            // 1.18+
+            section.findChild<NbtList<NbtCompound>>('block_states/palette') ||
+            // up to 1.17
+            section.findChild<NbtList<NbtCompound>>('Palette')
+        );
+    }
+
+    /**
+     * Returns all sections
+     */
+    private sectionsTag(): NbtList<NbtCompound> | undefined {
+        const section =
+            // 1.18+
+            this.rootNbt.findChild<NbtList<NbtCompound>>('sections') ||
+            // up to 1.17
+            this.rootNbt.findChild<NbtList<NbtCompound>>('Level/Sections');
+
+        if (section && this.isValidChunkSection(section)) {
+            return section;
+        }
+
+        return;
+    }
+
+    /**
+     * Returns the Y coordinate of a section, which goes from 0 to 256. If you want the world coordinate, pass true to get -128 to 4031.
+     */
+    private sectionY(section: NbtCompound, useWorldCoordinate = false): number {
+        const ySection = section.findChild<NbtInt>('Y')?.data || 0;
+
+        if (!useWorldCoordinate) {
+            return ySection;
+        }
+
+        let yWorld = ySection * 16;
+
+        if (yWorld >= 4032) {
+            yWorld -= 4096;
+        }
+
+        return yWorld;
+    }
+}

package/src/nbt/nbt-base.ts

@@ -0,0 +1,38 @@
+import { BinaryData } from '../lib/binary-data';
+import { NbtTagType } from './nbt-tag-type';
+
+export abstract class NbtBase<T> {
+    static readName(bd: BinaryData) {
+        const nameLength = bd.getUShort();
+
+        return bd.getString(nameLength);
+    }
+
+    constructor(
+        public type: NbtTagType,
+        public data: T,
+        public name = '',
+    ) {}
+
+    /**
+     * Search for a child by path. Use '/' as separators.
+     *
+     * nbt.findChild('Level/Sections/0/BlockStates')
+     */
+    findChild<T extends NbtBase<any>>(_path: string): T | undefined {
+        // By default, most elements do not have children.
+        return;
+    }
+
+    isCompound(_name?: string): boolean {
+        return false;
+    }
+
+    isList(_subtype?: NbtTagType): boolean {
+        return false;
+    }
+
+    abstract toObject(): any;
+
+    abstract toSnbt(): string;
+}

package/src/nbt/nbt-byte-array.ts

@@ -0,0 +1,38 @@
+import debug from 'debug';
+import { BinaryData } from '../lib/binary-data';
+import { NbtBase } from './nbt-base';
+import { NbtTagType } from './nbt-tag-type';
+
+const debugLogFromBinaryData = debug('nbt:byte-array:from-binary-data');
+
+export class NbtByteArray extends NbtBase<number[]> {
+    static fromBinaryData(bd: BinaryData, name?: string): NbtByteArray {
+        name ??= NbtByteArray.readName(bd);
+        const data: number[] = [];
+        const length = bd.getInt();
+        debugLogFromBinaryData(`BYTE_ARRAY, name ${name}, length ${length}`);
+
+        for (let i = 0; i < length; i++) {
+            data.push(bd.getByte());
+        }
+
+        debugLogFromBinaryData(`BYTE_ARRAY, data ${data}`);
+
+        return new NbtByteArray(data, name);
+    }
+
+    constructor(data: number[], name?: string) {
+        super(NbtTagType.BYTE_ARRAY, data, name);
+    }
+
+    toObject() {
+        return {
+            type: this.type,
+            byteArray: this.data,
+        };
+    }
+
+    toSnbt() {
+        return `[B;${this.data.map((v) => `${v}b`).join(',')}]`;
+    }
+}

package/src/nbt/nbt-byte.ts

@@ -0,0 +1,31 @@
+import debug from 'debug';
+import { BinaryData } from '../lib/binary-data';
+import { NbtBase } from './nbt-base';
+import { NbtTagType } from './nbt-tag-type';
+
+const debugLogFromBinaryData = debug('nbt:byte:from-binary-data');
+
+export class NbtByte extends NbtBase<number> {
+    static fromBinaryData(bd: BinaryData, name?: string): NbtByte {
+        name ??= NbtByte.readName(bd);
+        const data = bd.getByte();
+        debugLogFromBinaryData(`BYTE, name ${name}, data ${data}`);
+
+        return new NbtByte(data, name);
+    }
+
+    constructor(data: number, name?: string) {
+        super(NbtTagType.BYTE, data, name);
+    }
+
+    toObject() {
+        return {
+            type: this.type,
+            byte: this.data,
+        };
+    }
+
+    toSnbt() {
+        return `${this.data}b`;
+    }
+}

package/src/nbt/nbt-compound.ts

@@ -0,0 +1,95 @@
+import debug from 'debug';
+import { BinaryData } from '../lib/binary-data';
+import { Nbt } from './nbt';
+import { NbtBase } from './nbt-base';
+import { NbtTagType } from './nbt-tag-type';
+
+const debugLogFromBinaryData = debug('nbt:compound:from-binary-data');
+const debugLogFindChild = debug('nbt:compound:find-child');
+
+export class NbtCompound extends NbtBase<NbtBase<any>[]> {
+    static fromBinaryData<T>(bd: BinaryData, name?: string): NbtCompound {
+        name ??= NbtCompound.readName(bd);
+        const data: NbtBase<T>[] = [];
+        debugLogFromBinaryData(`COMPOUND, name ${name}, starting`);
+
+        // Careful - this does not store the END tag
+        let tag = Nbt.getTag(bd);
+        debugLogFromBinaryData(
+            `COMPOUND, name ${name}, tag ${tag.type} was retrieved`
+        );
+
+        while (tag && tag.type !== NbtTagType.END) {
+            data.push(tag);
+            tag = Nbt.getTag(bd);
+            debugLogFromBinaryData(
+                `COMPOUND, name ${name}, tag ${tag.type} was retrieved`
+            );
+        }
+
+        debugLogFromBinaryData(`COMPOUND, name ${name}, finished`);
+
+        return new NbtCompound(data, name);
+    }
+
+    constructor(data: NbtBase<any>[], name?: string) {
+        super(NbtTagType.COMPOUND, data, name);
+    }
+
+    override findChild<RESULT extends NbtBase<any>>(path: string) {
+        const pathSegments = path.split('/');
+        const currentSegment = pathSegments.shift();
+        const result = this.data.find((item) => item.name === currentSegment);
+        debugLogFindChild(
+            `COMPOUND, name ${this.name}, path ${path}, found? ${!!result}`
+        );
+
+        if (!result) {
+            return;
+        }
+
+        if (pathSegments.length) {
+            return result.findChild<RESULT>(pathSegments.join('/'));
+        }
+
+        return result as RESULT;
+    }
+
+    override isCompound(name?: string) {
+        if (name !== undefined && this.name !== name) {
+            return false;
+        }
+
+        return true;
+    }
+
+    toObject() {
+        const compound: Record<string, any> = {};
+
+        for (const item of this.data) {
+            const name = item.name;
+
+            if (compound[name]) {
+                console.error('Corrupt chunk - duplicate key found', name);
+            }
+
+            compound[name] = item.toObject();
+        }
+
+        return {
+            type: this.type,
+            compound,
+        };
+    }
+
+    toSnbt() {
+        const compound: string[] = [];
+
+        for (const item of this.data) {
+            const itemSnbt = item.toSnbt();
+            compound.push(`${item.name}:${itemSnbt}`);
+        }
+
+        return `{${compound.join(',')}}`;
+    }
+}

package/src/nbt/nbt-double.ts

@@ -0,0 +1,31 @@
+import debug from 'debug';
+import { BinaryData } from '../lib/binary-data';
+import { NbtBase } from './nbt-base';
+import { NbtTagType } from './nbt-tag-type';
+
+const debugLogFromBinaryData = debug('nbt:double:from-binary-data');
+
+export class NbtDouble extends NbtBase<number> {
+    static fromBinaryData(bd: BinaryData, name?: string): NbtDouble {
+        name ??= NbtDouble.readName(bd);
+        const data = bd.getDouble();
+        debugLogFromBinaryData(`DOUBLE, name ${name}, data ${data}`);
+
+        return new NbtDouble(data, name);
+    }
+
+    constructor(data: number, name?: string) {
+        super(NbtTagType.DOUBLE, data, name);
+    }
+
+    toObject() {
+        return {
+            type: this.type,
+            double: this.data,
+        };
+    }
+
+    toSnbt() {
+        return `${this.data}d`;
+    }
+}

package/src/nbt/nbt-end.ts

@@ -0,0 +1,27 @@
+import debug from 'debug';
+import { NbtBase } from './nbt-base';
+import { NbtTagType } from './nbt-tag-type';
+
+const debugLogFromBinaryData = debug('nbt:end:from-binary-data');
+
+export class NbtEnd extends NbtBase<null> {
+    static fromBinaryData(): NbtEnd {
+        debugLogFromBinaryData('END');
+
+        return new NbtEnd();
+    }
+
+    constructor() {
+        super(NbtTagType.END, null, '');
+    }
+
+    toObject() {
+        return {
+            type: this.type,
+        };
+    }
+
+    toSnbt(): string {
+        throw new Error('END tag cannot be converted to SNBT');
+    }
+}

package/src/nbt/nbt-float.ts

@@ -0,0 +1,31 @@
+import debug from 'debug';
+import { BinaryData } from '../lib/binary-data';
+import { NbtBase } from './nbt-base';
+import { NbtTagType } from './nbt-tag-type';
+
+const debugLogFromBinaryData = debug('nbt:float:from-binary-data');
+
+export class NbtFloat extends NbtBase<number> {
+    static fromBinaryData(bd: BinaryData, name?: string): NbtFloat {
+        name ??= NbtFloat.readName(bd);
+        const data = bd.getFloat();
+        debugLogFromBinaryData(`FLOAT, name ${name}, data ${data}`);
+
+        return new NbtFloat(data, name);
+    }
+
+    constructor(data: number, name?: string) {
+        super(NbtTagType.FLOAT, data, name);
+    }
+
+    toObject() {
+        return {
+            type: this.type,
+            float: this.data,
+        };
+    }
+
+    toSnbt() {
+        return `${this.data}f`;
+    }
+}