isaacscript-common 7.10.0 → 7.13.0

package/dist/interfaces/CustomStageTSConfig.d.ts

@@ -119,8 +119,22 @@ export interface CustomStageTSConfig {
      *
      * If not specified, the vanilla Basement decorations spritesheet will be used. For reference,
      * this is located at: `resources/gfx/grid/props_01_basement.png`
+     *
+     * If you want to have custom animations for your decorations, then do not use this field and use
+     * `decorationsANM2Path` instead.
      */
     decorationsPNGPath?: string;
+    /**
+     * Optional. The full path to the anm2 file that contains the custom animations for the
+     * decorations of the floor.
+     *
+     * If not specified, the vanilla Basement decorations spritesheet will be used. For reference,
+     * this is located at: `resources/gfx/grid/props_01_basement.png`
+     *
+     * If you do not want to have custom animations for your decorations, then do not use this field
+     * and use `decorationsPNGPath` instead.
+     */
+    decorationsANM2Path?: string;
     /**
      * Optional. The full path to the spritesheet that contains the graphics of the rocks/blocks/urns
      * for the floor.
@@ -132,16 +146,49 @@ export interface CustomStageTSConfig {
      *
      * If not specified, the vanilla Basement rocks spritesheet will be used. For reference, this is
      * located at: `resources-dlc3/gfx/grid/rocks_basement.png`
+     *
+     * If you want to have custom animations for your rocks, then do not use this field and use
+     * `rocksANM2Path` instead.
      */
     rocksPNGPath?: string;
+    /**
+     * Optional. The full path to the anm2 file that contains the custom animations for the
+     * rocks/blocks/urns of the floor.
+     *
+     * If specified, it is assumed that you have your own custom rock alt type, and all vanilla
+     * rewards/enemies that spawn from urns will be automatically removed. Use the
+     * `POST_GRID_ENTITY_BROKEN` callback to make your own custom rewards. Or, if you want to emulate
+     * a vanilla urn/mushroom/skull/polyp/bucket, use the `spawnRockAltReward` helper function.
+     *
+     * If not specified, the vanilla Basement rocks spritesheet will be used. For reference, this is
+     * located at: `resources-dlc3/gfx/grid/rocks_basement.png`
+     *
+     * If you do not want to have custom animations for your rocks, then do not use this field and use
+     * `rocksPNGPath` instead.
+     */
+    rocksANM2Path?: string;
     /**
      * Optional. The full path to the spritesheet that contains the graphics of the pits for the
      * floor.
      *
      * If not specified, the vanilla Basement pits spritesheet will be used. For reference, this is
      * located at: `resources/gfx/grid/grid_pit.png`
+     *
+     * If you do not want to have custom animations for your pits, then do not use this field and use
+     * `pitsANM2Path` instead.
      */
     pitsPNGPath?: string;
+    /**
+     * Optional. The full path to the anm2 file that contains the custom animations for the pits of
+     * the floor.
+     *
+     * If not specified, the vanilla Basement pits spritesheet will be used. For reference, this is
+     * located at: `resources/gfx/grid/grid_pit.png`
+     *
+     * If you do not want to have custom animations for your pits, then do not use this field and use
+     * `pitsPNGPath` instead.
+     */
+    pitsANM2Path?: string;
     /**
      * Optional. A collection of paths that contain graphics for the doors of the floor. If not
      * specified, the doors for Basement will be used.

package/dist/interfaces/CustomStageTSConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CustomStageTSConfig.d.ts","sourceRoot":"","sources":["../../src/interfaces/CustomStageTSConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CustomStageTSConfig.d.ts","sourceRoot":"","sources":["../../src/interfaces/CustomStageTSConfig.ts"],"names":[],"mappings":"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"}

package/dist/objects/coinSubTypeToValue.d.ts

@@ -1,6 +1,6 @@
 import { CoinSubType } from "isaac-typescript-definitions";
 export declare const DEFAULT_COIN_VALUE = 1;
-export declare const COIN_SUBTYPE_TO_VALUE: {
+export declare const COIN_SUB_TYPE_TO_VALUE: {
     readonly [key in CoinSubType]: int;
 };
 //# sourceMappingURL=coinSubTypeToValue.d.ts.map

package/dist/objects/coinSubTypeToValue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coinSubTypeToValue.d.ts","sourceRoot":"","sources":["../../src/objects/coinSubTypeToValue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,eAAO,MAAM,qBAAqB,EAAE;IAAE,QAAQ,EAAE,GAAG,IAAI,WAAW,GAAG,GAAG;CAS9D,CAAC"}
+{"version":3,"file":"coinSubTypeToValue.d.ts","sourceRoot":"","sources":["../../src/objects/coinSubTypeToValue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,eAAO,MAAM,sBAAsB,EAAE;IAAE,QAAQ,EAAE,GAAG,IAAI,WAAW,GAAG,GAAG;CAS/D,CAAC"}

package/dist/objects/coinSubTypeToValue.lua

@@ -2,7 +2,7 @@ local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local CoinSubType = ____isaac_2Dtypescript_2Ddefinitions.CoinSubType
 ____exports.DEFAULT_COIN_VALUE = 1
-____exports.COIN_SUBTYPE_TO_VALUE = {
+____exports.COIN_SUB_TYPE_TO_VALUE = {
     [CoinSubType.NULL] = 0,
     [CoinSubType.PENNY] = 1,
     [CoinSubType.NICKEL] = 5,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "7.10.0",
+  "version": "7.13.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",

package/src/features/customPickup.ts

@@ -0,0 +1,135 @@
+import {
+  EffectVariant,
+  EntityType,
+  ModCallback,
+  PickupVariant,
+} from "isaac-typescript-definitions";
+import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
+import {
+  getEntityID,
+  getEntityIDFromConstituents,
+} from "../functions/entities";
+import { spawnEffect } from "../functions/entitiesSpecific";
+
+const FEATURE_NAME = "customPickup";
+
+interface CustomPickupFunctions {
+  collectFunc: (player: EntityPlayer) => void;
+  collisionFunc: (player: EntityPlayer) => boolean;
+}
+
+/**
+ * Normally, we would make a custom entity to represent a fading-away pickup, but we don't want to
+ * interfere with the "entities2.xml" file in end-user mods. Thus, we must select a vanilla effect
+ * to masquerade as a backdrop effect.
+ *
+ * We arbitrarily choose a ladder for this purpose because it will not automatically despawn after
+ * time passes, like most other effects.
+ */
+const PICKUP_EFFECT_VARIANT = EffectVariant.LADDER;
+const PICKUP_EFFECT_SUB_TYPE = 103;
+
+/** Indexed by entity ID. */
+const customPickupFunctionsMap = new Map<string, CustomPickupFunctions>();
+
+export function customPickupInit(mod: Mod): void {
+  mod.AddCallback(ModCallback.PRE_PICKUP_COLLISION, prePickupCollision); // 38
+  mod.AddCallback(
+    ModCallback.POST_EFFECT_RENDER,
+    postEffectRenderPickupEffect,
+    PICKUP_EFFECT_VARIANT,
+  ); // 56
+}
+
+// ModCallback.PRE_PICKUP_COLLISION (38)
+function prePickupCollision(
+  pickup: EntityPickup,
+  collider: Entity,
+): boolean | undefined {
+  const entityID = getEntityID(pickup);
+  const customPickupFunctions = customPickupFunctionsMap.get(entityID);
+  if (customPickupFunctions === undefined) {
+    return undefined;
+  }
+
+  const player = collider.ToPlayer();
+  if (player === undefined) {
+    return undefined;
+  }
+
+  const shouldPickup = customPickupFunctions.collisionFunc(player);
+  if (!shouldPickup) {
+    return undefined;
+  }
+
+  pickup.Remove();
+
+  const pickupSprite = pickup.GetSprite();
+  const fileName = pickupSprite.GetFilename();
+
+  const effect = spawnEffect(
+    PICKUP_EFFECT_VARIANT,
+    PICKUP_EFFECT_SUB_TYPE,
+    pickup.Position,
+  );
+  const effectSprite = effect.GetSprite();
+  effectSprite.Load(fileName, true);
+  effectSprite.Play("Collect", true);
+
+  customPickupFunctions.collectFunc(player);
+
+  return undefined;
+}
+
+// ModCallback.POST_EFFECT_RENDER (56)
+// PICKUP_EFFECT_VARIANT
+function postEffectRenderPickupEffect(effect: EntityEffect) {
+  if (effect.SubType !== PICKUP_EFFECT_SUB_TYPE) {
+    return;
+  }
+
+  const sprite = effect.GetSprite();
+  if (sprite.IsFinished("Collect")) {
+    effect.Remove();
+  }
+}
+
+/**
+ * Helper function to register a custom pickup with the IsaacScript standard library. Use this
+ * feature for custom pickups that are intended to be picked up by the player, like keys and bombs.
+ *
+ * When IsaacScript detects that a player should be collecting the custom pickup, then the pickup
+ * will be immediately removed, and an effect showing the pickup's respective `Collect` animation
+ * will be spawned. (This emulates how a normal vanilla pickup would work.)
+ *
+ * Note that when you specify your custom pickup in the "entities2.xml" file, it should have a type
+ * of "5" and be associated with an anm2 file that has a "Collect" animation.
+ *
+ * @param pickupVariantCustom The variant for the corresponding custom pickup.
+ * @param subType The sub-type for the corresponding custom pickup.
+ * @param collectFunc The function to run when the player collects this pickup.
+ * @param collisionFunc Optional. The function to run when a player collides with the pickup.
+ *                      Default is a function that always returns true, meaning that the player will
+ *                      always immediately collect the pickup when they collide with it. Specify
+ *                      this function if your pickup should only be able to be collected under
+ *                      certain conditions.
+ */
+export function registerCustomPickup(
+  pickupVariantCustom: PickupVariant,
+  subType: int,
+  collectFunc: (player: EntityPlayer) => void,
+  collisionFunc: (player: EntityPlayer) => boolean = () => true,
+): void {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
+  const entityID = getEntityIDFromConstituents(
+    EntityType.PICKUP,
+    pickupVariantCustom,
+    subType,
+  );
+  const customPickupFunctions: CustomPickupFunctions = {
+    collectFunc,
+    collisionFunc,
+  };
+  customPickupFunctionsMap.set(entityID, customPickupFunctions);
+}

package/src/features/customStage/backdrop.ts

@@ -14,7 +14,7 @@ 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 { removeCharactersBefore, trimPrefix } from "../../functions/string";
 import { erange, irange } from "../../functions/utils";
 import { CustomStage } from "../../interfaces/private/CustomStage";
 import { ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH } from "./customStageConstants";
@@ -83,7 +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_EFFECT_SUB_TYPE = 101;
 
 const BACKDROP_ROOM_TYPE_SET: ReadonlySet<RoomType> = new Set([
   RoomType.DEFAULT,
@@ -118,7 +118,8 @@ function getBackdropPNGPath(
       : customStage.backdropPNGPaths;
 
   const pathArray = backdrop[backdropKind];
-  return getRandomArrayElement(pathArray, rng);
+  const randomPath = getRandomArrayElement(pathArray, rng);
+  return removeCharactersBefore(randomPath, "gfx/");
 }
 
 function spawnWallEntity(
@@ -134,7 +135,7 @@ function spawnWallEntity(
   const seed = 1 as Seed;
   const wallEffect = spawnEffectWithSeed(
     BACKDROP_EFFECT_VARIANT,
-    BACKDROP_EFFECT_SUBTYPE,
+    BACKDROP_EFFECT_SUB_TYPE,
     VectorZero,
     seed,
   );

package/src/features/customStage/customStageGridEntities.ts

@@ -14,6 +14,7 @@ import {
   getTrinkets,
 } from "../../functions/pickupsSpecific";
 import { calculateStageType } from "../../functions/stage";
+import { removeCharactersBefore } from "../../functions/string";
 import { vectorEquals } from "../../functions/vector";
 import { CustomStage } from "../../interfaces/private/CustomStage";
 import { isCustomGridEntity } from "../customGridEntity";
@@ -31,7 +32,10 @@ export function setCustomDecorationGraphics(
 ): void {
   // If the end-user did not specify custom decoration graphics, default to Basement graphics. (We
   // don't have to adjust anything for this case.)
-  if (customStage.decorationsPNGPath === undefined) {
+  if (
+    customStage.decorationsPNGPath === undefined &&
+    customStage.decorationsANM2Path === undefined
+  ) {
     return;
   }
 
@@ -47,8 +51,22 @@ export function setCustomDecorationGraphics(
   const sprite = gridEntity.GetSprite();
   const fileName = sprite.GetFilename();
   // On Windows, this is: gfx/grid/Props_01_Basement.anm2
-  if (fileName.toLowerCase() === "gfx/grid/props_01_basement.anm2") {
-    sprite.ReplaceSpritesheet(0, customStage.decorationsPNGPath);
+  if (fileName.toLowerCase() !== "gfx/grid/props_01_basement.anm2") {
+    return;
+  }
+
+  if (customStage.decorationsANM2Path !== undefined) {
+    const anm2Path = removeCharactersBefore(
+      customStage.decorationsANM2Path,
+      "gfx/",
+    );
+    sprite.Load(anm2Path, true);
+  } else if (customStage.decorationsPNGPath !== undefined) {
+    const pngPath = removeCharactersBefore(
+      customStage.decorationsPNGPath,
+      "gfx/",
+    );
+    sprite.ReplaceSpritesheet(0, pngPath);
     sprite.LoadGraphics();
   }
 }
@@ -60,7 +78,10 @@ export function setCustomRockGraphics(
 ): void {
   // If the end-user did not specify custom rock graphics, default to Basement graphics. (We don't
   // have to adjust anything for this case.)
-  if (customStage.rocksPNGPath === undefined) {
+  if (
+    customStage.rocksPNGPath === undefined &&
+    customStage.rocksANM2Path === undefined
+  ) {
     return;
   }
 
@@ -75,12 +96,41 @@ export function setCustomRockGraphics(
 
   const sprite = gridEntity.GetSprite();
   const fileName = sprite.GetFilename();
-  if (fileName === "gfx/grid/grid_rock.anm2") {
-    sprite.ReplaceSpritesheet(0, customStage.rocksPNGPath);
-    sprite.LoadGraphics();
-  } else if (fileName === "gfx/grid/grid_pit.anm2") {
-    sprite.ReplaceSpritesheet(1, customStage.rocksPNGPath);
-    sprite.LoadGraphics();
+
+  switch (fileName) {
+    case "gfx/grid/grid_rock.anm2": {
+      // The normal case of a rock.
+      if (customStage.rocksANM2Path !== undefined) {
+        const anm2Path = removeCharactersBefore(
+          customStage.rocksANM2Path,
+          "gfx/",
+        );
+        sprite.Load(anm2Path, true);
+      } else if (customStage.rocksPNGPath !== undefined) {
+        const pngPath = removeCharactersBefore(
+          customStage.rocksPNGPath,
+          "gfx/",
+        );
+        sprite.ReplaceSpritesheet(0, pngPath);
+        sprite.LoadGraphics();
+      }
+
+      break;
+    }
+
+    case "gfx/grid/grid_pit.anm2": {
+      // The case of when a rock is blown on a pit to make a bridge.
+      if (customStage.rocksPNGPath !== undefined) {
+        const pngPath = removeCharactersBefore(
+          customStage.rocksPNGPath,
+          "gfx/",
+        );
+        sprite.ReplaceSpritesheet(1, pngPath);
+        sprite.LoadGraphics();
+      }
+
+      break;
+    }
   }
 }
 
@@ -95,6 +145,8 @@ export function setCustomPitGraphics(
     return;
   }
 
+  const pngPath = removeCharactersBefore(customStage.pitsPNGPath, "gfx/");
+
   if (isCustomGridEntity(gridEntity)) {
     return;
   }
@@ -107,7 +159,7 @@ export function setCustomPitGraphics(
   const sprite = gridEntity.GetSprite();
   const fileName = sprite.GetFilename();
   if (fileName === "gfx/grid/grid_pit.anm2") {
-    sprite.ReplaceSpritesheet(0, customStage.pitsPNGPath);
+    sprite.ReplaceSpritesheet(0, pngPath);
     sprite.LoadGraphics();
   }
 }
@@ -136,7 +188,8 @@ export function setCustomDoorGraphics(
   const fileName = sprite.GetFilename();
   const doorPNGPath = getNewDoorPNGPath(customStage, fileName);
   if (doorPNGPath !== undefined) {
-    sprite.ReplaceSpritesheet(0, doorPNGPath);
+    const fixedPath = removeCharactersBefore(doorPNGPath, "gfx/");
+    sprite.ReplaceSpritesheet(0, fixedPath);
     sprite.LoadGraphics();
   }
 }

package/src/features/customStage/shadows.ts

@@ -2,6 +2,7 @@ import { EffectVariant, RoomShape } from "isaac-typescript-definitions";
 import { game } from "../../core/cachedClasses";
 import { getRandomArrayElement } from "../../functions/array";
 import { spawnEffectWithSeed } from "../../functions/entitiesSpecific";
+import { removeCharactersBefore } from "../../functions/string";
 import { CustomStage } from "../../interfaces/private/CustomStage";
 import { ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH } from "./customStageConstants";
 import v from "./v";
@@ -17,7 +18,7 @@ type ShadowAnimation = "1x1" | "1x2" | "2x1" | "2x2";
  * time passes, like most other effects.
  */
 const SHADOW_EFFECT_VARIANT = EffectVariant.LADDER;
-const SHADOW_EFFECT_SUBTYPE = 102;
+const SHADOW_EFFECT_SUB_TYPE = 102;
 
 /** The animation comes from StageAPI. */
 const ROOM_SHAPE_TO_SHADOW_ANIMATION: {
@@ -59,7 +60,7 @@ export function setShadows(customStage: CustomStage): void {
   const seed = 1 as Seed;
   const shadowEffect = spawnEffectWithSeed(
     SHADOW_EFFECT_VARIANT,
-    SHADOW_EFFECT_SUBTYPE,
+    SHADOW_EFFECT_SUB_TYPE,
     centerPos,
     seed,
   );
@@ -68,7 +69,8 @@ export function setShadows(customStage: CustomStage): void {
   sprite.Load(`${ISAACSCRIPT_CUSTOM_STAGE_GFX_PATH}/stage-shadow.anm2`, false);
   const decorationSeed = room.GetDecorationSeed();
   const shadow = getRandomArrayElement(shadows, decorationSeed);
-  sprite.ReplaceSpritesheet(0, shadow.pngPath);
+  const pngPath = removeCharactersBefore(shadow.pngPath, "gfx/");
+  sprite.ReplaceSpritesheet(0, pngPath);
   sprite.LoadGraphics();
   sprite.SetFrame(animation, 0);
   sprite.Color =

package/src/features/customStage/versusScreen.ts

@@ -10,6 +10,7 @@ import { game, sfxManager } from "../../core/cachedClasses";
 import { arrayRemove } from "../../functions/array";
 import { getBosses } from "../../functions/bosses";
 import { getRoomSubType } from "../../functions/roomData";
+import { removeCharactersBefore } from "../../functions/string";
 import { erange } from "../../functions/utils";
 import { CustomStage } from "../../interfaces/private/CustomStage";
 import { BOSS_NAME_PNG_FILE_NAMES } from "../../objects/bossNamePNGFileNames";
@@ -155,10 +156,18 @@ export function playVersusScreenAnimation(customStage: CustomStage): void {
   // Boss
   {
     const { namePNGPath, portraitPNGPath } = getBossPNGPaths(customStage);
-    versusScreenSprite.ReplaceSpritesheet(BOSS_NAME_ANM2_LAYER, namePNGPath);
+    const trimmedNamePNGPath = removeCharactersBefore(namePNGPath, "gfx/");
     versusScreenSprite.ReplaceSpritesheet(
-      BOSS_PORTRAIT_ANM2_LAYER,
+      BOSS_NAME_ANM2_LAYER,
+      trimmedNamePNGPath,
+    );
+    const trimmedPortraitPNGPath = removeCharactersBefore(
       portraitPNGPath,
+      "gfx/",
+    );
+    versusScreenSprite.ReplaceSpritesheet(
+      BOSS_PORTRAIT_ANM2_LAYER,
+      trimmedPortraitPNGPath,
     );
   }
 

package/src/functions/npcs.ts

@@ -41,7 +41,7 @@ const NON_ALIVE_NPCS_TYPE_VARIANT: ReadonlySet<string> = new Set([
  * Used to filter out certain NPCs when determining of an NPC is "alive" and/or should keep the
  * doors open.
  */
-const NON_ALIVE_NPCS_TYPE_VARIANT_SUBTYPE: ReadonlySet<string> = new Set([
+const NON_ALIVE_NPCS_TYPE_VARIANT_SUB_TYPE: ReadonlySet<string> = new Set([
   `${EntityType.CHARGER}.${ChargerVariant.CHARGER}.${ChargerSubType.MY_SHADOW}`, // 23.0.1
   `${EntityType.MOTHER}.${MotherVariant.MOTHER_1}.${MotherSubType.PHASE_2}`, // 912
 ]);
@@ -81,7 +81,7 @@ export function isAliveExceptionNPC(npc: EntityNPC): boolean {
   }
 
   const entityTypeVariantSubType = `${npc.Type}.${npc.Variant}.${npc.SubType}`;
-  if (NON_ALIVE_NPCS_TYPE_VARIANT_SUBTYPE.has(entityTypeVariantSubType)) {
+  if (NON_ALIVE_NPCS_TYPE_VARIANT_SUB_TYPE.has(entityTypeVariantSubType)) {
     return true;
   }
 

package/src/functions/pickups.ts

@@ -1,6 +1,6 @@
 import { CoinSubType } from "isaac-typescript-definitions";
 import {
-  COIN_SUBTYPE_TO_VALUE,
+  COIN_SUB_TYPE_TO_VALUE,
   DEFAULT_COIN_VALUE,
 } from "../objects/coinSubTypeToValue";
 import { CHEST_PICKUP_VARIANTS } from "../sets/chestPickupVariantsSet";
@@ -14,7 +14,7 @@ import { isHeart } from "./pickupVariants";
  * sub-types.
  */
 export function getCoinValue(coinSubType: CoinSubType): int {
-  const value = COIN_SUBTYPE_TO_VALUE[coinSubType];
+  const value = COIN_SUB_TYPE_TO_VALUE[coinSubType];
   // Handle modded coin sub-types.
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   return value === undefined ? DEFAULT_COIN_VALUE : value;

package/src/functions/string.ts

@@ -10,6 +10,18 @@ export function removeAllCharacters(string: string, character: string): string {
   return string.replaceAll(character, "");
 }
 
+/**
+ * Helper function to remove all of the characters in a string before a given substring. Returns the
+ * modified string.
+ */
+export function removeCharactersBefore(
+  string: string,
+  substring: string,
+): string {
+  const index = string.indexOf(substring);
+  return string.slice(index);
+}
+
 /**
  * Helper function to remove one or more substrings from a string, if they exist. Returns the
  * modified string.

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   removeCustomGridEntity,
   spawnCustomGridEntity,
 } from "./features/customGridEntity";
+export { registerCustomPickup } from "./features/customPickup";
 export * from "./features/customStage/exports";
 export * from "./features/customTrapdoor/exports";
 export * from "./features/debugDisplay/exports";

package/src/initFeatures.ts

@@ -3,6 +3,7 @@ import { characterHealthConversionInit } from "./features/characterHealthConvers
 import { characterStatsInit } from "./features/characterStats";
 import { collectibleItemPoolTypeInit } from "./features/collectibleItemPoolType";
 import { customGridEntityInit } from "./features/customGridEntity";
+import { customPickupInit } from "./features/customPickup";
 import { customStageInit } from "./features/customStage/init";
 import { customTrapdoorInit } from "./features/customTrapdoor/init";
 import { deployJSONRoomInit } from "./features/deployJSONRoom";
@@ -42,6 +43,7 @@ function initFeaturesMajor(mod: ModUpgraded) {
 }
 
 function initFeaturesMinor(mod: ModUpgraded) {
+  customPickupInit(mod);
   customTrapdoorInit(mod);
   disableAllSoundInit(mod);
   disableInputsInit(mod);

package/src/interfaces/CustomStageTSConfig.ts

@@ -132,9 +132,24 @@ export interface CustomStageTSConfig {
    *
    * If not specified, the vanilla Basement decorations spritesheet will be used. For reference,
    * this is located at: `resources/gfx/grid/props_01_basement.png`
+   *
+   * If you want to have custom animations for your decorations, then do not use this field and use
+   * `decorationsANM2Path` instead.
    */
   decorationsPNGPath?: string;
 
+  /**
+   * Optional. The full path to the anm2 file that contains the custom animations for the
+   * decorations of the floor.
+   *
+   * If not specified, the vanilla Basement decorations spritesheet will be used. For reference,
+   * this is located at: `resources/gfx/grid/props_01_basement.png`
+   *
+   * If you do not want to have custom animations for your decorations, then do not use this field
+   * and use `decorationsPNGPath` instead.
+   */
+  decorationsANM2Path?: string;
+
   /**
    * Optional. The full path to the spritesheet that contains the graphics of the rocks/blocks/urns
    * for the floor.
@@ -146,18 +161,53 @@ export interface CustomStageTSConfig {
    *
    * If not specified, the vanilla Basement rocks spritesheet will be used. For reference, this is
    * located at: `resources-dlc3/gfx/grid/rocks_basement.png`
+   *
+   * If you want to have custom animations for your rocks, then do not use this field and use
+   * `rocksANM2Path` instead.
    */
   rocksPNGPath?: string;
 
+  /**
+   * Optional. The full path to the anm2 file that contains the custom animations for the
+   * rocks/blocks/urns of the floor.
+   *
+   * If specified, it is assumed that you have your own custom rock alt type, and all vanilla
+   * rewards/enemies that spawn from urns will be automatically removed. Use the
+   * `POST_GRID_ENTITY_BROKEN` callback to make your own custom rewards. Or, if you want to emulate
+   * a vanilla urn/mushroom/skull/polyp/bucket, use the `spawnRockAltReward` helper function.
+   *
+   * If not specified, the vanilla Basement rocks spritesheet will be used. For reference, this is
+   * located at: `resources-dlc3/gfx/grid/rocks_basement.png`
+   *
+   * If you do not want to have custom animations for your rocks, then do not use this field and use
+   * `rocksPNGPath` instead.
+   */
+  rocksANM2Path?: string;
+
   /**
    * Optional. The full path to the spritesheet that contains the graphics of the pits for the
    * floor.
    *
    * If not specified, the vanilla Basement pits spritesheet will be used. For reference, this is
    * located at: `resources/gfx/grid/grid_pit.png`
+   *
+   * If you do not want to have custom animations for your pits, then do not use this field and use
+   * `pitsANM2Path` instead.
    */
   pitsPNGPath?: string;
 
+  /**
+   * Optional. The full path to the anm2 file that contains the custom animations for the pits of
+   * the floor.
+   *
+   * If not specified, the vanilla Basement pits spritesheet will be used. For reference, this is
+   * located at: `resources/gfx/grid/grid_pit.png`
+   *
+   * If you do not want to have custom animations for your pits, then do not use this field and use
+   * `pitsPNGPath` instead.
+   */
+  pitsANM2Path?: string;
+
   /**
    * Optional. A collection of paths that contain graphics for the doors of the floor. If not
    * specified, the doors for Basement will be used.

package/src/objects/coinSubTypeToValue.ts

@@ -2,7 +2,7 @@ import { CoinSubType } from "isaac-typescript-definitions";
 
 export const DEFAULT_COIN_VALUE = 1;
 
-export const COIN_SUBTYPE_TO_VALUE: { readonly [key in CoinSubType]: int } = {
+export const COIN_SUB_TYPE_TO_VALUE: { readonly [key in CoinSubType]: int } = {
   [CoinSubType.NULL]: 0, // 0
   [CoinSubType.PENNY]: 1, // 1
   [CoinSubType.NICKEL]: 5, // 2