Utils

Functions

assertDefined()

assertDefined<T>(value, …__namedParameters): asserts value is Exclude<T, undefined>

Defined in: packages/isaacscript-common/src/functions/utils.ts:12

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

T

T

Parameters

value

T

__namedParameters

…[undefined] extends [T] ? [string] : ["The assertion is useless because the provided value does not contain undefined."]

Returns

asserts value is Exclude<T, undefined>

---

assertNotNull()

assertNotNull<T>(value, …__namedParameters): asserts value is Exclude<T, null>

Defined in: packages/isaacscript-common/src/functions/utils.ts:31

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

T

T

Parameters

value

T

__namedParameters

…[null] extends [T] ? [string] : ["The assertion is useless because the provided value does not contain null."]

Returns

asserts value is Exclude<T, null>

---

eRange()

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

Defined in: packages/isaacscript-common/src/functions/utils.ts:66

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

start

int

The integer to start at.

end?

int

Optional. The integer to end at. If not specified, then the start will be 0 and the first argument will be the end.

increment?

number = 1

Optional. The increment to use. Default is 1.

Returns

readonly int[]

---

getTraversalDescription()

getTraversalDescription(key, traversalDescription): string

Defined in: packages/isaacscript-common/src/functions/utils.ts:85

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

Parameters

key

unknown

traversalDescription

string

Returns

string

---

inRange()

inRange(num, start, end): boolean

Defined in: packages/isaacscript-common/src/functions/utils.ts:108

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

num

int

The number to check.

start

int

The start of the range to check.

end

int

The end of the range to check.

Returns

boolean

---

iRange()

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

Defined in: packages/isaacscript-common/src/functions/utils.ts:133

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

start

int

The integer to start at.

end?

int

Optional. The integer to end at. If not specified, then the start will be 0 and the first argument will be the end.

increment?

number = 1

Optional. The increment to use. Default is 1.

Returns

readonly int[]

---

isMultiplayer()

isMultiplayer(): boolean

Defined in: packages/isaacscript-common/src/functions/utils.ts:152

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

---

isRepentance()

isRepentance(): boolean

Defined in: packages/isaacscript-common/src/functions/utils.ts:168

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

Returns

boolean

---

isRepentancePlus()

isRepentancePlus(): boolean

Defined in: packages/isaacscript-common/src/functions/utils.ts:195

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

Returns

boolean

---

isRepentogon()

isRepentogon(): boolean

Defined in: packages/isaacscript-common/src/functions/utils.ts:213

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

---

repeat()

repeat(num, func): void

Defined in: packages/isaacscript-common/src/functions/utils.ts:251

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

num

int

func

(i) => void

Returns

void

---

todo()

todo(…args): void

Defined in: packages/isaacscript-common/src/functions/utils.ts:273

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

args

…readonly unknown[]

Returns

void

Allow Empty Variadic