mcbe-leveldb 1.11.0-jsonly → 1.12.0

package/Changelog.md

@@ -1,3 +1,10 @@
+# v1.12.0
+
+## Additions
+
+-   Added the `WorldClocks` content type.
+-   Added the `WorldClocks` NBT schema.
+
 # v1.11.0
 
 ## Additions

package/DBUtils.ts

@@ -0,0 +1,246 @@
+import type { LevelDB } from "@8crafter/leveldb-zlib";
+import { getContentTypeFromDBKey, type DBEntryContentType } from "./LevelUtils.ts";
+import NBT from "prismarine-nbt";
+import { JSONB } from "./utils/JSONB.ts";
+
+// TO-DO: Make an abstract class version of the LevelDB class to use as the type of the db parameter.
+
+/**
+ * Gets the keys from the LevelDB with a specific content type.
+ *
+ * @template T The content type to look for.
+ * @param db The LevelDB. Should match the type of the {@link LevelDB} class from the {@link https://www.npmjs.com/package/@8crafter/leveldb-zlib | @8crafter/leveldb-zlib} package. It does not have to be the one from that package, as long as the types match.
+ * @param type The {@link DBEntryContentType | content type} to look for.
+ * @returns The keys from the LevelDB with the specified content type, the keys are in Buffer format, this is because some keys contain binary data like chunk indices.
+ */
+export async function getKeysOfType<T extends DBEntryContentType>(db: LevelDB, type: T): Promise<Buffer<ArrayBuffer>[]>;
+/**
+ * Gets the keys from the list of LevelDB keys with a specific content type.
+ *
+ * @template T The content type to look for.
+ * @template TArrayBuffer The type of the buffers.
+ * @param dbKeys The LevelDB keys. Should be an array of Buffers.
+ * @param type The {@link DBEntryContentType | content type} to look for.
+ * @returns The keys from the provided LevelDB keys array with the specified content type, the keys are in Buffer format, this is because some keys contain binary data like chunk indices.
+ */
+export function getKeysOfType<T extends DBEntryContentType, TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>(
+    dbKeys: Buffer<TArrayBuffer>[],
+    type: T
+): Buffer<TArrayBuffer>[];
+export function getKeysOfType<T extends DBEntryContentType>(dbOrDBKeys: LevelDB | Buffer[], type: T): Promise<Buffer<ArrayBuffer>[]> | Buffer[] {
+    if (Array.isArray(dbOrDBKeys)) return dbOrDBKeys.filter((key: Buffer): boolean => getContentTypeFromDBKey(key) === type);
+    return new Promise(
+        (resolve: (value: Buffer<ArrayBuffer>[]) => void): void =>
+            void (async (): Promise<void> => {
+                const foundKeys: Buffer<ArrayBuffer>[] = [];
+                for await (const [rawKey, _value] of dbOrDBKeys.getIterator({ keys: true, keyAsBuffer: true, values: false })) {
+                    if (getContentTypeFromDBKey(rawKey) === type) foundKeys.push(rawKey);
+                }
+                resolve(foundKeys);
+            })()
+    );
+}
+
+/**
+ * Gets the keys from the LevelDB with one of the specified content types.
+ *
+ * @template T The content types to look for.
+ * @param db The LevelDB. Should match the type of the {@link LevelDB} class from the {@link https://www.npmjs.com/package/@8crafter/leveldb-zlib | @8crafter/leveldb-zlib} package. It does not have to be the one from that package, as long as the types match.
+ * @param types The {@link DBEntryContentType | content types} to look for.
+ * @returns An object mapping each of the specified content types to the keys from the LevelDB with that content type, the keys are in Buffer format, this is because some keys contain binary data like chunk indices.
+ */
+export async function getKeysOfTypes<T extends DBEntryContentType[] | readonly DBEntryContentType[]>(
+    db: LevelDB,
+    types: T
+): Promise<{ [key in T[number]]: Buffer<ArrayBuffer>[] }>;
+/**
+ * Gets the keys from the list of LevelDB keys with one of the specified content types.
+ *
+ * @template T The content types to look for.
+ * @template TArrayBuffer The type of the buffers.
+ * @param dbKeys The LevelDB keys. Should be an array of Buffers.
+ * @param types The {@link DBEntryContentType | content types} to look for.
+ * @returns An object mapping each of the specified content types to the keys from the provided LevelDB keys array with that content type, the keys are in Buffer format, this is because some keys contain binary data like chunk indices.
+ */
+export function getKeysOfTypes<T extends DBEntryContentType[] | readonly DBEntryContentType[], TArrayBuffer extends ArrayBufferLike>(
+    dbKeys: Buffer<TArrayBuffer>[],
+    types: T
+): { [key in T[number]]: Buffer<TArrayBuffer>[] };
+export function getKeysOfTypes<T extends DBEntryContentType[] | readonly DBEntryContentType[]>(
+    dbOrDBKeys: LevelDB | Buffer[],
+    types: T
+): Promise<{ [key in T[number]]: Buffer<ArrayBuffer>[] }> | { [key in T[number]]: Buffer[] } {
+    const results = {} as { [key in T[number]]: Buffer<any>[] };
+    types.forEach((contentType: T[number]): void => {
+        results[contentType] = [];
+    });
+    if (Array.isArray(dbOrDBKeys)) {
+        for (const key of dbOrDBKeys) {
+            const contentType: DBEntryContentType = getContentTypeFromDBKey(key);
+            if (types.includes(contentType)) results[contentType as T[number]].push(key);
+        }
+        return results;
+    }
+    return new Promise(
+        (resolve: (value: { [key in T[number]]: Buffer<ArrayBuffer>[] }) => void): void =>
+            void (async (): Promise<void> => {
+                for await (const [rawKey, _value] of dbOrDBKeys.getIterator({ keys: true, keyAsBuffer: true, values: false })) {
+                    const contentType: DBEntryContentType = getContentTypeFromDBKey(rawKey);
+                    if (types.includes(contentType)) results[contentType as T[number]].push(rawKey);
+                }
+                resolve(results);
+            })()
+    );
+}
+
+/**
+ * Gets the keys from the LevelDB with one of the specified content types.
+ *
+ * @template T The content types to look for.
+ * @param db The LevelDB. Should match the type of the {@link LevelDB} class from the {@link https://www.npmjs.com/package/@8crafter/leveldb-zlib | @8crafter/leveldb-zlib} package. It does not have to be the one from that package, as long as the types match.
+ * @param types The {@link DBEntryContentType | content types} to look for.
+ * @returns An object mapping each of the specified content types to the keys from the LevelDB with that content type, the keys are in Buffer format, this is because some keys contain binary data like chunk indices.
+ */
+export function getKeysOfTypesG<T extends DBEntryContentType[] | readonly DBEntryContentType[]>(
+    db: LevelDB,
+    types: T
+): AsyncGenerator<{ count: number; results: { [key in T[number]]: Buffer<ArrayBuffer>[] } }, { [key in T[number]]: Buffer<ArrayBuffer>[] }>;
+/**
+ * Gets the keys from the list of LevelDB keys with one of the specified content types.
+ *
+ * @template T The content types to look for.
+ * @template TArrayBuffer The type of the buffers.
+ * @param dbKeys The LevelDB keys. Should be an array of Buffers.
+ * @param types The {@link DBEntryContentType | content types} to look for.
+ * @returns An object mapping each of the specified content types to the keys from the provided LevelDB keys array with that content type, the keys are in Buffer format, this is because some keys contain binary data like chunk indices.
+ */
+export function getKeysOfTypesG<T extends DBEntryContentType[] | readonly DBEntryContentType[], TArrayBuffer extends ArrayBufferLike>(
+    dbKeys: Buffer<TArrayBuffer>[],
+    types: T
+): Generator<{ count: number; results: { [key in T[number]]: Buffer<TArrayBuffer>[] } }, { [key in T[number]]: Buffer<TArrayBuffer>[] }>;
+export function getKeysOfTypesG<T extends DBEntryContentType[] | readonly DBEntryContentType[]>(
+    dbOrDBKeys: LevelDB | Buffer[],
+    types: T
+):
+    | AsyncGenerator<{ count: number; results: { [key in T[number]]: Buffer<ArrayBuffer>[] } }, { [key in T[number]]: Buffer<ArrayBuffer>[] }>
+    | Generator<{ count: number; results: { [key in T[number]]: Buffer<ArrayBuffer>[] } }, { [key in T[number]]: Buffer[] }> {
+    const results = {} as { [key in T[number]]: Buffer<any>[] };
+    var count = 0;
+    types.forEach((contentType: T[number]): void => {
+        results[contentType] = [];
+    });
+    if (Array.isArray(dbOrDBKeys)) {
+        return (function* getKeysOfTypesGInner() {
+            for (const key of dbOrDBKeys) {
+                const contentType: DBEntryContentType = getContentTypeFromDBKey(key);
+                if (types.includes(contentType)) {
+                    results[contentType as T[number]].push(key);
+                    count++;
+                }
+                yield { count, results };
+            }
+            return results;
+        })();
+    }
+    return (async function* getKeysOfTypesGInner() {
+        for await (const [rawKey, _value] of dbOrDBKeys.getIterator({ keys: true, keyAsBuffer: true, values: false })) {
+            const contentType: DBEntryContentType = getContentTypeFromDBKey(rawKey);
+            if (types.includes(contentType)) {
+                results[contentType as T[number]].push(rawKey);
+                count++;
+            }
+            yield { count, results };
+        }
+        return results;
+    })();
+}
+
+/**
+ * Gets a player's name from their UUID.
+ *
+ * Only works if the player's name was stored in an add-on's dynamic properties with their ID linked to it, and it only works for a hardcoded list of add-ons,
+ * if you have your own add-on that you would like this to be able to read the player's names from, {@link https://www.8crafter.com/main/contact | contact 8Crafter},
+ * or make a pull request.
+ *
+ * @param db The LevelDB. Should match the type of the {@link LevelDB} class from the {@link https://www.npmjs.com/package/@8crafter/leveldb-zlib | @8crafter/leveldb-zlib} package. It does not have to be the one from that package, as long as the types match.
+ * @param uuid The UUID of the play to get the name of.
+ * @returns The name of the player, or `null` if the player's name cannot be found or the world has no dynamic properties.
+ *
+ * @throws {any} If there was an error reading the DynamicProperties from the DB.
+ */
+export async function getPlayerNameFromUUID(db: LevelDB, uuid: string | bigint): Promise<string | null> {
+    const dynamicProperties: NBT.NBT | null = await db
+        .get("DynamicProperties")
+        .then((data: Buffer | null): Promise<NBT.NBT> | null =>
+            data ? NBT.parse(data!).then((data: { parsed: NBT.NBT; type: NBT.NBTFormat; metadata: NBT.Metadata }): NBT.NBT => data.parsed) : null
+        );
+    if (!dynamicProperties) return null;
+    return getPlayerNameFromUUIDSync(dynamicProperties, uuid);
+}
+
+/**
+ * Gets a player's name from their UUID using the provided dynamic properties data.
+ *
+ * Only works if the player's name was stored in an add-on's dynamic properties with their ID linked to it, and it only works for a hardcoded list of add-ons,
+ * if you have your own add-on that you would like this to be able to read the player's names from, {@link https://www.8crafter.com/main/contact | contact 8Crafter},
+ * or make a pull request.
+ *
+ * @param dynamicProperties The dynamic properties data, should be the data from the `DynamicProperties` LevelDB key.
+ * @param uuid The UUID of the play to get the name of.
+ * @returns The name of the player, or `null` if the player's name cannot be found .
+ */
+export function getPlayerNameFromUUIDSync(dynamicProperties: NBT.NBT, uuid: string | bigint): string | null {
+    const UUIDString: string = uuid.toString();
+    for (const parser of playerUUIDToNameDynamicPropertyParsers) {
+        const name: string | null = parser(dynamicProperties, UUIDString);
+        if (name !== null) return name;
+    }
+    return null;
+}
+
+/**
+ * A function that can be used to get a player's name from their UUID from the dynamic properties.
+ */
+interface PlayerUUIDToNameDynamicPropertyParser {
+    /**
+     * A function that can be used to get a player's name from their UUID from the dynamic properties.
+     *
+     * @param dynamicProperties The dynamic properties data, should be the data from the `DynamicProperties` LevelDB key.
+     * @param uuid The UUID of the player to get the name of.
+     * @returns The name of the player, or `null` if the player's name cannot be found.
+     */
+    (dynamicProperties: NBT.NBT, uuid: string): string | null;
+}
+
+/**
+ * The list of functions that can be used to get a player's name from their UUID from the dynamic properties.
+ *
+ * These will be called in order until one of them returns a non-null value.
+ */
+const playerUUIDToNameDynamicPropertyParsers: PlayerUUIDToNameDynamicPropertyParser[] = [
+    function parse8CraftersServerUtilities(dynamicProperties: NBT.NBT, uuid: string): string | null {
+        const addOnUUIDs: string[] = [
+            // Internal development version
+            "53170125-3e79-4659-9bba-e49eb90b6ded",
+            // Release version
+            "53170125-3e79-4659-9bba-e49eb90b6dea",
+        ];
+        for (const addOnUUID of addOnUUIDs) {
+            const addonDynamicProperties: NBT.Compound["value"] | null =
+                dynamicProperties.value[addOnUUID]?.type === "compound" ? dynamicProperties.value[addOnUUID].value : null;
+            if (!addonDynamicProperties) continue;
+            for (const key in addonDynamicProperties) {
+                if (key !== `player:${uuid}`) continue;
+                const dynamicPropertyValue: NBT.Byte | NBT.Double | NBT.String | NBT.List<NBT.TagType.Float> = addonDynamicProperties[key]! as any;
+                if (dynamicPropertyValue.type !== "string") continue;
+                try {
+                    const data: any = JSONB.parse(dynamicPropertyValue.value);
+                    if (typeof data === "object" && data !== null && typeof data.name === "string") return data.name;
+                } catch (e) {
+                    continue;
+                }
+            }
+        }
+        return null;
+    },
+];

package/LevelUtils.d.ts

@@ -43,7 +43,7 @@ export declare const gameModes: readonly ["survival", "creative", "adventure", u
 /**
  * The content types for LevelDB entries.
  */
-export declare const DBEntryContentTypes: readonly ["Data3D", "Version", "Data2D", "Data2DLegacy", "SubChunkPrefix", "LegacyTerrain", "BlockEntity", "Entity", "PendingTicks", "LegacyBlockExtraData", "BiomeState", "FinalizedState", "ConversionData", "BorderBlocks", "HardcodedSpawners", "RandomTicks", "Checksums", "GenerationSeed", "GeneratedPreCavesAndCliffsBlending", "BlendingBiomeHeight", "MetaDataHash", "BlendingData", "ActorDigestVersion", "LegacyVersion", "AABBVolumes", "VillageDwellers", "VillageInfo", "VillagePOI", "VillagePlayers", "VillageRaid", "Player", "PlayerClient", "ActorPrefix", "ChunkLoadedRequest", "Digest", "Map", "Portals", "SchedulerWT", "StructureTemplate", "TickingArea", "FlatWorldLayers", "LegacyOverworld", "LegacyNether", "LegacyTheEnd", "MVillages", "Villages", "LevelSpawnWasFixed", "PositionTrackingDB", "PositionTrackingLastId", "Scoreboard", "Overworld", "Nether", "TheEnd", "AutonomousEntities", "BiomeData", "BiomeIdsTable", "MobEvents", "DynamicProperties", "LevelChunkMetaDataDictionary", "RealmsStoriesData", "LevelDat", "ForcedWorldCorruption", "Unknown"];
+export declare const DBEntryContentTypes: readonly ["Data3D", "Version", "Data2D", "Data2DLegacy", "SubChunkPrefix", "LegacyTerrain", "BlockEntity", "Entity", "PendingTicks", "LegacyBlockExtraData", "BiomeState", "FinalizedState", "ConversionData", "BorderBlocks", "HardcodedSpawners", "RandomTicks", "Checksums", "GenerationSeed", "GeneratedPreCavesAndCliffsBlending", "BlendingBiomeHeight", "MetaDataHash", "BlendingData", "ActorDigestVersion", "LegacyVersion", "AABBVolumes", "VillageDwellers", "VillageInfo", "VillagePOI", "VillagePlayers", "VillageRaid", "Player", "PlayerClient", "ActorPrefix", "ChunkLoadedRequest", "Digest", "Map", "Portals", "SchedulerWT", "StructureTemplate", "TickingArea", "FlatWorldLayers", "LegacyOverworld", "LegacyNether", "LegacyTheEnd", "MVillages", "Villages", "LevelSpawnWasFixed", "PositionTrackingDB", "PositionTrackingLastId", "Scoreboard", "Overworld", "Nether", "TheEnd", "AutonomousEntities", "BiomeData", "BiomeIdsTable", "MobEvents", "DynamicProperties", "LevelChunkMetaDataDictionary", "RealmsStoriesData", "LevelDat", "WorldClocks", "ForcedWorldCorruption", "Unknown"];
 /**
  * Maps content types to grouping labels.
  *
@@ -111,6 +111,7 @@ export declare const DBEntryContentTypesGrouping: {
     readonly LevelChunkMetaDataDictionary: "LevelChunkMetaDataDictionary";
     readonly RealmsStoriesData: "RealmsStoriesData";
     readonly LevelDat: "LevelDat";
+    readonly WorldClocks: "WorldClocks";
     readonly ForcedWorldCorruption: "ForcedWorldCorruption";
     readonly Unknown: "Unknown";
 };
@@ -1145,6 +1146,44 @@ export declare const entryContentTypeToFormatMap: {
          */
         readonly rawFileExtension: "dat";
     };
+    /**
+     * The content type of the `WorldClocks` LevelDB key, which serves an unknown purpose.
+     *
+     * @see {@link NBTSchemas.nbtSchemas.WorldClocks}
+     *
+     * @since 1.26.10 (maybe 1.26.0)
+     *
+     * @todo Update the linked NBT schema once it is known the structure of the items of the `clocks` list.
+     * @todo Figure out that this is used for.
+     * @todo Figure out what preview and full release this was actually added in.
+     */
+    readonly WorldClocks: {
+        /**
+         * The format type of the data.
+         */
+        readonly type: "NBT";
+        /**
+         * The default value to use when initializing a new entry.
+         *
+         * Value:
+         * ```json
+         * {
+         *     type: "compound",
+         *     name: "",
+         *     value: {
+         *         clocks: {
+         *             type: "list",
+         *             value: {
+         *                 type: "end",
+         *                 value: [],
+         *             },
+         *         },
+         *     },
+         * }
+         * ```
+         */
+        readonly defaultValue: Buffer<ArrayBufferLike>;
+    };
     /**
      * Bounding boxes for structures, including structure spawns (such as a Pillager Outpost)
      * and volumes where mobs cannot spawn through the normal biome-based means (such as

package/LevelUtils.js

@@ -428,6 +428,7 @@ export const DBEntryContentTypes = [
     "LevelChunkMetaDataDictionary",
     "RealmsStoriesData",
     "LevelDat",
+    "WorldClocks",
     // Dev Version
     "ForcedWorldCorruption",
     // Misc.
@@ -503,6 +504,7 @@ export const DBEntryContentTypesGrouping = {
     LevelChunkMetaDataDictionary: "LevelChunkMetaDataDictionary",
     RealmsStoriesData: "RealmsStoriesData",
     LevelDat: "LevelDat",
+    WorldClocks: "WorldClocks",
     // Dev Version
     ForcedWorldCorruption: "ForcedWorldCorruption",
     // Misc.
@@ -2085,6 +2087,56 @@ export const entryContentTypeToFormatMap = {
          */
         rawFileExtension: "dat",
     },
+    /**
+     * The content type of the `WorldClocks` LevelDB key, which serves an unknown purpose.
+     *
+     * @see {@link NBTSchemas.nbtSchemas.WorldClocks}
+     *
+     * @since 1.26.10 (maybe 1.26.0)
+     *
+     * @todo Update the linked NBT schema once it is known the structure of the items of the `clocks` list.
+     * @todo Figure out that this is used for.
+     * @todo Figure out what preview and full release this was actually added in.
+     */
+    WorldClocks: {
+        /**
+         * The format type of the data.
+         */
+        type: "NBT",
+        /**
+         * The default value to use when initializing a new entry.
+         *
+         * Value:
+         * ```json
+         * {
+         *     type: "compound",
+         *     name: "",
+         *     value: {
+         *         clocks: {
+         *             type: "list",
+         *             value: {
+         *                 type: "end",
+         *                 value: [],
+         *             },
+         *         },
+         *     },
+         * }
+         * ```
+         */
+        defaultValue: NBT.writeUncompressed({
+            type: "compound",
+            name: "",
+            value: {
+                clocks: {
+                    type: "list",
+                    value: {
+                        type: "end",
+                        value: [],
+                    },
+                },
+            },
+        }, "little"),
+    },
     /**
      * Bounding boxes for structures, including structure spawns (such as a Pillager Outpost)
      * and volumes where mobs cannot spawn through the normal biome-based means (such as
@@ -2604,6 +2656,7 @@ export function getKeyDisplayName(key) {
         case "VillagePlayers":
         case "VillageRaid":
         case "Villages":
+        case "WorldClocks":
         case "Unknown":
         default:
             return key.toString("binary");
@@ -2702,6 +2755,8 @@ export function getContentTypeFromDBKey(key) {
             return "DynamicProperties";
         case "LevelChunkMetaDataDictionary":
             return "LevelChunkMetaDataDictionary";
+        case "WorldClocks":
+            return "WorldClocks";
         case "SST_SALOG":
         case "SST_WORD":
         case "SST_WORD_":