Chapter 2: Objects and state

Things in the game world are represented by objects (hashtags) in the Dialog language. Dialog objects are thin; they are identifiers without any code or data inside them. They exist, as names, simply by virtue of being mentioned somewhere in the source code. But they have no contents. Instead, the game world is modelled using predicates where a predicate is a collection of rule definitions.

We will now extend our minimal example with two objects: A table (called #table) and a chair (#chair). We will give them names and descriptions, categorize them using traits (a kind of inheritable properties), and place them in their initial locations. All of this is achieved by defining rules:

Every rule definition starts with a rule head (the part within parentheses), which must begin at the leftmost column of a line in the source code. The rule head is optionally followed by a rule body (that’s the non-parenthesized text in the above example), which may continue onto subsequent lines, as long as those lines are indented by at least one space or tab character.

A double-percent (%%) in the source code begins a comment that lasts to the end of the line.

The rule body is a piece of code that can be executed. Plain text is an instruction to print that text. Some special characters (#, $, @, ~, *, |, \, parentheses, brackets, and braces) need to be prefixed by a backslash (\). No special treatment is required for apostrophes or double quotes.

Other instructions may appear within parentheses in rule bodies: For instance, (line) inserts a line break, and (par) inserts a paragraph break. Text in the source code can be formatted freely, because it is broken down internally into a stream of words and punctuation characters, and then reassembled, with space characters automatically inserted in all the right places. This process eliminates the risk of duplicate or missing spaces, line breaks, and paragraph breaks.

The resulting object description would look like this:

To reduce the repetitiveness of coding by rules, Dialog provides a bit of syntactic sugar: It is possible to set a current topic, which is an object name, by mentioning that object at the leftmost column of a line. Then, whenever an asterisk (*) appears in a position where an object name could go, it is understood as a reference to the current topic. This feature makes the code more concise, and easier to type out:

Thus, we have created two tangible objects in our room, given them source code names (#table, #chair), printed names (“wooden table”, “chair”), and descriptions to be revealed by the EXAMINE verb. We have also categorized the objects: The table is a supporter, which means that the player is allowed to put things on top of it. The chair is an on-seat, which is a special kind of supporter that the player may sit on. The standard library defines many other standard categories that may be used by stories, and we’ll take a closer look at them in the upcoming chapter on traits. The predefined categories include containers and in-seats (such as armchairs), as well as rooms.

We have also defined an initial location for each object. A location has two parts: A relation (#in) and a parent object (#room). In addition to #in, the standard library supports the relations #on, #under, #behind, #heldby, #wornby, and #partof.

The (descr $) predicate prints the external description of an object; what it looks like when viewed from the outside. Another predicate, (look $), prints the internal description of an object, i.e. what it looks like from the inside. This is used for room descriptions.

Let’s add a room description to our example game:

Try this game! You can LOOK, and then X IT, and SIT (on what? Answer CHAIR).

Did you miss the chair in the room description? In Dialog, as a general design principle, game objects do not call attention to themselves. They are assumed to be part of the scenery, and it is up to the story author to mention (or subtly hint at) their existence in the prose, like we did with the table. Nevertheless, there is a way to furnish objects with appearances, which are displayed in separate paragraphs of their own after the room description:

The room description would then turn into:

Appearances can be very handy for objects that move around during gameplay. This includes objects that the player might pick up, and drop in another room. We will learn more about such objects—and appearances—when we get to the chapter about items.

How does the game know that CHAIR refers to the chair object? By default, the standard library assumes that every word that appears in the printed name of an object, i.e. the body of the (name $) rule, can be used to refer to it. If the player types several words in succession, they must all refer to the same object, so WOODEN CHAIR does not match any object in this game. We can easily add extra synonyms to an object, using the (dict $) predicate:

Now the game would understand SIT ON THE WHITE CHAIR, for instance. Add some synonyms to the game and try them out!

What happens if you add “wooden” as a synonym for the chair, and type EXAMINE WOODEN? What about SIT ON WOODEN?

It’s easy to conjure up new predicates. We simply define one or more rules for them. For instance, we might want to put the primary construction material of our objects in a separate predicate that we call (material):

This predicate can then be queried from within rule bodies, like so:

We can use variables to pass parameters around. In the following example, a generic object description calls out to object-specific material and colour predicates. The standard library doesn’t know about these predicates; we just created them by defining rules for them. The library queries (descr $), and we take it from there:

Note that the rule for (descr `player), on line four, supersedes the generic rule for (descr $Obj), at the very last line. This is solely due to the order in which they appear in the source code. When coding in Dialog, make sure to always put specific rules before generic rules.

Variables are local to the rule definition in which they appear: In the example, $Obj is only available from within the last rule. If we were to use a variable named $Obj inside one of the other rules, that would be a completely unrelated variable.

Queries either fail or succeed. When a predicate is queried, each rule definition is tried in program order, until a match is found. If there is no matching rule, the query fails. As a general rule of thumb, predicates that print text should be designed to always succeed. Therefore, we’ll often want to put a catch-all rule at the end of the program, with a wildcard ($) in the rule head:

The standard library provides a catch-all rule for (descr $), printing a stock message along the lines of “It seems to be harmless”. But for our material and colour predicates, we have to provide our own catch-all rules.

At runtime, objects of the game world are organized into object trees. Every object has (at most) one parent, and a relation (in, on, under, behind, held by, or worn by) to that parent. The root of a tree has no parent. Sometimes you will run into the expression “the object tree of the game”, as though every object were part of a single, huge tree with only one root. Technically, it is more correct to say “the object forest of the game”, because there can be more than one root object. Rooms don’t have parents, so every room is the root of a tree.

In the Dialog standard library, the object forest is encoded using two predicates: ($Object has parent $Parent) and ($Object has relation $Relation). For brevity, there’s an access predicate that combines them into a single expression: ($Object is $Relation $Parent). We have already seen that one defines the initial location of an object like this:

and, due to the access predicate, the above is equivalent to the following pair of definitions:

From within a rule body, you may query the access predicate to determine the current location of an object:

The output of the above code might be:

With a multi-query, you can backtrack over every object that has a particular location:

The location of an object is dynamic, which means that it can be modified at runtime using the (now) keyword:

The standard library also uses dynamic predicates to track the internal state of game world objects. For instance, ($ is closed) succeeds when a particular openable object (such as a container, or a door) is currently closed. The access predicate ($ is open) is defined as its negation, ~($ is closed), allowing both forms to appear as queries, now-expressions, and initial value definitions.

A convenience predicate, (open or closed $), prints the word “open” if the given object is open, and “closed” otherwise. The same thing can of course be coded explicitly with an if statement.

The following dynamic predicates are used by the library:

Hidden objects, ($ is hidden), can be in scope (meaning that the parser will recognize them as nouns), but the library is careful not to mention them. Thus, if the player carries a pink slip, and the current room contains a pink elephant that is hidden, then EXAMINE PINK will print the description of the slip, with no disambiguating questions asked. EXAMINE PINK ELEPHANT will examine the elephant, as would EXAMINE PINK if the slip weren’t there. The idea is to improve the experience of replaying a game, while avoiding spoilers on the first playthrough.

Hidden objects can be revealed either by directly updating the flag, (now) (elephant is revealed), or by querying (reveal $) for the given object. A hidden object is also revealed implicitly when its name is printed, or when (notice $) is invoked on it.