isaacscript-common/dist/classes/ModFeature.d.ts

Helper functions and features for IsaacScript mods.

import type { ModCallback } from "isaac-typescript-definitions";
import type { ModCallbackCustom } from "../enums/ModCallbackCustom";
import type { ModUpgraded } from "./ModUpgraded";
export declare const MOD_FEATURE_CALLBACKS_KEY = "__callbacks";
export declare const MOD_FEATURE_CUSTOM_CALLBACKS_KEY = "__customCallbacks";
/**
 * Helper class for mods that want to represent their individual features as classes. Extend your
 * mod features from this class in order to enable the `@Callback` and `@CustomCallback` decorators
 * that automatically subscribe to callbacks.
 *
 * It is recommended that you use the `initModFeatures` helper function to instantiate all of your
 * mod classes (instead of instantiating them yourself). This is so that any attached `v` objects
 * are properly registered with the save data manager; see below.
 *
 * If you are manually instantiating a mod feature yourself, then:
 *
 * - You must pass your upgraded mod as the first argument to the constructor.
 * - In almost all cases, you will want the callback functions to be immediately subscribed after
 *   instantiating the class. However, if this is not the case, you can pass `false` as the optional
 *   second argument to the constructor.
 *
 * If your mod feature has a property called `v`, it will be assumed that these are variables that
 * should be managed by the save data manager. Unfortunately, due to technical limitations with
 * classes, this registration will only occur if you initialize the class with the `initModFeatures`
 * helper function. (This is because the parent class does not have access to the child's properties
 * upon first construction.)
 */
export declare class ModFeature {
    private readonly mod;
    /**
     * An optional method that allows for conditional callback execution. If specified, any class
     * method that is annotated with a `@Callback` or `@CallbackCustom` decorator will only be fired
     * if the executed conditional function returns true.
     *
     * This property is used to easily turn entire mod features on and off (rather than repeating
     * conditional logic and early returning at the beginning of every callback function).
     *
     * Since the specific information for the firing callback is passed as arguments into the
     * conditional method, you can also write logic that would only apply to a specific type of
     * callback.
     *
     * By default, this is set to null, which means that all callback methods will fire
     * unconditionally. Override this property in your class if you need to use it.
     *
     * The function has the following signature:
     *
     * ```ts
     * <T extends boolean>(
     *   vanilla: T, // Whether this is a vanilla or custom callback.
     *   modCallback: T extends true ? ModCallback : ModCallbackCustom,
     *   ...callbackArgs: unknown[] // This would be e.g. `pickup: EntityPickup` for the `POST_PICKUP_INIT` callback.
     * ) => boolean;
     * ```
     */
    protected shouldCallbackMethodsFire: (<T extends boolean>(vanilla: T, modCallback: T extends true ? ModCallback : ModCallbackCustom, ...callbackArgs: readonly unknown[]) => boolean) | null;
    /**
     * Whether the feature has registered its callbacks yet.
     *
     * This will almost always be equal to true unless you explicitly passed `false` to the second
     * argument of the constructor.
     */
    initialized: boolean;
    constructor(mod: ModUpgraded, init?: boolean);
    /**
     * Runs the `Mod.AddCallback` and `ModUpgraded.AddCallbackCustom` methods for all of the decorated
     * callbacks. Also registers/unregisters the "v" variable on the save data manager.
     *
     * @param init Optional. Whether to initialize or uninitialize. Default is true.
     */
    init(init?: boolean): void;
    /**
     * Runs the `Mod.RemoveCallback` and `ModUpgraded.RemoveCallbackCustom` methods for all of the
     * decorated callbacks.
     *
     * This is just an alias for `ModFeature.init(false)`.
     */
    uninit(): void;
}
//# sourceMappingURL=ModFeature.d.ts.map