isaacscript-common 7.0.0 → 7.2.0

package/src/functions/bitSet128.ts

@@ -0,0 +1,96 @@
+import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
+import { isTable } from "./types";
+
+export type SerializedBitSet128 = LuaMap<string, unknown> & {
+  readonly __serializedBitSet128Brand: symbol;
+};
+
+const OBJECT_NAME = "BitSet128";
+const KEYS = ["l", "h"];
+
+/** Helper function to copy a `BitSet128` Isaac API class. */
+export function copyBitSet128(bitSet128: BitSet128): BitSet128 {
+  if (!isBitSet128(bitSet128)) {
+    error(
+      `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  const lowBits = bitSet128.l;
+  const highBits = bitSet128.h;
+
+  return BitSet128(lowBits, highBits);
+}
+
+/**
+ * Helper function to convert a `SerializedBitSet128` object to a normal `BitSet128` object. (This
+ * is used by the save data manager when reading data from the "save#.dat" file.)
+ */
+export function deserializeBitSet128(
+  bitSet128: SerializedBitSet128,
+): BitSet128 {
+  if (!isTable(bitSet128)) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+    );
+  }
+
+  const [l, h] = getNumbersFromTable(
+    bitSet128 as LuaMap<string, unknown>,
+    OBJECT_NAME,
+    ...KEYS,
+  );
+
+  if (l === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: l`,
+    );
+  }
+  if (h === undefined) {
+    error(
+      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: h`,
+    );
+  }
+
+  return BitSet128(l, h);
+}
+
+/** Helper function to check if something is an instantiated `BitSet128` object. */
+export function isBitSet128(object: unknown): object is BitSet128 {
+  return isIsaacAPIClassOfType(object, OBJECT_NAME);
+}
+
+/**
+ * Used to determine is the given table is a serialized `BitSet128` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export function isSerializedBitSet128(
+  object: unknown,
+): object is SerializedBitSet128 {
+  if (!isTable(object)) {
+    return false;
+  }
+
+  return (
+    tableHasKeys(object, ...KEYS) && object.has(SerializationBrand.BIT_SET_128)
+  );
+}
+
+/**
+ * Helper function to convert a `BitSet128` object to a `SerializedBitSet128` object. (This is used
+ * by the save data manager when writing data from the "save#.dat" file.)
+ */
+export function serializeBitSet128(bitSet128: BitSet128): SerializedBitSet128 {
+  if (!isBitSet128(bitSet128)) {
+    error(
+      `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+    );
+  }
+
+  const bitSet128Table = new LuaMap<string, unknown>();
+  copyValuesToTable(bitSet128, KEYS, bitSet128Table);
+  bitSet128Table.set(SerializationBrand.BIT_SET_128, "");
+  return bitSet128Table as SerializedBitSet128;
+}

package/src/functions/cacheFlag.ts

@@ -1,5 +1,62 @@
-import { CacheFlag } from "isaac-typescript-definitions";
+import { CacheFlag, CollectibleType } from "isaac-typescript-definitions";
+import { itemConfig } from "../core/cachedClasses";
 import { DEFAULT_PLAYER_STAT_MAP } from "../maps/defaultPlayerStatMap";
+import { getCollectibleArray } from "./collectibleSet";
+import { getEnumValues } from "./enums";
+import { hasFlag } from "./flag";
+import { copySet, getSortedSetValues } from "./set";
+import { repeat } from "./utils";
+
+const CACHE_FLAG_TO_COLLECTIBLES_MAP = new Map<
+  CacheFlag,
+  Set<CollectibleType>
+>();
+
+function initCacheFlagMap() {
+  for (const cacheFlag of getEnumValues(CacheFlag)) {
+    const collectiblesSet = new Set<CollectibleType>();
+
+    for (const collectibleType of getCollectibleArray()) {
+      if (collectibleHasCacheFlag(collectibleType, cacheFlag)) {
+        collectiblesSet.add(collectibleType);
+      }
+    }
+
+    CACHE_FLAG_TO_COLLECTIBLES_MAP.set(cacheFlag, collectiblesSet);
+  }
+}
+
+export function collectibleHasCacheFlag(
+  collectibleType: CollectibleType,
+  cacheFlag: CacheFlag,
+): boolean {
+  const itemConfigItem = itemConfig.GetCollectible(collectibleType);
+  if (itemConfigItem === undefined) {
+    return false;
+  }
+
+  return hasFlag(itemConfigItem.CacheFlags, cacheFlag);
+}
+
+/**
+ * Returns a set containing every collectible type with the given cache flag, including modded
+ * collectibles.
+ */
+export function getCollectiblesForCacheFlag(
+  cacheFlag: CacheFlag,
+): Set<CollectibleType> {
+  // Lazy initialize the map.
+  if (CACHE_FLAG_TO_COLLECTIBLES_MAP.size === 0) {
+    initCacheFlagMap();
+  }
+
+  const collectiblesSet = CACHE_FLAG_TO_COLLECTIBLES_MAP.get(cacheFlag);
+  if (collectiblesSet === undefined) {
+    return new Set();
+  }
+
+  return copySet(collectiblesSet);
+}
 
 /**
  * Returns the starting stat that Isaac (the default character) starts with. For example, if you
@@ -10,3 +67,35 @@ import { DEFAULT_PLAYER_STAT_MAP } from "../maps/defaultPlayerStatMap";
 export function getDefaultPlayerStat(cacheFlag: CacheFlag): number | undefined {
   return DEFAULT_PLAYER_STAT_MAP.get(cacheFlag);
 }
+
+/**
+ * Returns an array containing every collectible type that the player has that matches the provided
+ * CacheFlag.
+ *
+ * For example, if the cache flag is `CacheFlag.FLYING`, and the player has one Lord of the Pit and
+ * two Dead Doves, then this function would return:
+ *
+ * ```ts
+ * [
+ *   CollectibleType.LORD_OF_THE_PIT,
+ *   CollectibleType.DEAD_DOVE,
+ *   CollectibleType.DEAD_DOVE,
+ * ]
+ * ```
+ */
+export function getPlayerCollectiblesForCacheFlag(
+  player: EntityPlayer,
+  cacheFlag: CacheFlag,
+): CollectibleType[] {
+  const collectiblesForCacheFlag = getCollectiblesForCacheFlag(cacheFlag);
+
+  const playerCollectibles: CollectibleType[] = [];
+  for (const collectibleType of getSortedSetValues(collectiblesForCacheFlag)) {
+    const numCollectibles = player.GetCollectibleNum(collectibleType);
+    repeat(numCollectibles, () => {
+      playerCollectibles.push(collectibleType);
+    });
+  }
+
+  return playerCollectibles;
+}

package/src/functions/collectibles.ts

@@ -614,8 +614,8 @@ export function setCollectibleSprite(
 }
 
 /**
- * Helper function to change the collectible on a pedestal. Simply updating the `SubType` property
- * is not sufficient because the sprite will not change.
+ * Helper function to change the collectible on a pedestal. Simply updating the `SubType` field is
+ * not sufficient because the sprite will not change.
  */
 export function setCollectibleSubType(
   collectible: EntityPickup,

package/src/functions/color.ts

@@ -9,8 +9,8 @@ export type SerializedColor = LuaMap<string, unknown> & {
   readonly __serializedColorBrand: symbol;
 };
 
-const KEYS = ["R", "G", "B", "A", "RO", "GO", "BO"];
 const OBJECT_NAME = "Color";
+const KEYS = ["R", "G", "B", "A", "RO", "GO", "BO"];
 
 export function colorEquals(color1: Color, color2: Color): boolean {
   return isaacAPIClassEquals(color1, color2, KEYS);
@@ -91,7 +91,7 @@ export function getRandomColor(
   return Color(r, g, b, alpha);
 }
 
-/** Helper function to check if something is an instantiated Color object. */
+/** Helper function to check if something is an instantiated `Color` object. */
 export function isColor(object: unknown): object is Color {
   return isIsaacAPIClassOfType(object, OBJECT_NAME);
 }
@@ -107,6 +107,7 @@ export function isSerializedColor(object: unknown): object is SerializedColor {
 
   return tableHasKeys(object, ...KEYS) && object.has(SerializationBrand.COLOR);
 }
+
 /**
  * Helper function to convert a `Color` object to a `SerializedColor` object. (This is used by the
  * save data manager when writing data from the "save#.dat" file.)

package/src/functions/deepCopy.ts

@@ -42,6 +42,7 @@ const COPYABLE_ISAAC_API_CLASS_TYPES_SET = new Set<string>(
  * - TSTL `Set`
  * - TSTL classes
  * - `DefaultMap`
+ * - Isaac `BitSet128` objects
  * - Isaac `Color` objects
  * - Isaac `KColor` objects
  * - Isaac `RNG` objects

package/src/functions/familiars.ts

@@ -11,8 +11,8 @@ import { getFamiliars } from "./entitiesSpecific";
  * specify an incorrect RNG object. (The vanilla method is bugged in that it does not increment the
  * RNG object; see the documentation of the method for more details.)
  *
- * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
- * to `CacheFlag.FAMILIARS`).
+ * This function is meant to be called in the `EVALUATE_CACHE` callback (when the cache flag is
+ * equal to `CacheFlag.FAMILIARS`).
  *
  * Note that this function is only meant to be used in special circumstances where the familiar
  * count is completely custom and does not correspond to the amount of collectibles. For the general
@@ -56,8 +56,8 @@ export function checkFamiliar(
  * Use this helper function instead of invoking the `EntityPlayer.CheckFamiliar` method directly so
  * that the target count is handled automatically.
  *
- * This function is meant to be called in the EvaluateCache callback (when the cache flag is equal
- * to `CacheFlag.FAMILIARS`).
+ * This function is meant to be called in the `EVALUATE_CACHE` callback (when the cache flag is
+ * equal to `CacheFlag.FAMILIARS`).
  *
  * Use this function when the amount of familiars should be equal to the amount of associated
  * collectibles that the player has (plus any extras from having used Box of Friends or Monster

package/src/functions/flag.ts

@@ -42,7 +42,7 @@ export function addFlag<T extends BitFlag | BitFlag128>(
  * Helper function for casting a flag enum value to a `BitFlags` object.
  *
  * This is useful because the compiler will prevent you from assigning a specific flag to a
- * `BitFlags` property. (It does this to ensure type safety, since `BitFlags` can represent a zero
+ * `BitFlags` field. (It does this to ensure type safety, since `BitFlags` can represent a zero
  * value or a composition of N flags.)
  *
  * For example:

package/src/functions/flying.ts

@@ -5,7 +5,7 @@ import {
   PlayerType,
   TrinketType,
 } from "isaac-typescript-definitions";
-import { getCollectiblesForCacheFlag } from "./collectibleCacheFlag";
+import { getCollectiblesForCacheFlag } from "./cacheFlag";
 import { copySet, deleteSetsFromSet } from "./set";
 
 const FLYING_CHARACTERS: ReadonlySet<PlayerType> = new Set([

package/src/functions/index.ts

@@ -3,6 +3,7 @@
 export * from "./ambush";
 export * from "./array";
 export * from "./benchmark";
+export * from "./bitSet128";
 export * from "./bitwise";
 export * from "./bombs";
 export * from "./bosses";
@@ -12,7 +13,6 @@ export * from "./challenges";
 export * from "./characters";
 export * from "./charge";
 export * from "./chargeBar";
-export * from "./collectibleCacheFlag";
 export * from "./collectibles";
 export * from "./collectibleSet";
 export * from "./collectibleTag";
@@ -63,6 +63,7 @@ export * from "./playerDataStructures";
 export * from "./playerHealth";
 export * from "./playerIndex";
 export * from "./players";
+export * from "./playerStats";
 export * from "./pocketItems";
 export * from "./positionVelocity";
 export * from "./pressurePlate";

package/src/functions/indexTypeDoc.ts

@@ -3,6 +3,7 @@
 export * as Ambush from "./ambush";
 export * as Array from "./array";
 export * as Benchmark from "./benchmark";
+export * as BitSet128 from "./bitSet128";
 export * as Bitwise from "./bitwise";
 export * as Bombs from "./bombs";
 export * as Bosses from "./bosses";
@@ -12,7 +13,6 @@ export * as Challenges from "./challenges";
 export * as Characters from "./characters";
 export * as Charge from "./charge";
 export * as ChargeBar from "./chargeBar";
-export * as CollectibleCacheFlag from "./collectibleCacheFlag";
 export * as Collectibles from "./collectibles";
 export * as CollectibleSet from "./collectibleSet";
 export * as CollectibleTag from "./collectibleTag";
@@ -63,6 +63,7 @@ export * as PlayerDataStructures from "./playerDataStructures";
 export * as PlayerHealth from "./playerHealth";
 export * as PlayerIndex from "./playerIndex";
 export * as Players from "./players";
+export * as PlayerStats from "./playerStats";
 export * as PocketItems from "./pocketItems";
 export * as PositionVelocity from "./positionVelocity";
 export * as PressurePlate from "./pressurePlate";

package/src/functions/input.ts

@@ -4,6 +4,7 @@ import {
   ControllerIndex,
   Keyboard,
 } from "isaac-typescript-definitions";
+import { KEYBOARD_TO_STRING } from "../maps/keyboardToString";
 import { getEnumValues } from "./enums";
 import { copySet } from "./set";
 import { trimPrefix } from "./string";
@@ -133,6 +134,18 @@ export function isShootActionTriggeredOnAnyInput(): boolean {
   );
 }
 
-export function keyboardToString(keyboard: Keyboard): string {
-  return Keyboard[keyboard] ?? "unknown";
+/**
+ * Helper function to get the string that would be typed if someone pressed the corresponding key.
+ */
+export function keyboardToString(
+  keyboard: Keyboard,
+  uppercase: boolean,
+): string | undefined {
+  const tuple = KEYBOARD_TO_STRING.get(keyboard);
+  if (tuple === undefined) {
+    return undefined;
+  }
+
+  const [lowercaseCharacter, uppercaseCharacter] = tuple;
+  return uppercase ? uppercaseCharacter : lowercaseCharacter;
 }

package/src/functions/jsonRoom.ts

@@ -22,7 +22,7 @@ export function getJSONRoomDoorSlotFlags(
   const roomShapeNumber = tonumber(roomShapeString);
   if (roomShapeNumber === undefined) {
     error(
-      `Failed to parse the "shape" property of a JSON room: ${roomShapeString}`,
+      `Failed to parse the "shape" field of a JSON room: ${roomShapeString}`,
     );
   }
   const roomShape = roomShapeNumber as RoomShape;
@@ -33,7 +33,7 @@ export function getJSONRoomDoorSlotFlags(
     const existsString = door.$.exists;
     if (existsString !== "True" && existsString !== "False") {
       error(
-        `Failed to parse the "exists" property of a JSON room door: ${existsString}`,
+        `Failed to parse the "exists" field of a JSON room door: ${existsString}`,
       );
     }
 
@@ -44,13 +44,13 @@ export function getJSONRoomDoorSlotFlags(
     const xString = door.$.x;
     const x = tonumber(xString);
     if (x === undefined) {
-      error(`Failed to parse the "x" property of a JSON room door: ${xString}`);
+      error(`Failed to parse the "x" field of a JSON room door: ${xString}`);
     }
 
     const yString = door.$.y;
     const y = tonumber(yString);
     if (y === undefined) {
-      error(`Failed to parse the "y" property of a JSON room door: ${yString}`);
+      error(`Failed to parse the "y" field of a JSON room door: ${yString}`);
     }
 
     const doorSlot = getRoomShapeDoorSlot(roomShape, x, y);

package/src/functions/kColor.ts

@@ -9,8 +9,8 @@ export type SerializedKColor = LuaMap<string, unknown> & {
   readonly __serializedKColorBrand: symbol;
 };
 
-const KEYS = ["Red", "Green", "Blue", "Alpha"];
 const OBJECT_NAME = "KColor";
+const KEYS = ["Red", "Green", "Blue", "Alpha"];
 
 /** Helper function to copy a `KColor` Isaac API class. */
 export function copyKColor(kColor: KColor): KColor {
@@ -84,7 +84,7 @@ export function getRandomKColor(
   return KColor(r, g, b, alpha);
 }
 
-/** Helper function to check if something is an instantiated KColor object. */
+/** Helper function to check if something is an instantiated `KColor` object. */
 export function isKColor(object: unknown): object is KColor {
   return isIsaacAPIClassOfType(object, OBJECT_NAME);
 }

package/src/functions/log.ts

@@ -455,7 +455,7 @@ export function logUseFlags(
  * the Isaac API).
  */
 export function logUserdata(this: void, userdata: unknown): void {
-  if (isUserdata(userdata)) {
+  if (!isUserdata(userdata)) {
     log("Userdata: [not userdata]");
     return;
   }

package/src/functions/npcs.ts

@@ -108,8 +108,8 @@ export function isAliveExceptionNPC(npc: EntityNPC): boolean {
  * that is spawned when the boss does the multi-stomp attack.
  *
  * When this attack occurs, four extra copies of Daddy Long Legs will be spawned with the same
- * entity type, variant, and sub-type. The `Entity.Parent` property will be undefined in this case,
- * so the way to tell them apart is to check for a non-undefined `Entity.SpawnerEntity` property.
+ * entity type, variant, and sub-type. The `Entity.Parent` field will be undefined in this case, so
+ * the way to tell them apart is to check for a non-undefined `Entity.SpawnerEntity` field.
  */
 export function isDaddyLongLegsChildStompEntity(npc: EntityNPC): boolean {
   return (

package/src/functions/playerIndex.ts

@@ -198,7 +198,7 @@ export function getSubPlayerParent(
 
 /**
  * Helper function to detect if a particular player is a "child" player, meaning that they have a
- * non-undefined `EntityPlayer.Parent` property. (For example, the Strawman Keeper.)
+ * non-undefined `EntityPlayer.Parent` field. (For example, the Strawman Keeper.)
  */
 export function isChildPlayer(player: EntityPlayer): boolean {
   return player.Parent !== undefined;

package/src/functions/playerStats.ts

@@ -0,0 +1,25 @@
+import { StatType } from "../enums/StatType";
+import { StatTypeType } from "../interfaces/StatTypeType";
+
+/** Helper function to get the stat for a player corresponding to the `StatType`. */
+export function getPlayerStat<T extends StatType>(
+  player: EntityPlayer,
+  statType: T,
+): StatTypeType[T] {
+  // We can't use a switch statement here because control-flow based type analysis does not apply to
+  // generic type parameters.
+  return {
+    [StatType.DAMAGE]: player.Damage, // 1 << 0
+    [StatType.FIRE_DELAY]: player.MaxFireDelay, // 1 << 1
+    [StatType.SHOT_SPEED]: player.ShotSpeed, // 1 << 2
+    [StatType.TEAR_HEIGHT]: player.TearHeight, // 1 << 3
+    [StatType.TEAR_RANGE]: player.TearRange, // 1 << 3
+    [StatType.TEAR_FALLING_ACCELERATION]: player.TearFallingAcceleration, // 1 << 3
+    [StatType.TEAR_FALLING_SPEED]: player.TearFallingSpeed, // 1 << 3
+    [StatType.MOVE_SPEED]: player.MoveSpeed, // 1 << 4
+    [StatType.TEAR_FLAG]: player.TearFlags, // 1 << 5
+    [StatType.TEAR_COLOR]: player.TearColor, // 1 << 6
+    [StatType.FLYING]: player.CanFly, // 1 << 7
+    [StatType.LUCK]: player.Luck, // 1 << 10
+  }[statType];
+}

package/src/functions/players.ts

@@ -48,7 +48,7 @@ export function addCollectibleCostume(
 
 /**
  * Helper function to add a stat to a player based on the `CacheFlag` provided. Call this function
- * from the EvaluateCache callback.
+ * from the `EVALUATE_CACHE` callback.
  *
  * Note that for `CacheFlag.FIRE_DELAY`, the "amount" argument will be interpreted as the tear stat
  * to add (and not the amount to mutate `EntityPlayer.MaxFireDelay` by).

package/src/functions/rng.ts

@@ -15,8 +15,8 @@ export type SerializedRNG = LuaMap<string, unknown> & {
  */
 const RECOMMENDED_SHIFT_IDX = 35;
 
-const KEYS = ["seed"];
 const OBJECT_NAME = "RNG";
+const KEYS = ["seed"];
 
 /** Helper function to copy an `RNG` Isaac API class. */
 export function copyRNG(rng: RNG): RNG {
@@ -60,7 +60,7 @@ export function getRandomSeed(): Seed {
   return safeRandomNumber as Seed;
 }
 
-/** Helper function to check if something is an instantiated RNG object. */
+/** Helper function to check if something is an instantiated `RNG` object. */
 export function isRNG(object: unknown): object is RNG {
   return isIsaacAPIClassOfType(object, OBJECT_NAME);
 }

package/src/functions/rockAlt.ts

@@ -41,6 +41,13 @@ const ROCK_ALT_CHANCES = {
 } as const;
 
 const COIN_VELOCITY_MULTIPLIER = 2;
+
+/** Matches the vanilla value, according to Fly's decompilation. */
+const FIND_FREE_INITIAL_STEP = 70;
+
+/** Matches the vanilla value, according to Fly's decompilation. */
+const FART_RADIUS = DISTANCE_OF_GRID_TILE * 3;
+
 const POLYP_PROJECTILE_SPEED = 10;
 const POLYP_NUM_PROJECTILES = 6;
 
@@ -128,6 +135,8 @@ export function spawnRockAltReward(
 }
 
 function spawnRockAltRewardUrn(position: Vector, rng: RNG): boolean {
+  const room = game.GetRoom();
+
   const chance = getRandom(rng);
   let totalChance = 0;
 
@@ -171,11 +180,11 @@ function spawnRockAltRewardUrn(position: Vector, rng: RNG): boolean {
   // Since the detrimental effect is the final option, we don't need to check the chance.
   const numEnemiesChance = getRandom(rng);
   const numEnemies = numEnemiesChance < 0.5 ? 1 : 2;
-  const length = DISTANCE_OF_GRID_TILE * 3;
   repeat(numEnemies, () => {
-    const randomVector = getRandomVector(rng);
-    const offset = randomVector.mul(length);
-    const targetPos = position.add(offset);
+    const targetPos = room.FindFreePickupSpawnPosition(
+      position,
+      FIND_FREE_INITIAL_STEP,
+    );
     EntityNPC.ThrowSpider(position, undefined, targetPos, false, 0);
   });
   return true;
@@ -253,7 +262,8 @@ function spawnRockAltRewardMushroom(position: Vector, rng: RNG): boolean {
   }
 
   // Since the detrimental effect is the final option, we don't need to check the chance.
-  spawnEffectWithSeed(EffectVariant.FART, 0, position, rng);
+  game.Fart(position);
+  game.ButterBeanFart(position, FART_RADIUS, undefined);
   return true;
 }
 
@@ -383,6 +393,8 @@ function spawnRockAltRewardPolyp(position: Vector, rng: RNG): boolean {
 }
 
 function spawnRockAltRewardBucketDownpour(position: Vector, rng: RNG): boolean {
+  const room = game.GetRoom();
+
   const chance = getRandom(rng);
   let totalChance = 0;
 
@@ -430,11 +442,12 @@ function spawnRockAltRewardBucketDownpour(position: Vector, rng: RNG): boolean {
 
   const numEnemiesChance = getRandom(rng);
   const numEnemies = numEnemiesChance < 0.5 ? 1 : 2;
-  const jumpDistance = DISTANCE_OF_GRID_TILE * 3;
   repeat(numEnemies, () => {
-    const randomVector = getRandomVector(rng);
-    const offset = randomVector.mul(jumpDistance);
-    const targetPos = position.add(offset);
+    const targetPos = room.FindFreePickupSpawnPosition(
+      position,
+      FIND_FREE_INITIAL_STEP,
+    );
+
     // If the room has water, Spiders will automatically be replaced with Striders.
     const spider = EntityNPC.ThrowSpider(
       position,
@@ -455,6 +468,8 @@ function spawnRockAltRewardBucketDownpour(position: Vector, rng: RNG): boolean {
 }
 
 function spawnRockAltRewardBucketDross(position: Vector, rng: RNG): boolean {
+  const room = game.GetRoom();
+
   const chance = getRandom(rng);
   let totalChance = 0;
 
@@ -502,11 +517,11 @@ function spawnRockAltRewardBucketDross(position: Vector, rng: RNG): boolean {
 
   const numEnemiesChance = getRandom(rng);
   const numEnemies = numEnemiesChance < 0.5 ? 1 : 2;
-  const jumpDistance = DISTANCE_OF_GRID_TILE * 3;
   repeat(numEnemies, () => {
-    const randomVector = getRandomVector(rng);
-    const offset = randomVector.mul(jumpDistance);
-    const targetPos = position.add(offset);
+    const targetPos = room.FindFreePickupSpawnPosition(
+      position,
+      FIND_FREE_INITIAL_STEP,
+    );
     const spider = EntityNPC.ThrowSpider(
       position,
       undefined,

package/src/functions/roomTransition.ts

@@ -31,7 +31,7 @@ export function reloadRoom(): void {
  * arguments.
  *
  * Use this function instead of invoking the `Game.StartRoomTransition` method directly so that:
- * - you do not forget to set `Level.LeaveDoor` property
+ * - you do not forget to set the `Level.LeaveDoor` field
  * - to prevent crashing on invalid room grid indexes
  * - to automatically handle Curse of the Maze
  *

package/src/functions/rooms.ts

@@ -50,7 +50,7 @@ import { erange, irange } from "./utils";
 /**
  * Helper function for quickly switching to a new room without playing a particular animation. Use
  * this helper function over invoking the `Game.ChangeRoom` method directly to ensure that you do
- * not forget to set the `LeaveDoor` property and to prevent crashing on invalid room grid indexes.
+ * not forget to set the `LeaveDoor` field and to prevent crashing on invalid room grid indexes.
  */
 export function changeRoom(roomGridIndex: int): void {
   const level = game.GetLevel();
@@ -498,6 +498,7 @@ export function roomUpdateSafe(): void {
 /** Helper function to set the backdrop of the current room. */
 export function setBackdrop(backdropType: BackdropType): void {
   game.ShowHallucination(0, backdropType);
+  sfxManager.Stop(SoundEffect.DEATH_CARD);
 }
 
 /**

package/src/functions/sprites.ts

@@ -34,9 +34,9 @@ export function clearSprite(sprite: Sprite, ...layerIDs: int[]): void {
  *
  * Note that this function is bugged with the Stop Watch or the Broken Watch, since using the
  * `Sprite.SetFrame` method will reset the internal accumulator used to slow down the playback speed
- * of the animation. (The `PlaybackSpeed` property of the sprite is not used.) Thus, it is only safe
- * to use this function on animations that are not slowed down by Stop Watch or Broken Watch, such
- * as player animations.
+ * of the animation. (The `PlaybackSpeed` field of the sprite is not used.) Thus, it is only safe to
+ * use this function on animations that are not slowed down by Stop Watch or Broken Watch, such as
+ * player animations.
  */
 export function getLastFrameOfAnimation(
   sprite: Sprite,