Skip to main content

Utils

Functions​

assertDefined​

▸ assertDefined<T>(value, ...«destructured»): asserts value is Exclude<T, undefined>

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.

Type parameters​

Name
T

Parameters​

NameType
valueT
...«destructured»[undefined] extends [T] ? [string] : ["The assertion is useless because the provided value does not contain undefined."]

Returns​

asserts value is Exclude<T, undefined>

Defined in​

packages/isaacscript-common/src/functions/utils.ts:11

assertNotNull​

▸ assertNotNull<T>(value, ...«destructured»): asserts value is Exclude<T, null>

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.

Type parameters​

Name
T

Parameters​

NameType
valueT
...«destructured»[null] extends [T] ? [string] : ["The assertion is useless because the provided value does not contain null."]

Returns​

asserts value is Exclude<T, null>

Defined in​

packages/isaacscript-common/src/functions/utils.ts:30

eRange​

▸ eRange(start, end?, increment?): readonly int[]

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 [].

Parameters​

NameTypeDefault valueDescription
startintundefinedThe integer to start at.
end?intundefinedOptional. The integer to end at. If not specified, then the start will be 0 and the first argument will be the end.
incrementnumber1Optional. The increment to use. Default is 1.

Returns​

readonly int[]

Defined in​

packages/isaacscript-common/src/functions/utils.ts:65

getTraversalDescription​

▸ getTraversalDescription(key, traversalDescription): string

Helper function to log what is happening in functions that recursively move through nested data structures.

Parameters​

NameType
keyunknown
traversalDescriptionstring

Returns​

string

Defined in​

packages/isaacscript-common/src/functions/utils.ts:83

iRange​

▸ iRange(start, end?, increment?): readonly int[]

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].

Parameters​

NameTypeDefault valueDescription
startintundefinedThe integer to start at.
end?intundefinedOptional. The integer to end at. If not specified, then the start will be 0 and the first argument will be the end.
incrementnumber1Optional. The increment to use. Default is 1.

Returns​

readonly int[]

Defined in​

packages/isaacscript-common/src/functions/utils.ts:117

inRange​

▸ inRange(num, start, end): boolean

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.

Parameters​

NameTypeDescription
numintThe number to check.
startintThe start of the range to check.
endintThe end of the range to check.

Returns​

boolean

Defined in​

packages/isaacscript-common/src/functions/utils.ts:136

isMultiplayer​

▸ isMultiplayer(): 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).

Returns​

boolean

Defined in​

packages/isaacscript-common/src/functions/utils.ts:149

isRepentance​

▸ isRepentance(): boolean

Helper function to check if the player is using Afterbirth+ or Repentance.

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

Returns​

boolean

Defined in​

packages/isaacscript-common/src/functions/utils.ts:165

isRepentogon​

▸ isRepentogon(): 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

Returns​

boolean

Defined in​

packages/isaacscript-common/src/functions/utils.ts:194

repeat​

▸ repeat(num, func): void

Helper function to repeat code N times. This is faster to type and cleaner than using a for loop.

For example:

const player = Isaac.GetPlayer();
repeat(10, () => {
  player.AddCollectible(CollectibleType.STEVEN);
});

The repeated function is passed the index of the iteration, if needed:

repeat(3, (i) => {
  print(i); // Prints "0", "1", "2"
});

Parameters​

NameType
numint
func(i: int) => void

Returns​

void

Defined in​

packages/isaacscript-common/src/functions/utils.ts:233

todo​

▸ todo(...args): 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.)

Parameters​

NameType
...argsreadonly unknown[]

Returns​

void

Allow Empty Variadic

Defined in​

packages/isaacscript-common/src/functions/utils.ts:255