Hooks

For addons, hooks are a way of causing certain code to be triggered by events happening in the game.

They are all used the same way, with "ToME:load" being replaced with the actual hook name:

class:bindHook("ToME:load", function(self, data)
your code
end

If the hook function has any arguments, they are accessed through the data variable like data.argumentname .

Here is a list of hooks currently available for addon creators and what they do.

ToME:load Triggers when ToME loads up. Used to load an addons files into the game. Must be included in every addon or the addon will not work! There are a few important functions you'll want to trigger to make the magic happen.

• Birther:loadDefinition will load a new race or class
• ActorTalents:loadDefinition will load new talents for your new race, class, or monster to use
• DamageType:loadDefinition will load new damage types for your talents to use
• ActorTemporaryEffects:loadDefinition will load new temporary effect, bad or good, to be used by talents and damage types
• WorldAchievements:loadDefinition loads new achievement. Not commonly used in addons
• PlayerLore:loadDefinition adds new lore to be collected by the player. Not commonly used in addons
• PartyIngredients:loadDefinition loads new ingredients to be collected by the player for reciptes. Not commonly used in addons.

So for example if we want a new class called "Pilgrim" with it's own unique talents, but no new damage types or effects, we could load it like so.

class:bindHook("ToME:load", function(self, data)
ActorTalents:loadDefinition("/data-classpack/talents/techniques/techniques-pilgrim.lua")
Birther:loadDefinition("/data-classpack/birth/pilgrim.lua")
end)

Engine Hooks:

Chat:Talkbox:command

/dialogs/Talkbox.lua/okclick

data = { command=command, params=params, talkbox=self}

Allows the addition of new chat commands.

Entity:loadList

/Entity.lua/loadList

data = { file=file, no_default=no_default, res=res, mod=mod, loaded=loaded}

Useful for adding new entries into a list file, without overwriting it.

MapGeneratorStatic:subgenRegister

/generator/map/Static.lua/generate

data = { mapfile=self.data.map, list=self.subgen}

Something for adding in new things to map generation?

Module Hooks:

Actor:actBase:Effects

/mod/class/Actor.lua/actBase

data = { }

Triggers when the actor does anything. Useful for anything with a constant effect. self is the actor doing the action.

Actor:move

/mod/class/Actor.lua/move

data = { moved=moved, force=force, ox=ox, oy=oy}

Triggers when an actor moves.

Actor:takeHit

/mod/class/Actor.lua/onTakeHit

data = { value=value, src=src}

Triggers when an actor is hit by something. It's useful mostly for talents and effects that alter or avoid damage being recieved on a particular actor. self in this case is the thing being hit. data.value contains the amount of damage taken.

Actor:preUseTalent

/mod/class/Actor.lua/preUseTalent

data = { t=ab, silent=silent, fale=fake}

Triggers whenever an actor tries to use a talent, but before the talent is run. Useful for new resources or failure effects.

Actor:postUseTalent

/mod/class/Actor.lua/postUseTalent

data = { t=ab, ret=ret, trigger=trigger}

Triggers after an actor successfully uses a talent. Useful for new resources types.

Actor:getTalentFullDescription:ressources

/mod/class/Actor.lua/getTalentFullDescription

data = {str=d, t=t, addlevel=addlevel, config=config, fake_mastery=fake_mastery}

This is where you add code to make your new resource display.

Actor:getTalentFullDescription

/mod/class/Actor.lua/getTalentFullDescription

data = { str=d, t=t, addlevel=addlevel, config=config, fake_mastery=fake_mastery}

Let's you add something else just above the talent description.

ToME:run

/mod/class/Game.lua/run

data = { }

See ToME run. Run ToME run! Inserts code before the module starts running.

Game:alterGameMenu

/mod/class/Game.lua/setupCommands

data = { menu=l, unregister=function() self:unregisterDialog(menu) end}

Allows editing of the escape menu.

Combat:archeryAcquire

/mod/class/interface/Archery.lua/archeryAcquireTargets

data = { tg=tg, params=params, weapon=weapon, ammo=a}

Similar to Combat:attackTarget but with ranged weapons.

Combat:archeryHit

/mod/class/interface/Archery.lua/archery_projectile

data = { hitted=hitted, target=target, weapon=weapon, ammo=ammo, damtype=damtype, mult=mult, dam=dam}

Triggers when a projectile hits an actor.

Combat:attackTarget

/mod/class/interface/Combat.lua/attackTarget

data = { target=target, damtype=damtype, mult=mult, noenergy=noenergy}

Triggers when the actor starts to attack but before anything actually happens to weapons are taken into account. Useful for effects that prevent attacking. self is the actor trying to attack, data.target is his target, data.damtype is the damage type being applied.

Return false to continue the attack without modifying it.

Return true to take into account changes made in the hook. You can change data.mult and data.damtype to modify damage characteristics.

To cancel the attack set data.stop to true and data.hit to false and return true.

Combat:attackTargetWith

/mod/class/interface/Combat.lua/attackTargetWith

data = { hitted=hitted, crit=crit, target=target, weapon=weapon, damtype=damtype, mult=mult, dam=dam}

Triggers when the actor makes an attack after the weapon and whether it hits or not has been taken into account. Useful for just about any effect or skill that triggers on attack. self is the actor attacking, data.target is the target being hit, data.hitted is whether or not the attack hit the target, and data.dam, data.damtype, and data.weapon should be self-evident.

Combat:attackTargetWith:attackerBonuses

/mod/class/interface/Combat.lua/attackTargetWith

data = { target=target, weapon=weapon, damtype=damtype, mult=mult, dam=dam, apr=apr, atk=atk, def=def, armor=armor}

Triggers when processing an actor attack before the damage computation. Useful to take into account bonuses of the attacker and/or the target. data.target is the target being hit, other parameters should be self-evident.

ToME:PlayerDumpJSON

/mod/class/interface/PlayerDumpJSON.lua/dumpToJSON

data = { title=title, js=js, tags=tags}

I'm guessing its for appending something to the character data before it is sent to the server.

Object:descCombat

/mod/class/Object.lua/getTextualDesc

data = { compare_with=compare_with, compare_fields=compare_fields, compare_table_fields=compare_table_fields, desc=desc, combat=combat}

Useful for editing the combat stats in an objects tooltips.

Object:descWielder

/mod/class/Object.lua/getTextualDesc

data = { compare_with=compare_with, compare_fields=compare_fields, compare_table_fields=compare_table_fields, desc=desc, w=w}

Useful for editing the weilder stats in an objects tooltips.

Object:descMisc

/mod/class/Object.lua/getTextualDesc

data = { compare_with=compare_with, compare_fields=compare_fields, compare_table_fields=compare_table_fields, desc=desc, object=self}

Should you want to add anything right at the bottom of an items tooltip, this hook is for you.

Object:descPowerSource

/mod/class/Object.lua/getDesc

data = { desc=desc, object=self}

Want to add in new power sources? Use this.

UISet:Minimalist:saveSettings

/mod/class/uiset/Minimalist.lua/saveSettings

data = { lines=lines}

Not sure, could be for adding framework for dealing with new settings.

UISet:Minimalist:Resources

/mod/class/uiset/Minimalist.lua/displayResources

data = { a=a, player=player, x=x, y=y, bx=bx, by=by, orient=orient, scale=scale}

Use for adding new resource bars.

UISet:Minimalist:Toolbar

/mod/class/uiset/Minimalist.lua/displayToolbar

data = { x=x, y=y, bx=bx, by=by, orient=orient, scale=scale, tb_bg=tb_bg}

Something for hooking code into the display of the toolbar. For what end, I have no idea.

DebugMain:use

/mod/dialogs/debug/DebugMain.lua/use

data = { act=act}

Use to code new debug commands.

DebugMain:generate

/mod/dialogs/debug/DebugMain.lua/generateList

data = { menu=list}

Use to add new commands to the debug menu.

DonationDialog:features

/mod/dialogs/Donation.lua/init

data = { list=donation_features}

Use to add new features to the list of donator features.

GameOptions:HUDs

/mod/dialogs/GameOptions.lua/generateList

data = { huds=huds}

Allows the addition of new HUD types to the HUD menu.

PlayerLevelup:addTalentType

/mod/dialogs/LevelupDialog.lua/learnType

data = { actor=self.actor, tt=tt}

Triggers when a player spends a category point in a category.

PlayerLevelup:subTalentType

/mod/dialogs/LevelupDialog.lua/learnType

data = { actor=self.actor, tt=tt}

Triggers when a player changes their mind and unspends a category point.

EquipInvenDialog:makeUI

/mod/dialogs/ShowEquipInven.lua/init

self:triggerHook{"EquipInvenDialog:makeUI", uis=uis}

Triggers during inventory screen creation. I guess it lets you edit it.

UseItemMenu:use

/mod/dialogs/UseItemDialog.lua/use

data = { actor=self.actor, object=self.object, inven=self.inven, item=self.item, act=act, onuse=self.onuse}

Use to add code for new menu items.

UseItemMenu:generate

/mod/dialogs/UseItemDialog.lua/generateList

data = { actor=self.actor, object=self.object, inven=self.inven, item=self.item, menu=list}

Use to add new menu items to the item action menu.

ToME:load

/mod/load.lua

data = { }

This is where you load up new files for your addon.

Quest:escort:reward

/data/chats/escort-quest.lua/reward_types

data = { reward_types=reward_types}

Allows editing of the escort rewards.

DamageProjector:base

/data/damage_types.lua/setDefaultProjector

data = { src=src, x=x, y=y, type=type, dam=dam}

DamageProjector:final

/data/damage_types.lua/setDefaultProjector

data = { src=src, x=x, y=y, type=type, dam=dam}

These are similar, but trigger slightly differently. Both trigger when the damage projector is used to put damage on something, such as a spell or other effect. The first one triggers before any other skills effects, or calculations are taken into consideration. The other one takes place after this is all done and right before the damage is actually applied. In both cases, data.src is the actor doing the damage, data.x and data.y are the locations of the target, data.type is the damage type and data.dam is the actual amount of damage.

Quest:escort:assign

/data/quests/escort-duty.lua/on_grant

data = { possible_types=possible_types}

This is where you add in (or remove) escortee types.