isaacscript-common 4.0.0 → 4.0.3

package/functions/trinkets.ts

@@ -0,0 +1,215 @@
+import {
+  CacheFlag,
+  PlayerType,
+  TrinketSlot,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { itemConfig } from "../cachedClasses";
+import {
+  FIRST_MODDED_TRINKET_TYPE,
+  FIRST_TRINKET_TYPE,
+  LAST_TRINKET_TYPE,
+  LAST_VANILLA_TRINKET_TYPE,
+} from "../constantsFirstLast";
+import {
+  DEFAULT_TRINKET_DESCRIPTION,
+  TRINKET_DESCRIPTION_MAP,
+} from "../maps/trinketDescriptionMap";
+import { DEFAULT_TRINKET_NAME, TRINKET_NAME_MAP } from "../maps/trinketNameMap";
+import { getEntityID } from "./entity";
+import { hasFlag } from "./flag";
+import { isTrinket } from "./pickupVariants";
+import { isCharacter } from "./player";
+import { clearSprite } from "./sprite";
+import { irange } from "./utils";
+
+/**
+ * Add this to a `TrinketType` to get the corresponding golden trinket type.
+ *
+ * Corresponds to the vanilla `PillColor.TRINKET_GOLDEN_FLAG` value.
+ *
+ * 1 << 15
+ */
+const GOLDEN_TRINKET_ADJUSTMENT = 32768;
+
+const TRINKET_SPRITE_LAYER = 0;
+
+/**
+ * Helper function to get the corresponding golden trinket type from a normal trinket type.
+ *
+ * For example, passing `TrinketType.SWALLOWED_PENNY` would result in 32769, which is the value that
+ * corresponds to the golden trinket sub-type for Swallowed Penny.
+ */
+export function getGoldenTrinketType(trinketType: TrinketType): TrinketType {
+  return trinketType + GOLDEN_TRINKET_ADJUSTMENT; // eslint-disable-line isaacscript/strict-enums
+}
+
+/**
+ * Helper function to get an array that represents every modded trinket type.
+ *
+ * Returns an empty array if there are no modded trinket types.
+ */
+export function getModdedTrinketTypes(): TrinketType[] {
+  if (LAST_VANILLA_TRINKET_TYPE === LAST_TRINKET_TYPE) {
+    return [];
+  }
+
+  return irange(FIRST_MODDED_TRINKET_TYPE, LAST_TRINKET_TYPE) as TrinketType[];
+}
+
+/**
+ * Returns the slot number corresponding to where a trinket can be safely inserted.
+ *
+ * For example:
+ *
+ * ```ts
+ * const player = Isaac.GetPlayer();
+ * const trinketSlot = getOpenTrinketSlotNum(player);
+ * if (trinketSlot !== undefined) {
+ *   // They have one or more open trinket slots
+ *   player.AddTrinket(TrinketType.SWALLOWED_PENNY);
+ * }
+ * ```
+ */
+export function getOpenTrinketSlot(player: EntityPlayer): int | undefined {
+  const maxTrinkets = player.GetMaxTrinkets();
+  const trinketType1 = player.GetTrinket(TrinketSlot.SLOT_1);
+  const trinketType2 = player.GetTrinket(TrinketSlot.SLOT_2);
+
+  if (maxTrinkets === 1) {
+    return trinketType1 === TrinketType.NULL ? 0 : undefined;
+  }
+
+  if (maxTrinkets === 2) {
+    if (trinketType1 === TrinketType.NULL) {
+      return 0;
+    }
+
+    return trinketType2 === TrinketType.NULL ? 1 : undefined;
+  }
+
+  return error(
+    `The player has an unknown number of trinket slots: ${maxTrinkets}`,
+  );
+}
+
+/**
+ * Helper function to get the in-game description for a trinket. Returns "Unknown" if the provided
+ * trinket type was not valid.
+ */
+export function getTrinketDescription(trinketType: TrinketType): string {
+  // "ItemConfigItem.Description" is bugged with vanilla items on patch v1.7.6, so we use a
+  // hard-coded map as a workaround.
+  const trinketDescription = TRINKET_DESCRIPTION_MAP.get(trinketType);
+  if (trinketDescription !== undefined) {
+    return trinketDescription;
+  }
+
+  const itemConfigItem = itemConfig.GetTrinket(trinketType);
+  if (itemConfigItem !== undefined) {
+    return itemConfigItem.Description;
+  }
+
+  return DEFAULT_TRINKET_DESCRIPTION;
+}
+
+/**
+ * Helper function to get the name of a trinket. Returns "Unknown" if the provided trinket type is
+ * not valid.
+ *
+ * For example:
+ *
+ * ```ts
+ * const trinketType = TrinketType.SWALLOWED_PENNY;
+ * const trinketName = getTrinketName(trinketType); // trinketName is "Swallowed Penny"
+ * ```
+ */
+export function getTrinketName(trinketType: TrinketType): string {
+  // "ItemConfigItem.Name" is bugged with vanilla items on patch v1.7.6, so we use a hard-coded map
+  // as a workaround.
+  const trinketName = TRINKET_NAME_MAP.get(trinketType);
+  if (trinketName !== undefined) {
+    return trinketName;
+  }
+
+  const itemConfigItem = itemConfig.GetTrinket(trinketType);
+  if (itemConfigItem !== undefined) {
+    return itemConfigItem.Name;
+  }
+
+  return DEFAULT_TRINKET_NAME;
+}
+
+/** Helper function to get an array that contains every trinket type. */
+export function getTrinketTypes(): TrinketType[] {
+  return irange(FIRST_TRINKET_TYPE, LAST_TRINKET_TYPE) as TrinketType[];
+}
+
+/** Helper function to get an array that represents every vanilla trinket type. */
+export function getVanillaTrinketTypes(): TrinketType[] {
+  return irange(FIRST_TRINKET_TYPE, LAST_VANILLA_TRINKET_TYPE) as TrinketType[];
+}
+
+/**
+ * Returns whether or not the player can hold an additional trinket, beyond what they are currently
+ * carrying. This takes into account items that modify the max number of trinkets, like Mom's Purse.
+ *
+ * If the player is the Tainted Soul, this always returns false, since that character cannot pick up
+ * items. (Only Tainted Forgotten can pick up items.)
+ */
+export function hasOpenTrinketSlot(player: EntityPlayer): boolean {
+  if (isCharacter(player, PlayerType.THE_SOUL_B)) {
+    return false;
+  }
+
+  const openTrinketSlot = getOpenTrinketSlot(player);
+  return openTrinketSlot !== undefined;
+}
+
+export function isGoldenTrinket(trinketType: TrinketType): boolean {
+  return trinketType > (GOLDEN_TRINKET_ADJUSTMENT as TrinketType);
+}
+
+/**
+ * Helper function to change the sprite of a trinket entity.
+ *
+ * For more information about removing the trinket sprite, see the documentation for the
+ * "clearSprite" helper function.
+ *
+ * @param trinket The trinket whose sprite you want to modify.
+ * @param pngPath Equal to either the spritesheet path to load (e.g.
+ *                "gfx/items/trinkets/trinket_001_swallowedpenny.png") or undefined. If undefined,
+ *                the sprite will be removed, making it appear like the collectible has already been
+ *                taken by the player.
+ */
+export function setTrinketSprite(
+  trinket: EntityPickup,
+  pngPath: string | undefined,
+): void {
+  if (!isTrinket(trinket)) {
+    const entityID = getEntityID(trinket);
+    error(
+      `The "setTrinketSprite" function was given a non-trinket: ${entityID}`,
+    );
+  }
+
+  const sprite = trinket.GetSprite();
+  if (pngPath === undefined) {
+    clearSprite(sprite, TRINKET_SPRITE_LAYER);
+  } else {
+    sprite.ReplaceSpritesheet(TRINKET_SPRITE_LAYER, pngPath);
+    sprite.LoadGraphics();
+  }
+}
+
+export function trinketHasCacheFlag(
+  trinketType: TrinketType,
+  cacheFlag: CacheFlag,
+): boolean {
+  const itemConfigItem = itemConfig.GetTrinket(trinketType);
+  if (itemConfigItem === undefined) {
+    return false;
+  }
+
+  return hasFlag(itemConfigItem.CacheFlags, cacheFlag);
+}

package/functions/tstlClass.ts

@@ -0,0 +1,157 @@
+import { DefaultMap } from "../classes/DefaultMap";
+import { TSTLClassMetatable } from "../interfaces/private/TSTLClassMetatable";
+import { TSTLClass } from "../types/private/TSTLClass";
+import { isString, isTable } from "./types";
+
+const VANILLA_TSTL_CLASSES = new Set(["Map", "Set", "WeakMap", "WeakSet"]);
+
+const TSTL_CLASS_METATABLE_KEYS: ReadonlySet<string> = new Set([
+  "____constructor",
+  "__index",
+  "constructor",
+]);
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function getTSTLClassName(object: unknown): string | undefined {
+  if (!isTable(object)) {
+    return undefined;
+  }
+
+  const metatable = getmetatable(object);
+  if (metatable === undefined) {
+    return undefined;
+  }
+
+  const { constructor } = metatable;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (constructor === undefined) {
+    return undefined;
+  }
+
+  return constructor.name;
+}
+
+/**
+ * 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`.
+ */
+export function isDefaultMap(
+  object: unknown,
+): object is DefaultMap<AnyNotNil, unknown> {
+  const className = getTSTLClassName(object);
+  return className === "DefaultMap";
+}
+
+/**
+ * Returns whether or not this is a class that is provided by the `isaacscript-common` library, such
+ * as a `DefaultMap`.
+ */
+export function isIsaacScriptCommonClass(object: unknown): boolean {
+  return isDefaultMap(object);
+}
+
+/**
+ * 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`.
+ */
+export function isTSTLMap(object: unknown): object is Map<AnyNotNil, unknown> {
+  const className = getTSTLClassName(object);
+  return className === "Map";
+}
+
+/**
+ * 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`.
+ */
+export function isTSTLSet(object: unknown): object is Set<AnyNotNil> {
+  const className = getTSTLClassName(object);
+  return className === "Set";
+}
+
+/** TypeScriptToLua classes are Lua tables that have a metatable with a certain amount of keys. */
+export function isUserDefinedTSTLClass(object: unknown): object is TSTLClass {
+  if (isVanillaTSTLClass(object) || isIsaacScriptCommonClass(object)) {
+    return false;
+  }
+
+  if (!isTable(object)) {
+    return false;
+  }
+
+  const metatable = getmetatable(object);
+  if (metatable === undefined) {
+    return false;
+  }
+
+  let numKeys = 0;
+  for (const [key] of pairs(metatable)) {
+    numKeys += 1;
+
+    if (!isString(key)) {
+      return false;
+    }
+
+    if (!TSTL_CLASS_METATABLE_KEYS.has(key)) {
+      return false;
+    }
+  }
+
+  return numKeys === TSTL_CLASS_METATABLE_KEYS.size;
+}
+
+/**
+ * Returns whether or not this is a class that is provided as part of the TypeScriptToLua
+ * transpiler, such as a `Map` or a `Set`.
+ */
+export function isVanillaTSTLClass(object: unknown): boolean {
+  const className = getTSTLClassName(object);
+  if (className === undefined) {
+    return false;
+  }
+
+  return VANILLA_TSTL_CLASSES.has(className);
+}
+
+/**
+ * Initializes a new TypeScriptToLua class in the situation where you do not know what kind of class
+ * it is. This function requires that you provide an instantiated class of the same type, as it will
+ * use the class constructor that is present on the other object's metatable to initialize the new
+ * class.
+ */
+export function newTSTLClass(oldClass: TSTLClass): TSTLClass {
+  const metatable = getmetatable(oldClass) as TSTLClassMetatable | undefined;
+  if (metatable === undefined) {
+    error(
+      "Failed to instantiate a new TypeScriptToLua class since the provided old class does not have a metatable.",
+    );
+  }
+
+  return newTSTLClassFromMetatable(metatable);
+}
+
+/** This is a re-implementation of the transpiled "__TS__New" function. */
+function newTSTLClassFromMetatable(metatable: TSTLClassMetatable): TSTLClass {
+  const newClass = new LuaTable<AnyNotNil, unknown>();
+  const newClassMetatable = setmetatable(
+    newClass,
+    metatable.constructor.prototype,
+  ) as unknown as TSTLClassMetatable;
+  newClassMetatable.____constructor(); // eslint-disable-line no-underscore-dangle
+
+  return newClass as unknown as TSTLClass;
+}

package/functions/types.ts

@@ -0,0 +1,36 @@
+export function isBoolean(variable: unknown): variable is boolean {
+  return type(variable) === "boolean";
+}
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function isFunction(variable: unknown): variable is Function {
+  return type(variable) === "function";
+}
+
+export function isNumber(variable: unknown): variable is number {
+  return type(variable) === "number";
+}
+
+/** Helper function to detect if a variable is a boolean, number, or string. */
+export function isPrimitive(
+  variable: unknown,
+): variable is boolean | number | string {
+  const variableType = type(variable);
+  return (
+    variableType === "boolean" ||
+    variableType === "number" ||
+    variableType === "string"
+  );
+}
+
+export function isString(variable: unknown): variable is string {
+  return type(variable) === "string";
+}
+
+export function isTable(variable: unknown): variable is LuaTable {
+  return type(variable) === "table";
+}
+
+export function isUserdata(variable: unknown): variable is LuaUserdata {
+  return type(variable) === "userdata";
+}

package/functions/ui.ts

@@ -0,0 +1,138 @@
+import { CollectibleType, LevelCurse } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+import { UI_HEART_WIDTH, VectorZero } from "../constants";
+import { copyVector } from "./vector";
+
+/**
+ * In the options menu, players have the ability to set a HUD offset. However, mods do not have
+ * access to this value. To get around this, Mod Config Menu provides a separate HUD offset setting
+ * on the first page of the menu. This is intended to be set by end-users to match their vanilla HUD
+ * offset setting so that mods can render UI elements to the screen in the correct position.
+ *
+ * @returns If the user does not have Mod Config Menu enabled, or does not have this option set,
+ *          then this function will return `Vector.Zero.` Otherwise, it will return a Vector that
+ *          represents a HUD offset that should be added to the position of a UI element.
+ */
+export function getHUDOffsetVector(): Vector {
+  const defaultVector = copyVector(VectorZero);
+
+  // Convert e.g. 0.4 to 4.
+  const hudOffset = math.floor(Options.HUDOffset * 10);
+
+  // Expected values are integers between 1 and 10.
+  if (hudOffset < 1 || hudOffset > 10) {
+    return defaultVector;
+  }
+
+  const x = hudOffset * 2;
+  let y = hudOffset;
+  if (y >= 4) {
+    y += 1;
+  }
+  if (y >= 9) {
+    y += 1;
+  }
+
+  return Vector(x, y);
+}
+
+/**
+ * Returns how many hearts are in the heart UI row. If the player has more than 6 hearts, this
+ * function will return 6.
+ */
+export function getHeartRowLength(player: EntityPlayer): int {
+  const maxHearts = player.GetMaxHearts();
+  const soulHearts = player.GetSoulHearts();
+  const boneHearts = player.GetBoneHearts();
+
+  const combinedHearts = maxHearts + soulHearts + boneHearts * 2; // There are no half bone hearts
+  const heartRowLength = combinedHearts / 2;
+
+  // After 6 hearts, the hearts wrap to a second row.
+  return Math.min(heartRowLength, 6);
+}
+
+/**
+ * Helper function to get the width of the first player's hearts on the UI. This is useful for
+ * drawing UI elements to the right of where the player's hearts are. Make sure to use this in
+ * combination with the the `getHUDOffsetVector` helper function.
+ */
+export function getHeartsUIWidth(): int {
+  const level = game.GetLevel();
+  const curses = level.GetCurses();
+  const player = Isaac.GetPlayer();
+  const extraLives = player.GetExtraLives();
+  const effects = player.GetEffects();
+  const hasHolyMantleEffect = effects.HasCollectibleEffect(
+    CollectibleType.HOLY_MANTLE,
+  );
+
+  let heartRowLength = getHeartRowLength(player);
+  if (hasHolyMantleEffect) {
+    heartRowLength += 1;
+  }
+  if (curses === LevelCurse.UNKNOWN) {
+    heartRowLength = 1;
+  }
+
+  let width = heartRowLength * UI_HEART_WIDTH;
+  if (extraLives > 9) {
+    width += 20;
+    if (player.HasCollectible(CollectibleType.GUPPYS_COLLAR)) {
+      width += 6;
+    }
+  } else if (extraLives > 0) {
+    width += 16;
+    if (player.HasCollectible(CollectibleType.GUPPYS_COLLAR)) {
+      width += 4;
+    }
+  }
+
+  return width;
+}
+
+export function getScreenBottomLeftPos(): Vector {
+  const bottomRight = getScreenBottomRightPos();
+  return Vector(0, bottomRight.Y);
+}
+
+export function getScreenBottomRightPos(): Vector {
+  const screenWidth = Isaac.GetScreenWidth();
+  const screenHeight = Isaac.GetScreenHeight();
+
+  return Vector(screenWidth, screenHeight);
+}
+
+export function getScreenCenterPos(): Vector {
+  const bottomRight = getScreenBottomRightPos();
+  return bottomRight.div(2);
+}
+
+export function getScreenTopLeftPos(): Vector {
+  return copyVector(VectorZero);
+}
+
+export function getScreenTopRightPos(): Vector {
+  const bottomRight = getScreenBottomRightPos();
+  return Vector(bottomRight.X, 0);
+}
+
+/**
+ * Get how many hearts are currently being shown on the hearts UI.
+ *
+ * This function is originally from piber20 Helper.
+ */
+export function getVisibleHearts(player: EntityPlayer): int {
+  const effectiveMaxHearts = player.GetEffectiveMaxHearts();
+  const soulHearts = player.GetSoulHearts();
+  const boneHearts = player.GetBoneHearts();
+
+  const maxHearts = math.max(effectiveMaxHearts, boneHearts * 2);
+
+  let visibleHearts = math.ceil((maxHearts + soulHearts) / 2);
+  if (visibleHearts < 1) {
+    visibleHearts = 1;
+  }
+
+  return visibleHearts;
+}

package/functions/utils.d.ts

@@ -1,42 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
 /// <reference types="isaac-typescript-definitions" />
-/**
- * Helper function to get type safety on a switch statement.
- *
- * Very useful to be future-safe against people adding values to a type or an enum.
- *
- * For example:
- *
- * ```ts
- * enum Situation {
- *   ONE,
- *   TWO,
- *   THREE,
- *   // FOUR, // If we uncomment this line, the program will no longer compile
- * }
- *
- * function handleSituation(situation: Situation) {
- *   switch (situation) {
- *     case Situation.ONE: {
- *       return 41;
- *     }
- *
- *     case Situation.TWO: {
- *       return 68;
- *     }
- *
- *     case Situation.THREE: {
- *       return 12;
- *     }
- *
- *     default: {
- *       return ensureAllCases(situation);
- *     }
- *   }
- * }
- * ```
- */
-export declare const ensureAllCases: (obj: never) => never;
 /**
  * Helper function to return an array with the elements from start to end. It is inclusive at the
  * start and exclusive at the end. (The "e" stands for exclusive.)

package/functions/utils.lua

@@ -7,41 +7,6 @@ local RenderMode = ____isaac_2Dtypescript_2Ddefinitions.RenderMode
 local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local HEX_STRING_LENGTH = 6
---- Helper function to get type safety on a switch statement.
--- 
--- Very useful to be future-safe against people adding values to a type or an enum.
--- 
--- For example:
--- 
--- ```ts
--- enum Situation {
---   ONE,
---   TWO,
---   THREE,
---   // FOUR, // If we uncomment this line, the program will no longer compile
--- }
--- 
--- function handleSituation(situation: Situation) {
---   switch (situation) {
---     case Situation.ONE: {
---       return 41;
---     }
--- 
---     case Situation.TWO: {
---       return 68;
---     }
--- 
---     case Situation.THREE: {
---       return 12;
---     }
--- 
---     default: {
---       return ensureAllCases(situation);
---     }
---   }
--- }
--- ```
-____exports.ensureAllCases = function(____, obj) return obj end
 --- Helper function to return an array with the elements from start to end. It is inclusive at the
 -- start and exclusive at the end. (The "e" stands for exclusive.)
 --