player Status Effects API Documentation

-- Creating your own 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"


-- Custom Functions

Here is a list of all the functions currently added by the API, alongside with what inputs they take, what values they return and, in general, how you can use them to make the best use of the API!
Notation:
FunctionName (arg1,arg2,arg3) -- function and its argumetns
	description of what the function does, whether (type of variable)arg1,(type of variable)arg2 and (type of variable)arg3 are optional, their default value if arg1 == nil and if they return (type of variable)anything.



_StatusAPI.CheckPlayerEffectList (player):
	A function that takes (EntityPlayer) player and makes sure all required tables on player:GetData() are set up properly. Returns true unless the entity was not a player, in which case, it returns false.
_StatusAPI.CheckPlayerEffectIconList (player)
	Does a similar job to _StatusAPI.CheckPlayerEffectList() , but sets up the arrays for the icons in (EntityPlayer) player:GetData().
_StatusAPI.CheckPlayerEffectPriorityList (player)
	Similarly to _StatusAPI.CheckPlayerEffectList(), takes (EntityPlayer) player and sets up its priority list table on player:GetData(). Is already called by _StatusAPI.GiveEffect()
_StatusAPI.GetEffectPriority (player,effect)
	A function that takes (EntityPlayer) player and (string) effect	 and returns an integer (from 1 to infinity) corresponding to the current place on the "priority list" for that effect. returns nil if effect is not being applied.
_StatusAPI.AddEffectToPriorityList (player,effect)
	Includes (string) effect to the priority list of (EntityPlayer) player, at its end. It is already called when using _StatusAPI.GiveEffect()
_StatusAPI.RemoveEffectFromPriorityList (player,effect)
	Removes (string) effect from (EntityPlayer) player 's priority list. Already called by _StatusAPI.RemoveEffect()
_StatusAPI.UpdateEffectPriorityList (player)
	Removes any nil value from the priority list of (EntityPlayer)player


_StatusAPI.GiveEffect (player,effect,amount,params(cumulative,addmaxcharge,setintensity,intesitymixing) )
	Applies (string)effect to (EntityPlayer)player for (float)amount. If amount == nil, then 150 will be the default. (table)params accepts the following arguments as named variables inside it: (boolean)cumulative indicates if amount should be added to any pre-existing value of said effect (if cumulative == true), or if the highest of both values should remain (cumulative == false). (boolean) addmaxcharge defines if the value should be added to the previous max charge or the highest of which should be the new one (basically, it's cumulative, but for charge). (float)setintensity Determines if you want to specify the "intensity" attribute of the effect, and has the default value of 1. (boolean)intensitymixing, if false or nil, makes the effect not be applied if its intensity value is lower than the effect's current intensity.
_StatusAPI.RemoveEffect (player,effect,amount)
	Removes (float)amount of time from (string)effect on (EntityPlayer)player. If amount == nil, removes the effect entirely from the player. If remaining time would be negative, also removes effect from player
_StatusAPI.SetEffect (player,effect,amount)
	Sets (string)effect 's time to (float)amount, on (EntityPlayer)player. If amount <= 0, then it removes the effect entirely.
_StatusAPI.HasEffect(player,effect)
	Returns true if (EntityPlayer)player has (string)effect, with a timer higher than 0. Returns false otherwise
_StatusAPI.GetEffectTimer(player,effect)
	returns (float) "time"/"timer" value for (string)effect on (EntityPlayer)player


_StatusAPI.SetEffectCharge (player,effect,amount)
	Sets the "Charge" value to a given (string)effect to (float)amount, on a (EntityPlayer)player. Returns true if player provided is indeed an EntityPlayer. Effect Charges are used to determine the chargebar values.
_StatusAPI.GiveEffectCharge (player,effect,amount,cumulative)
	If (boolean)cumulative == true, it adds (float)amount to (EntityPlayer)player's (string)effect charge. Otherwise, choses the highest value between the current and amount. Effect Charges are used to determine the maximum value for filling the chargebar.



_StatusAPI.GetNumEffects(player)
	Returns (integer) number of effects the player has at the current moment. Useful for tracking overlays and such
_StatusAPI.IsEffectActive(effect)
	returns true if any player has (string)effect. Useful for when an effect should apply to the entire game, or determine something globally.


-- Useful variables

If you are one of those rogue punks that don't want to have to rely on my custom functions for your schemes, here's a list of variables and things you can use to interfere with the effects

-Userdata tables
This subsection contains a list of tables and variables used by the mod. They can be accessed by using [EntityPlayer]:GetData().[tablename].

_StatusAPIPlayersEffect
Is a table with named elements, where the name is the name attributed to the effect. It's value, if not nil, is an unbound float that is the "timer" value for said effect.

_StatusAPIPlayersEffectPriority
Is an ordered table where the indices of the variants are integers starting at 1 (Lua's default number for starting tables). The values of the variants are strings corresponding to the name of the effect, and their index is the current order they have on the priority list. Using the order as the index made for an easier algorhythm for "moving the stack" as one effect wore off.

_StatusAPIPlayersEffectIcon
Is a table whose elements have the effect name as their index and are either nil or EntityEffect entities. They serve to render a display of the currently active effect and how long it'll last for

_StatusAPIPlayersEffectIntensity
Is a table with elements having the effect name as their index and are either nil or unbound floats, and determines the "intensity" attribute of said effect. Some effects are not affected by this value, but others use this to regulate how severely they'll impact the player.


- Global mod variables
These are variables intentionally made global by the mod. They are usually created to enable and facilitate other mods to check if this is properly loaded, tell this they are also loaded, and tell each other they have loaded, among what effects they're using and other similar parameters.
(In square brackets are the classes of each variable)

[Table] _StatusAPI
Holds all other global variables

[Table] _StatusAPI.EffectsList
Holds all declared effects. While an effect doesn't have to be declared in order to work, this allows easier customisation of said effect. For more information, please read "Creating your own effect"

[Boolean] _StatusAPI.LoadPresetEffects
Dictates whether the preset effects should be loaded or not, in order to improve performance. False by default. For more information, read "Using preset effects".

[Table] _StatusAPI.SaveData
Table saved using JSON on the mod's savedata savX.dat files.

[Table] _StatusAPI.SaveData.PlayerEffectRegistry
A table listing all effects that should be saved upon quitting the game. Indices of elements on this table are the effect names, and the elements themselves are tables with the following attributes: timer (the amount of time the effect should still run for); charge (the maximum value used as reference for the chargebar. Can also be used to determine the threshold value of said effect above which something is triggered, such as the player taking damage) ; intensity (the intensity attribute, determines, for some effects, the magnitude of the impact said effect has on the player)  .

[???] _StatusAPI.Json
The mod's instance of Json

All global functions are listed separately and are elements of _StatusAPI

[Table]_StatusAPI.ActiveMods
A table for mods to create their own variables in to inform other mods they're loaded.

[Boolean] _StatusAPI.ActiveMods.StatusEffectAPI
A variable that is set to true whenever the mod is loaded. Can be used to detect if the mod is properly loaded and should generally not be modified by other mods unless they run a copy of this mod in their internal code

[Boolean]_transformationsAPI.ActiveMods.StatusEffectAPI
Similar to the above. Used for full compatibility with the transformations API.


-- Using preset effects

While I heavily recommend you create your own effects, so you can adjust all details, values and whatnots, some of you may instead prefer to use some effects I preset myself. Originally, they were meant solely as an example for what you could do with the mod, but their potential use convinced me to expand upon their functionality.

-Enabling preset effects
First, for many performance and compatibility issues, all code for the presets needs to be enabled by adding the following line to your code before using any of the further functions:
 if _StatusAPI ~= nil then
  _StatusAPI = {}
 end
 _StatusAPI.LoadPresetEffects = true


- Effects List
Following, is a list of all effects I added and how each of them works:

Note: [intensity] is an attribute of an effect that, for some of them, reflects how much they'll impact the player. it'll also be mentioned in some functions. Note that, if you add the same effect under different intensities, the higher one will prevail.
[chargevalue] is a value used to determine, among other things, how much "timer" is required to fully fill the effct chargebar. It has also been used, in these effects, to denote the threshold for which some effects trigger (in poison and burning, for example, it is the value above which you take damage)

Burn:
Naturally increases by 1 (per update). Decreases by 3 each frame your movement speed is above 1. Upon reaching [chargevalue] (default 150 updates = 5 seconds), deals [intensity] half-hearts of damage and resets.

Poison:
Naturally decreases by 1 (per update). Upon reaching [chargevalue], deals [intensity] half-hearts of damage.

Slow:
Naturally decreases by 1 (per update). While in effect, reduces the player speed by 10% per [intesity] value.


Freeze:
Naturally decreases by 1. Isn't affected by [intensity]. While in effect, prevents the player from firing, walking, using items, bombs and consumables.

Fear:
Naturally decreases by 1 (per update). Isn't affected by [intensity.] While in effect, prevents the player from firing, using items or consumables.



Curse (may be removed):
Is not affected by [intensity]. Upon reaching a new floor, depletes 1 heart container per 2 curse value and replaces it with a black heart.



- Functions List

In addition to working with all normal functions from the mod (listed in another discussion thread), these effects have the following functions to apply themselves to the player. Note that all of them can be replicated by the default functions, but this is meant to simplify the process of using them, if you so choose, as they're targeted at less experienced programmers or people wanting to use simpler functionality instead of going through multiple steps involved in adding your own effect.

 _StatusAPI.AddPlayerBurn (player,duration,charge,intensity)
Adds burning to [player] for [duration], with a certain [intensity]. The default values for the arguments are as follows: [charge] = 150; [intensity] = 1; [duration] = 0; [player] = nil.


 _StatusAPI.AddPlayerPoison (player,duration,charge,intensity)
Adds poison to [player] for [duration], with a certain [intensity]. The default values for the arguments are as follows: [charge] = 150; [intensity] = 1; [duration] = 0; [player] = nil.


 _StatusAPI.AddPlayerSlow (player,duration,intensity,cumulative)
Adds burning to [player] for [duration], with a certain [intensity]. The default values for the arguments are as follows: [intensity] = 1; [duration] = 0; [player] = nil. If [cumulative] is set to true, it adds [duration] to any previous duration left.

 _StatusAPI.AddPlayerFreeze (player,duration,cumulative)
Adds burning to [player] for [duration], with a certain [intensity]. The default values for the arguments are as follows: [duration] = 0; [player] = nil. If [cumulative] is set to true, it adds [duration] to any previous duration left.

 _StatusAPI.AddPlayerFear (player,duration,cumulative)
Adds burning to [player] for [duration], with a certain [intensity]. The default values for the arguments are as follows: [duration] = 0; [player] = nil. If [cumulative] is set to true, it adds [duration] to any previous duration left.