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

[Glyph Lefkowitz]

I think this is a pretty clear description of when to return false, but I
believe it may have exposed a design flaw in the search path for TR --

It is quite common that an object will not want other objects to be able
to use a verb that it has exposed on it as an ablative object.  It is
pretty weird behavior for an object to be usable like that... (I.E.
something which you can "turn on" allowing you to "turn on" something else
"with" it)

You should never be able to "sit on Bob with chair" or "turn on Bob with
Lamp". (well, perhaps it were a very good looking lamp, and it was one of
Bob's worse days... but I digress)

I think that adding some initialization methods in verb like featureWith()
(for allowing the verb to be found by Reality on abletive objects)  
featureDirect() featureIndirect(String) (obvious) and featureOverride()
(for allowing the verb to be found on any object in the room or on the
room itself and override the default search pattern) might be a good idea,
except that that would necessitate rewriting all the verbs we've coded to
date...

In the meanwhile, do as James says with returning false, and remember that
verbObject can tell you where a given verb is found.

On Mon, 28 Jun 1999, James Knight wrote:

> 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.