backIndex

Xelagot action script

Location variables and operations

The script language has a variable type called location. This type can be used to store positions and modify them. They are used in movement statements, to move the bot to a new position or give it a new rotation.

This type is actually a class, with two descendants: the person and object variables. Any person or object variable may be treated as a location variable, and used in its place, except for the simple assignement @a = .... The following operations apply to location variables and to person and object variables, unless stated otherwise. For instance, GetPosition ~m will move object variable ~m to the bot's position.

On this page you find a description of operations that can be done with these variables, and of conditional statements involving them. But first, a 3.3 note on notation.

New extended coordinate notation


Two rotation angles had to be added to the coordinates of objects in the 3.3 bot: Tilt and Roll. The new notation looks like this:
23.000w 30.500s 1.60a 45.0 15.0t -15.0r
where 15.0t -15.0r represent the Tilt and Roll angles. 45.0 is the familiar Rotation, which is now called Yaw (as it allways was in the SDK); the degrees symbol may be omitted. If the Tilt and Roll angles are both zero, then the old notation is used:
23.000w 30.500s 1.60a 45.0
although 23.000w 30.500s 1.60a 45.0 0.0t 0.0r is valid.

And now, the statements.

Variables shown in black may be substituted by literal values, variables shown in red are assigned the result of the operation, variables in green may not be substituted by their literal equivalents.

@a = @b
@a = &b
@a = ~b
@a = $b

variable @a may not be substituted by a person or object variable in this statement.
simple assignement of all values of @b to @a. Variable @b may be substituded by a person variable &b or object variable ~b, and by a string variable $b or literal, in the form of "10n 5.3e 0a 45", or including the world, as in "10n 5.3e 0a 45 :mars" (notice the colon before the world name, which may be left out as from xelagot version 3.0). All missing values will default to zero, a missing world defaults to an empty string. See Variables for a fuller explanation.
GetLocation $a
GetLocation @a
@a may be substituted by &a and ~a.

GetLocation $a %n
GetLocation @a %n
@a may be substituted by &a and ~a.
assigns to string variable $a, location variable @a, person variable &a or object variable ~a the coordinates and the world of the bot. If %n is specified, it gets the location of bot number %n. Bots are numbered from 1 upwards, numbers out of range default to the bot running the script. For X1 xelagots, valid numbers are: 1, 2 and 3.
GetLocation @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.

GetLocation @a $b
@a may be substituted by &a and ~a.

GetLocation $a @b
@b may be substituted by &b and ~b.

GetLocation $a $b
identical to @a = @b, @a = &b, etc: assigns locations (including the world). GetLocation $a $b standardises the notation of a location string.
Notice here the full compatibility between variables of the location family: location, person and object.
GetWarpString @a $b
@a may be substituted by &a and ~a.
parses the string variable or literal, which may only contain coordinates and optionally a world name, extracts the coordinates and world and modifies only those specified in the string. The world name may be at the begining or end of the string. Altitudes must be specified in metres. Useful to parse chatlines like 'Warp 0n 5w', after removing the 'Warp ' substring.
GetPosition $a
GetPosition @a
@a may be substituted by &a and ~a.

GetPosition $a %n
GetPosition @a %n
@a may be substituted by &a and ~a.
assigns to string variable $a, location variable @a, person variable &a or object variable ~a the coordinates of the bot. If %n is specified, it gets the coordinates of bot number %n. Bots are numbered from 1 upwards, numbers out of range default to the bot running the script. For X1 xelagots, valid numbers are: 1, 2 and 3.
GetPosition @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.

GetPosition @a $b
@a may be substituted by &a and ~a.

GetPosition $a @b.
@b may be substituted by &b and ~b.

GetPosition $a $b
gets the position values (not the world) in @b, &b, ~b or $b, assigns them to @a, &a, ~a or $a.
3.3 statements

GetCoords $a
GetCoords @a
@a may be substituted by &a and ~a.

GetCoords $a %n
GetCoords @a %n
@a may be substituted by &a and ~a.
assigns to string variable $a, location variable @a, person variable &a or object variable ~a the coordinates of the bot but not its rotation. If %n is specified, it gets the coordinates of bot number %n. Bots are numbered from 1 upwards, numbers out of range default to the bot running the script. For X1 xelagots, valid numbers are: 1, 2 and 3.
3.3 statements

GetCoords @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.

GetCoords @a $b
@a may be substituted by &a and ~a.

GetCoords $a @b.
@b may be substituted by &b and ~b.

GetCoords $a $b
gets the position values (not the world) in @b, &b, ~b or $b, assigns them to @a, &a, ~a or $a.
GetNS %a
GetNS %a %n

similarly: GetWE, GetAltitude
gets the bot's present NS position, assigns it to %a. If %n is specified, it gets the NS coordinate of bot number %n. Bots are numbered from 1 upwards, numbers out of range default to the bot running the script. For X1 xelagots, valid numbers are: 1, 2 and 3.
GetNS @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.

GetNS @a %b
@a may be substituted by &a and ~a.

GetNS %a @b
@b may be substituted by &b and ~b.

new in 3.3
GetNS @a $b
@a may be substituted by &a and ~a.

similarly: GetWE, GetAltitude
gets the NS position in @b, &b or ~b, or the value in metres in variable or literal %b (in 3.3: or extracts the NS value from a location string $b), and assigns it to @a or %a. Numerical variables or literals are in metres. Does not modify other values of @a (or &a, ~a).

Similarly for WE and Altitude.

GetRotation
see GetYaw, its new Xelagot 3.3 name. The older GetRotation statements still work in newer bots.
3.3 statements

GetYaw %a
GetYaw %a %n

similarly: GetTilt (or 3.4 GetPitch), GetRoll
gets the bot's present Yaw, assigns it to %a. If %n is specified, it gets the Yaw of bot number %n. Bots are numbered from 1 upwards, numbers out of range default to the bot running the script. For X1 xelagots, valid numbers are: 1, 2 and 3.

Similarly for Tilt and Roll.

3.3 statements

GetYaw @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.

GetYaw @a %b
@a may be substituted by &a and ~a.

GetYaw %a @b
@b may be substituted by &b and ~b.

new in 3.3
GetYaw @a $b
@a may be substituted by &a and ~a.

similarly: GetTilt (or 3.4 GetPitch), GetRoll
gets the Yaw in @b, &b, ~b, or the value in degrees in variable or literal %b (in 3.3: or extracts the Yaw value from a location string $b), and assigns it to @a or %a. Numerical variables or literals are in degrees. Does not modify other values of @a (or &a, ~a).

Similarly for Tilt and Roll.

GetWorld $a
GetWorld $a %n
gets the bot's present world, assigns it to $a. If %n is specified, it gets the world of bot number %n. Bots are numbered from 1 upwards, numbers out of range default to the bot running the script. For X1 xelagots, valid numbers are: 1, 2 and 3.
GetWorld @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.

GetWorld @a $b
@a may be substituted by &a and ~a.

GetWorld $a @b
@b may be substituted by &b and ~b.

GetWorld $a $b
gets the world name in @b, &b or ~b, or the value in $b or its literal representation (in 3.3: or extracts the world name from a location string $b, which may contain or not the other location parameters, but must contain a valid world name), and assigns it to @a or to $a. Does not modify other values of @a.
LocClear @a
@a may be substituted by &a and ~a.
clears variable @a, setting all values to zero and the world name to an empty string. If variable @a is substituted by a person &a or object ~a variable, only the location, rotation and world fields of the variable will be cleared.
3.3 statement
LocClearRotations @a
@a may be substituted by &a and ~a.
clears the rotations of variable @a, &a or ~a, setting Yaw, Tilt and Roll to zero.
3.3 statement
LocYawBy @a %b
older statement
LocTurn @a %b
@a may be substituted by &a and ~a.
rotates the Yaw angle of location @a by %b degrees (positive is anti-clockwise), i.e. adds %b degrees to the present Yaw of location @a. Does not alter the other values of @a.
3.3 statement
LocTiltBy @a %b
3.424 statement
LocPitchBy @a %b
@a may be substituted by &a and ~a.
rotates the Tilt angle of location @a by %b degrees (positive is anti-clockwise), i.e. adds %b degrees to the present Tilt of location @a. Does not alter the other values of @a. Both statements are equivalent as from version 3.424.
3.3 statement
LocRollBy @a %b
@a may be substituted by &a and ~a.
rotates the Roll angle of location @a by %b degrees (positive is anti-clockwise), i.e. adds %b degrees to the present Roll of location @a. Does not alter the other values of @a.
3.3 statement
LocYawTo @a @b
older statement
LocTurn @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.
rotates the Yaw of location @a, person &a or object ~a towards location @b, person &b or object ~b, so that it will face it. Does not alter the other values of @a, &a or ~a.
Note 1 - singularity: if both locations are at exactly the same NS and WE coordinates, this statement does nothing useful.
Note 2 - rolled objects may fail to rotate as expected in this manner.
3.424 statement
LocTiltTo @a @b
LocPitchTo @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.
tilts location @a, person &a or object ~a towards location @b, person &b or object ~b. It does not make it face the target! Does not alter the other values of @a, &a or ~a.
Note 1 - singularity: if both locations coincide exactly, this statement does nothing useful.
Note 2 - rolled objects may fail to rotate as expected in this manner.
3.424 statement
LocYawTiltTo @a @b
LocYawPitchTo @a @b
@a may be substituted by &a and ~a,
@b may be substituted by &b and ~b.
rotates the Yaw and Tilt (Pitch) of location @a, person &a or object ~a towards location @b, person &b or object ~b, so that it will face it and point up or down to it. Does not alter the other values of @a, &a or ~a.
Note 1 - singularities: see Note 1 of LocYawTo and LocTiltTo.
Note 2 - rolled objects may fail to rotate as expected in this manner.
LocMove3D @a %d %ha %va
@a may be substituted by &a and ~a.
moves location @a a distance of %d metres in space, at a horizontal angle of %ha degrees (from the angle indicated by its rotation) and a vertical angle of %va degrees (to the horizontal plane). Does not alter the Yaw, Tilt or Roll angles of @a.

For example:
LocMove3d @pipo 25.3 90.0 0 will move location @pipo 25.3 metres to its left, not altering its altitude. Location @pipo will end up facing the way it was before being moved.
LocMove3d @pipo 10 0 0 will move @pipo 10 metres forward.
LocMove3d @pipo 10 0 -90 will move @pipo 10 metres down.
LocMove3d @pipo 10 0 30 will move @pipo 10 metres in space, up at an angle of 30 degrees to the horizontal plane. Horizontally it will move less than 10 metres, of course.

LocMoveZXY @a %ns %we %alt
@a may be substituted by &a and ~a.
(3.434) moves location @a a distance of %ns (Z), %we (X) and %alt (Y) metres in space along the world coordinate axes.
LocMidPoint @a @b @c [@d ... @n]
@a may be substituted by &a and ~a.
@b may be substituted by &b and ~b,
and so on.
takes a variable number of parameters of the location family, assigns to @a the weighed mid-values of variables @b, @c up to @n. If the variables are substituted by a person or object variables, only the location fields of the variables will be used. For example, if you wish to find the midpoint between @corner1 and &John and assign it to @p, you write:
LocMidPoint @p @corner1 &John.
Distance %a @p @q
@p may be substituted by &p and ~p,
@q may be substituted by &q and ~q.
gets the spatial distance in metres between locations @p and @q and assigns it to %a. Its value is always positive. You may also compare person and objects variables.
DistanceH %a @p @q
@p may be substituted by &p and ~p,
@q may be substituted by &q and ~q.
gets the horizontal distance in metres between locations @p and @q and assigns it to %a. Its value is always positive. You may also compare person and objects variables.
DistanceV %a @p @q
@p may be substituted by &p and ~p,
@q may be substituted by &q and ~q.
gets the difference in altitude in metres between locations @p and @q and assigns it to %a. Its value is positive if @q is higher than @p. You may also compare person and objects variables.
DistanceNS %a @p @q
@p may be substituted by &p and ~p,
@q may be substituted by &q and ~q.
gets the difference in metres between the NS coordinates of locations @p and @q and assigns it to %a. Its value is positive if @q is North of @p. You may also compare person and objects variables.
DistanceWE %a @p @q
@p may be substituted by &p and ~p,
@q may be substituted by &q and ~q.
gets the difference in metres between the WE coordinates of locations @p and @q and assigns it to %a. Its value is positive if @q is West of @p. You may also compare person and objects variables.
AWDistanceNS %a @p @q
@p may be substituted by &p and ~p,
@q may be substituted by &q and ~q.
gets the difference in AW units between the NS coordinates of locations @p and @q and assigns it to %a. Its value is positive if @q is North of @p. This value should not be used in calculations involving metres. You may also compare person and objects variables.
AWDistanceWE %a @p @q
@p may be substituted by &p and ~p,
@q may be substituted by &q and ~q.
gets the difference in AW units between the WE coordinates of locations @p and @q and assigns it to %a. Its value is positive if @q is West of @p. This value should not be used in calculations involving metres. You may also compare person and objects variables.

CONDITIONAL STATEMENTS FOR LOCATION
shared by Person and Object variables

See Conditional Statements for a general explanation.
In all the conditional statements involving location, you may use person or object variables instead of location variables, e.g. IfLoc &a IsInSquare @b @c ...., IfLoc &a IsNorthOf &b ...., IfLoc ~a IsInCircle ~c %r ..., IfLoc &p IsInSphere ~c %r ... All conditional statements may be followed by a line containing:
Else statement2
IfLoc @a IsInTriangle @b @c @d statement1 defines a horizontal triangle by its 3 vertices @b, @c and @d (altitudes are ignored) and tests if @a is inside it
IfLoc @a IsInSquare @b @c statement1 defines a NSWE oriented rectangle by its 2 opposite vertices @b and @c (altitudes are ignored) and tests if @a is inside it
IfLoc @a IsInCube @b @c statement1 defines a NSWE oriented cuboid by its 2 opposite vertices @b and @c (e.g. Top-North-West and Bottom-South-East) and tests if @a is inside it.
IfLoc @a IsInCircle @b %r statement1 defines a circle by its centre @b (altitudes are ignored) and radius %r and tests if @a is inside it. This is actually a topless and bottomless vertical cylinder.
IfLoc @a IsInSphere @b %r statement1 defines a sphere by its centre @b and radius %r tests if @a is inside it.
IfLoc @a IsInVCylinder @b %r %h statement1 defines a vertical cylinder by the centre @b of its base, its radius %r and its (positive or negative) height %h, and tests if @a is inside it.
IfLoc @a IsInFan @centre @b @c [...] @n statement1 X1 2.9999978 tests if location @a is in a fan defined in the following way: @centre is common to all triangles in the fan, @b, @c etc are the other vertices of adjacent triangles. First it tests triangle @centre @b @c, then @centre @c @d and so on. With this statement, many irregular shapes can be formed, including squares. The altitudes are ignored.
IfLoc @a IsInVFan @centre %height @b @c [...] @n statement1 X1 2.9999978 tests if location @a is in a fan defined in the following way: @centre is common to all triangles in the fan, @b, @c etc are the other vertices of adjacent triangles. First it tests triangle @centre @b @c, then @centre @c @d and so on. With this statement, many irregular shapes can be formed, including cubes. The altitude of @centre forms the base of the fan, %height (which can be negative) indicates the height of the fan, the altitudes of @b, @c etc are ignored.
IfLoc @a IsNorthOf @b statement1
IfLoc @a IsNorthOf %b statement
location @a is compared to either location @b or to a signed value %b which is the distance in metres from GZ 0n 0w 0a, where North and West have positive values. One AW unit is 10m, so 35.2e (AW units) = -352 metres. Altitudes are expressed in metres too.
IfLoc @a IsSouthOf @b statement1
IfLoc @a IsSouthOf %b statement
IfLoc @a IsWestOf @b statement1
IfLoc @a IsWestOf %b statement
IfLoc @a IsEastOf @b statement1
IfLoc @a IsEastOf %b statement
IfLoc @a IsHigherThan @b statement1
IfLoc @a IsHigherThan %b statement
IfLoc @a IsLowerThan @b statement1
IfLoc @a IsLowerThan %b statement
IfLoc @a IsBehind @b statement1

3.427
IfLoc @a IsBehind3D @b statement1
compares the position of @a relative to @b's position and yaw (rotation). IsBehind and IsInFrontOf assume that the Tilt or Pitch of the Location (Person or Object) variable = 0, IsBehind3D and IsInFrontOf3D take the Tilt (Pitch) angle into consideration.
IfLoc @a IsInFrontOf @b statement1

3.427
IfLoc @a IsInFrontOf3D @b statement1
IfLoc @a Sees @b %hang %vang %range statement1
IfLoc @a Sees @b %hang %vang %range statement1

3.427
IfLoc @a Sees3D @b %hang %vang %range statement1
IfLoc @a Sees3D @b %hang %vang %range statement1
checks if @b is in the field of vision of @a, as defined by the horizontal angle %hang and vertical angle %vang (degrees) and %range (metres). If %range = 0 then does not check the range. If %range is a variable, it will be modified if the condition is met, and will contain the actual distance between @a and @b (in metres). Sees assumes the 'eyes' of @a look along the horizontal plane, as in 1st person vision in the aw browser without Pitch or Tilt, Sees3D uses the Pitch (Tilt) similarly to how the AW browser uses Look Up and Look Down.
Please note that bots see through avatars, objects and terrain!


backIndex