isaacscript-common 6.20.1 → 6.22.0

package/src/functions/logEntities.ts

@@ -0,0 +1,276 @@
+import {
+  EffectVariant,
+  EntityType,
+  GridEntityType,
+} from "isaac-typescript-definitions";
+import { getEntities, getEntityID } from "./entities";
+import { getGridEntities, getGridEntityID } from "./gridEntities";
+import { log } from "./log";
+
+const IGNORE_EFFECT_VARIANTS: ReadonlySet<EffectVariant> = new Set([
+  EffectVariant.BLOOD_EXPLOSION, // 2
+  EffectVariant.BLOOD_PARTICLE, // 5
+  EffectVariant.TINY_BUG, // 21
+  EffectVariant.TINY_FLY, // 33
+  EffectVariant.WATER_DROPLET, // 41
+  EffectVariant.WALL_BUG, // 68
+  EffectVariant.FALLING_EMBER, // 87
+  EffectVariant.LIGHT, // 121
+  EffectVariant.TADPOLE, // 158
+]);
+
+/** Helper function for printing out every entity (or filtered entity) in the current room. */
+export function logAllEntities(
+  this: void,
+  includeBackgroundEffects: boolean,
+  entityTypeFilter?: EntityType,
+): void {
+  let msg = "Entities in the room";
+  if (entityTypeFilter !== undefined) {
+    msg += ` (filtered to entity type ${entityTypeFilter})`;
+  } else if (!includeBackgroundEffects) {
+    msg += " (not including background effects)";
+  }
+  msg += ":\n";
+
+  const entities = getEntities();
+  let numMatchedEntities = 0;
+  entities.forEach((entity, i) => {
+    // If a filter was specified, exclude all entities outside of the filter.
+    if (entityTypeFilter !== undefined && entity.Type !== entityTypeFilter) {
+      return;
+    }
+
+    const effect = entity.ToEffect();
+    if (
+      !includeBackgroundEffects &&
+      effect !== undefined &&
+      IGNORE_EFFECT_VARIANTS.has(effect.Variant)
+    ) {
+      return;
+    }
+
+    msg += getEntityLogLine(entity, i + 1);
+    numMatchedEntities++;
+  });
+
+  if (numMatchedEntities === 0) {
+    msg += "(no entities matched)\n";
+  } else {
+    msg += `(${numMatchedEntities} total ${
+      numMatchedEntities === 1 ? "entity" : "entities"
+    })\n`;
+  }
+
+  log(msg);
+}
+
+/**
+ * Helper function for printing out every grid entity (or filtered grid entity) in the current room.
+ */
+export function logAllGridEntities(
+  this: void,
+  includeWalls: boolean,
+  gridEntityTypeFilter?: GridEntityType,
+): void {
+  let msg = "Grid entities in the room";
+  if (gridEntityTypeFilter !== undefined) {
+    msg += ` (filtered to grid entity type ${gridEntityTypeFilter})`;
+  } else if (!includeWalls) {
+    msg += " (not including walls)";
+  }
+  msg += ":\n";
+
+  const gridEntities = getGridEntities();
+  let numMatchedEntities = 0;
+  gridEntities.forEach((gridEntity) => {
+    const gridEntityIndex = gridEntity.GetGridIndex();
+    const gridEntityType = gridEntity.GetType();
+
+    // If a filter was specified, exclude all entities outside of the filter.
+    if (
+      gridEntityTypeFilter !== undefined &&
+      gridEntityType !== gridEntityTypeFilter
+    ) {
+      return;
+    }
+
+    if (
+      !includeWalls &&
+      gridEntityType === GridEntityType.WALL &&
+      gridEntityTypeFilter !== GridEntityType.WALL
+    ) {
+      return;
+    }
+
+    msg += getGridEntityLogLine(gridEntity, gridEntityIndex);
+
+    numMatchedEntities++;
+  });
+
+  if (numMatchedEntities === 0) {
+    msg += "(no grid entities matched)\n";
+  } else {
+    msg += `(${numMatchedEntities} total grid ${
+      numMatchedEntities === 1 ? "entity" : "entities"
+    })\n`;
+  }
+
+  log(msg);
+}
+
+/** Helper function for logging an array of specific entities. */
+export function logEntities(this: void, entities: Entity[]): void {
+  for (const entity of entities) {
+    logEntity(entity);
+  }
+}
+
+/** Helper function to log information about a specific entity. */
+export function logEntity(this: void, entity: Entity): void {
+  const msg = getEntityLogLine(entity);
+  log(msg);
+}
+
+function getEntityLogLine(entity: Entity, num?: int): string {
+  let msg = num === undefined ? "" : `${num}) `;
+
+  msg += getEntityID(entity);
+
+  const bomb = entity.ToBomb();
+  if (bomb !== undefined) {
+    msg += " (bomb)";
+  }
+
+  const effect = entity.ToEffect();
+  if (effect !== undefined) {
+    msg += ` (effect) (State: ${effect.State})`;
+  }
+
+  const familiar = entity.ToFamiliar();
+  if (familiar !== undefined) {
+    msg += ` (familiar) (State: ${familiar.State})`;
+  }
+
+  const knife = entity.ToKnife();
+  if (knife !== undefined) {
+    msg += " (knife)";
+  }
+
+  const laser = entity.ToLaser();
+  if (laser !== undefined) {
+    msg += " (laser)";
+  }
+
+  const npc = entity.ToNPC();
+  if (npc !== undefined) {
+    msg += ` (NPC) (State: ${npc.State})`;
+  }
+
+  const pickup = entity.ToPickup();
+  if (pickup !== undefined) {
+    msg += ` (pickup) (State: ${pickup.State})`;
+  }
+
+  const player = entity.ToPlayer();
+  if (player !== undefined) {
+    msg += " (player)";
+  }
+
+  const projectile = entity.ToProjectile();
+  if (projectile !== undefined) {
+    msg += " (projectile)";
+  }
+
+  const tear = entity.ToTear();
+  if (tear !== undefined) {
+    msg += " (tear)";
+  }
+
+  msg += "\n";
+  msg += `  - Index: ${entity.Index}\n`;
+  msg += `  - InitSeed: ${entity.InitSeed}\n`;
+  msg += `  - DropSeed: ${entity.DropSeed}\n`;
+  msg += `  - Position: (${entity.Position.X}, ${entity.Position.Y})\n`;
+  msg += `  - Velocity: (${entity.Velocity.X}, ${entity.Velocity.Y})\n`;
+  msg += `  - HP: ${entity.HitPoints} / ${entity.MaxHitPoints}\n`;
+  msg += `  - Parent: ${entity.Parent}\n`;
+  msg += `  - Child: ${entity.Child}\n`;
+  msg += `  - SpawnerEntity: ${entity.SpawnerEntity}\n`;
+  msg += `  - SpawnerType / SpawnerVariant: ${entity.SpawnerType}.${entity.SpawnerVariant}\n`;
+  if (npc !== undefined) {
+    msg += `  - CanShutDoors: ${npc.CanShutDoors}\n`;
+  }
+
+  return msg;
+}
+
+/** Helper function for logging an array of specific grid entities. */
+export function logGridEntities(this: void, gridEntities: GridEntity[]): void {
+  for (const gridEntity of gridEntities) {
+    logGridEntity(gridEntity);
+  }
+}
+
+/** Helper function for log information about a specific grid entity. */
+export function logGridEntity(this: void, gridEntity: GridEntity): void {
+  const msg = getGridEntityLogLine(gridEntity);
+  log(msg);
+}
+
+function getGridEntityLogLine(gridEntity: GridEntity, num?: int): string {
+  const gridEntityDesc = gridEntity.GetSaveState();
+
+  let msg = num === undefined ? "" : `${num}) `;
+
+  msg += getGridEntityID(gridEntity);
+
+  const door = gridEntity.ToDoor();
+  if (door !== undefined) {
+    msg += " (door)";
+  }
+
+  const pit = gridEntity.ToPit();
+  if (pit !== undefined) {
+    msg += " (pit)";
+  }
+
+  const poop = gridEntity.ToPoop();
+  if (poop !== undefined) {
+    msg += " (poop)";
+  }
+
+  const pressurePlate = gridEntity.ToPressurePlate();
+  if (pressurePlate !== undefined) {
+    msg += " (pressurePlate)";
+  }
+
+  const rock = gridEntity.ToRock();
+  if (rock !== undefined) {
+    msg += " (rock)";
+  }
+
+  const spikes = gridEntity.ToSpikes();
+  if (spikes !== undefined) {
+    msg += " (spikes)";
+  }
+
+  const tnt = gridEntity.ToTNT();
+  if (tnt !== undefined) {
+    msg += " (TNT)";
+  }
+
+  msg += `  - State: ${gridEntity.State}\n`;
+  msg += `  - VarData: ${gridEntity.VarData}\n`;
+  msg += `  - Position: (${gridEntity.Position.X}, ${gridEntity.Position.Y})\n`;
+  msg += `  - SpawnSeed: ${gridEntityDesc.SpawnSeed}\n`;
+  msg += `  - VariableSeed: ${gridEntityDesc.VariableSeed})\n`;
+  if (door !== undefined) {
+    msg += `  - Slot: ${door.Slot}\n`;
+    msg += `  - Direction: ${door.Direction}\n`;
+    msg += `  - TargetRoomIndex: ${door.TargetRoomIndex}\n`;
+    msg += `  - TargetRoomType: ${door.TargetRoomType}\n`;
+  }
+
+  return msg;
+}

package/src/functions/rockAlt.ts

@@ -40,6 +40,7 @@ const ROCK_ALT_CHANCES = {
   COLLECTIBLE: 0.005,
 } as const;
 
+const COIN_VELOCITY_MULTIPLIER = 2;
 const POLYP_PROJECTILE_SPEED = 10;
 const POLYP_NUM_PROJECTILES = 6;
 
@@ -76,16 +77,17 @@ export function getRockAltType(): RockAltType {
  * trinket is still in the pool. Thus, it will always have a chance to spawn the respective trinket
  * (e.g. Swallowed Penny from urns).
  *
+ * When filled buckets are destroyed, 6 projectiles will always spawn in a random pattern (in
+ * addition to any other rewards that are spawned). This function does not account for this, so if
+ * you want to specifically emulate destroying a filled bucket, you have to account for the
+ * projectiles yourself.
+ *
  * The logic in this function is based on the rewards listed on the wiki:
  * https://bindingofisaacrebirth.fandom.com/wiki/Rocks
  *
  * @param position The place to spawn the reward.
  * @param rockAltType The type of reward to spawn. For example, `RockAltType.URN` will have a chance
  *                    at spawning coins and spiders.
- * @param variant Optional. The variant of the grid entity to emulate. Default is 0, which
- *                corresponds to a "normal" grid entity or an empty bucket. This only matters when
- *                spawning the reward for buckets. (Empty buckets have different rewards than full
- *                buckets.)
  * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
  *                  `RNG.Next` method will be called. Default is `getRandomSeed()`. Normally, you
  *                  should pass the `InitSeed` of the grid entity that was broken.
@@ -94,7 +96,6 @@ export function getRockAltType(): RockAltType {
 export function spawnRockAltReward(
   position: Vector,
   rockAltType: RockAltType,
-  variant = 0,
   seedOrRNG: Seed | RNG = getRandomSeed(),
 ): boolean {
   const rng = isRNG(seedOrRNG) ? seedOrRNG : newRNG(seedOrRNG);
@@ -116,8 +117,12 @@ export function spawnRockAltReward(
       return spawnRockAltRewardPolyp(position, rng);
     }
 
-    case RockAltType.BUCKET: {
-      return spawnRockAltRewardBucket(position, rng, variant);
+    case RockAltType.BUCKET_DOWNPOUR: {
+      return spawnRockAltRewardBucketDownpour(position, rng);
+    }
+
+    case RockAltType.BUCKET_DROSS: {
+      return spawnRockAltRewardBucketDross(position, rng);
     }
   }
 }
@@ -135,10 +140,9 @@ function spawnRockAltRewardUrn(position: Vector, rng: RNG): boolean {
   if (chance < totalChance) {
     const numCoinsChance = getRandom(rng);
     const numCoins = numCoinsChance < 0.5 ? 1 : 2;
-    const length = DISTANCE_OF_GRID_TILE;
     repeat(numCoins, () => {
       const randomVector = getRandomVector(rng);
-      const velocity = randomVector.mul(length);
+      const velocity = randomVector.mul(COIN_VELOCITY_MULTIPLIER);
       spawnCoinWithSeed(CoinSubType.NULL, position, rng, velocity);
     });
     return true;
@@ -165,10 +169,10 @@ function spawnRockAltRewardUrn(position: Vector, rng: RNG): boolean {
   }
 
   // Since the detrimental effect is the final option, we don't need to check the chance.
-  const numSpidersChance = getRandom(rng);
-  const numSpiders = numSpidersChance < 0.5 ? 1 : 2;
+  const numEnemiesChance = getRandom(rng);
+  const numEnemies = numEnemiesChance < 0.5 ? 1 : 2;
   const length = DISTANCE_OF_GRID_TILE * 3;
-  repeat(numSpiders, () => {
+  repeat(numEnemies, () => {
     const randomVector = getRandomVector(rng);
     const offset = randomVector.mul(length);
     const targetPos = position.add(offset);
@@ -378,11 +382,79 @@ function spawnRockAltRewardPolyp(position: Vector, rng: RNG): boolean {
   return true;
 }
 
-function spawnRockAltRewardBucket(
-  _position: Vector,
-  rng: RNG,
-  _variant: int,
-): boolean {
+function spawnRockAltRewardBucketDownpour(position: Vector, rng: RNG): boolean {
+  const chance = getRandom(rng);
+  let totalChance = 0;
+
+  totalChance += ROCK_ALT_CHANCES.NOTHING;
+  if (chance < totalChance) {
+    return false;
+  }
+
+  totalChance += ROCK_ALT_CHANCES.BASIC_DROP;
+  if (chance < totalChance) {
+    const numCoinsChance = getRandom(rng);
+    const numCoins = numCoinsChance < 0.5 ? 1 : 2;
+    repeat(numCoins, () => {
+      const randomVector = getRandomVector(rng);
+      const velocity = randomVector.mul(COIN_VELOCITY_MULTIPLIER);
+      spawnCoinWithSeed(CoinSubType.NULL, position, rng, velocity);
+    });
+    return true;
+  }
+
+  totalChance += ROCK_ALT_CHANCES.TRINKET;
+  if (chance < totalChance) {
+    spawnTrinketWithSeed(TrinketType.SWALLOWED_PENNY, position, rng);
+    return true;
+  }
+
+  totalChance += ROCK_ALT_CHANCES.COLLECTIBLE;
+  if (chance < totalChance) {
+    const stillInPools = isCollectibleInItemPool(
+      CollectibleType.LEECH,
+      ItemPoolType.TREASURE,
+    );
+    if (stillInPools) {
+      spawnCollectible(CollectibleType.LEECH, position, rng);
+      return true;
+    }
+
+    return false;
+  }
+
+  // Since the detrimental effect is the final option, we don't need to check the chance.
+  const enemiesChance = getRandom(rng);
+  const entityType =
+    enemiesChance < 0.5 ? EntityType.SPIDER : EntityType.SMALL_LEECH;
+
+  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);
+    // If the room has water, Spiders will automatically be replaced with Striders.
+    const spider = EntityNPC.ThrowSpider(
+      position,
+      undefined,
+      targetPos,
+      false,
+      0,
+    );
+
+    // There is no `ThrowLeech` function exposed in the API, so we can piggyback off of the
+    // `ThrowSpider` method.
+    if (entityType === EntityType.SMALL_LEECH && spider.Type !== entityType) {
+      spider.Morph(entityType, 0, 0, -1);
+    }
+  });
+
+  return true;
+}
+
+function spawnRockAltRewardBucketDross(position: Vector, rng: RNG): boolean {
   const chance = getRandom(rng);
   let totalChance = 0;
 
@@ -391,6 +463,62 @@ function spawnRockAltRewardBucket(
     return false;
   }
 
-  // TODO
-  return false;
+  totalChance += ROCK_ALT_CHANCES.BASIC_DROP;
+  if (chance < totalChance) {
+    const numCoinsChance = getRandom(rng);
+    const numCoins = numCoinsChance < 0.5 ? 1 : 2;
+    repeat(numCoins, () => {
+      const randomVector = getRandomVector(rng);
+      const velocity = randomVector.mul(COIN_VELOCITY_MULTIPLIER);
+      spawnCoinWithSeed(CoinSubType.NULL, position, rng, velocity);
+    });
+    return true;
+  }
+
+  totalChance += ROCK_ALT_CHANCES.TRINKET;
+  if (chance < totalChance) {
+    spawnTrinketWithSeed(TrinketType.BUTT_PENNY, position, rng);
+    return true;
+  }
+
+  totalChance += ROCK_ALT_CHANCES.COLLECTIBLE;
+  if (chance < totalChance) {
+    const stillInPools = isCollectibleInItemPool(
+      CollectibleType.POOP,
+      ItemPoolType.TREASURE,
+    );
+    if (stillInPools) {
+      spawnCollectible(CollectibleType.POOP, position, rng);
+      return true;
+    }
+
+    return false;
+  }
+
+  // Since the detrimental effect is the final option, we don't need to check the chance.
+  const enemiesChance = getRandom(rng);
+  const entityType =
+    enemiesChance < 0.5 ? EntityType.DRIP : EntityType.SMALL_LEECH;
+
+  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 spider = EntityNPC.ThrowSpider(
+      position,
+      undefined,
+      targetPos,
+      false,
+      0,
+    );
+
+    // There is no `ThrowLeech` or `ThrowDrip` functions exposed in the API, so we can piggyback off
+    // of the `ThrowSpider` method.
+    spider.Morph(entityType, 0, 0, -1);
+  });
+
+  return true;
 }

package/src/functions/roomData.ts

@@ -62,7 +62,7 @@ export function getRoomDescriptor(roomGridIndex?: int): RoomDescriptor {
  * Alias for the `Level.GetCurrentRoomDesc` method. Use this to make it more clear what type of
  * `RoomDescriptor` object that you are retrieving.
  */
-export function getRoomDescriptorReadOnly(): ReadonlyRoomDescriptor {
+export function getRoomDescriptorReadOnly(): Readonly<RoomDescriptor> {
   const level = game.GetLevel();
   return level.GetCurrentRoomDesc();
 }

package/src/functions/roomTransition.ts

@@ -0,0 +1,78 @@
+import {
+  Direction,
+  DoorSlot,
+  LevelCurse,
+  RoomTransitionAnim,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { runNextRoom } from "../features/runNextRoom";
+import { hasCurse } from "./curses";
+import { getRoomData, getRoomGridIndex } from "./roomData";
+
+/**
+ * Helper function to reload the current room using `Game.StartRoomTransition`.
+ *
+ * This is useful for canceling the "goto" console command or to make the `Level.SetStage` method
+ * take effect.
+ */
+export function reloadRoom(): void {
+  const roomGridIndex = getRoomGridIndex();
+  teleport(
+    roomGridIndex,
+    Direction.NO_DIRECTION,
+    RoomTransitionAnim.FADE,
+    true,
+  );
+}
+
+/**
+ * Helper function to change the current room. It can be used for both teleportation and "normal"
+ * room transitions, depending on what is passed for the `direction` and `roomTransitionAnim`
+ * arguments.
+ *
+ * Use this function instead of invoking the `Game.StartRoomTransition` method directly so that:
+ * - you do not forget to set `Level.LeaveDoor` property
+ * - to prevent crashing on invalid room grid indexes
+ * - to automatically handle Curse of the Maze
+ *
+ * @param roomGridIndex The room grid index of the destination room.
+ * @param direction Optional. Default is `Direction.NO_DIRECTION`.
+ * @param roomTransitionAnim Optional. Default is `RoomTransitionAnim.TELEPORT`.
+ * @param force Optional. Whether to temporarily disable Curse of the Maze. Default is false. If set
+ *              to false, then this function may not go to the provided room grid index.
+ */
+export function teleport(
+  roomGridIndex: int,
+  direction = Direction.NO_DIRECTION,
+  roomTransitionAnim = RoomTransitionAnim.TELEPORT,
+  force = false,
+): void {
+  const level = game.GetLevel();
+
+  // Before starting a room transition, we must ensure that Curse of the Maze is not in effect, or
+  // else the room transition might send us to the wrong room.
+  const shouldTempDisableCurse = force && hasCurse(LevelCurse.MAZE);
+  if (shouldTempDisableCurse) {
+    level.RemoveCurses(LevelCurse.MAZE);
+  }
+
+  const roomData = getRoomData(roomGridIndex);
+  if (roomData === undefined) {
+    error(
+      `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
+    );
+  }
+
+  // This must be set before every `Game.StartRoomTransition` method invocation or else the function
+  // can send you to the wrong room.
+  level.LeaveDoor = DoorSlot.NO_DOOR_SLOT;
+
+  game.StartRoomTransition(roomGridIndex, direction, roomTransitionAnim);
+
+  if (shouldTempDisableCurse) {
+    runNextRoom(() => {
+      const futureLevel = game.GetLevel();
+      futureLevel.AddCurse(LevelCurse.MAZE, false);
+    });
+  }
+}