Binding of Isaac - Afterbirth+ Lua Reference/Guide
Functions
Isaac Namespace Reference

Functions

 DebugString (string str)
 
EntityPlayer & GetPlayer (integer playerId)
 
int GetFrameCount ()
 
Entity & Spawn (int entityType, int entityVariant, int entitySubtype, Vector position, Vector velocity, Entity Spawner)
 
GridEntity & GridSpawn (GridEntity gridEntityType, int Variant, Vector position, boolean forced)
 
 RenderText (string str, float X, float Y, float R, float G, float B, float A)
 
 RenderScaledText (string str, float X, float Y, float ScaleX, float ScaleY, float R, float G, float B, float A)
 
integer GetTextWidth (string str)
 
Vector GetRandomPosition ()
 
Vector GetFreeNearPosition (Vector pos, float step)
 
 Explode (Vector pos, Entity source, float damage)
 
integer AddPillEffectToPool (integer pillEffect)
 returns pill color More...
 
table GetRoomEntities ()
 returns all entities in the room More...
 
integer GetChallenge ()
 
integer GetEntityTypeByName (string entityName)
 
integer GetEntityVariantByName (string entityName)
 
integer GetItemIdByName (string itemName)
 
integer GetPlayerTypeByName (string playerName)
 
integer GetCardIdByName (string cardHudName)
 
integer GetPillEffectByName (string pillEffect)
 
integer GetTrinketIdByName (string trinketName)
 
integer GetChallengeIdByName (string challengeName)
 
integer GetCostumeIdByPath (string path)
 
integer GetCurseIdByName (string curseName)
 
integer GetSoundIdByName (string soundName)
 
integer GetMusicIdByName (string musicName)
 
integer GetTime ()
 
string ExecuteCommand (string command)
 
 ConsoleOutput (string text)
 
Config & GetItemConfig ()
 
table FindInRadius (Vector Position, float Radius, integer Partitions)
 Returns entities in range of Radius from Position filtered by Partitions mask (see EntityPartition enum) (include all = 0xffffffff) More...
 
table FindByType (integer Type, integer Variant, integer Subtype, boolean Cache, boolean IgnoreFriendly)
 
integer CountEntities (Entity Spawner, integer Type, integer Variant, integer Subtype)
 Counts entities from SpawnerEntity (can be NULL) and/or Type (can be ENTITY_NULL), and/or Variant/Subtype (can be -1) More...
 
integer CountBosses ()
 
integer CountEnemies ()
 
 RegisterMod (table ref, string modName, integer apiVersion)
 Exposed methods. More...
 
 AddCallback (table ref, integer callbackId, table callbackFn, integer entityId)
 
 RemoveCallback (table ref, integer callbackId, table callbackFn)
 
 SaveModData (table ref, string data)
 
string LoadModData (table ref)
 
boolean HasModData (table ref)
 
 RemoveModData (table ref)
 
Vector ScreenToWorld (Vector pos)
 
Vector WorldToScreen (Vector pos)
 
Vector WorldToScreenDistance (Vector pos)
 
Vector WorldToRenderPosition (Vector pos)
 
Vector ScreenToWorldDistance (Vector pos)
 

Function Documentation

◆ AddCallback()

Isaac::AddCallback ( table  ref,
integer  callbackId,
table  callbackFn,
integer  entityId 
)

◆ AddPillEffectToPool()

integer Isaac::AddPillEffectToPool ( integer  pillEffect)

returns pill color

◆ ConsoleOutput()

Isaac::ConsoleOutput ( string  text)

Prints a string into the Debug Console

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.

◆ CountBosses()

integer Isaac::CountBosses ( )

Returns the number of bosses in the current room.

◆ CountEnemies()

integer Isaac::CountEnemies ( )

Returns the number of enemies in the current room.

◆ CountEntities()

integer Isaac::CountEntities ( Entity  Spawner,
integer  Type,
integer  Variant,
integer  Subtype 
)

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 entitys Variant and Subtype (Can be -1)

◆ DebugString()

Isaac::DebugString ( string  str)

Prints a string into the log file. You can find this file here C:\Users\Jan\Documents\My Games\Binding of Isaac Afterbirth+\log.txt

This code prints "This is a Test." in the log.txt file. 
Isaac.DebugString("This is a Test.")
-- Output: Lua Debug: This is a Test.

◆ ExecuteCommand()

string Isaac::ExecuteCommand ( string  command)

This function executes a debug console command. see [Tutorial] Debug Console for informations on how to use commands.

◆ Explode()

Isaac::Explode ( Vector  pos,
Entity  source,
float  damage 
)

Spawn an explosion on a specified location.

◆ FindByType()

table Isaac::FindByType ( integer  Type,
integer  Variant,
integer  Subtype,
boolean  Cache,
boolean  IgnoreFriendly 
)

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.

◆ FindInRadius()

table Isaac::FindInRadius ( Vector  Position,
float  Radius,
integer  Partitions 
)

Returns entities in 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.

◆ GetCardIdByName()

integer Isaac::GetCardIdByName ( string  cardHudName)

Returns the CardID based on its hud value. (File: pocketitems.xml)

This code gets the CardID of XVI - The Tower. 
Isaac.GetCardIdByName("16_TheTower")
    --Returns: 17
  • The name of this function is misleading, this function will only work with the hud value of a card and not the name of a card.

◆ GetChallenge()

integer Isaac::GetChallenge ( )

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

◆ GetChallengeIdByName()

integer Isaac::GetChallengeIdByName ( string  challengeName)

Returns the ChallengeID of a challenge based on its name. (File: challenges.xml)

This code gets the ChallengeID of Aprils fool. 
Isaac.GetChallengeIdByName("Aprils fool")
    --Returns: 32

◆ GetCostumeIdByPath()

integer Isaac::GetCostumeIdByPath ( string  path)

Returns the CostumeID of a costume based on its file path. (File: costumes2.xml)

This code gets the CostumeID of the Poop transformation costume. 
Isaac.GetCostumeIdByPath("gfx/characters/n027_Transformation_Poop.anm2")
    --Returns: 27

◆ GetCurseIdByName()

integer Isaac::GetCurseIdByName ( string  curseName)

Returns the CurseID of a curse based on its name. (File: curses.xml)

This code gets the CurseID of Curse of the Unknown. 
Isaac.GetCurseIdByName("Curse of the Unknown")
    --Returns: 4

◆ GetEntityTypeByName()

integer Isaac::GetEntityTypeByName ( string  entityName)

Returns the EntityType of an entity based on its name. (File: entities2.xml)

This code gets the EntityType of Flaming Gaper. 
Isaac.GetEntityTypeByName("Flaming Gaper")
    --Returns: 10
  • There is no SubType version of this function.

◆ GetEntityVariantByName()

integer Isaac::GetEntityVariantByName ( string  entityName)

Returns the variant of an entity based on its name. (File: entities2.xml)

This code gets the variant of Flaming Gaper. 
Isaac.GetEntityVariantByName("Flaming Gaper")
    --Returns: 2
  • There is no SubType version of this function.

◆ GetFrameCount()

int Isaac::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()

◆ GetFreeNearPosition()

Vector Isaac::GetFreeNearPosition ( Vector  pos,
float  step 
)

◆ GetItemConfig()

Config& Isaac::GetItemConfig ( )

Returns the ItemConfig::Config object.

◆ GetItemIdByName()

integer Isaac::GetItemIdByName ( string  itemName)

Returns the ItemID of a Collectible. (File: items.xml)

This code gets the ItemID of Brimstone. 
Isaac.GetItemIdByName("Brimstone")
    --Returns: 118

◆ GetMusicIdByName()

integer Isaac::GetMusicIdByName ( string  musicName)

Returns the MusicID of a music track. (File: music.xml)

This code gets the MusicID of the Title Screen. 
Isaac.GetMusicIdByName("Title Screen")
    --Returns: 61

◆ GetPillEffectByName()

integer Isaac::GetPillEffectByName ( string  pillEffect)

Returns the PillEffectID based on its name. (File: pocketitems.xml)

This code gets the PillEffectID of I can see forever!. 
Isaac.GetPillEffectByName("I can see forever!")
    --Returns: 23

◆ GetPlayer()

EntityPlayer& Isaac::GetPlayer ( integer  playerId)

Returns the EntityPlayer which the user is controlling. 0 = Main player. Higher numbers refer to coop babies.

Isaac.GetPlayer(0)

◆ GetPlayerTypeByName()

integer Isaac::GetPlayerTypeByName ( string  playerName)

Returns the PlayerType of a character based on its name. (File: players.xml)

This code gets the PlayerType of Azazel. 
Isaac.GetPlayerTypeByName("Azazel")
    --Returns: 7

◆ GetRandomPosition()

Vector Isaac::GetRandomPosition ( )

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

◆ GetRoomEntities()

table Isaac::GetRoomEntities ( )

Returns a table containing all entities in the room.

◆ GetSoundIdByName()

integer Isaac::GetSoundIdByName ( string  soundName)

Returns the SoundEffectID of a sound based on its name. (File: sounds.xml)

This code gets the SoundEffectID of a sound named "Custom Sound Effect" 
Isaac.GetSoundIdByName("Custom Sound Effect")

◆ GetTextWidth()

integer Isaac::GetTextWidth ( string  str)

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

◆ GetTime()

integer Isaac::GetTime ( )

Returns the current game time in milliseconds. This includes pauses!

◆ GetTrinketIdByName()

integer Isaac::GetTrinketIdByName ( string  trinketName)

Returns the TrinketType of a trinket based on its name. (File: items.xml)

This code gets the TrinketType of Lucky Toe. 
Isaac.GetTrinketIdByName("Lucky Toe")
    --Returns: 42

◆ GridSpawn()

GridEntity& Isaac::GridSpawn ( GridEntity  gridEntityType,
int  Variant,
Vector  position,
boolean  forced 
)

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

forced has no effect and will NOT override the grid entity at the given location. Remove a grid entity at the given location if nessesary before spawning something again.

◆ HasModData()

boolean Isaac::HasModData ( table  ref)

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

◆ LoadModData()

string Isaac::LoadModData ( table  ref)

Returns a JSON array/table 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. 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.

This code loads data stored in the "saveX.dat" file, if it exists. 
local yourMod = RegisterMod("someMod", 1)
local json = require("json")
-- ...
function yourMod:OnGameStart(isSave)
	--Loading Moddata--
	if yourMod:HasData() then
		local myTable = json.decode(Isaac.LoadModData(yourMod))
	end
end
yourMod:AddCallback(ModCallbacks.MC_POST_GAME_STARTED, yourMod.OnGameStart)

◆ RegisterMod()

Isaac::RegisterMod ( table  ref,
string  modName,
integer  apiVersion 
)

Method to define a mod in the game. THIS NEEDS TO BE DEFINED IN EVERY MOD!

local yourMod = RegisterMod("someMod", 1)

◆ RemoveCallback()

Isaac::RemoveCallback ( table  ref,
integer  callbackId,
table  callbackFn 
)

◆ RemoveModData()

Isaac::RemoveModData ( table  ref)

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.

◆ RenderScaledText()

Isaac::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.

This code renders the player position on the screen. 
local player = Isaac.GetPlayer(0)
local pos = player.Position
Isaac.RenderText("X: "..pos.X.." Y: "..pos.Y, 50, 50, 0.5, 0.5, 1 ,1 ,1 ,1 )

◆ RenderText()

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

This code renders the player position on the screen. 
local player = Isaac.GetPlayer(0)
local pos = player.Position
Isaac.RenderText("X: "..pos.X.." Y: "..pos.Y, 50, 50, 1 ,1 ,1 ,1 )

◆ SaveModData()

Isaac::SaveModData ( table  ref,
string  data 
)

Stores a JSON array/table 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. 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.

This code saves a table in the "saveX.dat" file. 
local yourMod = RegisterMod("someMod", 1)
local json = require("json")
-- ...
--Saving Moddata--
function yourMod:SaveGame()
    local table= {1,2,3}
    yourMod.SaveData(yourMod, json.encode(table))
end
yourMod:AddCallback(ModCallbacks.MC_PRE_GAME_EXIT, yourMod.SaveGame)

◆ ScreenToWorld()

Vector Isaac::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).

◆ ScreenToWorldDistance()

Vector Isaac::ScreenToWorldDistance ( Vector  pos)

◆ Spawn()

Entity& Isaac::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() and Game():Spawn(). If you need to spawn something with a specific seed, then you use Game():Spawn(). If you need to spawn something with a randomly generated seed, then use Isaac.Spawn(). Most of the time, you will probably want to use Isaac.Spawn().

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)

◆ WorldToRenderPosition()

Vector Isaac::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.

◆ WorldToScreen()

Vector Isaac::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

This code render "test" at the position of the player. The text will move with isaac. 
local player = Isaac.GetPlayer(0)
local screenpos = Isaac.WorldToScreen(player.Position)	
Isaac.RenderText("test", screenpos.X, screenpos.Y, 1 ,1 ,1 ,1 )

◆ WorldToScreenDistance()

Vector Isaac::WorldToScreenDistance ( Vector  pos)