[Divunal-devel] Proper usage of return values from a Verb

[James Knight]

There seems to be some confusion over when a verb should return false. I
hope this will clear it up.
The return value from Verb.action() is not (like some documentation seems
to say) an indication of whether the verb succeeded or failed. Rather, it
is an indication of whether the verb is appropriate to use or not. For
example, lets take the "Sit" verb. If you type "sit on chair" Reality will
go through a complicated search process to find an object with the
specified verb on it. It will stop with the first one it finds. It searches
in the following order:

1) the object in a 'with' clause
2) the object in an indirect object clause
(in/on/to/at/from/through/except/into)
3) the direct object (ie the phrase right after the verb)
4) the room itself (or if you're on a chair or something, the chair you're
on, and then the room)
5) the player's abilities
6) ANY object in the same room.
7) ANY object the player is carrying
Only after not finding the verb in any of those places will it give up.
Therefore, it is important for your verb to not work when it is
inappropriate.

Lets take a real example. divunal.common.Sit is a verb on a 'red chair'.
There is also a lantern in the same room. "Sit on chair" should run sit on
the chair and will do so (from case 2). However, "Sit on lantern" will (if
no extra checking is done) get to case 6, and try to use the "sit" verb
from the chair. This is incorrect behavior. Note that if the user does "sit
on lantern with chair" it will try to run the "sit" verb from the chair in
case #1. This is even more problematic if there are two chairs in the room.
Lets say chair 1 and chair 2 have different "sit" verbs on them. The user
can then cause the game to use the *wrong* one intentionally by doing "sit
on chair 1 with chair 2". That will use chair 2's sit because the with
clause is checked first.
To fix this behavior, you can return false from your verb. What this means
is essentially "I am the wrong verb, keep looking".

So e.g. to make Sit work properly, you want to check that the object that
the verb was found on is the same as the object you're trying to sit on. If
it isn't, then don't run this verb, BUT keep looking for another one that
may be appropriate.
You can do this by adding the following code: if(d.verbObject() != box)
return false;
(d.verbObject() returns the object that the verb was found on, and box is
previously set in Sit.java to be d.indirectObject("in") or
d.indirectObject("on"))

The same should be done for Stand. However, in stand's case, the verb is
only applicable if you are currently on the object that the verb was found
on. In java, this translates to: if(d.verbObject() != d.subject().place())
return false;

Now that those modifications are made, if the user types "sit on lantern"
it will properly give a generic error message. And, if in the second
example, the user types "sit on chair 1 with chair 2" it will properly use
chair 1's Sit. Anyways, I hope this clears things up somewhat, so you can
all write better verbs. If my explaination is lacking in some way please
tell me so I can correct it.
-James

--
You are in a maze of testy little Java VMs, all subtly different.