The Binding of Isaac: Rebirth

The Binding of Isaac: Rebirth

Player Status Effects API
 This topic has been pinned, so it's probably important
pedroff_1  [developer] 11 May, 2020 @ 7:54pm
Setting up an effect
Creating your own effect is fairly easy, but it involves defining a few different parameters. I believe this is not essential for your effect to work, but this can make things much easier to change in the future, so I highly recommend you do so.
First, you must make sure the array to store your effect already exists. To do so, put the following at the beginning of your code:

if _StatusAPI == nil then _StatusAPI = {} end

if _StatusAPI.EffectsList == nil then _StatusAPI.EffectsList = {} end
Skip any parts you had already added before, if any.

Then, you need to create an element in the table _StatusAPI.EffectsList for each effect you want to add. this element is another table, with some (or all) of the attributes below:
_StatusAPI.EffectsList.Slow = {name = "Slow", type = "Increasing", changeby = 1, icon = {animpath = "gfx/statuseffects.anm2",animation = "Slow", mode = "charge",spritesheetpath = nil,chargeanimation = "Charge",chargespritesheetpath = nil,chargeranimationlength = 29,renderoffset = Vector(0,-70),smartoffset = Vector(0,-30)}}

As you see, there are many elements, but don't be discouraged by it. Not all of them are required, depending on what you want. Listed below is the current list of attritubtes, what values they can be given, and what they do:

-name: Optional. Determines the name used to reference the effect in the rest of the code. If nil, will use the name given to the array that is the effect. If that is also nil, will assign it a number value or something
-type: For now, there are three types: "increasing", "decreasing" and others. "increasing" ones will have their value increased as time passes, at the default rate of 1 per update. "decreasing" does the opposite, vanishing when reaching 0. Any other name (including nil) will make the value stationary, only changing if you manually program it to do so.
-changeby: if nil, 1 by default. The amount by which it increases or decreases, for now. May have other uses for future non-linear types.
-icon: Array with parameters for rendering an icon above Isaac's head. If nil, no icon is rendered. If not nil, may have the following parameters:
*mode: string detailing the type of animation to be run. For now, can be either "loop" or "charge". "charge" means you intend to work with chargebars, to indicate the maximum value this effect can reach. In the "example.lua" file, I use it to indicate when burning or poison are going to inflict damage. "loop" is for icons that simply loop over an animation, and was the first type of icon to be introduced due to being the simplest
*animpath: Optional. The path to the .anm2 file for the icon. By default, is "gfx/statuseffects.anm2"
*spritesheetpath: Optional. The path to the .png for the icon you want to display. Will replace the layer 0 of your animation, if not nil.
*animation: The name of the animation inside the .anm2 to be played in a loop
*renderoffset: Optoonal. a "world" vector (distance is equivalent to in-game distance, not on-screen one) that is added to the player position to determine where the icon will be rendered. (0,0) by default.
*smartoffset: Optional. a vector that gets multiplied by how many other effects you had before this one, used to determine the icon's placement as to not overlap with others
*chargespritesheetpath: Optional. Only compatible with the "charge" mode. If using a different spritesheet than that of the animation for the chragebar, specify its path here.
*chargeanimation: Optional. Only compatible with "charge" mode. define the animation name for the spritesheet overlay. If not specified, "Charge" will be used by default.
*chargeranimationlength: Optional. Only compatible with "charge" mode. Set the length of the cahrgebar animation, to allow scaling of the meter according to the effect timer. Set to 30 by default



After you've defined all the attributes you want, your effect will be ready for use. For more information, please refer to "Custom Functions"