Global Class "Isaac"⚓︎

Info

You can get this class by using the Isaac global table.

Note that to call these functions, you must use a . (period) instead of a : (colon)!

Example Code

local player = Isaac.GetPlayer()

Functions⚓︎

Add·Callback ()⚓︎

void AddCallback ( table modRef, ModCallback|string callbackId, table callbackFn, int entityId )⚓︎

It is recommended to use the AddCallback function on a Mod Reference instead.

Add·Pill·Effect·To·Pool ()⚓︎

int AddPillEffectToPool ( int pillEffect )⚓︎

Returns the PillColor of the added pill.

Add·Priority·Callback ()⚓︎

void AddPriorityCallback ( table modRef, ModCallback|string callbackId, CallbackPriority priority, table callbackFn, int entityId )⚓︎

It is recommended to use the AddPriorityCallback function on a Mod Reference instead.

Console·Output ()⚓︎

void ConsoleOutput ( string text )⚓︎

Prints a string into the Debug Console.

Example Code

You can use this example as an alternative.

Isaac.ConsoleOutput("This is a Test.")
-- Output: This is a Test.

-- Alternatively:
print("This is a Test.")
-- Output: This is a Test.

Count·Bosses ()⚓︎

int CountBosses ( )⚓︎

Returns the number of bosses in the current room.

Count·Enemies ()⚓︎

int CountEnemies ( )⚓︎

Returns the number of enemies in the current room.

Count·Entities ()⚓︎

int CountEntities ( Entity Spawner, EntityType Type = EntityType.ENTITY_NULL, int Variant = -1, int SubType = -1 )⚓︎

Returns the number of entities in the current room that fulfill the specified requirements.

Spawner refers to an Entity object (can be nil).
Type refers to the found entity's type (can be EntityType.ENTITY_NULL).
Variant and Subtype refer to the found entity's Variant and Subtype (can be -1).

Debug·String ()⚓︎

void DebugString ( string str )⚓︎

Prints a string into the log file. You can find this file here: %systemdrive%\Users\%username%\Documents\My Games\Binding of Isaac Repentance\log.txt

Example Code

This code prints "This is a Test." in the log.txt file.

Isaac.DebugString("This is a Test.")
-- Output: [INFO] - Lua Debug: This is a Test.

Execute·Command ()⚓︎

string ExecuteCommand ( string command )⚓︎

This function executes a debug console command. See the Debug Console Tutorial for informations on how to use commands.

Explode ()⚓︎

void Explode ( Vector pos, Entity source, float damage )⚓︎

Spawn an explosion on a specified location.

Find·By·Type ()⚓︎

Entity[] FindByType ( EntityType Type, int Variant = -1, int SubType = -1, boolean Cache = false, boolean IgnoreFriendly = false )⚓︎

Returns entities based on Type, Variant, Subtype. If Variant and/or Subtype is -1 then everything is included. Use Cache flag for multiple calls per frame.

If an entity has EntityFlag.FLAG_NO_QUERY then it will be excluded from the results. If you need to get an entity with that flag then you should use GetRoomEntities instead.

Find·In·Radius ()⚓︎

Entity[] FindInRadius ( Vector Position, float Radius, int Partitions = 0xFFFFFFFF )⚓︎

Returns an array of all entities inside the range of Radius from Position filtered by Partitions mask (see EntityPartition enum) (include all = 0xffffffff)

This function does not return the entities sorted by nearest first, but based on the order they were loaded.

Get·Built·In·Callback·State ()⚓︎

boolean GetBuiltInCallbackState ( ModCallbacks callbackId )⚓︎

Returns true if callbacks under callbackId will be ran by the game. This is normally only false if there are no callbacks added under callbackId.

Get·Callbacks ()⚓︎

table GetCallbacks ( ModCallback|string callbackId, boolean createIfMissing = nil )⚓︎

Returns a list of callbacks added under callbackId. Callbacks are represented as a table, for more information see the custom callback tutorial.

The game holds all callbacks added to callbackId in a table, where the callbackId is the index, and the value is a table containing all callbacks added using said callbackId. If createIfMissing is true, and there are no added callbacks under callbackId, then the game will create an empty table for the callbackId for new callbacks to be added to. This empty table contains a metatable with a default __matchParams metamethod, which is called when checking if the extra parameter specified when adding the callback is valid. This function is also used with createIfMissing set to true by the game whenever any callback is added.

If createIfMissing is false or nil and there are no callbacks added under callbackId, this function will return an empty table.

Get·Card·Id·By·Name ()⚓︎

int GetCardIdByName ( string cardHudName )⚓︎

Returns the CardID based on the "hud"-attribute defined in the "pocketitems.xml" file. Returns -1 if no card with that "hud" attribute value could be found.

Warning

The name of this function is misleading, this function will only work with the "hud"-attribute value of a card and not the name of a card.

Bug

This function does not work for vanilla cards/runes, because they don't have the "hud" attribute defined in their entry in the pocketitems.xml file. You need to use the Card enum to get those vanilla IDs instead.

Example Code

This code gets the CardID of a modded card.

<pocketitems>
    <card type="tarot" pickup="1" description="some description"  name="My new card" hud="my_modded_card" />
</pocketitems>

Isaac.GetCardIdByName("my_modded_card")

Get·Challenge ()⚓︎

int GetChallenge ( )⚓︎

Returns the ID of a challenge the player is currently in. Returns 0 if the player is not playing any challenge.

Get·Challenge·Id·By·Name ()⚓︎

int GetChallengeIdByName ( string challengeName )⚓︎

Returns the ChallengeID of a challenge based on its name. (File: challenges.xml) Returns -1 if no challenge with that name could be found (Case sensitive).

Example Code

This code gets the ChallengeID of Aprils fool.

Isaac.GetChallengeIdByName("Aprils fool")
--Returns: 32

Get·Costume·Id·By·Path ()⚓︎

int GetCostumeIdByPath ( string path )⚓︎

Returns the CostumeID of a costume based on its file path. (File: costumes2.xml) Returns -1 if no costume with that path could be found.

Example Code

This code gets the CostumeID of the Poop transformation costume.

Isaac.GetCostumeIdByPath("gfx/characters/n027_Transformation_Poop.anm2")
--Returns: 27

Get·Curse·Id·By·Name ()⚓︎

int GetCurseIdByName ( string curseName )⚓︎

Returns the CurseID of a curse based on its name. (File: curses.xml) Returns -1 if no curse with that name could be found.

Example Code

This code gets the CurseID of Curse of the Unknown.

Isaac.GetCurseIdByName("Curse of the Unknown")
--Returns: 4

Get·Entity·Type·By·Name ()⚓︎

int GetEntityTypeByName ( string entityName )⚓︎

Returns the EntityType of an entity based on its name. (File: entities2.xml) Returns 0 if no entity with that name could be found.

Notes

There is no SubType version of this function.

Example Code

This code gets the EntityType of Flaming Gaper.

Isaac.GetEntityTypeByName("Flaming Gaper")
--Returns: 10

Get·Entity·Variant·By·Name ()⚓︎

int GetEntityVariantByName ( string entityName )⚓︎

Returns the variant of an entity based on its name. (File: entities2.xml) Returns -1 if no entity with that name could be found.

Notes

There is no SubType version of this function.

Example Code

This code gets the variant of Flaming Gaper.

Isaac.GetEntityVariantByName("Flaming Gaper")
--Returns: 2

Get·Frame·Count ()⚓︎

int GetFrameCount ( )⚓︎

Returns the amount of frames the game as a whole is running. The counter increases even when the game is paused or when you are in the main menu! 1 second equals roughtly 60 frames. This function therefore works drastically different than Game():GetFrameCount()

Get·Free·Near·Position ()⚓︎

Vector GetFreeNearPosition ( Vector pos, float step )⚓︎

Get·Item·Config ()⚓︎

ItemConfig GetItemConfig ( )⚓︎

This is the only way to access the ItemConfig object.

Get·Item·Id·By·Name ()⚓︎

int GetItemIdByName ( string itemName )⚓︎

Returns the ItemID of a Collectible. (File: items.xml) Returns -1 if no item with that name could be found.

Example Code

This code gets the ItemID of Brimstone.

Isaac.GetItemIdByName("Brimstone")
--Returns: 118

Get·Music·Id·By·Name ()⚓︎

int GetMusicIdByName ( string musicName )⚓︎

Returns the MusicID of a music track. (File: music.xml) Returns -1 if no music with that name could be found.

Example Code

This code gets the MusicID of the Title Screen.

Isaac.GetMusicIdByName("Title Screen")
--Returns: 61

Get·Pill·Effect·By·Name ()⚓︎

int GetPillEffectByName ( string pillEffect )⚓︎

Returns the PillEffectID based on its name. (File: pocketitems.xml) Returns -1 if no pill with that name could be found.

Example Code

This code gets the PillEffectID of I can see forever!.

Isaac.GetPillEffectByName("I can see forever!")
--Returns: 23

Get·Player ()⚓︎

EntityPlayer GetPlayer ( int playerID = 0 )⚓︎

Returns the EntityPlayer that matches the provided player ID. Player IDs start at 0 and increment upwards. For example, when playing as Jacob & Esau, Jacob will have a player ID of 0 and Esau will have a player ID of 1.

If an invalid player ID is passed (such as -20 or 20), the function will instead assume a player index of 0.

This function can return nil if it is called before any player is initialized (i.e. if you call it in the main menu).

This function is the same as Game():GetPlayer().

Example Code

local function getPlayers()
  local game = Game()
  local numPlayers = game:GetNumPlayers()

  local players = {}
  for i = 0, numPlayers - 1 do
    local player = Isaac.GetPlayer(i)
    table.insert(players, player)
  end

  return players
end

Get·Player·Type·By·Name ()⚓︎

PlayerType GetPlayerTypeByName ( string playerName , boolean Tainted = false )⚓︎

Returns the PlayerType (ID) of a character based on its name. (File: players.xml) Returns -1 if no player with that name could be found.

Warning

In Repentance, character names where made translateable and therefore use the translation placeholder as their "base name". For example, to get the PlayerType of Cain, you need to use this function with the character name #AZAZEL_NAME instead of Azazel. It is therefore recommended to use this function for modded characters, and use the PlayerType enum directly, if you want to have the PlayerType of a vanilla character.

Example Code

This code gets the PlayerType of Azazel.

-- REPENTANCE:
Isaac.GetPlayerTypeByName("#AZAZEL_NAME") --Returns: 7

-- AFTERBIRTH+:
Isaac.GetPlayerTypeByName("Azazel") --Returns: 7

Get·Random·Position ()⚓︎

Vector GetRandomPosition ( )⚓︎

Returns a random position inside the current room. The Return value is a Vector containing the position in world coordinates.

Get·Room·Entities ()⚓︎

Entity[] GetRoomEntities ( )⚓︎

Returns an iterable table containing all entities in the room at the time the function was called.

This behavior is different to Room::GetEntities(), which returns a raw pointer to the array that stores all entities of the room at any given time. For most usecases, its advised to use Isaac.GetRoomEntities()!

Example Code

This code prints the Type, Variant and SubType of each entity in the room.

for i, entity in ipairs(Isaac.GetRoomEntities()) do
    print(entity.Type, entity.Variant, entity.SubType)
end

Get·Screen·Height ()⚓︎

float GetScreenHeight ( )⚓︎

Get·Screen·Point·Scale ()⚓︎

float GetScreenPointScale ( )⚓︎

Returns a number denoting how "zoomed in" the screen is. This can be 1.0 or 2.0, depending on the resolution of the game window.

Video Demonstration

Demonstration of how the size of the game window changes the value this function returns.

Get·Screen·Width ()⚓︎

float GetScreenWidth ( )⚓︎

Get·Sound·Id·By·Name ()⚓︎

int GetSoundIdByName ( string soundName )⚓︎

Returns the SoundEffectID of a sound based on its name. (File: sounds.xml) Returns -1 if no sound with that name could be found.

Example Code

This code gets the SoundEffectID of a sound named "Custom Sound Effect"

Isaac.GetSoundIdByName("Custom Sound Effect")

Get·Text·Width ()⚓︎

int GetTextWidth ( string str )⚓︎

Returns the width of the given string in pixels based on the "terminus8" font (same font as used in Isaac.RenderText())

Get·Time ()⚓︎

int GetTime ( )⚓︎

Returns the current time in milliseconds since the computer's operating system was started.

This is useful for measuring how much real time has passed independent of how many frames have passed. (Frames are not a very good indicator of how much time has passed, because the game locks up to load new data on every level transition and room transition.)

For example, you could use this to implement an on-screen speedrunning timer based on real-time, or to benchmark the performance impact of one function over another.

Get·Trinket·Id·By·Name ()⚓︎

int GetTrinketIdByName ( string trinketName )⚓︎

Returns the TrinketType of a trinket based on its name. (File: items.xml) Returns -1 if no trinket with that name could be found.

Example Code

This code gets the TrinketType of Lucky Toe.

Isaac.GetTrinketIdByName("Lucky Toe")
--Returns: 42

Grid·Spawn ()⚓︎

GridEntity GridSpawn ( GridEntityType gridEntityType, int variant, Vector position, boolean forced )⚓︎

Spawn a GridEntity at the given position (world coordinates).

Bugs

The "forced" argument can override the grid entity at the given location in certain cases. For example: it won't work with a rock, but will work with a rock that's been blown up. You can check the location with Isaac.GetFreeNearPosition to see if the game considers that location free. Check the returned grid entity's type to make sure the replacement happened. Otherwise, you may need to remove the grid entity at the given location before spawning something else in its place.

For example, to spawn a super secret rock in the center of the room:

local game = Game()
local room = game:GetRoom()
local centerPos = room:GetCenterPos()
Isaac.GridSpawn(GridEntityType.GRID_ROCK_SS, 0, centerPos, true)

Has·Mod·Data ()⚓︎

boolean HasModData ( table modRef )⚓︎

Returns "true" if your mod has Data stored using the "SaveModData()" function. Aka. if there is a "saveX.dat" file in your mod folder.

There are 3 "saveX.dat" files, one per Savegame. The number indicates the savegame it corresponds to. The number will be determined automatically by the game.

For AB+, they are stored inside their mod's folder next to the "main.lua" file.

For Repentance, They are stored in the "data" folder next to the "mods" folder inside the game files.

It is recommended to use the HasData function on a Mod Reference instead.

Load·Mod·Data ()⚓︎

string LoadModData ( table modRef )⚓︎

Returns a string that was stored in a "saveX.dat" file using the "SaveModData()" function. If there is no "saveX.dat" file in your mod, this function will return an empty string. There are 3 "saveX.dat" files, one per Savegame. The number indicates the savegame it corresponds to. The number will be determined automatically by the game.

If you call this function in the main menu, it will return the save data for save slot 1 by default.

For AB+, they are stored inside their mod's folder next to the "main.lua" file.

For Repentance, They are stored in the "data" folder next to the "mods" folder inside the game files.

It is recommended to use the LoadData function on a Mod Reference instead.

Register·Mod ()⚓︎

void RegisterMod ( table modRef, string modName, int apiVersion )⚓︎

Registers a table with the game to use as a Mod Reference.

It is recommended to use the global RegisterMod function instead.

Remove·Callback ()⚓︎

void RemoveCallback ( table modRef, ModCallback|string callbackId, table callbackFn )⚓︎

It is recommended to use the RemoveCallback function on a Mod Reference instead.

Remove·Mod·Data ()⚓︎

void RemoveModData ( table modRef )⚓︎

Deletes the stored "saveX.dat" file if it exists. There are 3 "saveX.dat" files, one per Savegame. They are stored in the mod's folder next to the "main.lua" file. The number indicates the savegame it corresponds to. The number will be determined automatically by the game.

It is recommended to use the RemoveData function on a Mod Reference instead.

Render·Scaled·Text ()⚓︎

void RenderScaledText ( string str, float X, float Y, float ScaleX, float ScaleY, float R, float G, float B, float A )⚓︎

Renders a scaled text on the Screen. X and Y coordinates need to be in screen coordinates ( x[0,~500) y [0,~350) ). ScaleX, ScaleY, R ,G ,B and A need to be between [0,1]. Some scale values can cause the font to display deformed and pixelated.

Example Code

This code renders the player position on the screen.

local player = Isaac.GetPlayer()
local text = "X: " .. player.Position.X .. ", Y: " .. player.Position.Y
Isaac.RenderScaledText(text, 50, 50, 0.5, 0.5, 1, 1, 1, 1)

Render·Text ()⚓︎

void RenderText ( string str, float X, float Y, float R, float G, float B, float A )⚓︎

Renders a text with the default size on the Screen. X and Y coordinates need to be in screen coordinates ( x[0,~500) y [0,~350) ). R,G,B and A need to be between [0,1].

Example Code

This code renders the player position on the screen.

local player = Isaac.GetPlayer()
local pos = player.Position
Isaac.RenderText("X: "..pos.X.." Y: "..pos.Y, 50, 50, 1 ,1 ,1 ,1 )

Run·Callback ()⚓︎

void RunCallback ( ModCallback|string callbackId )⚓︎

Runs all callbacks added under callbackId, breaking on the first return and returning that value.

Run·Callback·With·Param ()⚓︎

void RunCallbackWithParam ( ModCallback|string callbackId )⚓︎

Runs all callbacks added under callbackId, breaking on the first return and returning that value.

Save·Mod·Data ()⚓︎

void SaveModData ( table modRef, string data )⚓︎

Stores a string in a "saveX.dat" file. The stored Data persists thruout resets and game restart, so its perfect to store persistent data.

There are 3 "saveX.dat" files, one per Savegame. The number indicates the savegame it corresponds to. The number will be determined automatically by the game.

For AB+, they are stored inside their mod's folder next to the "main.lua" file.

For Repentance, They are stored in the "data" folder next to the "mods" folder inside the game files.

It is recommended to use the SaveData function on a Mod Reference instead.

Screen·To·World ()⚓︎

Vector ScreenToWorld ( Vector pos )⚓︎

Transfers Screen (aka. Window coordinates) into Worldcoordinates. This can be used to get a specific location in the room in World coordnates The World coordinate system is x[0,inf) y[0,inf).

Screen·To·World·Distance ()⚓︎

Vector ScreenToWorldDistance ( Vector pos )⚓︎

Set·Built·In·Callback·State ()⚓︎

void SetBuiltInCallbackState ( ModCallbacks callbackId, boolean state )⚓︎

Sets whether callbacks under callbackId will be ran by the game. The game uses this to activate a ModCallbacks once a callback is added under one, or deactivate them when those callbacks have been removed.

Spawn ()⚓︎

Entity Spawn ( int entityType, int entityVariant, int entitySubtype, Vector position, Vector velocity, Entity Spawner )⚓︎

Spawns the defined entity at the given location. If the position is not free, it spawns it in the nearest free position.

There are two spawn functions. Isaac.Spawn() (this one), which spawns an entity with a random seed, and Game():Spawn(), which spawns an entity with a specific seed. However due to a bug, Isaac.Spawn() has a chance to generate a seed of 0, which crashes the game. If you need to spawn an entity with a random seed, you should always use Game():Spawn() with a helper function that calls Random() and arbitrarily sets the seed to 1 when the seed is 0. (IsaacScript users can just use the spawn helper function, which uses Game.Spawn under the hood.)

Example Code

This code spawns a random collectible at in center of the current room.

Isaac.Spawn(EntityType.ENTITY_PICKUP, PickupVariant.PICKUP_COLLECTIBLE, 0, Vector(320,280), Vector(0,0), nil)

Bug

Because the random seed is generated using the Random() function, there is a chance that the entity's InitSeed is set to 0, which causes a crash if the entity needs to use RNG.

World·To·Render·Position ()⚓︎

Vector WorldToRenderPosition ( Vector pos )⚓︎

Transfers world (aka. game coordinates) into Rendercoordinates. This can be used to render things at fixed positions in a room. The Render coordinate system is x[0,inf) y[0,inf). It defines the Position on the rendering-plane in the current room.

Example Code

This code render "test" at the position of the mouse cursor independend on if the game is in full screen or not.

local mousePos = Input.GetMousePosition(true)
local renderpos = Isaac.WorldToRenderPosition(mousePos) * 2
Isaac.RenderText("test", renderpos.X, renderpos.Y, 1 ,1 ,1 ,1 )

World·To·Screen ()⚓︎

Vector WorldToScreen ( Vector pos )⚓︎

Transfers world (aka. game coordinates) into Screen (aka. Window) coordinates. This can be used to render things next to an entity. The Screen coordinate system is x[0,inf) y[0,inf). Normally, it goes till ~500x ~300y. The return vector contains integer values or numbers ending with .5

Example Code

This code render "test" at the position of the player. The text will move with isaac.

local player = Isaac.GetPlayer()
local screenpos = Isaac.WorldToScreen(player.Position)
Isaac.RenderText("test", screenpos.X, screenpos.Y, 1 ,1 ,1 ,1 )

World·To·Screen·Distance ()⚓︎

Vector WorldToScreenDistance ( Vector pos )⚓︎

Last update: August 12, 2024