From the NannyMUD documentation

LAST CHANGE

2002-07-20

CONCEPT

NAME
        hooks - about hooks in NannyMUD


DESCRIPTION
        Hooks were added to provide support for:

        * Global and consistent means of adding custom code to any
          object.

        * Allow several wizards to add custom code to an object.

        * Provide the means for adding and removing the costum code
          safely.

        * Be the ONLY solution. It should be the only supported
          method for providing this functionality.
 
        With custom code we mean code that you want to have evaluted
        when an event happens. An event can be that a monster dies, a
        player kills a monster, a player or monster walks around, and
        for some reason you want to know when the player/monster does
        these things.

        The hook system is all this. It provides, for any object
        configured for its use, the ability to use a single simple
        call, and have your code called at the appropriate times.
 
        There are three kinds of hooks, though they are treated almost
        identically:
        1/ the blocking hook
        2/ the value hook
        3/ the notification hook. 

        Block hooks are hooks in which the return values are
        meaningful; these hooks all have the following syntax: block_
        _hook, like block_die_hook.

        If you hook, for example, block_die_hook in a monster, then
        the object you specify will be called when the monster is
        about to die... and since it's a blocking hook, if you return
        1 from your function then the monster will not die.

        Also value hooks have meaningful return values; these hooks
        all have the following syntax:
        value__, like
        value_hit_player_hook.

        If you hook, for example, value_hit_player_hook in a monster,
        then the object you specify will be called when the monster is
        hit, and since it is a value hook what you return will somehow
        effect the event, in this case if you return a number then
        that number will be added to the damage being done to the
        monster.

        The notification hook is the most commonly used hook; return
        values from these are ignored. It is used when you want your
        code to be notified of an event. To continue the example with
        block_die_hook: if none of the block_die_hook hooks abort the
        kill, then the monster will die normally, and the die_hook
        hook will be called. The arguments are generally the same for
        a pair of blocking and notification hooks. The syntax here is
        generally; _hook. The function called is
        _hook with some standard argument and
        the object you registred the hook in as second argument.

        Also you need to know how to add hooks to objects, how to
        remove them, and how to check if you have a hook in an
        object. Read the documentation on add_hook(), remove_hook()
        and query_hook().


NOTE
        All use of block-hooks must be approved by the admin.


NOTE
        All use of value-hooks must be approved by the admin.