isaacscript-common 6.20.2 → 6.22.1

package/src/callbacks/subscriptions/postSpikesUpdate.ts

@@ -5,19 +5,16 @@ export type PostSpikesUpdateRegisterParameters = [
 
 const subscriptions: PostSpikesUpdateRegisterParameters[] = [];
 
-/** @internal */
 export function postSpikesUpdateHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function postSpikesUpdateRegister(
   ...args: PostSpikesUpdateRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function postSpikesUpdateFire(spikes: GridEntitySpikes): void {
   const gridEntityVariant = spikes.GetVariant();
 

package/src/callbacks/subscriptions/postTNTRender.ts

@@ -5,19 +5,16 @@ export type PostTNTRenderRegisterParameters = [
 
 const subscriptions: PostTNTRenderRegisterParameters[] = [];
 
-/** @internal */
 export function postTNTRenderHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function postTNTRenderRegister(
   ...args: PostTNTRenderRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function postTNTRenderFire(tnt: GridEntityTNT): void {
   const gridEntityVariant = tnt.GetVariant();
 

package/src/callbacks/subscriptions/postTNTUpdate.ts

@@ -5,19 +5,16 @@ export type PostTNTUpdateRegisterParameters = [
 
 const subscriptions: PostTNTUpdateRegisterParameters[] = [];
 
-/** @internal */
 export function postTNTUpdateHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function postTNTUpdateRegister(
   ...args: PostTNTUpdateRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function postTNTUpdateFire(tnt: GridEntityTNT): void {
   const gridEntityVariant = tnt.GetVariant();
 

package/src/callbacks/subscriptions/postTearInitLate.ts

@@ -7,19 +7,16 @@ export type PostTearInitLateRegisterParameters = [
 
 const subscriptions: PostTearInitLateRegisterParameters[] = [];
 
-/** @internal */
 export function postTearInitLateHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function postTearInitLateRegister(
   ...args: PostTearInitLateRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function postTearInitLateFire(tear: EntityTear): void {
   for (const [callback, tearVariant] of subscriptions) {
     // Handle the optional 2nd callback argument.

package/src/callbacks/subscriptions/postTearInitVeryLate.ts

@@ -7,19 +7,16 @@ export type PostTearInitVeryLateRegisterParameters = [
 
 const subscriptions: PostTearInitVeryLateRegisterParameters[] = [];
 
-/** @internal */
 export function postTearInitVeryLateHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function postTearInitVeryLateRegister(
   ...args: PostTearInitVeryLateRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function postTearInitVeryLateFire(tear: EntityTear): void {
   for (const [callback, tearVariant] of subscriptions) {
     // Handle the optional 2nd callback argument.

package/src/callbacks/subscriptions/postTransformation.ts

@@ -11,19 +11,16 @@ export type PostTransformationRegisterParameters = [
 
 const subscriptions: PostTransformationRegisterParameters[] = [];
 
-/** @internal */
 export function postTransformationHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function postTransformationRegister(
   ...args: PostTransformationRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function postTransformationFire(
   player: EntityPlayer,
   playerForm: PlayerForm,

package/src/callbacks/subscriptions/postTrinketBreak.ts

@@ -7,19 +7,16 @@ export type PostTrinketBreakRegisterParameters = [
 
 const subscriptions: PostTrinketBreakRegisterParameters[] = [];
 
-/** @internal */
 export function postTrinketBreakHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function postTrinketBreakRegister(
   ...args: PostTrinketBreakRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function postTrinketBreakFire(
   player: EntityPlayer,
   trinketType: TrinketType,

package/src/callbacks/subscriptions/preBerserkDeath.ts

@@ -8,19 +8,16 @@ export type PreBerserkDeathRegisterParameters = [
 
 const subscriptions: PreBerserkDeathRegisterParameters[] = [];
 
-/** @internal */
 export function preBerserkDeathHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function preBerserkDeathRegister(
   ...args: PreBerserkDeathRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function preBerserkDeathFire(player: EntityPlayer): void {
   const character = player.GetPlayerType();
 

package/src/callbacks/subscriptions/preCustomRevive.ts

@@ -8,19 +8,16 @@ export type PreCustomReviveRegisterParameters = [
 
 const subscriptions: PreCustomReviveRegisterParameters[] = [];
 
-/** @internal */
 export function preCustomReviveHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function preCustomReviveRegister(
   ...args: PreCustomReviveRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function preCustomReviveFire(player: EntityPlayer): int | undefined {
   const character = player.GetPlayerType();
 

package/src/callbacks/subscriptions/preItemPickup.ts

@@ -30,19 +30,16 @@ export type PreItemPickupRegisterParameters =
 
 const subscriptions: PreItemPickupRegisterParameters[] = [];
 
-/** @internal */
 export function preItemPickupHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function preItemPickupRegister(
   ...args: PreItemPickupRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function preItemPickupFire(
   player: EntityPlayer,
   pickingUpItem: PickingUpItem,

package/src/callbacks/subscriptions/preNewLevel.ts

@@ -4,19 +4,16 @@ export type PreNewLevelRegisterParameters = [
 
 const subscriptions: PreNewLevelRegisterParameters[] = [];
 
-/** @internal */
 export function preNewLevelHasSubscriptions(): boolean {
   return subscriptions.length > 0;
 }
 
-/** @internal */
 export function preNewLevelRegister(
   ...args: PreNewLevelRegisterParameters
 ): void {
   subscriptions.push(args);
 }
 
-/** @internal */
 export function preNewLevelFire(player: EntityPlayer): void {
   for (const [callback] of subscriptions) {
     callback(player);

package/src/classes/ModUpgraded.ts

@@ -1,6 +1,6 @@
 import { ModCallback } from "isaac-typescript-definitions";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
-import { AddCallbackParameterCustom } from "../interfaces/AddCallbackParameterCustom";
+import { AddCallbackParameterCustom } from "../interfaces/private/AddCallbackParameterCustom";
 import { CALLBACK_REGISTER_FUNCTIONS } from "../objects/callbackRegisterFunctions";
 
 /**

package/src/classes/index.ts

@@ -0,0 +1,2 @@
+export * from "./DefaultMap";
+export * from "./ModUpgraded";

package/src/classes/indexTypeDoc.ts

@@ -0,0 +1,2 @@
+export * as DefaultMap from "./DefaultMap";
+export * as ModUpgraded from "./ModUpgraded";

package/src/{constants.ts → core/constants.ts}

@@ -5,10 +5,16 @@ import {
   ItemPoolType,
   TrinketSlot,
 } from "isaac-typescript-definitions";
+import { getEnumLength } from "../functions/enums";
+import { addFlag } from "../functions/flag";
 import { NUM_NORMAL_PILL_COLORS } from "./constantsFirstLast";
-import { getEnumLength } from "./functions/enums";
-import { addFlag } from "./functions/flag";
 
+/**
+ * The combination of the following flags:
+ * - `DisplayFlag.VISIBLE` (1 << 0)
+ * - `DisplayFlag.SHADOW` (1 << 1)
+ * - `DisplayFlag.SHOW_ICON` (1 << 2)
+ */
 export const ALL_DISPLAY_FLAGS = addFlag(
   DisplayFlag.VISIBLE,
   DisplayFlag.SHADOW,

package/src/{constantsFirstLast.ts → core/constantsFirstLast.ts}

@@ -8,8 +8,8 @@ import {
   RoomType,
   TrinketType,
 } from "isaac-typescript-definitions";
+import { getEnumLength, getLastEnumValue } from "../functions/enums";
 import { itemConfig } from "./cachedClasses";
-import { getEnumLength, getLastEnumValue } from "./functions/enums";
 
 // ------------
 // Collectibles
@@ -21,8 +21,8 @@ export const FIRST_COLLECTIBLE_TYPE = CollectibleType.SAD_ONION;
 /**
  * Will change depending on how many modded collectibles there are.
  *
- * Equal to `itemConfig.GetCollectibles().Size - 1`. (`Size` includes invalid collectibles. We
- * subtract one to account for `CollectibleType.NULL`.)
+ * Equal to `itemConfig.GetCollectibles().Size - 1`. (`Size` includes invalid collectibles, like
+ * 666. We subtract one to account for `CollectibleType.NULL`.)
  */
 export const LAST_COLLECTIBLE_TYPE = (itemConfig.GetCollectibles().Size -
   1) as CollectibleType;

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from "./cachedClasses";
+export * from "./constants";
+export * from "./constantsFirstLast";
+export * from "./upgradeMod";

package/src/core/indexTypeDoc.ts

@@ -0,0 +1,4 @@
+export * as CachedClasses from "./cachedClasses";
+export * as Constants from "./constants";
+export * as ConstantsFirstLast from "./constantsFirstLast";
+export * as UpgradeMod from "./upgradeMod";

package/src/{upgradeMod.ts → core/upgradeMod.ts}

@@ -1,14 +1,14 @@
-import { postNewRoomEarlyCallbackInit } from "./callbacks/postNewRoomEarly";
-import { ModUpgraded } from "./classes/ModUpgraded";
-import { saveDataManagerInit } from "./features/saveDataManager/main";
+import { postNewRoomEarlyCallbackInit } from "../callbacks/postNewRoomEarly";
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { saveDataManagerInit } from "../features/saveDataManager/main";
 import {
   areFeaturesInitialized,
   setFeaturesInitialized,
-} from "./featuresInitialized";
-import { initCustomCallbacks } from "./initCustomCallbacks";
-import { initFeatures } from "./initFeatures";
-import { patchErrorFunction } from "./patchErrorFunctions";
-import { loadShaderCrashFix } from "./shaderCrashFix";
+} from "../featuresInitialized";
+import { initCustomCallbacks } from "../initCustomCallbacks";
+import { initFeatures } from "../initFeatures";
+import { patchErrorFunction } from "../patchErrorFunctions";
+import { loadShaderCrashFix } from "../shaderCrashFix";
 
 /**
  * Use this function to enable the custom callbacks and other optional features provided by

package/src/enums/RockAltType.ts

@@ -3,5 +3,18 @@ export enum RockAltType {
   MUSHROOM,
   SKULL,
   POLYP,
-  BUCKET,
+
+  /**
+   * Destroying buckets in Downpour give different outcomes than in Dross.
+   *
+   * See: https://bindingofisaacrebirth.fandom.com/wiki/Rocks#Buckets
+   */
+  BUCKET_DOWNPOUR,
+
+  /**
+   * Destroying buckets in Dross give different outcomes than in Downpour.
+   *
+   * See: https://bindingofisaacrebirth.fandom.com/wiki/Rocks#Buckets
+   */
+  BUCKET_DROSS,
 }

package/src/enums/index.ts

@@ -0,0 +1,8 @@
+export * from "./AmbushType";
+export * from "./CornerType";
+export * from "./HealthType";
+export * from "./ModCallbackCustom";
+export * from "./PocketItemType";
+export * from "./RockAltType";
+export * from "./SerializationType";
+export * from "./SlotDestructionType";

package/src/enums/indexTypeDoc.ts

@@ -0,0 +1,8 @@
+export * as AmbushType from "./AmbushType";
+export * as CornerType from "./CornerType";
+export * as HealthType from "./HealthType";
+export * as ModCallbackCustom from "./ModCallbackCustom";
+export * as PocketItemType from "./PocketItemType";
+export * as RockAltType from "./RockAltType";
+export * as SerializationType from "./SerializationType";
+export * as SlotDestructionType from "./SlotDestructionType";

package/src/enums/private/StageTravelState.ts

@@ -2,7 +2,8 @@ export enum StageTravelState {
   NONE,
   PLAYERS_JUMPING_DOWN,
   PIXELATION_TO_BLACK,
-  PAUSING_ON_BLACK,
+  WAITING_FOR_FIRST_PIXELATION_TO_END,
+  WAITING_FOR_SECOND_PIXELATION_TO_GET_HALF_WAY,
   PIXELATION_TO_ROOM,
   PLAYERS_LAYING_DOWN,
 }

package/src/features/characterHealthConversion.ts

@@ -23,7 +23,6 @@ const characterHealthReplacementMap = new Map<
   ConversionHeartSubType
 >();
 
-/** @internal */
 export function characterHealthConversionInit(mod: Mod): void {
   mod.AddCallback(ModCallback.POST_PEFFECT_UPDATE, postPEffectUpdate); // 4
   mod.AddCallback(

package/src/features/characterStats.ts

@@ -18,7 +18,6 @@ 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
 }

package/src/features/collectibleItemPoolType.ts

@@ -7,7 +7,7 @@ import {
   ModCallback,
   PickupVariant,
 } from "isaac-typescript-definitions";
-import { game } from "../cachedClasses";
+import { game } from "../core/cachedClasses";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
 import { getEntityID } from "../functions/entities";
 import { isCollectible } from "../functions/pickupVariants";
@@ -22,7 +22,6 @@ const v = {
   },
 };
 
-/** @internal */
 export function collectibleItemPoolTypeInit(mod: Mod): void {
   saveDataManager(FEATURE_NAME, v);
 

package/src/features/customDoor.ts

@@ -0,0 +1,66 @@
+import { DoorSlot, EffectVariant } from "isaac-typescript-definitions";
+import {
+  initCustomDoorInternal,
+  spawnCustomDoorInternal,
+} from "../callbacks/postCustomDoorEnter";
+import { ModUpgraded } from "../classes/ModUpgraded";
+
+/**
+ * `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 {
+  initCustomDoorInternal(mod, effectVariant);
+}
+
+/**
+ * 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 run-time 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 {
+  return spawnCustomDoorInternal(effectVariant, doorSlot);
+}

package/src/features/customGridEntity.ts

@@ -9,10 +9,10 @@ import {
   ModCallback,
   UseFlag,
 } from "isaac-typescript-definitions";
-import { game } from "../cachedClasses";
 import { postGridEntityCustomBrokenFire } from "../callbacks/subscriptions/postGridEntityCustomBroken";
 import { DefaultMap } from "../classes/DefaultMap";
 import { ModUpgraded } from "../classes/ModUpgraded";
+import { game } from "../core/cachedClasses";
 import { DecorationVariant } from "../enums/DecorationVariant";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
@@ -45,7 +45,6 @@ const v = {
   },
 };
 
-/** @internal */
 export function customGridEntityInit(mod: ModUpgraded): void {
   saveDataManager(FEATURE_NAME, v);
 

package/src/features/customStage/backdrop.ts

@@ -8,15 +8,15 @@ import {
   RoomShape,
   RoomType,
 } from "isaac-typescript-definitions";
-import { game } from "../../cachedClasses";
-import { VectorZero } from "../../constants";
+import { game } from "../../core/cachedClasses";
+import { VectorZero } from "../../core/constants";
 import { getRandomArrayElement } from "../../functions/array";
 import { spawnEffectWithSeed } from "../../functions/entitiesSpecific";
 import { newRNG } from "../../functions/rng";
 import { isLRoom, isNarrowRoom } from "../../functions/roomShape";
 import { trimPrefix } from "../../functions/string";
 import { erange, irange } from "../../functions/utils";
-import { CustomStage } from "../../interfaces/CustomStage";
+import { CustomStage } from "../../interfaces/private/CustomStage";
 import { ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH } from "./customStageConstants";
 
 enum BackdropKind {
@@ -83,6 +83,7 @@ const N_FLOOR_ANM2_LAYERS: readonly int[] = [18, 19];
  * time passes, like most other effects.
  */
 const BACKDROP_EFFECT_VARIANT = EffectVariant.LADDER;
+const BACKDROP_EFFECT_SUBTYPE = 101;
 
 const BACKDROP_ROOM_TYPE_SET: ReadonlySet<RoomType> = new Set([
   RoomType.DEFAULT,
@@ -132,7 +133,7 @@ function spawnWallEntity(
   // does this. (`EntityFlag.RENDER_WALL` is intended for this purpose.)
   const wallEffect = spawnEffectWithSeed(
     BACKDROP_EFFECT_VARIANT,
-    0,
+    BACKDROP_EFFECT_SUBTYPE,
     VectorZero,
     1 as Seed,
   );

package/src/features/customStage/customStageConstants.ts

@@ -1 +1,17 @@
 export const ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH = "gfx/isaacscript-custom-stage";
+
+/** Corresponds to "ui_streak.anm2". */
+export enum UIStreakAnimation {
+  NONE,
+  TEXT,
+  TEXT_STAY,
+}
+
+/** Corresponds to "ui_streak.anm2". */
+export const UI_STREAK_ANIMATION_END_FRAMES: {
+  readonly [key in UIStreakAnimation]: int;
+} = {
+  [UIStreakAnimation.NONE]: 0,
+  [UIStreakAnimation.TEXT]: 69,
+  [UIStreakAnimation.TEXT_STAY]: 1,
+} as const;