isaacscript-common 2.2.0 → 2.3.0

package/src/enums/PocketItemType.ts

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

package/src/enums/SerializationType.ts

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

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,14 @@
+/* eslint-disable sort-exports/sort-exports */
+
+export enum SaveDataKey {
+  PERSISTENT = "persistent",
+  RUN = "run",
+  LEVEL = "level",
+  ROOM = "room",
+}
+
+export const RESETTABLE_SAVE_DATA_KEYS: ReadonlySet<SaveDataKey> = new Set([
+  SaveDataKey.RUN,
+  SaveDataKey.LEVEL,
+  SaveDataKey.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,116 @@
+import {
+  HeartSubType,
+  ModCallback,
+  PickupVariant,
+  PlayerType,
+} from "isaac-typescript-definitions";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import { isRedHeart } from "../functions/pickups";
+import { ensureAllCases } from "../functions/utils";
+
+const FEATURE_NAME = "character health manager";
+
+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);
+      return;
+    }
+
+    case HeartSubType.BLACK: {
+      player.AddBlackHearts(maxHearts);
+      return;
+    }
+
+    default: {
+      ensureAllCases(heartSubType);
+    }
+  }
+}
+
+/**
+ * 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);
+  characterHealthReplacementMap.set(playerType, conversionHeartSubType);
+}

package/src/features/characterStats.ts

@@ -0,0 +1,61 @@
+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 = "character stat manager";
+
+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/debugDisplay/debugDisplay.ts

@@ -0,0 +1,221 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { ModUpgraded } from "../../classes/ModUpgraded";
+import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
+import { isReflectionRender } from "../../functions/utils";
+import { saveDataManager } from "../saveDataManager/exports";
+import v, { debugDisplayTextCallbacks } from "./v";
+
+export function debugDisplayInit(mod: ModUpgraded): void {
+  saveDataManager("debugDisplay", v, () => false);
+
+  mod.AddCallback(ModCallback.POST_FAMILIAR_RENDER, postFamiliarRender); // 25
+  mod.AddCallback(ModCallback.POST_NPC_RENDER, postNPCRender); // 28
+  mod.AddCallback(ModCallback.POST_PLAYER_RENDER, postPlayerRender); // 32
+  mod.AddCallback(ModCallback.POST_PICKUP_RENDER, postPickupRender); // 36
+  mod.AddCallback(ModCallback.POST_TEAR_RENDER, postTearRender); // 41
+  mod.AddCallback(ModCallback.POST_PROJECTILE_RENDER, postProjectileRender); // 45
+  mod.AddCallback(ModCallback.POST_LASER_RENDER, postLaserRender); // 49
+  mod.AddCallback(ModCallback.POST_KNIFE_RENDER, postKnifeRender); // 52
+  mod.AddCallback(ModCallback.POST_EFFECT_RENDER, postEffectRender); // 56
+  mod.AddCallback(ModCallback.POST_BOMB_RENDER, postBombRender); // 59
+  mod.AddCallbackCustom(ModCallbackCustom.POST_SLOT_RENDER, postSlotRender);
+  mod.AddCallbackCustom(ModCallbackCustom.POST_ROCK_RENDER, postRockRender);
+  mod.AddCallbackCustom(ModCallbackCustom.POST_PIT_RENDER, postPitRender);
+  mod.AddCallbackCustom(ModCallbackCustom.POST_SPIKES_RENDER, postSpikesRender);
+  mod.AddCallbackCustom(ModCallbackCustom.POST_TNT_RENDER, postTNTRender);
+  mod.AddCallbackCustom(ModCallbackCustom.POST_POOP_RENDER, postPoopRender);
+  mod.AddCallbackCustom(ModCallbackCustom.POST_DOOR_RENDER, postDoorRender);
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_PRESSURE_PLATE_RENDER,
+    postPressurePlateRender,
+  );
+}
+
+function renderTextOnEntity(entity: Entity | GridEntity, text: string) {
+  if (isReflectionRender()) {
+    return;
+  }
+
+  const position = Isaac.WorldToScreen(entity.Position);
+  Isaac.RenderText(text, position.X, position.Y, 1, 1, 1, 1);
+}
+
+// ModCallback.POST_FAMILIAR_RENDER (25)
+function postFamiliarRender(familiar: EntityFamiliar) {
+  if (!v.run.familiar) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.familiar(familiar);
+  renderTextOnEntity(familiar, text);
+}
+
+// ModCallback.POST_NPC_RENDER (28)
+function postNPCRender(npc: EntityNPC) {
+  if (!v.run.npc) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.npc(npc);
+  renderTextOnEntity(npc, text);
+}
+
+// ModCallback.POST_PLAYER_RENDER (32)
+function postPlayerRender(player: EntityPlayer) {
+  if (!v.run.player) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.player(player);
+  renderTextOnEntity(player, text);
+}
+
+// ModCallback.POST_PICKUP_RENDER (36)
+function postPickupRender(pickup: EntityPickup) {
+  if (!v.run.pickup) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.pickup(pickup);
+  renderTextOnEntity(pickup, text);
+}
+
+// ModCallback.POST_TEAR_RENDER (41)
+function postTearRender(tear: EntityTear) {
+  if (!v.run.tear) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.tear(tear);
+  renderTextOnEntity(tear, text);
+}
+
+// ModCallback.POST_PROJECTILE_RENDER (45)
+function postProjectileRender(projectile: EntityProjectile) {
+  if (!v.run.projectile) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.projectile(projectile);
+  renderTextOnEntity(projectile, text);
+}
+
+// ModCallback.POST_LASER_RENDER (49)
+function postLaserRender(laser: EntityLaser) {
+  if (!v.run.laser) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.laser(laser);
+  renderTextOnEntity(laser, text);
+}
+
+// ModCallback.POST_KNIFE_RENDER (52)
+function postKnifeRender(knife: EntityKnife) {
+  if (!v.run.knife) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.knife(knife);
+  renderTextOnEntity(knife, text);
+}
+
+// ModCallback.POST_EFFECT_RENDER (56)
+function postEffectRender(effect: EntityEffect) {
+  if (!v.run.effect) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.effect(effect);
+  renderTextOnEntity(effect, text);
+}
+
+// ModCallback.POST_BOMB_RENDER (59)
+function postBombRender(bomb: EntityBomb) {
+  if (!v.run.bomb) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.bomb(bomb);
+  renderTextOnEntity(bomb, text);
+}
+
+// ModCallbackCustom.POST_SLOT_RENDER
+function postSlotRender(slot: Entity) {
+  if (!v.run.slot) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.slot(slot);
+  renderTextOnEntity(slot, text);
+}
+
+// ModCallbackCustom.POST_ROCK_RENDER
+function postRockRender(rock: GridEntityRock) {
+  if (!v.run.rock) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.rock(rock);
+  renderTextOnEntity(rock, text);
+}
+
+// ModCallbackCustom.POST_PIT_RENDER
+function postPitRender(pit: GridEntityPit) {
+  if (!v.run.pit) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.pit(pit);
+  renderTextOnEntity(pit, text);
+}
+
+// ModCallbackCustom.POST_SPIKES_RENDER
+function postSpikesRender(spikes: GridEntitySpikes) {
+  if (!v.run.spikes) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.spikes(spikes);
+  renderTextOnEntity(spikes, text);
+}
+
+// ModCallbackCustom.POST_TNT_RENDER
+function postTNTRender(tnt: GridEntityTNT) {
+  if (!v.run.tnt) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.tnt(tnt);
+  renderTextOnEntity(tnt, text);
+}
+
+// ModCallbackCustom.POST_POOP_RENDER
+function postPoopRender(poop: GridEntityPoop) {
+  if (!v.run.poop) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.poop(poop);
+  renderTextOnEntity(poop, text);
+}
+
+// ModCallbackCustom.POST_DOOR_RENDER
+function postDoorRender(door: GridEntityDoor) {
+  if (!v.run.door) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.door(door);
+  renderTextOnEntity(door, text);
+}
+
+// ModCallbackCustom.POST_PRESSURE_PLATE_RENDER
+function postPressurePlateRender(pressurePlate: GridEntityPressurePlate) {
+  if (!v.run.pressurePlate) {
+    return;
+  }
+
+  const text = debugDisplayTextCallbacks.pressurePlate(pressurePlate);
+  renderTextOnEntity(pressurePlate, text);
+}