isaacscript-common 84.0.1 → 84.1.1

package/dist/functions/playerIndex.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFoundSoul = exports.isChildPlayer = exports.getSubPlayerParent = exports.getPlayers = exports.getPlayerIndexVanilla = exports.getPlayerIndex = exports.getPlayerFromIndex = exports.getOtherPlayers = exports.getAllPlayers = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const cachedClasses_1 = require("../core/cachedClasses");
+const ReadonlySet_1 = require("../types/ReadonlySet");
+const DEFAULT_COLLECTIBLE_TYPE = isaac_typescript_definitions_1.CollectibleType.SAD_ONION;
+const EXCLUDED_CHARACTERS = new ReadonlySet_1.ReadonlySet([
+    isaac_typescript_definitions_1.PlayerType.ESAU,
+    isaac_typescript_definitions_1.PlayerType.SOUL_B, // 40
+]);
+/**
+ * Helper function to get every player with no restrictions, by using `Game.GetNumPlayers` and
+ * `Isaac.GetPlayer`.
+ *
+ * This function is almost never what you want to use. For most purposes, use the `getPlayers`
+ * helper function instead to get a filtered list of players.
+ */
+function getAllPlayers() {
+    const numPlayers = cachedClasses_1.game.GetNumPlayers();
+    const players = [];
+    for (let i = 0; i < numPlayers; i++) {
+        const player = Isaac.GetPlayer(i);
+        players.push(player);
+    }
+    return players;
+}
+exports.getAllPlayers = getAllPlayers;
+/**
+ * Helper function to get all of the other players in the room besides the one provided. (This
+ * includes "child" players.)
+ */
+function getOtherPlayers(player) {
+    const playerPtrHash = GetPtrHash(player);
+    const players = getAllPlayers();
+    return players.filter((otherPlayer) => GetPtrHash(otherPlayer) !== playerPtrHash);
+}
+exports.getOtherPlayers = getOtherPlayers;
+/**
+ * Helper function to get the corresponding `EntityPlayer` object that corresponds to a
+ * `PlayerIndex`.
+ */
+function getPlayerFromIndex(playerIndex) {
+    const players = getAllPlayers();
+    return players.find((player) => getPlayerIndex(player) === playerIndex);
+}
+exports.getPlayerFromIndex = getPlayerFromIndex;
+/**
+ * Mods often have to track variables relating to the player. In naive mods, information will only
+ * be stored about the first player. However, in order to be robust, mods must handle up to 4
+ * players playing at the same time. This means that information must be stored on a map data
+ * structure. Finding a good index for these types of map data structures is difficult:
+ *
+ * - We cannot use the index from `Isaac.GetPlayer(i)` since this fails in the case where there are
+ *   two players and the first player leaves the run.
+ * - We cannot use `EntityPlayer.ControllerIndex` as an index because it fails in the case of Jacob
+ *   & Esau or Tainted Forgotten. It also fails in the case of a player changing their controls
+ *   mid-run.
+ * - We cannot use `EntityPlayer.GetData().index` because it does not persist across saving and
+ *   continuing.
+ * - We cannot use `GetPtrHash()` as an index because it does not persist across exiting and
+ *   relaunching the game.
+ * - We cannot use `EntityPlayer.InitSeed` because it is not consistent with additional players
+ *   beyond the first.
+ *
+ * Instead, we use the `EntityPlayer.GetCollectibleRNG` method with an arbitrary value of Sad Onion
+ * (1). This works even if the player does not have any Sad Onions.
+ *
+ * Note that by default, this returns the same index for both The Forgotten and The Soul. (Even
+ * though they are technically different characters, they share the same inventory and `InitSeed`.)
+ * If this is not desired, pass true for the `differentiateForgottenAndSoul` argument, and the RNG
+ * of Spoon Bender (3) will be used for The Soul.
+ *
+ * Also note that this index does not work in the `POST_PLAYER_INIT` function for players 2 through
+ * 4. With that said, in almost all cases, you should be lazy-initializing your data structures in
+ * other callbacks, so this should not be an issue.
+ */
+function getPlayerIndex(player, differentiateForgottenAndSoul = false) {
+    // Sub-players use separate RNG values for some reason, so we need to always use the main player:
+    // https://github.com/Meowlala/RepentanceAPIIssueTracker/issues/443
+    // We can safely ignore the player's character because regardless of whether the main player ends
+    // up being The Forgotten or The Soul, the collectible RNG values will be the same. The
+    // `EntityPlayer.IsSubPlayer` method can return true for Dead Tainted Lazarus during the
+    // `POST_PLAYER_INIT` callback, but since we fall back to the player in the case of
+    // "getSubPlayerParent" returning undefined, we do not need to explicitly check for this case.
+    let playerToUse = player;
+    const isSubPlayer = player.IsSubPlayer();
+    if (isSubPlayer) {
+        const subPlayer = player;
+        // The "getSubPlayerParent" function will return undefined in the situation where we are on Dead
+        // Tainted Lazarus in the `POST_PLAYER_INIT` callback.
+        const playerParent = getSubPlayerParent(subPlayer);
+        if (playerParent !== undefined) {
+            playerToUse = playerParent;
+        }
+    }
+    const collectibleType = getPlayerIndexCollectibleType(player, differentiateForgottenAndSoul);
+    const collectibleRNG = playerToUse.GetCollectibleRNG(collectibleType);
+    const seed = collectibleRNG.GetSeed();
+    return seed;
+}
+exports.getPlayerIndex = getPlayerIndex;
+function getPlayerIndexCollectibleType(player, differentiateForgottenAndSoul) {
+    const character = player.GetPlayerType();
+    if (character === isaac_typescript_definitions_1.PlayerType.SOUL) {
+        return differentiateForgottenAndSoul
+            ? isaac_typescript_definitions_1.CollectibleType.INNER_EYE
+            : DEFAULT_COLLECTIBLE_TYPE;
+    }
+    return DEFAULT_COLLECTIBLE_TYPE;
+}
+/**
+ * Helper function to return the index of this player with respect to the output of the
+ * `Isaac.GetPlayer` method.
+ *
+ * Note that if you storing information about a player in a data structure, you never want to use
+ * this index; use the `getPlayerIndex` function instead.
+ */
+function getPlayerIndexVanilla(playerToFind) {
+    const numPlayers = cachedClasses_1.game.GetNumPlayers();
+    const playerToFindHash = GetPtrHash(playerToFind);
+    for (let i = 0; i < numPlayers; i++) {
+        const player = Isaac.GetPlayer(i);
+        const playerHash = GetPtrHash(player);
+        if (playerHash === playerToFindHash) {
+            return i;
+        }
+    }
+    return undefined;
+}
+exports.getPlayerIndexVanilla = getPlayerIndexVanilla;
+/**
+ * This function always excludes players with a non-undefined parent, since they are not real
+ * players (e.g. the Strawman Keeper).
+ *
+ * If this is not desired, use the `getAllPlayers` helper function instead.
+ *
+ * @param performCharacterExclusions Whether to exclude characters that are not directly controlled
+ *                                 by the player (i.e. Esau & Tainted Soul). Default is false.
+ */
+function getPlayers(performCharacterExclusions = false) {
+    const players = getAllPlayers();
+    const nonChildPlayers = players.filter((player) => !isChildPlayer(player));
+    const nonChildPlayersFiltered = nonChildPlayers.filter((player) => {
+        const character = player.GetPlayerType();
+        return !EXCLUDED_CHARACTERS.has(character);
+    });
+    return performCharacterExclusions ? nonChildPlayersFiltered : nonChildPlayers;
+}
+exports.getPlayers = getPlayers;
+/**
+ * Helper function to get a parent `EntityPlayer` object for a given `EntitySubPlayer` object. This
+ * is useful because calling the `EntityPlayer.GetSubPlayer` method on a sub-player object will
+ * return undefined.
+ */
+function getSubPlayerParent(subPlayer) {
+    const subPlayerPtrHash = GetPtrHash(subPlayer);
+    const players = getPlayers();
+    return players.find((player) => {
+        const thisPlayerSubPlayer = player.GetSubPlayer();
+        if (thisPlayerSubPlayer === undefined) {
+            return false;
+        }
+        const thisPlayerSubPlayerPtrHash = GetPtrHash(thisPlayerSubPlayer);
+        return thisPlayerSubPlayerPtrHash === subPlayerPtrHash;
+    });
+}
+exports.getSubPlayerParent = getSubPlayerParent;
+/**
+ * Helper function to detect if a particular player is a "child" player, meaning that they have a
+ * non-undefined `EntityPlayer.Parent` field. (For example, the Strawman Keeper.)
+ */
+function isChildPlayer(player) {
+    return player.Parent !== undefined;
+}
+exports.isChildPlayer = isChildPlayer;
+/**
+ * Helper function to detect if a particular player is the Found Soul player provided by the
+ * trinket.
+ */
+function isFoundSoul(player) {
+    return (isChildPlayer(player) &&
+        player.Variant === isaac_typescript_definitions_1.PlayerVariant.COOP_BABY &&
+        player.SubType === isaac_typescript_definitions_1.BabySubType.FOUND_SOUL);
+}
+exports.isFoundSoul = isFoundSoul;

package/dist/functions/playerTrinkets.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeTrinketCostume = exports.removeAllPlayerTrinkets = exports.hasTrinket = exports.hasOpenTrinketSlot = exports.hasAnyTrinket = exports.getPlayersWithTrinket = exports.getPlayerTrinkets = exports.getOpenTrinketSlot = exports.anyPlayerHasTrinket = exports.addTrinketCostume = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const cachedEnumValues_1 = require("../arrays/cachedEnumValues");
+const cachedClasses_1 = require("../core/cachedClasses");
+const playerIndex_1 = require("./playerIndex");
+const players_1 = require("./players");
+function addTrinketCostume(player, trinketType) {
+    const itemConfigTrinket = cachedClasses_1.itemConfig.GetTrinket(trinketType);
+    if (itemConfigTrinket === undefined) {
+        return;
+    }
+    player.AddCostume(itemConfigTrinket, false);
+}
+exports.addTrinketCostume = addTrinketCostume;
+/**
+ * Helper function to check to see if any player has a particular trinket.
+ *
+ * @param trinketType The trinket type to check for.
+ * @param ignoreModifiers If set to true, only counts trinkets the player actually holds and ignores
+ *                        effects granted by other items. Default is false.
+ */
+function anyPlayerHasTrinket(trinketType, ignoreModifiers) {
+    const players = (0, playerIndex_1.getAllPlayers)();
+    return players.some((player) => player.HasTrinket(trinketType, ignoreModifiers));
+}
+exports.anyPlayerHasTrinket = anyPlayerHasTrinket;
+/**
+ * Returns the slot number corresponding to where a trinket can be safely inserted.
+ *
+ * For example:
+ *
+ * ```ts
+ * const player = Isaac.GetPlayer();
+ * const trinketSlot = getOpenTrinketSlotNum(player);
+ * if (trinketSlot !== undefined) {
+ *   // They have one or more open trinket slots
+ *   player.AddTrinket(TrinketType.SWALLOWED_PENNY);
+ * }
+ * ```
+ */
+function getOpenTrinketSlot(player) {
+    const maxTrinkets = player.GetMaxTrinkets();
+    const trinketType1 = player.GetTrinket(isaac_typescript_definitions_1.TrinketSlot.SLOT_1);
+    const trinketType2 = player.GetTrinket(isaac_typescript_definitions_1.TrinketSlot.SLOT_2);
+    if (maxTrinkets === 1) {
+        return trinketType1 === isaac_typescript_definitions_1.TrinketType.NULL ? 0 : undefined;
+    }
+    if (maxTrinkets === 2) {
+        if (trinketType1 === isaac_typescript_definitions_1.TrinketType.NULL) {
+            return 0;
+        }
+        return trinketType2 === isaac_typescript_definitions_1.TrinketType.NULL ? 1 : undefined;
+    }
+    error(`The player has an unknown number of trinket slots: ${maxTrinkets}`);
+}
+exports.getOpenTrinketSlot = getOpenTrinketSlot;
+/**
+ * Helper function to get all of the trinkets that the player is currently holding. This will not
+ * include any smelted trinkets.
+ */
+function getPlayerTrinkets(player) {
+    const trinketTypes = [];
+    for (const trinketSlot of cachedEnumValues_1.TRINKET_SLOT_VALUES) {
+        const trinketType = player.GetTrinket(trinketSlot);
+        if (trinketType !== isaac_typescript_definitions_1.TrinketType.NULL) {
+            trinketTypes.push(trinketType);
+        }
+    }
+    return trinketTypes;
+}
+exports.getPlayerTrinkets = getPlayerTrinkets;
+/**
+ * Helper function to get only the players that have a certain trinket.
+ *
+ * This function is variadic, meaning that you can supply as many trinket types as you want to check
+ * for. It only returns the players that have all of the trinkets.
+ */
+function getPlayersWithTrinket(...trinketTypes) {
+    const players = (0, playerIndex_1.getPlayers)();
+    return players.filter((player) => trinketTypes.every((trinketType) => player.HasTrinket(trinketType)));
+}
+exports.getPlayersWithTrinket = getPlayersWithTrinket;
+/** Helper function to check to see if the player is holding one or more trinkets. */
+function hasAnyTrinket(player) {
+    const playerTrinketTypes = cachedEnumValues_1.TRINKET_SLOT_VALUES.map((trinketSlot) => player.GetTrinket(trinketSlot));
+    return playerTrinketTypes.some((trinketType) => trinketType !== isaac_typescript_definitions_1.TrinketType.NULL);
+}
+exports.hasAnyTrinket = hasAnyTrinket;
+/**
+ * Returns whether the player can hold an additional trinket, beyond what they are currently
+ * carrying. This takes into account items that modify the max number of trinkets, like Mom's Purse.
+ *
+ * If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+ * items. (Only Tainted Forgotten can pick up items.)
+ */
+function hasOpenTrinketSlot(player) {
+    if ((0, players_1.isCharacter)(player, isaac_typescript_definitions_1.PlayerType.SOUL_B)) {
+        return false;
+    }
+    const openTrinketSlot = getOpenTrinketSlot(player);
+    return openTrinketSlot !== undefined;
+}
+exports.hasOpenTrinketSlot = hasOpenTrinketSlot;
+/**
+ * Helper function to check to see if a player has one or more trinkets.
+ *
+ * This function is variadic, meaning that you can supply as many trinket types as you want to check
+ * for. Returns true if the player has any of the supplied trinket types.
+ *
+ * This function always passes `false` to the `ignoreModifiers` argument.
+ */
+function hasTrinket(player, ...trinketTypes) {
+    return trinketTypes.some((trinketType) => player.HasTrinket(trinketType));
+}
+exports.hasTrinket = hasTrinket;
+/**
+ * Helper function to remove all of the held trinkets from a player.
+ *
+ * This will not remove any smelted trinkets, unless the player happens to also be holding a trinket
+ * that they have smelted. (In that case, both the held and the smelted trinket will be removed.)
+ */
+function removeAllPlayerTrinkets(player) {
+    for (const trinketSlot of cachedEnumValues_1.TRINKET_SLOT_VALUES) {
+        const trinketType = player.GetTrinket(trinketSlot);
+        if (trinketType === isaac_typescript_definitions_1.TrinketType.NULL) {
+            continue;
+        }
+        let alreadyHasTrinket;
+        do {
+            player.TryRemoveTrinket(trinketType);
+            alreadyHasTrinket = player.HasTrinket(trinketType);
+        } while (alreadyHasTrinket);
+    }
+}
+exports.removeAllPlayerTrinkets = removeAllPlayerTrinkets;
+/**
+ * Helper function to remove a trinket costume from a player. Use this helper function to avoid
+ * having to request the trinket from the item config.
+ */
+function removeTrinketCostume(player, trinketType) {
+    const itemConfigTrinket = cachedClasses_1.itemConfig.GetTrinket(trinketType);
+    if (itemConfigTrinket === undefined) {
+        return;
+    }
+    player.RemoveCostume(itemConfigTrinket);
+}
+exports.removeTrinketCostume = removeTrinketCostume;