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

# Special-Purpose Commands

## The POINTS Command

The points command is used to award points to the player and must be followed by a single integer indicating the number of points to be awarded. The awarded points will be added to the integer variable score. Below are two examples of the points command being used:

    points 10
    points gold(points)

When the points command is used the following message will be displayed to the player:

    [YOUR SCORE JUST WENT UP BY n POINTS]

## The PROXY Command

The proxy command is used to issue an in-game move as though it was typed by the player and must be of the following syntax:

    proxy Move

The specified Move may consist of multiple parameters, built up from plain text, variables, constants or macros. When the move is issued by the proxy command, all the normal testing will take place and all usual messages will be displayed. The most common use for the proxy command is to translate one command into another similar command. For example, sometimes two different commands can be mapped to the same function:

    grammar put *held in *here     >insert
    grammar insert *held in *here  >insert

With the above two grammar statements only the verb is different so mapping them to the same function is possible. In some situations, however, this is not possible as the nouns appear in a different order. Below is an example of how the proxy command can save the day:

    grammar look at *here through *held >look_at_through

    {+look_at_through

    ;main function code tied to this syntax

    }

    grammar look through *held at *here >look_through_at

    {+look_through_at
    proxy "look at " noun2{names} " through " noun1{names} ; This will cause
                                                           ; the alternate
                                                           ; syntax to be used
    }

When the second syntax is used by the player, the only action is to execute a a proxy command. This issues a command on the player's behalf that matches the first syntax, therefore arriving at the main function with noun1 and noun2 pointing to the correct objects.

The macro {names} is almost exclusively used with the proxy command and outputs all of the names of the object separated by spaces. For example, the following code will issue the command "set safe dial to 42":

    object dial : safe dial
     short		the "safe dial"

    {set
    execute +build_command<this<42
    }

    {+issue_set
    proxy "set " arg[0]{names} " to " arg[1]
    }

| Don't forget to put spaces before and after any macros or variables used in a proxy command.

## Trigonometry

JACL provides a set of trigonometric commands to help model a two dimensional space. Each object in JACL has the integer elements x, y, bearing and velocity. The values of these elements are read and updated by the following three commands.

## The POSITION Command

The position command is used to change an object's x and y elements to simulate it moving on a two-dimensional grid. The movement that occurs depends on the current values for the object's bearing and velocity. A position command is simply followed by the label of the object to be moved:

    set ship_object(bearing) = 180
    set ship_object(velocity) = 100
    set ship_object(x) = 500
    set ship_object(y) = 500

    position ship_object

The above code will set ship_object(x) to equal 500 and ship_object(y) to equal 400.

## The BEARING Command

The bearing command is used to calculate the angle from one object to another based on their current x and y values. A bearing command is followed by a variable to store the calculated angle in, the object to measure the angle from, then the object to measure the angle to. For example:

    bearing INDEX lighthouse ship
    write "Bearing from " lighthouse{the} " to "
    write ship{the} ": " INDEX " degrees.^"

The above code calculates the bearing from the object lighthouse to the object ship in degrees (0 - 359), and stores the result in the variable INDEX. This calculation is based on the current values of lighthouse(x) and lighthouse(y) relative to the current values of ship(x) and ship(y).

## The DISTANCE Command

The distance command is used to calculate the distance between two objects based on their current x and y values. A distance command works in the same manner as a bearing command:

    distance INDEX lighthouse ship
    write "Distance from " lighthouse{the} " to "
    write ship{the} ": " INDEX ^

The above code calculates the distance between the object lighthouse and the object ship and stores the result in the variable INDEX. This calculation is based on the current values of lighthouse(x) and lighthouse(y) relative to the current values of ship(x) and ship(y).

## The ASKNUMBER AND GETNUMBER Commands

The commands asknumber and getnumber prompt the player to input a number between a particular range and wait for a response. The only difference between the two commands is that getnumber will continue to ask the player for a valid response, only returning when a number between the upper and lower limit is entered. Both of these commands use the following syntax:

    asknumber StorageVariable LowerLimit UpperLimit

StorageVariable is the integer variable used to store the number entered by the player. LowerLimit and UpperLimit indicate the inclusive range of numbers that are acceptable. For example, below is some code that prompts the player to enter a number between 1 and 5 (inclusive), and stores the answer in a variable called RESPONSE:

    integer RESPONSE
    integer UPPER       5

    {+ask_player
    ...
    asknumber RESPONSE 1 UPPER
    write "You typed " RESPONSE .^
    }

When using the asknumber command, if the player enters an invalid response, -1 will be placed in the storage variable and the next line of code will be executed.

## The GETSTRING Command

The command getstring will prompt the player to enter an arbitrary string of text. The only parameter of a getstring is the name of the string variable to store the player's response. Below is an example of the use of the getstring command:

    string players_name

    {+intro
    write "What is your name? "
    getstring players_name
    write "Hello " players_name "!^"
    }

## The GETYESORNO Command

The command getyesorno will prompt the player to enter yes or no. It will repeatedly prompt the player to enter a valid response until they do so. The only parameter of a getyesorno command is the integer variable used to store the player's response. If the player types yes (or y), the variable will contain the number 1. If the player types no (or n), the variable will contain the number 0. Below is an example of the getyesorno command in action:

    constant hints		5

    {+ask_player
    write "Would you like hints?^"
    getyesorno player(hints)
    if player(hints) =  1
       write "You typed yes.^"
    else
       write "You typed no.^"
    endif
    }

## The SAVEGAME and RESTOREGAME Commands

These commands can be used to access the internal functionality to save and restore the current game state. Both of these commands require a container to be passed as a parameter. This container is used to store the return code of the command. If the save or restore operation fails, an appropriate error message will be displayed and the supplied container will be set to false. If the save or restore operation is successful, the supplied container will be set to true and no message will be displayed. Both commands accept an optional second parameter that is a string to use as the filename. If this parameter is not supplied the Glk library will prompt the player to select a file. A common use of these commands is to define the functions +save_game and +restore_game to override the internal implementation of this functionality. For example:

    variable ANSWER
    variable RETURN_CODE

    {+restore_game
    write "Are you sure you wish to restore a saved game?^"
    getyesorno ANSWER
    if ANSWER = 0
       write "Returning to game.^"
       return
    endif
    restoregame RETURN_CODE
    if RETURN_CODE = true
       print:
          "You cast the spell of time travel and return to the past...^"
       .
    endif
    }

The ability to supply a filename can be used to either allow the player to supply the filename directly after the save command, or implement a system of auto-saving every tenth move such as this:

    {+eachturn
    set save_timer = total_moves
    set save_timer % 10
    if save_timer = 0
       set save_count + 1
       setstring filename "autosave"
       addstring filename save_count
       addstring filename ".sav"
       savegame RETURN_CODE filename
    endif

## The ENDGAME Command

The endgame command stops the current game and provides the player with the following options:

    Please type S to start again, R to restore, U to undo or Q to quit:

## The TERMINATE Command

The terminate command will directly initiate the termination of the JACL interpreter.

## The UNDOMOVE Command

The undomove command will take the game back to the state it was in prior to the player's last command.

Back to Contents