wyvern.lib
Interface Command

All Known Subinterfaces:

BuiltInCommand, CommandList.CommandFilter

All Known Implementing Classes:

ApplyCommand, AppraiseCommand, ATM, AtmosphereCommands, AttackCommand, AudioCommand, AxisShapeChanger, BerserkSkill, BoltSpell, Book, Camera, CastCommand, CharmMonster, wyvern.lib.classes.games.ChessChair, ClientCommands, CodeEvent, CrystalBall, DamageCommand, DeathEvent, DrinkCommand, DropCommand, EatCommand, EmoteRoom, FireCommand, FlameShield, GetFromCommand, GiantShrink, GiveCommand, Guild, GuildSkills, HalflingSkills, HelpCommand, HitCommand, ImageFetcher, Instrument, Lamp, Lever, LockPickCommand, LookCommand, MouseCommand, MoveCommand, NagaShift, NullEvent, OfferCommand, OpenCommand, OrderCommand, PayTeleporter, PickupCommand, PixieSkills, PlayerGroups, PortableHole, PostOffice, PropertyWrapper, PushCommand, PutCommand, QuestTeleporter, QuitCommand, RakshasaSkills, ReadCommand, Registration, SayCommand, SearchCommand, Shop, ShoutCommand, ShowCommand, SimpleHandler, SokobanLevel, SpiralStair, Stair, SwordOfMercy, TalkCommand, TeleportCommand, TellCommand, ThrowCommand, TimerAgent, TurnCommand, Unlearner, Vehicle, WaitCommand, WearCommand, WhisperCommand, WieldCommand, XPToken

public interface Command

This is how you implement new game commands, or provide new implementation for existing commands.

The Command interface is, in a sense, the core of the programming model for the Wyvern engine, and takes a bit of explanation.

Game commands are plain text strings, such as "move west" or "get all from bag". The command verb is defined as the first word of the string.

An Command registers a command with an "agent" (often the agent is often a Player, but it can be a Monster or any other object that implements the Commandable interface). When the agent enters the command, it's sent through the agent's EventQueue and ultimately to the Command that registered it. It's also possible for the object to register the command with a map, or a "room" in a map, using the various command-registration methods provided by the wyvern.lib.GameMap interface.

There are four significant events in the life of a Command:

• specifying the conditions for when to register its command.

• knowing when those conditions are satisfied, and registering the command at that point.

• knowing when the agent enters the registered command, so the Command can execute it.

• knowing when the conditions for having the command registered no longer hold, so the Command can unregister it.

These four events are the core of the command registration system.

A simple example should help clarify things. Let's say you're making Cube Puzzle object that knows what to do when the user types "turn cube". The cube must implement the Command interface in order to be able to register its "turn" command.

Let's suppose the cube only wants "turn cube" to work if the agent (a player) is actually holding the cube in the agent's top-level inventory (i.e., not in a bag in the inventory):

1. the cube must indicate that it wishes to register the "turn" command with a player if the player picks it up. This can be accomplished in one of two ways:
   • have the cube implement PickupInterest, which calls a method when the cube is picked up or dropped.
   • have the cube get on the player's hooks for get, give, drop, throw, etc. This is clearly more painful, but it's a general mechanism that works when there isn't a ready-made interface like PickupInterest that you can use.

2. when the cube is picked up, it must be notified so it can register the command with the player who picked it up. The cube will call player.registerCommand("turn", this).

3. if the player types "turn ", the cube should be notified so it can see if it should execute the command.

   First its knowsCommand() will be called, in which the cube can check the arguments to see if the player typed "turn cube" (return true) or if they intended to turn something else (return false).

   If it returned true, its createEvent() method will be called, and if there is any other interesting context about the command that hook callbacks should be aware of, the cube can add this context into the event by setting properties in the event and documenting them thoroughly.

   Next, the execute() method is called, passing in the event that the cube created in createEvent(), but after any hook callbacks have had a chance to modify properties of the event. The cube should expect that some properties may have been modified, and re-check them before executing the event.

   Finally, the appropriate success/failure post-hook is invoked for the event, depending on the return value from execute().

4. when the cube is dropped (or removed from the top-level inventory in any way at all), it unregisters the "turn" command with the player by calling player.unregisterCommand("turn", this).

Version:

1.0, 10/02/97

Author:

Steve Yegge

Method Summary

CommandEvent	createEvent(CommandEvent initialInfo) Creates a CommandEvent that encapsulates all the state necessary to perform the command.
boolean	execute(CommandEvent event) Executes the specified CommandEvent.
boolean	knowsCommand(java.lang.String command) Returns true if this Command wants to handle the command.

Method Detail

knowsCommand

public boolean knowsCommand(java.lang.String command)

Returns true if this Command wants to handle the command. The Command can examine the arguments and determine that it doesn't actually understand the command, in which case it should return false.

This method exists to allow more than one game object to implement the same command verb, but with different expected arguments.

If two objects register for the same command and the same arguments, the object that was registered most recently gets to handle at the command.

Parameters:

command - the entire command string, including arguments

Returns:

true if we want to handle the command

createEvent

public CommandEvent createEvent(CommandEvent initialInfo)

Creates a CommandEvent that encapsulates all the state necessary to perform the command. A well-designed CommandEvent exposes all of its "properties" so that hook objects can modify its behavior. For instance, many commands result in some sort of message being sent back to the client. The message should be among the properties that hooks can override.

This method is called by the kernel. The kernel passes the event to the pre-hook, then calls Command.execute() (below) to execute the event, and finally calls the post-hook.

Parameters:

initialInfo - a "blank" CommandEvent containing only the command text and the agent who's performing the command. This initial event is created by the originator of the event (e.g. the AI or player's command preprocessor).

Returns:

a CommandEvent subclass encapsulating this command's execution parameters and state. It should copy in the fields from the passed-in event.

execute

public boolean execute(CommandEvent event)

Executes the specified CommandEvent. The CommandEvent contains all the parameters and state required to execute the command; the parameters have been filtered through hook objects, so they may not be the same as when the event was created.

Parameters:

event - the CommandEvent to execute

Returns:

true if the event completed successfully, else false.