isaacscript-common 9.3.0 → 9.5.0

package/src/enums/ModCallbackCustom.ts

@@ -356,8 +356,10 @@ export enum ModCallbackCustom {
    * For grid entities created with `spawnCustomGridEntity`, use the
    * `POST_GRID_ENTITY_CUSTOM_BROKEN` callback instead.
    *
-   * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional second argument that will make the callback
+   *   only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional third argument that will make the callback
+   *   only fire if it matches the variant provided.
    *
    * ```ts
    * function postGridEntityBroken(gridEntity: GridEntity): void {}
@@ -373,8 +375,14 @@ export enum ModCallbackCustom {
    * For grid entities created with `spawnCustomGridEntity`, use the
    * `POST_GRID_ENTITY_CUSTOM_COLLISION` callback instead.
    *
-   * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional second argument that will make the callback
+   *   only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional third argument that will make the callback
+   *   only fire if it matches the variant provided (for the grid entity).
+   * - When registering the callback, takes an optional fourth argument that will make the callback
+   *   only fire if the colliding entity matches the `EntityType` provided.
+   * - When registering the callback, takes an optional fifth argument that will make the callback
+   *   only fire if the colliding entity matches the variant provided.
    *
    * ```ts
    * function postGridEntityCollision(
@@ -390,7 +398,8 @@ export enum ModCallbackCustom {
    * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * only fire if it matches the `GridEntityType` provided. (Custom grid entities do not have
+   * variants, so there is no need for an optional third argument to filter by variant.)
    *
    * ```ts
    * function postGridEntityCustomBroken(
@@ -405,8 +414,13 @@ export enum ModCallbackCustom {
    * The same as the `POST_GRID_ENTITY_COLLISION` callback, but only fires for grid entities created
    * with the `spawnCustomGridEntity` helper function.
    *
-   * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional second argument that will make the callback
+   *   only fire if it matches the `GridEntityType` provided. (Custom grid entities do not have
+   *   variants, so there is no need for an optional third argument to filter by variant.)
+   * - When registering the callback, takes an optional third argument that will make the callback
+   *   only fire if the the colliding entity matches the `EntityType` provided.
+   * - When registering the callback, takes an optional fourth argument that will make the callback
+   *   only fire if the the colliding entity matches the variant provided.
    *
    * ```ts
    * function postGridEntityCustomCollision(
@@ -423,7 +437,8 @@ export enum ModCallbackCustom {
    * the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * only fire if it matches the `GridEntityType` provided. (Custom grid entities do not have
+   * variants, so there is no need for an optional third argument to filter by variant.)
    *
    * ```ts
    * function postGridEntityCustomInit(
@@ -439,7 +454,8 @@ export enum ModCallbackCustom {
    * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * only fire if it matches the `GridEntityType` provided. (Custom grid entities do not have
+   * variants, so there is no need for an optional third argument to filter by variant.)
    *
    * ```ts
    * function postGridEntityCustomRemove(
@@ -455,7 +471,8 @@ export enum ModCallbackCustom {
    * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * only fire if it matches the `GridEntityType` provided. (Custom grid entities do not have
+   * variants, so there is no need for an optional third argument to filter by variant.)
    *
    * ```ts
    * function postGridEntityCustomRender(
@@ -471,7 +488,8 @@ export enum ModCallbackCustom {
    * created with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * only fire if it matches the `GridEntityType` provided. (Custom grid entities do not have
+   * variants, so there is no need for an optional third argument to filter by variant.)
    *
    * ```ts
    * function postGridEntityCustomStateChanged(
@@ -489,7 +507,8 @@ export enum ModCallbackCustom {
    * with the `spawnCustomGridEntity` helper function.
    *
    * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * only fire if it matches the `GridEntityType` provided. (Custom grid entities do not have
+   * variants, so there is no need for an optional third argument to filter by variant.)
    *
    * ```ts
    * function postGridEntityCustomUpdate(
@@ -511,8 +530,10 @@ export enum ModCallbackCustom {
    * For grid entities created with `spawnCustomGridEntity`, use the `POST_GRID_ENTITY_CUSTOM_INIT`
    * callback instead.
    *
-   * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional second argument that will make the callback
+   *   only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional third argument that will make the callback
+   *   only fire if it matches the variant provided.
    *
    * ```ts
    * function postGridEntityInit(gridEntity: GridEntity): void {}
@@ -531,8 +552,10 @@ export enum ModCallbackCustom {
    * For grid entities created with `spawnCustomGridEntity`, use the
    * `POST_GRID_ENTITY_CUSTOM_REMOVE` callback instead.
    *
-   * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional second argument that will make the callback
+   *   only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional third argument that will make the callback
+   *   only fire if it matches the variant provided.
    *
    * ```ts
    * function postGridEntityRemove(
@@ -546,14 +569,14 @@ export enum ModCallbackCustom {
   /**
    * Fires from the `POST_RENDER` callback on every frame that a grid entity exists.
    *
+   * For grid entities created with `spawnCustomGridEntity`, use the
+   * `POST_GRID_ENTITY_CUSTOM_RENDER` callback instead.
+   *
    * - When registering the callback, takes an optional second argument that will make the callback
    *   only fire if it matches the `GridEntityType` provided.
    * - When registering the callback, takes an optional third argument that will make the callback
    *   only fire if it matches the variant provided.
    *
-   * For grid entities created with `spawnCustomGridEntity`, use the
-   * `POST_GRID_ENTITY_CUSTOM_RENDER` callback instead.
-   *
    * ```ts
    * function postGridEntityRender(gridEntity: GridEntity): void {}
    * ```
@@ -564,12 +587,14 @@ export enum ModCallbackCustom {
    * Fires from the `POST_UPDATE` callback when a grid entity changes its state. (In this context,
    * "state" refers to the `GridEntity.State` field.)
    *
-   * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `GridEntityType` provided.
-   *
    * For grid entities created with `spawnCustomGridEntity`, use the
    * `POST_GRID_ENTITY_CUSTOM_STATE_CHANGED` callback instead.
    *
+   * - When registering the callback, takes an optional second argument that will make the callback
+   *   only fire if it matches the `GridEntityType` provided.
+   * - When registering the callback, takes an optional third argument that will make the callback
+   *   only fire if it matches the variant provided.
+   *
    * ```ts
    * function postGridEntityStateChanged(
    *   gridEntity: GridEntity,
@@ -583,14 +608,14 @@ export enum ModCallbackCustom {
   /**
    * Fires from the `POST_UPDATE` callback on every frame that a grid entity exists.
    *
+   * For grid entities created with `spawnCustomGridEntity`, use the
+   * `POST_GRID_ENTITY_CUSTOM_UPDATE` callback instead.
+   *
    * - When registering the callback, takes an optional second argument that will make the callback
    *   only fire if it matches the `GridEntityType` provided.
    * - When registering the callback, takes an optional third argument that will make the callback
    *   only fire if it matches the variant provided.
    *
-   * For grid entities created with `spawnCustomGridEntity`, use the
-   * `POST_GRID_ENTITY_CUSTOM_UPDATE` callback instead.
-   *
    * ```ts
    * function postGridEntityUpdate(gridEntity: GridEntity): void {}
    * ```
@@ -1251,7 +1276,8 @@ export enum ModCallbackCustom {
    * certain conditions, like if the slot entity is playing the "Idle" animation, and so on.
    *
    * When registering the callback, takes an optional second argument that will make the callback
-   * only fire if it matches the `SlotVariant` provided.
+   * only fire if it matches the `SlotVariant` provided. (There is no need for any additional
+   * arguments, since only players will cause this callback to fire.)
    *
    * ```ts
    * function postSlotCollision(

package/src/features/customStage/customStageGridEntities.ts

@@ -25,7 +25,7 @@ import {
 import { DEFAULT_BASE_STAGE } from "./exports";
 import v from "./v";
 
-/** For `GridEntityType.DECORATION` (1) */
+/** For `GridEntityType.DECORATION` (1). */
 export function setCustomDecorationGraphics(
   customStage: CustomStage,
   gridEntity: GridEntity,
@@ -71,7 +71,7 @@ export function setCustomDecorationGraphics(
   }
 }
 
-/** For `GridEntityType.ROCK` (2) */
+/** For `GridEntityType.ROCK` (2). */
 export function setCustomRockGraphics(
   customStage: CustomStage,
   gridEntity: GridEntity,
@@ -134,7 +134,7 @@ export function setCustomRockGraphics(
   }
 }
 
-/** For `GridEntityType.PIT` (7) */
+/** For `GridEntityType.PIT` (7). */
 export function setCustomPitGraphics(
   customStage: CustomStage,
   gridEntity: GridEntity,
@@ -164,7 +164,7 @@ export function setCustomPitGraphics(
   }
 }
 
-/** For GridEntityType.DOOR (16) */
+/** For `GridEntityType.DOOR` (16). */
 export function setCustomDoorGraphics(
   customStage: CustomStage,
   gridEntity: GridEntity,

package/src/functions/effects.ts

@@ -1,6 +1,6 @@
 import { inRectangle } from "./math";
 
-/** For `EntityType.EFFECT` (1000), `EffectVariant.DICE_FLOOR` (76) */
+/** For `EntityType.EFFECT` (1000), `EffectVariant.DICE_FLOOR` (76). */
 export const DICE_FLOOR_TRIGGER_SQUARE_SIZE = 75;
 
 /** Helper function to see if a player is close enough to activate a Dice Room floor. */

package/src/functions/entities.ts

@@ -234,6 +234,10 @@ export function getFilteredNewEntities<T extends AnyEntity>(
 /**
  * Helper function to measure an entity's velocity to see if it is moving.
  *
+ * Use this helper function over checking if the velocity length is equal to 0 because entities can
+ * look like they are completely immobile but yet still have a non zero velocity. Thus, using a
+ * threshold is needed.
+ *
  * @param entity The entity whose velocity to measure.
  * @param threshold Optional. The threshold from 0 to consider to be moving. Default is 0.01.
  */

package/src/functions/entityTypes.ts

@@ -1,6 +1,6 @@
 import { EntityType } from "isaac-typescript-definitions";
 
-/** For `EntityType.SLOT` (6) */
+/** For `EntityType.SLOT` (6). */
 export function isSlot(entity: Entity): entity is EntitySlot {
   return entity.Type === EntityType.SLOT;
 }

package/src/functions/gridEntitiesSpecific.ts

@@ -173,6 +173,21 @@ export function getTNT(variant = -1): GridEntityTNT[] {
   return tntArray;
 }
 
+/**
+ * Helper function to get all of the grid entities of type `GridEntityType.TELEPORTER` (23) in the
+ * room.
+ *
+ * @param variant Optional. If specified, will only get the teleporters that match the variant.
+ *                Default is -1, which matches every variant.
+ */
+export function getTeleporters(variant = -1): GridEntity[] {
+  if (variant === -1) {
+    return getGridEntities(GridEntityType.TELEPORTER);
+  }
+
+  return getMatchingGridEntities(GridEntityType.TELEPORTER, variant);
+}
+
 /**
  * Helper function to get all of the grid entities of type `GridEntityType.TRAPDOOR` (17) in the
  * room. Specify a specific trapdoor variant to select only trapdoors of that variant.
@@ -333,6 +348,26 @@ export function removeAllTNT(
   return removeGridEntities(tnt, updateRoom, cap);
 }
 
+/**
+ * Helper function to remove all of the `GridEntityType.TELEPORTER` (23) in the room.
+ *
+ * @param variant Optional. If specified, will only remove the teleporters that match this variant.
+ *                Default is -1, which matches every variant.
+ * @param updateRoom Optional. Whether or not to update the room after the teleporters are removed.
+ *                   Default is false. For more information, see the description of the
+ *                   `removeGridEntities` helper function.
+ * @param cap Optional. If specified, will only remove the given amount of teleporters.
+ * @returns The teleporters that were removed.
+ */
+export function removeAllTeleporters(
+  variant = -1,
+  updateRoom = false,
+  cap?: int,
+): GridEntity[] {
+  const teleporters = getTeleporters(variant);
+  return removeGridEntities(teleporters, updateRoom, cap);
+}
+
 /**
  * Helper function to remove all of the `GridEntityType.TRAPDOOR` (17) in the room.
  *
@@ -584,6 +619,25 @@ export function spawnTNTWithVariant(
   return tnt;
 }
 
+/** Helper function to spawn a `GridEntityType.TELEPORTER` (23). */
+export function spawnTeleporter(
+  gridIndexOrPosition: int | Vector,
+): GridEntity | undefined {
+  return spawnTeleporterWithVariant(0, gridIndexOrPosition);
+}
+
+/** Helper function to spawn a `GridEntityType.TELEPORTER` (23) with a specific variant. */
+export function spawnTeleporterWithVariant(
+  variant: int,
+  gridIndexOrPosition: int | Vector,
+): GridEntity | undefined {
+  return spawnGridEntityWithVariant(
+    GridEntityType.TELEPORTER,
+    variant,
+    gridIndexOrPosition,
+  );
+}
+
 /** Helper function to spawn a `GridEntityType.TRAPDOOR` (17). */
 export function spawnTrapdoor(
   gridIndexOrPosition: int | Vector,

package/src/functions/pickupVariants.ts

@@ -2,59 +2,59 @@
 
 import { PickupVariant } from "isaac-typescript-definitions";
 
-/** For `PickupVariant.HEART` (10) */
+/** For `PickupVariant.HEART` (10). */
 export function isHeart(pickup: EntityPickup): pickup is EntityPickupHeart {
   return pickup.Variant === PickupVariant.HEART;
 }
 
-/** For `PickupVariant.COIN` (20) */
+/** For `PickupVariant.COIN` (20). */
 export function isCoin(pickup: EntityPickup): pickup is EntityPickupCoin {
   return pickup.Variant === PickupVariant.COIN;
 }
 
-/** For `PickupVariant.KEY` (30) */
+/** For `PickupVariant.KEY` (30). */
 export function isKey(pickup: EntityPickup): pickup is EntityPickupKey {
   return pickup.Variant === PickupVariant.KEY;
 }
 
-/** For `PickupVariant.BOMB` (40) */
+/** For `PickupVariant.BOMB` (40). */
 export function isBombPickup(pickup: EntityPickup): pickup is EntityPickupBomb {
   return pickup.Variant === PickupVariant.BOMB;
 }
 
-/** For `PickupVariant.POOP` (42) */
+/** For `PickupVariant.POOP` (42). */
 export function isPoopPickup(pickup: EntityPickup): pickup is EntityPickupPoop {
   return pickup.Variant === PickupVariant.POOP;
 }
 
-/** For `PickupVariant.SACK` (69) */
+/** For `PickupVariant.SACK` (69). */
 export function isSack(pickup: EntityPickup): pickup is EntityPickupSack {
   return pickup.Variant === PickupVariant.SACK;
 }
 
-/** For `PickupVariant.PILL` (70) */
+/** For `PickupVariant.PILL` (70). */
 export function isPill(pickup: EntityPickup): pickup is EntityPickupPill {
   return pickup.Variant === PickupVariant.PILL;
 }
 
-/** For `PickupVariant.LIL_BATTERY` (90) */
+/** For `PickupVariant.LIL_BATTERY` (90). */
 export function isBattery(pickup: EntityPickup): pickup is EntityPickupBattery {
   return pickup.Variant === PickupVariant.LIL_BATTERY;
 }
 
-/** For `PickupVariant.COLLECTIBLE` (100) */
+/** For `PickupVariant.COLLECTIBLE` (100). */
 export function isCollectible(
   pickup: EntityPickup,
 ): pickup is EntityPickupCollectible {
   return pickup.Variant === PickupVariant.COLLECTIBLE;
 }
 
-/** For `PickupVariant.TAROT_CARD` (300) */
+/** For `PickupVariant.TAROT_CARD` (300). */
 export function isCardPickup(pickup: EntityPickup): pickup is EntityPickupCard {
   return pickup.Variant === PickupVariant.TAROT_CARD;
 }
 
-/** For `PickupVariant.TRINKET` (350) */
+/** For `PickupVariant.TRINKET` (350). */
 export function isTrinket(pickup: EntityPickup): pickup is EntityPickupTrinket {
   return pickup.Variant === PickupVariant.TRINKET;
 }

package/src/functions/pickups.ts

@@ -26,10 +26,12 @@ export function getRedHearts(): EntityPickupHeart[] {
   return hearts.filter((heart) => RED_HEART_SUB_TYPES_SET.has(heart.SubType));
 }
 
+/** Helper function to test if the provided pickup matches one of the various chest variants. */
 export function isChest(pickup: EntityPickup): boolean {
   return CHEST_PICKUP_VARIANTS.has(pickup.Variant);
 }
 
+/** Helper function to test if the provided pickup matches on of the various red heart sub types. */
 export function isRedHeart(pickup: EntityPickup): boolean {
   return isHeart(pickup) && RED_HEART_SUB_TYPES_SET.has(pickup.SubType);
 }