Subscribe to download
StatAPI 2.0

Props to Oroshibu for the cool icon art! If you get any errors or bugs, report them in the comments below or start a new thread!

Modding support tool designed to fix some of the issues with the modding api's current limited stats system. If you decide to use it, a credit would be cool (albeit not necessary).

Currently, the only way that stats are able to be accessed and changed are after the game has fully constructed them - this means that you cant add changes to the tears stat, you have to mess with the fire delay. This is extremely limiting, and causes many modded items to fall outside the normal system of how the game does stats. Even haemolacria, which was added to the game, initially was coded to completely break the normal rules of the stat system in the game.

This is a tool designed to fix that issue with as minimal work on your part as possible.

The way it works is by deconstructing the stat given to the api based on every accessible detail and rule of the modding system to get back down to the base stat for any individual category. Once that is done, it rebuilds the stats in order, allowing modders to change the stats as they please. More accurate stats, better compatbility with other mods, and just a smoother experience for anyone looking to make stat changing content.


If you are a modder and want to know how to get this to work with your mod, the general idea is simple. You first either need to require the mod on the store page, or download the mod, grab statAPI.lua from its folder, and then pcall(require, "statAPI") that file at the top of your mod. Once that is done, you can access the global variable "stats" and use its functions in your code as you need. You can also do both if you desire, and doing so will allow you to not need any checks before using statAPI functions while letting the modded version automatically save and load necessary functions for its code.

If you don't want to have to require the mod on the workshop, then you will have to patch in a save/load function to allow the mod to save data about damage taken and d8 uses and such. If you don't do this step the mod will work fine mostly, but bloody lust and the d8 may cause buggy interactions with your mod.

To setup the save, use stats.GenerateSave() which will return a string of all the mod's data. If you need to, you can add any of your own mod's data on afterwards and save that string. When loading the data back, use stats.LoadSave(savedata) and it will load the data for the mod and return a string without any of the statapi's data attached to it, thus you dont have to change the rest of your saving code.

If you have no save/load code setup already, simply create a new function for saving which does the following:

function yourMod:Save()
local savedata = stats.GenerateSave()
yourMod:SaveData(savedata)
end

Add that to a post new level and pre game exit callback. Then add create another for loading as follows:

function yourMod:Load(fromSave)
if fromSave then
local savedata = yourMod:LoadData()
stats.LoadSave(savedata)
end
end

And add that to a post game started callback.

Now that you have the api setup and functional, how do you use it? Simple. There are two functions available to you - stats.AddCache() and stats.RemoveCache().


stats.AddCache(Mod, Function, CacheFlag, Stage, Name)

Mod is just the mod you want to register your function with - if you dont specifically care how it is registered, you can just use stats:AddCache instead and it will register it as a modless cache.

Function is the function you want to run - just the same way you would add it to a Callback.

CacheFlag is what flag you want it to run on. You can simple give nil and it will automatically use the cache flag for all, and thus always run like a normal cache callback would.

Stage is the stage you want this callback to run on. There are 4 stages in the normal stats lineup for Isaac - this allows you to specify which one you want. If left nil, it will run on all of them. (More details down below).

Name is the name you want to register this function under. Names do not have to be unique - the only purpose of a name is to remove functions once you have added them using the second function.

The callback will also give you the mod, player, and cacheflag like normal, however it will also give the current stage of the cache you are on in the fourth variable. This can be useful if you want a big function to run on multiple stages instead of splitting it up.


stats.RemoveCache(mod, name)

Mod is the mod, use a colon to default to no registered mod.

Name is the name of the function you want to remove. Any similarly named functions from the same mod will be removed.


There is also one enumeration available - StatStage.

StatStage.ALL - This will run on any stage.
StatStage.BASE - This is the first stage, applied to the base internal stat of the game (tears not firedelay). Note: On this stage, the tears stat is multiplied by 1000 in order to make it fit on the MaxFireDelay stat. To modify the tear delay, just modify that stat, but keep in mind it has to remain an integer.
StatStage.BREAK_MULTI - These are multipliers, such as Polyphemus or Character multipliers, which are applied before flat changes.
StatStage.FLAT - Flat changes to the stat, the cancer trinket for instance.
StatStage.MULTI - The last stage, multipliers which apply after everything else. Magic mush is one of these.


To use the stat api, figure out what stage you want your modifier to apply to, register the cache function with the mod (you can usually just use your already created cache callback), make appropriate changes to check for the proper stage, and boom, the Stats API will take care of everything else.

If you have any questions, feel free to leave a comment or create a discussion and I'll get back to you as soon as possible (usually within the day).