isaacscript-common 6.6.1-dev.1 → 6.6.1-dev.5

package/src/enums/PocketItemType.ts

@@ -0,0 +1,8 @@
+export enum PocketItemType {
+  EMPTY,
+  CARD,
+  PILL,
+  ACTIVE_ITEM,
+  DICE_BAG_DICE,
+  UNDETERMINABLE,
+}

package/src/enums/RockAltType.ts

@@ -0,0 +1,7 @@
+export enum RockAltType {
+  URN,
+  MUSHROOM,
+  SKULL,
+  POLYP,
+  BUCKET,
+}

package/src/enums/SerializationType.ts

@@ -0,0 +1,5 @@
+export enum SerializationType {
+  NONE,
+  SERIALIZE,
+  DESERIALIZE,
+}

package/src/enums/SlotDestructionType.ts

@@ -0,0 +1,4 @@
+export enum SlotDestructionType {
+  NORMAL,
+  COLLECTIBLE_PAYOUT,
+}

package/src/enums/private/CopyableIsaacAPIClassType.ts

@@ -0,0 +1,7 @@
+/** This must match the enumeration in the JSDoc comments for `deepCopy` and `merge`. */
+export enum CopyableIsaacAPIClassType {
+  COLOR = "Color",
+  K_COLOR = "KColor",
+  RNG = "RNG",
+  VECTOR = "Vector",
+}

package/src/enums/private/SaveDataKey.ts

@@ -0,0 +1,6 @@
+export enum SaveDataKey {
+  PERSISTENT = "persistent",
+  RUN = "run",
+  LEVEL = "level",
+  ROOM = "room",
+}

package/src/enums/private/SerializationBrand.ts

@@ -0,0 +1,42 @@
+/**
+ * During serialization, we write an arbitrary string key to the object with a value of an empty
+ * string. This is used during deserialization to instantiate the correct type of object.
+ *
+ * Note that we do not bother branding TSTL classes because we have no way to invoke the proper
+ * constructor during deserialization.
+ */
+export enum SerializationBrand {
+  // Specific TSTL class brands:
+  DEFAULT_MAP = "__TSTL_DEFAULT_MAP",
+  MAP = "__TSTL_MAP",
+  SET = "__TSTL_SET",
+
+  // Specific Isaac API class brands:
+  COLOR = "__COLOR",
+  K_COLOR = "__K_COLOR",
+  RNG = "__RNG",
+  VECTOR = "__VECTOR",
+
+  /**
+   * This is set to the value that represents the default value (instead of an empty string like the
+   * other brands are).
+   *
+   * Default maps that use a factory function are unserializable, but do not throw runtime errors
+   * because the merge function can derive the factory function from the already-instantiated
+   * object.
+   */
+  DEFAULT_MAP_VALUE = "__TSTL_DEFAULT_MAP_VALUE",
+
+  /**
+   * The JSON library is unable to distinguish between a maps with number keys and an array. It will
+   * assume that both of these are an array. Thus, in the case of a map with number keys, it will
+   * insert null in every empty spot, leading to crashes.
+   *
+   * For example, a map with keys of 5 and 10 would be converted to the following array: `[null,
+   * null, null, null, "myValueForKey5", null, null, null, null, "myValueForKey10"]`
+   *
+   * The deep copier works around this by converting number keys to strings. It inserts this brand
+   * to keep track of the mutation.
+   */
+  OBJECT_WITH_NUMBER_KEYS = "__TSTL_OBJECT_WITH_NUMBER_KEYS",
+}

package/src/features/characterHealthConversion.ts

@@ -0,0 +1,125 @@
+/**
+ * Easily create custom characters that have the same health mechanic as Blue Baby (red heart
+ * containers --> soul hearts) or Black Judas (red heart containers --> black hearts).
+ *
+ * @module
+ */
+
+import {
+  HeartSubType,
+  ModCallback,
+  PickupVariant,
+  PlayerType,
+} from "isaac-typescript-definitions";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { isRedHeart } from "../functions/pickups";
+
+const FEATURE_NAME = "characterHealthConversion";
+
+export type ConversionHeartSubType = HeartSubType.SOUL | HeartSubType.BLACK;
+
+const characterHealthReplacementMap = new Map<
+  PlayerType,
+  ConversionHeartSubType
+>();
+
+/** @internal */
+export function characterHealthConversionInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.POST_PEFFECT_UPDATE, postPEffectUpdate); // 4
+  mod.AddCallback(
+    ModCallback.PRE_PICKUP_COLLISION,
+    prePickupCollisionHeart,
+    PickupVariant.HEART,
+  ); // 38
+}
+
+// ModCallback.POST_PEFFECT_UPDATE (4)
+function postPEffectUpdate(player: EntityPlayer) {
+  const character = player.GetPlayerType();
+  const conversionHeartSubType = characterHealthReplacementMap.get(character);
+  if (conversionHeartSubType === undefined) {
+    return;
+  }
+
+  convertRedHeartContainers(player, conversionHeartSubType);
+  removeRedHearts(player);
+}
+
+function convertRedHeartContainers(
+  player: EntityPlayer,
+  heartSubType: ConversionHeartSubType,
+) {
+  const maxHearts = player.GetMaxHearts();
+  if (maxHearts === 0) {
+    return;
+  }
+
+  player.AddMaxHearts(maxHearts * -1, false);
+
+  switch (heartSubType) {
+    case HeartSubType.SOUL: {
+      player.AddSoulHearts(maxHearts);
+      break;
+    }
+
+    case HeartSubType.BLACK: {
+      player.AddBlackHearts(maxHearts);
+      break;
+    }
+  }
+}
+
+/**
+ * We also have to check for normal red hearts, so that the player is not able to fill bone hearts
+ * (by e.g. picking up a healing item like Breakfast).
+ */
+function removeRedHearts(player: EntityPlayer) {
+  const hearts = player.GetHearts();
+  if (hearts > 0) {
+    player.AddHearts(hearts * -1);
+  }
+}
+
+// ModCallback.PRE_PICKUP_COLLISION (38)
+// PickupVariant.HEART (10)
+function prePickupCollisionHeart(pickup: EntityPickup, collider: Entity) {
+  if (!isRedHeart(pickup)) {
+    return undefined;
+  }
+
+  const player = collider.ToPlayer();
+  if (player === undefined) {
+    return undefined;
+  }
+
+  const character = player.GetPlayerType();
+  const conversionHeartSubType = characterHealthReplacementMap.get(character);
+  if (conversionHeartSubType === undefined) {
+    return undefined;
+  }
+
+  // Prevent internal code from running, which will prevent the player from picking up the heart,
+  // but will still allow the heart to bounce off of the player.
+  return false;
+}
+
+/**
+ * Helper function to make a character that has the same health mechanic as Blue Baby (red heart
+ * containers --> soul hearts) or Dark Judas (red heart containers --> black hearts).
+ *
+ * Call this function once at the beginning of your mod to declare the health conversion type.
+ */
+export function registerCharacterHealthConversion(
+  playerType: PlayerType,
+  conversionHeartSubType: ConversionHeartSubType,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (characterHealthReplacementMap.has(playerType)) {
+    error(
+      `Failed to register a character of type ${playerType} because there is already an existing registered character with that type.`,
+    );
+  }
+
+  characterHealthReplacementMap.set(playerType, conversionHeartSubType);
+}

package/src/features/characterStats.ts

@@ -0,0 +1,67 @@
+/**
+ * Easily create custom characters that have base stats different from that of Isaac.
+ *
+ * @module
+ */
+
+import {
+  CacheFlag,
+  ModCallback,
+  PlayerType,
+} from "isaac-typescript-definitions";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { getDefaultPlayerStat } from "../functions/cacheFlag";
+import { addStat } from "../functions/player";
+
+const FEATURE_NAME = "characterStats";
+
+type StatMap = Map<CacheFlag, number> | ReadonlyMap<CacheFlag, number>;
+const charactersStatMap = new Map<PlayerType, StatMap>();
+
+/** @internal */
+export function characterStatsInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.EVALUATE_CACHE, evaluateCache); // 8
+}
+
+// ModCallback.EVALUATE_CACHE (8)
+function evaluateCache(player: EntityPlayer, cacheFlag: CacheFlag) {
+  const character = player.GetPlayerType();
+  const statMap = charactersStatMap.get(character);
+  if (statMap === undefined) {
+    return;
+  }
+
+  const stat = statMap.get(cacheFlag);
+  const defaultStat = getDefaultPlayerStat(cacheFlag);
+  if (stat === undefined || defaultStat === undefined) {
+    return;
+  }
+  const delta = stat - defaultStat;
+
+  addStat(player, cacheFlag, delta);
+}
+
+/**
+ * Helper function to manage the stats for a vanilla or custom character. Call this function once at
+ * the beginning of your mod to declare the starting stats.
+ *
+ * You must provide this function with a map of CacheFlag to the default stat amount. For example,
+ * the default amount of damage is 3.5. To make a custom character start with 4.5 damage:
+ *
+ * ```ts
+ * const fooDefaultStats = new Map<CacheFlag, number>([
+ *   [CacheFlag.DAMAGE, 4.5],
+ * ])
+ * registerCharacterStats(PlayerTypeCustom.FOO, fooDefaultStats);
+ * ```
+ *
+ * Note that the format for the `CacheFlag.FIRE_DELAY` value should be in the tears stat format, not
+ * the `MaxFireDelay` format.
+ */
+export function registerCharacterStats(
+  playerType: PlayerType,
+  statMap: Map<CacheFlag, number> | ReadonlyMap<CacheFlag, number>,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+  charactersStatMap.set(playerType, statMap);
+}

package/src/features/collectibleItemPoolType.ts

@@ -0,0 +1,66 @@
+// The item pool type of a collectible is not stored on the collectible. Thus, we scan for incoming
+// item pool types in the PreGetCollectible callback, and then assume that the next spawned
+// collectible has this item pool type.
+
+import {
+  ItemPoolType,
+  ModCallback,
+  PickupVariant,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { getEntityID } from "../functions/entity";
+import { isCollectible } from "../functions/pickupVariants";
+import { getRoomItemPoolType } from "../functions/rooms";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "collectibleItemPoolType";
+
+const v = {
+  run: {
+    collectibleItemPoolTypeMap: new Map<PtrHash, ItemPoolType>(),
+  },
+};
+
+/** @internal */
+export function collectibleItemPoolTypeInit(mod: Mod): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallback(
+    ModCallback.POST_PICKUP_INIT,
+    postPickupInitCollectible,
+    PickupVariant.COLLECTIBLE,
+  ); // 34
+}
+
+// ModCallback.POST_PICKUP_INIT (34)
+// PickupVariant.COLLECTIBLE (100)
+function postPickupInitCollectible(pickup: EntityPickup) {
+  const itemPool = game.GetItemPool();
+  const ptrHash = GetPtrHash(pickup);
+  const lastItemPoolType = itemPool.GetLastPool();
+
+  v.run.collectibleItemPoolTypeMap.set(ptrHash, lastItemPoolType);
+}
+
+/**
+ * Helper function to get the item pool type that a given collectible came from. Since there is no
+ * native method in the API to get this, we listen in the PreGetCollectible callback for item pool
+ * types, and then assume that the next spawned collectible will match.
+ */
+export function getCollectibleItemPoolType(
+  collectible: EntityPickup,
+): ItemPoolType {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  if (!isCollectible(collectible)) {
+    const entityID = getEntityID(collectible);
+    error(
+      `The "getCollectibleItemPoolType" function was given a non-collectible: ${entityID}`,
+    );
+  }
+
+  const ptrHash = GetPtrHash(collectible);
+  const itemPoolType = v.run.collectibleItemPoolTypeMap.get(ptrHash);
+  return itemPoolType === undefined ? getRoomItemPoolType() : itemPoolType;
+}

package/src/features/customGridEntity.ts

@@ -0,0 +1,192 @@
+import {
+  GridCollisionClass,
+  GridEntityType,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { DefaultMap } from "../classes/DefaultMap";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { DecorationVariant } from "../enums/DecorationVariant";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { removeGrid, spawnGridWithVariant } from "../functions/gridEntity";
+import { getRoomListIndex } from "../functions/roomData";
+import { isVector } from "../functions/vector";
+import { CustomGridEntityData } from "../interfaces/CustomGridEntityData";
+import { saveDataManager } from "./saveDataManager/exports";
+
+const FEATURE_NAME = "customGridEntity";
+
+const v = {
+  level: {
+    /** Indexed by room list index and grid index. */
+    customGridEntities: new DefaultMap<int, Map<int, CustomGridEntityData>>(
+      () => new Map(),
+    ),
+  },
+};
+
+/** @internal */
+export function customGridEntityInit(mod: ModUpgraded): void {
+  saveDataManager(FEATURE_NAME, v);
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_NEW_ROOM_REORDERED,
+    postNewRoomReordered,
+  );
+}
+
+// ModCallbackCustom.POST_NEW_ROOM_REORDERED
+function postNewRoomReordered() {
+  // When we re-enter a room, the graphics for any custom entities will be reverted back to that of
+  // a normal decoration. Thus, we must re-apply the anm2.
+  const roomListIndex = getRoomListIndex();
+  const roomCustomGridEntities = v.level.customGridEntities.get(roomListIndex);
+  if (roomCustomGridEntities === undefined) {
+    return;
+  }
+
+  const room = game.GetRoom();
+  for (const [gridIndex, data] of roomCustomGridEntities.entries()) {
+    const decoration = room.GetGridEntity(gridIndex);
+    if (decoration === undefined) {
+      roomCustomGridEntities.delete(gridIndex);
+      continue;
+    }
+
+    const sprite = decoration.GetSprite();
+    sprite.Load(data.anm2, true);
+    sprite.Play(data.defaultAnimation, true);
+  }
+}
+
+/**
+ * Helper function to spawn a custom grid entity.
+ *
+ * This is an IsaacScript feature because the vanilla game does not support any custom grid
+ * entities. Under the hood, IsaacScript accomplishes this by using decorations with an arbitrary
+ * non-zero variant to represent custom grid entities.
+ *
+ * Once a custom grid entity is spawned, you can take advantage of the custom grid callbacks such as
+ * `POST_GRID_ENTITY_CUSTOM_UPDATE`.
+ *
+ * @param gridEntityTypeCustom An integer that identifies what kind of grid entity you are creating.
+ *                             It should correspond to a local enum value in your mod. The integer
+ *                             can be any unique value and will not correspond to the actual grid
+ *                             entity type used. (This integer is used in the various custom grid
+ *                             entity callbacks.)
+ * @param gridIndexOrPosition The grid index or position in the room that you want to spawn the grid
+ *                            entity at. If a position is specified, the closest grid index will be
+ *                            used.
+ * @param anm2 The path to the ANM2 file to use for the sprite.
+ * @param defaultAnimation The name of the animation to play after the sprite is initialized and
+ *                         after the player re-enters a room with this grid entity in it.
+ * @param gridCollisionClass The collision class that you want the custom grid entity to have.
+ */
+export function spawnCustomGrid(
+  gridEntityTypeCustom: GridEntityType,
+  gridIndexOrPosition: int | Vector,
+  anm2: string,
+  defaultAnimation: string,
+  gridCollisionClass: GridCollisionClass,
+): GridEntity {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const room = game.GetRoom();
+  const roomListIndex = getRoomListIndex();
+  const gridIndex = isVector(gridIndexOrPosition)
+    ? room.GetGridIndex(gridIndexOrPosition)
+    : gridIndexOrPosition;
+
+  const existingGridEntity = room.GetGridEntity(gridIndex);
+  const isExistingDecoration =
+    existingGridEntity !== undefined &&
+    existingGridEntity.GetType() === GridEntityType.DECORATION &&
+    existingGridEntity.GetVariant() ===
+      (DecorationVariant.CUSTOM_GRID_ENTITY as int);
+  const decoration = isExistingDecoration
+    ? existingGridEntity
+    : spawnGridWithVariant(
+        GridEntityType.DECORATION,
+        DecorationVariant.CUSTOM_GRID_ENTITY,
+        gridIndexOrPosition,
+      );
+  if (decoration === undefined) {
+    error("Failed to spawn a decoration for a custom grid entity.");
+  }
+
+  const sprite = decoration.GetSprite();
+  sprite.Load(anm2, true);
+  sprite.Play(defaultAnimation, true);
+
+  const customGridEntityData: CustomGridEntityData = {
+    gridEntityTypeCustom,
+    roomListIndex,
+    gridIndex,
+    anm2,
+    defaultAnimation,
+    gridCollisionClass,
+  };
+
+  const roomCustomGridEntities =
+    v.level.customGridEntities.getAndSetDefault(roomListIndex);
+  roomCustomGridEntities.set(gridIndex, customGridEntityData);
+
+  return decoration;
+}
+
+/**
+ * Helper function to remove a custom grid entity created by the `spawnCustomGrid` function.
+ *
+ * @param gridIndexOrPositionOrGridEntity You can specify the custom grid entity to remove by
+ *                                 providing the grid index, the room position, or the grid entity
+ *                                 itself.
+ * @param updateRoom Optional. Whether or not to update the room after the grid entity is removed.
+ *                   Default is true. This is generally a good idea because if the room is not
+ *                   updated, you will be unable to spawn another grid entity on the same tile until
+ *                   a frame has passed. However, doing this is expensive, since it involves a call
+ *                   to `Isaac.GetRoomEntities`, so set it to false if you need to invoke this
+ *                   function multiple times.
+ * @returns The grid entity that was removed. Returns undefined if no grid entity was found at the
+ *          given location or if the given grid entity was not a custom grid entity.
+ */
+export function removeCustomGrid(
+  gridIndexOrPositionOrGridEntity: int | Vector | GridEntity,
+  updateRoom = true,
+): GridEntity | undefined {
+  const room = game.GetRoom();
+  const roomListIndex = getRoomListIndex();
+
+  let decoration: GridEntity;
+  if (typeof gridIndexOrPositionOrGridEntity === "number") {
+    const gridIndex = gridIndexOrPositionOrGridEntity;
+    const gridEntity = room.GetGridEntity(gridIndex);
+    if (gridEntity === undefined) {
+      return undefined;
+    }
+
+    decoration = gridEntity;
+  } else if (isVector(gridIndexOrPositionOrGridEntity)) {
+    const position = gridIndexOrPositionOrGridEntity;
+    const gridEntity = room.GetGridEntityFromPos(position);
+    if (gridEntity === undefined) {
+      return undefined;
+    }
+
+    decoration = gridEntity;
+  } else {
+    decoration = gridIndexOrPositionOrGridEntity;
+  }
+
+  const gridIndex = decoration.GetGridIndex();
+  const roomCustomGridEntities =
+    v.level.customGridEntities.getAndSetDefault(roomListIndex);
+  const exists = roomCustomGridEntities.has(gridIndex);
+  if (!exists) {
+    return undefined;
+  }
+
+  roomCustomGridEntities.delete(gridIndex);
+  removeGrid(decoration, updateRoom);
+
+  return decoration;
+}