isaacscript-common 3.1.0 → 3.3.0

package/features/deployJSONRoom.lua

@@ -4,7 +4,7 @@ local __TS__New = ____lualib.__TS__New
 local Map = ____lualib.Map
 local __TS__Iterator = ____lualib.__TS__Iterator
 local ____exports = {}
-local postNewRoom, setDecorationsInvisible, respawnPersistentEntities, removeSpecificNPCs, fillRoomWithDecorations, spawnAllEntities, spawnGridEntityForJSONRoom, spawnNormalEntityForJSONRoom, storePersistentEntity, fixPitGraphics, getPitMap, getPitFrame, FEATURE_NAME, NPC_TYPES_TO_NOT_REMOVE, PERSISTENT_ENTITY_TYPES, v
+local postNewRoomReordered, setDecorationsInvisible, respawnPersistentEntities, removeSpecificNPCs, fillRoomWithDecorations, spawnAllEntities, spawnGridEntityForJSONRoom, spawnNormalEntityForJSONRoom, storePersistentEntity, fixPitGraphics, getPitMap, getPitFrame, FEATURE_NAME, NPC_TYPES_TO_NOT_REMOVE, PERSISTENT_ENTITY_TYPES, v
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local EffectVariant = ____isaac_2Dtypescript_2Ddefinitions.EffectVariant
 local EntityCollisionClass = ____isaac_2Dtypescript_2Ddefinitions.EntityCollisionClass
@@ -12,7 +12,6 @@ local EntityFlag = ____isaac_2Dtypescript_2Ddefinitions.EntityFlag
 local EntityGridCollisionClass = ____isaac_2Dtypescript_2Ddefinitions.EntityGridCollisionClass
 local EntityType = ____isaac_2Dtypescript_2Ddefinitions.EntityType
 local GridEntityType = ____isaac_2Dtypescript_2Ddefinitions.GridEntityType
-local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
 local PickupVariant = ____isaac_2Dtypescript_2Ddefinitions.PickupVariant
 local PitfallVariant = ____isaac_2Dtypescript_2Ddefinitions.PitfallVariant
 local RoomType = ____isaac_2Dtypescript_2Ddefinitions.RoomType
@@ -20,6 +19,8 @@ local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local ____DefaultMap = require("classes.DefaultMap")
 local DefaultMap = ____DefaultMap.DefaultMap
+local ____ModCallbackCustom = require("enums.ModCallbackCustom")
+local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
 local ____featuresInitialized = require("featuresInitialized")
 local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
 local ____entity = require("functions.entity")
@@ -57,7 +58,7 @@ local ____utils = require("functions.utils")
 local erange = ____utils.erange
 local ____exports = require("features.saveDataManager.exports")
 local saveDataManager = ____exports.saveDataManager
-function postNewRoom(self)
+function postNewRoomReordered(self)
     local roomListIndex = getRoomListIndex(nil)
     if not v.level.deployedRoomListIndexes:has(roomListIndex) then
         return
@@ -427,7 +428,7 @@ v = {level = {
 -- @internal
 function ____exports.deployJSONRoomInit(self, mod)
     saveDataManager(nil, "deployJSONRoom", v)
-    mod:AddCallback(ModCallback.POST_NEW_ROOM, postNewRoom)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_REORDERED, postNewRoomReordered)
 end
 --- Helper function to deconstruct a vanilla room and set up a custom room in its place.
 -- Specifically, this will clear the current room of all entities and grid entities, and then spawn

package/features/extraConsoleCommands/listCommands.lua

@@ -810,6 +810,7 @@ end
 --- Logs information about the room to the "log.txt" file.
 function ____exports.roomCommand(self)
     logRoom()
+    printConsole(nil, "Logged room information to the \"log.txt\" file.")
 end
 --- Gives a rotten heart. Provide a number to give a custom amount of hearts. (You can use negative
 -- numbers to remove hearts.)

package/features/persistentEntities.d.ts

@@ -0,0 +1,28 @@
+import { EntityType } from "isaac-typescript-definitions";
+/**
+ * Helper function to spawn an entity that will have persistence similar to a pickup.
+ *
+ * By default, as soon as you leave a room, any spawned entities will be despawned and will not
+ * return if the player revisits the room. This means that if you want to have an entity like a
+ * pickup, you have to manually respawn it when the player re-enters the room. Use this helper
+ * function to avoid having to do any tracking on your own.
+ *
+ * Conventionally, the word "persistent" refers to `EntityFlag.FLAG_PERSISTENT`, which is used on
+ * e.g. familiars to make them appear in every room. On the other hand, pickups are also persistent,
+ * but they are not present in every room, only one specific room. This function spawns entities
+ * like pickups, not familiars.
+ *
+ * @returns A tuple containing the entity and the persistent entity index. You can use the index
+ *          with the `removePersistentEntity` function.
+ */
+export declare function spawnPersistentEntity(entityType: EntityType, variant: int, subType: int, position: Vector): [Entity, int];
+/**
+ * Helper function to stop an entity spawned with the `spawnPersistentEntity` helper function from
+ * respawning.
+ *
+ * @param persistentEntityIndex The index that was returned by the `spawnPersistentEntity` function.
+ * @param removeEntity Optional. True by default. Set to false if you want to stop an entity from
+ *                     being persistent but you don't want to actually remove the currently-spawned
+ *                     entity from the room.
+ */
+export declare function removePersistentEntity(persistentEntityIndex: int, removeEntity?: boolean): void;

package/features/persistentEntities.lua

@@ -0,0 +1,150 @@
+local ____lualib = require("lualib_bundle")
+local Map = ____lualib.Map
+local __TS__New = ____lualib.__TS__New
+local __TS__Iterator = ____lualib.__TS__Iterator
+local ____exports = {}
+local postEntityRemove, postNewRoomReordered, spawnAndTrack, v
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local EntityFlag = ____isaac_2Dtypescript_2Ddefinitions.EntityFlag
+local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
+local ____cachedClasses = require("cachedClasses")
+local game = ____cachedClasses.game
+local ____ModCallbackCustom = require("enums.ModCallbackCustom")
+local ModCallbackCustom = ____ModCallbackCustom.ModCallbackCustom
+local ____entity = require("functions.entity")
+local spawn = ____entity.spawn
+local ____roomData = require("functions.roomData")
+local getRoomListIndex = ____roomData.getRoomListIndex
+local ____exports = require("features.saveDataManager.exports")
+local saveDataManager = ____exports.saveDataManager
+function postEntityRemove(self, entity)
+    local ptrHash = GetPtrHash(entity)
+    local tuple = v.room.spawnedPersistentEntities:get(ptrHash)
+    if tuple == nil then
+        return
+    end
+    local index = tuple[1]
+    local level = game:GetLevel()
+    local previousRoomGridIndex = level:GetPreviousRoomIndex()
+    local previousRoomListIndex = getRoomListIndex(nil, previousRoomGridIndex)
+    v.level.persistentEntities:set(index, {
+        entityType = entity.Type,
+        variant = entity.Variant,
+        subType = entity.SubType,
+        roomListIndex = previousRoomListIndex,
+        position = entity.Position
+    })
+end
+function postNewRoomReordered(self)
+    local roomListIndex = getRoomListIndex(nil)
+    for ____, ____value in __TS__Iterator(v.level.persistentEntities:entries()) do
+        local index = ____value[1]
+        local description = ____value[2]
+        do
+            if roomListIndex ~= description.roomListIndex then
+                goto __continue6
+            end
+            v.level.persistentEntities:delete(index)
+            spawnAndTrack(
+                nil,
+                description.entityType,
+                description.variant,
+                description.subType,
+                description.position,
+                index,
+                true
+            )
+        end
+        ::__continue6::
+    end
+end
+function spawnAndTrack(self, entityType, variant, subType, position, index, respawning)
+    if respawning == nil then
+        respawning = false
+    end
+    local entity = spawn(
+        nil,
+        entityType,
+        variant,
+        subType,
+        position
+    )
+    if respawning then
+        entity:ClearEntityFlags(EntityFlag.APPEAR)
+    end
+    local ptrHash = GetPtrHash(entity)
+    local tuple = {
+        index,
+        EntityPtr(entity)
+    }
+    v.room.spawnedPersistentEntities:set(ptrHash, tuple)
+    return entity
+end
+--- Iterates upward as new persistent entities are created.
+local persistentEntityIndexCounter = 0
+v = {
+    level = {persistentEntities = __TS__New(Map)},
+    room = {spawnedPersistentEntities = __TS__New(Map)}
+}
+---
+-- @internal
+function ____exports.persistentEntitiesInit(self, mod)
+    saveDataManager(nil, "persistentEntities", v)
+    mod:AddCallback(ModCallback.POST_ENTITY_REMOVE, postEntityRemove)
+    mod:AddCallbackCustom(ModCallbackCustom.POST_NEW_ROOM_REORDERED, postNewRoomReordered)
+end
+--- Helper function to spawn an entity that will have persistence similar to a pickup.
+-- 
+-- By default, as soon as you leave a room, any spawned entities will be despawned and will not
+-- return if the player revisits the room. This means that if you want to have an entity like a
+-- pickup, you have to manually respawn it when the player re-enters the room. Use this helper
+-- function to avoid having to do any tracking on your own.
+-- 
+-- Conventionally, the word "persistent" refers to `EntityFlag.FLAG_PERSISTENT`, which is used on
+-- e.g. familiars to make them appear in every room. On the other hand, pickups are also persistent,
+-- but they are not present in every room, only one specific room. This function spawns entities
+-- like pickups, not familiars.
+-- 
+-- @returns A tuple containing the entity and the persistent entity index. You can use the index
+-- with the `removePersistentEntity` function.
+function ____exports.spawnPersistentEntity(self, entityType, variant, subType, position)
+    persistentEntityIndexCounter = persistentEntityIndexCounter + 1
+    local entity = spawnAndTrack(
+        nil,
+        entityType,
+        variant,
+        subType,
+        position,
+        persistentEntityIndexCounter
+    )
+    return {entity, persistentEntityIndexCounter}
+end
+--- Helper function to stop an entity spawned with the `spawnPersistentEntity` helper function from
+-- respawning.
+-- 
+-- @param persistentEntityIndex The index that was returned by the `spawnPersistentEntity` function.
+-- @param removeEntity Optional. True by default. Set to false if you want to stop an entity from
+-- being persistent but you don't want to actually remove the currently-spawned
+-- entity from the room.
+function ____exports.removePersistentEntity(self, persistentEntityIndex, removeEntity)
+    if removeEntity == nil then
+        removeEntity = true
+    end
+    v.level.persistentEntities:delete(persistentEntityIndex)
+    for ____, ____value in __TS__Iterator(v.room.spawnedPersistentEntities:entries()) do
+        local ptrHash = ____value[1]
+        local tuple = ____value[2]
+        do
+            local index, entityPtr = table.unpack(tuple)
+            if index ~= persistentEntityIndex then
+                goto __continue13
+            end
+            v.room.spawnedPersistentEntities:delete(ptrHash)
+            if removeEntity and entityPtr.Ref ~= nil then
+                entityPtr.Ref:Remove()
+            end
+        end
+        ::__continue13::
+    end
+end
+return ____exports

package/functions/bombs.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="isaac-typescript-definitions" />
+/** Helper function to find out how large a bomb explosion is based on the damage inflicted. */
+export declare function getBombRadiusFromDamage(damage: float): float;

package/functions/bombs.lua

@@ -0,0 +1,12 @@
+local ____exports = {}
+--- Helper function to find out how large a bomb explosion is based on the damage inflicted.
+function ____exports.getBombRadiusFromDamage(self, damage)
+    if damage > 175 then
+        return 105
+    end
+    if damage <= 140 then
+        return 75
+    end
+    return 90
+end
+return ____exports

package/functions/collectibles.d.ts

@@ -52,13 +52,13 @@ export declare function getCollectibleGfxFilename(collectibleType: CollectibleTy
  *   and the pedestal pushed to an adjacent tile, but this case should be extremely rare.)
  * - Mega Chests spawn two collectibles on the exact same position. However, both of them will have
  *   different InitSeeds, so this is not a problem for this indexing scheme.
- * - The indexing scheme used is different for collectibles that are inside of a Treasure Room, in
- *   order to handle the case of the player seeing the same collectible again in a post-Ascent
- *   Treasure Room. A 5-tuple of stage, stage type, grid index, SubType, and InitSeed is used in
- *   this case. (Using the room list index or the room grid index is not suitable for this purpose,
- *   since both of these values can change in the post-Ascent Treasure Room.) Even though there can
- *   be two Treasure Rooms on an XL floor, both Treasure Rooms should not have collectibles with the
- *   same grid index, Subtype, and InitSeed.
+ * - The indexing scheme used is different for collectibles that are inside of a Treasure Room or
+ *   Boss Room, in order to handle the case of the player seeing the same collectible again in a
+ *   post-Ascent Treasure Room or Boss Room. A 5-tuple of stage, stage type, grid index, SubType,
+ *   and InitSeed is used in this case. (Using the room list index or the room grid index is not
+ *   suitable for this purpose, since both of these values can change in the post-Ascent rooms.)
+ *   Even though Treasure Rooms and Boss Rooms are grouped together in this scheme, there probably
+ *   will not be collectibles with the same grid index, SubType, and InitSeed.
  */
 export declare function getCollectibleIndex(collectible: EntityPickup): CollectibleIndex;
 /**

package/functions/collectibles.lua

@@ -176,13 +176,13 @@ end
 --   and the pedestal pushed to an adjacent tile, but this case should be extremely rare.)
 -- - Mega Chests spawn two collectibles on the exact same position. However, both of them will have
 --   different InitSeeds, so this is not a problem for this indexing scheme.
--- - The indexing scheme used is different for collectibles that are inside of a Treasure Room, in
---   order to handle the case of the player seeing the same collectible again in a post-Ascent
---   Treasure Room. A 5-tuple of stage, stage type, grid index, SubType, and InitSeed is used in
---   this case. (Using the room list index or the room grid index is not suitable for this purpose,
---   since both of these values can change in the post-Ascent Treasure Room.) Even though there can
---   be two Treasure Rooms on an XL floor, both Treasure Rooms should not have collectibles with the
---   same grid index, Subtype, and InitSeed.
+-- - The indexing scheme used is different for collectibles that are inside of a Treasure Room or
+--   Boss Room, in order to handle the case of the player seeing the same collectible again in a
+--   post-Ascent Treasure Room or Boss Room. A 5-tuple of stage, stage type, grid index, SubType,
+--   and InitSeed is used in this case. (Using the room list index or the room grid index is not
+--   suitable for this purpose, since both of these values can change in the post-Ascent rooms.)
+--   Even though Treasure Rooms and Boss Rooms are grouped together in this scheme, there probably
+--   will not be collectibles with the same grid index, SubType, and InitSeed.
 function ____exports.getCollectibleIndex(self, collectible)
     if not isCollectible(nil, collectible) then
         local entityID = getEntityID(nil, collectible)
@@ -195,7 +195,7 @@ function ____exports.getCollectibleIndex(self, collectible)
     local roomType = room:GetType()
     local gridIndex = room:GetGridIndex(collectible.Position)
     local roomListIndex = getRoomListIndex(nil)
-    if roomType == RoomType.TREASURE then
+    if roomType == RoomType.TREASURE or roomType == RoomType.BOSS then
         return (((((((tostring(stage) .. ",") .. tostring(stageType)) .. ",") .. tostring(gridIndex)) .. ",") .. tostring(collectible.SubType)) .. ",") .. tostring(collectible.InitSeed)
     end
     return (((((tostring(roomListIndex) .. ",") .. tostring(gridIndex)) .. ",") .. tostring(collectible.SubType)) .. ",") .. tostring(collectible.InitSeed)

package/functions/color.d.ts

@@ -9,9 +9,6 @@ interface CopyColorReturn {
     [SerializationType.SERIALIZE]: SerializedColor;
     [SerializationType.DESERIALIZE]: Color;
 }
-/**
- * @category color
- */
 export declare function colorEquals(color1: Color, color2: Color): boolean;
 /**
  * Helper function to copy a `Color` object.
@@ -19,27 +16,16 @@ export declare function colorEquals(color1: Color, color2: Color): boolean;
  * @param color The Color object to copy. In the case of deserialization, this will actually be a
  *              Lua table instead of an instantiated Color class.
  * @param serializationType Default is `SerializationType.NONE`.
- * @category color
  */
 export declare function copyColor<C extends Color | SerializedColor, S extends SerializationType>(color: C, serializationType: S): CopyColorReturn[S];
 export declare function copyColor<C extends Color | SerializedColor>(color: C): CopyColorReturn[SerializationType.NONE];
-/**
- * Returns `Color(1, 1, 1)`.
- *
- * @category color
- */
+/** Returns `Color(1, 1, 1)`. */
 export declare function getDefaultColor(): Color;
-/**
- * Helper function to check if something is an instantiated Color object.
- *
- * @category color
- */
+/** Helper function to check if something is an instantiated Color object. */
 export declare function isColor(object: unknown): object is Color;
 /**
  * Used to determine is the given table is a serialized `Color` object created by the save data
  * manager and/or the `deepCopy` function.
- *
- * @category color
  */
 export declare function isSerializedColor(object: unknown): object is SerializedColor;
 export {};

package/functions/color.lua

@@ -14,8 +14,6 @@ local tableHasKeys = ____table.tableHasKeys
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
 --- Helper function to check if something is an instantiated Color object.
--- 
--- @category color
 function ____exports.isColor(self, object)
     return isIsaacAPIClassOfType(nil, object, OBJECT_NAME)
 end
@@ -29,8 +27,6 @@ local KEYS = {
     "BO"
 }
 OBJECT_NAME = "Color"
----
--- @category color
 function ____exports.colorEquals(self, color1, color2)
     return isaacAPIClassEquals(nil, color1, color2, KEYS)
 end
@@ -39,7 +35,6 @@ end
 -- @param color The Color object to copy. In the case of deserialization, this will actually be a
 -- Lua table instead of an instantiated Color class.
 -- @param serializationType Default is `SerializationType.NONE`.
--- @category color
 function ____exports.copyColor(self, color, serializationType)
     if serializationType == nil then
         serializationType = SerializationType.NONE
@@ -116,15 +111,11 @@ function ____exports.copyColor(self, color, serializationType)
     until true
 end
 --- Returns `Color(1, 1, 1)`.
--- 
--- @category color
 function ____exports.getDefaultColor(self)
     return Color(1, 1, 1)
 end
 --- Used to determine is the given table is a serialized `Color` object created by the save data
 -- manager and/or the `deepCopy` function.
--- 
--- @category color
 function ____exports.isSerializedColor(self, object)
     local objectType = type(object)
     if objectType ~= "table" then

package/functions/direction.d.ts

@@ -1,4 +1,11 @@
 import { Direction } from "isaac-typescript-definitions";
+/**
+ * Helper function to convert the degrees of an angle to the `Direction` enum.
+ *
+ * Note that this function considers 0 degrees to be pointing to the right, which is unusual because
+ * 0 normally corresponds to up. (This corresponds to how the `Vector.GetAngleDegrees` method
+ * works.)
+ */
 export declare function angleToDirection(angleDegrees: int): Direction;
 export declare function directionToDegrees(direction: Direction): int;
 export declare function directionToVector(direction: Direction): Vector;

package/functions/direction.lua

@@ -7,6 +7,11 @@ local ____directionToDegrees = require("objects.directionToDegrees")
 local DIRECTION_TO_DEGREES = ____directionToDegrees.DIRECTION_TO_DEGREES
 local ____directionToVector = require("objects.directionToVector")
 local DIRECTION_TO_VECTOR = ____directionToVector.DIRECTION_TO_VECTOR
+--- Helper function to convert the degrees of an angle to the `Direction` enum.
+-- 
+-- Note that this function considers 0 degrees to be pointing to the right, which is unusual because
+-- 0 normally corresponds to up. (This corresponds to how the `Vector.GetAngleDegrees` method
+-- works.)
 function ____exports.angleToDirection(self, angleDegrees)
     local positiveDegrees = angleDegrees
     while positiveDegrees < 0 do
@@ -14,18 +19,18 @@ function ____exports.angleToDirection(self, angleDegrees)
     end
     local normalizedDegrees = positiveDegrees % 360
     if normalizedDegrees < 45 then
-        return Direction.UP
+        return Direction.RIGHT
     end
     if normalizedDegrees < 135 then
-        return Direction.RIGHT
+        return Direction.DOWN
     end
     if normalizedDegrees < 225 then
-        return Direction.DOWN
+        return Direction.LEFT
     end
     if normalizedDegrees < 315 then
-        return Direction.RIGHT
+        return Direction.UP
     end
-    return Direction.UP
+    return Direction.RIGHT
 end
 function ____exports.directionToDegrees(self, direction)
     return DIRECTION_TO_DEGREES[direction]

package/functions/entity.d.ts

@@ -11,6 +11,16 @@ import { AnyEntity } from "../types/AnyEntity";
  * @param ignoreFriendly Default is false.
  */
 export declare function countEntities(entityType?: EntityType, variant?: number, subType?: number, ignoreFriendly?: boolean): int;
+/**
+ * Helper function to check if one or more of a specific kind of entity is present in the current
+ * room. It uses the `countEntities` helper function to determine this.
+ *
+ * @param entityType Default is -1. -1 matches every entity type.
+ * @param variant Default is -1. -1 matches every variant.
+ * @param subType Default is -1. -1 matches every sub-type.
+ * @param ignoreFriendly Default is false.
+ */
+export declare function doesEntityExist(entityType?: EntityType, variant?: number, subType?: number, ignoreFriendly?: boolean): boolean;
 /**
  * Given an array of entities, this helper function returns the closest one to a provided reference
  * entity.

package/functions/entity.lua

@@ -66,6 +66,35 @@ function ____exports.countEntities(self, entityType, variant, subType, ignoreFri
     )
     return #entities
 end
+--- Helper function to check if one or more of a specific kind of entity is present in the current
+-- room. It uses the `countEntities` helper function to determine this.
+-- 
+-- @param entityType Default is -1. -1 matches every entity type.
+-- @param variant Default is -1. -1 matches every variant.
+-- @param subType Default is -1. -1 matches every sub-type.
+-- @param ignoreFriendly Default is false.
+function ____exports.doesEntityExist(self, entityType, variant, subType, ignoreFriendly)
+    if entityType == nil then
+        entityType = -1
+    end
+    if variant == nil then
+        variant = -1
+    end
+    if subType == nil then
+        subType = -1
+    end
+    if ignoreFriendly == nil then
+        ignoreFriendly = false
+    end
+    local count = ____exports.countEntities(
+        nil,
+        entityType,
+        variant,
+        subType,
+        ignoreFriendly
+    )
+    return count > 0
+end
 --- Given an array of entities, this helper function returns the closest one to a provided reference
 -- entity.
 -- 

package/functions/log.lua

@@ -229,7 +229,7 @@ function ____exports.logEntities(includeBackgroundEffects, entityTypeFilter)
     if numMatchedEntities == 0 then
         msg = msg .. "(no entities matched)\n"
     else
-        msg = msg .. ("(" .. tostring(numMatchedEntities)) .. " total entities)\n"
+        msg = msg .. ((("(" .. tostring(numMatchedEntities)) .. " total ") .. (numMatchedEntities == 1 and "entity" or "entities")) .. ")\n"
     end
     ____exports.log(msg)
 end
@@ -336,7 +336,7 @@ function ____exports.logGridEntities(includeWalls, gridEntityTypeFilter)
     if numMatchedEntities == 0 then
         msg = msg .. "(no grid entities matched)\n"
     else
-        msg = msg .. ("(" .. tostring(numMatchedEntities)) .. " total grid entities)\n"
+        msg = msg .. ((("(" .. tostring(numMatchedEntities)) .. " total grid ") .. (numMatchedEntities == 1 and "entity" or "entities")) .. ")\n"
     end
     ____exports.log(msg)
 end

package/functions/player.d.ts

@@ -100,6 +100,8 @@ export declare function getPlayerCollectibleCount(player: EntityPlayer, ...colle
  * the player has.
  */
 export declare function getPlayerCollectibleMap(player: EntityPlayer): Map<CollectibleType, int>;
+/** Helper function to get the player from a tear, laser, bomb, etc. */
+export declare function getPlayerFromTear(entity: Entity): EntityPlayer | undefined;
 /**
  * Returns the number of red hearts that the player has, excluding any rotten hearts. For example,
  * if the player has one full black heart, one full soul heart, and one half black heart, this
@@ -207,6 +209,11 @@ export declare function isBethany(player: EntityPlayer): boolean;
  * for. Returns true if the player is any of the supplied characters.
  */
 export declare function isCharacter(player: EntityPlayer, ...characters: PlayerType[]): boolean;
+/**
+ * Helper function to see if a damage source is from a player. Use this instead of comparing to the
+ * entity directly because it takes familiars into account.
+ */
+export declare function isDamageFromPlayer(damageSource: Entity): boolean;
 /**
  * Helper function for detecting when a player is Eden or Tainted Eden. Useful for situations where
  * you want to know if the starting stats were randomized, for example.

package/functions/player.lua

@@ -15,6 +15,7 @@ local ActiveSlot = ____isaac_2Dtypescript_2Ddefinitions.ActiveSlot
 local CacheFlag = ____isaac_2Dtypescript_2Ddefinitions.CacheFlag
 local Challenge = ____isaac_2Dtypescript_2Ddefinitions.Challenge
 local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
+local FamiliarVariant = ____isaac_2Dtypescript_2Ddefinitions.FamiliarVariant
 local NullItemID = ____isaac_2Dtypescript_2Ddefinitions.NullItemID
 local PlayerForm = ____isaac_2Dtypescript_2Ddefinitions.PlayerForm
 local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
@@ -377,6 +378,30 @@ function ____exports.getPlayerCollectibleMap(self, player)
     end
     return collectibleMap
 end
+--- Helper function to get the player from a tear, laser, bomb, etc.
+function ____exports.getPlayerFromTear(self, entity)
+    if entity.Parent ~= nil then
+        local player = entity.Parent:ToPlayer()
+        if player ~= nil then
+            return player
+        end
+        local familiar = entity.Parent:ToFamiliar()
+        if familiar ~= nil and familiar.Variant == FamiliarVariant.INCUBUS then
+            return familiar.Player
+        end
+    end
+    if entity.SpawnerEntity ~= nil then
+        local player = entity.SpawnerEntity:ToPlayer()
+        if player ~= nil then
+            return player
+        end
+        local familiar = entity.SpawnerEntity:ToFamiliar()
+        if familiar ~= nil and familiar.Variant == FamiliarVariant.INCUBUS then
+            return familiar.Player
+        end
+    end
+    return nil
+end
 --- Returns the number of red hearts that the player has, excluding any rotten hearts. For example,
 -- if the player has one full black heart, one full soul heart, and one half black heart, this
 -- function returns 3.
@@ -567,6 +592,16 @@ function ____exports.isBethany(self, player)
     local character = player:GetPlayerType()
     return character == PlayerType.BETHANY or character == PlayerType.BETHANY_B
 end
+--- Helper function to see if a damage source is from a player. Use this instead of comparing to the
+-- entity directly because it takes familiars into account.
+function ____exports.isDamageFromPlayer(self, damageSource)
+    local player = damageSource:ToPlayer()
+    if player ~= nil then
+        return true
+    end
+    local indirectPlayer = ____exports.getPlayerFromTear(nil, damageSource)
+    return indirectPlayer ~= nil
+end
 --- Helper function for detecting when a player is Eden or Tainted Eden. Useful for situations where
 -- you want to know if the starting stats were randomized, for example.
 function ____exports.isEden(self, player)
@@ -684,9 +719,9 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
         itemPool:RemoveCollectible(collectibleType)
     end
     repeat
-        local ____switch113 = activeSlot
-        local ____cond113 = ____switch113 == ActiveSlot.PRIMARY
-        if ____cond113 then
+        local ____switch122 = activeSlot
+        local ____cond122 = ____switch122 == ActiveSlot.PRIMARY
+        if ____cond122 then
             do
                 if primaryCollectibleType ~= CollectibleType.NULL then
                     player:RemoveCollectible(primaryCollectibleType)
@@ -695,8 +730,8 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
                 break
             end
         end
-        ____cond113 = ____cond113 or ____switch113 == ActiveSlot.SECONDARY
-        if ____cond113 then
+        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.SECONDARY
+        if ____cond122 then
             do
                 if primaryCollectibleType ~= CollectibleType.NULL then
                     player:RemoveCollectible(primaryCollectibleType)
@@ -711,16 +746,16 @@ function ____exports.setActiveItem(self, player, collectibleType, activeSlot, ch
                 break
             end
         end
-        ____cond113 = ____cond113 or ____switch113 == ActiveSlot.POCKET
-        if ____cond113 then
+        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.POCKET
+        if ____cond122 then
             do
                 player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
                 player:SetActiveCharge(charge, activeSlot)
                 break
             end
         end
-        ____cond113 = ____cond113 or ____switch113 == ActiveSlot.POCKET_SINGLE_USE
-        if ____cond113 then
+        ____cond122 = ____cond122 or ____switch122 == ActiveSlot.POCKET_SINGLE_USE
+        if ____cond122 then
             do
                 player:SetPocketActiveItem(collectibleType, activeSlot, keepInPools)
                 break

package/functions/playerHealth.d.ts

@@ -12,6 +12,8 @@ export declare function addPlayerHealthType(player: EntityPlayer, healthType: He
  */
 export declare function getPlayerHealth(player: EntityPlayer): PlayerHealth;
 export declare function getPlayerHealthType(player: EntityPlayer, healthType: HealthType): int;
+export declare function playerConvertBlackHeartsToSoulHearts(player: EntityPlayer): void;
+export declare function playerConvertSoulHeartsToBlackHearts(player: EntityPlayer): void;
 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