Xelagot action script

Motion: Following Paths

Xelagot version 3.422 introduces the notion of paths a bot can follow. Paths are a collection of interconnected world locations. Using a modified A* (A star) routine, the bot can be made to select the best path to follow.

In 3D games, the A* routine uses collision detection to construct a path. Xelagot does not have collision detection, so a collection of user defined interconnected locations must be used. These are loaded from a definition file by the script. Making this file is tedious, but the result can be very rewarding. Here follows an example with 8 locations.

# this is my GZ
Entry=1s 0w 0a,      s1, n1, e1
# this path goes north
n1=0.627s 0.189w 0a, Entry, n2
n2=1.974n 0.189w 0a, n1, e3
# this path goes south
s1=1.342s 0.203w 0a, Entry, s2
s2=2.076s 0.535w 0a, s1
# this path goes east
e1=0.983s 0.520e 0a, Entry, e2
e2=1.729s 3.131e 0a, e3=weight:2/fly, e1
e3=1.974n 2.811e 0a, e2, n2

Notice the use of # to start a comment line.

All other lines start with the name of the location point. Each point has a unique name: Entry, n1, n2, etc. The names have no special meaning, but they must be unique and must not contain these 4 'special' characters: , : / =, which are used as separators, nor should they contain spaces.

The name is followed by an equal sign and the exact position in the world.

After that, separated by commas, are the names of the points that this point connects to (let's call them 'connectors'). This represents a one-way connection. For example, Entry connects to the points s1, n1 and e1. To connect back, e1 needs to include Entry in its own line.

Connectors can have parameters, see for example the line of e2: e2 connects to e3 with a weight of 2, and specifies an avatar state of flying. Between parameters, a forward slash is used as separator.

All connectors have default parameters, you only need to write parameters if you want to change the default. The defaults are:
avatar state: walking
weight: 1
no terrain sensing
More on these parameters later on.

Let's illustrate the working of this feature using the above mentioned data. If the bot is required to find a path between Entry and e3, it will construct the following path: Entry, n1, n2, e3. It could have chosen: Entry, e1, e2, e3; but according to the data the bot has, the other way is shorter. Notice here the weight between e2 and e3: it is a factor 2. This means that the distance between these points has been doubled when calculating the path. A weight higher than 1 makes it more difficult for the bot to select that way, lower than 1 makes it easier. Valid values are from 1 to near 0 for 'easy', and from 1 upwards for 'difficult'.

Parameters are separated from the name of the connector they qualify using an equal sign. Example on the e2 line:
To specify avatar state, just write down the name of the state: walking, running, flying, swimming, jumping, warping, falling. You may shorten this to walk, run, fly, swim, jump, warp, fall (in fact only these first letters are tested). To specify a weight, for example 0.75, write weight:0.75 (with a colon separating the word and the value), or shorten it to weig:0.75. To specify terrain sensing, write ter. Parameters may be written in any order, and must be separated by a forward slash.

You saw what the weight parameter does: it is used to select the shortest path, modifying the distance between points to favour certain paths above others. But what do the avatar state and terrain sensing parameters do? Nothing at all! they are informative and can be retrieved by the script when selecting a certain point on a path: this allows the script to make a decision.

In the description of the statements below, the term Point is used to describe any of the points loaded in memory. The term Mark is used to describe a Point that has been selected as part of a path.

You can download an example script I made to test these statements. You must have xelagot 3.422 or higher to run this script. It is written for GZ, but because the bot uses the To statement to follow the paths, you can easily transpose it to another place by editing the [Settings] Origin line. The script file is scriptPath01.txt, and the path definition file is paths01.txt. Download it here.

PathClear This statement must be used before loading path definitions from file. It clears the memory of the path finding engine, removing all data.
PathLoadFromFile $filename Loads from file the data needed to construct paths (see the example shown at the top of the page). Data can be split between various files, as this Load is actually a Merge.

xelagot 3.607 or newer
The filename convention is explained in the section Filenames.

xelagot 3.606 or older
The file should be in the same folder as the script.
PathConsolidate Must be issued after loading data from file. It builds up the relationship between the points.
PathCountAll %c Retrieves in %c the total number of points in the bot's path finding engine.
PathMakeMarks $start $end Attempts to construct a path between point $start and point $end. $start and $end must contain the names of the points (not the coordinates). That is why these names (the first thing on a line in the definition file) must be unique.
PathCountMarks %m Stores in %m the number of marks in a path (i.e. the number of points that have been selected as part of path). It will be zero if no path was made.
PathGetMark %n @a [$name $avstate %weight %ter]
PathGetMark %n @a [$name $avstate %weight $ter]
Retrieves in location variable @a the coordinates of a mark in a path. The position of the mark is set in %n before calling this statement: this position must be from 1 to the total number of marks in a path (retrieved with PathCountMarks %m)... assuming, of course, that the path is not empty.

Optionally, other parameters can be retrieved:
PathGetMark %n @a $name
retrieves the coordinates and the name of the mark. Avatar state, weight and terrain sensing can be retrieved by including more parameters.

Note on terrain sensing: it can be retrieved as a number (0 or 1), or as a string ("ON" or "OFF").
PathGetMarkNames $names Useful when testing a script, it retrieves the names of the marks in a path as a comma separated list.
PathGetConnections $names $pointname Useful when testing a script, it retrieves the names of the points that point $pointname connects to. Only the existing connections are listed (i.e. if a point is defined but does not exist, it does not appear in this list).