Man hook list
From LSWiki
Current revision
Synopsis
This document lists the hooks available via the hooks mechanism, what objects acknowledge them, and the arguments provided to them.
Files
/mod/basic/hooks.c /lib/hooks.h
Description
There are seven types of hooks: Can, Do, Fail, Mod, Poll, Value, At, and Revise hooks. Each hook begins with one of these classifications. All Can hooks have Do and Fail hooks which corresponds to them.
Can hooks control whether an event can take place. In general, they are expected to have a return value of 1, for allowing the action to take place, 0, for denying the action, or a string or message array, for denying the action with the return value providing an error message. Any special properties of return values are noted in the description of the individual hook.
IMPORTANT NOTE: It is very important not to *do* things in Can_ hooks. That includes issuing messages other than by return value, moving things, harming people, or anything else. If you need to do anything like that, and the choice of whether you need to do it has to be made in the Can_ hook, use a global variable to signal to a corresponding Do_ or Fail_ hook and execute the action there. This is VERY IMPORTANT. The reason is that Can_ hooks are SPECIFICALLY MEANT to be able to be called merely to *find out* if an action would theoretically be possible. That means that when a Can_ hook is called, you DO NOT KNOW whether the action is actually taking place, so having consequences to it occur may be utterly inappropriate.
Do hooks are called to indicate that an event has taken place or, in some cases, is imminently about to take place. Their return values are usually, but not always, ignored. Any action taken based on their return values will be specified in the hook's documentation.
Fail hooks are called to indicate that an event has failed. Depending on the individual implementation, this may mean specifically that a Can hook has prevented the event, or other failure modes may trigger the hook. As with Do hooks, return values are usually ignored, but if not, this will be described in the hook's documentation.
Mod hooks usually affect the numerical values associated with an event; e.g. the amount of damage inflicted by a weapon hit, the chance of success at picking a lock or breaking a door. As they can be used to accumulate other addable values, such as arrays, they can also be used in the process of building object lists and so forth.
Value hooks resemble Mod hooks, except that they only allow one value to be returned. They are mainly used by lib core applications.
Poll hooks resemble Value hooks, but rather than simply using the first nonzero value encountered, a "vote" is taken among all the hooks, with the value which receives the most "votes" winning.
At hooks are identical to Do hooks except in that they have no corresponding Can and Fail hooks. They exist so notification hooks can be properly defined for events cannot feasibly or appropriatly be made preventable.
Revise hooks are something like Mod or Poll hooks, but work by continually modifying a given value. The return value of each hook is considered to be the desired modification of this value. The current value being revised is passed as the first argument to the hook functions, before any other arguments normally used by the hook.
The full list of lib-wide hooks is defined by /lib/hooks.h. Not all hooks defined are necessarily implemented. Hooks in the following list can be considered implemented. Each has its own man page for further information; note that the man pages use the lower case version of the name (so you should type e.g. 'man can_act' rather than 'man Can_Act').
The lib-wide hooks are designated using integer macros. The hooks support also allows strings to be used to designate "local hooks"; this is intended to be used by limited-scope applications for which it would not be appropriate to define a lib-wide hook. Hooks of this type should use a name that looks like "can_xxx_yyy", "do_xxx_yyy", and so on, where xxx is an indicator of the context (e.g. "ring", "figurine", "Project_Monster") and yyy is a description of the action of the hook. The type of a local hook is determined by the letter the name begins with:
'a' : At hook 'c' : Can hook 'd' : Do hook 'f' : Fail hook 'm' : Mod hook 'p' : Poll hook 'v' : Value hook
Hooks beginning with other letters are also treated as Mod hooks, but it is not recommended that you take advantage of this, as it could change.
Can_Act Can_Ammo_Launch_Move Can_Attack Can_Attack_In Can_Be_Attacked Can_Be_Closed Can_Be_Friend Can_Be_Linkdead Can_Be_Locked Can_Be_Opened Can_Be_Unlocked Can_Block_Exit Can_Die Can_Equip_Item Can_Fight Can_Go_Direction Can_Have_Limb_Disabled Can_Have_Limb_Restored Can_Have_Limb_Severed Can_Have_Lock_Picked Can_Hear Can_Heart_Beat Can_Launch_Move Can_Look_Direction Can_Move Can_Move_In Can_Move_Out Can_Obey Can_Perform_Close Can_Perform_Lock Can_Perform_Obey Can_Perform_Open Can_Perform_Pick_Lock Can_Perform_Unlock Can_Quit Can_Unequip_Item
Do_Act Do_Ammo_Launch_Move Do_Attack Do_Attack_In Do_Be_Attacked Do_Be_Closed Do_Be_Friend Do_Be_Linkdead Do_Be_Locked Do_Be_Opened Do_Be_Unlocked Do_Block_Exit Do_Die Do_Equip_Item Do_Fight Do_Go_Direction Do_Have_Limb_Disabled Do_Have_Limb_Restored Do_Have_Limb_Severed Do_Have_Lock_Picked Do_Hear Do_Heart_Beat Do_Launch_Move Do_Look_Direction Do_Move Do_Move_In Do_Move_Out Do_Obey Do_Perform_Close Do_Perform_Lock Do_Perform_Obey Do_Perform_Open Do_Perform_Pick_Lock Do_Perform_Unlock Do_Quit Do_Unequip_Item
Fail_Act Fail_Attack Fail_Attack_In Fail_Be_Attacked Fail_Be_Closed Fail_Be_Friend Fail_Be_Locked Fail_Be_Opened Fail_Be_Unlocked Fail_Block_Exit Fail_Die Fail_Equip_Item Fail_Fight Fail_Go_Direction Fail_Have_Limb_Disabled Fail_Have_Limb_Restored Fail_Have_Limb_Severed Fail_Have_Lock_Picked Fail_Hear Fail_Heart_Beat Fail_Obey Fail_Perform_Close Fail_Perform_Lock Fail_Perform_Obey Fail_Perform_Open Fail_Perform_Pick_Lock Fail_Perform_Unlock Fail_Unequip_Item
Mod_Absorb_Damage Mod_Ammo_Inflict_Damage Mod_Attack_Cycle Mod_Comprehend_Language Mod_Destination Mod_Friendship Mod_Inflict_Damage Mod_Obedience Mod_Pick_Lock
At_Update_Configuration At_Incarnate
