mcbe-leveldb 1.13.1 → 1.14.0

package/Changelog.md

@@ -1,3 +1,30 @@
+# v1.14.0
+
+## Additions
+
+-   Added custom dimension support for chunk keys, and the `getChunkKeyIndices` and `generateChunkKeyFromIndices` functions.
+-   Added the following functions:
+    -   `dimensionVectorDimensionToInt`
+    -   `dimensionVectorDimensionToId`
+    -   `dimensionVectorDimensionToIdSync`
+    -   `dimensionIdToDimensionVectorDimension`
+    -   `dimensionIdToDimensionVectorDimensionSync`
+    -   `intToDimensionVectorDimension`
+    -   `getDimensionTypes`
+    -   `getDimensionTypesSync`
+    -   `getDimensionIds`
+    -   `getDimensionIdsSync`
+    -   `getDimensionNumericIds`
+    -   `getDimensionNumericIdsSync`
+
+## Changes
+
+-   The `dimension` field of dimension vectors is now a union of `Dimension` and `number` instead of just `Dimension`.
+
+## Fixes
+
+-   Fixed a bug where the `entries` field of the `DimensionNameIdTable` NBT schema was marked as optional.
+
 # v1.13.1
 
 ## Fixes

package/LevelUtils.d.ts

@@ -2,6 +2,8 @@ import NBT from "prismarine-nbt";
 import BiomeData from "./__biome_data__.ts";
 import type { LevelDB } from "@8crafter/leveldb-zlib";
 import type { NBTSchemas } from "./nbtSchemas.ts";
+import type { LooseAutocomplete } from "./types.js";
+import type { DimensionNameIdTable } from "./test/nbtSchemaTypeScriptInterfaces.js";
 /**
  * A tuple of length 16.
  *
@@ -1539,7 +1541,7 @@ export interface DimensionLocation extends Vector3 {
     /**
      * Dimension that this coordinate is associated with.
      */
-    dimension: Dimension;
+    dimension: Dimension | number;
 }
 /**
  * Represents a two-directional vector with an associated dimension.
@@ -1548,7 +1550,7 @@ export interface DimensionVector2 extends Vector2 {
     /**
      * Dimension that this coordinate is associated with.
      */
-    dimension: Dimension;
+    dimension: Dimension | number;
 }
 /**
  * Represents a two-directional vector with X and Z components and an associated dimension.
@@ -1557,7 +1559,7 @@ export interface DimensionVectorXZ extends VectorXZ {
     /**
      * Dimension that this coordinate is associated with.
      */
-    dimension: Dimension;
+    dimension: Dimension | number;
 }
 /**
  * Represents a two-directional vector with X and Z components and an associated dimension and a sub-chunk index.
@@ -1750,6 +1752,118 @@ export declare function splitRange([min, max]: [min: number, max: number], size:
  * @param blocksPerWord How many blocks fit inside one 32-bit integer.
  */
 export declare function writeBlockIndices(buffer: Buffer, blockDataOffset: number, block_indices: number[], bitsPerBlock: number, blocksPerWord: number): void;
+/**
+ * Converts the dimension of a dimension vector to a numeric ID.
+ *
+ * @param dimension The dimension to convert.
+ * @returns The numeric ID of the dimension.
+ */
+export declare function dimensionVectorDimensionToInt(dimension: Dimension | number): number;
+/**
+ * Converts the dimension of a dimension vector to a ID.
+ *
+ * Vanilla dimensions will not include a namespace.
+ *
+ * @param dimension The dimension to convert.
+ * @param db The LevelDB to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export declare function dimensionVectorDimensionToId(dimension: Dimension | number, db: LevelDB): Promise<LooseAutocomplete<Dimension>>;
+/**
+ * Converts the dimension of a dimension vector to a ID synchronously.
+ *
+ * Vanilla dimensions will not include a namespace.
+ *
+ * @param dimension The dimension to convert.
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export declare function dimensionVectorDimensionToIdSync(dimension: Dimension | number, dimensionNameIdTable: DimensionNameIdTable): LooseAutocomplete<Dimension>;
+/**
+ * Converts the ID of a dimension of a dimension vector.
+ *
+ * Vanilla dimensions do not require a namespace.
+ *
+ * @param dimension The dimension to convert. Case-sensitive.
+ * @param db The LevelDB to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export declare function dimensionIdToDimensionVectorDimension(dimension: LooseAutocomplete<Dimension>, db: LevelDB): Promise<Dimension | number>;
+/**
+ * Converts the ID of a dimension of a dimension vector synchronously.
+ *
+ * Vanilla dimensions do not require a namespace.
+ *
+ * @param dimension The dimension to convert. Case-sensitive.
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export declare function dimensionIdToDimensionVectorDimensionSync(dimension: LooseAutocomplete<Dimension>, dimensionNameIdTable: DimensionNameIdTable): Dimension | number;
+/**
+ * Converts a dimension's numeric ID to a dimension vector dimension.
+ *
+ * @param dimension The numeric ID of the dimension.
+ * @returns The dimension vector dimension.
+ */
+export declare function intToDimensionVectorDimension(dimension: number): Dimension | number;
+/**
+ * Gets the dimension types from the DimensionNameIdTable.
+ *
+ * @param db The LevelDB to use.
+ * @returns The dimension types.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ */
+export declare function getDimensionTypes(db: LevelDB): Promise<Record<Dimension | `${string}:${string}`, number>>;
+/**
+ * Gets the dimension types from the DimensionNameIdTable synchronously.
+ *
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The dimension types.
+ */
+export declare function getDimensionTypesSync(dimensionNameIdTable: DimensionNameIdTable): Record<Dimension | `${string}:${string}`, number>;
+/**
+ * Gets the dimension IDs from the DimensionNameIdTable.
+ *
+ * @param db The LevelDB to use.
+ * @returns The dimension IDs.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ */
+export declare function getDimensionIds(db: LevelDB): Promise<(Dimension | `${string}:${string}`)[]>;
+/**
+ * Gets the dimension IDs from the DimensionNameIdTable synchronously.
+ *
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The dimension IDs.
+ */
+export declare function getDimensionIdsSync(dimensionNameIdTable: DimensionNameIdTable): (Dimension | `${string}:${string}`)[];
+/**
+ * Gets the dimension numeric IDs from the DimensionNameIdTable.
+ *
+ * @param db The LevelDB to use.
+ * @returns The dimension numeric IDs.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ */
+export declare function getDimensionNumericIds(db: LevelDB): Promise<number[]>;
+/**
+ * Gets the dimension numeric IDs from the DimensionNameIdTable synchronously.
+ *
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The dimension numeric IDs.
+ */
+export declare function getDimensionNumericIdsSync(dimensionNameIdTable: DimensionNameIdTable): number[];
 /**
  * Gets the chunk indices from a LevelDB key.
  *

package/LevelUtils.js

@@ -2509,6 +2509,190 @@ export function writeBlockIndices(buffer, blockDataOffset, block_indices, bitsPe
         setInt32Val(buffer, blockDataOffset + wordIndex * 4, maskVal);
     }
 }
+/**
+ * Converts the dimension of a dimension vector to a numeric ID.
+ *
+ * @param dimension The dimension to convert.
+ * @returns The numeric ID of the dimension.
+ */
+export function dimensionVectorDimensionToInt(dimension) {
+    return typeof dimension === "string" ? dimensions.indexOf(dimension) : dimension;
+}
+/**
+ * Converts the dimension of a dimension vector to a ID.
+ *
+ * Vanilla dimensions will not include a namespace.
+ *
+ * @param dimension The dimension to convert.
+ * @param db The LevelDB to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export async function dimensionVectorDimensionToId(dimension, db) {
+    if (typeof dimension === "string")
+        return dimension;
+    const rawDimensionNameIdTable = await db.get("DimensionNameIdTable");
+    if (rawDimensionNameIdTable === null)
+        throw new ReferenceError("DimensionNameIdTable not found.");
+    const dimensionNameIdTable = NBT.parseUncompressed(rawDimensionNameIdTable, "little");
+    const dimensionNamespacedId = Object.entries(dimensionNameIdTable.value.entries.value).find(([_namespacedId, numericId]) => numericId.value === dimension)?.[0];
+    if (dimensionNamespacedId === undefined)
+        throw new ReferenceError(`Dimension ${dimension} not found in DimensionNameIdTable.`);
+    return dimensionNamespacedId;
+}
+/**
+ * Converts the dimension of a dimension vector to a ID synchronously.
+ *
+ * Vanilla dimensions will not include a namespace.
+ *
+ * @param dimension The dimension to convert.
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export function dimensionVectorDimensionToIdSync(dimension, dimensionNameIdTable) {
+    if (typeof dimension === "string")
+        return dimension;
+    const dimensionNamespacedId = Object.entries(dimensionNameIdTable.value.entries.value).find(([_namespacedId, numericId]) => numericId.value === dimension)?.[0];
+    if (dimensionNamespacedId === undefined)
+        throw new ReferenceError(`Dimension ${dimension} not found in DimensionNameIdTable.`);
+    return dimensionNamespacedId;
+}
+/**
+ * Converts the ID of a dimension of a dimension vector.
+ *
+ * Vanilla dimensions do not require a namespace.
+ *
+ * @param dimension The dimension to convert. Case-sensitive.
+ * @param db The LevelDB to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export async function dimensionIdToDimensionVectorDimension(dimension, db) {
+    if (dimensions.includes(dimension.replace(/^minecraft:/, "")))
+        return dimension.replace(/^minecraft:/, "");
+    const rawDimensionNameIdTable = await db.get("DimensionNameIdTable");
+    if (rawDimensionNameIdTable === null)
+        throw new ReferenceError("DimensionNameIdTable not found.");
+    const dimensionNameIdTable = NBT.parseUncompressed(rawDimensionNameIdTable, "little");
+    const dimensionNumericId = Object.entries(dimensionNameIdTable.value.entries.value).find(([namespacedId, _numericId]) => namespacedId === dimension)?.[1].value;
+    if (dimensionNumericId === undefined)
+        throw new ReferenceError(`Dimension ${dimension} not found in DimensionNameIdTable.`);
+    return dimensionNumericId;
+}
+/**
+ * Converts the ID of a dimension of a dimension vector synchronously.
+ *
+ * Vanilla dimensions do not require a namespace.
+ *
+ * @param dimension The dimension to convert. Case-sensitive.
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The ID of the dimension.
+ *
+ * @throws {ReferenceError} If the dimension is not found in the DimensionNameIdTable.
+ */
+export function dimensionIdToDimensionVectorDimensionSync(dimension, dimensionNameIdTable) {
+    if (dimensions.includes(dimension.replace(/^minecraft:/, "")))
+        return dimension.replace(/^minecraft:/, "");
+    const dimensionNumericId = Object.entries(dimensionNameIdTable.value.entries.value).find(([namespacedId, _numericId]) => namespacedId === dimension)?.[1].value;
+    if (dimensionNumericId === undefined)
+        throw new ReferenceError(`Dimension ${dimension} not found in DimensionNameIdTable.`);
+    return dimensionNumericId;
+}
+/**
+ * Converts a dimension's numeric ID to a dimension vector dimension.
+ *
+ * @param dimension The numeric ID of the dimension.
+ * @returns The dimension vector dimension.
+ */
+export function intToDimensionVectorDimension(dimension) {
+    return dimensions[dimension] ?? dimension;
+}
+/**
+ * Gets the dimension types from the DimensionNameIdTable.
+ *
+ * @param db The LevelDB to use.
+ * @returns The dimension types.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ */
+export async function getDimensionTypes(db) {
+    const rawDimensionNameIdTable = await db.get("DimensionNameIdTable");
+    if (rawDimensionNameIdTable === null)
+        throw new ReferenceError("DimensionNameIdTable not found.");
+    const dimensionNameIdTable = NBT.parseUncompressed(rawDimensionNameIdTable, "little");
+    return getDimensionTypesSync(dimensionNameIdTable);
+}
+/**
+ * Gets the dimension types from the DimensionNameIdTable synchronously.
+ *
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The dimension types.
+ */
+export function getDimensionTypesSync(dimensionNameIdTable) {
+    return {
+        ...Object.fromEntries(dimensions.map((dimension, i) => [dimension, i])),
+        ...Object.fromEntries(Object.entries(dimensionNameIdTable.value.entries.value).map(([namespacedId, numericId]) => [namespacedId, numericId.value])),
+    };
+}
+/**
+ * Gets the dimension IDs from the DimensionNameIdTable.
+ *
+ * @param db The LevelDB to use.
+ * @returns The dimension IDs.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ */
+export async function getDimensionIds(db) {
+    const rawDimensionNameIdTable = await db.get("DimensionNameIdTable");
+    if (rawDimensionNameIdTable === null)
+        throw new ReferenceError("DimensionNameIdTable not found.");
+    const dimensionNameIdTable = NBT.parseUncompressed(rawDimensionNameIdTable, "little");
+    return getDimensionIdsSync(dimensionNameIdTable);
+}
+/**
+ * Gets the dimension IDs from the DimensionNameIdTable synchronously.
+ *
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The dimension IDs.
+ */
+export function getDimensionIdsSync(dimensionNameIdTable) {
+    return [...new Set([...dimensions, ...Object.keys(dimensionNameIdTable.value.entries.value)])];
+}
+/**
+ * Gets the dimension numeric IDs from the DimensionNameIdTable.
+ *
+ * @param db The LevelDB to use.
+ * @returns The dimension numeric IDs.
+ *
+ * @throws {ReferenceError} If the DimensionNameIdTable is not found.
+ */
+export async function getDimensionNumericIds(db) {
+    const rawDimensionNameIdTable = await db.get("DimensionNameIdTable");
+    if (rawDimensionNameIdTable === null)
+        throw new ReferenceError("DimensionNameIdTable not found.");
+    const dimensionNameIdTable = NBT.parseUncompressed(rawDimensionNameIdTable, "little");
+    return getDimensionNumericIdsSync(dimensionNameIdTable);
+}
+/**
+ * Gets the dimension numeric IDs from the DimensionNameIdTable synchronously.
+ *
+ * @param dimensionNameIdTable The DimensionNameIdTable to use.
+ * @returns The dimension numeric IDs.
+ */
+export function getDimensionNumericIdsSync(dimensionNameIdTable) {
+    return [
+        ...new Set([
+            ...dimensions.map((_dimension, i) => i),
+            ...Object.values(dimensionNameIdTable.value.entries.value).map((numericId) => numericId.value),
+        ]),
+    ];
+}
 /**
  * Gets the chunk indices from a LevelDB key.
  *
@@ -2521,7 +2705,7 @@ export function getChunkKeyIndices(key) {
     return {
         x: getInt32Val(key, 0),
         z: getInt32Val(key, 4),
-        dimension: [13, 14].includes(key.length) ? (dimensions[getInt32Val(key, 8)] ?? "overworld") : "overworld",
+        dimension: [13, 14].includes(key.length) ? (dimensions[getInt32Val(key, 8)] ?? getInt32Val(key, 8)) : "overworld",
         ...([10, 14].includes(key.length) ? { subChunkIndex: (key.at(-1) << 24) >> 24 } : undefined),
     };
 }
@@ -2533,11 +2717,13 @@ export function getChunkKeyIndices(key) {
  * @returns The raw chunk key.
  */
 export function generateChunkKeyFromIndices(indices, chunkKeyType) {
+    if (typeof indices.dimension === "string" && dimensions.indexOf(indices.dimension) === -1)
+        throw new TypeError(`Invalid dimension: ${indices.dimension}. For custom dimensions please provide the numeric ID instead.`);
     const buffer = Buffer.alloc((indices.dimension === "overworld" ? 9 : 13) + +("subChunkIndex" in indices && indices.subChunkIndex !== undefined));
     setInt32Val(buffer, 0, indices.x);
     setInt32Val(buffer, 4, indices.z);
     if (indices.dimension !== "overworld")
-        setInt32Val(buffer, 8, dimensions.indexOf(indices.dimension) ?? 0);
+        setInt32Val(buffer, 8, typeof indices.dimension === "string" ? dimensions.indexOf(indices.dimension) : indices.dimension);
     buffer[8 + +(indices.dimension !== "overworld") * 4] = getIntFromChunkKeyType(chunkKeyType);
     if ("subChunkIndex" in indices && indices.subChunkIndex !== undefined)
         buffer[9 + +(indices.dimension !== "overworld") * 4] = indices.subChunkIndex;