Modding The Binding Of Isaac
In this article, we're going to take a look at The Binding of Isaac: Afterbirth+ modding API and go over the basic steps to create a simple item mod for the game.
The first step to making a new mod is to navigate to your mods directory and create a new folder.
// Windows C:\Users\YourName\My Games\Binding of Isaac Afterbirth+ Mods\ // OSX ~/Library/Application Support/Binding of Isaac Afterbirth+ Mods/
This new folder requires a few files and a specific folder structure to actually work correctly. In our case, we're going to be creating an item - so our mod will require a folder named
content a folder named
Inside of our
resources directory we need to add a few more folders. When done, our directory structure should look like so:
- my-mod/ - content/ - resources/ - gfx/ - items/ - collectibles/
The reason that we have to structure the
resources folders in this way is because they directly map to the folder structure that the game already uses. We're essentially mimicking this structure so that the game knows where to find our files and pull them into the game.
Creating The Items File
Next, inside of our
content directory, we will need to create a new file named
items.xml. This file will contain the basic information for the item that we are creating in addition to a reference to the graphic that we will be using for it.
This file has to be located inside of the
content directory to work properly. Unlike the
resources directory, this breaks the pattern of mimicking the same location the the game already uses.
<items gfxroot="gfx/items/" version="1"> <passive cache="damage shotspeed range luck flying" name="My Item" description="My item description" soulhearts="6" gfx="collectibles_my_item.png"/> </items>
<items /> element, we just need to provide the root directory to find the graphics files that we will be using and the version of the API.
Inside, we added a new
<passive /> element which signifies that we are creating a passive item (for reference, the other options are
<active /> and
<trinket />). On this element, we provide all of the necessary properties that that game will use.
First we provide it a
description. These will be used directly inside of the game when the player picks up the item. Next, we have a couple function properties
cache property values are used to trigger stat changes for the player. You will provide a corresponding cache value for every stat that you wish to modify.
soulhearts property values reflect how many soul hearts we would like to give to the player when they pick up this item. It is important to note that this numeric value corresponds to the smallest heart unit: the half-heart. So, in this case, we wish to give the player 3 full soulhearts so we must double the number assigned to this property.
Adding Your Item Graphics
Once you have successfully added your
items.xml file, we can now add in an image file for our item. Making the image from scratch is well beyond the scope of this tutorial, but all you need is to have an image that is 32px-by-32px and place it into the
resources/gfx/items/collectibles/ directory that we created earlier. Just make sure that the image filename is exactly what you set as the value in the
gfx property of the item in the
items.xml file we created above.
Our item is going to do basic stat updates for the player, similar to the various items already in the game that give increase all of your stats.
To do this, we need to add in some logic to tell the game which stats we would like to increase and by how much.
In the root directory of our project, create a new
main.lua file. Inside of the file, we'll first register our new mod and set a reference to the game.
local MyMod = RegisterMod("My Mod", 1) local game = Game()
This registers our new mod by passing in a string of
"My Mod" and
1, which sets the name of our mod and the API version we're using. A reference to our mod is then stored in the
MyMod local variable that we can now use within our code.
As an additional convenience, we've also created a
game variable to reference the game class.
Next, let's make some references to the item that we are creating and attach them to our mod. This will make it easier reference them throughout our code.
-- Initialize Item Constants MyMod.COLLECTIBLE_MY_ITEM = Isaac.GetItemIdByName("My Item")
Next, we will begin setting up some various callbacks. These callbacks are what the game uses to trigger logic around events that happen in the game. We will be using these callbacks to execute custom logic for our item.
Since this item is going to update our stats, let's make a function called
onCacheEval and then assign it to the
MC_CACHE_EVALUATE callback. This will trigger the the
onCacheEval function anytime a cache update occurs.
-- Handle Cache Updates (eg. Stat Changes) function MyMod:onCacheEval(player, flag) -- My Item Functionality if player:HasCollectible(MyMod.COLLECTIBLE_MY_ITEM) then if flag == CacheFlag.CACHE_DAMAGE then player.Damage = player.Damage + 1; -- Prevent Delay From Going Too Low -- (Best Practice Is 5 As Lowest Value) if player.MaxFireDelay >= 5 + 2 then player.MaxFireDelay = player.MaxFireDelay - 2; elseif player.MaxFireDelay >= 5 then player.MaxFireDelay = 5; end end if flag == CacheFlag.CACHE_SPEED then player.MoveSpeed = player.MoveSpeed + 0.25; end if flag == CacheFlag.CACHE_RANGE then player.TearHeight = player.TearHeight - 1; --player.TearFallingSpeed = player.TearFallingSpeed - 1; --player.TearColor = TearFlags.TEAR_FEAR; end if flag == CacheFlag.CACHE_TEARFLAG then player.TearFlags = player.TearFlags + TearFlags.TEAR_BOUNCE; end if flag == CacheFlag.CACHE_LUCK then player.Luck = player.Luck + 1; end if flag == CacheFlag.CACHE_SHOTSPEED then player.ShotSpeed = player.ShotSpeed + 0.15; end end end MyMod:AddCallback(ModCallbacks.MC_EVALUATE_CACHE, MyMod.onCacheEval)
The majority of this code should read fairly straightforward. We are simply writing if statements to check whether or not cache flags are set. These flags are the string values that we assigned to the
cache property of our item in the
items.xml file we created before.
The cache values are preset keywords defined by the game itself. So, these have to be exactly what the game defines to work properly.
The oddball in this set of code is where we are updating the fire delay. For some strange reason, this value must be updated within the code that checks the
damage cache flag. Unfortunately, I don't know a lot of detail behind this issue, but as soon as I find out I will update this to reflect the finer details.
So, to easily test our item, let's setup a quick way to immediately spawn our custom item into the game as soon as we begin a new run.
Let's add in a debug variable that will hold a boolean value. This is what we will use to easily trigger our item in game for testing purposes.
At the beginning of our
main.lua file, let's add in a
isDebugging property after our mod and game references.
local TheOfficeMod = RegisterMod("The Office", 1) local game = Game() local isDebugging = false // Added
With that added, let's add in a new callback that will run on every game update.
-- Update Callback (Runs Every Frame) function MyMod:onUpdate(player) -- Place Item On Ground (For Testing) -- Change isDebugging Variable To True To Enable if game:GetFrameCount() == 1 and isDebugging then Isaac.DebugString("! Initializing Debug Items !") -- Spawn My Item Isaac.Spawn( EntityType.ENTITY_PICKUP, PickupVariant.PICKUP_COLLECTIBLE, MyMod.COLLECTIBLE_MY_ITEM, Vector(320, 300), Vector(0, 0), nil ) end end MyMod:AddCallback(ModCallbacks.MC_POST_PEFFECT_UPDATE, MyMod.onUpdate)
The overall structure of this code should be familiar to you having completed the cache callback code above. This creates a new
onUpdate function and then assigns it to the
MC_POST_PEFFECT_UPDATE callback which is executed every time the game updates (every frame).
For more information on the various mod callbacks that the Afterbirth+ API gives us, check out this article on modding callbacks.
Now, we don't want the item to be added every single frame so we add in a bit of logic to only add the item when both the game frame count is
1 (aka the beginning of the run) and the
isDebugging property is set to true.
This will only spawn the item as the game is beginning and gives us a mechanism to easily toggle it's availability for when we are debugging.
Testing Your Item
With the code we have written above we can now open the game and begin testing our item. If all goes well, the game will book up normally and you will be able to access the "Mods" menu item in the options and see your mod listed.
If the title of your mod is a red color, then it means that there is an error in your code. You will have to close the game and begin exploring the log files for the cause. We will be covering that next!
Go ahead and start a new run. When you spawn into the first room, your item should now be spawned in the middle of the room on item altar. You can pick it up and double check your item title and description and also ensure that the stats are properly being updated.
So, what happens if things go wrong? The easiest way to debug any problems is to take a look at the log file that the game generates.
// Windows C:\Users\YourName\My Games\Binding of Isaac Afterbirth+\log.txt // OSX ~/Library/Application Support/Binding of Isaac Afterbirth+/log.txt
I will personally open this via the command line by running
tail -f log.txt which will keep displaying any updates to the log file so I don't have to keep reopening the file to see what went wrong.
Of course, this is just a simple text file, so you can open it up in a text editor if that works better for you!
Once you have identified the issue, jump back into your code and patch things up. Once you have a solution in place, you have a couple options.
You could just reboot the game, but that can be quite time consuming. So, the developers have given us another option via the in-game console that will allow us to reload our mod while the game is running.
To access the console, type
` while in the game. This will bring up a command line where you can run various commands. The command that we are interested in is
To reload the mod, type
luamod followed by the directory name of your mod. In this case, it will be:
After running this command, it will provide you with a success or error message. If successful, press
Enter again to close the console and quickly jump back into the game.
I hope you've enjoyed this article and it has been insightful. I'm really quite pleased with the modding API after the initial learning curve. It definitely has some confusing turns and shortcomings but overall, it's a relatively easy way to get started and create your own mods for the game.