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

# Changing Data

It is often desireable to change the value of data that is defined when the game is first loaded. This is achieved using the set command for integers, objects and locations (see Typecasting below), and the setstring command for text.

## The SET Command

Any set command must be of the following format:

    set container operator value [ operator value...]

The set command enables you to modify the current value of the specified container. A container is either an object element (see the chapter Definitions in Detail for more information), a variable or an item pointer such as noun1 or here. The value can be an integer, integer constant or any other container whose value you wish to copy.

The following is a list of operators that can be used with the set command:

Operator | Description
--- | ---
= | Set the value of the specified container to the specified value.
+ | Add the specified value to the current value of the specified container.
- | Subtract the specified value from the current value of the specified container.
/ | Divide the current value of the specified container by the specified value.
* | Multiply the current value of the specified container by the specified value.
% | The modulo operator calculates the remainder value of the specified container when divided by the specified value.

The following example demonstrates how to add 7 and 8 then divide the result by 5:

    integer TEMP

    {+maths
    set TEMP = 7 + 8 / 5
    }

This line of code can be read as a container to apply the operations to followed by groups of two parameters: an operator and a value. In this case the three operations are:

1. make TEMP equal to 7
2. add 8 to TEMP
3. divided TEMP by 5

| Although all JACL commands require whitespace between each parameter, it is especially easy to forget the space between the container and the operator or the operator and the value. It is, of course, valid to have a command such as:
    set BANK_BALANCE = -42

| The set command also has the ability to use the current value of a string as the name of the container or value being referred to. For example, if an integer variable called counter was defined, its value could be set to 1 using the following code:
    integer counter 0

    {+modify
    setstring indirection "counter"
    set indirection = 1
    }
This technique can be particularly useful when the need arises to pass a reference to an array as a function argument.

## Type Casting

The JACL language allows the definition of complex types such as objects and locations at load time, but once the game is running, the only types that can be modified are integers and strings. When objects and locations are created they are assigned an integer value. The first object or location defined is given the number one, the remainder are numbered sequentially in the order they appear in the source file. For the purposes of numbering there is no distinction between objects and locations. Because of this, it is possible to use an integer variable wherever an object label is expected. For example:

    integer VARIABLE

    {+code
    set VARIABLE = small_frog
    set noun4 = VARIABLE
    set noun4 + 1 ; NOTE: noun4 will now equal the item defined
                  ; directly after small_frog in the game file.
    set lantern(status) = noun1(parent)
    set max_rand = objects
    set sword(parent) = random
    }

This code sets an integer variable to the index of the object small_frog. It then sets the internal object pointer (another integer variable) noun4 to that value. This pointer is then incremented to point to the object or location that is definied directly after the small_frog. After that, the current parent of the object pointed to by noun1 is stored in the status element of the object lantern. Finally, max_rand is set to the constant objects (the number of objects and locations in the game), and the parent of the object sword is randomly set to one of the object or locations from in the game.

As you can see, all these variables, object elements, object labels, object pointers and constants simply resolve into integers and can be used interchangeably.

| The only real potential danger in the above examples it that of setting one of the object pointers to a value less than one, or greater than the internal number of the last object. The index of the last object or location (which is also the number of object and locations in the game) is stored in the constant objects.

## The SETSTRING and ADDSTRING Commands

The setstring command is in many ways similar to the write command. Where a write command can take a list of parameters and will output the result to the screen, the setstring command can take an identical list of parameters and store the result in a string. The first parameter of a setstring command is a string to store the resulting output in. All other parameters constitute the text to be stored. Any previous contents in a string are overwritten by a setstring command. Below is an example of the setstring command in action:

    string buffer "empty"

    {+some_function
    setstring buffer "You are currently in " here{the} " on turn " total_moves ".^"
    }

The addstring command works in a similar way except it does not erase the current contents of the string being written to.

## The PADSTRING Command

The padstring command takes three parameters. The label of the string to fill, the text to fill the string with and an integer specifying the number of times to copy the text into the string. This command primarily exists to assist with presentation within the status window. For example, to print a blank line in the status window, the text that will by copied is a single space in quotes (" ") and it will be copied status_width times. The code below demonstrates creating a string called status_text that contains enough spaces to fill a line in the status window:

    string status_text

    {+update_status_window
    padstring status_text " " status_width
    }

Back to Contents