isaacscript-common 84.0.0 → 84.1.0

package/dist/classes/features/other/CollectibleItemPoolType.js

@@ -0,0 +1,75 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectibleItemPoolType = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const cachedClasses_1 = require("../../../core/cachedClasses");
+const decorators_1 = require("../../../decorators");
+const ISCFeature_1 = require("../../../enums/ISCFeature");
+const entities_1 = require("../../../functions/entities");
+const pickupVariants_1 = require("../../../functions/pickupVariants");
+const rooms_1 = require("../../../functions/rooms");
+const Feature_1 = require("../../private/Feature");
+const v = {
+    run: {
+        collectibleItemPoolTypeMap: new Map(),
+    },
+};
+class CollectibleItemPoolType extends Feature_1.Feature {
+    /** @internal */
+    v = v;
+    pickupIndexCreation;
+    /** @internal */
+    constructor(pickupIndexCreation) {
+        super();
+        this.featuresUsed = [ISCFeature_1.ISCFeature.PICKUP_INDEX_CREATION];
+        this.callbacksUsed = [
+            // 34
+            [
+                isaac_typescript_definitions_1.ModCallback.POST_PICKUP_INIT,
+                this.postPickupInitCollectible,
+                [isaac_typescript_definitions_1.PickupVariant.COLLECTIBLE],
+            ],
+        ];
+        this.pickupIndexCreation = pickupIndexCreation;
+    }
+    // ModCallback.POST_PICKUP_INIT (34)
+    // PickupVariant.COLLECTIBLE (100)
+    postPickupInitCollectible = (collectible) => {
+        const pickupIndex = this.pickupIndexCreation.getPickupIndex(collectible);
+        if (!v.run.collectibleItemPoolTypeMap.has(pickupIndex)) {
+            const itemPool = cachedClasses_1.game.GetItemPool();
+            const lastItemPoolType = itemPool.GetLastPool();
+            v.run.collectibleItemPoolTypeMap.set(pickupIndex, lastItemPoolType);
+        }
+    };
+    /**
+     * Helper function to get the item pool type that a given collectible came from. Since there is no
+     * native method in the API to get this, we listen in the `POST_PICKUP_INIT` callback for
+     * collectibles, use the `ItemPool.GetLastPool` method, and then assume that the collectible
+     * matches.
+     *
+     * In order to use this function, you must upgrade your mod with
+     * `ISCFeature.COLLECTIBLE_ITEM_POOL_TYPE`.
+     *
+     * @public
+     */
+    getCollectibleItemPoolType(collectible) {
+        if (!(0, pickupVariants_1.isCollectible)(collectible)) {
+            const entityID = (0, entities_1.getEntityID)(collectible);
+            error(`The "getCollectibleItemPoolType" function was given a non-collectible: ${entityID}`);
+        }
+        const pickupIndex = this.pickupIndexCreation.getPickupIndex(collectible);
+        const itemPoolType = v.run.collectibleItemPoolTypeMap.get(pickupIndex);
+        return itemPoolType ?? (0, rooms_1.getRoomItemPoolType)();
+    }
+}
+exports.CollectibleItemPoolType = CollectibleItemPoolType;
+__decorate([
+    decorators_1.Exported
+], CollectibleItemPoolType.prototype, "getCollectibleItemPoolType", null);

package/dist/classes/features/other/CustomHotkeys.js

@@ -0,0 +1,144 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomHotkeys = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const decorators_1 = require("../../../decorators");
+const input_1 = require("../../../functions/input");
+const DefaultMap_1 = require("../../DefaultMap");
+const Feature_1 = require("../../private/Feature");
+class CustomHotkeys extends Feature_1.Feature {
+    /**
+     * The keys are the keyboard keys that trigger the hotkey. The values are the functions that
+     * contain the arbitrary code to run.
+     */
+    staticHotkeyFunctionMap = new Map();
+    /**
+     * The keys are the functions that determine what the hotkey key is. The values are the functions
+     * that contain the arbitrary code to run.
+     */
+    dynamicHotkeyFunctionMap = new Map();
+    keyPressedMap = new DefaultMap_1.DefaultMap(false);
+    /** @internal */
+    constructor() {
+        super();
+        this.callbacksUsed = [
+            // 2
+            [isaac_typescript_definitions_1.ModCallback.POST_RENDER, this.postRender],
+        ];
+    }
+    // ModCallback.POST_RENDER (2)
+    postRender = () => {
+        for (const [keyboard, triggerFunc] of this.staticHotkeyFunctionMap) {
+            this.checkIfTriggered(keyboard, triggerFunc);
+        }
+        for (const [keyboardFunc, triggerFunc] of this.dynamicHotkeyFunctionMap) {
+            const keyboard = keyboardFunc();
+            if (keyboard !== undefined) {
+                this.checkIfTriggered(keyboard, triggerFunc);
+            }
+        }
+    };
+    checkIfTriggered(keyboard, triggerFunc) {
+        const isPressed = (0, input_1.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.
+     *
+     * Inputs are checked for in the `POST_RENDER` callback.
+     *
+     * 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.
+     * @public
+     */
+    setConditionalHotkey(getKeyFunc, triggerFunc) {
+        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.
+     *
+     * Inputs are checked for in the `POST_RENDER` callback.
+     *
+     * 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.
+     * @public
+     */
+    setHotkey(keyboard, triggerFunc) {
+        if (this.staticHotkeyFunctionMap.has(keyboard)) {
+            error(`Failed to register a hotkey due to a hotkey already being defined for: Keyboard.${isaac_typescript_definitions_1.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.
+     * @public
+     */
+    unsetConditionalHotkey(getKeyFunc) {
+        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.
+     * @public
+     */
+    unsetHotkey(keyboard) {
+        if (!this.staticHotkeyFunctionMap.has(keyboard)) {
+            error(`Failed to unregister a hotkey since there is no existing hotkey defined for: Keyboard.${isaac_typescript_definitions_1.Keyboard[keyboard]} (${keyboard})`);
+        }
+        this.staticHotkeyFunctionMap.delete(keyboard);
+    }
+}
+exports.CustomHotkeys = CustomHotkeys;
+__decorate([
+    decorators_1.Exported
+], CustomHotkeys.prototype, "setConditionalHotkey", null);
+__decorate([
+    decorators_1.Exported
+], CustomHotkeys.prototype, "setHotkey", null);
+__decorate([
+    decorators_1.Exported
+], CustomHotkeys.prototype, "unsetConditionalHotkey", null);
+__decorate([
+    decorators_1.Exported
+], CustomHotkeys.prototype, "unsetHotkey", null);

package/dist/classes/features/other/CustomItemPools.js

@@ -0,0 +1,128 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomItemPools = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const decorators_1 = require("../../../decorators");
+const ModCallbackCustom_1 = require("../../../enums/ModCallbackCustom");
+const array_1 = require("../../../functions/array");
+const map_1 = require("../../../functions/map");
+const utils_1 = require("../../../functions/utils");
+const weighted_1 = require("../../../functions/weighted");
+const ReadonlyMap_1 = require("../../../types/ReadonlyMap");
+const Feature_1 = require("../../private/Feature");
+const v = {
+    run: {
+        customItemPools: new ReadonlyMap_1.ReadonlyMap(),
+    },
+};
+const customItemPoolMap = new Map();
+class CustomItemPools extends Feature_1.Feature {
+    /** @internal */
+    v = v;
+    /** @internal */
+    constructor() {
+        super();
+        this.customCallbacksUsed = [
+            [
+                ModCallbackCustom_1.ModCallbackCustom.POST_GAME_STARTED_REORDERED,
+                this.postGameStartedReorderedFalse,
+                [false],
+            ],
+        ];
+    }
+    // ModCallbackCustom.POST_GAME_STARTED_REORDERED
+    // false
+    postGameStartedReorderedFalse = () => {
+        v.run.customItemPools = (0, map_1.copyMap)(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.
+     * @public
+     */
+    registerCustomItemPool(itemPoolTypeCustom, collectibles) {
+        if (customItemPoolMap.has(itemPoolTypeCustom)) {
+            error(`Failed to register a custom item pool since the provided type of ${itemPoolTypeCustom} was already registered.`);
+        }
+        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).
+     *
+     * If you want to get an unseeded collectible type, you must explicitly pass `undefined` to the
+     * `seedOrRNG` parameter.
+     *
+     * 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 seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+     *                  `RNG.Next` method will be called. If `undefined` is provided, it will default
+     *                  to a random seed.
+     * @param decrease Optional. Whether to remove the selected collectible from the item pool.
+     *                 Default is true.
+     * @param defaultItem Optional. The collectible to return if the item pool is depleted. Default is
+     *                    `CollectibleType.NULL`.
+     * @public
+     */
+    getCustomItemPoolCollectible(itemPoolTypeCustom, seedOrRNG, decrease = false, defaultItem = isaac_typescript_definitions_1.CollectibleType.NULL) {
+        const customItemPool = v.run.customItemPools.get(itemPoolTypeCustom);
+        (0, utils_1.assertDefined)(customItemPool, `Failed to find the custom item pool of: ${itemPoolTypeCustom}`);
+        if (customItemPool.length === 0) {
+            return defaultItem;
+        }
+        const randomIndex = (0, weighted_1.getRandomIndexFromWeightedArray)(customItemPool, seedOrRNG);
+        const tuple = customItemPool[randomIndex];
+        (0, utils_1.assertDefined)(tuple, `Failed to get an element from a custom item pool using a random index of: ${randomIndex}`);
+        if (decrease) {
+            (0, array_1.arrayRemoveIndexInPlace)(customItemPool, randomIndex);
+        }
+        return tuple[0];
+    }
+}
+exports.CustomItemPools = CustomItemPools;
+__decorate([
+    decorators_1.Exported
+], CustomItemPools.prototype, "registerCustomItemPool", null);
+__decorate([
+    decorators_1.Exported
+], CustomItemPools.prototype, "getCustomItemPoolCollectible", null);

package/dist/classes/features/other/CustomPickups.js

@@ -0,0 +1,118 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomPickups = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const decorators_1 = require("../../../decorators");
+const LadderSubTypeCustom_1 = require("../../../enums/LadderSubTypeCustom");
+const entities_1 = require("../../../functions/entities");
+const entitiesSpecific_1 = require("../../../functions/entitiesSpecific");
+const Feature_1 = require("../../private/Feature");
+/**
+ * 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 = isaac_typescript_definitions_1.EffectVariant.LADDER;
+const PICKUP_EFFECT_SUB_TYPE = LadderSubTypeCustom_1.LadderSubTypeCustom.CUSTOM_PICKUP;
+class CustomPickups extends Feature_1.Feature {
+    /** Indexed by entity ID. */
+    customPickupFunctionsMap = new Map();
+    /** @internal */
+    constructor() {
+        super();
+        this.callbacksUsed = [
+            // 38
+            [isaac_typescript_definitions_1.ModCallback.PRE_PICKUP_COLLISION, this.prePickupCollision],
+            // 56
+            [
+                isaac_typescript_definitions_1.ModCallback.POST_EFFECT_RENDER,
+                this.postEffectRenderPickupEffect,
+                [PICKUP_EFFECT_VARIANT],
+            ],
+        ];
+    }
+    // ModCallback.PRE_PICKUP_COLLISION (38)
+    prePickupCollision = (pickup, collider) => {
+        const entityID = (0, entities_1.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 = (0, entitiesSpecific_1.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
+    postEffectRenderPickupEffect = (effect) => {
+        if (effect.SubType !== 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.
+     * @public
+     */
+    registerCustomPickup(pickupVariantCustom, subType, collectFunc, collisionFunc = () => true) {
+        const entityID = (0, entities_1.getEntityIDFromConstituents)(isaac_typescript_definitions_1.EntityType.PICKUP, pickupVariantCustom, subType);
+        const customPickupFunctions = {
+            collectFunc,
+            collisionFunc,
+        };
+        this.customPickupFunctionsMap.set(entityID, customPickupFunctions);
+    }
+}
+exports.CustomPickups = CustomPickups;
+__decorate([
+    decorators_1.Exported
+], CustomPickups.prototype, "registerCustomPickup", null);