Skip to content

Enum "ModCallbacks"⚓︎

Execution order diagram: callback diagram

MC_NPC_UPDATE⚓︎

Called after an NPC is updated.

Returning any value will have no effect on later callback executions.

Warning

This callback will NOT fire when the NPC is playing the "Appear" animation. For example, when a Gaper spawns, it will fire on frame 1, then on frame 31 and onwards.

Example Code

This code will print "Hello World!" for every NPC Update.

1
2
3
4
function mod:myFunction(entity) -- 'entity' contains a reference to the NPC
    print("Hello World!")
end
mod:AddCallback(ModCallbacks.MC_NPC_UPDATE, mod.myFunction)

This function will only print "Gaper found", if the NPC is of the type "ENTITY_GAPER".

1
2
3
4
function mod:myFunction2(entity) -- 'entity' contains a reference to the NPC
    print("Gaper found!")
end
mod:AddCallback(ModCallbacks.MC_NPC_UPDATE, mod.myFunction2, EntityType.ENTITY_GAPER)

DLC Value Name Function Args Optional Args Return Type
0 MC_NPC_UPDATE (EntityNPC) EntityType void

MC_POST_UPDATE⚓︎

Called after every game update.

Returning any value will have no effect on later callback executions.

Execution informations

This callback is called 30 times per second. It will not be called, when its paused (for example on screentransitions or on the pause menu).

Example Code

This code will print "Hello World!" for every Game Update.

1
2
3
4
function mod:myFunction()
    print("Hello World!")
end
mod:AddCallback(ModCallbacks.MC_POST_UPDATE, mod.myFunction)

DLC Value Name Function Args Optional Args Return Type
1 MC_POST_UPDATE - - void

MC_POST_RENDER⚓︎

Called after every game render (60 times per second).

Returning any value will have no effect on later callback executions.

Execution informations

It is highly recommended to only use this function when you want to render something. Its not recommended to use this function for things which are not frequently used or need constant recalculation.

Example Code

This code will print "Hello World!" everytime the game renders.

1
2
3
4
function mod:myFunction()
    print("Hello World!")
end
mod:AddCallback(ModCallbacks.MC_POST_RENDER, mod.myFunction)

DLC Value Name Function Args Optional Args Return Type
2 MC_POST_RENDER - - void

MC_USE_ITEM⚓︎

Called when an active item is used, or when any item is passed through EntityPlayer.UseActiveItem.

The item RNG allows for the item's random events to be seeded.

Return true to show the "use item" animation, otherwise false.Returning any value will have no effect on later callback executions.

If a table is returned instead of a boolean, the following fields can be set to a non-nil value for extra functionality:

  • Discharge: Determines whether the item should be discharged or not after being used
  • Remove: Determines whether the item should be removed from the player or not after being used
  • ShowAnim: Plays the default use animation if set to true (equivalent to simply returning true in AB+)
Example Code

This code will print "Hello World!" everytime an active item is used.

1
2
3
4
function mod:myFunction(collectibleID, rngObj, playerWhoUsedItem, useFlags, activeSlot, varData)
    print("Hello World!")
end
mod:AddCallback(ModCallbacks.MC_USE_ITEM, mod.myFunction)

This code showcases how the return value can be used to alter the behavior of the item usage. Here, it will cause the item to not discharge, not be removed on use and not show the use animation.

1
2
3
4
5
6
7
8
function mod:myFunction2(collectibleID, rngObj, playerWhoUsedItem, useFlags, activeSlot, varData)
    return {
        Discharge = false,
        Remove = false,
        ShowAnim = false,
    }
end
mod:AddCallback(ModCallbacks.MC_USE_ITEM, mod.myFunction2)

This code will only print "D6 used!" when the D6 is used.

1
2
3
4
function mod:myFunction3(collectibleID, rngObj, playerWhoUsedItem, useFlags, activeSlot, varData)
    print("D6 used!")
end
mod:AddCallback(ModCallbacks.MC_USE_ITEM, mod.myFunction3, CollectibleType.COLLECTIBLE_D6)

DLC Value Name Function Args Optional Args Return Type
3 MC_USE_ITEM (CollectibleType,
RNG,
EntityPlayer,
UseFlags [int],
ActiveSlot,
CustomVarData [int])
CollectibleType boolean

MC_POST_PEFFECT_UPDATE⚓︎

Called for each player, each frame, after the player evaluates the effects of items that must be constantly evaluated.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
4 MC_POST_PEFFECT_UPDATE (EntityPlayer) PlayerType void

MC_USE_CARD⚓︎

Called when a card/rune is used.

Returning any value will have no effect on later callback executions.

Example Code

This code will print "Hello World!" everytime any card is used.

1
2
3
4
function mod:myFunction(cardID, playerWhoUsedItem, useFlags)
    print("Hello World!")
end
mod:AddCallback(ModCallbacks.MC_USE_CARD, mod.myFunction)

This code will only print "Fool card used!" when the Fool card is used.

1
2
3
4
function mod:myFunction2(cardID, playerWhoUsedItem, useFlags)
    print("Fool card used!")
end
mod:AddCallback(ModCallbacks.MC_USE_CARD, mod.myFunction2, Card.CARD_FOOL)

DLC Value Name Function Args Optional Args Return Type
5 MC_USE_CARD (Card,
EntityPlayer,
UseFlags [int]
Card void

MC_FAMILIAR_UPDATE⚓︎

Called every frame for each familiar.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
6 MC_FAMILIAR_UPDATE (EntityFamiliar) FamiliarVariant void

MC_FAMILIAR_INIT⚓︎

Called just after a familiar is initialized.

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_PEFFECT_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
7 MC_FAMILIAR_INIT (EntityFamiliar) FamiliarVariant void

MC_EVALUATE_CACHE⚓︎

Called one or more times when a player's stats are re-evaluated. For example, this will fire after the player picks up a collectible item that grants stats or uses a stat pill.

The optional parameter can be used to specify a CacheFlag. It must be a singular CacheFlag, a composition of two or more CacheFlags will not work.

Returning any value will have no effect on later callback executions.

Use this callback to implement anything that changse the player's stats, familiars, flying, weapons, and so on.

Custom collectibles and trinkets annotate which specific stats they affect with the "cache" tag in the "items.xml" file. For example, a custom passive collectible that increases tear rate and damage should have an "items.xml" entry with something along the lines of:

1
2
3
4
5
6
  <passive
    name="Foo"
    description="My cool item"
    gfx="foo.png"
    cache="damage firedelay"
  />

With this entry, the MC_EVALUATE_CACHE callback will fire twice when Foo item is picked up by the player, once with CacheFlag.CACHE_DAMAGE, and once with CacheFlag.CACHE_FIREDELAY.

The stats for vanilla items and effects are applied before the callback is fired for any modded effects.

You can force this callback to fire in other callbacks by 1) manually adding the appropriate cache flags to the player, and 2) calling the EntityPlayer.EvaluateItems method. For example:

1
2
3
4
5
-- My custom item changes the player's damage on every frame
function barPostPEffectUpdate(player)
  player:AddCacheFlags(CacheFlag.CACHE_DAMAGE)
  player:EvaluateItems() -- The "MC_EVALUATE_CACHE" callback will now fire.
end

Note that the value passed to the callback will always be an exact value of the CacheFlag enum. It is never a composition of two or more CacheFlags. Thus, you should always use normal equality instead of bitwise operators when comparing the cache flag.

DLC Value Name Function Args Optional Args Return Type
8 MC_EVALUATE_CACHE (EntityPlayer,
CacheFlag)
CacheFlag void

MC_POST_PLAYER_INIT⚓︎

Called after a Player Entity is initialized.

The optional parameter can be used to specify a Player Variant. 0 = Player, 1 = Co-Op-Baby

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_PEFFECT_UPDATE and check those attributes on the first possible frame.

Conditional Behaviour

This callback causes many EntityPlayer methods to silently fail if the methods are called while continuing a saved run. This behavior was intentionally added by Kilburn in the Repentance DLC in order to make it easier for modders to add starting items to custom characters. (This behavior obviaties the need for modders to use filtration logic to distinguish between the cases of a new run/Genesis use/co-op spawn and a continued run.)

The following EntityPlayer methods are known to fail:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
AddCollectible
AddTrinket
AddKeys
AddCoins
AddBombs
AddGoldenBomb
AddGoldenKey
AddGigaBombs
AddMaxHearts
AddHearts
AddBlackHearts
AddSoulHearts
AddRottenHearts
AddBoneHearts
AddGoldenHearts
AddEternalHearts
AddBrokenHearts
AddCard
AddPill
AddPrettyFly
AddJarFlies
AddJarHearts
AddSoulCharge
AddBloodCharge
AddPoopMana
SetPocketActiveItem

The following EntityPlayer methods have been verified to continue firing:

1
2
3
4
5
6
AddBlueFlies
AddBlueSpider
AddWisp
AddItemWisp
AddSwarmFlyOrbital
AddFriendlyDip
DLC Value Name Function Args Optional Args Return Type
9 MC_POST_PLAYER_INIT (EntityPlayer) PlayerVariant* void

MC_USE_PILL⚓︎

Called when a pill is used.

Returning any value will have no effect on later callback executions.

Example Code

This code will print "Hello World!" everytime any pill is used.

1
2
3
4
function mod:myFunction(pillEffectID, playerWhoUsedItem, useFlags)
    print("Hello World!")
end
mod:AddCallback(ModCallbacks.MC_USE_PILL, mod.myFunction)

This code will only print "Bad Gas Pill used!" when the Fool pill is used.

1
2
3
4
function mod:myFunction2(pillEffectID, playerWhoUsedItem, useFlags)
    print("Bad Gas Pill used!")
end
mod:AddCallback(ModCallbacks.MC_USE_PILL, mod.myFunction2, PillEffect.PILLEFFECT_BAD_GAS)

DLC Value Name Function Args Optional Args Return Type
10 MC_USE_PILL (PillEffect,
EntityPlayer,
UseFlags [int])
PillEffect void

MC_ENTITY_TAKE_DMG⚓︎

Called before new damage is applied.

If the entity has a DAMAGE_COUNTDOWN flag, it will ignore any other DAMAGE_COUNTDOWN hits for the duration specified.

Return true or nil if the entity or player should sustain the damage, otherwise false to ignore it. If the entity is an EntityPlayer, the DamageAmount is the integer number of half-hearts of damage that the player will take. Otherwise, DamageAmount is a number of hit points.

Bug

Returning any value besides nil will prevent later callbacks from being executed.

DLC Value Name Function Args Optional Args Return Type
11 MC_ENTITY_TAKE_DMG (Entity [Entity],
Amount [float],
DamageFlags [int],
Source [EntityRef],
CountdownFrames [int])
EntityType boolean

MC_POST_CURSE_EVAL⚓︎

Curses is a bitmask containing current curses. Called after the current Level applied it's curses. Returns the new curse bitmask. Use Isaac.GetCurseIdByName() to get the curseID.

If a number is returned, it will be the "Curses" arg for later executed callbacks.

Bug

Returning a value that is not an integer or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

DLC Value Name Function Args Optional Args Return Type
12 MC_POST_CURSE_EVAL (Curses [int]) - int

MC_INPUT_ACTION⚓︎

This callback fires every time the game polls for a ButtonAction input, often several times per frame even for the same action. Since it has to do with polling, it fires regardless of whether or not the player is actually pressing any particular input.

This callback is used to arbitrarily change inputs. For example, you can completely disable the player from pressing a certain button. Or, you can force the player to press a specific button, and so on. If all you want to do is read if an input is pressed or not, then you should not use this callback, and instead use the Input.IsActionTriggered method in the MC_POST_RENDER callback.

  • Entity - The entity that is requesting the input. Most of the time this will be a player. However, it can also be nil if the input is not read from an entity class, or an entity being controlled by Friend Finder.
  • InputHook - This determines the kind of input that is being polled. This corresponds to the Input.IsActionTriggered, Input.IsActionPressed, and Input.GetActionValue methods, which trigger this callback.

Return nil if you do not want to overwrite the input. If you do want to overwrite the input, then you have to return a boolean for the IS_ACTION_PRESSED (0) and IS_ACTION_TRIGGERED (1) input hooks, or a float between 0.0 and 1.0 for the GET_ACTION_VALUE (2) input hook.

Returning any value will have no effect on later callback executions.

Execution information

This callback is called roughly 1470 times a second.

DLC Value Name Function Args Optional Args Return Type
13 MC_INPUT_ACTION (Entity,
InputHook,
ButtonAction)
InputHook boolean or float

MC_LEVEL_GENERATOR⚓︎

Bug

This callback doesn't work right now and will never be called by the game!

DLC Value Name Function Args Optional Args Return Type
14 MC_LEVEL_GENERATOR - - void

MC_POST_GAME_STARTED⚓︎

This function gets called when you start a game. The boolean value is true when you continue a run, false when you start a new one.

This callback will be called after MC_POST_NEW_ROOM and after MC_POST_NEW_LEVEL.

Returning any value will have no effect on later callback executions.

Example code
1
2
3
4
local function onStart(_,bool)
    print(bool)
end
mod:AddCallback(ModCallbacks.MC_POST_GAME_STARTED, onStart)
DLC Value Name Function Args Optional Args Return Type
15 MC_POST_GAME_STARTED (IsContinued [bool]) - void

MC_POST_GAME_END⚓︎

This function gets called when the game over screen appears, or when the an ending starts playing. The boolean value is true when you died and got a game over, false when you won and got an ending.

Returning any value will have no effect on later callback executions.

Example code
1
2
3
4
local function onEnd(_,bool)
    print(bool)
end
mod:AddCallback(ModCallbacks.MC_POST_GAME_END, onEnd)
DLC Value Name Function Args Optional Args Return Type
16 MC_POST_GAME_END (IsGameOver [bool]) - void

MC_PRE_GAME_EXIT⚓︎

This function gets called when you quit a run. The boolean value is true when the game would normally create a continuable save, false when it wouldn't. Called twice when the game plays an ending.

Returning any value will have no effect on later callback executions.

Example code
1
2
3
4
local function onExit(_,bool)
    print(bool)
end
mod:AddCallback(ModCallbacks.MC_PRE_GAME_EXIT, onExit)
DLC Value Name Function Args Optional Args Return Type
17 MC_PRE_GAME_EXIT (ShouldSave [bool]) - void

MC_POST_NEW_LEVEL⚓︎

This triggers after transitioning a level or stage.

Unintuitively, it is always called after MC_POST_NEW_ROOM.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
18 MC_POST_NEW_LEVEL - - void

MC_POST_NEW_ROOM⚓︎

This triggers after entering a room.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
19 MC_POST_NEW_ROOM - - void

MC_GET_CARD⚓︎

This callback is used for handling Card Pools.

Because not all cards have the same chance to spawn, use RNG for a seeded random selection.

You can use the boolean values as a filter for the selection.

The return value determines, what Card will be spawned. Return nil to not replace the spawned card.

Returned values will not update the "Card" arg of later executed callbacks.

Bug

Returning a value that is not an integer or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

DLC Value Name Function Args Optional Args Return Type
20 MC_GET_CARD (RNG,
Card,
IncludePlayingCards [bool],
IncludeRunes [bool],
OnlyRunes [bool])
- Card

MC_GET_SHADER_PARAMS⚓︎

Returns a table containing a key -> value pair for custom shader parameters.

Will skip remaining callbacks when returning a table.

DLC Value Name Function Args Optional Args Return Type
21 MC_GET_SHADER_PARAMS (ShaderName [string]) - table

MC_EXECUTE_CMD⚓︎

Returns a string separated by <br /> (newline) per output line CMD is the first word of the Console input.

The parameters are the rest of the Input.

Important

This function is NOT called for default game commands like Spawn or Debug.

Returning a string will print it to the console.

Returning any value will have no effect on later callback executions.

Bug

Returning any value beside nil will cause the game to crash, including a string.

Example code
1
2
3
4
5
6
7
8
function mod.oncmd(_, command, args)
    print(command)
    print(args)
end
mod:AddCallback(ModCallbacks.MC_EXECUTE_CMD, mod.oncmd)
-- executing command "Test apple 1 Pear test" prints
-- Test
-- apple 1 Pear test
DLC Value Name Function Args Optional Args Return Type
22 MC_EXECUTE_CMD (CMD [string],
Parameters [string])
- string

MC_PRE_USE_ITEM⚓︎

Called before an item is used.

Return true to prevent the default code of an item to be triggered. This will still discharge the item.

Bug

Returning any value besides nil will also prevent later callbacks from being executed.

DLC Value Name Function Args Optional Args Return Type
23 MC_PRE_USE_ITEM (CollectibleType,
RNG,
EntityPlayer,
UseFlags [int],
ActiveSlot,
CustomVarData [int])
CollectibleType boolean

MC_PRE_ENTITY_SPAWN⚓︎

Called right before an entity is spawned.

Optional: Return a table with new values { Type, Variant, Subtype, Seed } to override these values of the spawned entity.

If you want to prevent an entity from spawning, you cannot return an EntityType of 0, since that will cause the game to crash.

Sometimes, if you return a type other than the original type (e.g. replacing a pickup with an effect), the game will crash. Thus, you should replace a pickup with a new pickup, and so on.

Bug

Returning a value that is not a table or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

DLC Value Name Function Args Optional Args Return Type
24 MC_PRE_ENTITY_SPAWN (EntityType,
Variant [int],
SubType [int],
Position [Vector],
Velocity [Vector],
Spawner [Entity],
Seed [int])
- table

MC_POST_FAMILIAR_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
25 MC_POST_FAMILIAR_RENDER (EntityFamiliar,
RenderOffset [Vector])
FamiliarVariant void

MC_PRE_FAMILIAR_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
26 MC_PRE_FAMILIAR_COLLISION (EntityFamiliar,
Collider [Entity],
Low [bool])
FamiliarVariant boolean

MC_POST_NPC_INIT⚓︎

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_NPC_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
27 MC_POST_NPC_INIT (EntityNPC) EntityType void

MC_POST_NPC_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
28 MC_POST_NPC_RENDER (EntityNPC,
RenderOffset [Vector])
EntityType void

MC_POST_NPC_DEATH⚓︎

Gets called after the Death animation is played.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
29 MC_POST_NPC_DEATH (EntityNPC) EntityType void

MC_PRE_NPC_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
30 MC_PRE_NPC_COLLISION (EntityNPC,
Collider [Entity],
Low [bool])
EntityType boolean

MC_POST_PLAYER_UPDATE⚓︎

The optional parameter can be used to specify a Player Variant. 0 = Player, 1 = Co-Op-Baby

Returning any value will have no effect on later callback executions.

Execution informations

This callback is called 60 times per second

DLC Value Name Function Args Optional Args Return Type
31 MC_POST_PLAYER_UPDATE (EntityPlayer) PlayerVariant* void

MC_POST_PLAYER_RENDER⚓︎

The optional parameter can be used to specify a Player Variant. 0 = Player, 1 = Co-Op-Baby

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
32 MC_POST_PLAYER_RENDER (EntityPlayer,
RenderOffset [Vector])
PlayerVariant* void

MC_PRE_PLAYER_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

The optional parameter can be used to specify a Player Variant. 0 = Player, 1 = Co-Op-Baby

DLC Value Name Function Args Optional Args Return Type
33 MC_PRE_PLAYER_COLLISION (EntityPlayer,
Collider [Entity],
Low [bool])
PlayerVariant* boolean

MC_POST_PICKUP_INIT⚓︎

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_PICKUP_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
34 MC_POST_PICKUP_INIT (EntityPickup) PickupVariant void

MC_POST_PICKUP_UPDATE⚓︎

Returning any value will have no effect on later callback executions.

Execution informations

This callback will be called on the 1st frame that the entity exists. It will only be called on the 0th frame, when you enter a room that already contains a spawned pickup.

DLC Value Name Function Args Optional Args Return Type
35 MC_POST_PICKUP_UPDATE (EntityPickup) PickupVariant void

MC_POST_PICKUP_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
36 MC_POST_PICKUP_RENDER (EntityPickup,
RenderOffset [Vector])
PickupVariant void

MC_POST_PICKUP_SELECTION⚓︎

Called after a Pickup was choosen from a list of random pickups to be spawned.Return nil to continue with default game code.

Return a table { Variant, Subtype } to override the specified values. This does also affect later executed callbacks.

Bug

Returning a value that is not a table or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

Bug

EntityPickup does contain the Type/variant of the pickup to spawn, but is otherwise an empty class with empty / zeroed values.

This Callback is also called when entering a room that contains pickups that are already selected. It is also called when the player drops a card. Those facts make this callback useless to use for handling pickup pools.

DLC Value Name Function Args Optional Args Return Type
37 MC_POST_PICKUP_SELECTION (EntityPickup,
Variant [int],
Subtype [int])
- table

MC_PRE_PICKUP_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
38 MC_PRE_PICKUP_COLLISION (EntityPickup,
Collider [Entity],
Low [bool])
PickupVariant boolean

MC_POST_TEAR_INIT⚓︎

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_TEAR_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
39 MC_POST_TEAR_INIT (EntityTear) TearVariant void

MC_POST_TEAR_UPDATE⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
40 MC_POST_TEAR_UPDATE (EntityTear) TearVariant void

MC_POST_TEAR_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
41 MC_POST_TEAR_RENDER (EntityTear,
RenderOffset [Vector])
TearVariant void

MC_PRE_TEAR_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
42 MC_PRE_TEAR_COLLISION (EntityTear,
Collider [Entity],
Low [bool])
TearVariant boolean

MC_POST_PROJECTILE_INIT⚓︎

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_PROJECTILE_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
43 MC_POST_PROJECTILE_INIT (EntityProjectile) ProjectileVariant void

MC_POST_PROJECTILE_UPDATE⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
44 MC_POST_PROJECTILE_UPDATE (EntityProjectile) ProjectileVariant void

MC_POST_PROJECTILE_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
45 MC_POST_PROJECTILE_RENDER (EntityProjectile,
RenderOffset [Vector])
ProjectileVariant void

MC_PRE_PROJECTILE_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
46 MC_PRE_PROJECTILE_COLLISION (EntityProjectile,
Collider [Entity],
Low [bool])
ProjectileVariant boolean

MC_POST_LASER_INIT⚓︎

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_LASER_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
47 MC_POST_LASER_INIT (EntityLaser) LaserVariant void

MC_POST_LASER_UPDATE⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
48 MC_POST_LASER_UPDATE (EntityLaser) LaserVariant void

MC_POST_LASER_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
49 MC_POST_LASER_RENDER (EntityLaser,
RenderOffset [Vector])
LaserVariant void

MC_POST_KNIFE_INIT⚓︎

Returning any value will have no effect on later callback executions.

Note

The optional parameter is a SubType and NOT a Variant!

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_KNIFE_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
50 MC_POST_KNIFE_INIT (EntityKnife) KnifeSubType * void

MC_POST_KNIFE_UPDATE⚓︎

Returning any value will have no effect on later callback executions.

Note

The optional parameter is a SubType and NOT a Variant!

DLC Value Name Function Args Optional Args Return Type
51 MC_POST_KNIFE_UPDATE (EntityKnife) KnifeSubType * void

MC_POST_KNIFE_RENDER⚓︎

Returning any value will have no effect on later callback executions.

Note

The optional parameter is a SubType and NOT a Variant!

DLC Value Name Function Args Optional Args Return Type
52 MC_POST_KNIFE_RENDER (EntityKnife,
RenderOffset [Vector])
KnifeSubType * void

MC_PRE_KNIFE_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

Note

The optional parameter is a SubType and NOT a Variant!

DLC Value Name Function Args Optional Args Return Type
53 MC_PRE_KNIFE_COLLISION (EntityKnife,
Collider [Entity],
Low [bool])
KnifeSubType * boolean

MC_POST_EFFECT_INIT⚓︎

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_EFFECT_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
54 MC_POST_EFFECT_INIT (EntityEffect) EffectVariant void

MC_POST_EFFECT_UPDATE⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
55 MC_POST_EFFECT_UPDATE (EntityEffect) EffectVariant void

MC_POST_EFFECT_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
56 MC_POST_EFFECT_RENDER (EntityEffect,
RenderOffset [Vector])
EffectVariant void

MC_POST_BOMB_INIT⚓︎

Returning any value will have no effect on later callback executions.

Warning

Accessing the initialized entity does provide incomplete data in some use cases. Only Position, Velocity, SpawnerType, SpawnerVariant, SpawnerEntity and some others are set before PostInit callbacks are called and are therefore accessible. Some other attributes (i.e. effect attributes or tear flags) will not be set. If you want to access those values, you need to hook into MC_POST_BOMB_UPDATE and check those attributes on the first possible frame.

DLC Value Name Function Args Optional Args Return Type
57 MC_POST_BOMB_INIT (EntityBomb) BombVariant void

MC_POST_BOMB_UPDATE⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
58 MC_POST_BOMB_UPDATE (EntityBomb) BombVariant void

MC_POST_BOMB_RENDER⚓︎

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
59 MC_POST_BOMB_RENDER (EntityBomb,
Offset [Vector])
BombVariant void

MC_PRE_BOMB_COLLISION⚓︎

The Low value is true, when the entity collided with the collider first. Its false if the collider collides first.

Return true to ignore collision, false to collide but not execute internal code and nil to continue with internal code (example: taking damage on contact). Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
60 MC_PRE_BOMB_COLLISION (EntityBomb,
Collider [Entity],
Low [bool])
BombVariant boolean

MC_POST_FIRE_TEAR⚓︎

Called when the player fires a tear.

It is not called for other weapons or tears fired with Incubus.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
61 MC_POST_FIRE_TEAR (EntityTear) - void

MC_PRE_GET_COLLECTIBLE⚓︎

This callback is called when the game needs to get a new random item from an item pool.

You can return an integer from this callback in order to change the returned collectible type.

It is not called for "scripted" drops (like Mr. Boom from Wrath) and manually spawned items.

Returned values will not alter args of later executed callbacks.

Bug

Returning a value that is not a table or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

DLC Value Name Function Args Optional Args Return Type
62 MC_PRE_GET_COLLECTIBLE (ItemPoolType,
Decrease [bool],
Seed [int])
- int

MC_POST_GET_COLLECTIBLE⚓︎

This function is called right after MC_PRE_GET_COLLECTIBLE and determines the Collectible that will be spawned from the given ItemPoolType.

You can return an integer from this callback in order to change the returned collectible type.

Returned values will not update the "SelectedCollectible" arg of later executed callbacks.

Bug

Returning a value that is not a table or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

DLC Value Name Function Args Optional Args Return Type
63 MC_POST_GET_COLLECTIBLE (SelectedCollectible [CollectibleType],
ItemPoolType,
Decrease [bool],
Seed [int])
- table

MC_GET_PILL_COLOR⚓︎

This function is called, when the game is spawning a pill and needs to determine its PillColor.

Return a PillColor to specify a Pillcolor that needs to be choosen. Return nothing to let it be handled by the game.

Returned values will not alter the args of later executed callbacks.

Bug

Returning a value that is not a table or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

DLC Value Name Function Args Optional Args Return Type
64 MC_GET_PILL_COLOR (Seed [int]) - PillColor

MC_GET_PILL_EFFECT⚓︎

Called every frames when the game get the PillEffect of a pill. The effect of the pill can be choosed by returning the chosen PillEffect.

The effect is applied to every pill of the same PillColor, not to a single pill.

Returned values will not update the "SelectedPillEffect" arg of later executed callbacks.

Bug

Returning a value that is not a table or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

Example code

This code turn "Bad Trip" pills into "Balls of Steel" pills.

1
2
3
4
5
6
function mod:getPillEffect(pillEffect, pillColor)
    if pillEffect == PillEffect.PILLEFFECT_BAD_TRIP then
    return PillEffect.PILLEFFECT_BALLS_OF_STEEL
    end
end
mod:AddCallback(ModCallbacks.MC_GET_PILL_EFFECT, mod.getPillEffect)

DLC Value Name Function Args Optional Args Return Type
65 MC_GET_PILL_EFFECT (SelectedPillEffect [PillEffect],
PillColor)
- table

MC_GET_TRINKET⚓︎

Called when a TrinketType of a Trinket needs to be determined.

A TrinketType can be returned to change the SelectedTrinket.

Returned values will not update the "SelectedTrinket" arg of later executed callbacks.

Bug

Returning a value that is not a table or nil will cause the game to crash.

Warning

The last callback to return a valid return value wins out and overwrites previous callbacks' return values

DLC Value Name Function Args Optional Args Return Type
66 MC_GET_TRINKET (SelectedTrinket [TrinketType],
RNG)
- table

MC_POST_ENTITY_REMOVE⚓︎

Called whenever an Entity gets removed by the game. This includes deaths, kills, removals and even unloading an entity on room transition or ending a run.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
67 MC_POST_ENTITY_REMOVE (Entity) EntityType void

MC_POST_ENTITY_KILL⚓︎

Called right before a death animation is triggered for an Entity.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
68 MC_POST_ENTITY_KILL (Entity) EntityType void

MC_PRE_NPC_UPDATE⚓︎

Return true if the internal AI of an NPC should be ignored, nil/nothing otherwise. Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
69 MC_PRE_NPC_UPDATE (EntityNPC) EntityType boolean

MC_PRE_SPAWN_CLEAN_AWARD⚓︎

This function is triggered in every room that can be cleared, including boss and angel rooms, and even when it normally would not spawn a reward.

This Callback also handles special spawns like the spawning of Trapdoors after a boss is killed, therefore returning true here will also cancel those events.

Return true if the spawn routine should be ignored, nil/nothing otherwise. Returning any non-nil value will skip remaining callbacks.

DLC Value Name Function Args Optional Args Return Type
70 MC_PRE_SPAWN_CLEAN_AWARD (RNG,
SpawnPosition [Vector])
- boolean

MC_PRE_ROOM_ENTITY_SPAWN⚓︎

This is called when entering a new room, before spawning entities which are part of its layout. Grid entities will also trigger this callback and their type will the same as the type used by the gridspawn command. Because of this, effects are assigned the type 999 instead of 1000 in this callback.

Optional: Return a table with new values { Type, Variant, Subtype }. Returning such a table will override any replacements that might naturally occur i.e. enemy variants.

Returning any value will have no effect on later callback executions.

DLC Value Name Function Args Optional Args Return Type
71 MC_PRE_ROOM_ENTITY_SPAWN (EntityType,
Variant [int],
SubType [int],
GridIndex [int],
Seed [int])
- table

MC_PRE_ENTITY_DEVOLVE⚓︎

This is called when an entity is devolved through D10 or similar.

Returns true if the internal devolving behavior should be ignored - When returning true, this callback is responsible for spawning the devolved entity and removing the original one.

DLC Value Name Function Args Optional Args Return Type
72 MC_PRE_ENTITY_DEVOLVE (Entity) - boolean

MC_PRE_MOD_UNLOAD⚓︎

This is called right before any mod is unloaded (when disabling a mod or reloading it using luamod), the mod's table is passed as an argument

DLC Value Name Function Args Optional Args Return Type
73 MC_PRE_MOD_UNLOAD table Mod - void

Last update: March 13, 2023