Wesnoth Formula Language

The Wesnoth Formula Language is a functional language used to evaluate expressions within the game engine. The most common use of the WFL is in the $(formula) substitution syntax, which allows the use of formulas wherever variables are parsed, but it can also be used in unit filters, GUI2 dialogs, and even AI. When using WFL in these places, you should not use the $ to introduce the formula. Only do that if using formulas in places that don't explicitly support them.

All formulas should be enclosed in quotes, as in this example: key = "$(formula-expression)".

Data Types and Operators

Numbers

The most common use of WFL is for simple calculations involving numbers. For this, the standard arithmetic operators (+ - * / %) work as you would expect, performing addition, subtraction, multiplication, division, and remainder. The only caveat to watch out for is that / rounds down when used on integers. For example, 5 / 2 will evaluate to 2. To avoid this, make sure at least one of the numbers includes a decimal point - 5.0 / 2 will evaluate to 2.5. Note that WFL supports only three decimal places of precision; beyond that it will still be rounded down. (So 1.0 / 16 will evaluate to 0.062 instead of 0.0625.) The ^ operator performs exponentiation (raising to a power) - for example, 2 ^ 3 evaluates to 8

Note: The modulus operator only works if both operands are integers. (Version 1.13.5 and later only) This is no longer the case as of 1.13.5.

You can also use the standard comparison operators (= != < <= > >=) on numbers. This is often useful in unit filters - for example, a formula of hitpoints < max_hitpoints / 2 will match only if the unit is at less than half health. Comparison operators return 1 for true and 0 for false; there is no boolean type.

One final numeric operator exists - the dice roll. The syntax 3d12 will roll three 12-sided dice and return the sum of the results. Note however that this is not multiplayer-safe, so using it can and will produce OOS errors. (Version 1.13.5 and later only) The dice operator is now synced and should be safe for use in multiplayer contexts.

Note: (Version 1.13.5 and later only) Some numeric operations will return null instead of a number. This usually involves the exponentiation operator - for example, (-2) ^ 0.5 attempts to take the square root of -2, which doesn't exist, so it returns null to indicate this. Dividing by zero also returns null, as well as certain math functions in appropriate circumstances.

Strings

WFL also supports strings, which must be enclosed in single quotes ('like this'). The comparison operators also work on strings, performing lexicographical comparison (ie, alphabetical order). The comparison is case sensitive.

(Version 1.13.5 and later only)

Strings can be concatenated with the concatenation operator ... They also support interpolations enclosed in square brackets, the contents of which can be any valid formula. For example:

'Some text: [a + b]' where a = 12, b = 10

results in the string Some text: 22. (The where operator is explained below.)

If you need to include a literal square bracket in a string, write [(] or [)]. For a literal single quote, you can write [']. For example:

'[(]It[']s bracketed![)]'

results in the string [It's bracketed!].

You can index the characters or words of a string with the following syntax:

'Hello World'.char[4]
'Hello World'.word[1]

These return o and World, respectively. A third option is also available, item, which splits the string on commas but allows parentheses to prevent a portion of the string from being split up.

Lists

A list is a sequence of values represented as square brackets, [], surrounding a comma-separated list. For instance:

[ 1, 5, 'abc' ]

The comparison operators work on lists, performing lexicographical comparison. A specific list index can be obtained with the indexing operator, like this: my_list[index]. The first element of a list is numbered 0.

There are four vector operators (.+ .- .* ./) that perform entrywise operations on lists. For example, [1,2,3] .+ [12,2,8] produces [13,4,11]. Both lists must be of the same length to use these operators, and of course, they must contain only numbers.

(Version 1.13.5 and later only)

A negative list index now counts from the end of the list - -1 refers to the last element. You can check if an element exists in a list using the in operator. Lists can also be joined with the concatenation operator .., and sliced using the range operator ~. In fact, the range operator produces a list of consecutive numbers, and in fact any list of numbers can be used to index a list - the result is to take the elements at the requested indices, in order. Some examples:

[1, 7, 'abc', 2.5, 'foobar', 127][1~3]
(10~20)[[0,-1]]
[1, 7, 'abc', 2.5, 'foobar', 127][[2,4]]

These result in the following lists:

[7, 'abc', 2.5]
[10,20]
['abc', 'foobar']

Maps

Maps: A map is a sequence of key-value pairs. For example:

[12 -> 'Hello', [1,2] -> 9, 'abc' -> 1.5]

The comparison operators work on maps. A specific element of a map can be obtained with the indexing operation. In the above example, the following conditions are all true (assuming the map is in a variable called self):

• self[12] = 'Hello'
• self[[1,2]] = 9
• self['abc'] = 1.5

(Version 1.13.5 and later only)

You can now use the in operator to test if a key exists in the map. You can also access string keys using the dot operator . as long as they are valid identifiers. (Valid identifiers contain letters and underscores only; no digits are permitted.)

Note that the selection indexing that lists use is not valid for maps - a list can be used as a key, after all.

Objects

An object is a container containing additional variables (see below for further explanation of variables) which are not in the global scope. The dot operator can be used to evaluate a formula in the object's scope. For example, suppose u is a unit object referring to your leader, who is an Elvish Ranger who has taken 12 damage (thus has 30 hit points). Then u.hitpoints will evaluate to the number 30. For a more advanced example, u . (hitpoints < max_hitpoints - 10) will evaluate to true if the unit has taken more than 10 damage, which in this example, it has. (This could also be written u.hitpoints < u.max_hitpoints - 10 if you prefer; this enters the scope twice, instead of once, but the result is identical.)

Objects generally cannot be created directly by the code - they are created for you by the game when formulas are called in certain contexts. However, there are two types of object that can be created by your code. The first is the location object, which has variables x and y; it can be created by the loc() function. The second is the map pair object, which is returned (or used internally) by several of the built-in functions and has variables key and value.

Other Types and Operators

There is one other basic type in WFL - the null type, which is used to mean "no value". It will be returned if you attempt to perform an invalid operation, such as dividing a string. It is also returned by the built-in null() function, which allows you to test if a value is null by writing value = null().

The logical operators and and or can be used to connect conditional expressions, and the unary operator not negates them. Note that or is inclusive - A or B is false only if both A and B are false. These operators consider 0 or null to be false, while all other values count as true. The if() function also follows the same rules to determine whether a value is true or false.

Note: Programmers familiar with other languages may occasionally be surprised by the fact that and and or do not short-circuit (which would mean that they will never evaluate their second argument if they can know their result solely from the first argument). This should not be a problem in general formula usage, since functions do not have side-effects, but it could make a difference when using the debug functions.

Operator Precedence

The precedence of various operators is, more or less, what you'd expect - you can write something like a + b * 2 <= 5 and n - m / 4 > 7 and the engine will do what you expect - first multiplication and division, then addition and subtraction, then comparison, and finally logical conjunction. The only thing to watch out for is when chaining exponentiation - all operators are left associative, so a ^ b ^ c will be evaluated as (a ^ b) ^ c instead of a ^ (b ^ c) like you would expect. (Version 1.13.5 and later only) This has been fixed - exponentiation is now right-associative.

The full precedence list is as follows, from lowest to highest; operators on the same line have equal precedence.

1. not
2. where clauses
3. or
4. and
5. Comparison operators = != < <= > >= in
6. Range-generating operator ~
7. Additive operators + - ..
8. Multiplicative operators * /
9. Modulus %
10. Exponentiation ^
11. Dice operator d
12. Dot operator .

Variables

Formulas may have a variety of variables, depending on the context in which they are evaluated. A string substitution formula like $(3 + 5) has no variables, but a unit filter formula has variables such as hitpoints and max_hitpoints which contain various properties of the unit being tested (the same unit which is also referred to in variable substitution as $this_unit). The special variable self typically refers to the "global context" - in the case of a unit filter formula, the unit itself. This means for example that self.hitpoints and hitpoints are equivalent when used in a unit filter formula. In a string substitution formula (the $formula syntax), self is null. Because of this, you should prefer not to use the substitution syntax in places where formulas are specifically supported.

A formula may declare additional variables using a where clause. This assigns a meaning to any unknown variables in the preceding formula. The general syntax is:

<formula> where <variable> = <value> [, <variable> = value ...]

This functions similarly to an operator, so if desired, you could have multiple where clauses in a single formula. Note that all variables in WFL are read-only - they are variables because they may have different values depending on the context in which the formula is evaluated, but for a given context, they are constant. A variable that has not been assigned a value is considered to have a value of null. Variables are lazily-evaluated - if a where clause declares a variable that is never used, the expression assigned to it will never be evaluated. (This only really matters if it contains a call to a debug function.)

Variable names can contain letters and underscores only. In particular, they cannot contain digits. Also, names are case-sensitive, so y and Y refer to two different variables.

Documentation of some common objects

• unit objects
• weapon objects
• terrain objects
• side objects
• pixel objects

Comments

Sometimes with particularly complicated formulas, it may be useful to document what's going on inline. Of course, you can use WML comments to do this, but in some cases it may be useful to put some comments in the middle of the formula. This is easily done - simply enclose them in # characters, like this:

#This is a Wesnoth Formula Language comment.#

Note the final # - unlike WML, WFL requires this to indicate where the comment ends.

Functions

There are several predefined functions in the Wesnoth Formula Language, and if these are not enough, it is possible to define your own functions. The special variable functions always evaluates to a list of all known function names. This is mainly useful only as a debugging tool, though.

To define a function, you use the def keyword. For example:

def sgn(x) if(x < 0, -1, x > 0, 1, 0);

This defines a function called sgn which returns the sign of the input number. The semicolon marks the end of the function. It's optional if there's nothing else following the function, but in practice this will very rarely be the case.

You can select one of the function's arguments to be the "default" argument. If an object is passed to the default argument, then any attributes of that object are directly accessible in the global scope. For example:

def is_badly_wounded(u*) hitpoints < max_hitpoints / 2;

This function takes a unit and returns 1 if it is at less than half hitpoints. The * indicates the default argument, without which it would instead have to be defined like this:

def is_badly_wounded(u) u.hitpoints < u.max_hitpoints / 2;

It's important to remember that the function body has access to no variables other than its parameters. For example, the following function would not work (in an AI context) even though the my_leader variable is defined:

def endangers_leader(u) distance_between(u.loc, my_leader.loc) < u.moves;

This is because the body of the function can't see the my_leader variable. To make this work, you would need to pass in my_leader as an additional parameter.

Note: Prior to 1.14, function definitions only work in AI code and GUI2 code.

Files

(Version 1.13.5 and later only)

On occasion, you may find yourself working with formulas complex enough to split them out into a separate file. The formula engine normally assumes that it is executing inline code and reports errors accordingly, but you can tell it that to enter a file scope using the special wfl keyword. The convention is to frame your code, so that any file looks like this:

wfl 'filename.wfl'

# Put whatever code you need here, possibly including function definitions. #

wflend

The matching wflend is required.

Note: This functionality was available prior to 1.13.5 using keywords fai and faiend. These keywords are now deprecated, but still work.

Core Functions

Many of the core functions exhibit two features that (as of 1.13.4) cannot be used in user-defined functions. The first is the ability to accept a varying number of arguments - some core functions accept any number of arguments, while others have a few optional arguments. The second is that arguments are lazily-evaluated, and in some cases some arguments will not be evaluated at all, while others may be evaluated multiple times with different variable values. The description of each function will explain how and when its arguments are evaluated.

Conditional Functions

There are two functions which return one of their input values based on some condition - the if function, and the switch function. Both evaluate only as many parameters as is needed to determine which value to return. In particular, parameters that are neither returned nor part of the condition will never be evaluated.

if

• if(condition, if true [, condition 2, if true 2, ...] [, otherwise])

This function first evaluates the condition, which is a formula. If it evaluates to true, then the function evaluates and returns the if true parameter; otherwise, it tries the next condition (if any) with the same result. If none of the conditions evaluate to true, then it returns the otherwise parameter if present, or null() otherwise.

For instance, an AI that recruits Wolf Riders on the first turn, and Orcish Grunts thereafter might look like this:

if(turn = 1, recruit('Wolf Rider'), recruit('Orcish Grunt'))

switch

• switch(formula, value 1, outcome 1 [, ... , value N, outcome N] [, default outcome])

The switch function first evaluates the input formula, and then checks if it is equal to any of the specified values. If matching value is found, the outcome assigned to it is returned; if not, then function returns either default outcome (if specified) or null.

Numeric Functions

Several basic math functions are available. These generally work equally on integer and decimal values.

abs

• abs(number)

Returns the absolute value of an input number; for example

abs( -5 )

will return 5.

(Version 1.13.5 and later only) This now works on decimals as well as integers.

acos

(Version 1.13.5 and later only)

• acos(number)

Returns the arccosine of the input number, in degrees.

asin

(Version 1.13.5 and later only)

• asin(number)

Returns the arcsine of the input number, in degrees.

atan

(Version 1.13.5 and later only)

• atan(number)

Returns the arctangent of the input number, in degrees.

as_decimal

• as_decimal(number)

Ensures that the number is a decimal rather than an integer; useful if you're dividing two unknown values and want to ensure that the result is a decimal.

cbrt

(Version 1.13.5 and later only)

• cbrt(number)

Returns the cube root of the input number. This is better than using the exponentiation operator, because it will give the correct result for negative numbers.

ceil

• ceil(number)

Returns the ceiling of the specified number, ie rounding it up to the nearest integer.

cos

• cos(angle)

Returns the cosine of the given angle, which is specified in degrees.

exp

(Version 1.13.5 and later only)

• exp(number)

Returns the exponential of the input number, which is the constant e raised to the specified power.

floor

• floor(number)

Returns the floor of the specified number, ie rounding it down to the nearest integer.

frac

(Version 1.13.5 and later only)

• frac(number)

Returns the fractional part of the specified number.

hypot

(Version 1.13.5 and later only)

• hypot(x, y)

Returns the hypoteneuse length of a triangle with sides x and y.

log

(Version 1.13.5 and later only)

• log(number, [, base])

Returns the logarithm of the input number. If base is omitted, it returns the natural logarithm; otherwise, the logarithm to the specified base.

max

• max(list of numbers)

Returns the largest number from the list. For example:

max([2, 8, -10, 3])

will return 8.

(Version 1.13.5 and later only) This now works on decimals as well as integers.

min

• min(list of numbers)

Returns the smallest number from the list. For example:

min( [ 3, 7, -2, 6] )

will return -2.

(Version 1.13.5 and later only) This now works on decimals as well as integers.

pi

(Version 1.13.5 and later only)

• pi()

Returns pi.

root

(Version 1.13.5 and later only)

• root(number, base)

Returns the root of the input number, to the specified base. This is better than using the exponentiation operator, because it will give the correct result for negative numbers and odd bases (for example, the fifth root of -32, which is -2).

round

• round(number)

Returns the specified number rounded to the nearest integer.

sgn

(Version 1.13.5 and later only)

• sgn(number)

Returns the sign of the number, ie -1 if it is negative, 1 if it is positive, and 0 if it is zero.

sin

• sin(angle)

Returns the sine of the given angle, which is specified in degrees.

sqrt

(Version 1.13.5 and later only)

• sqrt(number)

Returns the square root of the input number.

sum

• sum(list of numbers)

This function evaluates to the sum of the numbers in the list of numbers. For example:

sum([ 2, 5, 8])

returns 15, and:

sum(map(my_units, max_hitpoints - hitpoints))

finds the total damage your units have taken.

tan

(Version 1.13.5 and later only)

• tan(number)

Returns the tangent of the given angle, which is specified in degrees.

trunc

(Version 1.13.5 and later only)

• trunc(number)

Returns the truncation of the specified number, ie rounding it towards zero. This is different from floor when applied to negative numbers - floor(-7.5) gives -8, but trunc(-7.5) gives -7.

wave

• wave(number)

Given a numeric value V, this returns:

 sin(2*pi/(V%1000/1000))

String Functions

There are a few useful functions for manipulating strings.

concatenate

• concatenate(value1[, value2, ...])

Converts each of its arguments to a string, and concatenates the result together into a single string.

contains_string

• contains_string(string, search_string)

Returns 1 if search_string can be found within string (as a substring), 0 otherwise. For example:

contains_string( 'Testing', 'ing' )

returns 1.

length

• length(string)

Returns the length of the input string.

find_string

(Version 1.13.5 and later only)

• find_string(string, search_string)

Returns the index at which search_string starts within string (as a substring), or -1 if it is not found. For example:

find_string( 'Testing', 'ing' )

returns 4.

replace

(Version 1.13.5 and later only)

• replace(string, offset, [size,] replacement)

Returns a new string obtained by replacing a portion of the input string with the contents of the replacement string. The offset and size work the same as for substring. Examples:

replace('The quick brown fox jumps over the lazy dog!', 4, 5, 'dumb')
replace('The quick brown fox jumps over the lazy dog!', -9, 4, 'sleeping')
replace('The quick brown fox jumps over the lazy dog!', -9, 'brook!')
replace('The quick brown fox jumps over the lazy dog!', -6, -4, 'yellow')

return the following strings:

'The dumb brown fox jumps over the lazy dog!'
'The quick brown fox jumps over the sleeping dog!'
'The quick brown fox jumps over the brook!'
'The quick brown fox jumps over the yellow dog!'

substring

• substring(string, offset[, size])

Extracts a substring from the given input string. The offset specifies the first character to extract; the first character is 0, and negative values count from the end, so the last character is -1. If specified, the size indicates the total number of characters to extract; it cannot be negative. If omitted, all characters from the offset to the end of the string are returned. For example:

substring('The quick brown fox jumps over the lazy dog!', 4, 5)
substring('The quick brown fox jumps over the lazy dog!', -9, 4)
substring('The quick brown fox jumps over the lazy dog!', -9)

return 'quick', 'lazy', and 'lazy dog!' respectively.

(Version 1.13.5 and later only) The size can now be negative. This means to count backwards from the given offset (but always including the given offset, so a size of -1 gives the same result as 1). For example:

substring('The quick brown fox jumps over the lazy dog!', -6, -4)

returns 'lazy'.

List and Map Functions

This section contains functions that directly manipulate a map or list.

head

• head(list [, count])

Returns the first item from the list; for example

head([5, 7, 9])

returns 5, and

head( [ 'Orc', 'Human' ] )

returns 'Orc'.

(Version 1.13.5 and later only) If a second argument is given, it returns a list containing the first count elements from the list. Note that head(L) is different from head(L,1) - the former returns the first element, while the latter returns a list containing only the first element.

index_of

• index_of(value, list)

This function will return the first index where value can be found in the input list. It will return -1 if the value is not found in the list'.

keys

• keys(map)

Extracts the key values from an input map and returns them as a list. For example:

keys(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])

returns

['Elvish Fighter', 'Elvish Archer']

size

• size(list)

This function returns the number of elements in the list.

For example, size([5, 7, 9]) returns 3 and size(['Archer', 'Fighter']) returns 2.

sort

• sort(list, formula)

This function evaluates to a result list sorted according to the comparison formula for each item a and its successor b. For instance, sorting units according to hitpoints would be done by:

sort(my_units, a.hitpoints > b.hitpoints)

To sort them in the reverse order, simply use < instead of >.

tail

(Version 1.13.5 and later only)

• tail(list [, count])

Returns the last item from the list; for example

tail([5, 7, 9])

returns 9, and

tail( [ 'Orc', 'Human' ] )

returns 'Human'.

If a second argument is given, it returns a list containing the last count elements from the list. Note that tail(L) is different from tail(L,1) - the former returns the last element, while the latter returns a list containing only the last element.

tolist

• tolist(map)

This function takes a map and return a list of key-value pair objects. For example:

tolist(['Elf' -> 10, 'Dwarf' -> 20])

will return:

[{key->'Elf',value->10}, {key->'Dwarf',value->20}]

tomap

• tomap(list A [, list B])

This function takes one or two lists as input and returns a map. If only one list is specified, then the function will evaluate this list, count how many similar elements are found within the list, and return a map with keys being these elements, and values being a number representing how many of them the list contains. For example:

tomap(['elf', 'dwarf', 'elf', 'elf', 'human', 'human'])

will return:

['elf' -> 3, 'dwarf' -> 1, 'human' -> 2]

(Version 1.13.5 and later only) However, if all the elements are key-value pairs such as those created by pair or tolist, then this function will invert the effect of tolist and return the original map which would have produced the input list as output when passed to tolist. If only some elements are key-value pairs, those elements will be directly converted into key-value pairs in the resulting map, while other values will be treated as described above.

If two lists are specified, then the elements of the first one will be used as a keys, and the elements of the second one as a values, when creating an output map. Note that these input lists must be of the same length. For example:

tomap(['elf', 'dwarf' ], [10, 20])

will result in:

['elf' -> 10, 'dwarf' -> 20]

values

• values(map)

Extracts the values assigned to keys from an input map and returns them as a list. For example:

values(['Elvish Fighter' -> 50, 'Elvish Archer' -> 60])

returns

[50, 60]

List-processing Functions

This section covers functions that operate on maps or lists by applying one or more formulas in succession to each element. Most return another map or list, reduce instead combines all the elements into a single result.

choose

• choose(input, [self_name,] formula)

This function evaluates formula for each item in the input (which can be a list or a map). It will return the first item to which formula gave the highest value. For example:

choose(my_units, level)

gives back the unit with the highest level.

The implicit input when evaluating a mapping/filtering function's formula component will be that specific item under evaluation (in this example one of "my_units"), and it can be explicitly referenced as self when necessary. The optional <self_name> parameter can be used to give a different name to the self variable.

When evaluating a map, we can reference each key by key and each value by value. In this case, the self variable is this key-value pair. For example:

choose(['elf' -> 10, 'dwarf' -> 20 ], value)

will return a key-value pair

{key->'dwarf', value->20}

The curly braces are used in output to indicate that this is an object, not a map. It is not valid WFL syntax.

filter

• filter(input, [self_name,] formula)

This function will run the formula on each item in the input (which can be a list or a map). It will evaluate to a list or map which only contains items that the formula was true for. The optional <self_name> parameter can be used to give a different name to the self variable.

filter(my_units, hitpoints < max_hitpoints)

will return all of your units which have less than maximum hitpoints. For instance this could be used if looking for candidates for healing.

find

• find(input, [self_name,] formula)

This function will run <formula> on each item in the <input> (which can be a list or a map) and will return the first item for which <formula> was true. The optional <self_name> parameter can be used to give a different name to the self variable. For example:

find(units, id = 'Elvish Archer' )

will return the first unit with id equal to 'Elvish Archer'.

map

• map(input, [self_name,] formula)

This function will run the formula on each item in the input (which can be a list or a map), and evaluate to a new list or map or a map, which contains the same number of items as in input, with the formulas run on each item. The optional <self_name> parameter can be used to give a different name to the self variable. When run on a map, the resulting map has the same keys as the input map, but with the values updated to the results of the formula. For example:

map([10,20], self*self)

and

map([10,20], 'value', value*value)

will both result in [100, 400]. The formula:

map(my_units, hitpoints)

will give a list back with the number of hitpoints each unit has. This is more useful in conjunction with other functions.

map(['elf' -> 10, 'dwarf' -> 20 ], value*2)

The above will produce ['elf' -> 20, 'dwarf' -> 40]. Note that in case of a map data type, the map function can only modify the value.

map(tomap([3,5,8,8]), value+key*100)

The above will produce [3 -> 301, 5 -> 502, 8 -> 801]. This can be used to take a list and make a map containing pairs [element_from_that_list -> f(element_from_that_list,number_of_repetitions_of_that_element_in_that_list)] where f is an arbitrary function.

reduce

• reduce(list, [identity, ] formula)

This function will run the formula on the first and second members of the list, then on the result and the third member and so on until the list is depleted. The final result is then returned. The two variables used in the formula are always 'a' and 'b'.

For example, reduce([1,2,3,4], a+b) returns 10 and reduce([9,4,8,2], 10*a+b) returns 9482.

(Version 1.13.5 and later only) The new identity argument specifies the starting value (which is null or 0 by default). If list is empty, then identity is returned. Otherwise, the list will be considered as if identity were an extra first element. For example, to calculate the product of a list of numbers, you might do something like this:

reduce(your_list, 1, a * b)

This will return 1 if the list is empty, as expected - the product of no numbers is 1. If the list is not empty, adding 1 to the list will have no effect, since it is the multiplicative identity.

take_while

(Version 1.13.5 and later only)

• take_while(list, formula)

Evaluates the formula for each element of the list until it finds one for which it evaluates to false, then returns a list of all elements up to but not including that element. For example:

take_while([1,5,3,6,3,7,9,5,6,4,12,2,53,2,1], self < 10)

returns the list [1,5,3,6,3,7,9,5,6,4].

zip

(Version 1.13.5 and later only)

• zip(list1, ... , listN)
• zip(list of lists)

Takes a list of lists and generates a new list of lists such that list n contains element n of each of the original lists, in order. If the lists are not all of the same length, it treats them as if they were padded on the end with null values so that they are all the length of the longest list.

zip([1,2,3],[4,5,6])
zip([1,4],[2,5],[3,6])

return [[1,4],[2,5],[3,6]] and [[1,2,3],[4,5,6]], respectively.

Miscellaneous Functions

Some functions really don't fit into any category. They are all listed here.

distance_between

(Version 1.13.5 and later only)

• distance_between(start, end)

Returns the distance between the locations start and end, which must be location objects such as those created by loc().

Note: This function was already available in FormulaAI prior to 1.13.5; however, from 1.13.5 onward it is available to all formulas.

loc

• loc(x, y)

Creates and returns a location object with the specified coordinates. If assigned to a variable pos (eg with a where clause), the individual coordinates can be accessed as pos.x and pos.y.

null

• null([arguments])

Evaluates each of its arguments (if any) in order, then returns null. Since formulas generally do not have side-effects, there is little point in specifying any arguments unless you are writing AI code (where several functions do have side-effects).

pair

(Version 1.13.5 and later only)

• pair(key, value)

Creates a key-value pair object, the same as those created by the tolist function.

reverse

(Version 1.13.5 and later only)

• reverse(string or list)

Returns the input string or list backwards.

type

(Version 1.13.5 and later only)

• type(anything)

Returns the type of its input as a string. Possible results are:

• 'integer'
• 'decimal'
• 'string'
• 'list'
• 'map'
• 'null'
• 'object'

Debugging Functions

There are also a few functions that can be useful for debugging formulas, for example by displaying intermediate results to the screen. Note that this breaks the general rule that functions do not have side-effects.

debug

• debug([formula])

Starts a GUI formula AI debugger when evaluating a formula. It takes a formula, evaluates it and returns the result unchanged. Note: this does not appear to work in 1.13.3.

(Version 1.13.5 and later only) The formula allows you to step through the formula one operation at a type, viewing the current stack and execution trace. As of 1.13.5, you need to enable debug mode to use the debugger; otherwise, it will simply be skipped.

debug_print

you need to enable formula log (--log-info='scripting/formula') to see the result of this call

• debug_print([explanation ,] formula )

This function can be used for debugging a formula. It takes a formula, writes its result to the console, and returns it unchanged. For example:

debug_print([1, 2, 3])

will result in printing to the console

[1, 2, 3]

and returning the same.

We can specify an optional parameter explanation that helps to distinguish between multiple debug_print calls in the same formula:

debug_print('My array: ', [1, 2, 3])

will write in the console:

My array: [1, 2, 3]

and return

[1, 2, 3]

debug_profile

• debug_profile(formula [, explanation])

Evaluates the formula 1000 times and prints (as with debug_print) a number indicating the average time required to evaluate the formula. Mainly intended for internal testing, but could occasionally be useful for people working with complicated formulas. The optional explanation argument is used in the same way as in debug_print.

debug_float

• debug_float(location, [explanation,] formula )

This function can be used for debugging a formula. It takes a formula, floats a label containing the result on the hex specified (in the same way damage is displayed) and returns it unchanged. Note that the location here is an object type; it can be created with the loc() function. For example:

debug_float(me.loc, me.id)

will make a label containing the id of the unit me float over the unit.

Return value is also the unit id.

We can specify an optional parameter explanation that helps to distinguish between multiple debug_float calls in the same formula:

debug_float( me.loc, 'id: ', me.id )

will float the following label

id: unit_id

and return the unit id.

dir

• dir(object)

This function return a list of all attributes in object. For example:

dir(my_leader)

will result in the following output:

[ 'x', 'y', 'loc', 'id', 'type', 'name', 'leader', 'undead', 'traits', 'attacks', 'abilities', 'hitpoints',
'max_hitpoints', 'experience', 'max_experience', 'level', 'total_movement', 'movement_left', 'attacks_left',
'side', 'states', 'cost', 'usage', 'vars']

This command is useful in the formula command line, to get information about the attributes of different types of data.