Screen Display

When a game is played using the web-based JACL interpreters, the output from each of the player's commands is returned in the form of a complete HTML page. These pages must be created by your game, including the HTTP header. The file frame.jacl contains two functions (+header and +footer) that contain serveral write commands that output both the HTTP and HTML header for you. If you include these functions in your game you will only be required to display the response to each of the player's commands. Feel free to modify the +header and +footer functions to suit your desired presentation. For more information, see the chapter on HTTP and HTML.

When a game is played using the console-based JACL interpreter, all text output is sent straight to the player's screen. There are several commands specific to outputing text using the console-based JACL interpreter that are detailed in this chapter.

The WRITE Command

The write command is the primary method of outputting text. It will accept one or more parameters, each separated by a space. A parameter can either be plain text, a variable, an integer constant, a string 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 circumflex and tilde should be used as parameters of a write command. The jacl interpreter must use the words lessthan and greaterthan in place of left and right angle brackets while the cgijacl interpreter will print them normally. This is because the jacl interpreter will strip out all angle brackets and any text inbetween them in order to ignore any HTML tags placed within the text.

write "<p>Use the command: bet " lessthan 
write "amount" greaterthan " dollars.^"

In most cases, when using the cgijacl interpreter, a newline printed using the caret character will be ingnored as whitespace by the browser. This extra whitespace can be of use to make the resulting HTML more readable. The cgijacl interpreter will also print an implicit newline after every write command. If this is not desired, the print command operates exactly the same as the write command except it will not print an implicit newline.

One place where the caret character is extremely important when using the cgijacl interpreters is the +header funtion of web-based games. The end of an HTTP header is delimited by two blank lines that must be printed from this function. Failing to do so will prevent the player's browser from displaying the page.

Below is an example of the use of the tilde character:

write "<p>~Hello,~ said the boy.^"
write "<p>~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 oppossed to verbatim text, the name of the variable must be entered as a separate parameter. For example, consider the following line from the +score function of the standard library — a write command with five parameters:

write "<p>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 "<p>The dial is set to " dial(status) "Mhz.</p>"

The elements of each object and location are stored in a sixteen element array (0-15). A number between 0 and 14 can be used between the brackets as an index to the object element rather than it name. This is most useful when a variable is used in place of an absolute number in order to iterate through several elements. For a mapping of 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:

variable INDEX
constant fuel_left	2

{+show_status
write "<p>FUEL: " submarine(fuel_left) <br>^
set INDEX = 3
repeat 
   write "<p> INDEX ": " submarine(INDEX) <br>^
   set INDEX + 1
until INDEX = 11
}

Printing the Names and Descriptions of Objects

As you can see in the file verbs.library, is it 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 noun1 and noun2 object pointers. When used as parameters of a write command, these object pointers 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 our box object:

write <p> noun1{The} " is no good to eat."

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

Two other available macros, for use primarily in web-based games, are {names} and {+names}. These macros both output all the names of the specified object. The former prints a space before each name, while the later prints a plus sign before each name. These macros are used to create commands that are sent to the interpreter for the player when he or she clicks on an HTML element. This could be either an input control on an HTML form or a hyperlink. Names sent as the value of an input control must be separated by spaces. Names sent as a URL parameter of an hyperlink must be separated by plus signs. For example:

write "<form>"
loop
   write "<input type=~radio~ noun=~command~ value=~"
   write noun3{names} "~>"
endloop
write "<input type=~submit~>"
write "</form>"

write "<a href=~" $url "?user_id=" $user_id 
write "&command=take" noun1{+names} "~>Take " noun1{the} "</a>^"

Like the {list} and {the} macros, these macros can be used with any object pointer or label. For information on commands for automatically creating input controls and hyperlinks see the chapter on HTTP and HTML.

Sentences Referring to Plural Objects

There are several other macros that may be used with the write command when coding the default action for verbs. They are designed to simplify the process of displaying the correct text for objects based on whether they have or haven't the attribute PLURAL. They are:

Printing the Value of String Constants

If the value of a string constant is to be printed, as oppossed to verbatim text, the name of the string constant must be entered as a separate parameter. For example:

string TABLE_START "<table><tr><td>^"
string NEW_ROW     "</td></tr><tr><td>^"
string TABLE_END   "</td></tr></table>^"

{+test
write TABLE_START Hello^ NEW_ROW World!^ TABLE_END
}

The output of the +test function will be:

<table<tr><td>
Hello
</td></tr><tr><td>
World!
</td></tr></table>

Special Tokens

The last line of the sample code above manually creates an HTML hyperlink that represents a command the player can perform with a single mouse click. To create this hyperlink, two speical tokens are used: $url and $user_id. These tokens are uesd exclusively with the cgijacl interpreter to create web-based games. When used as a parameter of a write command, $url will display the location or URL of the JACL game (minus the machine name), while user_id will display the player's user ID.

It is very important in web based games that the player's user ID is passed with every move. This can either be as a URL parameter, like the example above, or as a hidden field in a form.

If the player enters a command that allows an arbitrary text string, this string can be displayed using the token $text. For example:

grammar say $text >say

{+say
ifstring $text contains "microsoft"
   write "<p>Watch your language!</p>"
   break
endif
write "<p>You say, ~" $text ".~</p>"
}

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 does not break false, nothing more is done. If it does not exist, or does break false, then 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 the name of a 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 the name of a function, the property text is displayed verbatim.

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

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

Console Presentation

When playing a game using cgijacl, all presentation is achieved through the use of HTML tags. The jacl interpreter will automatically filter out any HTML tags from a write command and and provides some extra commands to assist with screen presentation.

The CENTRE Command

The centre command accepts a single parameter of plain text and displays it centred on the current row based on the configured screen width. The screen width can be set either by exporting the environment variable COLUMNS or adding a columns directive to the jacl.conf file. The player can also set the screen width during the course of the game by using the columns command. The interpreter will automatically move to a newline after printing text with the centre command.

The RIGHT Command

The right command accepts a single parameter of plain text and displays it on the far right of the screen based based on the configured screen width. The interpreter will automatically move to a newline after printing text with the right command.

The ANSI Command

The ansi command is used to output ANSI terminal codes. The ansi command accepts a single string containing the ANSI code to output, minus the escape sequence. Here is an example of an ansi command to set the text to bold:

ansi [1m

Below is a table showing some of the available VT100 ANSI codes:

The DELAY Command

The delay command accepts a single integer parameter and sets the time to pause between printing each character in milliseconds. This is used for simulating a slow terminal connection at appropriate points games.

The RULE Command

The rule command will print a complete line of dashes based on the current values of columns.

The MORE Command

The more command will print a [MORE] and wait for the player to press a key before continuing.