isaacscript-common 13.3.4 → 14.1.0

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

@@ -72,8 +72,13 @@ export function iRange(start: int, end?: int, increment = 1): int[] {
 }
 
 /**
- * Since this is a UI element, we do not want to draw it in water reflections. `renderOffset` will
- * be a non-zero value in reflections.
+ * Helper function to see if the current render callback is rendering a water reflection.
+ *
+ * When the player is in a room with water, things will be rendered twice: once for the normal
+ * rendering, and once for the reflecting rendering. Thus, any mod code in a render callback will
+ * run twice per frame in these situations, which may be unexpected or cause bugs.
+ *
+ * This function is typically used to early return from a render function if it returns true.
  */
 export function isReflectionRender(): boolean {
   const room = game.GetRoom();
@@ -89,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
@@ -181,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,10 @@ export * from "./core/upgradeMod";
 export * from "./enums/AmbushType";
 export * from "./enums/CornerType";
 export * from "./enums/HealthType";
+export * from "./enums/ISCFeature";
+export * from "./enums/LadderSubTypeCustom";
 export * from "./enums/ModCallbackCustom";
+export * from "./enums/ModCallbackCustom2";
 export * from "./enums/PocketItemType";
 export * from "./enums/RockAltType";
 export * from "./enums/SaveDataKey";
@@ -17,8 +21,8 @@ export * from "./enums/StatType";
 export * from "./features/characterHealthConversion";
 export * from "./features/characterStats";
 export * from "./features/collectibleItemPoolType";
-export * from "./features/customDoor";
 export * from "./features/customGridEntity";
+export * from "./features/customHotkeys";
 export * from "./features/customPickup";
 export * from "./features/customStage/exports";
 export * from "./features/customTrapdoor/exports";
@@ -42,7 +46,6 @@ export * from "./features/roomClearFrame";
 export * from "./features/roomHistory";
 export * from "./features/runInNFrames";
 export * from "./features/saveDataManager/exports";
-export * from "./features/setHotkey";
 export * from "./features/sirenHelpers";
 export * from "./features/stageHistory";
 export * from "./features/taintedLazarusPlayers";
@@ -66,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";
@@ -172,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/initCustomCallbacks.ts

@@ -7,7 +7,6 @@ import { postBoneSwingInit } from "./callbacks/postBoneSwing";
 import { postCollectibleEmptyInit } from "./callbacks/postCollectibleEmpty";
 import { postCollectibleInitFirstInit } from "./callbacks/postCollectibleInitFirst";
 import { postCursedTeleportInit } from "./callbacks/postCursedTeleport";
-import { postCustomDoorEnterInit } from "./callbacks/postCustomDoorEnter";
 import { postDiceRoomActivatedInit } from "./callbacks/postDiceRoomActivated";
 import { postDoorRenderInit } from "./callbacks/postDoorRender";
 import { postDoorUpdateInit } from "./callbacks/postDoorUpdate";
@@ -82,7 +81,6 @@ export function initCustomCallbacks(mod: ModUpgraded): void {
   postCollectibleEmptyInit(mod);
   postCollectibleInitFirstInit(mod);
   postCursedTeleportInit(mod);
-  postCustomDoorEnterInit();
   postDiceRoomActivatedInit(mod);
   postDoorRenderInit(mod);
   postDoorUpdateInit(mod);
@@ -103,6 +101,7 @@ export function initCustomCallbacks(mod: ModUpgraded): void {
   postItemDischargeInit(mod);
   postLaserInitLateInit(mod);
   postKnifeInitLateInit(mod);
+  // "postNewRoomEarlyCallbackInit" has already been called.
   postNPCInitLateInit(mod);
   postNPCStateChangedInit(mod);
   postPickupCollectInit(mod);

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 { customHotkeysInit } from "./features/customHotkeys";
 import { customPickupInit } from "./features/customPickup";
 import { customStageInit } from "./features/customStage/init";
 import { customTrapdoorInit } from "./features/customTrapdoor/init";
@@ -24,7 +25,6 @@ import { roomClearFrameInit } from "./features/roomClearFrame";
 import { roomHistoryInit } from "./features/roomHistory";
 import { runInNFramesInit } from "./features/runInNFrames";
 import { runNextRoomInit } from "./features/runNextRoom";
-import { setHotkeyInit } from "./features/setHotkey";
 import { sirenHelpersInit } from "./features/sirenHelpers";
 import { stageHistoryInit } from "./features/stageHistory";
 import { taintedLazarusPlayersInit } from "./features/taintedLazarusPlayers";
@@ -44,6 +44,7 @@ function initFeaturesMajor(mod: ModUpgraded) {
 }
 
 function initFeaturesMinor(mod: ModUpgraded) {
+  customHotkeysInit(mod);
   customPickupInit(mod);
   customTrapdoorInit(mod);
   disableAllSoundInit(mod);
@@ -63,7 +64,6 @@ function initFeaturesMinor(mod: ModUpgraded) {
   roomClearFrameInit(mod);
   roomHistoryInit(mod);
   runNextRoomInit(mod);
-  setHotkeyInit(mod);
   sirenHelpersInit(mod);
   stageHistoryInit(mod);
   taintedLazarusPlayersInit(mod);

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/{AddCallbackParameterCustom.ts → AddCallbackParametersCustom.ts}

@@ -1,12 +1,11 @@
 import { PostAmbushFinishedRegisterParameters } from "../../callbacks/subscriptions/postAmbushFinished";
 import { PostAmbushStartedRegisterParameters } from "../../callbacks/subscriptions/postAmbushStarted";
+import { PostBombExplodedRegisterParameters } from "../../callbacks/subscriptions/postBombExploded";
 import { PostBombInitRegisterParameters } from "../../callbacks/subscriptions/postBombInitLate";
-import { PostBombExplodedRegisterParameters } from "../../callbacks/subscriptions/postBoneExploded";
 import { PostBoneSwingRegisterParameters } from "../../callbacks/subscriptions/postBoneSwing";
 import { PostCollectibleEmptyRegisterParameters } from "../../callbacks/subscriptions/postCollectibleEmpty";
 import { PostCollectibleInitFirstRegisterParameters } from "../../callbacks/subscriptions/postCollectibleInitFirst";
 import { PostCursedTeleportRegisterParameters } from "../../callbacks/subscriptions/postCursedTeleport";
-import { PostCustomDoorEnterRegisterParameters } from "../../callbacks/subscriptions/postCustomDoorEnter";
 import { PostCustomReviveRegisterParameters } from "../../callbacks/subscriptions/postCustomRevive";
 import { PostDiceRoomActivatedRegisterParameters } from "../../callbacks/subscriptions/postDiceRoomActivated";
 import { PostDoorRenderRegisterParameters } from "../../callbacks/subscriptions/postDoorRender";
@@ -93,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;
@@ -103,7 +103,6 @@ export interface AddCallbackParametersCustom {
   [ModCallbackCustom.POST_COLLECTIBLE_EMPTY]: PostCollectibleEmptyRegisterParameters;
   [ModCallbackCustom.POST_COLLECTIBLE_INIT_FIRST]: PostCollectibleInitFirstRegisterParameters;
   [ModCallbackCustom.POST_CURSED_TELEPORT]: PostCursedTeleportRegisterParameters;
-  [ModCallbackCustom.POST_CUSTOM_DOOR_ENTER]: PostCustomDoorEnterRegisterParameters;
   [ModCallbackCustom.POST_CUSTOM_REVIVE]: PostCustomReviveRegisterParameters;
   [ModCallbackCustom.POST_DICE_ROOM_ACTIVATED]: PostDiceRoomActivatedRegisterParameters;
   [ModCallbackCustom.POST_DOOR_RENDER]: PostDoorRenderRegisterParameters;
@@ -148,7 +147,6 @@ export interface AddCallbackParametersCustom {
   [ModCallbackCustom.POST_PICKUP_INIT_FIRST]: PostPickupInitFirstRegisterParameters;
   [ModCallbackCustom.POST_PICKUP_INIT_LATE]: PostPickupInitLateRegisterParameters;
   [ModCallbackCustom.POST_PICKUP_STATE_CHANGED]: PostPickupStateChangedRegisterParameters;
-  [ModCallbackCustom.POST_PIT_RENDER]: PostPitRenderRegisterParameters;
   [ModCallbackCustom.POST_PIT_UPDATE]: PostPitUpdateRegisterParameters;
   [ModCallbackCustom.POST_PLAYER_CHANGE_HEALTH]: PostPlayerChangeHealthRegisterParameters;
   [ModCallbackCustom.POST_PLAYER_CHANGE_STAT]: PostPlayerChangeStatRegisterParameters;
@@ -160,6 +158,7 @@ export interface AddCallbackParametersCustom {
   [ModCallbackCustom.POST_PLAYER_INIT_LATE]: PostPlayerInitLateRegisterParameters;
   [ModCallbackCustom.POST_PLAYER_RENDER_REORDERED]: PostPlayerRenderReorderedRegisterParameters;
   [ModCallbackCustom.POST_PLAYER_UPDATE_REORDERED]: PostPlayerUpdateReorderedRegisterParameters;
+  [ModCallbackCustom.POST_PIT_RENDER]: PostPitRenderRegisterParameters;
   [ModCallbackCustom.POST_POOP_RENDER]: PostPoopRenderRegisterParameters;
   [ModCallbackCustom.POST_POOP_UPDATE]: PostPoopUpdateRegisterParameters;
   [ModCallbackCustom.POST_PRESSURE_PLATE_RENDER]: PostPressurePlateRenderRegisterParameters;
@@ -191,22 +190,4 @@ export interface AddCallbackParametersCustom {
   [ModCallbackCustom.PRE_NEW_LEVEL]: PreNewLevelRegisterParameters;
 }
 
-// Make copies of the objects we need to verify so that we can easily re-use the code block below.
-type EnumToCheck = ModCallbackCustom;
-type InterfaceToCheck = AddCallbackParametersCustom;
-
-// Throw a compiler error if InterfaceToCheck does not match the values of EnumToCheck.
-// From: https://stackoverflow.com/questions/51829842
-type KeysMissing = Exclude<EnumToCheck, keyof InterfaceToCheck>;
-type ExtraKeys = {
-  [K in keyof InterfaceToCheck]: Extract<EnumToCheck, K> extends never
-    ? K
-    : never;
-}[keyof InterfaceToCheck];
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-type Verify<
-  // eslint-disable-next-line @typescript-eslint/naming-convention
-  _Missing extends never = KeysMissing,
-  // eslint-disable-next-line @typescript-eslint/naming-convention
-  _Extra extends never = ExtraKeys,
-> = 0;
+validateInterfaceMatchesEnum<AddCallbackParametersCustom, ModCallbackCustom>();