4.1 Verb Methods

4.1.1 Verb Methods Are Always Public

Except for the special case noted in See Control Verbs, methods used for a verb must always be publicly accessible, or they won't be usable. This just means adding a call like this to the init method on the class:

     {self addPublicMethod( method: myVerb ) }

4.1.2 Verb Method Default Arguments

caller

The objectRef for the calling object.

player

The objectRef for the player object.

language

The language of the verb itself, for when the player is able to run verbs in multiple languages (i.e. help has language en, sidju has language lb).

result

The result of the verb, a record that indicatats success or failure of the method, among other things. It is described thoroughly in the next section. Result must be set at some point in the verb, or an error results when the verb exits. A common code fragment at the bottom of verbs to handle this issue is as follows:

          if {IsFree Result} then
              Result = result(
          	status: success
          	certainty: 1.0
              )
          end
     

This assumes that if the end of the verb has been reached without Result already being set, everything must have gone well.

force

If force is set to true, no checking should be done to see if the current object is the one the verb call was intended for: it is assume that this object is, in fact, the correct choice. Such checking would be things like name and alias matched, for example.

4.1.3 Verb Method Result Records

The result argument gets filled with a with a record similar to the pseudo-code one below:

     result(
     	status: success|failure|other  -- default success
     	certainty: float from 0.0 through 1.0 -- default 1.0
     	comments: <localized string> -- default nil, only relevant to failures
           )

There are a couple of problems that this structure is intended to address.

The first is that we want the option of delivering a specialized failure message from whichever object and method knows best what the problem was if things didn't work. The difficulty there is that many failure will be from objects that really are *not* the one the verb call was intended for, so we don't want to return their errors to the user.

The second problem is that on object might honestly not be sure if a verb call, that would in fact be successful, is meant for itself. For example, if an alias is used, or the name matches but only in a case-insensitive fashion, those matches should introduce some doubt as to whether the object in question is really the one the verb call was intended for.

The solution to these is the certainty field. The certainty field is a number from zero (0) to one (1), inclusive, which indicates how certain the verb method is that it was the intended target for the original verb call. In the case of target uncertainty, the status should be 'other'.

The certainty field is ignored if the status is success.

If no status field was set to success out of a group of verb method checks, the result records are sorted by certainty. The highest non-zero value whose status is *not* failure is called again with the force argument set to true. This selects, out of the methods that weren't sure they was being talked to, the method that was most sure it was the intended target. Verb methods should skip all certainty checks when force is set to true.

If there are only failures, the failure with the highest certainty has its comments field de-localized and sent to the player to help them figure out what happened.

Note that non-verb methods often also have result arguments. If so, they will often not return a certainty feature as part of their result record, because that sort of thing is the verb method's job to determine.