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

# Movement

## The MOVE Command

The move command is used to transport an object within your game world and uses the format:

    move object to destination

The object can be any object label, object pointer or the integer index of an object, while the destination can be any item label, item pointer or the integer index of an item. In essence, the move command will set the parent element of the object to be equal to the destination. In addition to this, it performs several functions relating to the mass of the object that is being moved. For example, the command:

    move note to box

will, in addition to moving the note to be a child of the box, automatically increase the capacity property of the object (if any) that the note was in before the move command, and decrease the capacity property of the box. This reflects the decreased burden on note's previous parent and an increase in the box's contents in accordance with the note's mass. The following code is equivalent to the above move command:

    set noun4 = note(parent)
    set note(parent) = box
    set noun4(capacity) + note(mass)
    set box(capacity) - note(mass)

As you can see, the move command is by far the easier option.

| If the capacity property of the destination object ends up a negative number, the move command will still successfully complete. It is therefore wise to test for this before issuing a move command. Below is an example of this from the library function +insert_in:
    if noun2(capacity) < noun1(mass)
       write "There is not enough room in " noun2{the}
       write " for " noun1{the} .^
       set TIME = false
       return
    endif

## The TRAVEL Command

A travel command must be of the format:

    travel direction

The travel command is used to move the player from one location to another. It simulates the player moving in the specified direction under their own steam. The player can also be moved to a different location by directly setting their parent to equal the new location. This, however, does not in perform any tests as to whether this movement is physically possible. The travel command is normally only ever used by the direction verbs in the library. One of the directions north, south, east, west, up, down, in, out, northeast, northwest, southeast or southwest must be specified as its single parameter.

Before the move actually occurs, two functions are executed. If either of these functions exists, and does not return false, the move will be prevented from occurring. The first of these functions is the movement function associated with the location the player is attempting to move out of. The second, executed if this first function does not exist or issues a return false command, is the global function +movement. Before either of these functions are called the integer variable compass is set to the direction the player is travelling in and the integer variable destination is set to the location the player is travelling into.

For example, if the player was in a location called hut and typed the command go north, the integer variable destination would be set to the location they are attempting to move into, say clearing, and the integer variable compass would be set to the direction he or she is attempting to move in, in this case north. Both of these variables would be set before the function movement that is associated with the location hut is called.

Two common uses of the movement function associated with a particular location are to replace the standard, "You can't go that way," message or to add some text describing the journey from one location to another. For example:

    location hut : hut
       short       the "hut"
       north       clearing

    {movement
    if COMPASS != north
       print:
          The only exit from here is the front door
          to the north.^"
       .
       return true
    endif
    print:
       You step out into the sun light, taking a
       moment for your eyes to adjust.^
    .
    return false
    }

Firstly, this function checks if the player is attempting to go in a direction other than this location's only exit. If this is the case, an appropriate message is displayed and a return true command is executed. It is this return command that prevents the normal message from being displayed. If the player is attempting to travel north, a short description of the journey is displayed and a return false is executed. It is this return false command that tells the interpreter that the move should continue as normal.

Another common use of an associated movement function is to simply remind the player of the available exits when they attempt to travel in an invalid direction. For example:

    {movement
    if destination = nowhere
       print:
          The only exit from here is to the south.^
       .
       return true
    endif
    return false
    }

This function would display the message "The only exit from here is to the south." whenever the player attempt to travel in a direction that is currently set to nowhere.

## Moving Non-player Characters

The file utils.library contains several functions to help simulate the natural movement of objects, such as a non-player character walking around. In addition to moving the object, these functions will display the appropriate message required to announce the movement to the player.

The function called from your game to initiate the movement is +push_object. This function is passed two arguments: the object to be moved and the direction to move the object in. The direction passed is one of the following integer constants:

Constant name | Integer value
--- | ---
north | 0
south | 1
east | 2
west | 3
northeast | 4
northwest | 5
southeast | 6
southwest | 7
up | 8
down | 9
in | 10
out | 11

Below is an example of the procedure for making an object move from one location to another:

    execute +push_object<security_guard<north

A message will be displayed to the player informing him or her of the object's movement if the player is in either the location the object is moving out of or the location the object is moving in to. If the location the player is in has the attribute DARKNESS, the message "You hear footsteps nearby." is displayed.

## The DIR_TO and NPC_TO Commands

The dir_to and npc_to commands calculate the first direction to move in when travelling from one location to another. The dir_to command will calculate a route that only passes through locations that have the attribute KNOWN, while the npc_to command will use all locations.

Both commands use the following syntax:

    dir_to <Container> <From Location> <To Location>

When this command runs, it will store the value of the first direction to move in inside the specified container. This container can be an integer variable or an object element. The value stored is one of the direction constants from the table above.

For example, given the map below, the command:

    dir_to INDEX clearing ledge

would put the value north (0), into the variable INDEX as this is the first direction that must be travelled in from the location clearing to get to the location ledge.

If the dir_to command is unable to calculate a route between the two locations, -1 will be placed into the container.

| The dir_to command is not able to determine if an exit is only temporarily blocked. If an exit is set to nowhere due to a door being closed between the two locations specified, -1 will be returned. If you wish to avoid this limitation you will need to temporarily open all doors that can be opened by the player, calculate the route and then return them to their initial state.

Back to Contents