isaacscript-common/dist/functions/utils.d.ts

Helper functions and features for IsaacScript mods.

/**
 * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
 * to `undefined`.
 *
 * This is useful to have TypeScript narrow a `T | undefined` value to `T` in a concise way.
 */
export declare function assertDefined<T>(value: T, ...[msg]: [undefined] extends [T] ? [string] : [
    "The assertion is useless because the provided value does not contain undefined."
]): asserts value is Exclude<T, undefined>;
/**
 * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
 * to `null`.
 *
 * This is useful to have TypeScript narrow a `T | null` value to `T` in a concise way.
 */
export declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T] ? [string] : [
    "The assertion is useless because the provided value does not contain null."
]): asserts value is Exclude<T, null>;
/**
 * Helper function to return an array of integers with the specified range, inclusive on the lower
 * end and exclusive on the high end. (The "e" in the function name stands for exclusive.) Thus,
 * this function works in a similar way as the built-in `range` function from Python.
 *
 * If the end is lower than the start, an empty array will be returned.
 *
 * For example:
 *
 * - `eRange(2)` returns `[0, 1]`.
 * - `eRange(3)` returns `[0, 1, 2]`.
 * - `eRange(-3)` returns `[0, -1, -2]`.
 * - `eRange(1, 3)` returns `[1, 2]`.
 * - `eRange(2, 5)` returns `[2, 3, 4]`.
 * - `eRange(5, 2)` returns `[]`.
 * - `eRange(3, 3)` returns `[]`.
 *
 * @param start The integer to start at.
 * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
 *            first argument will be the end.
 * @param increment Optional. The increment to use. Default is 1.
 */
export declare function eRange(start: int, end?: int, increment?: number): readonly int[];
/**
 * Helper function to log what is happening in functions that recursively move through nested data
 * structures.
 */
export declare function getTraversalDescription(key: unknown, traversalDescription: string): string;
/**
 * Helper function to return an array of integers with the specified range, inclusive on both ends.
 * (The "i" in the function name stands for inclusive.)
 *
 * If the end is lower than the start, an empty array will be returned.
 *
 * For example:
 *
 * - `iRange(2)` returns `[0, 1, 2]`.
 * - `iRange(3)` returns `[0, 1, 2, 3]`.
 * - `iRange(-3)` returns `[0, -1, -2, -3]`.
 * - `iRange(1, 3)` returns `[1, 2, 3]`.
 * - `iRange(2, 5)` returns `[2, 3, 4, 5]`.
 * - `iRange(5, 2)` returns `[]`.
 * - `iRange(3, 3)` returns `[3]`.
 *
 * @param start The integer to start at.
 * @param end Optional. The integer to end at. If not specified, then the start will be 0 and the
 *            first argument will be the end.
 * @param increment Optional. The increment to use. Default is 1.
 */
export declare function iRange(start: int, end?: int, increment?: number): readonly int[];
/**
 * Helper function to check if a variable is within a certain range, inclusive on both ends.
 *
 * - For example, `inRange(1, 1, 3)` will return `true`.
 * - For example, `inRange(0, 1, 3)` will return `false`.
 *
 * @param num The number to check.
 * @param start The start of the range to check.
 * @param end The end of the range to check.
 */
export declare function inRange(num: int, start: int, end: int): boolean;
/**
 * Helper function to detect if there is two or more players currently playing.
 *
 * Specifically, this function looks for unique `ControllerIndex` values across all players.
 *
 * This function is not safe to use in the `POST_PLAYER_INIT` callback, because the
 * `ControllerIndex` will not be set properly. As a workaround, you can use it in the
 * `POST_PLAYER_INIT_FIRST` callback (or some other callback like `POST_UPDATE`).
 */
export declare function isMultiplayer(): boolean;
/**
 * Helper function to check if the player has the Repentance DLC installed.
 *
 * This function should always be used over the `REPENTANCE` constant, since the latter is not safe.
 *
 * Specifically, this function checks for the `Sprite.GetAnimation` method:
 * https://bindingofisaacrebirth.fandom.com/wiki/V1.06.J818#Lua_Changes
 */
export declare function isRepentance(): boolean;
/**
 * Helper function to check if the player has the Repentance+ DLC installed.
 *
 * This function should always be used over the `REPENTANCE_PLUS` constant, since the latter is not
 * safe.
 *
 * Specifically, this function checks for `Room:DamageGridWithSource` method:
 * https://bindingofisaacrebirth.wiki.gg/wiki/The_Binding_of_Isaac:_Repentance%2B#Modding_Changes
 */
export declare function isRepentancePlus(): boolean;
/**
 * Helper function to check if the player is using REPENTOGON, an exe-hack which expands the modding
 * API.
 *
 * Although REPENTOGON has a `REPENTOGON` global to check if it's present, it is not safe to use as
 * it can be overwritten by other mods.
 *
 * Specifically, this function checks for the `Sprite.Continue` method:
 * https://repentogon.com/Sprite.html#continue
 */
export declare function isRepentogon(): boolean;
/**
 * 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 declare function repeat(num: int, func: (i: int) => void): void;
/**
 * 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
 * unused variables or 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 is variadic, meaning that you can pass as many arguments as you want. (This is
 * useful as a means to prevent unused variables.)
 *
 * This function does not actually do anything. (It is an "empty" function.)
 *
 * @allowEmptyVariadic
 */
export declare function todo(...args: readonly unknown[]): void;
//# sourceMappingURL=utils.d.ts.map