isaacscript-common 2.2.0 → 2.3.0

package/src/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/src/functions/tstlClass.ts

@@ -0,0 +1,91 @@
+import { DefaultMap } from "../classes/DefaultMap";
+import { TSTLClassMetatable } from "../interfaces/private/TSTLClassMetatable";
+import { TSTLClass } from "../types/private/TSTLClass";
+
+const TSTL_CLASS_METATABLE_KEYS: ReadonlySet<string> = new Set([
+  "____constructor",
+  "__index",
+  "constructor",
+]);
+
+/**
+ * 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 object instanceof DefaultMap;
+}
+
+/** 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;
+  }
+
+  const objectType = type(object);
+  if (objectType !== "table") {
+    return false;
+  }
+
+  const metatable = getmetatable(object);
+  if (metatable === undefined) {
+    return false;
+  }
+
+  let numKeys = 0;
+  for (const [key] of pairs(metatable)) {
+    numKeys += 1;
+
+    if (typeof key !== "string") {
+      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 {
+  return (
+    object instanceof Map ||
+    object instanceof Set ||
+    object instanceof WeakMap ||
+    object instanceof WeakSet
+  );
+}
+
+/**
+ * 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/src/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/src/functions/utils.ts

@@ -0,0 +1,200 @@
+import { RenderMode } from "isaac-typescript-definitions";
+import { game } from "../cachedClasses";
+
+const 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);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export const ensureAllCases = (obj: never): never => obj;
+
+/**
+ * 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.)
+ *
+ * For example, `erange(1, 3)` will return `[1, 2]`.
+ *
+ * If only one argument is specified, then it will assume that the start is 0.
+ */
+export function erange(start: int, end?: int): int[] {
+  if (end === undefined) {
+    end = start;
+    start = 0;
+  }
+
+  const array: int[] = [];
+  for (let i = start; i < end; i++) {
+    array.push(i);
+  }
+
+  return array;
+}
+
+/**
+ * Helper function to log what is happening in functions that recursively move through nested data
+ * structures.
+ */
+export function getTraversalDescription(
+  key: unknown,
+  traversalDescription: string,
+): string {
+  if (traversalDescription !== "") {
+    traversalDescription += " --> ";
+  }
+
+  traversalDescription += tostring(key);
+
+  return traversalDescription;
+}
+
+/**
+ * Converts a hex string like "#33aa33" to a KColor object.
+ *
+ * @param hexString A hex string like "#ffffff" or "ffffff". (The "#" character is optional.)
+ */
+export function hexToKColor(hexString: string, alpha: float): KColor {
+  hexString = hexString.replace("#", "");
+  if (hexString.length !== HEX_STRING_LENGTH) {
+    error(`Hex strings must be of length ${HEX_STRING_LENGTH}.`);
+  }
+
+  const rString = hexString.substr(0, 2);
+  const R = tonumber(`0x${rString}`);
+  if (R === undefined) {
+    error(`Failed to convert \`0x${rString}\` to a number.`);
+  }
+
+  const gString = hexString.substr(2, 2);
+  const G = tonumber(`0x${gString}`);
+  if (G === undefined) {
+    error(`Failed to convert \`0x${gString}\` to a number.`);
+  }
+
+  const bString = hexString.substr(4, 2);
+  const B = tonumber(`0x${bString}`);
+  if (B === undefined) {
+    error(`Failed to convert \`0x${bString}\` to a number.`);
+  }
+
+  // KColor values should be between 0 and 1.
+  const base = 255;
+  return KColor(R / base, G / base, B / base, alpha);
+}
+
+/**
+ * Helper function to return an array with the elements from start to end, inclusive. (The "i"
+ * stands for inclusive.)
+ *
+ * For example, `irange(1, 3)` will return `[1, 2, 3]`.
+ *
+ * If only one argument is specified, then it will assume that the start is 0.
+ */
+export function irange(start: int, end?: int): int[] {
+  if (end === undefined) {
+    end = start;
+    start = 0;
+  }
+
+  const array: int[] = [];
+  for (let i = start; i <= end; i++) {
+    array.push(i);
+  }
+
+  return array;
+}
+
+/**
+ * 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.
+ */
+export function isReflectionRender(): boolean {
+  const room = game.GetRoom();
+  const renderMode = room.GetRenderMode();
+  return renderMode === RenderMode.WATER_REFLECT;
+}
+
+/**
+ * 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
+ * of the message (which `Isaac.ConsoleOutput` does not do by default).
+ */
+export function printConsole(msg: string): void {
+  Isaac.ConsoleOutput(`${msg}\n`);
+}
+
+/** Helper function to print whether something was enabled or disabled to the in-game console. */
+export function printEnabled(enabled: boolean, description: string): void {
+  const enabledText = enabled ? "Enabled" : "Disabled";
+  printConsole(`${enabledText} ${description}.`);
+}
+
+/**
+ * Helper function to repeat code N times. This is faster to type and cleaner than using a for loop.
+ *
+ * For example:
+ *
+ * ```ts
+ * const player = Isaac.GetPlayer();
+ * repeat(10, () => {
+ *   player.AddCollectible(CollectibleType.STEVEN);
+ * });
+ * ```
+ *
+ * The repeated function is passed the index of the iteration, if needed:
+ *
+ * ```ts
+ * repeat(3, (i) => {
+ *   print(i); // Prints "0", "1", "2"
+ * });
+ * ```
+ */
+export function repeat(n: int, func: (i: int) => void): void {
+  for (let i = 0; i < n; i++) {
+    func(i);
+  }
+}
+
+/**
+ * Helper function to signify that the enclosing code block is not yet complete. Using this function
+ * is similar to writing a "TODO" comment, but it has the benefit of preventing ESLint errors due to
+ * early returns.
+ *
+ * When you see this function, it simply means that the programmer intends to add in more code to
+ * this spot later.
+ *
+ * This function does not actually do anything. (It is an "empty" function.)
+ */
+export function todo(): void {}