isaacscript-common 84.0.1 → 84.1.0

package/dist/functions/ui.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVisibleHearts = exports.getScreenTopRightPos = exports.getScreenTopLeftPos = exports.getScreenTopCenterPos = exports.getScreenRightX = exports.getScreenCenterPos = exports.getScreenBottomY = exports.getScreenBottomRightPos = exports.getScreenBottomLeftPos = exports.getScreenBottomCenterPos = exports.getHeartsUIWidth = exports.getHeartRowLength = exports.getHUDOffsetVector = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const cachedClasses_1 = require("../core/cachedClasses");
+const constants_1 = require("../core/constants");
+const vector_1 = require("./vector");
+/**
+ * In the options menu, players have the ability to set a HUD offset (which gets written to the
+ * `HudOffset` attribute in the "options.ini" file). This function uses the current HUD offset to
+ * generate a vector that should be added to the corresponding position that you want to draw a UI
+ * element at.
+ *
+ * For example:
+ * - If the user does not have a HUD offset configured, this function will return `Vector(0, 0)`.
+ * - If the user has a HUD offset of 1.0 configured, this function will return `Vector(20, 12)`.
+ */
+function getHUDOffsetVector() {
+    // Convert e.g. 0.4 to 4.
+    const hudOffset = Math.floor(Options.HUDOffset * 10);
+    // Expected values are integers between 1 and 10.
+    if (hudOffset < 1 || hudOffset > 10) {
+        return (0, vector_1.copyVector)(constants_1.VectorZero);
+    }
+    const x = hudOffset * 2;
+    let y = hudOffset;
+    if (y >= 4) {
+        y++;
+    }
+    if (y >= 9) {
+        y++;
+    }
+    return Vector(x, y);
+}
+exports.getHUDOffsetVector = getHUDOffsetVector;
+/**
+ * Returns how many hearts are in the heart UI row. If the player has more than 6 hearts, this
+ * function will return 6.
+ */
+function getHeartRowLength(player) {
+    const maxHearts = player.GetMaxHearts();
+    const soulHearts = player.GetSoulHearts();
+    const boneHearts = player.GetBoneHearts();
+    const brokenHearts = player.GetBrokenHearts();
+    // There are no half bone hearts or half broken hearts.
+    const combinedHearts = maxHearts + soulHearts + boneHearts * 2 + brokenHearts * 2;
+    const heartRowLength = combinedHearts / 2;
+    // After 6 hearts, the hearts wrap to a second row.
+    return Math.min(heartRowLength, 6);
+}
+exports.getHeartRowLength = getHeartRowLength;
+/**
+ * Helper function to get the width of the first player's hearts on the UI. This is useful for
+ * drawing UI elements to the right of where the player's hearts are. Make sure to use this in
+ * combination with the `getHUDOffsetVector` helper function.
+ */
+function getHeartsUIWidth() {
+    const level = cachedClasses_1.game.GetLevel();
+    const curses = level.GetCurses();
+    const player = Isaac.GetPlayer();
+    const extraLives = player.GetExtraLives();
+    const effects = player.GetEffects();
+    const hasHolyMantleEffect = effects.HasCollectibleEffect(isaac_typescript_definitions_1.CollectibleType.HOLY_MANTLE);
+    let heartRowLength = getHeartRowLength(player);
+    if (hasHolyMantleEffect) {
+        heartRowLength++;
+    }
+    if (curses === isaac_typescript_definitions_1.LevelCurse.UNKNOWN) {
+        heartRowLength = 1;
+    }
+    let width = heartRowLength * constants_1.UI_HEART_WIDTH;
+    if (extraLives > 9) {
+        width += 20;
+        if (player.HasCollectible(isaac_typescript_definitions_1.CollectibleType.GUPPYS_COLLAR)) {
+            width += 6;
+        }
+    }
+    else if (extraLives > 0) {
+        width += 16;
+        if (player.HasCollectible(isaac_typescript_definitions_1.CollectibleType.GUPPYS_COLLAR)) {
+            width += 4;
+        }
+    }
+    return width;
+}
+exports.getHeartsUIWidth = getHeartsUIWidth;
+function getScreenBottomCenterPos() {
+    const bottomRightPos = getScreenBottomRightPos();
+    return Vector(bottomRightPos.X / 2, bottomRightPos.Y);
+}
+exports.getScreenBottomCenterPos = getScreenBottomCenterPos;
+function getScreenBottomLeftPos() {
+    const bottomRightPos = getScreenBottomRightPos();
+    return Vector(0, bottomRightPos.Y);
+}
+exports.getScreenBottomLeftPos = getScreenBottomLeftPos;
+function getScreenBottomRightPos() {
+    const screenWidth = Isaac.GetScreenWidth();
+    const screenHeight = Isaac.GetScreenHeight();
+    return Vector(screenWidth, screenHeight);
+}
+exports.getScreenBottomRightPos = getScreenBottomRightPos;
+function getScreenBottomY() {
+    const bottomRightPos = getScreenBottomRightPos();
+    return bottomRightPos.Y;
+}
+exports.getScreenBottomY = getScreenBottomY;
+function getScreenCenterPos() {
+    const bottomRightPos = getScreenBottomRightPos();
+    return bottomRightPos.div(2);
+}
+exports.getScreenCenterPos = getScreenCenterPos;
+function getScreenRightX() {
+    const bottomRightPos = getScreenBottomRightPos();
+    return bottomRightPos.X;
+}
+exports.getScreenRightX = getScreenRightX;
+function getScreenTopCenterPos() {
+    const bottomRightPos = getScreenBottomRightPos();
+    return Vector(bottomRightPos.X / 2, 0);
+}
+exports.getScreenTopCenterPos = getScreenTopCenterPos;
+function getScreenTopLeftPos() {
+    return (0, vector_1.copyVector)(constants_1.VectorZero);
+}
+exports.getScreenTopLeftPos = getScreenTopLeftPos;
+function getScreenTopRightPos() {
+    const bottomRightPos = getScreenBottomRightPos();
+    return Vector(bottomRightPos.X, 0);
+}
+exports.getScreenTopRightPos = getScreenTopRightPos;
+/**
+ * Get how many hearts are currently being shown on the hearts UI.
+ *
+ * This function is originally from piber20 Helper.
+ */
+function getVisibleHearts(player) {
+    const effectiveMaxHearts = player.GetEffectiveMaxHearts();
+    const soulHearts = player.GetSoulHearts();
+    const boneHearts = player.GetBoneHearts();
+    const maxHearts = Math.max(effectiveMaxHearts, boneHearts * 2);
+    let visibleHearts = Math.ceil((maxHearts + soulHearts) / 2);
+    if (visibleHearts < 1) {
+        visibleHearts = 1;
+    }
+    return visibleHearts;
+}
+exports.getVisibleHearts = getVisibleHearts;

package/dist/functions/utils.d.ts

@@ -32,6 +32,7 @@ export declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T]
  * - `eRange(1, 3)` returns `[1, 2]`.
  * - `eRange(2, 5)` returns `[2, 3, 4]`.
  * - `eRange(5, 2)` returns `[]`.
+ * - `eRange(3, 3)` returns `[]`.
  *
  * @param start The integer to start at.
  * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
@@ -58,6 +59,7 @@ export declare function getTraversalDescription(key: unknown, traversalDescripti
  * - `iRange(1, 3)` returns `[1, 2, 3]`.
  * - `iRange(2, 5)` returns `[2, 3, 4, 5]`.
  * - `iRange(5, 2)` returns `[]`.
+ * - `iRange(3, 3)` returns `[3]`.
  *
  * @param start The integer to start at.
  * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the

package/dist/functions/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/functions/utils.ts"],"names":[],"mappings":";AAIA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,GAC7B,CAAC,MAAM,CAAC,GACR;IACE,iFAAiF;CAClF,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAIxC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GACxB,CAAC,MAAM,CAAC,GACR;IACE,4EAA4E;CAC7E,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAInC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,SAAS,GAAG,EAAE,CAY3E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,oBAAoB,EAAE,MAAM,GAC3B,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,SAAS,GAAG,EAAE,CAM3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAMvC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAiBtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,IAAI,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAG"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/functions/utils.ts"],"names":[],"mappings":";AAIA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,GAC7B,CAAC,MAAM,CAAC,GACR;IACE,iFAAiF;CAClF,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAIxC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GACxB,CAAC,MAAM,CAAC,GACR;IACE,4EAA4E;CAC7E,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAInC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,SAAS,GAAG,EAAE,CAY3E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,oBAAoB,EAAE,MAAM,GAC3B,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,SAAS,GAAG,EAAE,CAO3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAMvC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAiBtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,IAAI,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAG"}

package/dist/functions/utils.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.todo = exports.repeat = exports.isRepentance = exports.isMultiplayer = exports.inRange = exports.iRange = exports.getTraversalDescription = exports.eRange = exports.assertNotNull = exports.assertDefined = void 0;
+const ReadonlySet_1 = require("../types/ReadonlySet");
+const playerIndex_1 = require("./playerIndex");
+const types_1 = require("./types");
+/**
+ * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+ * to `undefined`.
+ *
+ * This is useful to have TypeScript narrow a `T | undefined` value to `T` in a concise way.
+ */
+function assertDefined(value, ...[msg]) {
+    if (value === undefined) {
+        error(msg);
+    }
+}
+exports.assertDefined = assertDefined;
+/**
+ * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+ * to `null`.
+ *
+ * This is useful to have TypeScript narrow a `T | null` value to `T` in a concise way.
+ */
+function assertNotNull(value, ...[msg]) {
+    if (value === null) {
+        error(msg);
+    }
+}
+exports.assertNotNull = assertNotNull;
+/**
+ * Helper function to return an array of integers with the specified range, inclusive on the lower
+ * end and exclusive on the high end. (The "e" in the function name stands for exclusive.) Thus,
+ * this function works in a similar way as the built-in `range` function from Python.
+ *
+ * If the end is lower than the start, an empty array will be returned.
+ *
+ * For example:
+ *
+ * - `eRange(2)` returns `[0, 1]`.
+ * - `eRange(3)` returns `[0, 1, 2]`.
+ * - `eRange(-3)` returns `[0, -1, -2]`.
+ * - `eRange(1, 3)` returns `[1, 2]`.
+ * - `eRange(2, 5)` returns `[2, 3, 4]`.
+ * - `eRange(5, 2)` returns `[]`.
+ * - `eRange(3, 3)` returns `[]`.
+ *
+ * @param start The integer to start at.
+ * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
+ *            first argument will be the end.
+ * @param increment Optional. The increment to use. Default is 1.
+ */
+function eRange(start, end, increment = 1) {
+    if (end === undefined) {
+        return eRange(0, start, increment);
+    }
+    const array = [];
+    for (let i = start; i < end; i += increment) {
+        array.push(i);
+    }
+    return array;
+}
+exports.eRange = eRange;
+/**
+ * Helper function to log what is happening in functions that recursively move through nested data
+ * structures.
+ */
+function getTraversalDescription(key, traversalDescription) {
+    if (traversalDescription !== "") {
+        traversalDescription += " --> ";
+    }
+    traversalDescription += tostring(key);
+    return traversalDescription;
+}
+exports.getTraversalDescription = getTraversalDescription;
+/**
+ * Helper function to return an array of integers with the specified range, inclusive on both ends.
+ * (The "i" in the function name stands for inclusive.)
+ *
+ * If the end is lower than the start, an empty array will be returned.
+ *
+ * For example:
+ *
+ * - `iRange(2)` returns `[0, 1, 2]`.
+ * - `iRange(3)` returns `[0, 1, 2, 3]`.
+ * - `iRange(-3)` returns `[0, -1, -2, -3]`.
+ * - `iRange(1, 3)` returns `[1, 2, 3]`.
+ * - `iRange(2, 5)` returns `[2, 3, 4, 5]`.
+ * - `iRange(5, 2)` returns `[]`.
+ * - `iRange(3, 3)` returns `[3]`.
+ *
+ * @param start The integer to start at.
+ * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
+ *            first argument will be the end.
+ * @param increment Optional. The increment to use. Default is 1.
+ */
+function iRange(start, end, increment = 1) {
+    if (end === undefined) {
+        return iRange(0, start, increment);
+    }
+    const exclusiveEnd = end + 1;
+    return eRange(start, exclusiveEnd, increment);
+}
+exports.iRange = iRange;
+/**
+ * Helper function to check if a variable is within a certain range, inclusive on both ends.
+ *
+ * - For example, `inRange(1, 1, 3)` will return `true`.
+ * - For example, `inRange(0, 1, 3)` will return `false`.
+ *
+ * @param num The number to check.
+ * @param start The start of the range to check.
+ * @param end The end of the range to check.
+ */
+function inRange(num, start, end) {
+    return num >= start && num <= end;
+}
+exports.inRange = inRange;
+/**
+ * Helper function to detect if there is two or more players currently playing.
+ *
+ * Specifically, this function looks for unique `ControllerIndex` values across all players.
+ *
+ * This function is not safe to use in the `POST_PLAYER_INIT` callback, because the
+ * `ControllerIndex` will not be set properly. As a workaround, you can use it in the
+ * `POST_PLAYER_INIT_FIRST` callback (or some other callback like `POST_UPDATE`).
+ */
+function isMultiplayer() {
+    const players = (0, playerIndex_1.getAllPlayers)();
+    const controllerIndexes = players.map((player) => player.ControllerIndex);
+    const controllerIndexesSet = new ReadonlySet_1.ReadonlySet(controllerIndexes);
+    return controllerIndexesSet.size > 1;
+}
+exports.isMultiplayer = isMultiplayer;
+/**
+ * Helper function to check if the player is using Afterbirth+ or Repentance.
+ *
+ * This function should always be used over the `REPENTANCE` constant, since the latter is not safe.
+ *
+ * Specifically, this function checks for the `Sprite.GetAnimation` method:
+ * https://bindingofisaacrebirth.fandom.com/wiki/V1.06.J818#Lua_Changes
+ */
+function isRepentance() {
+    const metatable = getmetatable(Sprite);
+    assertDefined(metatable, "Failed to get the metatable of the Sprite global table.");
+    const classTable = metatable.get("__class");
+    assertDefined(classTable, 'Failed to get the "__class" key of the Sprite metatable.');
+    const getAnimation = classTable.get("GetAnimation");
+    return (0, types_1.isFunction)(getAnimation);
+}
+exports.isRepentance = isRepentance;
+/**
+ * Helper function to repeat code N times. This is faster to type and cleaner than using a for loop.
+ *
+ * For example:
+ *
+ * ```ts
+ * const player = Isaac.GetPlayer();
+ * repeat(10, () => {
+ *   player.AddCollectible(CollectibleType.STEVEN);
+ * });
+ * ```
+ *
+ * The repeated function is passed the index of the iteration, if needed:
+ *
+ * ```ts
+ * repeat(3, (i) => {
+ *   print(i); // Prints "0", "1", "2"
+ * });
+ * ```
+ */
+function repeat(num, func) {
+    for (let i = 0; i < num; i++) {
+        func(i);
+    }
+}
+exports.repeat = repeat;
+/**
+ * Helper function to signify that the enclosing code block is not yet complete. Using this function
+ * is similar to writing a "TODO" comment, but it has the benefit of preventing ESLint errors due to
+ * unused variables or early returns.
+ *
+ * When you see this function, it simply means that the programmer intends to add in more code to
+ * this spot later.
+ *
+ * This function is variadic, meaning that you can pass as many arguments as you want. (This is
+ * useful as a means to prevent unused variables.)
+ *
+ * This function does not actually do anything. (It is an "empty" function.)
+ *
+ * @allowEmptyVariadic
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-empty-function
+function todo(...args) { }
+exports.todo = todo;

package/dist/functions/utils.lua

@@ -46,6 +46,7 @@ end
 -- - `eRange(1, 3)` returns `[1, 2]`.
 -- - `eRange(2, 5)` returns `[2, 3, 4]`.
 -- - `eRange(5, 2)` returns `[]`.
+-- - `eRange(3, 3)` returns `[]`.
 -- 
 -- @param start The integer to start at.
 -- @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
@@ -90,6 +91,7 @@ end
 -- - `iRange(1, 3)` returns `[1, 2, 3]`.
 -- - `iRange(2, 5)` returns `[2, 3, 4, 5]`.
 -- - `iRange(5, 2)` returns `[]`.
+-- - `iRange(3, 3)` returns `[3]`.
 -- 
 -- @param start The integer to start at.
 -- @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
@@ -102,7 +104,8 @@ function ____exports.iRange(self, start, ____end, increment)
     if ____end == nil then
         return ____exports.iRange(nil, 0, start, increment)
     end
-    return ____exports.eRange(nil, start, ____end + 1, increment)
+    local exclusiveEnd = ____end + 1
+    return ____exports.eRange(nil, start, exclusiveEnd, increment)
 end
 --- Helper function to check if a variable is within a certain range, inclusive on both ends.
 -- 

package/dist/functions/vector.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vectorToString = exports.vectorToDirection = exports.vectorEquals = exports.serializeVector = exports.isVector = exports.isSerializedVector = exports.getRandomVector = exports.getClosestVectorTo = exports.doesVectorHaveLength = exports.deserializeVector = exports.copyVector = void 0;
+const SerializationBrand_1 = require("../enums/private/SerializationBrand");
+const direction_1 = require("./direction");
+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 = "Vector";
+const KEYS = ["X", "Y"];
+/** Helper function to copy a `Vector` Isaac API class. */
+function copyVector(vector) {
+    if (!isVector(vector)) {
+        error(`Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`);
+    }
+    return Vector(vector.X, vector.Y);
+}
+exports.copyVector = copyVector;
+/**
+ * Helper function to convert a `SerializedVector` object to a normal `RNG` object. (This is used by
+ * the save data manager when reading data from the "save#.dat" file.)
+ */
+function deserializeVector(vector) {
+    if (!(0, types_1.isTable)(vector)) {
+        error(`Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`);
+    }
+    const [x, y] = (0, table_1.getNumbersFromTable)(vector, OBJECT_NAME, ...KEYS);
+    (0, utils_1.assertDefined)(x, `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: X`);
+    (0, utils_1.assertDefined)(y, `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Y`);
+    return Vector(x, y);
+}
+exports.deserializeVector = deserializeVector;
+/**
+ * Helper function to measure a vector to see if it has a non-zero length using a threshold to
+ * ignore extremely small values.
+ *
+ * Use this function instead of explicitly checking if the length is 0 because vectors in the game
+ * are unlikely to ever be exactly set to 0. Instead, they will always have some miniscule length.
+ *
+ * @param vector The vector to measure.
+ * @param threshold Optional. The threshold from 0 to consider to be a non-zero vector. Default is
+ *                  0.01.
+ */
+function doesVectorHaveLength(vector, threshold = 0.01) {
+    return vector.Length() >= threshold;
+}
+exports.doesVectorHaveLength = doesVectorHaveLength;
+/**
+ * Given an array of vectors, this helper function returns the closest one to a provided reference
+ * vector.
+ *
+ * @param referenceVector The vector to compare against.
+ * @param vectors The array of vectors to look through.
+ */
+function getClosestVectorTo(referenceVector, vectors) {
+    let closestVector;
+    let closestDistance = math.huge;
+    for (const vector of vectors) {
+        const distance = referenceVector.Distance(vector);
+        if (distance < closestDistance) {
+            closestVector = vector;
+            closestDistance = distance;
+        }
+    }
+    return closestVector;
+}
+exports.getClosestVectorTo = getClosestVectorTo;
+/**
+ * Helper function to get a random vector between (-1, -1) and (1, 1).
+ *
+ * To get random vectors with a bigger length, multiply this with a number.
+ *
+ * Use this over the `RandomVector` function when you need the vector to be seeded.
+ *
+ * If you want to generate an unseeded vector, 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.
+ */
+function getRandomVector(seedOrRNG) {
+    const rng = (0, rng_1.isRNG)(seedOrRNG) ? seedOrRNG : (0, rng_1.newRNG)(seedOrRNG);
+    const x = (0, random_1.getRandomFloat)(-1, 1, rng);
+    const y = (0, random_1.getRandomFloat)(-1, 1, rng);
+    return Vector(x, y);
+}
+exports.getRandomVector = getRandomVector;
+/**
+ * Used to determine is the given table is a serialized `Vector` object created by the `deepCopy`
+ * function.
+ */
+function isSerializedVector(object) {
+    if (!(0, types_1.isTable)(object)) {
+        return false;
+    }
+    return (0, table_1.tableHasKeys)(object, ...KEYS) && object.has(SerializationBrand_1.SerializationBrand.VECTOR);
+}
+exports.isSerializedVector = isSerializedVector;
+/** Helper function to check if something is an instantiated `Vector` object. */
+function isVector(object) {
+    return (0, isaacAPIClass_1.isIsaacAPIClassOfType)(object, OBJECT_NAME);
+}
+exports.isVector = isVector;
+/**
+ * Helper function to convert a `Vector` object to a `SerializedVector` object. (This is used by the
+ * save data manager when writing data from the "save#.dat" file.)
+ */
+function serializeVector(vector) {
+    if (!isVector(vector)) {
+        error(`Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`);
+    }
+    const vectorTable = new LuaMap();
+    (0, table_1.copyUserdataValuesToTable)(vector, KEYS, vectorTable);
+    vectorTable.set(SerializationBrand_1.SerializationBrand.VECTOR, "");
+    return vectorTable;
+}
+exports.serializeVector = serializeVector;
+/**
+ * Helper function to compare two vectors for equality.
+ *
+ * This function is useful because vectors are not directly comparable. In other words, `Vector(1.2)
+ * === Vector(1.2)` will be equal to false.
+ */
+function vectorEquals(vector1, vector2) {
+    return (0, isaacAPIClass_1.isaacAPIClassEquals)(vector1, vector2, KEYS);
+}
+exports.vectorEquals = vectorEquals;
+/** Helper function for finding out which way a vector is pointing. */
+function vectorToDirection(vector) {
+    const angleDegrees = vector.GetAngleDegrees();
+    return (0, direction_1.angleToDirection)(angleDegrees);
+}
+exports.vectorToDirection = vectorToDirection;
+/**
+ * Helper function to convert a vector to a string.
+ *
+ * @param vector The vector to convert.
+ * @param round Optional. If true, will round the vector values to the nearest integer. Default is
+ *              false.
+ */
+function vectorToString(vector, round = false) {
+    const x = round ? Math.round(vector.X) : vector.X;
+    const y = round ? Math.round(vector.Y) : vector.Y;
+    return `(${x}, ${y})`;
+}
+exports.vectorToString = vectorToString;

package/dist/functions/versusScreen.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCharacterPortraitPNGFilePath = exports.getCharacterNamePNGFilePath = exports.getBossPortraitPNGFilePath = exports.getBossNamePNGFilePath = void 0;
+const bossNamePNGFileNames_1 = require("../objects/bossNamePNGFileNames");
+const bossPortraitPNGFileNames_1 = require("../objects/bossPortraitPNGFileNames");
+const playerNamePNGFileNames_1 = require("../objects/playerNamePNGFileNames");
+const playerPortraitPNGFileNames_1 = require("../objects/playerPortraitPNGFileNames");
+/** Most of the PNG files related to the versus screen are located in this directory. */
+const PNG_PATH_PREFIX = "gfx/ui/boss";
+/**
+ * Player portraits are not located in the same directory as everything else, since they are re-used
+ * from the animation where the player travels to a new stage.
+ */
+const PLAYER_PORTRAIT_PNG_PATH_PREFIX = "gfx/ui/stage";
+/**
+ * Helper function to get the path to the name file that corresponds to the graphic shown on the
+ * versus screen for the particular boss.
+ *
+ * For example, the file path for `BossID.MONSTRO` is "gfx/ui/boss/bossname_20.0_monstro.png".
+ */
+function getBossNamePNGFilePath(bossID) {
+    const fileName = bossNamePNGFileNames_1.BOSS_NAME_PNG_FILE_NAMES[bossID];
+    return `${PNG_PATH_PREFIX}/${fileName}`;
+}
+exports.getBossNamePNGFilePath = getBossNamePNGFilePath;
+/**
+ * Helper function to get the path to the portrait file that corresponds to the graphic shown on the
+ * versus screen for the particular boss.
+ *
+ * For example, the file path for `BossID.MONSTRO` is "gfx/ui/boss/portrait_20.0_monstro.png".
+ */
+function getBossPortraitPNGFilePath(bossID) {
+    const fileName = bossPortraitPNGFileNames_1.BOSS_PORTRAIT_PNG_FILE_NAMES[bossID];
+    return `${PNG_PATH_PREFIX}/${fileName}`;
+}
+exports.getBossPortraitPNGFilePath = getBossPortraitPNGFilePath;
+/**
+ * Helper function to get the path to the name file that corresponds to the graphic shown on the
+ * versus screen for the particular character.
+ *
+ * For example, the file path for `PlayerType.ISAAC` is "gfx/ui/boss/playername_01_isaac.png".
+ */
+function getCharacterNamePNGFilePath(character) {
+    const fileName = playerNamePNGFileNames_1.PLAYER_NAME_PNG_FILE_NAMES[character];
+    return `${PNG_PATH_PREFIX}/${fileName}`;
+}
+exports.getCharacterNamePNGFilePath = getCharacterNamePNGFilePath;
+/**
+ * Helper function to get the path to the portrait file that corresponds to the graphic shown on the
+ * versus screen for the particular character.
+ *
+ * For example, the file path for `PlayerType.ISAAC` is "gfx/ui/boss/playerportrait_isaac.png".
+ */
+function getCharacterPortraitPNGFilePath(character) {
+    const fileName = playerPortraitPNGFileNames_1.PLAYER_PORTRAIT_PNG_FILE_NAMES[character];
+    return `${PLAYER_PORTRAIT_PNG_PATH_PREFIX}/${fileName}`;
+}
+exports.getCharacterPortraitPNGFilePath = getCharacterPortraitPNGFilePath;

package/dist/functions/weighted.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRandomIndexFromWeightedArray = exports.getRandomFromWeightedArray = void 0;
+const array_1 = require("./array");
+const random_1 = require("./random");
+const utils_1 = require("./utils");
+/**
+ * Get a random value from a `WeightedArray`. (A `WeightedArray` is an array of tuples, where the
+ * first element in the tuple is a value, and the second element in the tuple is a float
+ * corresponding to the value's weight.)
+ *
+ * If you want to get an unseeded element, you must explicitly pass `undefined` to the `seedOrRNG`
+ * parameter.
+ *
+ * @param weightedArray The array to pick from.
+ * @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.
+ */
+function getRandomFromWeightedArray(weightedArray, seedOrRNG) {
+    const randomIndex = getRandomIndexFromWeightedArray(weightedArray, seedOrRNG);
+    const randomElement = weightedArray[randomIndex];
+    (0, utils_1.assertDefined)(randomElement, `Failed to get an element from a weighted array using a random index of: ${randomIndex}`);
+    return randomElement[0];
+}
+exports.getRandomFromWeightedArray = getRandomFromWeightedArray;
+/**
+ * Get a random index from a `WeightedArray`. (A `WeightedArray` is an array of tuples, where the
+ * first element in the tuple is a value, and the second element in the tuple is a float
+ * corresponding to the value's weight.)
+ *
+ * If you want to get an unseeded index, you must explicitly pass `undefined` to the `seedOrRNG`
+ * parameter.
+ *
+ * @param weightedArray The array to pick from.
+ * @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.
+ */
+function getRandomIndexFromWeightedArray(weightedArray, seedOrRNG) {
+    if (weightedArray.length === 0) {
+        error("Failed to get a random index from a weighted array since the provided array was empty.");
+    }
+    const weights = weightedArray.map((tuple) => tuple[1]);
+    const totalWeight = (0, array_1.sumArray)(weights);
+    const randomWeight = (0, random_1.getRandomFloat)(0, totalWeight, seedOrRNG);
+    let weightAccumulator = 0;
+    for (const [i, tuple] of weightedArray.entries()) {
+        const [_element, weight] = tuple;
+        weightAccumulator += weight;
+        if (weightAccumulator >= randomWeight) {
+            return i;
+        }
+    }
+    error("Failed to get a random index from a weighted array.");
+}
+exports.getRandomIndexFromWeightedArray = getRandomIndexFromWeightedArray;