isaacscript-common 31.5.0 → 31.6.0

package/src/functions/gridEntitiesSpecific.ts

@@ -15,6 +15,7 @@ import {
   spawnGridEntityWithVariant,
 } from "./gridEntities";
 import { asNumber } from "./types";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to get all of the grid entities of type `GridEntityType.CRAWL_SPACE` (18) in the
@@ -421,13 +422,11 @@ export function spawnDoorWithVariant(
     gridIndexOrPosition,
   );
   if (gridEntity === undefined) {
-    return gridEntity;
+    return undefined;
   }
 
   const door = gridEntity.ToDoor();
-  if (door === undefined) {
-    error("Failed to spawn a door.");
-  }
+  assertDefined(door, "Failed to spawn a door.");
 
   return door;
 }
@@ -450,13 +449,11 @@ export function spawnPitWithVariant(
     gridIndexOrPosition,
   );
   if (gridEntity === undefined) {
-    return gridEntity;
+    return undefined;
   }
 
   const pit = gridEntity.ToPit();
-  if (pit === undefined) {
-    error("Failed to spawn a pit.");
-  }
+  assertDefined(pit, "Failed to spawn a pit.");
 
   return pit;
 }
@@ -482,13 +479,11 @@ export function spawnPoopWithVariant(
     gridIndexOrPosition,
   );
   if (gridEntity === undefined) {
-    return gridEntity;
+    return undefined;
   }
 
   const poop = gridEntity.ToPoop();
-  if (poop === undefined) {
-    error("Failed to spawn a poop.");
-  }
+  assertDefined(poop, "Failed to spawn a poop.");
 
   return poop;
 }
@@ -514,13 +509,11 @@ export function spawnPressurePlateWithVariant(
     gridIndexOrPosition,
   );
   if (gridEntity === undefined) {
-    return gridEntity;
+    return undefined;
   }
 
   const pressurePlate = gridEntity.ToPressurePlate();
-  if (pressurePlate === undefined) {
-    error("Failed to spawn a pressure plate.");
-  }
+  assertDefined(pressurePlate, "Failed to spawn a pressure plate.");
 
   return pressurePlate;
 }
@@ -543,13 +536,11 @@ export function spawnRockWithVariant(
     gridIndexOrPosition,
   );
   if (gridEntity === undefined) {
-    return gridEntity;
+    return undefined;
   }
 
   const rock = gridEntity.ToRock();
-  if (rock === undefined) {
-    error("Failed to spawn a rock.");
-  }
+  assertDefined(rock, "Failed to spawn a rock.");
 
   return rock;
 }
@@ -572,13 +563,11 @@ export function spawnSpikesWithVariant(
     gridIndexOrPosition,
   );
   if (gridEntity === undefined) {
-    return gridEntity;
+    return undefined;
   }
 
   const spikes = gridEntity.ToSpikes();
-  if (spikes === undefined) {
-    error("Failed to spawn spikes.");
-  }
+  assertDefined(spikes, "Failed to spawn spikes.");
 
   return spikes;
 }
@@ -601,13 +590,11 @@ export function spawnTNTWithVariant(
     gridIndexOrPosition,
   );
   if (gridEntity === undefined) {
-    return gridEntity;
+    return undefined;
   }
 
   const tnt = gridEntity.ToTNT();
-  if (tnt === undefined) {
-    error("Failed to spawn TNT.");
-  }
+  assertDefined(tnt, "Failed to spawn TNT.");
 
   return tnt;
 }

package/src/functions/input.ts

@@ -9,7 +9,7 @@ import { KEYBOARD_TO_STRING } from "../maps/keyboardToString";
 import { ReadonlySet } from "../types/ReadonlySet";
 import { trimPrefix } from "./string";
 
-const MODIFIER_KEYS = [
+export const MODIFIER_KEYS = [
   Keyboard.LEFT_SHIFT, // 340
   Keyboard.LEFT_CONTROL, // 341
   Keyboard.LEFT_ALT, // 342
@@ -20,7 +20,7 @@ const MODIFIER_KEYS = [
   Keyboard.RIGHT_SUPER, // 347
 ] as const;
 
-const MOVEMENT_ACTIONS = [
+export const MOVEMENT_ACTIONS = [
   ButtonAction.LEFT, // 0
   ButtonAction.RIGHT, // 1
   ButtonAction.UP, // 2
@@ -31,7 +31,7 @@ export const MOVEMENT_ACTIONS_SET = new ReadonlySet<ButtonAction>(
   MOVEMENT_ACTIONS,
 );
 
-const SHOOTING_ACTIONS = [
+export const SHOOTING_ACTIONS = [
   ButtonAction.SHOOT_LEFT, // 4
   ButtonAction.SHOOT_RIGHT, // 5
   ButtonAction.SHOOT_UP, // 6

package/src/functions/jsonRoom.ts

@@ -1,12 +1,14 @@
-import type { DoorSlotFlag, RoomShape } from "isaac-typescript-definitions";
-import { DoorSlotFlagZero } from "isaac-typescript-definitions";
+import type { DoorSlotFlag } from "isaac-typescript-definitions";
+import { DoorSlotFlagZero, RoomShape } from "isaac-typescript-definitions";
 import type { JSONEntity, JSONRoom } from "../interfaces/JSONRoomsFile";
 import { sumArray } from "./array";
 import { doorSlotToDoorSlotFlag, getRoomShapeDoorSlot } from "./doors";
+import { isEnumValue } from "./enums";
 import { addFlag } from "./flag";
 import { log } from "./log";
 import { getRandomFloat } from "./random";
 import { getRandomSeed } from "./rng";
+import { assertDefined } from "./utils";
 
 /** This represents either a `JSONRoom` or a `JSONEntity`. */
 interface JSONObject {
@@ -24,9 +26,14 @@ export function getJSONRoomDoorSlotFlags(
 ): BitFlags<DoorSlotFlag> {
   const roomShapeString = jsonRoom.$.shape;
   const roomShapeNumber = tonumber(roomShapeString);
-  if (roomShapeNumber === undefined) {
+  assertDefined(
+    roomShapeNumber,
+    `Failed to parse the "shape" field of a JSON room: ${roomShapeString}`,
+  );
+
+  if (!isEnumValue(roomShapeNumber, RoomShape)) {
     error(
-      `Failed to parse the "shape" field of a JSON room: ${roomShapeString}`,
+      `Failed to parse the "shape" field of a JSON room since it was an invalid number: ${roomShapeNumber}`,
     );
   }
   const roomShape = roomShapeNumber as RoomShape;
@@ -47,22 +54,23 @@ export function getJSONRoomDoorSlotFlags(
 
     const xString = door.$.x;
     const x = tonumber(xString);
-    if (x === undefined) {
-      error(`Failed to parse the "x" field of a JSON room door: ${xString}`);
-    }
+    assertDefined(
+      x,
+      `Failed to parse the "x" field of a JSON room door: ${xString}`,
+    );
 
     const yString = door.$.y;
     const y = tonumber(yString);
-    if (y === undefined) {
-      error(`Failed to parse the "y" field of a JSON room door: ${yString}`);
-    }
+    assertDefined(
+      y,
+      `Failed to parse the "y" field of a JSON room door: ${yString}`,
+    );
 
     const doorSlot = getRoomShapeDoorSlot(roomShape, x, y);
-    if (doorSlot === undefined) {
-      error(
-        `Failed to retrieve the door slot for a JSON room door at coordinates: [${x}, ${y}]`,
-      );
-    }
+    assertDefined(
+      doorSlot,
+      `Failed to retrieve the door slot for a JSON room door at coordinates: [${x}, ${y}]`,
+    );
 
     const doorSlotFlag = doorSlotToDoorSlotFlag(doorSlot);
     doorSlotFlags = addFlag(doorSlotFlags, doorSlotFlag);
@@ -159,9 +167,10 @@ export function getRandomJSONEntity(
     jsonEntities,
     chosenWeight,
   );
-  if (randomJSONEntity === undefined) {
-    error(`Failed to get a JSON entity with chosen weight: ${chosenWeight}`);
-  }
+  assertDefined(
+    randomJSONEntity,
+    `Failed to get a JSON entity with chosen weight: ${chosenWeight}`,
+  );
 
   return randomJSONEntity;
 }
@@ -197,9 +206,10 @@ export function getRandomJSONRoom(
   }
 
   const randomJSONRoom = getJSONObjectWithChosenWeight(jsonRooms, chosenWeight);
-  if (randomJSONRoom === undefined) {
-    error(`Failed to get a JSON room with chosen weight: ${chosenWeight}`);
-  }
+  assertDefined(
+    randomJSONRoom,
+    `Failed to get a JSON room with chosen weight: ${chosenWeight}`,
+  );
 
   return randomJSONRoom;
 }
@@ -208,9 +218,10 @@ function getTotalWeightOfJSONObject(jsonOjectArray: JSONObject[]): float {
   const weights = jsonOjectArray.map((jsonObject) => {
     const weightString = jsonObject.$.weight;
     const weight = tonumber(weightString);
-    if (weight === undefined) {
-      error(`Failed to parse the weight of a JSON object: ${weightString}.`);
-    }
+    assertDefined(
+      weight,
+      `Failed to parse the weight of a JSON object: ${weightString}.`,
+    );
 
     return weight;
   });
@@ -227,9 +238,10 @@ function getJSONObjectWithChosenWeight<T extends JSONObject>(
   for (const jsonObject of jsonOjectArray) {
     const weightString = jsonObject.$.weight;
     const weight = tonumber(weightString);
-    if (weight === undefined) {
-      error(`Failed to parse the weight of a JSON object: ${weightString}`);
-    }
+    assertDefined(
+      weight,
+      `Failed to parse the weight of a JSON object: ${weightString}`,
+    );
 
     weightAccumulator += weight;
     if (weightAccumulator >= chosenWeight) {

package/src/functions/kColor.ts

@@ -9,6 +9,7 @@ import {
   tableHasKeys,
 } from "./table";
 import { isTable } from "./types";
+import { assertDefined } from "./utils";
 
 export type SerializedKColor = LuaMap<string, unknown> & {
   readonly __serializedKColorBrand: symbol;
@@ -42,26 +43,22 @@ export function deserializeKColor(kColor: SerializedKColor): KColor {
 
   const [r, g, b, a] = getNumbersFromTable(kColor, OBJECT_NAME, ...KEYS);
 
-  if (r === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Red`,
-    );
-  }
-  if (g === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Green`,
-    );
-  }
-  if (b === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Blue`,
-    );
-  }
-  if (a === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Alpha`,
-    );
-  }
+  assertDefined(
+    r,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Red`,
+  );
+  assertDefined(
+    g,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Green`,
+  );
+  assertDefined(
+    b,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Blue`,
+  );
+  assertDefined(
+    a,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Alpha`,
+  );
 
   return KColor(r, g, b, a);
 }

package/src/functions/map.ts

@@ -1,6 +1,7 @@
 import type { DefaultMap } from "../classes/DefaultMap";
 import { sumArray } from "./array";
 import { getPartialMatch } from "./string";
+import { assertDefined } from "./utils";
 
 /** Helper function to copy a map. (You can also use a Map constructor to accomplish this task.) */
 export function copyMap<K, V>(
@@ -73,11 +74,10 @@ export function getMapPartialMatch<T>(
   }
 
   const value = map.get(matchingKey);
-  if (value === undefined) {
-    error(
-      `Failed to get the map value corresponding to the partial match of: ${matchingKey}`,
-    );
-  }
+  assertDefined(
+    value,
+    `Failed to get the map value corresponding to the partial match of: ${matchingKey}`,
+  );
 
   return [matchingKey, value];
 }

package/src/functions/minimap.ts

@@ -4,6 +4,7 @@ import { game } from "../core/cachedClasses";
 import { addFlag } from "./flag";
 import { getRoomDescriptor, getRoomGridIndex } from "./roomData";
 import { getRoomsInsideGrid } from "./rooms";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to add a `DisplayFlag` to a particular room's minimap display flags (e.g. whether
@@ -101,11 +102,11 @@ export function getRoomDisplayFlags(
   }
 
   const minimapAPIRoomDescriptor = MinimapAPI.GetRoomByIdx(roomGridIndex);
-  if (minimapAPIRoomDescriptor === undefined) {
-    error(
-      `Failed to get the MinimapAPI room descriptor for the room at grid index: ${roomGridIndex}`,
-    );
-  }
+  assertDefined(
+    minimapAPIRoomDescriptor,
+    `Failed to get the MinimapAPI room descriptor for the room at grid index: ${roomGridIndex}`,
+  );
+
   return minimapAPIRoomDescriptor.GetDisplayFlags();
 }
 
@@ -126,11 +127,11 @@ export function hideRoomOnMinimap(roomGridIndex: int): void {
   // `Hidden` property.
   if (MinimapAPI !== undefined) {
     const minimapAPIRoomDescriptor = MinimapAPI.GetRoomByIdx(roomGridIndex);
-    if (minimapAPIRoomDescriptor === undefined) {
-      error(
-        `Failed to get the MinimapAPI room descriptor for the room at grid index: ${roomGridIndex}`,
-      );
-    }
+    assertDefined(
+      minimapAPIRoomDescriptor,
+      `Failed to get the MinimapAPI room descriptor for the room at grid index: ${roomGridIndex}`,
+    );
+
     minimapAPIRoomDescriptor.Hidden = true;
   }
 }
@@ -225,11 +226,11 @@ export function setRoomDisplayFlags(
     }
   } else {
     const minimapAPIRoomDescriptor = MinimapAPI.GetRoomByIdx(roomGridIndex);
-    if (minimapAPIRoomDescriptor === undefined) {
-      error(
-        `Failed to get the MinimapAPI room descriptor for the room at grid index: ${roomGridIndex}`,
-      );
-    }
+    assertDefined(
+      minimapAPIRoomDescriptor,
+      `Failed to get the MinimapAPI room descriptor for the room at grid index: ${roomGridIndex}`,
+    );
+
     minimapAPIRoomDescriptor.SetDisplayFlags(displayFlags);
   }
 }

package/src/functions/players.ts

@@ -23,7 +23,7 @@ import {
   getPlayers,
 } from "./playerIndex";
 import { isNumber } from "./types";
-import { repeat } from "./utils";
+import { assertDefined, repeat } from "./utils";
 
 /**
  * Helper function to add one or more collectibles to a player.
@@ -217,9 +217,7 @@ export function getClosestPlayer(position: Vector): EntityPlayer {
     }
   }
 
-  if (closestPlayer === undefined) {
-    error("Failed to find the closest player.");
-  }
+  assertDefined(closestPlayer, "Failed to find the closest player.");
 
   return closestPlayer;
 }
@@ -251,9 +249,10 @@ export function getFinalPlayer(): EntityPlayer {
   const players = getPlayers();
 
   const lastPlayer = getLastElement(players);
-  if (lastPlayer === undefined) {
-    error("Failed to get the final player since there were 0 players.");
-  }
+  assertDefined(
+    lastPlayer,
+    "Failed to get the final player since there were 0 players.",
+  );
 
   return lastPlayer;
 }
@@ -273,9 +272,7 @@ export function getNewestPlayer(): EntityPlayer {
     }
   }
 
-  if (newestPlayer === undefined) {
-    error("Failed to find the newest player.");
-  }
+  assertDefined(newestPlayer, "Failed to find the newest player.");
 
   return newestPlayer;
 }

package/src/functions/rng.ts

@@ -4,6 +4,7 @@ import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
+import { assertDefined } from "./utils";
 
 export type SerializedRNG = LuaMap<string, unknown> & {
   readonly __serializedRNGBrand: symbol;
@@ -45,11 +46,10 @@ export function deserializeRNG(rng: SerializedRNG): RNG {
 
   const [seed] = getNumbersFromTable(rng, OBJECT_NAME, ...KEYS);
 
-  if (seed === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: seed`,
-    );
-  }
+  assertDefined(
+    seed,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: seed`,
+  );
 
   return newRNG(seed as Seed);
 }

package/src/functions/roomShapeWalls.ts

@@ -7,6 +7,7 @@ import { ReadonlySet } from "../types/ReadonlySet";
 import { getGridIndexesBetween } from "./gridIndex";
 import { getRoomShapeCorners, isLRoomShape } from "./roomShape";
 import { inBossRoomOf, inHomeCloset } from "./rooms";
+import { assertDefined } from "./utils";
 
 const ROOM_SHAPE_TO_WALL_GRID_INDEX_SET: ReadonlyMap<
   RoomShape,
@@ -329,10 +330,8 @@ export function isVanillaWallGridIndex(gridIndex: int): boolean {
     wallGridIndexSet = MOTHER_ROOM_CORNERS_SET;
   } else {
     wallGridIndexSet = ROOM_SHAPE_TO_WALL_GRID_INDEX_SET.get(roomShape);
-  }
-
-  if (wallGridIndexSet === undefined) {
-    error(
+    assertDefined(
+      wallGridIndexSet,
       `Failed to find the wall grid index set for: RoomShape.${RoomShape[roomShape]} (${roomShape})`,
     );
   }

package/src/functions/roomTransition.ts

@@ -5,6 +5,7 @@ import {
 } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
 import { getRoomData, getRoomGridIndex } from "./roomData";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to reload the current room using `Game.StartRoomTransition`.
@@ -40,11 +41,10 @@ export function teleport(
   const level = game.GetLevel();
 
   const roomData = getRoomData(roomGridIndex);
-  if (roomData === undefined) {
-    error(
-      `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
-    );
-  }
+  assertDefined(
+    roomData,
+    `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
+  );
 
   // This must be set before every `Game.StartRoomTransition` method invocation or else the function
   // can send you to the wrong room.

package/src/functions/rooms.ts

@@ -48,7 +48,7 @@ import { isLRoomShape } from "./roomShape";
 import { reloadRoom } from "./roomTransition";
 import { getGotoCommand } from "./stage";
 import { asNumber } from "./types";
-import { iRange } from "./utils";
+import { assertDefined, iRange } from "./utils";
 
 const SECRET_ROOM_TYPES = new ReadonlySet([
   RoomType.SECRET,
@@ -65,11 +65,10 @@ export function changeRoom(roomGridIndex: int): void {
   const level = game.GetLevel();
 
   const roomData = getRoomData(roomGridIndex);
-  if (roomData === undefined) {
-    error(
-      `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
-    );
-  }
+  assertDefined(
+    roomData,
+    `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
+  );
 
   // LeaveDoor must be set before every `Game.ChangeRoom` invocation or else the function can send
   // you to the wrong room.

package/src/functions/serialization.ts

@@ -10,6 +10,7 @@ import type {
 import { ISAAC_API_CLASS_TYPE_TO_FUNCTIONS } from "../objects/isaacAPIClassTypeToFunctions";
 import { getIsaacAPIClassName } from "./isaacAPIClass";
 import { isTable, isUserdata } from "./types";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to generically copy an Isaac API class without knowing what specific type of
@@ -27,11 +28,10 @@ export function copyIsaacAPIClass<T extends CopyableIsaacAPIClass>(
   }
 
   const isaacAPIClassType = getIsaacAPIClassName(isaacAPIClass);
-  if (isaacAPIClassType === undefined) {
-    error(
-      "Failed to copy an Isaac API class since it does not have a class type.",
-    );
-  }
+  assertDefined(
+    isaacAPIClassType,
+    "Failed to copy an Isaac API class since it does not have a class type.",
+  );
 
   const copyableIsaacAPIClassType =
     isaacAPIClassType as CopyableIsaacAPIClassType;
@@ -48,11 +48,10 @@ export function copyIsaacAPIClass<T extends CopyableIsaacAPIClass>(
         ThisSerializedIsaacAPIClassType
       >
     | undefined;
-  if (functions === undefined) {
-    error(
-      `Failed to copy an Isaac API class since the associated functions were not found for Isaac API class type: ${copyableIsaacAPIClassType}`,
-    );
-  }
+  assertDefined(
+    functions,
+    `Failed to copy an Isaac API class since the associated functions were not found for Isaac API class type: ${copyableIsaacAPIClassType}`,
+  );
 
   return functions.copy(isaacAPIClass);
 }
@@ -78,11 +77,10 @@ export function deserializeIsaacAPIClass<
   const copyableIsaacAPIClassType = getSerializedTableType(
     serializedIsaacAPIClass,
   );
-  if (copyableIsaacAPIClassType === undefined) {
-    error(
-      "Failed to deserialize an Isaac API class since a valid class type brand was not found.",
-    );
-  }
+  assertDefined(
+    copyableIsaacAPIClassType,
+    "Failed to deserialize an Isaac API class since a valid class type brand was not found.",
+  );
 
   type ThisIsaacAPIClassType = IsaacAPIClassTypeToType[SerializedT["__kind"]];
   type ThisSerializedIsaacAPIClassType = SerializedT;
@@ -95,11 +93,10 @@ export function deserializeIsaacAPIClass<
         ThisSerializedIsaacAPIClassType
       >
     | undefined;
-  if (functions === undefined) {
-    error(
-      `Failed to deserialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
-    );
-  }
+  assertDefined(
+    functions,
+    `Failed to deserialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
+  );
 
   return functions.deserialize(serializedIsaacAPIClass);
 }
@@ -170,11 +167,10 @@ export function serializeIsaacAPIClass<T extends CopyableIsaacAPIClass>(
   }
 
   const isaacAPIClassType = getIsaacAPIClassName(isaacAPIClass);
-  if (isaacAPIClassType === undefined) {
-    error(
-      "Failed to serialize an Isaac API class since it does not have a class type.",
-    );
-  }
+  assertDefined(
+    isaacAPIClassType,
+    "Failed to serialize an Isaac API class since it does not have a class name.",
+  );
 
   const copyableIsaacAPIClassType =
     isaacAPIClassType as CopyableIsaacAPIClassType;
@@ -191,11 +187,10 @@ export function serializeIsaacAPIClass<T extends CopyableIsaacAPIClass>(
         ThisSerializedIsaacAPIClassType
       >
     | undefined;
-  if (functions === undefined) {
-    error(
-      `Failed to serialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
-    );
-  }
+  assertDefined(
+    functions,
+    `Failed to serialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
+  );
 
   return functions.serialize(isaacAPIClass);
 }