isaacscript-common 2.3.0 → 3.0.0

package/functions/playerDataStructures.d.ts

@@ -0,0 +1,92 @@
+/// <reference types="isaac-typescript-definitions" />
+import { DefaultMap } from "../classes/DefaultMap";
+import { PlayerIndex } from "../types/PlayerIndex";
+/**
+ * Helper function to make using default maps with an index of `PlayerIndex` easier. Use this
+ * instead of the `DefaultMap.getAndSetDefault` method if you have a default map of this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const v = {
+ *   run: {
+ *     playersSpeedBoost: new DefaultMap<PlayerIndex, int>(0),
+ *   },
+ * };
+ *
+ * function evaluateCacheSpeed(player: EntityPlayer) {
+ *   player.MoveSpeed = defaultMapGetPlayer(v.run.playersSpeedBoost, player);
+ * }
+ * ```
+ */
+export declare function defaultMapGetPlayer<V, A extends unknown[]>(map: DefaultMap<PlayerIndex, V, A>, player: EntityPlayer, ...extraArgs: A): V;
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.set` method if you have a map of this type.
+ *
+ * Since `Map` and `DefaultMap` set values in the same way, this function is simply an alias for the
+ * `mapSetPlayer` helper function.
+ */
+export declare function defaultMapSetPlayer<V>(map: Map<PlayerIndex, V>, player: EntityPlayer, value: V): void;
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.get` method if you have a map of this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const v = {
+ *   run: {
+ *     playersSpeedBoost: new Map<PlayerIndex, int>(),
+ *   },
+ * };
+ *
+ * function incrementSpeedBoost(player: EntityPlayer) {
+ *   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+ *   const newSpeedBoost = oldSpeedBoost + 0.1;
+ *   mapSetPlayer(v.run.playersSpeedBoost, player);
+ * }
+ * ```
+ */
+export declare function mapGetPlayer<V>(map: Map<PlayerIndex, V>, player: EntityPlayer): V | undefined;
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.has` method if you have a map of this type.
+ */
+export declare function mapHasPlayer<V>(map: Map<PlayerIndex, V>, player: EntityPlayer): boolean;
+/**
+ * Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+ * `Map.set` method if you have a map of this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const v = {
+ *   run: {
+ *     playersSpeedBoost: new Map<PlayerIndex, int>(),
+ *   },
+ * };
+ *
+ * function incrementSpeedBoost(player: EntityPlayer) {
+ *   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+ *   const newSpeedBoost = oldSpeedBoost + 0.1;
+ *   mapSetPlayer(v.run.playersSpeedBoost, player);
+ * }
+ * ```
+ */
+export declare function mapSetPlayer<V>(map: Map<PlayerIndex, V>, player: EntityPlayer, value: V): void;
+/**
+ * Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+ * `Set.add` method if you have a set of this type.
+ */
+export declare function setAddPlayer(set: Set<PlayerIndex>, player: EntityPlayer): Set<PlayerIndex>;
+/**
+ * Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+ * `Set.delete` method if you have a set of this type.
+ */
+export declare function setDeletePlayer(set: Set<PlayerIndex>, player: EntityPlayer): boolean;
+/**
+ * Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+ * `Set.has` method if you have a set of this type.
+ */
+export declare function setHasPlayer(set: Set<PlayerIndex>, player: EntityPlayer): boolean;

package/functions/playerDataStructures.lua

@@ -0,0 +1,103 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local Set = ____lualib.Set
+local ____exports = {}
+local ____playerIndex = require("functions.playerIndex")
+local getPlayerIndex = ____playerIndex.getPlayerIndex
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.set` method if you have a map of this type.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   run: {
+--     playersSpeedBoost: new Map<PlayerIndex, int>(),
+--   },
+-- };
+-- 
+-- function incrementSpeedBoost(player: EntityPlayer) {
+--   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+--   const newSpeedBoost = oldSpeedBoost + 0.1;
+--   mapSetPlayer(v.run.playersSpeedBoost, player);
+-- }
+-- ```
+function ____exports.mapSetPlayer(self, map, player, value)
+    local playerIndex = getPlayerIndex(nil, player)
+    map:set(playerIndex, value)
+end
+--- Helper function to make using default maps with an index of `PlayerIndex` easier. Use this
+-- instead of the `DefaultMap.getAndSetDefault` method if you have a default map of this type.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   run: {
+--     playersSpeedBoost: new DefaultMap<PlayerIndex, int>(0),
+--   },
+-- };
+-- 
+-- function evaluateCacheSpeed(player: EntityPlayer) {
+--   player.MoveSpeed = defaultMapGetPlayer(v.run.playersSpeedBoost, player);
+-- }
+-- ```
+function ____exports.defaultMapGetPlayer(self, map, player, ...)
+    local playerIndex = getPlayerIndex(nil, player)
+    return map:getAndSetDefault(playerIndex, ...)
+end
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.set` method if you have a map of this type.
+-- 
+-- Since `Map` and `DefaultMap` set values in the same way, this function is simply an alias for the
+-- `mapSetPlayer` helper function.
+function ____exports.defaultMapSetPlayer(self, map, player, value)
+    ____exports.mapSetPlayer(nil, map, player, value)
+end
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.get` method if you have a map of this type.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const v = {
+--   run: {
+--     playersSpeedBoost: new Map<PlayerIndex, int>(),
+--   },
+-- };
+-- 
+-- function incrementSpeedBoost(player: EntityPlayer) {
+--   const oldSpeedBoost = mapGetPlayer(v.run.playersSpeedBoost, player);
+--   const newSpeedBoost = oldSpeedBoost + 0.1;
+--   mapSetPlayer(v.run.playersSpeedBoost, player);
+-- }
+-- ```
+function ____exports.mapGetPlayer(self, map, player)
+    local playerIndex = getPlayerIndex(nil, player)
+    return map:get(playerIndex)
+end
+--- Helper function to make using maps with an index of `PlayerIndex` easier. Use this instead of the
+-- `Map.has` method if you have a map of this type.
+function ____exports.mapHasPlayer(self, map, player)
+    local playerIndex = getPlayerIndex(nil, player)
+    return map:has(playerIndex)
+end
+--- Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+-- `Set.add` method if you have a set of this type.
+function ____exports.setAddPlayer(self, set, player)
+    local playerIndex = getPlayerIndex(nil, player)
+    return set:add(playerIndex)
+end
+--- Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+-- `Set.delete` method if you have a set of this type.
+function ____exports.setDeletePlayer(self, set, player)
+    local playerIndex = getPlayerIndex(nil, player)
+    return set:delete(playerIndex)
+end
+--- Helper function to make using sets with an type of `PlayerIndex` easier. Use this instead of the
+-- `Set.has` method if you have a set of this type.
+function ____exports.setHasPlayer(self, set, player)
+    local playerIndex = getPlayerIndex(nil, player)
+    return set:has(playerIndex)
+end
+return ____exports

package/functions/playerHealth.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="isaac-typescript-definitions" />
+import { HealthType } from "../enums/HealthType";
+import { PlayerHealth } from "../interfaces/PlayerHealth";
+export declare function addPlayerHealthType(player: EntityPlayer, healthType: HealthType, numHearts: int): void;
+/**
+ * Helper function to get an object representing the player's health. You can use this in
+ * combination with the `setPlayerHealth` function to restore the player's health back to a certain
+ * configuration at a later time.
+ *
+ * This is based on the `REVEL.StoreHealth` function in the Revelations mod.
+ */
+export declare function getPlayerHealth(player: EntityPlayer): PlayerHealth;
+export declare function getPlayerHealthType(player: EntityPlayer, healthType: HealthType): int;
+export declare function removeAllPlayerHealth(player: EntityPlayer): void;
+/**
+ * Helper function to set a player's health to a specific state. You can use this in combination
+ * with the `getPlayerHealth` function to restore the player's health back to a certain
+ * configuration at a later time.
+ *
+ * Based on the `REVEL.LoadHealth` function in the Revelations mod.
+ */
+export declare function setPlayerHealth(player: EntityPlayer, playerHealth: PlayerHealth): void;

package/functions/playerHealth.lua

@@ -0,0 +1,296 @@
+local ____lualib = require("lualib_bundle")
+local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local HeartSubType = ____isaac_2Dtypescript_2Ddefinitions.HeartSubType
+local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+local ____constants = require("constants")
+local MAX_PLAYER_HEART_CONTAINERS = ____constants.MAX_PLAYER_HEART_CONTAINERS
+local ____HealthType = require("enums.HealthType")
+local HealthType = ____HealthType.HealthType
+local ____player = require("functions.player")
+local getPlayerBlackHearts = ____player.getPlayerBlackHearts
+local getPlayerHearts = ____player.getPlayerHearts
+local getPlayerSoulHearts = ____player.getPlayerSoulHearts
+local isCharacter = ____player.isCharacter
+local ____utils = require("functions.utils")
+local ensureAllCases = ____utils.ensureAllCases
+local ____repeat = ____utils["repeat"]
+function ____exports.addPlayerHealthType(self, player, healthType, numHearts)
+    repeat
+        local ____switch3 = healthType
+        local ____cond3 = ____switch3 == HealthType.RED
+        if ____cond3 then
+            do
+                player:AddHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.SOUL
+        if ____cond3 then
+            do
+                player:AddSoulHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.ETERNAL
+        if ____cond3 then
+            do
+                player:AddEternalHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.BLACK
+        if ____cond3 then
+            do
+                player:AddBlackHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.GOLDEN
+        if ____cond3 then
+            do
+                player:AddGoldenHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.BONE
+        if ____cond3 then
+            do
+                player:AddBoneHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.ROTTEN
+        if ____cond3 then
+            do
+                player:AddRottenHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.BROKEN
+        if ____cond3 then
+            do
+                player:AddBrokenHearts(numHearts)
+                return
+            end
+        end
+        ____cond3 = ____cond3 or ____switch3 == HealthType.MAX_HEARTS
+        if ____cond3 then
+            do
+                player:AddMaxHearts(numHearts, false)
+                return
+            end
+        end
+        do
+            do
+                ensureAllCases(nil, healthType)
+            end
+        end
+    until true
+end
+--- Helper function to get an object representing the player's health. You can use this in
+-- combination with the `setPlayerHealth` function to restore the player's health back to a certain
+-- configuration at a later time.
+-- 
+-- This is based on the `REVEL.StoreHealth` function in the Revelations mod.
+function ____exports.getPlayerHealth(self, player)
+    local character = player:GetPlayerType()
+    local soulHeartTypes = {}
+    local maxHearts = player:GetMaxHearts()
+    local hearts = getPlayerHearts(nil, player)
+    local soulHearts = player:GetSoulHearts()
+    local boneHearts = player:GetBoneHearts()
+    local goldenHearts = player:GetGoldenHearts()
+    local eternalHearts = player:GetEternalHearts()
+    local rottenHearts = player:GetRottenHearts()
+    local brokenHearts = player:GetBrokenHearts()
+    local subPlayer = player:GetSubPlayer()
+    local soulCharges = player:GetEffectiveSoulCharge()
+    local bloodCharges = player:GetEffectiveBloodCharge()
+    if character == PlayerType.THE_FORGOTTEN and subPlayer ~= nil then
+        maxHearts = boneHearts * 2
+        boneHearts = 0
+        soulHearts = subPlayer:GetSoulHearts()
+    elseif character == PlayerType.THE_SOUL and subPlayer ~= nil then
+        maxHearts = subPlayer:GetBoneHearts() * 2
+        hearts = subPlayer:GetHearts()
+    end
+    local extraHearts = math.ceil(soulHearts / 2) + boneHearts
+    local currentSoulHeart = 0
+    do
+        local i = 0
+        while i < extraHearts do
+            local isBoneHeart = player:IsBoneHeart(i)
+            if character == PlayerType.THE_FORGOTTEN and subPlayer ~= nil then
+                isBoneHeart = subPlayer:IsBoneHeart(i)
+            end
+            if isBoneHeart then
+                soulHeartTypes[#soulHeartTypes + 1] = HeartSubType.BONE
+            else
+                local isBlackHeart = player:IsBlackHeart(currentSoulHeart + 1)
+                if character == PlayerType.THE_FORGOTTEN and subPlayer ~= nil then
+                    isBlackHeart = subPlayer:IsBlackHeart(currentSoulHeart + 1)
+                end
+                if isBlackHeart then
+                    soulHeartTypes[#soulHeartTypes + 1] = HeartSubType.BLACK
+                else
+                    soulHeartTypes[#soulHeartTypes + 1] = HeartSubType.SOUL
+                end
+                currentSoulHeart = currentSoulHeart + 2
+            end
+            i = i + 1
+        end
+    end
+    return {
+        maxHearts = maxHearts,
+        hearts = hearts,
+        eternalHearts = eternalHearts,
+        soulHearts = soulHearts,
+        boneHearts = boneHearts,
+        goldenHearts = goldenHearts,
+        rottenHearts = rottenHearts,
+        brokenHearts = brokenHearts,
+        soulCharges = soulCharges,
+        bloodCharges = bloodCharges,
+        soulHeartTypes = soulHeartTypes
+    }
+end
+function ____exports.getPlayerHealthType(self, player, healthType)
+    repeat
+        local ____switch25 = healthType
+        local ____cond25 = ____switch25 == HealthType.RED
+        if ____cond25 then
+            do
+                return getPlayerHearts(nil, player)
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.SOUL
+        if ____cond25 then
+            do
+                return getPlayerSoulHearts(nil, player)
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.ETERNAL
+        if ____cond25 then
+            do
+                return player:GetEternalHearts()
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.BLACK
+        if ____cond25 then
+            do
+                return getPlayerBlackHearts(nil, player)
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.GOLDEN
+        if ____cond25 then
+            do
+                return player:GetGoldenHearts()
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.BONE
+        if ____cond25 then
+            do
+                return player:GetBoneHearts()
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.ROTTEN
+        if ____cond25 then
+            do
+                return player:GetRottenHearts()
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.BROKEN
+        if ____cond25 then
+            do
+                return player:GetBrokenHearts()
+            end
+        end
+        ____cond25 = ____cond25 or ____switch25 == HealthType.MAX_HEARTS
+        if ____cond25 then
+            do
+                return player:GetMaxHearts()
+            end
+        end
+        do
+            do
+                return ensureAllCases(nil, healthType)
+            end
+        end
+    until true
+end
+function ____exports.removeAllPlayerHealth(self, player)
+    local goldenHearts = player:GetGoldenHearts()
+    local eternalHearts = player:GetEternalHearts()
+    local boneHearts = player:GetBoneHearts()
+    local brokenHearts = player:GetBrokenHearts()
+    player:AddGoldenHearts(goldenHearts * -1)
+    player:AddEternalHearts(eternalHearts * -1)
+    player:AddBoneHearts(boneHearts * -1)
+    player:AddBrokenHearts(brokenHearts * -1)
+    player:AddMaxHearts(MAX_PLAYER_HEART_CONTAINERS * -2, true)
+    player:AddSoulHearts(MAX_PLAYER_HEART_CONTAINERS * -2)
+    if isCharacter(nil, player, PlayerType.THE_SOUL) then
+        local forgotten = player:GetSubPlayer()
+        if forgotten ~= nil then
+            local forgottenBoneHearts = forgotten:GetBoneHearts()
+            forgotten:AddBoneHearts(forgottenBoneHearts * -1)
+        end
+    end
+end
+--- Helper function to set a player's health to a specific state. You can use this in combination
+-- with the `getPlayerHealth` function to restore the player's health back to a certain
+-- configuration at a later time.
+-- 
+-- Based on the `REVEL.LoadHealth` function in the Revelations mod.
+function ____exports.setPlayerHealth(self, player, playerHealth)
+    local character = player:GetPlayerType()
+    local subPlayer = player:GetSubPlayer()
+    ____exports.removeAllPlayerHealth(nil, player)
+    if character == PlayerType.THE_SOUL and subPlayer ~= nil then
+        subPlayer:AddMaxHearts(playerHealth.maxHearts, false)
+    else
+        player:AddMaxHearts(playerHealth.maxHearts, false)
+    end
+    player:AddEternalHearts(playerHealth.eternalHearts)
+    local soulHeartsRemaining = playerHealth.soulHearts
+    __TS__ArrayForEach(
+        playerHealth.soulHeartTypes,
+        function(____, heartType, i)
+            local isHalf = playerHealth.soulHearts + playerHealth.boneHearts * 2 < (i + 1) * 2
+            local addAmount = 2
+            if isHalf or heartType == HeartSubType.BONE or soulHeartsRemaining < 2 then
+                addAmount = 1
+            end
+            if heartType == HeartSubType.SOUL then
+                player:AddSoulHearts(addAmount)
+                soulHeartsRemaining = soulHeartsRemaining - addAmount
+            elseif heartType == HeartSubType.BLACK then
+                player:AddBlackHearts(addAmount)
+                soulHeartsRemaining = soulHeartsRemaining - addAmount
+            elseif heartType == HeartSubType.BONE then
+                player:AddBoneHearts(addAmount)
+            end
+        end
+    )
+    player:AddRottenHearts(playerHealth.rottenHearts)
+    ____repeat(
+        nil,
+        playerHealth.hearts,
+        function()
+            player:AddHearts(1)
+            if character == PlayerType.MAGDALENE_B then
+                player:AddHearts(-1)
+            end
+        end
+    )
+    player:AddGoldenHearts(playerHealth.goldenHearts)
+    player:AddBrokenHearts(playerHealth.brokenHearts)
+    if character == PlayerType.BETHANY then
+        player:SetSoulCharge(playerHealth.soulCharges)
+    elseif character == PlayerType.BETHANY_B then
+        player:SetBloodCharge(playerHealth.bloodCharges)
+    end
+end
+return ____exports

package/functions/playerIndex.d.ts

@@ -0,0 +1,68 @@
+/// <reference types="isaac-typescript-definitions" />
+import { PlayerIndex } from "../types/PlayerIndex";
+/**
+ * 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.
+ */
+export declare function getAllPlayers(): EntityPlayer[];
+export declare function getPlayerFromIndex(playerIndex: PlayerIndex): EntityPlayer | undefined;
+/**
+ * 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.
+ *
+ * Since the RNG value is the same for both Tainted Lazarus and Dead Tainted Lazarus, we revert to
+ * using the RNG of The Inner Eye (2) for Dead Tainted Lazarus.
+ *
+ * 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.
+ */
+export declare function getPlayerIndex(player: EntityPlayer, differentiateForgottenAndSoul?: boolean): PlayerIndex;
+/**
+ * Helper function to return the index of this player with respect to the output of the
+ * `Isaac.GetPlayer` method.
+ */
+export declare function getPlayerIndexVanilla(playerToFind: EntityPlayer): int | undefined;
+/**
+ * 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 or not to exclude characters that are not directly
+ *                                 controlled by the player (i.e. Esau & Tainted Soul). Default is
+ *                                 false.
+ */
+export declare function getPlayers(performCharacterExclusions?: boolean): EntityPlayer[];
+/**
+ * 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.
+ */
+export declare function getSubPlayerParent(subPlayer: EntitySubPlayer): EntityPlayer | undefined;
+/**
+ * Some players are "child" players, meaning that they have a non-undefined Parent property. (For
+ * example, the Strawman Keeper.)
+ */
+export declare function isChildPlayer(player: EntityPlayer): boolean;