isaacscript-common 80.2.1 → 80.2.3

package/src/core/constantsFirstLast.ts

@@ -8,11 +8,9 @@ import {
   CardType,
   Challenge,
   CollectibleType,
-  LevelStage,
   PillColor,
   PillEffect,
   PlayerType,
-  RoomType,
   TrinketType,
 } from "isaac-typescript-definitions";
 import { getEnumLength, getHighestEnumValue } from "../functions/enums";
@@ -62,13 +60,7 @@ export const NUM_VANILLA_TRINKET_TYPES = getEnumLength(TrinketType) - 1;
 /** Equal to `Card.FOOL`. */
 export const FIRST_CARD_TYPE = CardType.FOOL;
 
-/**
- * Calculated from the `CardType` enum.
- *
- * Note that this could be calculated from the length of the enum, because card types are
- * contiguous. However, we instead get the highest enum value to be safer and to make the code more
- * consistent with collectibles and trinkets.
- */
+/** Calculated from the `CardType` enum. */
 export const LAST_VANILLA_CARD_TYPE = getHighestEnumValue(CardType);
 
 /** Calculated from the `Card` enum. `Card.NULL` is not included. */
@@ -81,13 +73,7 @@ export const NUM_VANILLA_CARD_TYPES = getEnumLength(CardType) - 1;
 /** Equal to `PillEffect.BAD_GAS`. */
 export const FIRST_PILL_EFFECT = PillEffect.BAD_GAS;
 
-/**
- * Calculated from the `PillEffect` enum.
- *
- * Note that this could be calculated from the length of the enum, because pill effects are
- * contiguous. However, we instead get the highest enum value to be safer and to make the code more
- * consistent with collectibles and trinkets.
- */
+/** Calculated from the `PillEffect` enum. */
 export const LAST_VANILLA_PILL_EFFECT = getHighestEnumValue(PillEffect);
 
 /**
@@ -136,29 +122,9 @@ export const FIRST_CHARACTER = PlayerType.ISAAC;
 
 // It is not possible to determine "LAST_PLAYER_TYPE", since there is no associated config.
 
-/**
- * Calculated from the `PlayerType` enum.
- *
- * Note that this could be calculated from the length of the enum, because characters are
- * contiguous. However, we instead get the highest enum value to be safer and to make the code more
- * consistent with collectibles and trinkets.
- */
+/** Calculated from the `PlayerType` enum. */
 export const LAST_VANILLA_CHARACTER = getHighestEnumValue(PlayerType);
 
-// ----------
-// Room Types
-// ----------
-
-export const FIRST_ROOM_TYPE = RoomType.DEFAULT;
-export const LAST_ROOM_TYPE = getHighestEnumValue(RoomType);
-
-// ------
-// Stages
-// ------
-
-export const FIRST_STAGE = LevelStage.BASEMENT_1;
-export const LAST_STAGE = getHighestEnumValue(LevelStage);
-
 // ----------
 // Challenges
 // ----------

package/src/functions/cards.ts

@@ -10,6 +10,7 @@ import {
 import { CARD_NAMES, DEFAULT_CARD_NAME } from "../objects/cardNames";
 import { ITEM_CONFIG_CARD_TYPES_FOR_CARDS } from "../sets/itemConfigCardTypesForCards";
 import { addFlag } from "./flag";
+import { asCardType } from "./types";
 
 /**
  * Helper function to get a card description from a `CardType` value. Returns "Unknown" if the
@@ -158,6 +159,12 @@ export function isTarotCard(cardType: CardType): boolean {
   return isCardType(cardType, ItemConfigCardType.TAROT);
 }
 
+export function isValidCardType(cardType: int): cardType is CardType {
+  const potentialCardType = asCardType(cardType);
+  const itemConfigCard = itemConfig.GetCard(potentialCardType);
+  return itemConfigCard !== undefined;
+}
+
 export function isVanillaCardType(cardType: CardType): boolean {
   return cardType <= LAST_VANILLA_CARD_TYPE;
 }

package/src/functions/collectibles.ts

@@ -35,7 +35,7 @@ import { getEntityID } from "./entities";
 import { hasFlag } from "./flag";
 import { isCollectible } from "./pickupVariants";
 import { clearSprite, spriteEquals } from "./sprites";
-import { isInteger } from "./types";
+import { asCollectibleType, isInteger } from "./types";
 import { assertDefined } from "./utils";
 
 const COLLECTIBLE_ANM2_PATH = "gfx/005.100_collectible.anm2";
@@ -569,9 +569,10 @@ export function isSingleUseCollectible(
 }
 
 export function isValidCollectibleType(
-  collectibleType: CollectibleType,
-): boolean {
-  const itemConfigItem = itemConfig.GetCollectible(collectibleType);
+  collectibleType: int,
+): collectibleType is CollectibleType {
+  const potentialCollectibleType = asCollectibleType(collectibleType);
+  const itemConfigItem = itemConfig.GetCollectible(potentialCollectibleType);
   return itemConfigItem !== undefined;
 }
 

package/src/functions/doors.ts

@@ -29,8 +29,10 @@ import { ROOM_SHAPE_TO_DOOR_SLOTS } from "../objects/roomShapeToDoorSlots";
 import { ReadonlySet } from "../types/ReadonlySet";
 import { arrayToBitFlags } from "./bitwise";
 import { directionToVector } from "./direction";
+import { isEnumValue } from "./enums";
 import { hasFlag } from "./flag";
 import { isTSTLSet } from "./tstlClass";
+import { parseIntSafe } from "./types";
 
 export function closeAllDoors(): void {
   for (const door of getDoors()) {
@@ -278,7 +280,6 @@ export function getRoomShapeDoorSlot(
   x: int,
   y: int,
 ): DoorSlot | undefined {
-  // The type assertion is necessary for some reason.
   const doorSlotCoordinates = ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES[
     roomShape
   ] as Record<DoorSlot, readonly [x: int, y: int]>;
@@ -286,7 +287,11 @@ export function getRoomShapeDoorSlot(
   for (const [doorSlotString, coordinates] of Object.entries(
     doorSlotCoordinates,
   )) {
-    const doorSlot = tonumber(doorSlotString) as DoorSlot;
+    const doorSlot = parseIntSafe(doorSlotString);
+    if (doorSlot === undefined || !isEnumValue(doorSlot, DoorSlot)) {
+      continue;
+    }
+
     const [doorX, doorY] = coordinates;
     if (x === doorX && y === doorY) {
       return doorSlot;
@@ -304,10 +309,10 @@ export function getRoomShapeDoorSlotCoordinates(
   roomShape: RoomShape,
   doorSlot: DoorSlot,
 ): readonly [x: int, y: int] | undefined {
-  // The type assertion is necessary for some reason.
   const doorSlotCoordinates = ROOM_SHAPE_TO_DOOR_SLOT_COORDINATES[
     roomShape
   ] as Record<DoorSlot, readonly [x: int, y: int]>;
+
   return doorSlotCoordinates[doorSlot];
 }
 

package/src/functions/entities.ts

@@ -18,7 +18,7 @@ import { newReadonlyColor } from "./readOnly";
 import { getRandomSeed, isRNG, newRNG } from "./rng";
 import { setSpriteOpacity } from "./sprites";
 import { isTSTLSet } from "./tstlClass";
-import { asNPCState, isPrimitive } from "./types";
+import { asNPCState, isPrimitive, parseIntSafe } from "./types";
 import { assertDefined } from "./utils";
 import { doesVectorHaveLength, isVector, vectorToString } from "./vector";
 
@@ -173,22 +173,37 @@ export function getConstituentsFromEntityID(
 
   const [entityTypeString, variantString, subTypeString] = parts;
 
-  const entityType = tonumber(entityTypeString);
+  assertDefined(
+    entityTypeString,
+    `Failed to get the first constituent from an entity ID: ${entityID}`,
+  );
+
+  assertDefined(
+    variantString,
+    `Failed to get the second constituent from an entity ID: ${entityID}`,
+  );
+
+  assertDefined(
+    subTypeString,
+    `Failed to get the third constituent from an entity ID: ${entityID}`,
+  );
+
+  const entityType = parseIntSafe(entityTypeString);
   assertDefined(
     entityType,
-    `Failed to convert the entity type to a number: ${entityTypeString}`,
+    `Failed to convert the entity type to an integer: ${entityTypeString}`,
   );
 
-  const variant = tonumber(variantString);
+  const variant = parseIntSafe(variantString);
   assertDefined(
     variant,
-    `Failed to convert the entity variant to a number: ${variantString}`,
+    `Failed to convert the entity variant to an integer: ${variantString}`,
   );
 
-  const subType = tonumber(subTypeString);
+  const subType = parseIntSafe(subTypeString);
   assertDefined(
     subType,
-    `Failed to convert the entity sub-type to a number: ${subTypeString}`,
+    `Failed to convert the entity sub-type to an integer: ${subTypeString}`,
   );
 
   return [entityType, variant, subType];
@@ -464,18 +479,23 @@ export function parseEntityID(
 
   const [entityTypeString, variantString, subTypeString] = entityIDArray;
 
-  const entityType = tonumber(entityTypeString);
-  if (entityType === undefined) {
+  if (
+    entityTypeString === undefined ||
+    variantString === undefined ||
+    subTypeString === undefined
+  ) {
     return undefined;
   }
 
-  const variant = tonumber(variantString);
-  if (variant === undefined) {
-    return undefined;
-  }
+  const entityType = parseIntSafe(entityTypeString);
+  const variant = parseIntSafe(variantString);
+  const subType = parseIntSafe(subTypeString);
 
-  const subType = tonumber(subTypeString);
-  if (subType === undefined) {
+  if (
+    entityType === undefined ||
+    variant === undefined ||
+    subType === undefined
+  ) {
     return undefined;
   }
 
@@ -500,13 +520,14 @@ export function parseEntityTypeVariantString(
 
   const [entityTypeString, variantString] = entityTypeVariantArray;
 
-  const entityType = tonumber(entityTypeString);
-  if (entityType === undefined) {
+  if (entityTypeString === undefined || variantString === undefined) {
     return undefined;
   }
 
-  const variant = tonumber(variantString);
-  if (variant === undefined) {
+  const entityType = parseIntSafe(entityTypeString);
+  const variant = parseIntSafe(variantString);
+
+  if (entityType === undefined || variant === undefined) {
     return undefined;
   }
 

package/src/functions/gridEntities.ts

@@ -26,7 +26,7 @@ import { removeEntities } from "./entities";
 import { getEffects } from "./entitiesSpecific";
 import { isCircleIntersectingRectangle } from "./math";
 import { roomUpdateSafe } from "./rooms";
-import { isInteger } from "./types";
+import { isInteger, parseIntSafe } from "./types";
 import { assertDefined, eRange, iRange } from "./utils";
 import { isVector, vectorEquals } from "./vector";
 
@@ -169,22 +169,32 @@ export function getConstituentsFromGridEntityID(
   const parts = gridEntityID.split(".");
   if (parts.length !== 2) {
     error(
-      `Failed to get the constituents from grid entity ID: ${gridEntityID}`,
+      `Failed to get the constituents from a grid entity ID: ${gridEntityID}`,
     );
   }
 
   const [gridEntityTypeString, variantString] = parts;
 
-  const gridEntityType = tonumber(gridEntityTypeString);
+  assertDefined(
+    gridEntityTypeString,
+    `Failed to get the first constituent from a grid entity ID: ${gridEntityID}`,
+  );
+
+  assertDefined(
+    variantString,
+    `Failed to get the second constituent from a grid entity ID: ${gridEntityID}`,
+  );
+
+  const gridEntityType = parseIntSafe(gridEntityTypeString);
   assertDefined(
     gridEntityType,
     `Failed to convert the grid entity type to a number: ${gridEntityTypeString}`,
   );
 
-  const variant = tonumber(variantString);
+  const variant = parseIntSafe(variantString);
   assertDefined(
     variant,
-    `Failed to convert the grid entity variant to a number: ${variantString}`,
+    `Failed to convert the grid entity variant to an integer: ${variantString}`,
   );
 
   return [gridEntityType, variant];

package/src/functions/jsonRoom.ts

@@ -7,6 +7,7 @@ import { isEnumValue } from "./enums";
 import { addFlag } from "./flag";
 import { log } from "./log";
 import { getRandomFloat } from "./random";
+import { parseIntSafe } from "./types";
 import { assertDefined } from "./utils";
 
 /** This represents either a `JSONRoom` or a `JSONEntity`. */
@@ -24,7 +25,7 @@ export function getJSONRoomDoorSlotFlags(
   jsonRoom: JSONRoom,
 ): BitFlags<DoorSlotFlag> {
   const roomShapeString = jsonRoom.$.shape;
-  const roomShape = tonumber(roomShapeString);
+  const roomShape = parseIntSafe(roomShapeString);
   assertDefined(
     roomShape,
     `Failed to parse the "shape" field of a JSON room: ${roomShapeString}`,
@@ -51,14 +52,14 @@ export function getJSONRoomDoorSlotFlags(
     }
 
     const xString = door.$.x;
-    const x = tonumber(xString);
+    const x = parseIntSafe(xString);
     assertDefined(
       x,
       `Failed to parse the "x" field of a JSON room door: ${xString}`,
     );
 
     const yString = door.$.y;
-    const y = tonumber(yString);
+    const y = parseIntSafe(yString);
     assertDefined(
       y,
       `Failed to parse the "y" field of a JSON room door: ${yString}`,
@@ -92,7 +93,13 @@ export function getJSONRoomOfVariant(
 ): JSONRoom | undefined {
   const jsonRoomsOfVariant = jsonRooms.filter((jsonRoom) => {
     const roomVariantString = jsonRoom.$.variant;
-    const roomVariant = tonumber(roomVariantString);
+    const roomVariant = parseIntSafe(roomVariantString);
+    if (roomVariant === undefined) {
+      error(
+        `Failed to convert a JSON room variant to an integer: ${roomVariantString}`,
+      );
+    }
+
     return roomVariant === variant;
   });
 
@@ -125,7 +132,13 @@ export function getJSONRoomsOfSubType(
 ): JSONRoom[] {
   return jsonRooms.filter((jsonRoom) => {
     const roomSubTypeString = jsonRoom.$.subtype;
-    const roomSubType = tonumber(roomSubTypeString);
+    const roomSubType = parseIntSafe(roomSubTypeString);
+    if (roomSubType === undefined) {
+      error(
+        `Failed to convert a JSON room sub-type to an integer: ${roomSubTypeString}`,
+      );
+    }
+
     return roomSubType === subType;
   });
 }

package/src/functions/pills.ts

@@ -28,7 +28,7 @@ import {
   DEFAULT_PILL_EFFECT_TYPE,
   PILL_EFFECT_TYPES,
 } from "../objects/pillEffectTypes";
-import { asNumber, asPillColor } from "./types";
+import { asNumber, asPillColor, asPillEffect } from "./types";
 import { iRange } from "./utils";
 
 /**
@@ -214,6 +214,12 @@ export function isModdedPillEffect(pillEffect: PillEffect): boolean {
   return !isVanillaPillEffect(pillEffect);
 }
 
+export function isValidPillEffect(pillEffect: int): pillEffect is PillEffect {
+  const potentialPillEffect = asPillEffect(pillEffect);
+  const itemConfigPillEffect = itemConfig.GetPillEffect(potentialPillEffect);
+  return itemConfigPillEffect !== undefined;
+}
+
 export function isVanillaPillEffect(pillEffect: PillEffect): boolean {
   return pillEffect <= LAST_VANILLA_PILL_EFFECT;
 }

package/src/functions/run.ts

@@ -1,8 +1,10 @@
-import type { PlayerType } from "isaac-typescript-definitions";
-import { Challenge, SeedEffect } from "isaac-typescript-definitions";
+import {
+  Challenge,
+  PlayerType,
+  SeedEffect,
+} from "isaac-typescript-definitions";
 import { SEED_EFFECTS } from "../arrays/cachedEnumValues";
 import { game } from "../core/cachedClasses";
-import { FIRST_CHARACTER } from "../core/constantsFirstLast";
 import { getCharacterName } from "./characters";
 import { log } from "./log";
 import { isString } from "./types";
@@ -84,7 +86,7 @@ export function restart(character?: PlayerType): void {
     return;
   }
 
-  if (character < FIRST_CHARACTER) {
+  if (character < PlayerType.ISAAC) {
     error(`Restarting as a character of ${character} would crash the game.`);
   }
 

package/src/functions/string.ts

@@ -1,3 +1,4 @@
+import { parseIntSafe } from "./types";
 import { assertDefined } from "./utils";
 
 export function capitalizeFirstLetter(string: string): string {
@@ -158,9 +159,9 @@ export function parseSemanticVersion(versionString: string):
     return undefined;
   }
 
-  const majorVersion = tonumber(majorVersionString);
-  const minorVersion = tonumber(minorVersionString);
-  const patchVersion = tonumber(patchVersionString);
+  const majorVersion = parseIntSafe(majorVersionString);
+  const minorVersion = parseIntSafe(minorVersionString);
+  const patchVersion = parseIntSafe(patchVersionString);
 
   if (
     majorVersion === undefined ||

package/src/functions/table.ts

@@ -66,8 +66,9 @@ export function getBooleansFromTable(
 }
 
 /**
- * Helper function to safely get number values from specific keys on a Lua table. Will throw an
- * error if the specific value does not exist on the table or if it cannot be converted to a number.
+ * Helper function to safely get number values from specific keys on a Lua table. If the values are
+ * strings, they will be converted to numbers. Will throw an error if the specific value does not
+ * exist on the table or if it cannot be converted to a number.
  *
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */

package/src/functions/trinkets.ts

@@ -14,7 +14,7 @@ import { getEnumLength } from "./enums";
 import { hasFlag } from "./flag";
 import { isTrinket } from "./pickupVariants";
 import { clearSprite } from "./sprites";
-import { asNumber } from "./types";
+import { asNumber, asTrinketType } from "./types";
 
 /**
  * Add this to a `TrinketType` to get the corresponding golden trinket type.
@@ -165,6 +165,14 @@ export function isModdedTrinketType(trinketType: TrinketType): boolean {
   return !isVanillaTrinketType(trinketType);
 }
 
+export function isValidTrinketType(
+  trinketType: int,
+): trinketType is TrinketType {
+  const potentialTrinketType = asTrinketType(trinketType);
+  const itemConfigItem = itemConfig.GetTrinket(potentialTrinketType);
+  return itemConfigItem !== undefined;
+}
+
 export function isVanillaTrinketType(trinketType: TrinketType): boolean {
   return trinketType <= LAST_VANILLA_TRINKET_TYPE;
 }

package/src/functions/types.ts

@@ -216,3 +216,28 @@ export function isTable(
 export function isUserdata(variable: unknown): variable is LuaUserdata {
   return type(variable) === "userdata";
 }
+
+/**
+ * Helper function to convert a string to an integer. Returns undefined if the string is not an
+ * integer.
+ *
+ * Under the hood, this uses the built-in `tonumber` and `math.floor` functions.
+ *
+ * This is named `parseIntSafe` in order to match the helper function in `isaacscript-common-ts`.
+ */
+export function parseIntSafe(string: string): int | undefined {
+  if (!isString(string)) {
+    return undefined;
+  }
+
+  // - The `tonumber` function correctly deals with leading and trailing whitespace.
+  // - The `tonumber` function correctly deals with a mix of numbers and letters. (e.g. `1a` returns
+  //   undefined.)
+  const number = tonumber(string);
+  if (number === undefined) {
+    return undefined;
+  }
+
+  const flooredNumber = math.floor(number);
+  return number === flooredNumber ? flooredNumber : undefined;
+}

package/src/objects/itemPoolTypeToCollectibleTypesSet.ts

@@ -4,7 +4,7 @@ import type {
 } from "isaac-typescript-definitions";
 import { ITEM_POOL_TYPE_VALUES } from "../arrays/cachedEnumValues";
 import * as itemPoolsJSON from "../data/itempools.json";
-import { asCollectibleType } from "../functions/types";
+import { asCollectibleType, parseIntSafe } from "../functions/types";
 import { ITEM_POOL_TYPE_TO_ITEM_POOL_NAME } from "../maps/itemPoolTypeToItemPoolName";
 
 export const ITEM_POOL_TYPE_TO_COLLECTIBLE_TYPES_SET: Readonly<
@@ -22,14 +22,14 @@ export const ITEM_POOL_TYPE_TO_COLLECTIBLE_TYPES_SET: Readonly<
       const collectibleTypesSet = new Set<CollectibleType>();
 
       for (const itemPoolJSONElement of itemPoolJSON.Item) {
-        const collectibleTypeNumber = tonumber(itemPoolJSONElement.$.Id);
-        if (collectibleTypeNumber === undefined) {
+        const collectibleTypeInt = parseIntSafe(itemPoolJSONElement.$.Id);
+        if (collectibleTypeInt === undefined) {
           error(
             `Failed to parse a collectible type in the "itempools.json" file: ${itemPoolJSONElement.$.Id}`,
           );
         }
 
-        const collectibleType = asCollectibleType(collectibleTypeNumber);
+        const collectibleType = asCollectibleType(collectibleTypeInt);
         collectibleTypesSet.add(collectibleType);
       }