isaacscript-common 84.0.0 → 84.1.0

package/dist/functions/jsonRoom.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRandomJSONRoom = exports.getRandomJSONEntity = exports.getJSONRoomsOfSubType = exports.getJSONRoomOfVariant = exports.getJSONRoomDoorSlotFlags = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const array_1 = require("./array");
+const doors_1 = require("./doors");
+const enums_1 = require("./enums");
+const flag_1 = require("./flag");
+const log_1 = require("./log");
+const random_1 = require("./random");
+const types_1 = require("./types");
+const utils_1 = require("./utils");
+/**
+ * Helper function to calculate what the resulting `BitFlags<DoorSlotFlag>` value would be for a
+ * given JSON room.
+ *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ */
+function getJSONRoomDoorSlotFlags(jsonRoom) {
+    const roomShapeString = jsonRoom.$.shape;
+    const roomShape = (0, types_1.parseIntSafe)(roomShapeString);
+    (0, utils_1.assertDefined)(roomShape, `Failed to parse the "shape" field of a JSON room: ${roomShapeString}`);
+    if (!(0, enums_1.isEnumValue)(roomShape, isaac_typescript_definitions_1.RoomShape)) {
+        error(`Failed to parse the "shape" field of a JSON room since it was an invalid number: ${roomShape}`);
+    }
+    let doorSlotFlags = isaac_typescript_definitions_1.DoorSlotFlagZero;
+    for (const door of jsonRoom.door) {
+        const existsString = door.$.exists;
+        if (existsString !== "True" && existsString !== "False") {
+            error(`Failed to parse the "exists" field of a JSON room door: ${existsString}`);
+        }
+        if (existsString === "False") {
+            continue;
+        }
+        const xString = door.$.x;
+        const x = (0, types_1.parseIntSafe)(xString);
+        (0, utils_1.assertDefined)(x, `Failed to parse the "x" field of a JSON room door: ${xString}`);
+        const yString = door.$.y;
+        const y = (0, types_1.parseIntSafe)(yString);
+        (0, utils_1.assertDefined)(y, `Failed to parse the "y" field of a JSON room door: ${yString}`);
+        const doorSlot = (0, doors_1.getRoomShapeDoorSlot)(roomShape, x, y);
+        (0, utils_1.assertDefined)(doorSlot, `Failed to retrieve the door slot for a JSON room door at coordinates: [${x}, ${y}]`);
+        const doorSlotFlag = (0, doors_1.doorSlotToDoorSlotFlag)(doorSlot);
+        doorSlotFlags = (0, flag_1.addFlag)(doorSlotFlags, doorSlotFlag);
+    }
+    return doorSlotFlags;
+}
+exports.getJSONRoomDoorSlotFlags = getJSONRoomDoorSlotFlags;
+/**
+ * Helper function to find a specific room from an array of JSON rooms.
+ *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
+ * @param jsonRooms The array of rooms to search through.
+ * @param variant The room variant to select. (The room variant can be thought of as the ID of the
+ *                room.)
+ */
+function getJSONRoomOfVariant(jsonRooms, variant) {
+    const jsonRoomsOfVariant = jsonRooms.filter((jsonRoom) => {
+        const roomVariantString = jsonRoom.$.variant;
+        const roomVariant = (0, types_1.parseIntSafe)(roomVariantString);
+        if (roomVariant === undefined) {
+            error(`Failed to convert a JSON room variant to an integer: ${roomVariantString}`);
+        }
+        return roomVariant === variant;
+    });
+    // The room variant acts as an ID for the room. We assume that there should only be a single room
+    // per variant.
+    if (jsonRoomsOfVariant.length === 0) {
+        return undefined;
+    }
+    if (jsonRoomsOfVariant.length === 1) {
+        return jsonRoomsOfVariant[0];
+    }
+    error(`Found ${jsonRoomsOfVariant.length} JSON rooms with a variant of ${variant}, when there should only be 1.`);
+}
+exports.getJSONRoomOfVariant = getJSONRoomOfVariant;
+/**
+ * Helper function to find all of the JSON rooms that match the sub-type provided.
+ *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
+ * @param jsonRooms The array of rooms to search through.
+ * @param subType The sub-type to match.
+ */
+function getJSONRoomsOfSubType(jsonRooms, subType) {
+    return jsonRooms.filter((jsonRoom) => {
+        const roomSubTypeString = jsonRoom.$.subtype;
+        const roomSubType = (0, types_1.parseIntSafe)(roomSubTypeString);
+        if (roomSubType === undefined) {
+            error(`Failed to convert a JSON room sub-type to an integer: ${roomSubTypeString}`);
+        }
+        return roomSubType === subType;
+    });
+}
+exports.getJSONRoomsOfSubType = getJSONRoomsOfSubType;
+/**
+ * Helper function to get a random JSON entity from an array of JSON entities.
+ *
+ * (A JSON entity is an entity inside of a JSON room. A JSON room is an XML file converted to JSON
+ * so that it can be directly imported into your mod.)
+ *
+ * Note that this function does not simply choose a random element in the provided array; it will
+ * properly account for each room weight using the algorithm from:
+ * https://stackoverflow.com/questions/1761626/weighted-random-numbers
+ *
+ * If you want an unseeded entity, you must explicitly pass `undefined` to the `seedOrRNG`
+ * parameter.
+ *
+ * @param jsonEntities The array of entities to randomly choose between.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
+ * @param verbose Optional. If specified, will write entries to the "log.txt" file that describe
+ *                what the function is doing. Default is false.
+ */
+function getRandomJSONEntity(jsonEntities, seedOrRNG, verbose = false) {
+    const totalWeight = getTotalWeightOfJSONObject(jsonEntities);
+    if (verbose) {
+        (0, log_1.log)(`Total weight of the JSON entities provided: ${totalWeight}`);
+    }
+    const chosenWeight = (0, random_1.getRandomFloat)(0, totalWeight, seedOrRNG);
+    if (verbose) {
+        (0, log_1.log)(`Randomly chose weight for JSON entity: ${chosenWeight}`);
+    }
+    const randomJSONEntity = getJSONObjectWithChosenWeight(jsonEntities, chosenWeight);
+    (0, utils_1.assertDefined)(randomJSONEntity, `Failed to get a JSON entity with chosen weight: ${chosenWeight}`);
+    return randomJSONEntity;
+}
+exports.getRandomJSONEntity = getRandomJSONEntity;
+/**
+ * Helper function to get a random JSON room from an array of JSON rooms.
+ *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
+ * Note that this function does not simply choose a random element in the provided array; it will
+ * properly account for each room weight using the algorithm from:
+ * https://stackoverflow.com/questions/1761626/weighted-random-numbers
+ *
+ * If you want an unseeded room, you must explicitly pass `undefined` to the `seedOrRNG` parameter.
+ *
+ * @param jsonRooms The array of rooms to randomly choose between.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
+ * @param verbose Optional. If specified, will write entries to the "log.txt" file that describe
+ *                what the function is doing. Default is false.
+ */
+function getRandomJSONRoom(jsonRooms, seedOrRNG, verbose = false) {
+    const totalWeight = getTotalWeightOfJSONObject(jsonRooms);
+    if (verbose) {
+        (0, log_1.log)(`Total weight of the JSON rooms provided: ${totalWeight}`);
+    }
+    const chosenWeight = (0, random_1.getRandomFloat)(0, totalWeight, seedOrRNG);
+    if (verbose) {
+        (0, log_1.log)(`Randomly chose weight for JSON room: ${chosenWeight}`);
+    }
+    const randomJSONRoom = getJSONObjectWithChosenWeight(jsonRooms, chosenWeight);
+    (0, utils_1.assertDefined)(randomJSONRoom, `Failed to get a JSON room with chosen weight: ${chosenWeight}`);
+    return randomJSONRoom;
+}
+exports.getRandomJSONRoom = getRandomJSONRoom;
+function getTotalWeightOfJSONObject(jsonOjectArray) {
+    const weights = jsonOjectArray.map((jsonObject) => {
+        const weightString = jsonObject.$.weight;
+        const weight = tonumber(weightString);
+        (0, utils_1.assertDefined)(weight, `Failed to parse the weight of a JSON object: ${weightString}.`);
+        return weight;
+    });
+    return (0, array_1.sumArray)(weights);
+}
+function getJSONObjectWithChosenWeight(jsonOjectArray, chosenWeight) {
+    let weightAccumulator = 0;
+    for (const jsonObject of jsonOjectArray) {
+        const weightString = jsonObject.$.weight;
+        const weight = tonumber(weightString);
+        (0, utils_1.assertDefined)(weight, `Failed to parse the weight of a JSON object: ${weightString}`);
+        weightAccumulator += weight;
+        if (weightAccumulator >= chosenWeight) {
+            return jsonObject;
+        }
+    }
+    return undefined;
+}

package/dist/functions/kColor.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeKColor = exports.kColorEquals = exports.isSerializedKColor = exports.isKColor = exports.getRandomKColor = exports.deserializeKColor = exports.copyKColor = void 0;
+const SerializationBrand_1 = require("../enums/private/SerializationBrand");
+const isaacAPIClass_1 = require("./isaacAPIClass");
+const random_1 = require("./random");
+const rng_1 = require("./rng");
+const table_1 = require("./table");
+const types_1 = require("./types");
+const utils_1 = require("./utils");
+const OBJECT_NAME = "KColor";
+const KEYS = ["Red", "Green", "Blue", "Alpha"];
+/** Helper function to copy a `KColor` Isaac API class. */
+function copyKColor(kColor) {
+    if (!isKColor(kColor)) {
+        error(`Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`);
+    }
+    return KColor(kColor.Red, kColor.Green, kColor.Blue, kColor.Alpha);
+}
+exports.copyKColor = copyKColor;
+/**
+ * Helper function to convert a `SerializedKColor` object to a normal `KColor` object. (This is used
+ * by the save data manager when reading data from the "save#.dat" file.)
+ */
+function deserializeKColor(kColor) {
+    if (!(0, types_1.isTable)(kColor)) {
+        error(`Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`);
+    }
+    const [r, g, b, a] = (0, table_1.getNumbersFromTable)(kColor, OBJECT_NAME, ...KEYS);
+    (0, utils_1.assertDefined)(r, `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Red`);
+    (0, utils_1.assertDefined)(g, `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Green`);
+    (0, utils_1.assertDefined)(b, `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Blue`);
+    (0, utils_1.assertDefined)(a, `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Alpha`);
+    return KColor(r, g, b, a);
+}
+exports.deserializeKColor = deserializeKColor;
+/**
+ * Helper function to get a random `KColor` object (for use in fonts).
+ *
+ * If you want to generate an unseeded object, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
+ * @param alpha Optional. The alpha value to use. Default is 1.
+ */
+function getRandomKColor(seedOrRNG, alpha = 1) {
+    const rng = (0, rng_1.isRNG)(seedOrRNG) ? seedOrRNG : (0, rng_1.newRNG)(seedOrRNG);
+    const r = (0, random_1.getRandom)(rng);
+    const g = (0, random_1.getRandom)(rng);
+    const b = (0, random_1.getRandom)(rng);
+    return KColor(r, g, b, alpha);
+}
+exports.getRandomKColor = getRandomKColor;
+/** Helper function to check if something is an instantiated `KColor` object. */
+function isKColor(object) {
+    return (0, isaacAPIClass_1.isIsaacAPIClassOfType)(object, OBJECT_NAME);
+}
+exports.isKColor = isKColor;
+/**
+ * Used to determine is the given table is a serialized `KColor` object created by the `deepCopy`
+ * function.
+ */
+function isSerializedKColor(object) {
+    if (!(0, types_1.isTable)(object)) {
+        return false;
+    }
+    return ((0, table_1.tableHasKeys)(object, ...KEYS) && object.has(SerializationBrand_1.SerializationBrand.K_COLOR));
+}
+exports.isSerializedKColor = isSerializedKColor;
+function kColorEquals(kColor1, kColor2) {
+    return (0, isaacAPIClass_1.isaacAPIClassEquals)(kColor1, kColor2, KEYS);
+}
+exports.kColorEquals = kColorEquals;
+/**
+ * Helper function to convert a `KColor` object to a `SerializedKColor` object. (This is used by the
+ * save data manager when writing data from the "save#.dat" file.)
+ */
+function serializeKColor(kColor) {
+    if (!isKColor(kColor)) {
+        error(`Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`);
+    }
+    const kColorTable = new LuaMap();
+    (0, table_1.copyUserdataValuesToTable)(kColor, KEYS, kColorTable);
+    kColorTable.set(SerializationBrand_1.SerializationBrand.K_COLOR, "");
+    return kColorTable;
+}
+exports.serializeKColor = serializeKColor;

package/dist/functions/language.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLanguageName = void 0;
+const languageNames_1 = require("../objects/languageNames");
+/**
+ * Helper function to convert the language abbreviation from `Options.Language` to the "full"
+ * language name.
+ *
+ * For example, if the current language is set to Korean, `Options.Language` will be set to "kr",
+ * and this function will return "Korean".
+ */
+function getLanguageName() {
+    const languageAbbreviation = Options.Language;
+    return languageNames_1.LANGUAGE_NAMES[languageAbbreviation];
+}
+exports.getLanguageName = getLanguageName;

package/dist/functions/level.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levelHasRoomType = exports.levelHasBossID = exports.getLevelBossIDs = exports.fillLevelWithRedRooms = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const cachedEnumValues_1 = require("../arrays/cachedEnumValues");
+const cachedClasses_1 = require("../core/cachedClasses");
+const array_1 = require("./array");
+const levelGrid_1 = require("./levelGrid");
+const rooms_1 = require("./rooms");
+/** Helper function to fill every possible level grid square with a red room. */
+function fillLevelWithRedRooms() {
+    const level = cachedClasses_1.game.GetLevel();
+    let numRoomsInGrid;
+    do {
+        const roomsInGrid = (0, rooms_1.getRoomsInsideGrid)();
+        numRoomsInGrid = roomsInGrid.length;
+        for (const roomDescriptor of roomsInGrid) {
+            for (const doorSlot of cachedEnumValues_1.DOOR_SLOT_VALUES) {
+                if ((0, levelGrid_1.isDoorSlotValidAtGridIndexForRedRoom)(doorSlot, roomDescriptor.GridIndex)) {
+                    level.MakeRedRoomDoor(roomDescriptor.GridIndex, doorSlot);
+                }
+            }
+        }
+    } while (numRoomsInGrid !== (0, rooms_1.getNumRooms)());
+}
+exports.fillLevelWithRedRooms = fillLevelWithRedRooms;
+/**
+ * Helper function to get the boss IDs of all of the Boss Rooms on this floor. (This is equivalent
+ * to the sub-type of the room data.)
+ *
+ * Note that this will only look at Boss Rooms inside of the grid, so e.g. Reverse Emperor card
+ * rooms will not count.
+ */
+function getLevelBossIDs() {
+    const roomsInsideGrid = (0, rooms_1.getRoomsInsideGrid)();
+    return (0, array_1.filterMap)(roomsInsideGrid, (roomDescriptor) => roomDescriptor.Data !== undefined &&
+        roomDescriptor.Data.Type === isaac_typescript_definitions_1.RoomType.BOSS &&
+        roomDescriptor.Data.StageID === isaac_typescript_definitions_1.StageID.SPECIAL_ROOMS
+        ? roomDescriptor.Data.Subtype
+        : undefined);
+}
+exports.getLevelBossIDs = getLevelBossIDs;
+/**
+ * Helper function to check if the current floor has a Boss Room that matches the boss ID provided.
+ *
+ * This function is variadic, meaning that you can pass as many boss IDs as you want to check for.
+ * It will return true if one or more of the boss IDs are matched.
+ */
+function levelHasBossID(...bossIDs) {
+    const levelBossIDs = getLevelBossIDs();
+    const levelBossIDsSet = new Set(levelBossIDs);
+    return bossIDs.some((bossID) => levelBossIDsSet.has(bossID));
+}
+exports.levelHasBossID = levelHasBossID;
+/**
+ * Helper function to check to see if the current floor has one or more of a specific room type in
+ * it.
+ *
+ * This function is variadic, meaning that you can pass as many room types as you want to check for.
+ * This function will return true if any of the room types are found.
+ */
+function levelHasRoomType(...roomTypes) {
+    const roomDescriptors = (0, levelGrid_1.getRoomDescriptorsForType)(...roomTypes);
+    return roomDescriptors.length > 0;
+}
+exports.levelHasRoomType = levelHasRoomType;