Screen Display

Interactive fiction is primarily a text-based medium and this chapter discusses all the features of JACL that relate to the output of text. Depending on the Glk library used, JACL interpreters may also provide the ability to add graphics and sound to your games. The use of these features is covered in the following chapter, Glk and Multimedia.

The WRITE Command

The write command is the most flexible method of outputting text. It takes one or more parameters, each separated by a whitespace, and prints the result to the screen. A parameter can either be plain text, a string or integer variable, a string or integer constant or an object macro.

For example, the following command:

write Hello, world!

contains two separate parameters, the string Hello and the string world! (the comma after hello is considered to be white space.) When executed it will produce the following output:

Helloworld!

This is obviously not the desired result. The correct way to print this familiar greeting is:

write "Hello, world!"

The reason for this demonstration of how not to print text is that it demonstrates how the write command operates. Each of the parameters supplied to the write command is printed directly after the one before it. In the second example a single parameter containing both a space and comma is printed.

As with all other JACL commands, any single parameter that contains spaces must be enclosed in quotes. Failing to do this is a common cause of error.

Special Characters

When printing text, the write command recognises the following special characters:

To print the first two special characters (^ and ~) literally, the words caret and tilde should be used as parameters of a write command.

Below is an example of the use of the above special characters:

write "~Hello,~ said the boy.^"
write "~Hello,~ said the girl in reply.^"

Each of these write commands prints a single parameter enclosed in quotes and together will display:

"Hello," said the boy.

"Hello," said the girl in reply.

Printing the Value of Variables

If the value of a variable is to be printed, as opposed to verbatim text, the name of the variable must be entered as a separate parameter that is not enclosed in double quotes. For example, consider the following line from the +score function of the standard library, a write command with five parameters:

write "Your score is " score "% in " total_moves " moves.^"

The output of this five parameter command will vary depending on the current value of the two variables being printed. Typed as the very first command of the game it would display:

Your score is 0% in 0 moves.

Printing the Value of Item Elements

The current value of object and location elements may also be printed using a write command. This is done by enclosing the name of the element in brackets directly after the object or location label. For example:

write "The dial is set to " dial(status) "Mhz.^"

The elements of each object and location are stored in a sixteen element array (0-15). A number between 0 and 15 can be used between the brackets as an index to the object element rather than it's name. For a mapping of default element names to index numbers, see the chapter Definitions in Detail. Constants can also be defined as a way of renaming any given element to a name that more clearly indicates its purpose. For example:

constant fuel_left	2

{+show_status
set submarine(fuel_left) = 42
write "FUEL: " submarine(fuel_left) ^
}

This code defines fuel_left as the constant 2, then sets the second element of the object submarine to equal 42. Finally, it uses a write statement to output the current value of submarine(2) by using the constant fuel_left to improve the readability of the code. This results in the following output:

FUEL: 42

Printing the Names and Descriptions of Objects

As you can see in the file verbs.library, it is a common need to print the short description of the object or objects that the player referred to in his or her last move. This is done using the integer variables noun1 and noun2. When used as parameters of a write command, these variables may be followed by either a {the} or a {list} macro to display the object's short description. Given the following object:

object wooden_box : small wooden box
  has          CONTAINER CLOSED CLOSABLE
  short        a "small wooden box"

if the player refers to this box as the first object in their command, then the write command:

write noun1{list}

would display, "a small wooden box", while

write noun1{the}

would display, "the small wooden box".

If you require the output to be capitalised when using these macros, use {The} or {List} instead. For example, with noun1 still set to the box object:

write noun1{The} " is no good to eat.^"

will display, "The small wooden box is no good to eat."

Sentences Referring to Varying Objects

There are several other macros that may be used with the write command to assist in constructing sentences that refer to different objects at different times. They are designed to simplify the process of displaying the correct text for objects based on whether they have the attributes PLURAL, ANIMATE or FEMALE. They are:

Printing the Value of Strings

If the value of a string is to be printed, as opposed to verbatim text, the name of the string variable or string constant must be entered as a separate parameter that is not enclosed in quotes. For example:

constant game_title  "Tutorial Game"
constant game_author "I. F. Author" 

{+intro
write "Welcome to " game_title " by " game_author ".^"
}

The output of the +intro function will be:

Welcome to Tutorial Game by I. F. Author.

The PRINT Command

The print command is the primary way to output plain text. Unlike the write command, the values of variables, macros or string constants cannot be displayed. In fact the only thing that can be displayed by a print command is plain literal text. A print command has no parameters. On executing a print command the interpreter will begin printing all the text from the following line onwards until it encounters a line with a period (.) as the first non-whitespace character. The lines of text will be displayed verbatim with the following considerations:

1. if a line does not end with a caret (^), an implicit space will be printed after the line and the following line of text will continue straight after it, following the usual word wrapping rules;
2. if a line ends with a backslash (\) or a caret (^), no implicit space will be added to the line;
3. a vertical bar will be translated into a space to allow formatting such as paragraph indenting to be done.

Below is an example of the print command in action (note that the colon after the word print is optional whitespace):

{+intro
clear
print:
   This text will be printed to the screen and
   word wrapped in the appropriate places.
   The backslash at the end of this line will prev\
   ent an implicit space being printed as will
   the caret at the end of this line.^
   ||These two vertical bars will allow this line
   to be indented two spaces.^
.
}

The LOOK Command

The look command will print the long description of the current location and any visible objects that are in the current location. A look command is executed implicitly by the JACL interpreter whenever a description of the player's current location is required. This is at times such as when then player moves into a location for the first time or restores a saved game.

If the player has set the game to verbose mode (DISPLAY_MODE = 1), locations will not be given the attribute VISITED.

The very first thing the look command will do is remove the attribute VISITED from the current location. It will then execute the global function +before_look. If this function exists, and returns true, nothing more is done. If it does not exist, or returns false, the function +title will be executed. This function is an opportunity to print extra information that is potentially relevant to all locations. For example, the +title function in frame.jacl tests if the player is currently sitting down and displays the text "(sitting)". It is also common to add the following line to the top of +title to give each location description a title:

write here{The} ^

Next the look function associated with the current location is executed. After this has finished, the interpreter will display the text supplied by the long property for each object that is in the current location and doesn't have a mass of scenery.

If the long property of an object is set to function, that function will be executed. This is useful for descriptions that are either too long to fit in a single line of code or change during the course of the game. If the long property is not set to function, the property text is displayed verbatim.

The final step in the process is that the global function +after_look is executed.

It is a convention to have a look command at the end of the +intro function so the player can see where they are and what objects are nearby when the game begins.

The MORE Command

The more command will print a message and then wait for the player to press a key before continuing. The message to print is passed as the only parameter of a more command. If no message is provided, the message [MORE] is used as a default. Below is an example of using the more command with a custom message:

more "Hit any key to continue"

Back to Contents