wyvern.lib
Interface Hookable

All Superinterfaces:

MethodHookable

All Known Subinterfaces:

Commandable, GameMap, Monster, Player

All Known Implementing Classes:

AbstractCommandable, AbstractGameMap, HookList, MonsterImpl, PlayerImpl

public interface Hookable

extends MethodHookable

Declares that an object has events and/or methods that can be "hooked" by other objects.

A hook is a special kind of notification that can take place before or after the associated action (method or event) has happened. The main difference between a hook and a normal event notification (such as the java.awt.event notification system) is that a hook lets you not only veto the event, but in fact change the parameters of the event so that the result is different.

Hooks are an important tool for Wizards coding objects and areas. Using hooks, you can know when just about anything happens in the game - random examples include:

• knowing when a player picks something up or drops it
• knowing when a player enters or leaves a map
• knowing when a player monster dies
• knowing when a spell enters a certain area of a map

In fact very few things can happen in the game that you can't know about or override in some way.

Event hooks are the most common kind of hook. An Event hook is created and run automatically by the game engine for all command events. Event hooks include pre-hooks (before the event) and post-hooks (after the event). Post-hooks are further subdivided into successful post-hooks and failed post-hooks, depending on whether the event was successful or not.

Method hooks are a way for an object to be notified when a given method is invoked on a given target. There is no general mechanism in Java for method hooks, so only certain methods that "provide" their own method hooks can be hooked in this fashion. The standard type of method hook has the same name as the method, although it's possible for a method to provide multiple hooks at different points in its execution. In this case the method will document the names and semantics of its various hooks.

Version:

1.0, 10/03/97

Author:

Steve Yegge

Method Summary

void	addHook(HookCallback callback, java.lang.String hookName) Registers a HookCallback object for the specified hook.
HookList	getHookList() Returns the HookList containing the registered hooks for this object.
java.lang.String[]	getHooks() Returns a list of custom hooks implemented by this object.
void	removeHook(HookCallback callback, java.lang.String hookName) Removes a callback from a specified hook list.
void	runFailedPostHook(CommandEvent event) Notifies all the objects registered on this post-hook that the command failed (for whatever reason).
void	runPostHook(CommandEvent event) Notifies all the objects registered on this post-hook that the event completed successfully.
void	runPreHook(CommandEvent event) Calls all objects registered for a particular event and gives them a chance to deal with the event before it happens.

Methods inherited from interface wyvern.lib.MethodHookable

addMethodHook, removeMethodHook, runMethodHook

Method Detail

getHooks

public java.lang.String[] getHooks()

Returns a list of custom hooks implemented by this object.

The list doesn't include names of default hooks for built-in commands.

Returns:

an array of names for custom hooks that the object defines. For example, if a Hookable had a Foo operation that it wanted to run pre- and post-hooks for, and no other hookable operations, this method would return an array of two strings:

• "fooPreHook"
• "fooPostHook"

Returns an empty string array if this object has no custom hooks.

addHook

public void addHook(HookCallback callback,
                    java.lang.String hookName)

Registers a HookCallback object for the specified hook.

The reserved pseudo-command "any" is reserved for callbacks that need to get every single command that comes through the queue. This should very rarely be necessary, and can hurt overall game performance considerably if abused.

Parameters:

callback - the HookCallback to notify when the hook is run.

hookName - the name of the hook list to register on.

removeHook

public void removeHook(HookCallback callback,
                       java.lang.String hookName)

Removes a callback from a specified hook list.

Parameters:

callback - the HookCallback to remove from the list

hookName - the name of the hook list to unregister from.

runPreHook

public void runPreHook(CommandEvent event)

Calls all objects registered for a particular event and gives them a chance to deal with the event before it happens.

Callbacks may veto the event, but it's still passed to any other callbacks on the list, and eventually to the Command. For callbacks, it typically doesn't really matter if the flag has been set by a previous callback; callbacks should do the same thing they would have done even if it wasn't vetoed, because the Command (or any other callback downstream) may un-veto it.

The callbacks may modify any of the event parameters. Callbacks aren't required to do rigorous checking of the validity of their changes. For example, a simple callback registered on a player's preMoveHook might change the direction in the MoveEvent randomly.

To prevent callbacks from generating illegal event parameters, the Command handling the event is implicitly the last hook on the list. Before executing the command it re-checks the preconditions to make sure the move is still legal, and if it isn't, it vetoes it and issues an error message. The message, of course, is a modifiable parameter of the event.

If a HookCallback wants to force an "illegal" event, it has to change the game state (in the agent, the map, the Command, or whatever) to make the move legal. For example, if the hook wants to make sure the player moves over a wall, the hook can set a property on the player (or the wall) that allows this move, before returning control to this method.

Parameters:

event - a CommandEvent that has already run. Calling getVerb() should return the canonical verb for this command, such as "move" or "get". The verb is used to construct the hook name, by appending "PreHook" to the verb.

runPostHook

public void runPostHook(CommandEvent event)

Notifies all the objects registered on this post-hook that the event completed successfully. Changing the event params will have no effect at this point.

Parameters:

event - a CommandEvent that has already run. Calling getVerb() should return the canonical verb for this command, such as "move" or "get". The verb is used to construct the hook name, by appending "PostHook" to the verb.

runFailedPostHook

public void runFailedPostHook(CommandEvent event)

Notifies all the objects registered on this post-hook that the command failed (for whatever reason). It's up to the CommandEvent subclass to provide more detailed information as to why it failed.

Changing the event parameters will have no effect at this point.

Parameters:

event - a CommandEvent that has failed for some reason. getVerb() should return the canonical verb for this command, such as "move" or "get". The verb is used to construct the hook name, by appending "FailedPostHook" to the verb.

getHookList

public HookList getHookList()

Returns the HookList containing the registered hooks for this object.