The JACL Author's Guide
Description: Documentation for the JACL Adventure Creation Language.
Keywords: JACL,tutorial,programming,programmers,guide,manual,documention,instructions

# Object Resolution

A large part of playing interactive fiction involves referring to the objects and locations that make up the game's world. The information in this chapter will assist you in coding your game in such a way that the JACL parser will select the object the player intended as often as possible. All references to objects made by the player are parsed for the following possible structure:

    objects [from other objects] [except objects [from other objects]]

The JACL parser will build two lists of objects for any reference made by the player. The first will contain all the objects for inclusion while the second will contain all the objects referred to after the word except for exclusion. Once the two lists have been built, the second list will be subtracted from the first list. Both lists can make multiple use of the word from to refer to objects, however, the word except can not appear more than once.

## Object Naming

When the player refers to an object during the course of the game they may use as many or as few of the object's names as are required to uniquely identify it. For example, consider the following three objects:

    object ball_1: ball
    object ball_2: small red ball
    object ball_3: big red ball

Presuming all these objects were in the current location, if the player referred to ball, then ball_1 would be selected. This is because the JACL interpreter divides the number of names an object has by the number of names supplied to come up with a best match. Although all three objects have the name ball, ball_1 matches 100% while ball_2 and ball_3 only match 33%. If the player referred to red ball, then ball_1 would automatically be excluded, as it does not have the name red. On the other hand, both ball_2 and ball_3 have the names red ball, and both would match 66%. In this case, a message would be displayed stating that the reference was ambiguous. If the player referred to big, then ball_3 would automatically be selected as neither of the other two objects have the name big at all.

It is important to be aware of the number of names that you give each object, and how they relate to each other. It is generally best to have two similar objects have the same number of names, although in some cases you may wish to nominate one to be the default by giving it less names.

For example, in The Unholy Grail there are two objects: beige agar and brown agar. To avoid problems when looking up agar in the encyclopedia, a third object named simply agar was added. This object stays permanently in limbo and therefore does not affect any physical manipulation of the two real agar objects. It does, however, get selected when using commands such as ask_about that accept objects that are *anywhere.

It also possible to define plural names for an object. When the player uses a plural name all the objects that have that plural name will be selected. For example, the above objects could all be given the plural name balls using the following code:

    object ball_1: ball
       plural		balls
    object ball_2: small red ball
       plural		balls
    object ball_3: big red ball
       plural		balls

If during the game the player was to type the command take balls, all of the above objects would be selected and three separate take commands would be issued. It is the use of the plural name that tells the parser that a reference to multiple objects was intended and that the reference is not ambiguous. It is also possible to further qualify a reference to a plural name by using one or more regular name. For example, the command take red balls would result in only the small red ball and the large red ball being taken.

## Disambiguation

It is also possible for each object to have the associated function disambiguate to assist in the process of disambiguation. The parser will attempt to call this function on every object that is a possible result for an ambiguous reference that needs to be resolved to a single object.

When called, this function will be passed a single argument being the context in which the ambiguous reference was made. The possible values for this argument are:

Value | Description
--- | ---
0 | The list of objects for noun1.
1 | The list of objects for noun2.
2 | Exceptions to the list of objects for noun1.
3 | Exceptions to the list of objects for noun2.
4 | The list of objects noun1 should be from.
5 | The list of objects noun2 should be from.
6 | The list of objects noun1's exceptions should be from.
7 | The list of objects noun2's exceptions should be from.

To demonstrate, consider a game that had two objects, a red ball and a red book. The following disambiguate function could be added to the book in order to allow the commands read red and look in red to prefer the book to the ball instead of displaying the usual "ambiguous reference" message:

    object red_book : red book

    {disambiguate
    if arg = 0
       ifstring command = "read"
          return true
       endif
       ifstringall command[0] = "look" : command[1] = "in"
          return true
       endif
    endif
    return false
    }

This function makes use of the command array to look at the words used so far in the player's command. Unfortunately as the command has not been fully processed the single resultant action is not yet known. This function communicates its decision to the parser via its return code. If this function returns false (or doesn't exist), the object will be included in the list of possible objects and processing will continue as normal. If this function returns true this object will be instantly selected as the object the player was referring to. If this function returns -1 this object will be excluded from contention and processing will continue as normal. If all objects exclude themselves from contention the first will be selected.

It is important to keep in mind that this function is only called when an ambiguous reference is made. The command read ball will still attempt to read the ball, it is only a command like read red that results in an ambiguous reference that will cause these functions to be called. It is also advisable to use this facility sparingly as it departs from the regular disambiguation rules and may lead to confusion for the player. Used appropriately, however, it can help to solve a frustrating disambiguation problem that has been identified during play testing.

Back to Contents