IsaacScript

https://isaacscript.github.io
Admin
Documentation for IsaacScript, a TypeScript-based framework for modding The Binding of Isaac.
Tokens:492,509
Snippets:6,386
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Game Mod Directory Path

Source: https://isaacscript.github.io/main/directory-structure

Shows the destination path where project files are copied within the game's installation.

```text
C:\Program Files (x86)\Steam\steamapps\common\The Binding of Isaac Rebirth\mods\revelations\image.png  


```

--------------------------------

### Example of a file path in Windows

Source: https://isaacscript.github.io/main/what-is-isaacscript-doing

Illustrates the expected path for a compiled Lua file after isaacscript recompiles TypeScript. This is an example path and may vary based on your project setup.

```plaintext
C:\Repositories\revelations\mod\main.lua
```

--------------------------------

### Example of a new asset file path

Source: https://isaacscript.github.io/main/what-is-isaacscript-doing

Shows an example of a new asset file (e.g., a PNG image) being placed within the nested mod directory structure. isaacscript will copy this file to the corresponding location in the game's mods directory.

```plaintext
C:\Repositories\revelations\mod\resources\gfx\items\collectibles\collectibles_new_item.png
```

--------------------------------

### Mod Directory Structure Example

Source: https://isaacscript.github.io/main/change-log

This example shows how to structure your mod's files to avoid naming conflicts when `luaBundle` is disabled. It involves namespacing your mod's code within a subdirectory.

```text
forgotten-fables/
└── src/ (TypeScript source code)
    ├── main.ts (with 1 line that just imports and runs "forgotten-fables/main")
    └── forgotten-fables/
        ├── main.ts (exporting a function to run)
        └── the rest of the code

```

--------------------------------

### Start Room Alias

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

An alias for the `startingRoom` command.

```bash
startRoom
```

--------------------------------

### Install typescript-to-lua with npm

Source: https://isaacscript.github.io/main/change-log

Use this command to install the required typescript-to-lua dependency if you are using npm.

```bash
npm install --save typescript-to-lua
```

--------------------------------

### Install Lua library with isaacscript-lua

Source: https://isaacscript.github.io/main/isaacscript-in-lua

Use the isaacscript-lua tool to install the Lua library into your mod directory. This is an optional automatic installation method.

```bash
isaacscript-lua install
```

--------------------------------

### POST_GAME_STARTED

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Callback triggered when the game starts. Cannot be filtered. Deprecated.

```APIDOC
## POST_GAME_STARTED

### Description
Callback triggered when the game starts. Cannot be filtered. Deprecated. Consider using `ModCallbackCustom.POST_GAME_STARTED_REORDERED` instead.

### Method
POST

### Endpoint
/ModCallback/POST_GAME_STARTED

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **isContinued** (boolean) - Required - Indicates if the game is a continuation of a saved run.

### Request Example
```json
{
  "isContinued": false
}
```

### Response
#### Success Response (200)
This callback does not return a value.

#### Response Example
```json
null
```
```

--------------------------------

### Start IsaacScript Monitor

Source: https://isaacscript.github.io/main/getting-started

Execute this command to start the IsaacScript monitor. It runs continuously, watching for changes in your project and propagating them to the Isaac mod directory. Press Ctrl + C to stop.

```bash
npx isaacscript
```

--------------------------------

### Registering a POST_GAME_STARTED Callback with @Callback

Source: https://isaacscript.github.io/isaacscript-common/functions/decorators

This example demonstrates how to use the @Callback decorator to register a function that will be called after the game has started. Ensure the ModFeature class is correctly extended and the callback type is specified.

```typescript
export class MyFeature extends ModFeature {
  @Callback(ModCallback.POST_GAME_STARTED)
  postGameStarted(isContinued: boolean): void {
    Isaac.DebugString(`Callback fired: POST_GAME_STARTED`);
  }
}
```

--------------------------------

### Install typescript-to-lua with pnpm

Source: https://isaacscript.github.io/main/change-log

Use this command to install the required typescript-to-lua dependency if you are using pnpm.

```bash
pnpm add typescript-to-lua
```

--------------------------------

### Get Open Trinket Slot Example

Source: https://isaacscript.github.io/isaacscript-common/functions/playerTrinkets

Demonstrates how to find an available trinket slot for a player and add a trinket if a slot is found. Ensure a player entity and the getOpenTrinketSlotNum function are available.

```typescript
const player = Isaac.GetPlayer();
const trinketSlot = getOpenTrinketSlotNum(player);
if (trinketSlot !== undefined) {
  // They have one or more open trinket slots
  player.AddTrinket(TrinketType.SWALLOWED_PENNY);
}
```

--------------------------------

### Example of a Steam mods directory path

Source: https://isaacscript.github.io/main/what-is-isaacscript-doing

Shows the typical location where isaacscript copies your mod's compiled files within the Steam installation directory. This path is specific to a Windows installation.

```plaintext
C:\Program Files (x86)\Steam\steamapps\common\The Binding of Isaac Rebirth\mods\revelations\main.lua
```

--------------------------------

### Install isaacscript-lua tool

Source: https://isaacscript.github.io/main/isaacscript-in-lua

Install the isaacscript-lua Python tool using pip. Ensure you have Python 3.10 or later.

```bash
pip install isaacscript-lua --upgrade
```

--------------------------------

### Install typescript-to-lua with Yarn

Source: https://isaacscript.github.io/main/change-log

Use this command to install the required typescript-to-lua dependency if you are using Yarn.

```bash
yarn add typescript-to-lua
```

--------------------------------

### Example of Map Reversal

Source: https://isaacscript.github.io/isaacscript-common/functions/map

Illustrates how a Map is reversed, swapping keys and values. This example shows the transformation from an initial map to its reversed counterpart.

```typescript
new Map<string, number>([
  ["foo", 1],
  ["bar", 2],
]);
```

```typescript
new Map<number, string>([
  [1, "foo"],
  [2, "bar"],
]);
```

--------------------------------

### Install isaacscript-tsconfig with pnpm

Source: https://isaacscript.github.io/main/change-log

When using pnpm, install 'isaacscript-tsconfig' as a dependency to ensure IsaacScript mod compatibility.

```bash
pnpm add isaacscript-tsconfig
```

--------------------------------

### Example of a copied asset file path in Steam mods

Source: https://isaacscript.github.io/main/what-is-isaacscript-doing

Illustrates the destination path for a copied asset file within the Steam installation's mods directory. This ensures the game can access the new asset.

```plaintext
C:\Program Files (x86)\Steam\steamapps\common\The Binding of Isaac Rebirth\mods\revelations\resources\gfx\items\collectibles\collectibles_new_item.png
```

--------------------------------

### Warp to Starting Room

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

Warps the player to the starting room of the current floor.

```bash
startingRoom
```

--------------------------------

### Install isaacscript-tsconfig with npm

Source: https://isaacscript.github.io/main/change-log

When using npm, install 'isaacscript-tsconfig' as a dependency to meet IsaacScript mod requirements.

```bash
npm install --save isaacscript-tsconfig
```

--------------------------------

### Example of using runNextGameFrame for delayed explosions

Source: https://isaacscript.github.io/isaacscript-common/features/RunInNFrames

This example demonstrates how to use `runNextGameFrame` to create a recursive explosion effect over multiple game frames. It highlights the need to handle frame counting and recursion within the deferred function.

```typescript
const NUM_EXPLODER_EXPLOSIONS = 5;

function useItemExploder(player: EntityPlayer) {
  playSound("exploderBegin");
  explode(player, NUM_EXPLODER_EXPLOSIONS);
}

function explode(player: EntityPlayer, numFramesLeft: int) {
  Isaac.Explode(player, undefined, 1);
  numFramesLeft -= 1;
  if (numFramesLeft === 0) {
    runNextFrame(() => {
      explode(player, numFramesLeft);
    });
  }
}
```

--------------------------------

### reloadRoom

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

Starts a room transition to the same room the player is currently in.

```APIDOC
## reloadRoom

### Description
Starts a room transition to the same room that you are already in.

### Method
`void`

### Defined in
packages/isaacscript-common/src/classes/features/other/extraConsoleCommands/commands.ts:1210
```

--------------------------------

### Example File Copying Path

Source: https://isaacscript.github.io/main/directory-structure

Illustrates how files from the project's mod directory are copied to the game's mod directory.

```text
C:\Repositories\revelations\mod\image.png  


```

--------------------------------

### getGridIndexDelta

Source: https://isaacscript.github.io/isaacscript-common/functions/roomShape

Helper function to get the grid index delta that a door out of the given room shape would lead to. For example, if you went through the bottom door in a room of RoomShape.SHAPE_1x2, you would end up in a room with a grid index that is +26 units from the SafeGridIndex of where you started.

```APIDOC
## getGridIndexDelta

### Description
Helper function to get the grid index delta that a door out of the given room shape would lead to. For example, if you went through the bottom door in a room of `RoomShape.SHAPE_1x2`, you would end up in a room with a grid index that is +26 units from the `SafeGridIndex` of where you started.

### Parameters
#### Path Parameters
- **roomShape** (RoomShape) - Required - The shape of the room.
- **doorSlot** (DoorSlot) - Required - The door slot to consider.

### Returns
#### Success Response
- `int` | `undefined` - The grid index delta or undefined if not applicable.
```

--------------------------------

### Initialize New IsaacScript Project

Source: https://isaacscript.github.io/main/getting-started

Run this command to bootstrap your new mod project. It will prompt you for information and set up necessary files and dependencies.

```bash
npx isaacscript@latest init
```

--------------------------------

### Get Collectible Tags Example

Source: https://isaacscript.github.io/isaacscript-common/functions/collectibles

Demonstrates how to get the tags of a collectible. Returns 0 for invalid types.

```typescript
const collectibleType = CollectibleType.SAD_ONION;
const itemConfigTags = getCollectibleTags(collectibleType); // itemConfigTags is "18350080"
```

```typescript
getCollectibleTags(collectibleOrCollectibleType: CollectibleType | EntityPickup): BitFlags<ItemConfigTag>
```

--------------------------------

### Initialize TypeScript Project

Source: https://isaacscript.github.io/main/isaacscript-in-typescript

Use this command to bootstrap a new, standard TypeScript project. Ensure you have the latest version of isaacscript installed.

```bash
npx isaacscript@latest init-ts foo  

```

--------------------------------

### fool

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

Alias for the "startingRoom" command.

```APIDOC
## fool

### Description
Alias for the "startingRoom" command.

### Method
`fool()`

### Returns
`void`
```

--------------------------------

### getRoomItemPoolType

Source: https://isaacscript.github.io/isaacscript-common/functions/rooms

Helper function to get the item pool type for the current room. For example, this returns `ItemPoolType.ItemPoolType.POOL_ANGEL` if you are in an Angel Room.

```APIDOC
## getRoomItemPoolType

### Description
Helper function to get the item pool type for the current room. For example, this returns `ItemPoolType.ItemPoolType.POOL_ANGEL` if you are in an Angel Room.

### Returns
`ItemPoolType` - The item pool type of the current room.
```

--------------------------------

### Spawn Trinket Examples

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

Shows how to spawn a trinket using its name or ID. Partial names are supported, and a golden variant can be spawned.

```bash
spawnTrinket wiggle worm
spawnTrinket wiggle
spawnTrinket wig
spawnTrinket 10
```

--------------------------------

### Array Iteration in TypeScript (keys)

Source: https://isaacscript.github.io/main/javascript-tutorial

Iterating over an array in TypeScript using keys() to get only the index. Note that keys start at 0.

```typescript
// If you just need the array index, use the `keys` method.
// The keys start at 0, unlike Lua. (In Lua, array keys start at 1.)
for (const i of gapers.keys()) {
  print("On gaper index:", i);
}

```

--------------------------------

### Deploying a Custom JSON Room

Source: https://isaacscript.github.io/isaacscript-common/features/DeployJSONRoom

Example of how to deploy the first room from a JSON file in the POST_NEW_ROOM callback. Ensure the JSON room data is imported correctly.

```typescript
import customRooms from "./customRooms.json";

export function postNewRoom(): void {
  const firstJSONRoom = customRooms.rooms.room[0];
  deployJSONRoom(firstJSONRoom);
}
```

--------------------------------

### POST_PLAYER_INIT_FIRST

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires on the first POST_PEFFECT_UPDATE_REORDERED frame for each non-child player, including Genesis room entries. Useful for initial player setup.

```APIDOC
## POST_PLAYER_INIT_FIRST

### Description
Fires on the first `POST_PEFFECT_UPDATE_REORDERED` frame for each player, excluding "child" players. This callback fires when a player enters a Genesis room. It is recommended for player initialization logic, such as assigning starting items.

### Method
`ModUpgraded.AddCallbackCustom` with `POST_PLAYER_INIT_FIRST` enum value.

### Parameters
#### Callback Parameters
- **player** (EntityPlayer) - The player entity being initialized.
- **optional playerVariant filter** (PlayerVariant) - Optional. Fires only if the player matches this variant.
- **optional playerType filter** (PlayerType) - Optional. Fires only if the player matches this type.

### Function Signature
```typescript
function postPlayerInitFirst(player: EntityPlayer): void;
```
```

--------------------------------

### getCharacterStartingTrinketType

Source: https://isaacscript.github.io/isaacscript-common/functions/characters

Helper function to get the trinket that is granted to a particular character at the beginning of a run. Returns undefined if the character does not start with a trinket.

```APIDOC
## getCharacterStartingTrinketType

### Description
Helper function to get the trinket that is granted to a particular character at the beginning of a run. Returns undefined if the character does not start with a trinket. Note that this will return undefined for Eden and Tainted Eden.

### Method
N/A (TypeScript Function)

### Signature
`getCharacterStartingTrinketType(character: PlayerType): TrinketType | undefined`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- `TrinketType | undefined`: The `TrinketType` granted to the character, or `undefined` if none.
```

--------------------------------

### getRoomTypeName

Source: https://isaacscript.github.io/isaacscript-common/functions/rooms

Helper function to get the proper name of a room type. For example, `RoomType.TREASURE` will return "Treasure Room".

```APIDOC
## getRoomTypeName

### Description
Helper function to get the proper name of a room type. For example, `RoomType.TREASURE` will return "Treasure Room".

### Parameters
#### Path Parameters
- **roomType** (RoomType) - Required - The room type to get the name for.

### Returns
`string` - The proper name of the room type.
```

--------------------------------

### Registering POST_USE_CARD Callback

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Example of registering a callback for when a card is used. It can be filtered by CardType.

```typescript
function postUseCard(
  cardType: CardType,
  player: EntityPlayer,
  useFlags: BitFlags<UseFlag>,
): void {}
```

--------------------------------

### Registering POST_PLAYER_INIT Callback

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Example of registering a callback for player initialization. It can be filtered by PlayerVariant. Use with caution due to potential issues when continuing saved runs.

```typescript
function postPlayerInit(player: EntityPlayer): void {}
```

--------------------------------

### getDirectionName

Source: https://isaacscript.github.io/isaacscript-common/functions/direction

Helper function to get the lowercase name of a direction. For example, `Direction.LEFT` (0) would return "left".

```APIDOC
## getDirectionName

### Description
Helper function to get the lowercase name of a direction. For example, `Direction.LEFT` (0) would return "left".

### Parameters
#### Path Parameters
- **direction** (Direction) - Required - The direction to get the name of.

### Returns
`string` | `undefined`

### Defined in
packages/isaacscript-common/src/functions/direction.ts:83
```

--------------------------------

### isEden

Source: https://isaacscript.github.io/isaacscript-common/functions/players

Helper function for detecting when a player is Eden or Tainted Eden. Useful for situations where you want to know if the starting stats were randomized, for example.

```APIDOC
## isEden

### Description
Helper function for detecting when a player is Eden or Tainted Eden. Useful for situations where you want to know if the starting stats were randomized, for example.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
N/A (Function Call)

### Endpoint
N/A (Function Call)

### Parameters
- **player** (`EntityPlayer`) - Required - The player entity to check.

### Returns
`boolean` - True if the player is Eden or Tainted Eden, false otherwise.

### Defined in
packages/isaacscript-common/src/functions/players.ts:412
```

--------------------------------

### getRoomShapeCharges

Source: https://isaacscript.github.io/isaacscript-common/functions/roomShape

Helper function to get the number of charges that a given room shape will grant to a player upon clearing it. For example, RoomShape.SHAPE_2x2 will return 2.

```APIDOC
## getRoomShapeCharges

### Description
Helper function to get the number of charges that a given room shape will grant to a player upon clearing it. For example, `RoomShape.SHAPE_2x2` will return 2.

### Parameters
#### Path Parameters
- **roomShape** (RoomShape) - Required - The shape of the room.

### Returns
#### Success Response
- `int` - The number of charges granted.
```

--------------------------------

### Validate Enum Contiguous Example

Source: https://isaacscript.github.io/isaacscript-common/functions/enums

Validates if all values in a number enum are contiguous, starting from 0. This helps automate the checking of large enums for typos.

```typescript
validateEnumContiguous("MyEnum", MyEnum);
```

--------------------------------

### Create and Change Project Directory

Source: https://isaacscript.github.io/main/getting-started

Use these commands to create a new directory for your mod and navigate into it. Ensure the directory is not a subdirectory of the Isaac `mods` folder.

```bash
mkdir C:\\Repositories\\revelations
cd C:\\Repositories\\revelations
```

--------------------------------

### POST_ROCK_UPDATE Callback Example

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires on every frame a rock exists. Can be filtered by GridEntityType and variant.

```typescript
function postRockUpdate(rock: GridEntityRock): void {}
```

--------------------------------

### getElapsedTimeSince

Source: https://isaacscript.github.io/isaacscript-common/functions/debugFunctions

Helper function to get the amount of elapsed time for benchmarking / profiling purposes. It takes a starting time and an optional boolean to determine if socket time should be used.

```APIDOC
## getElapsedTimeSince

### Description
Helper function to get the amount of elapsed time for benchmarking / profiling purposes.
For more information, see the documentation for the `getTime` helper function.

### Method
N/A (Function Signature)

### Signature
`getElapsedTimeSince(time: int, useSocketIfAvailable?: boolean): int`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **time** (int) - The milliseconds (int) or fractional seconds (float).
- **useSocketIfAvailable** (boolean) - Optional. Whether to use the `socket.gettime` method, if available. Default is true. If set to false, the `Isaac.GetTime()` method will always be used.

### Returns
`int`

### Defined in
`packages/isaacscript-common/src/functions/debugFunctions.ts:13
```

--------------------------------

### Spawn Collectible Examples

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

Demonstrates various ways to spawn a collectible by its name or ID. Partial names are also accepted.

```bash
spawnCollectible spoon bender
spawnCollectible spoon
spawnCollectible spo
spawnCollectible 3
```

--------------------------------

### Get Eden Passive Collectible Types

Source: https://isaacscript.github.io/isaacscript-common/features/ModdedElementSets

Retrieves a set of all valid passive items that can be granted to Eden as a passive starting item. This is determined by the 'noeden' tag in 'items_metadata.xml'. Requires ISCFeature.MODDED_ELEMENT_SETS.

```typescript
const edenPassiveItems = getEdenPassiveCollectibleTypes();
```

--------------------------------

### PRE_ROOM_LAYOUT_CHOOSE

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/StageAPICallback

Callback called on initial room load and when continuing a game, before INIT. Allows returning a table to use as the current room layout, or breaks on the first return.

```APIDOC
## PRE_ROOM_LAYOUT_CHOOSE

### Description
Callback called both on initial room load and when continuing a game, before INIT. Takes one return value. If a table, uses it as the current room layout. Otherwise, chooses from `roomsList` with seeded RNG. Breaks on first return.

### Method
POST

### Endpoint
/stage/callback/PRE_ROOM_LAYOUT_CHOOSE

### Parameters
#### Query Parameters
- **layoutData** (object | table) - Optional - The room layout data to use. If not provided, layout is chosen from `roomsList`.
```

--------------------------------

### Get Eden Active Collectible Types

Source: https://isaacscript.github.io/isaacscript-common/features/ModdedElementSets

Retrieves a set of all valid passive items that can be granted to Eden as an active starting item. This is determined by the 'noeden' tag in 'items_metadata.xml'. Requires ISCFeature.MODDED_ELEMENT_SETS.

```typescript
const edenActiveItems = getEdenActiveCollectibleTypes();
```

--------------------------------

### POST_GAME_STARTED Callback

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Fires when the game starts. This callback cannot be filtered. Consider using POST_GAME_STARTED_REORDERED for correct initialization order.

```typescript
function postGameStarted(isContinued: boolean): void {}

```

--------------------------------

### POST_PLAYER_INIT_FIRST Callback

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires on the first POST_PEFFECT_UPDATE_REORDERED frame for non-child players, including when entering a Genesis room. Use for initial player setup. Can be filtered by PlayerVariant or PlayerType.

```typescript
function postPlayerInitFirst(player: EntityPlayer): void {}
```

--------------------------------

### Array Initialization and Element Addition

Source: https://isaacscript.github.io/main/javascript-tutorial

Demonstrates array initialization and adding elements in Lua (using tables and table.insert) versus TypeScript (using bracket syntax and push method).

```lua
local myArray = {"foo", "bar", "baz"}  

```

```lua
table.insert(myArray, "someNewElement")  
myArray[#myArray + 1] = "anotherNewElement"  

```

```typescript
const myArray = ["foo", "bar", "baz"];  

```

```typescript
myArray.push("someNewElement");  

```

--------------------------------

### getCollectibleQuality

Source: https://isaacscript.github.io/isaacscript-common/functions/collectibles

Helper function to get a collectible's quality, which ranges from 0 to 4 (inclusive). For example, Mom's Knife has a quality of 4. Returns 0 if the provided collectible type was not valid.

```APIDOC
## getCollectibleQuality

### Description
Helper function to get a collectible's quality, which ranges from 0 to 4 (inclusive). For example, Mom's Knife has a quality of 4. Returns 0 if the provided collectible type was not valid.

### Signature
▸ **getCollectibleQuality**(`collectibleOrCollectibleType`): `Quality`

### Parameters
#### Path Parameters
- **collectibleOrCollectibleType** (CollectibleType | EntityPickup) - Description: The collectible type or entity pickup to get the quality for.

### Returns
`Quality` - The quality of the collectible.
```

--------------------------------

### getCollectiblePedestalType

Source: https://isaacscript.github.io/isaacscript-common/functions/collectibles

Helper function to get the "pedestal type" of a collectible. For example, it might be sitting on top of a broken Blood Donation Machine, or it might be sitting on top of an opened Spiked Chest.

```APIDOC
## getCollectiblePedestalType

### Description
Helper function to get the "pedestal type" of a collectible. For example, it might be sitting on top of a broken Blood Donation Machine, or it might be sitting on top of an opened Spiked Chest.

### Signature
▸ **getCollectiblePedestalType**(`collectible`): `CollectiblePedestalType`

### Parameters
#### Path Parameters
- **collectible** (EntityPickup) - Description: The collectible to get the pedestal type for.

### Returns
`CollectiblePedestalType` - The pedestal type of the collectible.
```

--------------------------------

### POST_LASER_INIT

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Callback for when a laser is initialized. Populates fields like Position, SpawnerEntity, etc. An optional third argument can filter by LaserVariant.

```APIDOC
## POST_LASER_INIT

### Description
Callback for when a laser is initialized. Populates fields like Position, SpawnerEntity, etc. An optional third argument can filter by LaserVariant.

### Callback ID
`47`

### Callback Signature
```typescript
function postLaserInit(laser: EntityLaser): void;
```

### Defined in
ModCallback.ts:678
```

--------------------------------

### Set up Post Update Function

Source: https://isaacscript.github.io/main/example-mod

Initial setup for the postUpdate function to check for green candle effects. This function serves as a placeholder for further logic.

```typescript
function postUpdate() {
  checkApplyGreenCandleEffect();
}

function checkApplyGreenCandleEffect() {
  // TODO - Fill this in.
}
```

--------------------------------

### getChallengeTrinketType

Source: https://isaacscript.github.io/isaacscript-common/functions/challenges

Retrieves the extra starting trinket for a given challenge. This function is reliable only for vanilla challenges.

```APIDOC
## getChallengeTrinketType

### Description
Get the extra starting trinket for a challenge. This will only work for vanilla challenges. If a challenge does not grant a starting trinket, `undefined` will be returned. For modded challenges, `undefined` will be returned.

### Parameters
#### Path Parameters
- **challenge** (Challenge) - Required - The challenge to get the trinket for.

### Returns
`TrinketType` | `undefined`
```

--------------------------------

### Lua Module Loading with require()

Source: https://isaacscript.github.io/main/javascript-tutorial

Demonstrates how to load modules in Lua using the 'require()' function, which necessitates specific directory structures to avoid conflicts.

```lua
-- In Lua, we must namespace the mod's Lua files in a directory of the same name to avoid require  
-- conflicts.  
local postGameStarted = require("revelations.callbacks.postGameStarted")  
  
local mod = RegisterMod("Revelations", 1)  
postGameStarted:init(mod)  
```

```lua
local postGameStarted = {}  
  
function postGameStarted:init(mod)  
  mod:AddCallback(ModCallbacks.POST_GAME_STARTED, postGameStarted.main);  
end  
  
function postGameStarted:main()  
  local player = Isaac.GetPlayer()  
  player:AddCollectible(1, 0, false) -- Sad Onion  
end  
  
return postGameStarted  
```

--------------------------------

### getTSTLClassName

Source: https://isaacscript.github.io/isaacscript-common/functions/tstlClass

Helper function to get the name of a TypeScriptToLua class from the instantiated class object. TSTL classes are Lua tables created with the `__TS__Class` Lua function from the TSTL lualib. Their name is contained within "constructor.name" metatable key. For example, a `Map` class is has a name of "Map". Returns undefined if passed a non-table or if the provided table does not have a metatable.

```APIDOC
## getTSTLClassName

### Description
Helper function to get the name of a TypeScriptToLua class from the instantiated class object. TSTL classes are Lua tables created with the `__TS__Class` Lua function from the TSTL lualib. Their name is contained within "constructor.name" metatable key. For example, a `Map` class is has a name of "Map". Returns undefined if passed a non-table or if the provided table does not have a metatable.

### Parameters
#### Path Parameters
- **object** (unknown) - Required - The object to get the name from.

### Returns
- **string | undefined** - The name of the TSTL class or undefined.
```

--------------------------------

### POST_ROOM_INIT

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/StageAPICallback

Callback called when a room initializes, either upon initial entry or loading from save data. Takes no return values.

```APIDOC
## POST_ROOM_INIT

### Description
Callback called when a room initializes. Can occur at two times: when a room is initially entered or when a room is loaded from save data. Takes no return values.

### Method
POST

### Endpoint
/stage/callback/POST_ROOM_INIT
```

--------------------------------

### POST_NEW_ROOM_EARLY

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires on the first `POST_NEW_ROOM` or `PRE_ENTITY_SPAWN` callback where being in a new room is detected. This is useful because the vanilla `POST_NEW_ROOM` callback fires only after entities in the room have been initialized and updated once. Allows optional filtering based on `RoomType`.

```APIDOC
## POST_NEW_ROOM_EARLY

### Description
Fires early in the room initialization process, before entities are fully initialized and updated, unlike the vanilla `POST_NEW_ROOM` callback. This allows for room-related initialization code to run before entity-related code.

### Method
`ModUpgraded.AddCallbackCustom`

### Parameters
#### Optional Filter Arguments
- `roomType` (RoomType) - Optional - Filters the callback to only fire for a specific `RoomType`.

### Callback Signature
`function postNewRoomEarly(roomType: RoomType): void`
```

--------------------------------

### PlayerIndex Map Example

Source: https://isaacscript.github.io/isaacscript-common/other/types/PlayerIndex

Demonstrates how to create a Map using PlayerIndex as the key type for storing player names.

```typescript
const playersNameMap = new Map<PlayerIndex, string>();
```

--------------------------------

### getGotoCommand

Source: https://isaacscript.github.io/isaacscript-common/functions/stage

Generates the 'goto' console command for a specified room type and variant.

```APIDOC
## getGotoCommand

### Description
Helper function to get the corresponding "goto" console command that would correspond to the provided room type and room variant.

### Parameters
#### Path Parameters
- **roomType** (RoomType) - Required - The `RoomType` of the destination room.
- **roomVariant** (int) - Required - The variant of the destination room.
- **useSpecialRoomsForRoomTypeDefault** (boolean) - Optional - Defaults to `false`. Whether to use `s.default` as the prefix for the `goto` command (instead of `d`) if the room type is `RoomType.DEFAULT` (1).

### Returns
`string`

### Defined in
packages/isaacscript-common/src/functions/stage.ts:106
```

--------------------------------

### Default IsaacScript Project Structure

Source: https://isaacscript.github.io/main/directory-structure

The basic folder structure created by `isaacscript init` includes source code and mod output directories.

```text
project/  
├── src/ (TypeScript source code)  
|   └── main.ts  
└── mod/ (what will exist in the "real" mod directory)  
    ├── main.lua  
    └── metadata.xml  


```

--------------------------------

### POST_PLAYER_INIT

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Callback for when a player is initialized. Can be filtered by PlayerVariant.

```APIDOC
## POST_PLAYER_INIT

### Description
Callback for when a player is initialized. Can be filtered by PlayerVariant.

### Method
POST

### Endpoint
/ModCallback/POST_PLAYER_INIT

### Parameters
#### Query Parameters
- **playerVariant** (PlayerVariant) - Optional - The variant of player to filter the callback by.
```

--------------------------------

### getDefaultPlayerStat

Source: https://isaacscript.github.io/isaacscript-common/functions/stats

Returns the starting stat that Isaac (the default character) starts with. The default fire delay is represented in the tear stat, not the MaxFireDelay value.

```APIDOC
## getDefaultPlayerStat

### Description
Returns the starting stat that Isaac (the default character) starts with. For example, if you pass this function `CacheFlag.DAMAGE`, it will return 3.5. Note that the default fire delay is represented in the tear stat, not the `MaxFireDelay` value.

### Parameters
#### Parameters
- **cacheFlag** (`CacheFlagValue`) - Description: The type of stat to retrieve the default value for.

### Returns
`number` | `undefined`

### Defined in
packages/isaacscript-common/src/functions/stats.ts:92
```

--------------------------------

### Get all grid entities

Source: https://isaacscript.github.io/isaacscript-common/functions/gridEntities

Retrieves all grid entities in the current room. Can be used with no arguments to get all entities, or with specific types to filter the results.

```typescript
for (const gridEntity of getGridEntities()) {
  print(gridEntity.GetType())
}
```

--------------------------------

### POST_GRID_ENTITY_INIT

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires when a new grid entity is initialized, either upon room entry or when an entity appears mid-room. For custom grid entities, POST_GRID_ENTITY_CUSTOM_INIT should be used. Callbacks can be filtered by GridEntityType and variant.

```APIDOC
## POST_GRID_ENTITY_INIT

### Description
This callback is invoked whenever a new grid entity is initialized. This occurs either when a room is entered (in the `POST_NEW_ROOM_REORDERED` callback) or when an entity appears dynamically within a room (e.g., in the `POST_UPDATE` callback). For custom grid entities, the `POST_GRID_ENTITY_CUSTOM_INIT` callback is recommended. Filtering by `GridEntityType` and variant is supported.

### Method
POST

### Endpoint
`/callback/grid_entity/init`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **gridEntity** (GridEntity) - Required - The grid entity being initialized.

### Request Example
```json
{
  "gridEntity": { ... }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates successful processing of the callback.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Spawn Custom Trapdoor on Game Start

Source: https://isaacscript.github.io/main/custom-stages

Add a custom trapdoor to a specific level stage when the game starts. This requires the 'custom trapdoors' feature to be enabled in your mod.

```typescript
import { LevelStage, ModCallback } from "isaac-typescript-definitions";  
import { mod } from "./mod";  
  
const TOP_LEFT_CORNER_GRID_INDEX = 32;  
  
mod.AddCallback(ModCallback.POST_GAME_STARTED, postGameStarted);  
  
function postGameStarted(isContinued: boolean) {  
  if (isContinued) {  
    return;  
  }  
  
  mod.spawnCustomTrapdoor(  
    TOP_LEFT_CORNER_GRID_INDEX,  
    "Foo",  
    LevelStage.BASEMENT_1,  
  );  
}  

```

--------------------------------

### POST_SLOT_INIT Callback Example

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires when a new slot entity is initialized in a room. Can be filtered by slot variant and sub-type.

```typescript
function postSlotInit(slot: Entity): void {}
```

--------------------------------

### Get colliding entities with grid entity

Source: https://isaacscript.github.io/isaacscript-common/functions/gridEntities

Gets entities whose hitboxes overlap with a grid entity's square. Note: This function is not reliable in the POST_NEW_ROOM callback.

```typescript
const collidingEntities = getCollidingEntitiesWithGridEntity(gridEntity);
```

--------------------------------

### POST_GAME_STARTED_REORDERED

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires in the correct order with respect to POST_NEW_LEVEL and POST_NEW_ROOM callbacks. It requires a third argument to specify whether the callback should fire for continued runs, new runs, or both.

```APIDOC
## POST_GAME_STARTED_REORDERED

### Description
Similar to the vanilla callback of the same name, but fires in the correct order with respect to the `POST_NEW_LEVEL` and the `POST_NEW_ROOM` callbacks. The order is: `POST_GAME_STARTED_REORDERED` --> `POST_NEW_LEVEL_REORDERED` --> `POST_NEW_ROOM_REORDERED`.

### Method
POST

### Endpoint
`/POST_GAME_STARTED_REORDERED`

### Parameters
#### Query Parameters
- **isContinued** (boolean) - Required - Pass `true` if you want the callback to only fire if the run is continued. Pass `false` if you want the callback to only fire when the run is not continued. Pass `undefined` if you want the callback to fire in both situations.

### Request Example
```json
{
  "isContinued": true
}
```

### Response
#### Success Response (200)
- **void** - This callback does not return any value.

#### Response Example
```json
{
  "message": "Callback executed successfully"
}
```
```

--------------------------------

### POST_PICKUP_INIT_FILTER

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

The POST_PICKUP_INIT_FILTER callback is identical to the vanilla POST_PICKUP_INIT, but it allows for additional filtration arguments. You can specify an optional third argument for PickupVariant and an optional fourth argument for sub-type to control when the callback fires.

```APIDOC
## POST_PICKUP_INIT_FILTER

### Description
Allows specifying extra arguments for additional filtration on the POST_PICKUP_INIT callback. The callback fires only if it matches the provided PickupVariant and/or sub-type.

### Method
`ModUpgraded.AddCallbackCustom`

### Parameters
- **callbackId** (int) - Required - `POST_PICKUP_INIT_FILTER`
- **callback** (function) - Required - The function to be called.
- **pickupVariant** (PickupVariant) - Optional - Filters the callback to only fire for the specified pickup variant.
- **subType** (int) - Optional - Filters the callback to only fire for the specified sub-type.

### Callback Signature
```typescript
function postPickupInitFilter(pickup: EntityPickup): void
```
```

--------------------------------

### Get Newest Player

Source: https://isaacscript.github.io/isaacscript-common/functions/players

Get the first player with the lowest frame count, useful for identifying freshly spawned players. Avoid using if multiple players spawn on the same frame.

```typescript
getNewestPlayer(): EntityPlayer
```

--------------------------------

### getTraceback

Source: https://isaacscript.github.io/isaacscript-common/functions/debugFunctions

Helper function to get a stack trace. This will only work if the `--luadebug` launch option is enabled. If it isn't, then a error string will be returned.

```APIDOC
## getTraceback

### Description
Helper function to get a stack trace. This will only work if the `--luadebug` launch option is enabled. If it isn't, then a error string will be returned.

### Method
N/A (Function Signature)

### Signature
`getTraceback(this: void): string`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **this** (void)

### Returns
`string`

### Defined in
`packages/isaacscript-common/src/functions/debugFunctions.ts:66
```

--------------------------------

### doesCharacterStartWithActiveItem

Source: https://isaacscript.github.io/isaacscript-common/functions/characters

Helper function to determine if the specified character starts with an active item. For the purposes of this function, the save file is considered to be fully unlocked (e.g. Isaac is considered to starts with the D6, but this is not the case on a brand new save file).

```APIDOC
## doesCharacterStartWithActiveItem

### Description
Helper function to determine if the specified character starts with an active item, assuming a fully unlocked save file.

### Parameters
#### Path Parameters
* **character** (PlayerType) - Required - The character to check.

### Returns
`boolean` - True if the character starts with an active item, false otherwise.
```

--------------------------------

### POST_PICKUP_INIT_FIRST

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

The POST_PICKUP_INIT_FIRST callback triggers the first time a player encounters a specific pickup during a run. This is useful because pickups can despawn and respawn when rooms are re-entered. Similar to POST_PICKUP_INIT_FILTER, it supports optional arguments for PickupVariant and sub-type filtration.

```APIDOC
## POST_PICKUP_INIT_FIRST

### Description
Fires from the POST_PICKUP_INIT callback on the first time that a player has seen the respective pickup on the run. Supports optional arguments for PickupVariant and sub-type filtration.

### Method
`ModUpgraded.AddCallbackCustom`

### Parameters
- **callbackId** (int) - Required - `POST_PICKUP_INIT_FIRST`
- **callback** (function) - Required - The function to be called.
- **pickupVariant** (PickupVariant) - Optional - Filters the callback to only fire for the specified pickup variant.
- **subType** (int) - Optional - Filters the callback to only fire for the specified sub-type.

### Callback Signature
```typescript
function postPickupInitFirst(pickup: EntityPickup): void
```
```

--------------------------------

### Get Player Index (IsaacScript)

Source: https://isaacscript.github.io/isaacscript-common/functions/playerIndex

Provides a robust method to get a unique player index, suitable for tracking variables across game states and handling special cases like Jacob & Esau. Optionally differentiates The Forgotten and The Soul.

```typescript
getPlayerIndex(player: EntityPlayer, differentiateForgottenAndSoul?: boolean): PlayerIndex
```

--------------------------------

### Setting Object Elements in TypeScript

Source: https://isaacscript.github.io/main/javascript-tutorial

Demonstrates setting object elements in TypeScript, similar to Lua.

```typescript
myObject.foo = 999;
myObject["foo"] = 999;

```

--------------------------------

### Registering a Mod and Upgrading for Features

Source: https://isaacscript.github.io/main/mod-feature

This snippet shows the standard practice for initializing a mod and upgrading it to use features with the standard library. It imports necessary functions and defines the features required for the mod.

```typescript
// mod.ts  
  
import { ISCFeature, upgradeMod } from "isaacscript-common";  
  
const ISC_FEATURES_FOR_THIS_MOD = [ISCFeature.SAVE_DATA_MANAGER] as const;  
  
const modVanilla = RegisterMod("Green Candle", 1);  
export const mod = upgradeMod(modVanilla, ISC_FEATURES_FOR_THIS_MOD);  


```

--------------------------------

### getRoomShapeWidth

Source: https://isaacscript.github.io/isaacscript-common/functions/roomShape

Gets the width of a given room shape.

```APIDOC
## getRoomShapeWidth

### Description
Gets the width of a given room shape.

### Parameters
#### Path Parameters
- **roomShape** (RoomShape) - Required - The shape of the room.

### Returns
#### Success Response
- `int` - The width of the room shape.
```

--------------------------------

### Example of a nested mod directory structure

Source: https://isaacscript.github.io/main/what-is-isaacscript-doing

Demonstrates how isaacscript handles copying files within nested directories from your project's mod folder to the game's mods directory. This is useful for organizing assets like graphics.

```plaintext
C:\Repositories\revelations\mod\resources\gfx\items\collectibles\
```

--------------------------------

### Example of a print statement in TypeScript

Source: https://isaacscript.github.io/main/what-is-isaacscript-doing

Add this to your main.ts file to test if isaacscript recompiles and refreshes your mod correctly. This will print 'hello world' to the in-game console.

```typescript
print("hello world");
```

--------------------------------

### POST_LASER_INIT Callback

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Fires after a laser is initialized. Populates fields like Position, SpawnerEntity, etc. Can be filtered by LaserVariant.

```typescript
function postLaserInit(laser: EntityLaser): void {}

```

--------------------------------

### GET_TRINKET Callback

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Fires to get a trinket. This callback cannot be filtered.

```typescript
function getTrinket(
  trinketType: TrinketType,
  rng: RNG,
): TrinketType | undefined {}
```

--------------------------------

### POST_LASER_INIT_LATE

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires on the first POST_LASER_UPDATE frame for each laser. This callback is useful because many attributes cannot be set or retrieved properly in the normal POST_LASER_INIT callback. It allows for optional filtering based on LaserVariant and sub-type.

```APIDOC
## POST_LASER_INIT_LATE

### Description
Fires on the first `POST_LASER_UPDATE` frame for each laser. This callback is useful because many attributes cannot be set or retrieved properly in the normal `POST_LASER_INIT` callback.

### Method
`ModUpgraded.AddCallbackCustom`

### Parameters
#### Optional Filter Arguments
- `laserVariant` (LaserVariant) - Optional - Filters the callback to only fire for a specific `LaserVariant`.
- `subType` (any) - Optional - Filters the callback to only fire for a specific sub-type.

### Callback Signature
`function postLaserInitLate(laser: EntityLaser): void`
```

--------------------------------

### GET_SHADER_PARAMS

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Callback triggered to get shader parameters. Cannot be filtered.

```APIDOC
## GET_SHADER_PARAMS

### Description
Callback triggered to get shader parameters. Cannot be filtered.

### Method
POST

### Endpoint
/ModCallback/GET_SHADER_PARAMS

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **shaderName** (string) - Required - The name of the shader.

### Request Example
```json
{
  "shaderName": "my_shader"
}
```

### Response
#### Success Response (200)
- **return value** (Record<string, unknown>) - An object containing the shader parameters.

#### Response Example
```json
{
  "param1": "value1",
  "param2": 123
}
```
```

--------------------------------

### onRerun

Source: https://isaacscript.github.io/isaacscript-common/features/RerunDetection

Helper function to detect if the current run was starting using the "Rerun" option from the main menu. This assumes that any run that is past the first floor and continues in the starting room of the run is a rerun. To use this function, you must upgrade your mod with `ISCFeature.RERUN_DETECTION`.

```APIDOC
## onRerun

### Description
Detects if the current game run was initiated using the "Rerun" option from the main menu. This is determined by checking if the run is past the first floor and the player remains in the starting room.

### Method

This is a helper function, not an HTTP method.

### Usage

To utilize this function, ensure your mod is upgraded with `ISCFeature.RERUN_DETECTION`.

### Returns

- `boolean`: Returns `true` if the current run is detected as a rerun, `false` otherwise.

### Defined in

`packages/isaacscript-common/src/classes/features/other/RerunDetection.ts:60`
```

--------------------------------

### POST_PICKUP_INIT

Source: https://isaacscript.github.io/isaac-typescript-definitions/enums/ModCallback

Callback for when a pickup is initialized. In Repentance, this populates Position, SpawnerEntity, SpawnerType, SpawnerVariant, and Velocity. Can be filtered by PickupVariant.

```APIDOC
## POST_PICKUP_INIT

### Description
Callback for when a pickup is initialized. In Repentance, this populates Position, SpawnerEntity, SpawnerType, SpawnerVariant, and Velocity. Can be filtered by PickupVariant.

### Method
POST

### Endpoint
`/callback/postPickupInit`

### Parameters
#### Query Parameters
- **pickupVariant** (PickupVariant) - Optional - Filters the callback to only fire for the specified PickupVariant.

### Request Example
```json
{
  "pickup": { ... } 
}
```

### Response
#### Success Response (200)
- **void** - No specific return value.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### pills

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

Spawns every pill on the ground, starting from the top-left-most tile.

```APIDOC
## pills

### Description
Spawns every pill on the ground, starting at the top-left-most tile.

### Method
`void`

### Defined in
packages/isaacscript-common/src/classes/features/other/extraConsoleCommands/commands.ts:1105
```

--------------------------------

### POST_PLAYER_INIT_LATE Callback

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Fires on the first POST_PEFFECT_UPDATE_REORDERED frame for each player. Useful when attributes are not properly set in POST_PLAYER_INIT. Use POST_PLAYER_INIT_FIRST for Genesis room scenarios. Can be filtered by PlayerVariant or PlayerType.

```typescript
function postPlayerInitLate(pickup: EntityPickup): void {}
```

--------------------------------

### gridEntities

Source: https://isaacscript.github.io/isaacscript-common/features/ExtraConsoleCommandsList

Spawns every grid entity, starting at the top-left-most tile.

```APIDOC
## gridEntities

### Description
Spawns every grid entity, starting at the top-left-most tile.

### Method
`void`

### Endpoint
`gridEntities()`
```

--------------------------------

### easeInBounce

Source: https://isaacscript.github.io/isaacscript-common/functions/easing

Applies a bounce easing effect that starts with a bouncing motion.

```APIDOC
## easeInBounce

### Description
Applies a bounce easing effect that starts with a bouncing motion. This function is derived from easings.net.

### Function Signature
`easeInBounce(time: number): number`

### Parameters
#### Parameters
- **time** (number) - Required - A value between 0 and 1 that represents how far along you are in the transition.

### Returns
`number` - The eased value.
```

--------------------------------

### POST_DOOR_RENDER Callback Example

Source: https://isaacscript.github.io/isaacscript-common/other/enums/ModCallbackCustom

Callback fired every frame a door exists, during the rendering phase. Can be filtered by door variant.

```typescript
function postDoorRender(door: GridEntityDoor): void {}
```
Tokens:
Raw