Laine at 21:48, 11 June 2007

Laine — Mon, 11 Jun 2007 21:48:19 GMT

New page

==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

Man hook list - Revision history

Laine at 21:48, 11 June 2007