isaacscript-common 14.0.0 → 14.1.1

package/src/functions/itemPool.ts

@@ -61,7 +61,7 @@ export function isCollectibleInItemPool(
 
   // On Tainted Lost, it is impossible to retrieve non-offensive collectibles from pools, so we
   // temporarily change the character to Isaac.
-  const taintedLosts = getPlayersOfType(PlayerType.THE_LOST_B);
+  const taintedLosts = getPlayersOfType(PlayerType.LOST_B);
   const isOffensive = collectibleHasTag(
     collectibleType,
     ItemConfigTag.OFFENSIVE,
@@ -108,7 +108,7 @@ export function isCollectibleInItemPool(
   // Change any players back to Tainted Lost, if necessary.
   if (changedPlayerTypes) {
     for (const player of taintedLosts) {
-      player.ChangePlayerType(PlayerType.THE_LOST_B);
+      player.ChangePlayerType(PlayerType.LOST_B);
     }
   }
 

package/src/functions/playerHealth.ts

@@ -177,7 +177,7 @@ export function getPlayerHealth(player: EntityPlayer): PlayerHealth {
   const bloodCharges = player.GetEffectiveBloodCharge();
 
   // The Forgotten and The Soul has special health, so we need to account for this.
-  if (character === PlayerType.THE_FORGOTTEN && subPlayer !== undefined) {
+  if (character === PlayerType.FORGOTTEN && subPlayer !== undefined) {
     // The Forgotten does not have red heart containers.
     maxHearts = boneHearts * 2;
     boneHearts = 0;
@@ -185,7 +185,7 @@ export function getPlayerHealth(player: EntityPlayer): PlayerHealth {
     // The Forgotten will always have 0 soul hearts; we need to get the soul heart amount from the
     // sub player.
     soulHearts = subPlayer.GetSoulHearts();
-  } else if (character === PlayerType.THE_SOUL && subPlayer !== undefined) {
+  } else if (character === PlayerType.SOUL && subPlayer !== undefined) {
     // The Soul will always have 0 bone hearts; we need to get the bone heart amount from the sub
     // player. We need to store it as "maxHearts" instead of "boneHearts".
     maxHearts = subPlayer.GetBoneHearts() * 2;
@@ -202,7 +202,7 @@ export function getPlayerHealth(player: EntityPlayer): PlayerHealth {
   const soulHeartTypes: SoulHeartType[] = [];
   for (let i = 0; i < extraHearts; i++) {
     let isBoneHeart = player.IsBoneHeart(i);
-    if (character === PlayerType.THE_FORGOTTEN && subPlayer !== undefined) {
+    if (character === PlayerType.FORGOTTEN && subPlayer !== undefined) {
       isBoneHeart = subPlayer.IsBoneHeart(i);
     }
     if (isBoneHeart) {
@@ -210,7 +210,7 @@ export function getPlayerHealth(player: EntityPlayer): PlayerHealth {
     } else {
       // We need to add 1 here because only the second half of a black heart is considered black.
       let isBlackHeart = player.IsBlackHeart(currentSoulHeart + 1);
-      if (character === PlayerType.THE_FORGOTTEN && subPlayer !== undefined) {
+      if (character === PlayerType.FORGOTTEN && subPlayer !== undefined) {
         isBlackHeart = subPlayer.IsBlackHeart(currentSoulHeart + 1);
       }
       if (isBlackHeart) {
@@ -520,7 +520,7 @@ export function removeAllPlayerHealth(player: EntityPlayer): void {
 
   // If we are The Soul, the `EntityPlayer.AddBoneHearts` method will not remove Forgotten's bone
   // hearts, so we need to explicitly handle this.
-  if (isCharacter(player, PlayerType.THE_SOUL)) {
+  if (isCharacter(player, PlayerType.SOUL)) {
     const forgotten = player.GetSubPlayer();
     if (forgotten !== undefined) {
       const forgottenBoneHearts = forgotten.GetBoneHearts();
@@ -559,7 +559,7 @@ export function setPlayerHealth(
   }
 
   // Add the red heart containers.
-  if (character === PlayerType.THE_SOUL && subPlayer !== undefined) {
+  if (character === PlayerType.SOUL && subPlayer !== undefined) {
     // Adding health to The Soul is a special case.
     subPlayer.AddMaxHearts(playerHealth.maxHearts, false);
   } else {

package/src/functions/playerIndex.ts

@@ -6,7 +6,7 @@ const DEFAULT_COLLECTIBLE_TYPE = CollectibleType.SAD_ONION;
 
 const EXCLUDED_CHARACTERS: ReadonlySet<PlayerType> = new Set([
   PlayerType.ESAU, // 20
-  PlayerType.THE_SOUL_B, // 40
+  PlayerType.SOUL_B, // 40
 ]);
 
 /**
@@ -122,7 +122,7 @@ function getPlayerIndexCollectibleType(
 ) {
   const character = player.GetPlayerType();
 
-  if (character === PlayerType.THE_SOUL) {
+  if (character === PlayerType.SOUL) {
     return differentiateForgottenAndSoul
       ? CollectibleType.INNER_EYE
       : DEFAULT_COLLECTIBLE_TYPE;

package/src/functions/players.ts

@@ -299,6 +299,21 @@ export function getPlayerFromEntity(entity: Entity): EntityPlayer | undefined {
   return entity.ToPlayer();
 }
 
+/**
+ * Helper function to get an `EntityPlayer` object from an `EntityPtr`. Returns undefined if the
+ * entity has gone out of scope or if the associated entity is not a player.
+ */
+export function getPlayerFromPtr(
+  entityPtr: EntityPtr,
+): EntityPlayer | undefined {
+  const entity = entityPtr.Ref;
+  if (entity === undefined) {
+    return undefined;
+  }
+
+  return entity.ToPlayer();
+}
+
 /**
  * Helper function to get the proper name of the player. Use this instead of the
  * `EntityPlayer.GetName` method because it accounts for Blue Baby, Lazarus II, and Tainted
@@ -442,7 +457,7 @@ export function hasLostCurse(player: EntityPlayer): boolean {
  * items. (Only Tainted Forgotten can pick up items.)
  */
 export function hasOpenActiveItemSlot(player: EntityPlayer): boolean {
-  if (isCharacter(player, PlayerType.THE_SOUL_B)) {
+  if (isCharacter(player, PlayerType.SOUL_B)) {
     return false;
   }
 
@@ -460,9 +475,15 @@ export function hasOpenActiveItemSlot(player: EntityPlayer): boolean {
   return activeItemPrimary === CollectibleType.NULL;
 }
 
+/**
+ * Helper function to check if the active slot of a particular player is empty.
+ *
+ * @param player The player to check.
+ * @param activeSlot Optional. The active slot to check. Default is `ActiveSlot.PRIMARY`.
+ */
 export function isActiveSlotEmpty(
   player: EntityPlayer,
-  activeSlot: ActiveSlot,
+  activeSlot = ActiveSlot.PRIMARY,
 ): boolean {
   const activeCollectibleType = player.GetActiveItem(activeSlot);
   return activeCollectibleType === CollectibleType.NULL;
@@ -546,9 +567,7 @@ export function isKeeper(player: EntityPlayer): boolean {
 export function isLost(player: EntityPlayer): boolean {
   const character = player.GetPlayerType();
 
-  return (
-    character === PlayerType.THE_LOST || character === PlayerType.THE_LOST_B
-  );
+  return character === PlayerType.LOST || character === PlayerType.LOST_B;
 }
 
 export function isModdedPlayer(player: EntityPlayer): boolean {
@@ -714,7 +733,7 @@ export function removeTrinketCostume(
  *
  * @param player The player to give the item to.
  * @param collectibleType The collectible type of the item to give.
- * @param activeSlot The slot to set.
+ * @param activeSlot Optional. The slot to set. Default is `ActiveSlot.PRIMARY`.
  * @param charge Optional. The argument of charges to set. If not specified, the item will be set
  *               with maximum charges.
  * @param keepInPools Optional. Whether or not to remove the item from pools. Default is false.
@@ -722,7 +741,7 @@ export function removeTrinketCostume(
 export function setActiveItem(
   player: EntityPlayer,
   collectibleType: CollectibleType,
-  activeSlot: ActiveSlot,
+  activeSlot = ActiveSlot.PRIMARY,
   charge?: int,
   keepInPools = false,
 ): void {

package/src/functions/pocketItems.ts

@@ -124,7 +124,7 @@ export function getPocketItems(player: EntityPlayer): PocketItemDescription[] {
  * items. (Only Tainted Forgotten can pick up items.)
  */
 export function hasOpenPocketItemSlot(player: EntityPlayer): boolean {
-  if (isCharacter(player, PlayerType.THE_SOUL_B)) {
+  if (isCharacter(player, PlayerType.SOUL_B)) {
     return false;
   }
 

package/src/functions/rooms.ts

@@ -546,7 +546,7 @@ export function roomUpdateSafe(): void {
   setEntityVelocities(entityVelocities, entities);
 }
 
-/** Helper function to set the backdrop of the current room. */
+/** Helper function to set the backdrop (i.e. background) of the current room. */
 export function setBackdrop(backdropType: BackdropType): void {
   game.ShowHallucination(0, backdropType);
   sfxManager.Stop(SoundEffect.DEATH_CARD);

package/src/functions/run.ts

@@ -1,5 +1,6 @@
 import {
   Challenge,
+  Difficulty,
   PlayerType,
   SlotVariant,
 } from "isaac-typescript-definitions";
@@ -26,6 +27,17 @@ export function canRunUnlockAchievements(): boolean {
   return canUnlockAchievements;
 }
 
+/**
+ * Helper function to check if the difficulty of the current run is equal to `Difficulty.GREED` or
+ * `Difficulty.GREEDIER`.
+ */
+export function isGreedMode(): boolean {
+  return (
+    game.Difficulty === Difficulty.GREED ||
+    game.Difficulty === Difficulty.GREEDIER
+  );
+}
+
 /**
  * Whether or not the player is playing on a set seed (i.e. that they entered in a specific seed by
  * pressing tab on the character selection screen). When the player resets the game on a set seed,

package/src/functions/table.ts

@@ -136,6 +136,17 @@ export function getStringsFromTable(
   return strings;
 }
 
+/** Helper function to check if a Lua table has 0 keys. */
+export function isTableEmpty(luaMap: LuaMap<AnyNotNil, unknown>): boolean {
+  // Using `next` does not seem to work properly, so we use `pairs` instead.
+  // eslint-disable-next-line no-unreachable-loop
+  for (const [_key, _value] of pairs(luaMap)) {
+    return false;
+  }
+
+  return true;
+}
+
 /**
  * Helper function to iterate over a table deterministically. This is useful because by default, the
  * `pairs` function will return the keys of a Lua table in a random order.

package/src/functions/trinkets.ts

@@ -156,7 +156,7 @@ export function getVanillaTrinketTypes(): TrinketType[] {
  * items. (Only Tainted Forgotten can pick up items.)
  */
 export function hasOpenTrinketSlot(player: EntityPlayer): boolean {
-  if (isCharacter(player, PlayerType.THE_SOUL_B)) {
+  if (isCharacter(player, PlayerType.SOUL_B)) {
     return false;
   }
 

package/src/functions/tstlClass.ts

@@ -1,5 +1,6 @@
 import { DefaultMap } from "../classes/DefaultMap";
-import { TSTLClassMetatable } from "../interfaces/private/TSTLClassMetatable";
+import { TSTLClassMetatable } from "../interfaces/TSTLClassMetatable";
+import { FunctionTuple } from "../types/FunctionTuple";
 import { TSTLClass } from "../types/TSTLClass";
 import { isString, isTable } from "./types";
 
@@ -12,16 +13,14 @@ const TSTL_CLASS_METATABLE_KEYS: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Helper function to get the name of a TypeScriptToLua class. TSTL classes are Lua tables created
- * with the `__TS__Class` Lua function from the TSTL lualib. Their name is contained within
- * "constructor.name" metatable key.
+ * Helper function to get the constructor from an instantiated TypeScriptToLua class, which is
+ * located on the metatable.
  *
- * For example, a `Map` class is has a name of "Map".
- *
- * Returns undefined if the object is not a table or if the aforementioned metatable key does not
- * exist.
+ * Returns undefined if passed a non-table or if the provided table does not have a metatable.
  */
-export function getTSTLClassName(object: unknown): string | undefined {
+export function getTSTLClassConstructor(
+  object: unknown,
+): TSTLClassMetatable["constructor"] | undefined {
   if (!isTable(object)) {
     return undefined;
   }
@@ -31,8 +30,35 @@ export function getTSTLClassName(object: unknown): string | undefined {
     return undefined;
   }
 
-  const { constructor } = metatable;
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return metatable.constructor;
+}
+
+export function getTSTLClassMethods(object: unknown): FunctionTuple[] {
+  const constructor = getTSTLClassConstructor(object);
+  if (constructor === undefined) {
+    return [];
+  }
+
+  const classEntries = Object.entries(constructor.prototype);
+  return classEntries.filter(
+    ([key, value]) =>
+      // Ignore the stock TSTL keys that are baked into every class.
+      !TSTL_CLASS_METATABLE_KEYS.has(key) && type(value) === "function",
+  );
+}
+
+/**
+ * Helper function to get the name of a TypeScriptToLua class from the instantiated class object.
+ *
+ * TSTL classes are Lua tables created with the `__TS__Class` Lua function from the TSTL lualib.
+ * Their name is contained within "constructor.name" metatable key.
+ *
+ * For example, a `Map` class is has a name of "Map".
+ *
+ * Returns undefined if passed a non-table or if the provided table does not have a metatable.
+ */
+export function getTSTLClassName(object: unknown): string | undefined {
+  const constructor = getTSTLClassConstructor(object);
   if (constructor === undefined) {
     return undefined;
   }
@@ -64,8 +90,9 @@ export function isIsaacScriptCommonClass(object: unknown): boolean {
 /**
  * Helper function to determine if a given object is a TypeScriptToLua `Map`.
  *
- * It is not reliable to use the `instanceof` operator to determine this because each Lua module has
- * their own copies of the entire lualib and thus their own instantiated version of a `Map`.
+ * It is not reliable to use the `instanceof` operator to determine this because each Lua module
+ * might have their own copy of the entire lualib and thus their own instantiated version of a
+ * `Map`.
  */
 export function isTSTLMap(object: unknown): object is Map<AnyNotNil, unknown> {
   const className = getTSTLClassName(object);
@@ -75,8 +102,9 @@ export function isTSTLMap(object: unknown): object is Map<AnyNotNil, unknown> {
 /**
  * Helper function to determine if a given object is a TypeScriptToLua `Set`.
  *
- * It is not reliable to use the `instanceof` operator to determine this because each Lua module has
- * their own copies of the entire lualib and thus their own instantiated version of a `Set`.
+ * It is not reliable to use the `instanceof` operator to determine this because each Lua module
+ * might have their own copy of the entire lualib and thus their own instantiated version of a
+ * `Set`.
  */
 export function isTSTLSet(object: unknown): object is Set<AnyNotNil> {
   const className = getTSTLClassName(object);
@@ -134,22 +162,18 @@ export function isVanillaTSTLClass(object: unknown): boolean {
  * class.
  */
 export function newTSTLClass(oldClass: TSTLClass): TSTLClass {
-  const metatable = getmetatable(oldClass) as TSTLClassMetatable | undefined;
-  if (metatable === undefined) {
+  const constructor = getTSTLClassConstructor(oldClass);
+  if (constructor === undefined) {
     error(
-      "Failed to instantiate a new TypeScriptToLua class since the provided old class does not have a metatable.",
+      "Failed to instantiate a new TypeScriptToLua class since the provided old class does not have a metatable/constructor.",
     );
   }
 
-  return newTSTLClassFromMetatable(metatable);
-}
-
-/** This is a re-implementation of the transpiled "__TS__New" function. */
-function newTSTLClassFromMetatable(metatable: TSTLClassMetatable): TSTLClass {
+  // We re-implement some of the logic from the transpiled "__TS__New" function.
   const newClass = new LuaMap<AnyNotNil, unknown>();
   const newClassMetatable = setmetatable(
     newClass,
-    metatable.constructor.prototype,
+    constructor.prototype,
   ) as unknown as TSTLClassMetatable;
   newClassMetatable.____constructor(); // eslint-disable-line no-underscore-dangle
 

package/src/functions/utils.ts

@@ -94,6 +94,22 @@ export function isVanillaConsoleCommand(commandName: string): boolean {
   return CONSOLE_COMMANDS_SET.has(commandName);
 }
 
+/**
+ * Helper function for creating objects that represent a mapping of an enum value to some other
+ * value in a type-safe way.
+ *
+ * This function will ensure that the provided object has a key for each value in the enum.
+ *
+ * After the `satisfies` operator is released in TypeScript 4.9, this function should be deleted.
+ */
+export function newObjectWithEnumKeys<
+  Enum extends number | string,
+  T extends Record<Enum, unknown>,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+>(theEnum: Record<string, Enum>, obj: T): T {
+  return obj;
+}
+
 /**
  * Helper function to print something to the in-game console. Use this instead of invoking the
  * `Isaac.ConsoleOutput` method directly because it will automatically insert a newline at the end
@@ -186,3 +202,36 @@ export function twoDimensionalSort<T>(array1: T[], array2: T[]): -1 | 0 | 1 {
 
   return firstElement1 < firstElement2 ? -1 : 1;
 }
+
+/**
+ * Helper function to validate that an interface contains all of the keys of an enum. You must
+ * specify both generic parameters in order for this to work properly (i.e. the interface and then
+ * the enum).
+ *
+ * For example:
+ *
+ * ```ts
+ * enum MyEnum {
+ *   Value1,
+ *   Value2,
+ *   Value3,
+ * }
+ *
+ * interface MyEnumToType {
+ *   [MyEnum.Value1]: boolean;
+ *   [MyEnum.Value2]: number;
+ *   [MyEnum.Value3]: string;
+ * }
+ *
+ * validateInterfaceMatchesEnum<MyEnumToType, MyEnum>();
+ * ```
+ *
+ * This function is only meant to be used with interfaces (i.e. types that will not exist at
+ * run-time). If you are generating an object that will contain all of the keys of an enum, use the
+ * `newObjectWithEnumKeys` helper function instead.
+ */
+export function validateInterfaceMatchesEnum<
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  T extends Record<Enum, unknown>,
+  Enum extends string | number,
+>(): void {}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./classes/DefaultMap";
+export * from "./classes/ModFeature";
 export * from "./classes/ModUpgraded";
 export * from "./core/cachedClasses";
 export * from "./core/constants";
@@ -7,7 +8,7 @@ export * from "./core/upgradeMod";
 export * from "./enums/AmbushType";
 export * from "./enums/CornerType";
 export * from "./enums/HealthType";
-export * from "./enums/IsaacScriptCommonFeature";
+export * from "./enums/ISCFeature";
 export * from "./enums/LadderSubTypeCustom";
 export * from "./enums/ModCallbackCustom";
 export * from "./enums/ModCallbackCustom2";
@@ -68,6 +69,7 @@ export * from "./functions/collectibleTag";
 export * from "./functions/color";
 export * from "./functions/curses";
 export * from "./functions/debugFunctions";
+export * from "./functions/decorators";
 export * from "./functions/deepCopy";
 export * from "./functions/deepCopyTests";
 export * from "./functions/dev";
@@ -174,13 +176,22 @@ export * from "./maps/pillNameToEffectMap";
 export * from "./maps/roomNameToTypeMap";
 export * from "./objects/colors";
 export * from "./objects/kColors";
+export * from "./types/AllButFirst";
+export * from "./types/AllButLast";
 export * from "./types/AnyEntity";
 export * from "./types/AnyGridEntity";
 export * from "./types/CollectibleIndex";
+export * from "./types/Constructor";
+export * from "./types/FunctionTuple";
+export * from "./types/HasAllEnumKeys";
 export * from "./types/Immutable";
+export * from "./types/LowercaseKeys";
 export * from "./types/PickingUpItem";
 export * from "./types/PickupIndex";
 export * from "./types/PlayerIndex";
 export * from "./types/PossibleStatType";
+export * from "./types/StartsWithLowercase";
+export * from "./types/StartsWithUppercase";
 export * from "./types/TSTLClass";
+export * from "./types/UppercaseKeys";
 export * from "./types/WeightedArray";

package/src/interfaces/SaveData.ts

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/explicit-member-accessibility */
+/* eslint-disable class-methods-use-this */
 /* eslint-disable max-classes-per-file */
 
 import { CopyableIsaacAPIClass } from "../objects/isaacAPIClassTypeToFunctions";
@@ -233,7 +235,7 @@ function test<Persistent, Run, Level>(
 {
   class Foo {
     someField = 123;
-    someMethod() {} // eslint-disable-line class-methods-use-this
+    someMethod() {}
   }
 
   const saveDataWithClassWithMethod = {
@@ -264,7 +266,7 @@ function test<Persistent, Run, Level>(
 {
   class Foo {
     someField = 123;
-    someMethod() {} // eslint-disable-line class-methods-use-this
+    someMethod() {}
   }
 
   const saveDataWithNestedClass = {

package/src/interfaces/private/AddCallbackParametersCustom.ts

@@ -92,6 +92,7 @@ import { PreGetPedestalRegisterParameters } from "../../callbacks/subscriptions/
 import { PreItemPickupRegisterParameters } from "../../callbacks/subscriptions/preItemPickup";
 import { PreNewLevelRegisterParameters } from "../../callbacks/subscriptions/preNewLevel";
 import { ModCallbackCustom } from "../../enums/ModCallbackCustom";
+import { validateInterfaceMatchesEnum } from "../../functions/utils";
 
 export interface AddCallbackParametersCustom {
   [ModCallbackCustom.POST_AMBUSH_FINISHED]: PostAmbushFinishedRegisterParameters;
@@ -188,3 +189,5 @@ export interface AddCallbackParametersCustom {
   [ModCallbackCustom.PRE_ITEM_PICKUP]: PreItemPickupRegisterParameters;
   [ModCallbackCustom.PRE_NEW_LEVEL]: PreNewLevelRegisterParameters;
 }
+
+validateInterfaceMatchesEnum<AddCallbackParametersCustom, ModCallbackCustom>();