wyvern.lib
Interface CommandEvent

All Superinterfaces:

Broadcaster, PropertyList

All Known Implementing Classes:

EventImpl

public interface CommandEvent

extends PropertyList, Broadcaster

Every command is turned into a CommandEvent that goes into some Commandable's event queue, to be executed later by the game scheduler.

Version:

1.0, May 17, 1998

Author:

Steve Yegge

Field Summary

Fields inherited from interface wyvern.lib.PropertyList

PROPERTY_PACKAGE

Method Summary

boolean	checkVeto() If the event is vetoed, sends the event's failureMessage() to the event's agent.
boolean	fail() Issues the event's failure-message to the event's agent.
java.util.List	findAllMatches(Commandable agent, Predicate p) Finds all objects in the map, adjacent to or beneath the agent, that match the passed predicate.
GameObject	findByHashcode(java.lang.String hashcode) Looks for an object by its hashcode.
GameObject	findInMap(Commandable agent, Predicate p) Searches for an object matching the specified predicate.
GameObject	findNeighbor(Commandable agent, Predicate pred) Searches for an object on the ground under and adjacent to the agent.
GameObject	findObject(Commandable agent, Predicate p) Searches for an object matching the specified predicate.
GameObject	findTarget(Commandable agent, Predicate match) Searches for an object matching the specified predicate.
Commandable	getAgent() Get the agent associated with this command event - usually a player or monster, but it can be anything with an event queue (such as a spell).
java.lang.String[]	getArgs() Gets the arguments to this command, split into an array.
java.lang.String	getArgString() Gets the arguments to the command as a whitespace-delimited string.
long	getDelay() Returns the delay associated with this event.
java.lang.String	getFailureMessage() Returns the "failure" message for this event.
CommandFilter[]	getFilterObjects() Returns the parsed CommandFilter objects that will be applied to the message for this event.
java.lang.String[]	getFilters() Returns the filter strings being applied to this event.
Command	getHandler() Returns the Command that will handle this event, if the Command is different from the one that created the event.
GameMap	getMap() Returns the map where this event is taking place.
java.lang.String	getOriginalText() Returns the original text for this command event, before removing aliases, prepositions, etc.
java.io.File	getRedirectFile() Returns the file that we're redirecting output to, if any.
java.lang.String	getSuccessMessage() Returns the "success" message for this event.
java.lang.String	getVerb() Returns the command verb for this event.
boolean	hasArgs() Returns true if there were any arguments to the event.
boolean	isAppending() Returns true if the redirect-to-file operator was "+>>" or ">>".
boolean	isModified() Returns true if this event has been modified by a hook callback.
boolean	isMonster() Returns true if the event's agent is a Monster (not a player).
boolean	isPlayer() Returns true if the event's agent is a Player (or wizard).
boolean	isPlayerOriginated() Returns true if a player actually typed in this command.
boolean	isRedirecting() True if there was a redirect operator detected at the end of the command: ">", ">>", "+>", or "+>>".
boolean	isSendingToAgent() Returns true if the redirect operator included a "+" to send the output to the agent as well.
boolean	isVetoed() Returns true if this event has been vetoed by someone.
boolean	isWizard() Returns true if the event's agent is a Wizard.
void	message(java.lang.String msg) Sends a message to the event's agent.
void	message(java.lang.String msg, byte style) Sends a message to the event's agent, in the specified TextStyle.
boolean	noArgs() Returns true if there were no arguments to the event.
void	runPostHooks(boolean success) Runs one of the event's post hooks. 99.9% of the time this is called by the game kernel after execute() runs.
void	runPreHooks() Runs the event's pre-hooks.
GameObject	searchInv(Predicate p) Searches the agent's inventory for the first object matching the passed Predicate.
GameObject	searchInvAndMapNearby(Predicate p) Searches for an object matching the specified predicate.
GameObject	searchInvAndMapUnder(Predicate p) Searches for an object matching the specified predicate.
GameObject	searchInvByHashcode(java.lang.String hashcode) Searches the agent's inventory for an object with the specified hashcode.
GameObject	searchMapNearby(Predicate p) Searches for an object on the ground under and adjacent to the agent.
GameObject	searchMapUnder(Predicate p) Searches for an object matching the specified predicate.
GameObject	searchMapUnderByHashcode(java.lang.String hashcode) Searches agent's inventory and the ground under the agent for an object with the specified hashcode.
void	setAgent(Commandable agent) Sets the agent for this event.
void	setArgs(java.lang.String[] args) Sets the arguments for this command.
void	setDelay(long delay) Sets the delay time to wait after this event is executed.
void	setFailureMessage(java.lang.String message) Sets the "failure" message for this event.
void	setHandler(Command handler) Sets the Command that will handle this event.
void	setMap(GameMap map) Sets the map where this event is taking place.
void	setModified(boolean modified) Sets the "modified" flag for this event.
void	setOriginalText(java.lang.String newText) This method is here for the sake of completeness, but it's not recommended that objects change the original text of a command, as other objects may rely on it.
void	setPlayerOriginated(boolean b) Sets the event flag indicating that this command was originated by a player.
void	setSuccessMessage(java.lang.String message) Sets the "success" message for this event.
void	setVerb(java.lang.String verb) Convenience method; when constructing an event, a Command should set the verb; otherwise it'll have to be deduced from the command text, and the guess could be incorrect.
void	setVeto(boolean veto) Sets the veto-flag for this event.
CommandEvent	veto(java.lang.String msg) Sets the veto flag and the failure message for the event.

Methods inherited from interface wyvern.lib.PropertyList

addProperty, addTransientProperty, adjustDoubleProperty, adjustIntProperty, adjustLongProperty, adjustTransientDoubleProperty, adjustTransientIntProperty, adjustTransientLongProperty, countLocalProperties, getDoubleProperty, getInheritedProperty, getIntProperty, getLocalProperties, getLocalProperty, getLongProperty, getParent, getPersistentDoubleProperty, getPersistentIntProperty, getPersistentLocalProperties, getPersistentLongProperty, getPersistentProperty, getProperties, getProperties, getPropertiesIncludingTransients, getPropertiesIncludingTransients, getProperty, getSerializableProperties, getSerializableProperty, getStringProperty, getTransientDoubleProperty, getTransientIntProperty, getTransientLongProperty, getTransientProperties, getTransientProperty, hasLocalProperty, hasPersistentProperty, hasProperty, hasTransientProperty, inheritProperty, isReadOnly, isRemoved, isTransientlyRemoved, printLocalProperties, printProperties, printProperties, printTransientProperties, removeProperty, removeTransientProperty, setDoubleProperty, setIntProperty, setLongProperty, setParent, setProperty, setReadOnly, setTransientDoubleProperty, setTransientIntProperty, setTransientLongProperty, setTransientProperty, toString, transientlyRemoveProperty

Methods inherited from interface wyvern.lib.Broadcaster

broadcast, broadcast, broadcast, broadcast, broadcast

Method Detail

getAgent

public Commandable getAgent()

Get the agent associated with this command event - usually a player or monster, but it can be anything with an event queue (such as a spell).

Returns:

the agent for this event

setAgent

public void setAgent(Commandable agent)

Sets the agent for this event. Normally set only once, by the object that creates the event, but a hook object that knows what it's doing can change it if necessary. Changing it may have weird effects; the event will try to act as if the new agent executed it (e.g. if you change it to a different player, that player will execute the command.) There's no guarantee it will work in any given situation; the hook object has to combine a bit of knowledge and a bit of luck to make it work.

Parameters:

agent - the new agent to perform the command

setMap

public void setMap(GameMap map)

Sets the map where this event is taking place. Normally this isn't necessary, because getMap() will use the agent's map. However, if the agent isn't in a map, or the event is supposed to be taking place in a map other than the agent's location, you can set the map explicitly.

Parameters:

map - the GameMap where the event is happening. This is primarily important for where the map-hooks for the event will be run.

getMap

public GameMap getMap()

Returns the map where this event is taking place. Usually (but not always) the agent's current map.

Returns:

the map where the map-hooks are being run. Note that the map pre-hook and post-hook could be run in different maps, if someone called setMap() in a pre-hook or execute(). Also note that the value returned may be null, if the event's agent isn't currently in a map, and nobody has called setMap() for this event.

setHandler

public void setHandler(Command handler)

Sets the Command that will handle this event. Normally the Command handling the event is the same as the one that created the event, but not always. The game engine will check to see if this has changed before calling the handler to execute the event.

Parameters:

handler - the new Command to execute the command

getHandler

public Command getHandler()

Returns the Command that will handle this event, if the Command is different from the one that created the event.

This is a somewhat rare occurrence; an example is the "move" command, which can result in a move, a push, an attack, or other events depending on the context. One Command will create the initial MoveEvent, and it may be transmogrified into an AttackEvent or other event, which requires a new handler to execute it.

This is the method the game engine calls to see if someone called setHandler() on the event during the hook callbacks.

Returns:

the Command to handle the event, or null to default to the Command that created the event.

getOriginalText

public java.lang.String getOriginalText()

Returns the original text for this command event, before removing aliases, prepositions, etc.

Returns:

the original text of the command

setOriginalText

public void setOriginalText(java.lang.String newText)

This method is here for the sake of completeness, but it's not recommended that objects change the original text of a command, as other objects may rely on it.

getVerb

public java.lang.String getVerb()

Returns the command verb for this event.

Returns:

the first (and sometimes only) word of the command text

setVerb

public void setVerb(java.lang.String verb)

Convenience method; when constructing an event, a Command should set the verb; otherwise it'll have to be deduced from the command text, and the guess could be incorrect. It's set in the EventImpl constructor to the first word of the original text - the Command only needs to change it if this isn't the correct verb to use. (It almost always is).

Parameters:

verb - the command verb (e.g. "move")

getArgs

public java.lang.String[] getArgs()

Gets the arguments to this command, split into an array. This array is produced during the call to event.parse().

Returns:

the arg array, null if the command had no arguments.

noArgs

public boolean noArgs()

Returns true if there were no arguments to the event.

Returns:

true if the command no arguments, false if there were any non-whitespace characters following the command verb.

hasArgs

public boolean hasArgs()

Returns true if there were any arguments to the event.

Returns:

opposite of noArgs()

setArgs

public void setArgs(java.lang.String[] args)

Sets the arguments for this command. An Command usually does all its argument-parsing in the createEvent() method, before the event is passed to the hooks, so setting the args in a hook callback may have no effect. Some event classes (if their documentation says so) may re-check the arg array during execute() to see if it changed, but this is rare. Usually a hook callback will modify the target of the event directly, rather than the arguments naming the target.

Parameters:

args - the arguments to use to interpret the command

getArgString

public java.lang.String getArgString()

Gets the arguments to the command as a whitespace-delimited string.

Returns:

the argument string, basically everything after the command verb. Returns null if there were no args.

message

public void message(java.lang.String msg)

Sends a message to the event's agent. Equivalent to event.getAgent().message(), except that it can be intercepted by ">" or "|" operators in the command. I.e. if you use event.message() instead of agent.message(), you can redirect the output to a file, or filter it for lines matching a specific string or regular expression.

Parameters:

msg - the message to print.

message

public void message(java.lang.String msg,
                    byte style)

Sends a message to the event's agent, in the specified TextStyle. Can be redirected or piped the same way the one-arg message() function can.

Parameters:

msg - the message

style - the Kernel.TextStyle constant

setVeto

public void setVeto(boolean veto)

Sets the veto-flag for this event. Normally, you don't call this method directly, but instead call veto (msg). This is because the first thing a Command typically does when executing an event is check the veto flag, and if it's set, issues the event's failure message to the agent. So if you set the veto, you normally set an appropriate failure-msg in the event as well. veto(msg) does just this.

If you want to use the default failure message, you can call this method to set the flag. This method can also be used to clear the veto flag, meaning you want to un-veto the event.

Parameters:

veto - true to veto the event.

isVetoed

public boolean isVetoed()

Returns true if this event has been vetoed by someone.

Returns:

true if the event was vetoed; false if not.

checkVeto

public boolean checkVeto()

If the event is vetoed, sends the event's failureMessage() to the event's agent. This is a useful call to make at the beginning of every CommandEvent's execute() method.

Returns:

true if event was vetoed

veto

public CommandEvent veto(java.lang.String msg)

Sets the veto flag and the failure message for the event.

Parameters:

msg - the failure message to send to the agent (i.e. the reason for vetoing the event).

Returns:

this event object, primarily for syntactic sugaring. It allows you to say "return event.veto(msg)", which you'll do often, as vetoing the event is usually cause for returning from the createEvent() handler.

setSuccessMessage

public void setSuccessMessage(java.lang.String message)

Sets the "success" message for this event. Typically set only once, by the Command creating the event. However, hook callbacks may change it where appropriate.

Parameters:

message - the message to display if the event succeeds.

getSuccessMessage

public java.lang.String getSuccessMessage()

Returns the "success" message for this event. Used by the Command when it completes the event successfully and is ready to display feedback to the client. EventImpl subclasses may have more than one success message, and should provide getter and setter methods for the other messages.

Returns:

the message to display if the event succeeds.

setFailureMessage

public void setFailureMessage(java.lang.String message)

Sets the "failure" message for this event. Typically set only once, by the Command creating the event. However, hook callbacks may change it where appropriate.

Parameters:

message - the message to display if the event fails.

getFailureMessage

public java.lang.String getFailureMessage()

Returns the "failure" message for this event. Used by the Command to display feedback to the agent when the command fails.

setModified

public void setModified(boolean modified)

Sets the "modified" flag for this event. HookCallbacks should be careful to set this flag if they change any parameters in the event that might invalidate the conditions for which the event is legal. For example, a callback changing the direction a player moves should set this flag, or the player could wind up walking into a wall.

Parameters:

modified - true to mark the event as modified

isModified

public boolean isModified()

Returns true if this event has been modified by a hook callback.

Returns:

true if the event parameters were modified.

setDelay

public void setDelay(long delay)

Sets the delay time to wait after this event is executed. The delay corresponds to how long it took the agent to perform the action.

Parameters:

delay - the command delay in milliseconds

getDelay

public long getDelay()

Returns the delay associated with this event.

Returns:

the total delay for this command, in millis

isPlayerOriginated

public boolean isPlayerOriginated()

Returns true if a player actually typed in this command.

Returns:

true if command was originated by a player. If false, the command was placed in the queue by the game engine.

setPlayerOriginated

public void setPlayerOriginated(boolean b)

Sets the event flag indicating that this command was originated by a player. Gives us a way to prevent the player from typing in the name of a game command that they shouldn't be able to originate (e.g. "teleport").

Parameters:

b - true if it was originated by a user, via the client.

findNeighbor

public GameObject findNeighbor(Commandable agent,
                               Predicate pred)

Searches for an object on the ground under and adjacent to the agent. The squares are not guaranteed to be searched in any particular order. The search may intermix squares beneath the agent with squares adjacent to the agent.

NOTE: If you're coding a command that looks for a target at the agent's feet first, use findObject() instead. Otherwise you'll get weird bugs if there's an item with the same name next to the agent, since this may find that one first.

Parameters:

agent - the GameObject to look around

pred - a Predicate to use for searching the map

Returns:

the first matching object, or null if not found

findObject

public GameObject findObject(Commandable agent,
                             Predicate p)

Searches for an object matching the specified predicate. Uses the following search order:

1. The agent's inventory.
2. The ground beneath the agent.
3. All squares immediately adjacent to the agent.

Parameters:

agent - the agent to check (must be in a map)

p - the predicate used to tell which object to grab.

Returns:

the first matching object, or null if not found

findTarget

public GameObject findTarget(Commandable agent,
                             Predicate match)

Searches for an object matching the specified predicate. Uses the following search order:

1. The agent's inventory.
2. The ground beneath the agent.

Unlike findObject() and findNeighbor(), this method doesn't look in squares adjacent the agent.

Parameters:

agent - the agent to look near

match - the predicate to use to locate the object

Returns:

the first GameObject found that passes the predicate, or null if none was found.

findInMap

public GameObject findInMap(Commandable agent,
                            Predicate p)

Searches for an object matching the specified predicate. Only looks in the map immediately beneath the agent.

Parameters:

agent - the agent to check (must be in a map)

p - the predicate used to tell which object to grab.

Returns:

the first matching object, or null if not found

findByHashcode

public GameObject findByHashcode(java.lang.String hashcode)

Looks for an object by its hashcode. Checks inventory first, then the ground beneath the agent. Used when manipulating objects in ground or inventory with the mouse.

Parameters:

hashcode - the hash code of the object to retrieve

Returns:

the object, if found, else null

findAllMatches

public java.util.List findAllMatches(Commandable agent,
                                     Predicate p)

Finds all objects in the map, adjacent to or beneath the agent, that match the passed predicate.

Parameters:

agent - the agent to check (must be in a map)

p - the predicate used to tell which object to grab.

Returns:

all matching objects, or an empty list if none are found

searchInv

public GameObject searchInv(Predicate p)

Searches the agent's inventory for the first object matching the passed Predicate.

Parameters:

p - a predicate to test the objects in inventory

Returns:

the first object in the agent's inventory for which the passed predicate returns true, or null if none matched

searchMapUnder

public GameObject searchMapUnder(Predicate p)

Searches for an object matching the specified predicate. Only looks in the map immediately beneath the agent.

Parameters:

p - the predicate used to tell which object to grab.

Returns:

the first matching object, or null if not found

searchMapNearby

public GameObject searchMapNearby(Predicate p)

Searches for an object on the ground under and adjacent to the agent. The squares are not guaranteed to be searched in any particular order. The search may intermix squares beneath the agent with squares adjacent to the agent.

NOTE: If you're coding a command that looks for a target at the agent's feet first, use findObject() instead. Otherwise you'll get weird bugs if there's an item with the same name next to the agent, since this may find that one first.

Parameters:

p - a Predicate to use for searching the map

Returns:

the first matching object, or null if not found

searchInvAndMapUnder

public GameObject searchInvAndMapUnder(Predicate p)

Searches for an object matching the specified predicate. Uses the following search order:

1. The agent's inventory.
2. The ground beneath the agent.

Only looks beneath the agent, not in adjacent squares.

Parameters:

p - the predicate to use to locate the object

Returns:

the first GameObject found that passes the predicate, or null if none was found.

searchInvAndMapNearby

public GameObject searchInvAndMapNearby(Predicate p)

Searches for an object matching the specified predicate. Uses the following search order:

1. The agent's inventory.
2. The ground beneath the agent.
3. All squares immediately adjacent to the agent.

Parameters:

p - the predicate used to tell which object to grab.

Returns:

the first matching object, or null if not found

searchInvByHashcode

public GameObject searchInvByHashcode(java.lang.String hashcode)

Searches the agent's inventory for an object with the specified hashcode.

Parameters:

hashcode - the object's hashcode, as a string

Returns:

the object, or null if not found

searchMapUnderByHashcode

public GameObject searchMapUnderByHashcode(java.lang.String hashcode)

Searches agent's inventory and the ground under the agent for an object with the specified hashcode.

Parameters:

hashcode - the object's hashcode, as a string

Returns:

the object, or null if not found

runPostHooks

public void runPostHooks(boolean success)

Runs one of the event's post hooks. 99.9% of the time this is called by the game kernel after execute() runs. The return value from execute() is passed into this method along with the agent. However, in certain very rare cases, the event has to run its own post-hooks. For example, the DeathEvent kills a monster, which destroys its hook-list, so the game kernel can't run the post-hooks - so DeathEvent does it manually in the execute() method.

Parameters:

success - true to run the post hook, false for failed hook

runPreHooks

public void runPreHooks()

Runs the event's pre-hooks.

isRedirecting

public boolean isRedirecting()

True if there was a redirect operator detected at the end of the command: ">", ">>", "+>", or "+>>". Only Wizards can do this.

Returns:

true if the agent specified a redirect for the output of this command

isAppending

public boolean isAppending()

Returns true if the redirect-to-file operator was "+>>" or ">>".

Returns:

true if the redirect had a "+" in it

isSendingToAgent

public boolean isSendingToAgent()

Returns true if the redirect operator included a "+" to send the output to the agent as well.

Returns:

true if the redirection is going to the agent

getRedirectFile

public java.io.File getRedirectFile()

Returns the file that we're redirecting output to, if any.

Returns:

the File object, if the command had a redirect (">") in it.

getFilters

public java.lang.String[] getFilters()

Returns the filter strings being applied to this event.

Returns:

the filters, such as "sort -r" or "wc -l". Returns null if there are no filters.

getFilterObjects

public CommandFilter[] getFilterObjects()

Returns the parsed CommandFilter objects that will be applied to the message for this event.

Returns:

the CommandFilter objects, parsed from any filters such as "sort -r" or "wc -l" or "grep -i foo/bar". Returns null if there are no filters on the event output.

isPlayer

public boolean isPlayer()

Returns true if the event's agent is a Player (or wizard).

isWizard

public boolean isWizard()

Returns true if the event's agent is a Wizard.

isMonster

public boolean isMonster()

Returns true if the event's agent is a Monster (not a player).

fail

public boolean fail()

Issues the event's failure-message to the event's agent. Equivalent to event.message(event.getFailureMessage())

Returns:

false - makes it more convenient in event handlers, which can simply say "return event.fail()" if the event was vetoed.