Callback

Callbacks allow you to execute a batch of code at certain points of the game. Such as when you're healed, when you're taking damage, or when you've moved.

Callbacks can be used in Talents, Timed Effects, or Items. Callbacks only happen if;

An Actor has the Talent learnt, if its an Active or Passive.

An Actor has the Talent sustained, if its a Sustain.

An Actor has the Timed Effect on them.

An Actor has the item equipped.

To use a Callback, simply insert one into your talent, timed effect, or item like you would any function.

If the Callback has additional arguments, add them onto the end, after your first two arguments.

Talent callbacks use (self, t)

Timed Effect callbacks use (self, eff)

Item callbacks use (self, who)

In the case of Item callbacks, 'self' refers to the item itself, while 'who' refers to the actor wearing said item.

Provided below is a simple example of a Talent callback.

          e.g.     callbackOnMeleeAttack = function(self, t, target, hitted, crit, weapon, damtype, mult, dam) 
                         if hitted and crit then
                              self:heal(dam/2) 
                         end
                     end,

The result of this particular callback is that you would heal yourself for half the damage dealt every time you land a melee attack that crits. You could use the same callback in an effect by replacing 't' (which represents the talent making the call) with 'eff' (which represents the effect making the call).

However, converting this into an Item callback is slightly more tricky. First you must change 't' to 'who' (which is the actor wearing the item). You would than need to change all references to 'self' in the code to 'who' to achive the same effect, as 'self' now refers to the item this callback is attached to.

                     callbackOnMeleeAttack = function(self, who, target, hitted, crit, weapon, damtype, mult, dam) 
                         if hitted and crit then
                              who:heal(dam/2) 
                         end
                     end,

List of callbacks in 1.2.5:

Actor.lua

-- Called once per global turn.

callbackOnActBase()

-- Called whenever an Actor begins their turn.

callbackOnAct()

-- Called whenever an Actor moves.

callbackOnMove(moved, force, ox, oy, x, y)

moved(was a move completed? this can be tricky; we may technically 'move' and still be in the same spot)

force(did somebody force us to move?)

ox, oy(our starting location)

x, y(where we moved to, or tried to move to (i.e. if we bump into a wall this will be the x and y of the wall)

• Note* If you want the callback to check if the actor actually moved from one tile to another, make sure you include an if statement that compares the starting location (ox and oy) to the actor's location (self.x and self.y).

Something like: ...if not (self.x == ox and self.y == oy) then...

-- Called whenever an Actor is healed.

callbackOnHeal(value, src)

value(amount healed)

src(source of the healing)

-- Called whenever an Actor takes damage. This happens at the end of onTakeHit, and right before the damage is actually dealt.

callbackOnHit(cb, src, death_note)

Special note: This passes along the damage dealt under cb.value. Make any changes you want to cb.value, than return cb, if you wish to change the damage dealt.

src(source of the damage)

death_note()

-- Called whenever an Actor deals damage.

callbackOnDealDamage(val, target, dead, death_note)

val(damage dealt)

target(who you're hitting)

dead(did the attack kill your target?)

death_note()

-- Called whenever an Actor dies.

callbackOnDeath(src, death_note)

src(who killed us?)

death_note()

-- Called whenever a Summon of an Actor dies.

callbackOnSummonDeath(summon, src, death_note)

summon(our summon)

src(who killed our summon?)

death_note()

-- Called whenever an Actor kills something.

callbackOnKill(src, death_note)

src(who we killed)

death_note()

-- Called whenever an Actor has a stat changed.

callbackOnStatChange(stat, v)

stat(the stat that was changed)

v(the value of the change)

-- Called whenever an Actor wears something.

callbackOnWear(o, bypass_set)

o(the object worn)

bypass_set()

-- Called whenever an Actor takes something off.

callbackOnTakeoff(o, bypass_set)

o(the object removed)

bypass_set()

-- Called whenever a magical or natural talent fails to activate.

callbackOnTalentDisturbed(ab)

ab(the talent that failed)

-- Called after a talent is used.

callbackOnTalentPost(ab, ret, silent)

ab(the talent that was used)

ret(whatever the talent returned)

Special note: Unless we are a sustain, we will fail if our talent returns anything but true.

silent()

-- Called whenever a sustain deactivates due to talent usage.

callbackBreakOnTalent(ab)

ab(the talent that was deactivated)

-- Called whenever a temporary effect tries to be applied.

callbackOnTemporaryEffect(eff_id, e, p)

eff_id(the effect id)

e(the base effect info, as shown in its timed_effect file)

p(the effect being applied, such as duration)

Archery.lua

-- Called whenever an archery attack hits us.

callbackOnArcheryHit(dam, src)

(dam, damage dealt. src, who hit us?)

-- Called whenever an archery attack misses us.

callbackOnArcheryMiss(src)

src(who failed to hit us?)

-- Called whenever an archery attack happens.

callbackOnArcheryAttack(target, hitted, crit, weapon, ammo, damtype, mult, dam)

target(who is being hit?)

hitted(did we hit?)

crit(did we crit?)

weapon(our weapon)

ammo(our ammo)

damtype(what type of damage did we do?)

mult(our damage multiplier)

dam(the damage dealt)

Combat.lua

-- Called whenever an enemy hits us with a melee attack.

callbackOnMeleeHit(target, dam)

Special note: target in this case is the enemy making the attack, not the attack's target (which would be you).

dam( damage dealt by the attack)

-- Called whenever an enemy misses us with a melee attack.

callbackOnMeleeMiss(target, dam)

Special note: target in this case is the enemy making the attack, not the attack's target (which would be you).

dam(our damage dealt)

-- Called whenever a melee attack happens.

callbackOnMeleeAttack(target, hitted, crit, weapon, damtype, mult, dam)

target(who is being hit?)

hitted(did we hit?)

crit(did we crit?)

weapon(our weapon)

damtype(what type of damage did we do?)

mult(our damage multiplier)

dam(the damage dealt)

-- Called whenever we crit.

callbackOnCrit(type, dam, chance, target)

Special note: type refers to either "physical" "spell" or "mind".

Special note 2: Only "physical" also returns a target along with it. Spell and mind do not.

dam(the damage dealt)

chance(the chance of the crit happening)

target(who did we hit?)

Player.lua

-- Called whenever we try to rest.

callbackOnRest(status)

Special note: status can either return "start" "stop" or "check".

"start" and "stop" simply allow you to do whatever you wish.

"check" will ask you to return either true or false. True will stop resting from ending.

-- Called whenever we run. (shift + direction)

callbackOnRun()

Special note: We will be unable to run if True is returned.

damage_types.lua

-- Called before we take damage. We can completely stop damage from ever happening from here.

callbackOnTakeDamage(src, x, y, type, dam, tmp, no_martyr)

Special note: This callback expects you to return a table. For our example's case, our table will be called 'data'.

You may return either data.dam or data.stopped. data.dam will behave just like you were passing the damage on, while data.stopped will stop the damage completely.

If stopped is a numerical value, the damage dealt will be set to this value before stopping.

stopped has a higher priority than dam, and dam will not directly impact stopped.

src(who is hitting us)

x, y(where is the damage happening?)

type(what damage type is hitting us?)

dam(how much are we being hit for?)

tmp()

no_martyr(set to true if your effect has the slightest chance of looping forever, usually due to dealing damage back)

callbackOnTakeDamageBeforeResists = function(src, x, y, type, dam, state)

Similar to the above, but happens before resists, flat reductions, etc.

Summons

callbackOnSummonHit callbackOnSummonDeath callbackOnSummonKill

callbackOnTeleport callbackOnDealDamage callbackOnHit callbackOnAct callbackOnActBase callbackOnActEnd callbackOnMove callbackOnRest callbackOnWait callbackOnCombat callbackOnRun callbackOnLevelup callbackOnDeath callbackOnDeathbox callbackOnResurrect callbackOnDispelled callbackOnDispel callbackOnDie callbackOnKill callbackOnCombatAttack callbackOnMeleeAttackBonuses callbackOnMeleeAttack callbackOnMeleeHit callbackOnMeleeMiss callbackOnArcheryAttack callbackOnArcheryHit callbackOnArcheryMiss callbackOnCrit callbackOnStatChange callbackOnTakeDamage callbackOnTakeDamageBeforeResists callbackOnHeal callbackOnQuickSwitchWeapons callbackOnWearTinker callbackOnTakeoffTinker callbackOnWear callbackOnTakeoff callbackOnTalentChange callbackOnTalentPost callbackOnTemporaryEffect callbackOnTemporaryEffectRemove callbackOnTemporaryEffectAdd callbackOnTalentDisturbed callbackOnBlock callbackOnChangeLevel callbackOnEffectSave callbackOnPartyAdd callbackOnPartyRemove callbackOnTargeted callbackOnCloned