isaacscript-common 2.3.0 → 3.0.0

package/src/functions/trinkets.ts

@@ -1,215 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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

@@ -1,138 +0,0 @@
-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

@@ -1,200 +0,0 @@
-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 {}