isaacscript-common 14.2.0 → 15.0.1

package/src/classes/features/other/CustomHotkeys.ts

@@ -0,0 +1,154 @@
+import { Keyboard, ModCallback } from "isaac-typescript-definitions";
+import { Exported } from "../../../decorators";
+import { isKeyboardPressed } from "../../../functions/input";
+import { DefaultMap } from "../../DefaultMap";
+import { Feature } from "../../private/Feature";
+
+export class CustomHotkeys extends Feature {
+  /**
+   * The keys are the keyboard keys that trigger the hotkey. The values are the functions that
+   * contain the arbitrary code to run.
+   */
+  private staticHotkeyFunctionMap = new Map<Keyboard, () => void>();
+
+  /**
+   * The keys are the functions that determine what the hotkey key is. The values are the functions
+   * that contain the arbitrary code to run.
+   */
+  private dynamicHotkeyFunctionMap = new Map<
+    () => Keyboard | undefined,
+    () => void
+  >();
+
+  private keyPressedMap = new DefaultMap<Keyboard, boolean>(false);
+
+  /** @internal */
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.POST_RENDER, [this.postRender]], // 2
+    ];
+  }
+
+  // ModCallback.POST_RENDER (2)
+  private postRender = () => {
+    for (const [
+      keyboard,
+      triggerFunc,
+    ] of this.staticHotkeyFunctionMap.entries()) {
+      this.checkIfTriggered(keyboard, triggerFunc);
+    }
+
+    for (const [
+      keyboardFunc,
+      triggerFunc,
+    ] of this.dynamicHotkeyFunctionMap.entries()) {
+      const keyboard = keyboardFunc();
+      if (keyboard !== undefined) {
+        this.checkIfTriggered(keyboard, triggerFunc);
+      }
+    }
+  };
+
+  private checkIfTriggered(keyboard: Keyboard, triggerFunc: () => void) {
+    const isPressed = isKeyboardPressed(keyboard);
+    const wasPreviouslyPressed = this.keyPressedMap.getAndSetDefault(keyboard);
+    this.keyPressedMap.set(keyboard, isPressed);
+
+    if (isPressed && !wasPreviouslyPressed) {
+      triggerFunc();
+    }
+  }
+
+  /**
+   * Helper function to run arbitrary code when you press and release a specific keyboard key.
+   *
+   * This can be used to easily set up custom hotkeys to facilitate custom game features or to
+   * assist in debugging.
+   *
+   * This is different from the `setHotkey` function in that the keyboard activation key is not
+   * hardcoded and is instead the return value of a provided function. This is useful for situations
+   * where the key can change (like if end-users can specify a custom hotkey using Mod Config Menu).
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.CUSTOM_HOTKEYS`.
+   *
+   * @param getKeyFunc The function that returns the key that will trigger the hotkey.
+   * @param triggerFunc A function containing the arbitrary code that you want to execute when the
+   *                    hotkey is triggered.
+   */
+  @Exported
+  public setConditionalHotkey(
+    getKeyFunc: () => Keyboard | undefined,
+    triggerFunc: () => void,
+  ): void {
+    if (this.dynamicHotkeyFunctionMap.has(getKeyFunc)) {
+      error(
+        "Failed to register a hotkey due to a custom hotkey already being defined for the submitted function.",
+      );
+    }
+
+    this.dynamicHotkeyFunctionMap.set(getKeyFunc, triggerFunc);
+  }
+
+  /**
+   * Helper function to run arbitrary code when you press and release a specific keyboard key.
+   *
+   * This can be used to easily set up custom hotkeys to facilitate custom game features or to
+   * assist in debugging.
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.CUSTOM_HOTKEYS`.
+   *
+   * @param keyboard The key that you want to trigger the hotkey.
+   * @param triggerFunc A function containing the arbitrary code that you want to execute when the
+   *                    hotkey is triggered.
+   */
+  @Exported
+  public setHotkey(keyboard: Keyboard, triggerFunc: () => void): void {
+    if (this.staticHotkeyFunctionMap.has(keyboard)) {
+      error(
+        `Failed to register a hotkey due to a hotkey already being defined for: Keyboard.${Keyboard[keyboard]} (${keyboard})`,
+      );
+    }
+
+    this.staticHotkeyFunctionMap.set(keyboard, triggerFunc);
+  }
+
+  /**
+   * Helper function to remove a hotkey created with the `setConditionalHotkey` function.
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.CUSTOM_HOTKEYS`.
+   *
+   * @param getKeyFunc Equal to the `getKeyFunc` that you passed when initially registering the
+   *                   hotkey.
+   */
+  @Exported
+  public unsetConditionalHotkey(getKeyFunc: () => Keyboard | undefined): void {
+    if (!this.dynamicHotkeyFunctionMap.has(getKeyFunc)) {
+      error(
+        "Failed to unregister a hotkey since there is no existing hotkey defined for the submitted function.",
+      );
+    }
+
+    this.dynamicHotkeyFunctionMap.delete(getKeyFunc);
+  }
+
+  /**
+   * Helper function to remove a hotkey created with the `setHotkey` function.
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.CUSTOM_HOTKEYS`.
+   *
+   * @param keyboard Equal to the keyboard value that you passed when initially registering the
+   *                 hotkey.
+   */
+  @Exported
+  public unsetHotkey(keyboard: Keyboard): void {
+    if (!this.staticHotkeyFunctionMap.has(keyboard)) {
+      error(
+        `Failed to unregister a hotkey since there is no existing hotkey defined for: Keyboard.${Keyboard[keyboard]} (${keyboard})`,
+      );
+    }
+
+    this.staticHotkeyFunctionMap.delete(keyboard);
+  }
+}

package/src/classes/features/other/CustomItemPools.ts

@@ -0,0 +1,139 @@
+import { CollectibleType, ItemPoolType } from "isaac-typescript-definitions";
+import { Exported } from "../../../decorators";
+import { ModCallbackCustom } from "../../../enums/ModCallbackCustom";
+import { arrayRemoveIndexInPlace } from "../../../functions/array";
+import { copyMap } from "../../../functions/map";
+import { getRandomSeed } from "../../../functions/rng";
+import { getRandomIndexFromWeightedArray } from "../../../functions/weighted";
+import { WeightedArray } from "../../../types/WeightedArray";
+import { Feature } from "../../private/Feature";
+
+export class CustomItemPools extends Feature {
+  /** @internal */
+  public override v = {
+    run: {
+      customItemPools: new Map<ItemPoolType, WeightedArray<CollectibleType>>(),
+    },
+  };
+
+  private customItemPoolMap = new Map<
+    ItemPoolType,
+    WeightedArray<CollectibleType>
+  >();
+
+  /** @internal */
+  constructor() {
+    super();
+
+    this.customCallbacksUsed = [
+      [
+        ModCallbackCustom.POST_GAME_STARTED_REORDERED,
+        [this.postGameStartedReordered],
+      ],
+    ];
+  }
+
+  // ModCallbackCustom.POST_GAME_STARTED_REORDERED
+  private postGameStartedReordered = (isContinued: boolean) => {
+    if (isContinued) {
+      return;
+    }
+
+    this.v.run.customItemPools = copyMap(this.customItemPoolMap);
+  };
+
+  /**
+   * Helper function to register a custom item pool. Use this function once when your mod first
+   * loads to declare the items that you want to be in the item pools. Then, in the middle of a run,
+   * you can use `getCustomItemPoolCollectible`.
+   *
+   * For example:
+   *
+   * ```ts
+   * const ItemPoolTypeCustom = {
+   *   FOO = 0 as ItemPoolType,
+   * } as const;
+   *
+   * const FOO_ITEM_POOL = [
+   *   [CollectibleType.SAD_ONION, 1],
+   *   [CollectibleType.INNER_EYE, 0.5],
+   * ];
+   *
+   * registerCustomItemPool(ItemPoolTypeCustom.FOO, FOO_ITEM_POOL);
+   * ```
+   *
+   * Note that custom item pools do not currently support partial weight decrementation on sight.
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.CUSTOM_ITEM_POOLS`.
+   *
+   * @param itemPoolTypeCustom An integer that identifies what kind of item pool you are creating.
+   *                           It should correspond to a local `ItemPoolTypeCustom` enum in your
+   *                           mod. The integer can be any unique value and can safely overlap with
+   *                           the vanilla item pool type values (or values chosen by other mods).
+   * @param collectibles An array of weighted collectible tuples that represent the item pool that
+   *                     you are creating. The first element in he tuple is the `CollectibleType`,
+   *                     and the second element in the tuple is the float that represents the weight
+   *                     of the collectible.
+   */
+  @Exported
+  public registerCustomItemPool(
+    itemPoolTypeCustom: ItemPoolType,
+    collectibles: WeightedArray<CollectibleType>,
+  ): void {
+    if (this.customItemPoolMap.has(itemPoolTypeCustom)) {
+      error(
+        `Failed to register a custom item pool since the provided type of ${itemPoolTypeCustom} was already registered.`,
+      );
+    }
+
+    this.customItemPoolMap.set(itemPoolTypeCustom, collectibles);
+  }
+
+  /**
+   * Helper function to get a new collectible from a custom item pool created with the
+   * `registerCustomItemPool` function. This function has the same format as the
+   * `ItemPool.GetCollectible` method.
+   *
+   * By default, a collectible will not be removed from the pool once it is selected, unless the
+   * `decrease` argument is set to true (similar to how a vanilla item pool works).
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.CUSTOM_ITEM_POOLS`.
+   *
+   * @param itemPoolTypeCustom An integer representing the custom item pool to use.
+   * @param decrease Optional. Whether or not to remove the selected collectible from the item pool.
+   *                 Default is true.
+   * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided,
+   *                  the `RNG.Next` method will be called. Default is `getRandomSeed()`.
+   * @param defaultItem Optional. The collectible to return if the item pool is depleted. Default is
+   *                    `CollectibleType.NULL`.
+   */
+  @Exported
+  public getCustomItemPoolCollectible(
+    itemPoolTypeCustom: ItemPoolType,
+    decrease = false,
+    seedOrRNG: Seed | RNG = getRandomSeed(),
+    defaultItem = CollectibleType.NULL,
+  ): CollectibleType {
+    const customItemPool = this.v.run.customItemPools.get(itemPoolTypeCustom);
+    if (customItemPool === undefined) {
+      error(`Failed to find the custom item pool of: ${itemPoolTypeCustom}`);
+    }
+
+    if (customItemPool.length === 0) {
+      return defaultItem;
+    }
+
+    const randomIndex = getRandomIndexFromWeightedArray(
+      customItemPool,
+      seedOrRNG,
+    );
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const tuple = customItemPool[randomIndex]!;
+
+    if (decrease) {
+      arrayRemoveIndexInPlace(customItemPool, randomIndex);
+    }
+
+    return tuple[0];
+  }
+}

package/src/classes/features/other/CustomPickups.ts

@@ -0,0 +1,152 @@
+// One of the functions below causes a false positive for ESLint:
+// https://github.com/gajus/eslint-plugin-jsdoc/issues/915
+/* eslint-disable jsdoc/check-param-names */
+
+import {
+  EffectVariant,
+  EntityType,
+  ModCallback,
+  PickupVariant,
+} from "isaac-typescript-definitions";
+import { Exported } from "../../../decorators";
+import { LadderSubTypeCustom } from "../../../enums/LadderSubTypeCustom";
+import {
+  getEntityID,
+  getEntityIDFromConstituents,
+} from "../../../functions/entities";
+import { spawnEffect } from "../../../functions/entitiesSpecific";
+import { asNumber } from "../../../functions/types";
+import { Feature } from "../../private/Feature";
+
+interface CustomPickupFunctions {
+  collectFunc: (this: void, player: EntityPlayer) => void;
+  collisionFunc: (this: void, player: EntityPlayer) => boolean;
+}
+
+/**
+ * Normally, we would make a custom entity to represent a fading-away pickup, but we don't want to
+ * interfere with the "entities2.xml" file in end-user mods. Thus, we must select a vanilla effect
+ * to masquerade as a backdrop effect.
+ *
+ * We arbitrarily choose a ladder for this purpose because it will not automatically despawn after
+ * time passes, like most other effects.
+ */
+const PICKUP_EFFECT_VARIANT = EffectVariant.LADDER;
+const PICKUP_EFFECT_SUB_TYPE = LadderSubTypeCustom.CUSTOM_PICKUP;
+
+export class CustomPickups extends Feature {
+  /** Indexed by entity ID. */
+  private customPickupFunctionsMap = new Map<string, CustomPickupFunctions>();
+
+  /** @internal */
+  constructor() {
+    super();
+
+    this.callbacksUsed = [
+      [ModCallback.PRE_PICKUP_COLLISION, [this.prePickupCollision]], // 38
+      [
+        ModCallback.POST_EFFECT_RENDER,
+        [this.postEffectRenderPickupEffect, PICKUP_EFFECT_VARIANT],
+      ], // 56
+    ];
+  }
+
+  // ModCallback.PRE_PICKUP_COLLISION (38)
+  private prePickupCollision = (
+    pickup: EntityPickup,
+    collider: Entity,
+  ): boolean | undefined => {
+    const entityID = getEntityID(pickup);
+    const customPickupFunctions = this.customPickupFunctionsMap.get(entityID);
+    if (customPickupFunctions === undefined) {
+      return undefined;
+    }
+
+    const player = collider.ToPlayer();
+    if (player === undefined) {
+      return undefined;
+    }
+
+    const shouldPickup = customPickupFunctions.collisionFunc(player);
+    if (!shouldPickup) {
+      return undefined;
+    }
+
+    pickup.Remove();
+
+    const pickupSprite = pickup.GetSprite();
+    const fileName = pickupSprite.GetFilename();
+
+    const effect = spawnEffect(
+      PICKUP_EFFECT_VARIANT,
+      PICKUP_EFFECT_SUB_TYPE,
+      pickup.Position,
+    );
+    const effectSprite = effect.GetSprite();
+    effectSprite.Load(fileName, true);
+    effectSprite.Play("Collect", true);
+
+    customPickupFunctions.collectFunc(player);
+
+    return undefined;
+  };
+
+  // ModCallback.POST_EFFECT_RENDER (56)
+  // PICKUP_EFFECT_VARIANT
+  // eslint-disable-next-line class-methods-use-this
+  private postEffectRenderPickupEffect = (effect: EntityEffect) => {
+    if (effect.SubType !== asNumber(PICKUP_EFFECT_SUB_TYPE)) {
+      return;
+    }
+
+    const sprite = effect.GetSprite();
+    if (sprite.IsFinished("Collect")) {
+      effect.Remove();
+    }
+  };
+
+  /**
+   * Helper function to register a custom pickup with the IsaacScript standard library. Use this
+   * feature for custom pickups that are intended to be picked up by the player, like bombs and
+   * keys.
+   *
+   * When IsaacScript detects that a player should be collecting the custom pickup, then the pickup
+   * will be immediately removed, and an effect showing the pickup's respective `Collect` animation
+   * will be spawned. (This emulates how a normal vanilla pickup would work.) After that, the
+   * provided `collectFunc` will be fired. In this function, you will probably want to play a sound
+   * corresponding to what kind of pickup it is (e.g. `SoundEffect.KEY_PICKUP_GAUNTLET`), as well as
+   * do things like adding something to the player's inventory.
+   *
+   * Note that when you specify your custom pickup in the "entities2.xml" file, it should have a
+   * type of "5" and be associated with an anm2 file that has a "Collect" animation.
+   *
+   * In order to use this function, you must upgrade your mod with `ISCFeature.CUSTOM_PICKUPS`.
+   *
+   * @param pickupVariantCustom The variant for the corresponding custom pickup.
+   * @param subType The sub-type for the corresponding custom pickup.
+   * @param collectFunc The function to run when the player collects this pickup.
+   * @param collisionFunc Optional. The function to run when a player collides with the pickup.
+   *                      Default is a function that always returns true, meaning that the player
+   *                      will always immediately collect the pickup when they collide with it.
+   *                      Specify this function if your pickup should only be able to be collected
+   *                      under certain conditions.
+   */
+  @Exported
+  public registerCustomPickup(
+    pickupVariantCustom: PickupVariant,
+    subType: int,
+    collectFunc: (this: void, player: EntityPlayer) => void,
+    collisionFunc: (this: void, player: EntityPlayer) => boolean = () => true,
+  ): void {
+    const entityID = getEntityIDFromConstituents(
+      EntityType.PICKUP,
+      pickupVariantCustom,
+      subType,
+    );
+    const customPickupFunctions: CustomPickupFunctions = {
+      collectFunc,
+      collisionFunc,
+    };
+    this.customPickupFunctionsMap.set(entityID, customPickupFunctions);
+  }
+}