isaacscript-common 2.2.0 → 2.3.0

package/src/callbacks/postCustomDoorEnter.ts

@@ -0,0 +1,297 @@
+/* eslint-disable sort-exports/sort-exports */
+
+import {
+  Direction,
+  DoorSlot,
+  DoorState,
+  EffectVariant,
+  GridCollisionClass,
+  GridEntityType,
+  ModCallback,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { ModCallbackCustom } from "../enums/ModCallbackCustom";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { directionToVector } from "../functions/direction";
+import { doorSlotToDirection } from "../functions/doors";
+import { getEffects, spawnEffect } from "../functions/entitySpecific";
+import { getClosestPlayer } from "../functions/player";
+import { ensureAllCases } from "../functions/utils";
+import {
+  postCustomDoorEnterFire,
+  postCustomDoorEnterHasSubscriptions,
+} from "./subscriptions/postCustomDoorEnter";
+
+interface CustomDoorData {
+  slot: DoorSlot;
+  state: DoorState;
+}
+
+const POSITION_OFFSET_MULTIPLIER = -23;
+
+const initializedEffectVariants = new Set<int>();
+
+const v = {
+  room: {
+    customDoors: new Map<PtrHash, CustomDoorData>(),
+    customDoorSlots: new Set<DoorSlot>(),
+  },
+};
+
+/** @internal */
+export function postCustomDoorEnterCallbackInit(): void {
+  saveDataManager("postCustomDoorEnter", v, hasSubscriptions);
+}
+
+function hasSubscriptions() {
+  return postCustomDoorEnterHasSubscriptions();
+}
+
+/**
+ * `isaacscript-common` provides custom doors that can be spawned where any wall segment is. If you
+ * use this feature, you must first call this initialization function at the beginning of your mod.
+ *
+ * Each kind of custom door that you create must have an entry in the "content/entities2.xml" file,
+ * like so:
+ *
+ * ```xml
+ * <entity id="1000" name="Foo Custom Door" anm2path="grid/door_foo.anm2" />
+ * ```
+ *
+ * (Custom door entities must have an id of "1000", which corresponds to an effect. If you do not
+ * specify the variant, then the game will automatically assign it.)
+ *
+ * Next, pass the variant into this function:
+ *
+ * ```ts
+ * const modVanilla = RegisterMod("My Mod", 1);
+ * const mod = upgradeMod(modVanilla);
+ * const fooEffectVariant = Isaac.GetEntityVariantByName("Foo Custom Door");
+ * initCustomDoor(mod, fooEffectVariant);
+ * ```
+ *
+ * Also see the `spawnCustomDoor` function.
+ */
+export function initCustomDoor(
+  mod: ModUpgraded,
+  effectVariant: EffectVariant,
+): void {
+  initializedEffectVariants.add(effectVariant);
+
+  mod.AddCallback(
+    ModCallback.POST_EFFECT_UPDATE,
+    postEffectUpdaterCustomEntity,
+    effectVariant,
+  ); // 55
+
+  mod.AddCallback(
+    ModCallback.POST_EFFECT_RENDER,
+    postEffectRenderCustomEntity,
+    effectVariant,
+  ); // 56
+
+  mod.AddCallbackCustom(
+    ModCallbackCustom.POST_ROOM_CLEAR_CHANGED,
+    (roomClear: boolean) => {
+      postRoomClearChanged(roomClear, effectVariant);
+    },
+  );
+}
+
+// ModCallback.POST_EFFECT_UPDATE (55)
+function postEffectUpdaterCustomEntity(effect: EntityEffect) {
+  const ptrHash = GetPtrHash(effect);
+  const doorData = v.room.customDoors.get(ptrHash);
+  if (doorData === undefined) {
+    return;
+  }
+
+  if (doorData.state === (effect.State as DoorState)) {
+    return;
+  }
+  doorData.state = effect.State as DoorState;
+
+  doorChangedState(effect);
+}
+
+function doorChangedState(effect: EntityEffect) {
+  const room = game.GetRoom();
+
+  const sprite = effect.GetSprite();
+  const animation = getAnimationForCustomDoor(effect);
+  sprite.Play(animation, true);
+
+  const gridIndex = room.GetGridIndex(effect.Position);
+  const wall = room.GetGridEntity(gridIndex);
+  if (wall !== undefined) {
+    wall.CollisionClass =
+      (effect.State as DoorState) === DoorState.OPEN
+        ? GridCollisionClass.WALL_EXCEPT_PLAYER
+        : GridCollisionClass.WALL;
+  }
+}
+
+function getAnimationForCustomDoor(effect: EntityEffect): string {
+  const freshlySpawned = effect.FrameCount === 0;
+
+  switch (effect.State as DoorState) {
+    case DoorState.OPEN: {
+      return freshlySpawned ? "Opened" : "Open";
+    }
+
+    case DoorState.CLOSED: {
+      return freshlySpawned ? "Closed" : "Close";
+    }
+
+    default: {
+      return "Opened";
+    }
+  }
+}
+
+// ModCallback.POST_EFFECT_RENDER (56)
+function postEffectRenderCustomEntity(effect: EntityEffect) {
+  const ptrHash = GetPtrHash(effect);
+  const doorData = v.room.customDoors.get(ptrHash);
+  if (doorData === undefined) {
+    return;
+  }
+
+  const direction = doorSlotToDirection(doorData.slot);
+  const player = getClosestPlayer(effect.Position);
+  if (isPlayerPastDoorThreshold(effect, player, direction)) {
+    postCustomDoorEnterFire(player, effect.Variant, doorData.slot, direction);
+  }
+}
+
+function isPlayerPastDoorThreshold(
+  effect: EntityEffect,
+  player: EntityPlayer,
+  direction: Direction,
+) {
+  switch (direction) {
+    case Direction.NO_DIRECTION: {
+      return false;
+    }
+
+    // 1
+    case Direction.UP: {
+      return player.Position.Y <= effect.Position.Y;
+    }
+
+    // 2
+    case Direction.RIGHT: {
+      return player.Position.X >= effect.Position.X;
+    }
+
+    // 3
+    case Direction.DOWN: {
+      return player.Position.Y >= effect.Position.Y;
+    }
+
+    // 4
+    case Direction.LEFT: {
+      return player.Position.X <= effect.Position.X;
+    }
+
+    default: {
+      return ensureAllCases(direction);
+    }
+  }
+}
+
+// ModCallbackCustom.POST_ROOM_CLEAR_CHANGED
+function postRoomClearChanged(
+  roomClear: boolean,
+  effectVariant: EffectVariant,
+) {
+  const state = roomClear ? DoorState.OPEN : DoorState.CLOSED;
+  const customDoors = getEffects(effectVariant);
+  for (const customDoor of customDoors) {
+    customDoor.State = state;
+  }
+}
+
+/**
+ * Helper function to spawn a custom door. This is intended to be called from the `POST_NEW_ROOM`
+ * callback when the player enters a room that should have a custom door. (You could also call it
+ * from another callback if you want the door to appear e.g. after clearing all enemies.)
+ *
+ * Like other entities, the door is not persistent, so you must spawn it every time when re-entering
+ * the room.
+ *
+ * Handle when a player enters the door by hooking the custom `POST_CUSTOM_DOOR_ENTER` callback.
+ *
+ * The custom door is an `EntityEffect`. You can manually open or close the door by modifying its
+ * state. (The values to use correspond to the `DoorState` enum.)
+ *
+ * This function will throw a runtime error if:
+ * - the door slot already has a vanilla door
+ * - the door slot already has a custom door
+ * - the tile at the door slot does not have a wall
+ *
+ * Before using this function, you must first initialize the effect/door variant with the
+ * `initCustomDoor` function.
+ */
+export function spawnCustomDoor(
+  effectVariant: EffectVariant,
+  doorSlot: DoorSlot,
+): EntityEffect {
+  if (!initializedEffectVariants.has(effectVariant)) {
+    error(
+      'In order to spawn custom doors, you must first initialize them with the "initCustomDoor" function at the beginning of your mod.',
+    );
+  }
+
+  if (v.room.customDoorSlots.has(doorSlot)) {
+    error(
+      `There is already a custom door initialized on door slot: ${doorSlot}`,
+    );
+  }
+
+  const room = game.GetRoom();
+  const roomClear = room.IsClear();
+  const position = room.GetDoorSlotPosition(doorSlot);
+  const gridEntity = room.GetGridEntityFromPos(position);
+  if (gridEntity === undefined) {
+    error(
+      `Failed to initialize a custom door at slot ${doorSlot} because the wall on that tile does not exist.`,
+    );
+  }
+
+  const gridEntityType = gridEntity.GetType();
+  if (gridEntityType !== GridEntityType.WALL) {
+    error(
+      `Failed to initialize a custom door at slot ${doorSlot} because there is another grid entity on that tile with a type of: ${gridEntityType}`,
+    );
+  }
+
+  const effect = spawnEffect(effectVariant, 0, position);
+
+  // Do initial setup for the door.
+  effect.State = roomClear ? DoorState.OPEN : DoorState.CLOSED;
+  effect.RenderZOffset = -10000;
+  effect.PositionOffset = getPositionOffset(doorSlot);
+  const sprite = effect.GetSprite();
+  sprite.Rotation = (doorSlot as int) * 90 - 90;
+
+  // Keep track of metadata about this door.
+  const ptrHash = GetPtrHash(effect);
+  const doorData: CustomDoorData = {
+    slot: doorSlot,
+    state: effect.State,
+  };
+  v.room.customDoors.set(ptrHash, doorData);
+  v.room.customDoorSlots.add(doorSlot);
+
+  doorChangedState(effect);
+
+  return effect;
+}
+
+function getPositionOffset(doorSlot: DoorSlot) {
+  const direction = doorSlotToDirection(doorSlot);
+  const vector = directionToVector(direction);
+  return vector.mul(POSITION_OFFSET_MULTIPLIER);
+}

package/src/callbacks/postDoorRender.ts

@@ -0,0 +1,26 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { getDoors } from "../functions/doors";
+import {
+  postDoorRenderFire,
+  postDoorRenderHasSubscriptions,
+} from "./subscriptions/postDoorRender";
+
+/** @internal */
+export function postDoorRenderInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.POST_RENDER, postRender); // 2
+}
+
+function hasSubscriptions() {
+  return postDoorRenderHasSubscriptions();
+}
+
+// ModCallback.POST_RENDER (2)
+function postRender() {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  for (const doors of getDoors()) {
+    postDoorRenderFire(doors);
+  }
+}

package/src/callbacks/postDoorUpdate.ts

@@ -0,0 +1,26 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { getDoors } from "../functions/doors";
+import {
+  postDoorUpdateFire,
+  postDoorUpdateHasSubscriptions,
+} from "./subscriptions/postDoorUpdate";
+
+/** @internal */
+export function postDoorUpdateInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.POST_UPDATE, postUpdate); // 1
+}
+
+function hasSubscriptions() {
+  return postDoorUpdateHasSubscriptions();
+}
+
+// ModCallback.POST_UPDATE (1)
+function postUpdate() {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  for (const doors of getDoors()) {
+    postDoorUpdateFire(doors);
+  }
+}

package/src/callbacks/postEffectInitLate.ts

@@ -0,0 +1,36 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import {
+  postEffectInitLateFire,
+  postEffectInitLateHasSubscriptions,
+} from "./subscriptions/postEffectInitLate";
+
+const v = {
+  room: {
+    firedSet: new Set<PtrHash>(),
+  },
+};
+
+/** @internal */
+export function postEffectInitLateCallbackInit(mod: Mod): void {
+  saveDataManager("postEffectInitLate", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_EFFECT_UPDATE, postEffectUpdate); // 55
+}
+
+function hasSubscriptions() {
+  return postEffectInitLateHasSubscriptions();
+}
+
+// ModCallback.POST_EFFECT_UPDATE (55)
+function postEffectUpdate(effect: EntityEffect) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const index = GetPtrHash(effect);
+  if (!v.room.firedSet.has(index)) {
+    v.room.firedSet.add(index);
+    postEffectInitLateFire(effect);
+  }
+}

package/src/callbacks/postEffectStateChanged.ts

@@ -0,0 +1,43 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { DefaultMap } from "../classes/DefaultMap";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import {
+  postEffectStateChangedFire,
+  postEffectStateChangedHasSubscriptions,
+} from "./subscriptions/postEffectStateChanged";
+
+const v = {
+  run: {
+    effectStateMap: new DefaultMap<PtrHash, int, [int]>((state) => state),
+  },
+};
+
+/** @internal */
+export function postEffectStateChangedCallbackInit(mod: Mod): void {
+  saveDataManager("postEffectStateChanged", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_EFFECT_UPDATE, postEffectUpdate); // 55
+}
+
+function hasSubscriptions() {
+  return postEffectStateChangedHasSubscriptions();
+}
+
+// ModCallback.POST_EFFECT_UPDATE (55)
+function postEffectUpdate(effect: EntityEffect) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const ptrHash = GetPtrHash(effect);
+  const previousState = v.run.effectStateMap.getAndSetDefault(
+    ptrHash,
+    effect.State,
+  );
+  const currentState = effect.State;
+  v.run.effectStateMap.set(ptrHash, currentState);
+
+  if (previousState !== currentState) {
+    postEffectStateChangedFire(effect, previousState, currentState);
+  }
+}

package/src/callbacks/postEsauJr.ts

@@ -0,0 +1,107 @@
+// This provides the logic for:
+// - PostEsauJr
+// - PostFirstEsauJr
+
+import {
+  CollectibleType,
+  ControllerIndex,
+  ModCallback,
+  UseFlag,
+} from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { getPlayers } from "../functions/playerIndex";
+import {
+  postEsauJrFire,
+  postEsauJrHasSubscriptions,
+} from "./subscriptions/postEsauJr";
+import {
+  postFirstEsauJrFire,
+  postFirstEsauJrHasSubscriptions,
+} from "./subscriptions/postFirstEsauJr";
+
+const v = {
+  run: {
+    usedEsauJrFrame: null as int | null,
+    usedEsauJrControllerIndex: null as ControllerIndex | null,
+    usedEsauJrAtLeastOnce: false,
+  },
+};
+
+/** @internal */
+export function postEsauJrCallbacksInit(mod: Mod): void {
+  saveDataManager("postEsauJr", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_UPDATE, postUpdate); // 1
+  mod.AddCallback(
+    ModCallback.POST_USE_ITEM,
+    useItemEsauJr,
+    CollectibleType.ESAU_JR,
+  ); // 3
+}
+
+function hasSubscriptions() {
+  return postEsauJrHasSubscriptions() || postFirstEsauJrHasSubscriptions();
+}
+
+// ModCallback.POST_UPDATE (1)
+function postUpdate() {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const gameFrameCount = game.GetFrameCount();
+
+  // Check to see if it is the frame after the player has used Esau Jr.
+  if (
+    v.run.usedEsauJrFrame === null ||
+    gameFrameCount < v.run.usedEsauJrFrame + 1
+  ) {
+    return;
+  }
+  v.run.usedEsauJrFrame = null;
+
+  // Find the player corresponding to the player who used Esau Jr. a frame ago (via matching the
+  // ControllerIndex).
+  if (v.run.usedEsauJrControllerIndex === null) {
+    return;
+  }
+  const player = getPlayerWithControllerIndex(v.run.usedEsauJrControllerIndex);
+  v.run.usedEsauJrControllerIndex = null;
+  if (player === undefined) {
+    return;
+  }
+
+  if (!v.run.usedEsauJrAtLeastOnce) {
+    v.run.usedEsauJrAtLeastOnce = true;
+    postFirstEsauJrFire(player);
+  }
+
+  postEsauJrFire(player);
+}
+
+function getPlayerWithControllerIndex(controllerIndex: ControllerIndex) {
+  const players = getPlayers();
+  return players.find((player) => player.ControllerIndex === controllerIndex);
+}
+
+// ModCallback.USE_ITEM (3)
+// CollectibleType.ESAU_JR (703)
+function useItemEsauJr(
+  _collectibleType: CollectibleType,
+  _rng: RNG,
+  player: EntityPlayer,
+  _useFlags: BitFlags<UseFlag>,
+  _activeSlot: int,
+  _customVarData: int,
+) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const gameFrameCount = game.GetFrameCount();
+
+  // The player only changes to Esau Jr. on the frame after the item is used.
+  v.run.usedEsauJrFrame = gameFrameCount + 1;
+  v.run.usedEsauJrControllerIndex = player.ControllerIndex;
+}

package/src/callbacks/postFamiliarInitLate.ts

@@ -0,0 +1,36 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import {
+  postFamiliarInitLateFire,
+  postFamiliarInitLateHasSubscriptions,
+} from "./subscriptions/postFamiliarInitLate";
+
+const v = {
+  run: {
+    firedSet: new Set<PtrHash>(),
+  },
+};
+
+/** @internal */
+export function postFamiliarInitLateCallbackInit(mod: Mod): void {
+  saveDataManager("postFamiliarInitLate", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_FAMILIAR_UPDATE, postFamiliarUpdate); // 6
+}
+
+function hasSubscriptions() {
+  return postFamiliarInitLateHasSubscriptions();
+}
+
+// ModCallback.POST_FAMILIAR_UPDATE (6)
+function postFamiliarUpdate(familiar: EntityFamiliar) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const index = GetPtrHash(familiar);
+  if (!v.run.firedSet.has(index)) {
+    v.run.firedSet.add(index);
+    postFamiliarInitLateFire(familiar);
+  }
+}

package/src/callbacks/postFamiliarStateChanged.ts

@@ -0,0 +1,43 @@
+import { ModCallback } from "isaac-typescript-definitions";
+import { DefaultMap } from "../classes/DefaultMap";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import {
+  postFamiliarStateChangedFire,
+  postFamiliarStateChangedHasSubscriptions,
+} from "./subscriptions/postFamiliarStateChanged";
+
+const v = {
+  run: {
+    familiarStateMap: new DefaultMap<PtrHash, int, [int]>((state) => state),
+  },
+};
+
+/** @internal */
+export function postFamiliarStateChangedCallbackInit(mod: Mod): void {
+  saveDataManager("postFamiliarStateChanged", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_FAMILIAR_UPDATE, postFamiliarUpdate); // 6
+}
+
+function hasSubscriptions() {
+  return postFamiliarStateChangedHasSubscriptions();
+}
+
+// ModCallback.POST_FAMILIAR_UPDATE (6)
+function postFamiliarUpdate(familiar: EntityFamiliar) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  const ptrHash = GetPtrHash(familiar);
+  const previousState = v.run.familiarStateMap.getAndSetDefault(
+    ptrHash,
+    familiar.State,
+  );
+  const currentState = familiar.State;
+  v.run.familiarStateMap.set(ptrHash, currentState);
+
+  if (previousState !== currentState) {
+    postFamiliarStateChangedFire(familiar, previousState, currentState);
+  }
+}

package/src/callbacks/postFlip.ts

@@ -0,0 +1,88 @@
+// This provides the logic for:
+// - PostFlip
+// - PostFirstFlip
+
+import {
+  CollectibleType,
+  ModCallback,
+  PlayerType,
+  UseFlag,
+} from "isaac-typescript-definitions";
+import { saveDataManager } from "../features/saveDataManager/exports";
+import { getPlayersOfType, isTaintedLazarus } from "../functions/player";
+import {
+  postFirstFlipFire,
+  postFirstFlipHasSubscriptions,
+} from "./subscriptions/postFirstFlip";
+import {
+  postFlipFire,
+  postFlipHasSubscriptions,
+} from "./subscriptions/postFlip";
+
+const v = {
+  run: {
+    usedFlipAtLeastOnce: false,
+  },
+};
+
+/** @internal */
+export function postFlipCallbacksInit(mod: Mod): void {
+  saveDataManager("postFlip", v, hasSubscriptions);
+
+  mod.AddCallback(ModCallback.POST_USE_ITEM, useItemFlip, CollectibleType.FLIP); // 3
+}
+
+function hasSubscriptions() {
+  return postFlipHasSubscriptions() || postFirstFlipHasSubscriptions();
+}
+
+// ModCallback.USE_ITEM (3)
+// CollectibleType.FLIP (711)
+function useItemFlip(
+  _collectibleType: CollectibleType,
+  _rng: RNG,
+  player: EntityPlayer,
+  _useFlags: BitFlags<UseFlag>,
+  _activeSlot: int,
+  _customVarData: int,
+) {
+  if (!hasSubscriptions()) {
+    return;
+  }
+
+  if (!isTaintedLazarus(player)) {
+    return;
+  }
+
+  // The player passed as part of the callback will be the old Lazarus that used the Flip item. We
+  // pass the new Lazarus to the callback subscribers.
+  const newLazarus = getNewLazarus(player);
+  if (newLazarus === undefined) {
+    return;
+  }
+
+  if (!v.run.usedFlipAtLeastOnce) {
+    v.run.usedFlipAtLeastOnce = true;
+    postFirstFlipFire(newLazarus);
+  }
+
+  postFlipFire(newLazarus);
+}
+
+function getNewLazarus(oldLazarus: EntityPlayer) {
+  const oldCharacter = oldLazarus.GetPlayerType();
+
+  let newCharacter: PlayerType;
+  if (oldCharacter === PlayerType.LAZARUS_B) {
+    newCharacter = PlayerType.LAZARUS_2_B;
+  } else if (oldCharacter === PlayerType.LAZARUS_2_B) {
+    newCharacter = PlayerType.LAZARUS_B;
+  } else {
+    error("Failed to determine the character in the postFlip callback.");
+  }
+
+  const playersOfType = getPlayersOfType(newCharacter);
+  return playersOfType.find(
+    (player) => player.FrameCount === oldLazarus.FrameCount,
+  );
+}