@node Reference Manual

@chapter Reference Manual

This manual is the complete description of GDL.  The style is somewhat
terse; for more detail on how to use GDL to design games, see the
previous chapter.

Please note that the current version of @i{Xconq} may not fully
implement all of the constructs or combinations of constructs described
here.  Any such omissions should be regarded as bugs and reported as
such.

@menu
* Language Syntax::
* Game Module Forms::
* World and Area Forms::
* Side and Player Forms::
* Unit Forms::
* Agreements::
* Scorekeeper Forms::
* History Forms::
* Types in General::
* Unit Types::
* Terrain Types::
* Material Types::
* Advance Types::
* Static Relationships Between Types::
* Vision::
* Game Initialization::
* Synthesis Methods::
* Setup Postprocessing::
* Naming and Text Generation::
* Actions::
* Backdrop::
* Behavior::
* Game End::
* Dates and Time::
* Image Families::
* Other Forms::
* Files and Directories::
@end menu

@node Language Syntax

@section Language Syntax

GDL is intended to be an easily used, yet powerful, tool for people who 
have little programming experience, but who wish to design Xconq game 
modules. For those who have programmed in Lisp before, GDL uses a 
similar syntax, but @emph{knowledge of Lisp is not required} to 
develop Xconq games. Elements of GDL include such things as numbers, 
lists, and tables.

Formally, GDL is a @emph{declarative}, or nonprocedural, language, rather
than an imperative language. This means that most of the time, you can 
declare lists, tables, and forms (which will be discussed later) in 
any order you like. There are two significant, though not unreasonable, 
restrictions however. The first is that any symbol, such as a variable 
or the name of a type, must be defined before it is used. The second is 
that a symbol must be used in an appropriate context or scope. This is 
basically to say that you can only assign properties to things for 
which those properties would make sense. Keep in mind that definitions 
can be overwritten with the use of @code{set} and @code{add} (which will
also be discussed later), and the order in which they are used is 
important.

@menu
* Lexical Elements::
* Conventions Used::
* Forms and Evaluation::
* Tables::
* Modifying Objects::
* Symbols::
* Lists::
* Arithmetic Operations::
* Arithmetic Comparisons::
* Boolean Comparisons::
@end menu

@node Lexical Elements

@subsection Lexical Elements

The Xconq interpreter parses GDL declarations into various lexical 
elements, or tokens. These include numbers, strings, symbols,  
comment delimiters, and list/form/table delimiters.

Numbers are introduced by a decimal digit, plus, or minus signs.  They
may contain only decimal digits, a decimal point, and be followed
(immediately, no whitespace allowed) by a percent sign. Numbers are 
used where integer quantities, percentages (which may meaningfully 
exceed 100% in many cases), or parts per 10,000 (0.01% increments) are 
expected. Typically numbers are positive. Unless otherwise stated, 
the default value for properties that take numeric values is @code{0}. 
Also of interest is the fact that @code{-1} is often used to indicate 
special behavior of a property or table element, such as "turning off" 
the property, or inheriting a value set in another table. Examples of 
numeric values include the following: @code{99}, @code{65.2%}, 
@code{4.00}, and @code{-1}.

Strings are sequences of characters (letters, digits, punctuation marks, 
etc...) enclosed by doublequotes (@code{"}).
They may contain any character except ASCII NUL (@code{'\0'}).  To
include a doublequote, use backslash, as in @code{"a \"quoted\"
string"}.  To include a nonprinting or eight-bit character (often 
associated with international characters or ANSI graphics), use
backslash followed by three octal digits, which will be interpreted as
an eight-bit character code.  (This is mostly the same syntax as in C.)
Note that game design files may be passed over networks and between
different kinds of computer systems, so non-ASCII characters should not
be inserted verbatim into strings. In places where string values are 
expected, the default is @code{""}, unless otherwise stated.

Symbols are sequences of characters that don't include any of the other
special characters.  If you wish to include such characters in a symbol,
enclose it in vertical bars, for example @code{|foo bar|}.  (The bars
are not part of the symbol.)  Symbols are case-sensitive, but this will
be changed eventually. Examples of symbols include: @code{acp-per-turn}, 
@code{|coastal waters|}, and @code{size}.

Numbers, strings, and symbols all belong to a kind called an @dfn{atom}. 
There are other elements of GDL which are not atoms; these are comments 
and lists.

Comments are enclosed either within @code{#| |#}, or else extend from a 
semicolon @code{;} to the end of the line. A comment is equivalent to 
whitespace, so @code{a#|bcd|#e} is the same as @code{a e}, not 
@code{ae}. The @code{#| |#} style comments can be nested (placed inside 
one another) without trouble, and are allowed to extend across multiple 
lines. Note that @code{#} by itself is nothing special and can be used as 
a normal character in, say, a symbol.

Lists are a sequence of atoms and/or other lists enclosed in parentheses. 
Empty lists can either be represented by the symbol @code{nil} or by the 
list @code{()}. There is nothing similar to the ``dotted pairs'' of Lisp; 
if you don't know what dotted pairs are, then don't worry about it. 
Tables and forms, both of which will be discussed in more detail later, 
are delimited by parentheses in the same manner as lists. Indeed, forms 
can be thought of as lists that start with a special symbol, or keyword. 
Lists might look like @code{(100 90 0)}, @code{("Lansing" "Denver")}, 
@code{((10 0 10) (5 10 15))}, @code{(cv bb dd)}, @code{("1 atom")}, or 
@code{nil}. Some examples of things which are not lists are 
@code{"1 atom"}, which, like it says, is one atom, and: @*
@code{(10 20 ; This comment can cause problems. )} @*
because everything past the semicolon is ignored. An acceptable 
alternative would be: @*
@code{(10 20 #| This comment will not cause problems. |#)}

All of the things mentioned above may range up to a very large size. In 
particular, numbers can generally hold values up to 32767 (sometimes 
referred to as TABHI or PROPHI in the documentation), though most 
games use values such as @code{99}, @code{999}, or @code{9999} for a value
which is too large to ever be reached.
Most tables are limited to be 127x127 at largest (which is really quite 
large); this is due to @i{Xconq's} present internal constraints on the 
number of unit types, terrain types, et cetera, that may be defined. 
Although strings and symbols are allowed to be quite large, one should 
exercise caution and keep them around a 100 characters or less in length, 
lest bugs (or ``unexpected features'') be tempted to emerge.

True/false values are just numbers, with no special characteristics.

@deffn GlobalConstant @code{true}
@end deffn
@deffn GlobalConstant @code{false}
These constants are symbolic forms for @code{1} and @code{0}.  They are
identical to numbers, but more descriptive for parameters that are
boolean-valued.
@end deffn

Unit, material, and terrain types are distinct objects.  However, they
can be considered to have numeric ``indices'' assigned in order of the
types' definition.  These numbers are not directly visible in GDL, but
they often affect sorting and ordering.

You may also supply numbers as @dfn{dice specs} in some cases.
The syntax of the dice specs should be familiar to those who play 
various RPGs.
There are two types of dice in Xconq: @dfn{Type 1 dice} and 
@dfn{Type 2 dice}.
@*Type 1 dice specs allow values to span both the positive and negative 
integers, including zero.
The syntax of Type 1 dice specs takes the form of 
@code{@var{n}d@var{ss}[+@var{ooo}]}, or
@code{@var{n}d@var{ss}[-@var{ooo}]}, where @var{n} is the number of 
dice, @var{ss} is the number of sides per die, and @var{ooo} is an 
offset to be added to or subtracted from the dice roll.
@*Type 2 dice specs restrict value ranges to be either wholly negative or 
wholly positive.  The value @code{0} is not allowed in the range.
The syntax of Type 2 dice specs takes the form of 
@code{-@var{n}d@var{ss}[-@var{ooo}]}, or
@code{@var{n}d@var{ss}[+@var{ooo}]}.
@*For both types of dice, @var{ss} is restricted from @code{2} to @code{17},
inclusive.
For Type 1 dice, @var{n} is restricted from between @code{1} and @code{8}, 
inclusive, and @var{ooo} is restricted from between @code{-128} and 
@code{127}, inclusive.
For Type 2 dice, @var{n} can be from between @code{1} and @code{8}, inclusive, 
with an offset restricted from @code{0} and @code{127}, inclusive, or 
@var{n} can be from between @code{-8} and @code{-1}, inclusive, with an 
offset restricted from @code{-127} and @code{0}, inclusive.
Both types of dice are 1-based, so they behave as you would expect.
For example, @code{1d8} yields values between @code{1} and @code{8}, 
inclusive, and @code{3d6} yields values between @code{3} and @code{18}, 
inclusive.  The dice spec @code{4d10+5} yields values between @code{9} 
and @code{45}, inclusive.
@*Note: The range of dice is quite limited because of the way Xconq stores 
them internally.  This problem may remedied at some later time.
@*Note: One cannot write chained dice specs, such as @code{3d5,1d4+2}.
All dice specs have only one homogeneous type of die involved.
@*Note: For those who have designed games in the past, yes, the present 
dice implementation does differ from the older implementation, which 
was 0-based, and allowed for @var{n} and @var{ss} to be 0.  This old 
behavior is no longer supported.
@*Note: Many things that accept dice specs can also take a restricted range 
of plain integers as well.  For example, a dice table may be able to also 
take on plain integer values from @code{-16384} to @code{16383}.

@node Conventions Used

@subsection Conventions Used

Descriptions of values in this manual follow the conventions listed here.

For parameters described as @var{t/f}, both @code{1}, @code{0} and
@code{true}, @code{false} may be used.  Parameters described as @var{n}
and @var{n%} are numbers.  Parameters described as @var{dist} or
@var{length} are also numbers, but are in the unit of measure for
lengths.  Parameters described as @var{str} or @var{string} are strings.

Parameters described as @var{u} or @var{ui}, @var{m} or @var{mi}, and
@var{t} or @var{ti}, are values that must be unit, material, or terrain
types, respectively.

Parameters described as @var{utype-value-list} match unit types with
values.  They can have several forms:

@itemize @bullet

@item
@code{(n1 n2 ...)} matches @code{n1} with type 0, etc in order.

@item
@code{((u1 n1) (u2 n2) ...)} evaluates @code{u1} to get a unit type,
then matches it with @code{n1}.  @code{u1} etc may also be a list of
types, in which case all the types get matched with @code{n1}.

@end itemize

Other types of lists, such as those defined as @var{side-value-list},
are interpreted similarly.  For all of these, multiple assignments to
the same type etc will overwrite quietly.

List values described as @var{interpolation-list} are lists of pairs
used to derive numerical values by interpolating between the listed
values.  The form of an interpolation list is always @code{((key1 val1)
(key2 val2) ...))}, where @var{keyi} and @var{vali} are numbers.  If the
input value @var{inp} to an interpolation matches @var{keyi}, the result
value is @var{vali}.  If it is between @var{keyi} and @var{keyi+1}, then
the result is gotten by linear interpolation, with the result value
falling somewhere between @var{vali} and @var{vali+1}.  Fractional
values always round down.  The @var{keyi} must occur in non-decreasing
order; it is legitimate for two consecutive keys to be identical, in
which the result value will be the value associated with the first key.
If the input value is outside the domain specified by the keys, the
result depends on the particular parameter; some will extrapolate in
some appropriate fashion, while others will generate an error or
warning. To be safe, one should set up key-value pairs for the min and 
max of the input domain.

One place where an interpolation list is used is the 
@code{acp-damage-effect} property that may be assigned to unit types. 
Suppose we have a unit type named @code{battleship}, which has 30 hit 
points and 6 action points when fully healthy. When the battleship 
reaches various levels of damage, we want to affect its ability to 
act to simulate such things as a gun turret or propeller being destroyed.
To do this, we can assign the @code{acp-damage-effect} property in 
perhaps the following way: @*
@smallexample
(unit-type battleship
(acp-damage-effect ((0 0) (10 2) (20 4) (30 6)))
)
@end smallexample
Now how many action points will the battleship have when it has 15 
hit points? The answer should be 3 action points. When it has 14 hit 
points? 2 action points (remember that fractional parts round down).
When it has 16 hit points? Again, 3 action points. When it has 10 
hit points? 2 action points (this can be read directly from the 
interpolation list). When it has 4 hit points? 0 action points.

Some values may be boolean expressions.  Boolean expressions are lists
headed by the keywords @code{and}, @code{or}, and @code{not}, and may
nest recursively.  For instance, the expression
@example
(and (or false (not false)) true)
@end example
is always true.  In some contexts, values other than @code{true} and
@code{false} may appear, in which case the interpretation of those
values depends on the context.

Some numeric values are @var{stochastic}, meaning that they are partly
fixed and partly probabilistic in effect.  The most common form of this
is values where the part > 100 is divided by 100, while the value mod
100 is the probability to add 1 to the first part.  Thus a value of 425
works out to a value of 4, 3/4 of the time, and to 5, 1/4 of the time,
on average.

Unless otherwise stated, all numeric values default to @code{0}, all
string values default to @code{""}, and all form values default to
@code{()}.  If one of these defaults has a notable consequence, such as
inability to perform some action, that will be mentioned.

@node Forms and Evaluation

@subsection Forms and Evaluation

A @dfn{form} is any single expression that appears in the file.
A GDL file consists of a sequence of forms.  Most forms of interest will
be lists whose first element is a symbol identifying the form.  For
instance, a form beginning with the symbol @code{side} declares a side
object.  When the file containing such a form is read, @i{Xconq} will
create a side object and fill in any properties as specified by the
form.  (Properties are like properties or attributes - most GDL objects
have some.)

In most contexts, @i{Xconq} will @dfn{evaluate} an expression before
using it, such as when filling in an object's property.  Numbers and
strings evaluate to themselves, while symbols evaluate to their
bindings, as set by @code{set} or @code{define}.  Lists evaluate to a
list of the same length, but with all the elements evaluated, unless the
first element of the list is a function.  In that case, the remaining
elements of the list are evaluated and given to the function, and its
result will be the result.

@node Tables

@subsection Tables

A @dfn{table} is a two-dimensional array of values indexed by types.
Indices can be any pair of unit, material, or terrain type.  The set of
tables is fixed by @i{Xconq}, and all are described below.

@deffn Form @code{table} table-name items@dots{}
This is the general form to fill in a table.  The table named by
@var{table-name} is filled in from the @var{items}.  If an item is an
atom, then every position in the table is filled in with that item,
overwriting any previously-specified values.  If an item is a list, it
must be a three-element list of the form @code{(@var{type1} @var{type2}
@var{value})}.  If both @var{type1} and @var{type2} are single types,
then @var{value} will be put into the table at the position indexed by
the two types.  If one of @var{type1} or @var{type2} evaluates to a
list, @i{Xconq} will iterate over all members of the list while keeping
the other type constant, while if both @var{type1} and @var{type2} are
lists, then @i{Xconq} will iterate over all pairs from the two lists.
The values used during iteration depend on whether the @var{value} is a
list.  If @var{value} is an atom, then that value will just be used on
every iteration.  If a list, then @i{Xconq} will use successive elements
of the list while iterating.

If the first member of @var{items} is the symbol @code{add}, then the
rest of the items will add to the existing contents of the table rather
than clearing to its default value first.
@end deffn

The following forms are all equivalent:
@example
(table foo (a y 1) (b y 2) (c y 3) (a z 9) (b z 9) (c z 9))

(table foo ((a b c) y (1 2 3)) ((a b c) (z) 9))

(define v1 (a b c))
(table foo (v1 y (1 2 3)) (v1 z 9))

(table foo ((a b c) (y z) ((1 2 3) (9 9 9))))

(table foo (a y 1) (b y 2) (c y 3))
(table foo add ((a b c) z 9))
@end example

@node Modifying Objects

@subsection Modifying Objects

Since forms normally define or create new objects, GDL defines the
@code{add} form to modify existing objects.

@deffn Form @code{add} objects property new-values@dots{}
This form evaluates the atom or list @var{objects} to arrive at the set
of objects to be modified.  Then it uses the @var{new-values} to write
new data into the property named @var{property} of those objects.  The
@var{new-values} may be a single number or string, or a list.
@end deffn

@node Symbols

@subsection Symbols

Most of the symbols used in a game module are the predefined ones
described in this manual.  Others are attached to types when the types
are defined, and still others name objects like units and sides.  You
can also define and set your own symbols to arbitrary values.

@deffn Form @code{define} symbol value
This form defines the symbol @var{symbol} to be bound to the result of
evaluating @var{value}.  If @var{symbol} is already defined, @i{Xconq}
will issue a warning, and ignore this form.
@end deffn

@deffn Form @code{set} symbol value
This form rebinds the already-bound symbol @var{symbol} to be bound to
the result of evaluating @var{value}.  If @var{symbol} is @emph{not}
bound already, then @i{Xconq} will issue a warning, but proceed anyway.
@end deffn

@deffn Form @code{undefine} symbol
This form destroys any binding of the @var{symbol}.  This is allowed for
any symbol, including already-unbound symbols.
@end deffn

@node Lists

@subsection Lists

Some transformations can be performed on lists. All of these are transforms 
are non-destructive, which is to say that the original list is not altered, 
but a new list with the transformation applied is returned as a result.

@deffn Function @code{quote} form@dots{}
This function prevents any evaluation of @var{form}.  (This implies that
the abovementioned evaluation of the argument list does @i{not} happen
for this ``function''.)
@end deffn

@deffn Function @code{list} form@dots{}
This function makes a list out of all the @var{form}.
@end deffn

@deffn Function @code{append} form@dots{}
NOTE: If you are not a Lisp programmer, be cautious about inferring what this 
function does based on its name.@*
This function "appends" all the @var{form} (which may be lists or not)
into a single list.  Another way to state the above is: @code{append} 
gathers everything following it into one list, "flattening out" any lists 
it encounters, and returns the result.
@end deffn

@deffn Function @code{remove} item list
This function removes @var{item} from every place that it occurs in 
@var{list}, returning the resulting list. If @var{item} is not found in 
@var{list}, then @var{list} is returned.
@end deffn

@deffn Function @code{remove-list} list1 list2
This function removes each item of list @var{list1} from every place that 
it occurs in @var{list2}, returning the resulting list. If no item in 
@var{list1} is found in @var{list2}, then @var{list2} is returned.
@end deffn

Some examples of the above commands:

The following three are all equivalent examples of quoting; they leave the 
list contents unevaluated when the list is first read.@*
@code{(quote not "independent")}@*
@code{'(not "independent")}@*
@code{`(not "independent")}@*

Quoting is useful for things that should not be evaluated immediately, but 
may be used Xconq later during run time (after the game has been read in).@*
These things include @code{synthesis-methods} and @code{possible-sides}.

Here is an example of appending:@*
@code{(define light-sea-u* (destroyer frigate))}@*
@code{(define heavy-sea-u* (battleship carrier))}@*
@code{(define sea-u* (append light-sea-u* heavy-sea-u*))}@*
In the above, two lists are defined. Then those two lists are joined 
into a single list, @code{sea-u*}. Note that @code{sea-u*} would 
be equivalent to the following definition:@*
@code{(define sea-u* (destroyer frigate battleship carrier))}@*
and not:@*
@code{(define sea-u* ((destroyer frigate) (battleship carrier)))}@*
because the lists were flattened.

Here is another example of appending:@*
@code{(define wyrms (red-wyrms blue-wyrms green-wyrms))}@*
@code{(define dragons (append wyrms dragon-turtle))}@*
In this case @code{wyrms} is a list, while @code{dragon-turtle} might be 
an atom. The definition of @code{dragons} would therefore be equivalent to:@*
@code{(define dragons (red-wyrms blue-wyrms green-wyrms dragon-turtle))}

Here is an example of removing a single item:@*
@code{(define land-combat-u* (infantry mechinf cavalry armor))}@*
@code{(define motor-land-combat-u* (remove infantry land-combat-u*))}@*
The definition of @code{motor-land-combat-u*} would then be equivalent to:@*
@code{(define motor-land-combat-u* (mechinf cavalry armor))}

@c Ex-ter-min-ate! Ex-ter-min-ate!
Here is an example of removing multiple items:@*
@code{(define monsters (daleks sontarans cybermen ice-warriors))}@*
@code{(define bad-robots (remove-list (sontarans ice-warriors) monsters))}

And here is a more sophisticated example of removing and appending:@*
@code{(define nco-ranks (chief senior-chief master-chief))}@*
@code{(define low-ranks (ensign lieutenant-jg lieutenant commander))}@*
@code{(define high-ranks (captain commodore r-admiral v-admiral admiral))}@*
@code{(define rank-sets (nco-ranks low-ranks high-ranks))}@*
@code{(define com-ranks (append (remove nco-ranks rank-sets)))}@*
which is equivalent to:@*
@code{(define com-ranks (append low-ranks high-ranks))}@*
which is equivalent to:@*
@code{(define com-ranks (ensign lieutenant-jg lieutenant commander captain commodore r-admiral v-admiral admiral))}@*
One should note that in the above example, a list, @code{nco-ranks}, was 
treated as the item to remove.

The above example can also be done in terms of @code{remove-list} instead:@*
@code{(define all-ranks (append nco-ranks low-ranks high-ranks))}@*
@code{(define com-ranks (remove-list nco-ranks all-ranks))}

@node Arithmetic Operations

@subsection Arithmetic Operations

GDL supports some basic mathematical operations. Addition, subtraction, 
multiplication, and division are all available. To use an operator, it 
must be at the start of a new form; everything after it until the end of 
that form will be interpreted as operands.

All four of the basic operators can operate on numbers, lists of numbers, 
and symbols which are bound to either numbers or lists of numbers, and 
any combination thereof. The only constraint is that all lists must be the 
same lengths as one another, with the exception that empty lists are allowed 
and will simply be skipped over. When a number is operated with a list, 
that number is operated with each item of the list. When a list is 
operated with a list, each item of the first operand list is operated 
with the item in the corresponding position of the second operand list. 
Thus, when a number is operated with a number, a number is always returned 
as the result. When a number is operated with a list or vice versa, a list 
is always returned as the result. When a list is operated with a list, then 
another list is always returned as the result.

Operators forms can be nested inside one another. Multiple operators 
within the same operator form are not allowed. Precedence is determined 
by evaluating the innermost (most deeply nested) operators first. 
Association is from left to right.

The results of operations are still subject to the same constraints as 
numbers and lists produced without operations. Value limits, such as 
@code{32767} and @code{-32768}, still apply. Because of this, you should 
be careful not to multiply, add, or subtract quantities that are too large 
in numeric magnitude or you may end up with undesired results.

Another thing to note about numbers is that, to Xconq, @code{10}, 
@code{10%}, and @code{0.10} are all the same thing. Likewise for 
@code{400}, @code{400%}, and @code{4.00}. Generally, when designing a 
game, you should not have to worry about how these number representations 
are handled internally; that is for the Xconq code writers to worry about. 
However, if you are doing math on numbers, this knowledge does come into 
play, unfortunately. For instance, if you use GDL to multiply a plain 
integer by a percent, you will not get a result that is a percentage of the 
integer. Some of the examples below will show you the correct way to deal 
with this and other similar situations. Also note that dice specs are 
treated as numbers internally in Xconq, and so there is a special way to 
manipulate them as well. Again, this will be demonstrated in the examples 
below.

@deffn Function @code{+} operands@dots{}
Sums all of the @var{operands} together. If only one operand is present, 
then that operand is returned unaltered. If no operands are present, then 
the additive identity, @code{0}, is returned.
@end deffn

@deffn Function @code{-} operand1 operands@dots{}
Subtracts all of the @var{operands} from @var{operand1}. If only 
@var{operand1} is present, then @code{0} minus @var{operand1} is 
returned. If no operands are present, then it returns @code{nil}.
@end deffn

@deffn Function @code{*} operands@dots{}
Multiplies all the operands together. Must have at least two operands 
to multiply, or else it returns @code{nil}, except when no operands 
are specified, in which case it returns the multiplicative identity, 
@code{1}.
@end deffn

@deffn Function @code{/} operand1 operands@dots{}
Divides all of the @var{operands} into @var{operand1}. If less than 
two operands are present, then it returns @code{nil}.@*
NOTE: Unlike Common Lisp, GDL does not support rational numbers, and 
therefore it is not possible for division with a single operand to return 
the reciprocal of that operand as Common Lisp implementations do. 
Furthermore, since all arithmetic is integer arithmetic in GDL, values 
between integers cannot be represented; numbers between @code{0} and 
@code{1} will appear as @code{0}.
@end deffn

Here are some examples of addition:@*
@code{(+ 1 1)}@*
  returns @code{2}@*
@code{(+ 1 2 3 4 5)}@*
  returns @code{15}@*
@code{(+ 1 (-1 2))}@*
  returns @code{(0 3)}@*
@code{(+ (50% 75%) 25%)}@*
  returns @code{(75% 100%)}@*
@code{(+ (0.33 0.67) (0.67 1.33))}@*
  returns @code{(1.00 2.00)}@*
@code{(define FOOD_RATS_LOSS 20%)}@*
@code{(define FOOD_ROT_LOSS 10%)}@*
@code{(define FOOD_LOSS (+ FOOD_RATS_LOSS FOOD_ROT_LOSS))}@*
  is the same as@*
@code{(define FOOD_LOSS 30%)}@*
@code{(+ (10 20) (30 40) (50 60) (70 80) (90 0))}@*
  returns @code{(250 200)}@*
@code{(+ 10 25 (+ 20 25))}@*
  returns @code{80}@*
@code{(+ -4)}@*
  returns @code{-4}@*
@code{(+ 190)}@*
  returns @code{190}@*
@code{(+)}@*
  returns @code{0}

Here are some examples of subtraction:@*
@code{(- 10 5)}@*
  returns @code{5}@*
@code{(- 15 5 4 3 2)}@*
  returns @code{1}@*
@code{(- 10 (4 5))}@*
  returns @code{(6 5)}@*
@code{(- (10 15) 10)}@*
  returns @code{(0 5)}@*
@code{(- (1.00 1.50) (0.25 0.45))}@*
  returns @code{(0.75 1.05)}@*
@code{(- 50%)}@*
  returns @code{-50%}@*
@code{(define burden 25%)}@*
@code{(define speed-effect (- burden))}@*
  is equivalent to@*
@code{(define speed-effect -25%)}

Here are some examples of multiplication:@*
@code{(* 5 5)}@*
  returns @code{25}@*
@code{(* 5 4 3 2 1)}@*
  returns @code{120}@*
@code{(* -1 (5 10))}@*
  returns @code{(-5 -10)}@*
@code{(* (25% 50%) 5)}@*
  returns @code{(125% 250%)}@*
@code{(* (2.00 5.00) (10 5))}@*
  returns @code{(20.00 25.00)}@*
@code{(*)}@*
  returns @code{1}

Here are some examples of division:@*
@code{(/ 14 2)}@*
  returns @code{7}@*
@code{(/ 15 2)}@*
  also returns @code{7}@*
@code{(/ 80 100)}@*
  returns @code{0}@*
@code{(/ 12 (6 4 3 2))}@*
  returns @code{(2 3 4 6)}@*
@code{(/ (15 10) 5)}@*
  returns @code{(3 2)}@*
@code{(/ (100% 250%) (2 5))}@*
  returns @code{(50% 50%)}

To take a percentage of a number, you need to do something like the 
following:@*
@code{(/ (* 4 50%) 100)}@*
  which returns @code{2}

To properly multiply a number by a decimal factor, you must do something 
like the following:@*
@code{(/ (* 5 4.00) 100)}@*
  which returns @code{20}@*
@code{(/ (* 40 0.25) 100)}@*
  which returns @code{10}@*
@code{(/ (* 3.00 3.00) 100)}@*
  which returns @code{9.00}, or @code{900} if you prefer to see it that way

To properly multiply a number by a fraction, try something like the 
following:@*
@code{(/ (* full-speed 4) 5)}@*
  which returns four-fifths of @code{full-speed}

For those seeking to do domething perhaps a bit trickier with GDL arithmetic 
operators, there is the manipulation of dice specs.
To properly manipulate dice specs requires some understanding of how 
Xconq internally represents dice.  Dice are stored in a 2-byte word.  
For values between @code{-16384} and @code{16383}, inclusive, this is treated 
as a short integer, and can be manipulated in a straightforward way.
Values above @code{16383} and below @code{-16384} are used by Xconq to 
encode dice specs into the internal representation of dice, where relevant.
@*All positive dice specs (Type 1 with positive offset and wholly-positive 
Type 2) are encoded starting at @code{16384} up to and including 
@code{32767}.
Likewise, all negative dice specs (Type 1 with negative offset and 
wholly-negative Type 2) are encoded starting at @code{-16385} down to and 
including @code{-32768}.
Thus, to get a positive dice spec, one must always start with @code{16384}, 
and to get a negative dice spec, one must always start with @code{-16385}.
@*A value of @code{16384} by itself is equivalent to @code{1d2}.
The least-significant 7 bits (bits 0 through 6, inclusive) are used to 
encode the offset.  Thus, @code{16385} is equivalent to @code{1d2+1}, 
and @code{16511} is equivalent to @code{1d2+127}.
@*The next 4 bits (bits 7 through 10, inclusive) are used to encode the 
sides of the dice.  Thus, @code{16512} is equivalent to @code{1d3}, and not 
@code{1d2+128}.  
Note that there is an implicit step-up/step-down of @code{2} in 
the die sides encoding; @code{2} sides are encoded as a @code{0}, 
@code{3} sides are encoded as a @code{1}, and so and so forth.
To properly encode the number of sides that you want your dice to have, 
follow this formula:
@smallexample
  (define sides-encoding (* (- numsides 2) 128))
@end smallexample
Thus @code{1d6} has its number of sides encoded as @code{512}, and the 
complete dice encoding is equivalent to @code{16896}.
@*The next 3 bits (bits 11 through 13, inclusive) are used to encode the 
number of dice.  Thus, @code{18432} is equivalent to @code{2d2}.
Note that there is an implicit step-up/step-down of @code{1} in the 
number of dice encoding; a single die is encoded as a @code{0}, 
@code{2} dice are encoded as a @code{1}, and so on and so forth.
To properly encode the number of dice that you want your synthetic dice spec 
to have, follow this formula:
@smallexample
  (define num-encoding (* (- numdice 1) 2048))
@end smallexample
Thus @code{5d2} has its number of dice encoded as @code{8192}, and the 
complete dice encoding is equivalent to @code{24576}.
@*The next bit (bit 14) is the dice indicator.  For positive dice specs, this 
bit should be set (i.e., one should add @code{16384} as already discussed). 
For negative dice specs, this bit should be unset (i.e., one should subtract 
@code{-16385} as already discussed).
@*The most significant bit is the sign bit; its interpretation by Xconq 
varies depending on whether the dice representation is being treated as a 
Type 1 or Type 2 dice.  For Type 1 dice, the sign bit only applies to the 
offset.  For Type 2 dice, the sign bit applies to both the number of dice 
and to the offset.
@*So a complete encoding of a positive dice spec is as follows:
@smallexample
  (define dice-encoding (+ 16384 offset (* (- numsides 2) 128) (* (- numdice 1) 2048)))
@end smallexample
For example, @code{3d6+5} would be encoded as follows:
@smallexample
  (define dice-encoding (+ 16384 5 (* (- 6 2) 128) (* (- 3 1) 2048)))
@end smallexample
A more sophisticated example, which shows the power of this method, is:
@smallexample
  (define xp-levels (1 2 3 4 5))
  (define hit-dice-levels (+ 16384 0 (* (- 6 2) 128) (* xp-levels 2048)))
@end smallexample
The above generates five levels of hit dice; level 1 is @code{2d6}, 
level 2 is @code{3d6}, and so on up to level 5, which is @code{6d6}.
@*Encoding the parts of a negative dice spec is essentially symmetrical with 
encoding the parts of a positive dice spec.

@node Arithmetic Comparisons

@subsection Arithmetic Comparisons

Xconq supports most of the typical Lisp arithmetic comparison operators 
in GDL.  In the case where only one expression is present in the comparison 
form, the result is always non-@code{nil}.  If any comparison fails, the 
result is @code{nil}.  If no comparison fails, then a true result like 
Lisp's @code{t} is returned.

@deffn Function @code{=} exp@dots{}
Test if all expressions are equal.
@end deffn

@deffn Function @code{/=} exp@dots{} 
Test if any expression is not equal to another one.
@end deffn

@deffn Function @code{>} exp@dots{} 
Test if the list of expressions is monotonically decreasing.
@end deffn

@deffn Function @code{>=} exp@dots{} 
Test if the list of expressions is monotonically nondecreasing.
@end deffn

@deffn Function @code{<} exp@dots{} 
Test if the list of expressions is monotonically increasing.
@end deffn

@deffn Function @code{<=} exp@dots{} 
Test if the list of expressions is monotonically nonincreasing.
@end deffn

@node Boolean Comparisons

@subsection Boolean Comparisons

Xconq supports the three primary boolean comparisons.  These comparisons 
are used in places such scorekeepers tests.  However, boolean comparisons 
are also used in side-and-side-class lists, and these follow special 
evaluations rules which do not conform to those listed below.  Always pay 
attention to the context of the boolean expression so that you can 
understand its evaluation behavior.

@deffn Function @code{and} exp@dots{}
The result is the last expression if all the operands are non-@code{nil}.
If any are false, then the result is @code{nil}.
@end deffn

@deffn Function @code{or} exp@dots{}
The result is the first non-@code{nil} expression.
If all are false, then the result is @code{nil}.
@end deffn

@deffn Function @code{not} exp
The result is @code{nil}, if the expression is non-@code{nil}.
Otherwise, the result is equivalent to Lisp's @code{t}.
@end deffn

@node Game Module Forms

@section Game Module Forms

The game module declaration supplies information about the file as a
whole.  It is optional; if missing, @i{Xconq} will get the module's name
from its file name, and supply defaults for the other properties.

@deffn Form @code{game-module} [ name ] properties@dots{}
This form defines the properties of this game module.  The optional
@var{name} is a string that will be used to look up the module in
libraries.  If the @var{name} is supplied, then this form is considered
to be the definition of the module, and overwrites any
@code{game-module} form previously appearing in this file.  If
@var{name} is missing, then this form will modify the existing
description of the module.  Although are currently no restrictions
enforced on the length or character set of a module name, @i{Xconq} may
warn about a name that does not match the name of the file containing
these forms.
@c ; see @xref{Files and Directories} for more detail.
@end deffn

@deffn ModuleProperty @code{title} string
If defined, this property is the name by which the module will be
displayed to players.  It is not used internally, so the name can be
modified freely (unlike the module's name, which may appear in other
modules).  Defaults to the module's name.
@end deffn

@deffn ModuleProperty @code{blurb} string
This property is a one-line description that users will see when they
are deciding whether to play the module.  It will be displayed without
any modification:
@example
Welcome to my nightmare! (version 1.0 with stronger goblins)
@end example
@end deffn

@deffn ModuleProperty @code{picture-name} string
This property is the name of a picture that may be displayed along with
the module's blurb, by those interfaces that support such pictures.
@end deffn

@deffn ModuleProperty @code{base-game} t/f
@end deffn

@deffn ModuleProperty @code{instructions} strings@dots{}
This property is a list of strings that are the instructions on how to
play the game.
@end deffn

@deffn ModuleProperty @code{notes} strings@dots{}
This property is a list of strings comprising the set of detailed
player's notes for the module.  Both the list and each string in the
list can be of any length.  When displayed, the strings are all
concatenated together, so the division into strings here is just for
convenience.  How these are displayed is up to the interface, but in
general an empty string signals a new paragraph.
@end deffn

@deffn ModuleProperty @code{design-notes} strings@dots{}
This property is a list of strings that are notes addressed to game
designers.
@end deffn

@deffn ModuleProperty @code{version} string
This property is the version of the module.  Defaults to @code{""},
which indicates that the module's version is undefined.
@end deffn

@deffn ModuleProperty @code{base-module} name
This property is the name of a module that must be loaded first.  It is
similar in effect to @code{include}.
@end deffn

@deffn ModuleProperty @code{default-base-module} name
This property specifies the name of a module that will be loaded if when
this module is loaded, no types are defined yet.

This is to allow a module to be used both as a standalone game and as a
data source for other games.  This is true of many maps, for instance.
@end deffn

@deffn ModuleProperty @code{original-module} name
@end deffn
@deffn ModuleProperty @code{original-version} string
@end deffn
@deffn ModuleProperty @code{original-variants} list
These properties record the module's name, version, and variant
selections before a game save.  They are needed to record the game in
the scorefile usefully.
@end deffn

@menu
* Module Variants::
* Including Other Modules::
* Conditional Loading::
@end menu

@node Module Variants

@subsection Module Variants

Variants are options chosen by players at the start of a game.  A
generic variant includes information that will be used for displaying
the choice to players, the acceptable range of choices, a default
choice, and additional forms that may be evaluated if particular values
were chosen.  Variant values are always numbers.

@deffn ModuleProperty @code{variants} items@dots{}
This property defines named variants on this module.  Variants appear as
startup options for the game.  Each item has the form
@example
([ @var{name} ] @var{type} [ @var{help} ] [ @var{range/default} ] [ @var{clauses} ])
@end example
The optional @var{name} is a string used to identify the choice to the
players, the @var{type} says what sort of change is being enabled,
@var{help} is an optional help string, @var{range/default} supplies a
range of values and a default value among them, and @var{clauses} is a
list of the form @code{(@var{value} @var{forms}@dots{})}, where the
@var{forms} are executed while reading if the value of the variant was
chosen to be @var{value}.  A game module may specify any number of
variants.  Defaults to @code{()}.
@end deffn

A number of commonly useful variant types are predefined.

@deffn VariantType @code{world-size} [ width [ height [ circumf [ lat [ lon ] ] ] ] ] [ clauses ]
This variant allows players to choose the size of the world.  The sizes
will default to the values in this variant's data.  (@var{width} and
@var{height} can be lists of the form @code{(lo dflt hi)}, with the
obvious interpretation??)
@end deffn

@deffn VariantType @code{world-seen} [ dflt ] [ clauses ]
This variant allows players to choose whether the terrain of the world
will be known at the start of the game.  The default setting will be the
value @code{dflt}, which may be either @code{true} or @code{false}.
@end deffn

@deffn VariantType @code{see-all} [ dflt ] [ clauses ]
This variant allows players to choose whether everything will be seen
always, as with the global variable @code{see-all}.  The default is set
by @code{dflt}.
@end deffn

@deffn VariantType @code{sequential} [ dflt ] [ clauses ]
This variant allows players to choose whether to move simultaneously
during a turn, or one at a time.  The default is set by @var{dflt}.  The
variant works by setting @code{use-side-priority}.
@end deffn

@deffn VariantType @code{real-time} [ total [ perside [ perturn ] ] ] [ clauses ]
This variant allows players to choose realtime limits on the game.  The
value will default to the values in this variant's data.
@c but what about upper/lower limits?
@end deffn

@deffn VariantType @code{economy}
This variant enables/disables the backdrop economy.
@end deffn

@deffn VariantType @code{supply}
This variant enables/disables the advanced supply line system.
@end deffn

@node Including Other Modules

@subsection Including Other Modules

You can include one game module in another.

@deffn Form @code{include} module-name [ variant-settings ]
This form has the effect of inserting the contents of @var{module-name}
into the current position in the module.  @code{game-module} forms in
the included module are not inserted, although they are remembered and
may appear in displays.  @i{Xconq} will fail completely if the included
module cannot be found.

Unlike C etc, the same module cannot be included more than once; you
will get a warning and the module will not be loaded.
@end deffn

Note that the module names are not file names, so that system-specific
features like directories and devices cannot be included.  The mapping
between module name and file name is interface-specific, so if you want
to distribute a module, you should make sure all the module names don't
have anything nonportable embedded.  Alphanumeric characters and hyphens
are guaranteed to be portable; mixed-case names are not.

@node Conditional Loading

@subsection Conditional Loading

You can control which forms in a module are actually evaluated by using
conditional loading.

@deffn Form @code{if} test-form sym
@end deffn
@deffn Form @code{else} sym
@end deffn
@deffn Form @code{end-if} sym
If @var{test-form} evaluates to @code{true}, then all subsequent forms,
up until the matching @code{else} or @code{end-if}, will be evaluated.
If @code{false}, then the forms will be read but not evaluated.  All
forms inside the conditional must be syntactically correct.
@end deffn

@node World and Area Forms

@section World and Area Forms

The world consists of one @dfn{area}, which is regular in shape and
consists of a number of @dfn{cells}.  Each cell has a type of terrain
and a number of optional data values.  Each kind of per-cell data will
be called a @dfn{layer} of the area.

@deffn Form @code{world} [ circumference ] properties@dots{}
This form defines the properties of the world as a whole.
@end deffn

@deffn Form @code{area} [ width [ height ] ] [ restriction ] properties@dots{}
This form defines the playing area of the world.  The @var{restriction}
identifies how to get data for this area from subsequent forms that are
based on larger areas.
@end deffn

@menu
* World Properties::
* Area Properties::
* Layers::
* Distances and Elevations::
* Temperatures::
* Winds::
* Clouds::
* User::
@end menu

@node World Properties

@subsection World Properties

@deffn WorldProperty @code{circumference} dist
This property is the distance in cells around the entire world (as a
sphere).  Default is @code{360}.
@end deffn

@deffn WorldProperty @code{axial-tilt} n
This property defines the extremes of seasonal changes.
If this is positive and the sunlit region is dynamically changing throughout 
the year, then the sun starts at the vernal equinox.  If this is negative and 
the sunlit region is dynamically changing throughout the year, then the sun 
starts at the autumnal equinox.
@end deffn

@node Area Properties

@subsection Area Properties

@deffn AreaProperty @code{width} n
@end deffn
@deffn AreaProperty @code{height} n
These properties are the width and height of the world, as measured in
cells.  Allowable values range from 3x3 up to 32767x32767, which is one
billion cells!  If only one of these is given, then the other defaults
to the same value.  If neither has been given, then they default to
@code{60} and @code{30}, respectively.
@end deffn

In the case of a cylinder, the world wraps around in the x direction,
and the width is the diameter of the cylinder, while the height is just
the height in the usual sense.  A hexagon world is flat on the top and
bottom; its width is measured across the middle height, which is the
largest span, and height is the same as for cylinders.  Here are some
crude pictures, first of an 8x6 cylinder:
@example
# # # # # # # #
 : : + + : : : :
: : : + ^ : : :
 : : : : : : : :
: : : : ^ : : :
 # # # # # # # #
@end example

This world is an 8x7 hexagon:
@example
   # # # # #
  # : + + : #
 # : : + ^ : #
# : : + ^ : : #
 # : : : : : #
  # : : ^ : #
   # # # # #
@end example

There are two kinds of properties that an area may have: scalar values
such as latitude, and layer values such as terrain and elevation.

@deffn AreaProperty @code{latitude} n
This property is the offset, in cells, from the equator of the middle of
the area (height / 2).
@end deffn

@deffn AreaProperty @code{longitude} n
This property is the offset, in cells, from the ``Greenwich Meridian''
of the world.
@end deffn

@deffn AreaProperty @code{projection} n
This property defines the mapping from the world to the area.  The
default value of @code{0} maps lat,long positions to x,y coordinates
directly (with the effect of stretching high latitude terrain
horizontally).  A value of @code{1} bends x coordinates in towards the
middle of the area, proportionally to the latitude (meridians will be
curved in a familiar fashion).
@end deffn

@deffn AreaRestriction @code{restrict} w h x y | @code{reset}
This is a special subform that specifies that subsequent layers in an
area of size @var{w} x @var{h} will be offset by @var{x},@var{y} and then read
into the actual area.  (This is useful for setting up a scenario that
needs only a subset of a full map.)

If the restriction specifies @code{reset} rather than four numbers,
it means to cancel the restriction and return to normal area layer
processing.

Note that an area restriction is not a property, and must always appear
before any properties in an area form.
@end deffn

@node Layers

@subsection Layers

@dfn{Layers} constitute the bulk of data about an area of the world.
Each layer assigns a value to each cell in the area; examples include
cell terrain, temperatures, elevations, and so forth.  Since there may
be many cells in a layer with the same values, each layer uses a common
run-length encoding scheme.  In this scheme, each horizontal band of
cells is a separate text string, and the contents of the string encode
individual numeric values, one for each cell.  The encoding uses the
characters @code{a..~} and @code{:..[} for 0 through 63, and decimal
digits followed by commas (or the end of the string) for all other
numbers.  An optional @code{-} is allowed, and indicates a negative
value.  Runs of constant value are prefixed with their length, in
decimal.  The character @code{*} separates run lengths from values
expressed as digits.  Thus, the string
@example
"40adaa100,2*-99"
@end example
represents 46 values in all: 40 zeroes, a three, 2 more zeros, a 100,
and two -99s.  Although this format is quite unreadable, it has the
advantages of compactness and portability; the expectation is that most
layer editing will be done on-line.  Note that the run encoding is
entirely optional.

The following subforms at the beginning of layer data have special
effects.

@deffn LayerSubform @code{constant} n
This subform causes every value in the layer to be set to @var{n}.
@end deffn

@deffn LayerSubform @code{subarea} x y w h
This subform indicates that the layer data should be positioned at the
given rectangle in the layer.
@end deffn

@deffn LayerSubform @code{xform} mul add
This subform has the effect of first multiplying the raw value by
@var{mul}, then adding @var{add} and storing the result into the layer.
@end deffn

@deffn LayerSubform @code{by-bits}
@end deffn

@deffn LayerSubform @code{by-char} str
This subform specifies that the characters in @var{str} give the
encodings of values in the layer.  The first character in @var{str}
encodes 0, the second encodes 1, and so forth.
@end deffn

@deffn LayerSubform @code{by-name} name-list
[what is the syntax of name-list exactly?]
This subform is for generic worlds that are useful across multiple game
designs.  It has the syntax @code{((sym1 n1) (sym2 n2) ...)}, where
@var{symi} is either a symbol or number that is the real value in the
layer, and @var{ni} is the value used in the layer's encoding.  For
example, in the terrain layer, this allows for the matching of terrain
types by name, so that if, say, the ``sea'' terrain type was type #0 in
one game and type #4 in another, the world would have sea in all the
same places after it was read in.  In practice, only a few worlds are
this general.  If a value appears in the layer's data that is not
listed, that value will simply go into the layer verbatim.
@end deffn

@deffn AreaProperty @code{terrain} layer-data@dots{}
This property is the actual layer of terrain types for cells.
@end deffn

@deffn AreaProperty @code{aux-terrain} terrain-type layer-data@dots{}
This property fills in values for borders, connections, and coatings.
For border and connection terrain, the value is a six-bit number
(0..63), with a bit turned on in each direction that there is a border
or connection.  For coating types, the value is the depth of the
coating.
@end deffn

@deffn AreaProperty @code{features} feature-list layer-data@dots{}
This property specifies the nature and location of all geographical
features.  The @var{feature-list} is a list of lists, where each sublist
has the form @code{([@var{id}] @var{typename} @var{name})} where
@var{id} is the numerical id referenced in the layer data (defaults to
feature's position in the @var{feature-list}), @var{typename} is a
symbol or string giving the general type of feature (such as
@code{continent}), and @var{name} is the name of the feature (such as
@code{"Asia"}).  If the name includes the string @code{"%T"}, then the
feature's type will be substituted at that position; so for instance the
name @code{"%T of Mexico"} with a type @code{gulf} results in a
displayed name @code{"Gulf of Mexico"}.
@end deffn

@deffn AreaProperty @code{material} material-type layer-data@dots{}
This property declares the quantity of the given @var{material-type} in
each cell of the area.
@end deffn

@deffn AreaProperty @code{people-sides} layer-data@dots{}
This property says which side the people of each cell are on.  A
@var{side-encoding} of @code{exact} assigns 0 to independence (no side),
1 to the first side, and so forth; otherwise, the encoding is a list of
side names/ids and numbers.
@end deffn

@deffn AreaProperty @code{control-sides} layer-data@dots{}
This property says which side controls each cell.  The encoding is the
same as for @code{people-sides}.
@end deffn

@node Distances and Elevations

@subsection Distances and Elevations

The unit of elevation is arbitrary, with its relation to cells defined by the
area's cell width.

@deffn AreaProperty @code{elevations} layer-data@dots{}
This property is the world elevation data itself.  If any elevation
falls outside the min/max elevation range for the terrain type of the
cell, then it will be truncated appropriately.
@end deffn

@deffn AreaProperty @code{cell-width} elev
This property is the distance across a single cell, expressed as units
of elevation.  Defaults to @code{1}.
@end deffn

@node Temperatures

@subsection Temperatures

Each type of terrain has a temperature range in which it may be found.
Any calculation that would fall outside this range will be clipped.

The temperature can be set to have a given value at a given elevation.
All air temperatures will be interpolated appropriately.

@deffn GlobalVariable @code{temperature-floor} n
This variable is the lowest possible temperature.
@end deffn

@deffn GlobalVariable @code{temperature-floor-elevation} n
This variable is the value of elevation at which the temperature is
always at @code{temperature-floor}.
@end deffn

@deffn AreaProperty @code{temperatures} layer-data@dots{}
This property contains the temperature data itself.  If any temperature
falls outside the min/max temperature range, then it will be truncated
appropriately.
@end deffn

@node Winds

@subsection Winds

Winds are defined as having a nonnegative force and a direction.

@deffn AreaProperty @code{winds} layer-data@dots{}
This property contains the force and direction of the prevailing winds
in each cell.
@end deffn

@node Clouds

@subsection Clouds

Cloud cover is defined as a layer over the terrain, with a bottom and
top and density for each cell.

@deffn AreaProperty @code{clouds} layer-data@dots{}
This property is the degree of cloud cover over each cell.  A value of
@code{0} corresponds to clear skies.
@end deffn

@deffn AreaProperty @code{cloud-bottoms} layer-data@dots{}
This property is the altitude above the ground of the bottoms of the
clouds.
@end deffn

@deffn AreaProperty @code{cloud-heights} layer-data@dots{}
This property is the vertical thickness of the cloud cover in each cell.
@end deffn

@node User

@subsection User

Advanced units' use of the surrounding area is recorded in the user
layer.

@deffn AreaProperty @code{user} layer-data@dots{}
This property indicates which unit is using which cells for production.
@end deffn

@node Side and Player Forms

@section Side and Player Forms

@deffn Form @code{side} [ num ] [ id ] properties@dots{}
This form has the effect of declaring a side to exist.  If the number 
@var{num} or symbol @var{id} is supplied and matches that of a side 
that has already been created, then the properties will modify the 
pre-existing side.
Otherwise a new side object will be created, with a arbitrarily-chosen
numeric id ranging between 1 and @code{sides-max}.  If the given
@var{id} is a symbol, then the side's numeric id will be bound to that
symbol.
@end deffn

@deffn GlobalVariable @code{sides-min} n
The minimum number of sides that are required for a game. A new game 
cannot be started with fewer than @code{sides-min} sides. Defaults to 
@code{1}.
@end deffn

@deffn GlobalVariable @code{sides-max} n
The maximum number of sides that are allowed in a game. This is a limit 
which is set by the designer of the game module. @i{Xconq} also has a 
built-in upper limit (@code{MAXSIDES}), and this is typically @code{15}. 
Defaults to @code{MAXSIDES}.
@end deffn

@deffn GlobalVariable @code{sides-wanted} n
The ideal number of sides for a game. This is the initial number of sides 
that a new game will have during side setup. This should be between 
@code{sides-min} and @code{sides-max}, inclusive. Defaults to @code{2}.
@end deffn

@deffn Form @code{side-defaults} properties@dots{}
This form sets the defaults for all newly-created sides declared
subsequently.  These defaults will be set before the new side's
properties are interpreted.  This form has no effect on existing sides
or on side declarations that modify existing sides.
@end deffn

@menu
* Side Name Properties::
* Side Class::
* Status in Game::
* Side Relationships::
* Numbering Units::
* Side-Specific Namers::
* Side Tech Levels::
* Side Views::
* Interaction::
* Doctrine::
* Side Action Restrictions::
* Other Side Properties::
* Independent Side::
* Players::
* Rules of Side Configuration::
@end menu

@node Side Name Properties

@subsection Side Name Properties

If the game design allows, all of these properties can be set at startup
by the players (see <side config> and below).  Omission of some of these
results in suppression or substitution, depending on the interface and
the situation.  Omission of all name properties allows the side to go
unmentioned, which is useful when the concept of ``side'' is useless or
confusing to a player (as in some adventure games).  All of these
properties may be set at any time by any player.

@deffn SideProperty @code{name} str
This property is the proper name of a side, as a country or alliance
name.  Examples include @code{"Axis"} and @code{"Hyperborea"}.
@end deffn

@deffn SideProperty @code{long-name} str
This property is the long form of a side's name, as in @code{"People's
Republic of Hyperborea"}.  Defaults to be the same as the side's name.
@end deffn

@deffn SideProperty @code{short-name} str
This property is an short name or acronym for the side, often just the
letters of the long name, as in @code{"PRH"}.
@end deffn

@deffn SideProperty @code{noun} str
This property is the name of an individual unit or person belonging to
the side.  Defaults to @code{""}, which suppresses any mention of the
side when (textually) describing the individual.
@end deffn

@deffn SideProperty @code{plural-noun} str
This property is what you would call a group of individuals.  Defaults
to the most common plural form of the @code{noun} (in English, the
default pluralizer adds an ``s''), so any alternative plural noun, such
as @code{"Chinese"}, will need an explicit @code{plural-noun} value.
@end deffn

@deffn SideProperty @code{adjective} str
This property is an adjective that can be used of individuals on the
side, as in @code{"Spanish"}.  Defaults to @code{""}, which suppresses
use of the adjective.
@end deffn

As a complete example, a side named @code{"Poland"} would have a long
name @code{"Kingdom of Poland"}, short name @code{"Po"}, noun
@code{"Pole"}, plural noun @code{"Poles"}, and adjective
@code{"Polish"}.

Alternatively, one can specify a side namer to do the work of naming 
sides.

@deffn GlobalVariable @code{side-namer} namer-id
The name of a known namer that will be used to generate the names of 
all the sides (except the independent side). Defaults to 
@code{default-side-names}.
@end deffn

@deffn SideProperty @code{color} str
This property is a comma-separated list of colors that represents the
side.  Defaults to @code{"black"}.
@end deffn

@deffn SideProperty @code{emblem-name} str
This property is the name of a graphical icon that represents the side.
An emblem name of @code{"none"} suppresses any emblem display for the
side.  Defaults to @code{""}, which gives the side a randomly-selected
emblem.
@end deffn

@deffn SideProperty @code{names-locked} t/f
If the value of this property is @code{true}, then the player cannot
modify any of the side's names.  Defaults to @code{false}.
@end deffn

@node Side Class

@subsection Side Class

@deffn SideProperty @code{class} str
This property is a side's class, which is a keyword that characterizes
the side.  Any number of sides may be in the same class.
@end deffn

@node Status in Game

@subsection Status in Game

Once a side is in the game, it can never be totally removed.  However,
sides can become inactive.

@deffn SideProperty @code{active} t/f
This property is @code{true} if the side is still actively participating
in the game.  If the side has won, lost, or simply withdrew, this will
be @code{false}.  Any units on a side not in the game are effectively
frozen statues; they don't do anything, and are untouchable by anyone
else.  Defaults to @code{true}.
@end deffn

@deffn SideProperty @code{status} lose/draw/win
This property tells how this side did in the game.  Defaults to
@code{draw}.
@end deffn

@deffn GlobalConstant @code{win}
@end deffn
@deffn GlobalConstant @code{draw}
@end deffn
@deffn GlobalConstant @code{lose}
These constants are the different possible values for a side's status.
@end deffn

@deffn SideProperty @code{ever-active} t/f
This property records if the side was ever active during the course of a
game.  Sides that were never active (perhaps because they are used in
some scenarios of a game design but not others) will not be recorded in
the scorefile.
@end deffn

@deffn SideProperty @code{advantage} n
@end deffn
@deffn SideProperty @code{advantage-min} n
@end deffn
@deffn SideProperty @code{advantage-max} n
Initial and min/max limits on advantage for the side.  All default to
the values of the corresponding global variables.
@end deffn

@node Side Relationships

@subsection Side Relationships

By default, sides are neutral with respect to each other.

@dfn{Control} is a situation where one side can observe and move another
side's units, but not vice versa.  The controlling side can also just
take the units of the controlled side.  If the controlled side loses or
resigns, then the controlling side automatically gets everything.  Both
sides must agree to this relationship.

@deffn SideProperty @code{controlled-by} side
This property refers to the side controlling this one.  If 0, then the
side is not under control.
@end deffn

The closest side relationship is one of trust.  A trusted side unit's
may do anything at any time, including entering and leaving units on the
other side, consuming the other side's materials, and so forth.

@deffn SideProperty @code{trusts} side-value-list
This property is true for any side that is trusted by this side.  Note
that this relationship need not be symmetrical.  Defaults to
@code{false} for all sides.
@end deffn

Note that these parameters apply only to relationships as enforced by
@i{Xconq}.  In an actual game, both human and robot sides can make
agreements and have positive/negative opinions about the other sides.

@deffn SideProperty @code{trades} side-value-list
This property defines the trading relationship with other sides.
@*Note: Currently not implemented.
@end deffn

@node Numbering Units

@subsection Numbering Units

@deffn SideProperty @code{next-numbers} utype-value-list
This property gives the next serial numbers that will be assigned to
units acquired by this side.  Defaults to @code{1} for each unit type
(Dijkstra notwithstanding, that's still where people start numbering
things).
@end deffn

If the unit is of a type that gets numbered (@code{assign-number}
property is true), then any unit of that type, acquired by any means
whatsoever, will be assigned the @code{next-numbers} value for that type
and @code{next-numbers} will be incremented.

@node Side-Specific Namers

@subsection Side-Specific Namers

A side can have its own set of namers (see below) that will be used for
units and geographical features associated with that side.

@deffn SideProperty @code{unit-namers} utype-value-list
This property specifies which namers will be used with which types that
the side starts out with or creates new units.  These will not be run
automatically on captured units or gifts.
@end deffn

@deffn SideProperty @code{feature-namers} feature-type-value-list
This property specifies which namers to use with which geographical
features in the side's initial country (if if has one).  Defaults to
@code{()}.
@end deffn

@node Side Tech Levels

@subsection Side Tech Levels

The tech level of a side determines what it can do with each type of unit.

@deffn SideProperty @code{tech} utype-value-list
This property assigns a tech level to each unit type named.
@end deffn

@deffn SideProperty @code{init-tech} utype-value-list
This property is the tech level at the beginning of the current turn.
@end deffn

@deffn SideProperty @code{advances-done} atype-value-list
This property is the state of the side's research on each advance.  A
value of -1 indicates that the advance has been achieved.
@end deffn

@deffn SideProperty @code{advance-goal} atype
The research goal that the side is presently working toward.
@end deffn

@deffn SideProperty @code{current-advance} atype
The research topic that the side is presently working on.
@end deffn

@node Side Views

@subsection Side Views

View-related properties record the side's knowledge about the world,
other units, weather, etc.

These properties are necessary only if the relevant globals are set a
certain way (@code{see-all} is false, etc).

@deffn SideProperty @code{terrain-view} layer-data@dots{}
This property is the side's current knowledge of the world's terrain.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{terrain-view-dates} layer-data@dots{}
This property is the dates of the side's current knowledge of the
world's terrain.  Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{aux-terrain-view} ttype layer-data@dots{}
This property is the side's current knowledge of the world's aux terrain
of type @var{ttype}.  Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{aux-terrain-view-dates} ttype layer-data@dots{}
This property is the dates of the side's current knowledge of the
world's aux terrain of type @var{ttype}.  Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{unit-views} unit-view@dots{}
This property is the side's current knowledge of the positions of units
in the world.  It is a list of @var{unit-view} objects, where each has
the forms @code{(type side id x y)}.  Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{material-view} mtype layer-data@dots{}
This property is the side's current knowledge of the amounts of each
type of material at each location in the world.  Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{material-view-dates} ttype layer-data@dots{}
Defaults to @code{()}.
@end deffn

If the weather is not always known and up-to-date, then the following
properties what is known and when the information was recorded.

@deffn SideProperty @code{temperature-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{temperature-view-dates} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-bottom-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-height-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-view-dates} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{wind-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{wind-view-dates} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@node Interaction

@subsection Interaction

@deffn SideProperty @code{initial-center-at} x y
This property is the preferred location at which to center the first map
displayed by an interface.
@end deffn

@deffn SideProperty @code{turn-time-used} seconds
This property is the number of (real) seconds that this side has been
moving units during the present turn.
@end deffn

@deffn SideProperty @code{total-time-used} seconds
This property is the number of (real) seconds that this side has been
moving units during the course of the game.
@end deffn

@deffn SideProperty @code{timeouts} n
This property is the number of ``time outs'' a side gets for the game.
@end deffn

@deffn SideProperty @code{timeouts-used} n
This property is the number of ``time outs'' a side has already used up.
@end deffn

@deffn SideProperty @code{finished-turn} t/f
This property is true if the side has declared that it is finished
moving things during this turn.  Defaults to @code{false}.
@end deffn

@deffn SideProperty @code{willing-to-draw} t/f
This property is true if the side will go along with any other side that
wants to end the game in a draw.  Defaults to @code{false}.
@end deffn

@node Doctrine

@subsection Doctrine

Doctrines are objects that units consult to decide about individual
behavior.

@deffn SideProperty @code{doctrines} utype-property-groups@dots{}
This property is the side's unit-type-specific doctrine.  Each
@var{utype-property-group} has the form @code{(@var{unit-types}
doctrine)}.  Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{doctrines-locked} t/f
This property says whether the docrine-unit type correspondence for the
side may be altered during the game.  This property does not control
whether or not the properties of the doctrines may be altered.  Defaults
to @code{false}.
@end deffn

@deffn SideProperty @code{default-doctrine} doctrine-id
This property is the base doctrine that applies to all unit types by
default.
@end deffn

@deffn Form @code{doctrine} [ id ] properties@dots{}
This form creates a doctrine with the given id and properties.
@end deffn

@deffn DoctrineProperty @code{resupply-percent} n%
This property indicates that when the level of a operationally-consumed
material is at @var{n%} of capacity, try to resupply.  Defaults to
@code{50}.
@end deffn

@deffn DoctrineProperty @code{rearm-percent} n%
This property indicates that when the level of a combat-consumed
material is at @var{n%} of capacity, try to resupply.
@end deffn

@deffn DoctrineProperty @code{repair-percent} n%
This property indicates that when the unit's hp is at @var{n%} of max,
make a plan to repair.
@end deffn

@deffn DoctrineProperty @code{construction-run} type-value-list
This property is the default number of units to build when construction
has been requested.
@end deffn

@deffn DoctrineProperty @code{locked} t/f
This property is true if the properties of the doctrine cannot be
modified by the side's player during the game.  Defaults to
@code{false}.
@end deffn

@node Side Action Restrictions

@subsection Side Action Restrictions

Sides can be restricted to only acting with certain kinds of units, 
or only doing certain kinds of actions.

@deffn SideProperty @code{could-act-with} utype-value-list
A list of unit type and boolean pairs.  
If the boolean value is @code{true}, 
then the side can use the unit type to act with.  
If @code{false}, then the side cannot use the unit type to perform 
any actions.
Defaults to @code{true} for all unit types for all sides but the independent 
sides.  Defaults to @code{false} for all unit types for the independent side.
The differing behavior of the independent side is due to legacy reasons.
@end deffn

@deffn SideProperty @code{could-construct} utype-value-list
A list of unit type and boolean pairs.
If the boolean value is @code{true}, 
then the side can construct the unit type.
If @code{false}, then the side cannot construct the unit type.
Defaults to @code{true} for all unit types.
@end deffn

@node Other Side Properties

@subsection Other Side Properties

@deffn SideProperty @code{self-unit} unit
This property identifies a unit that represents the side itself.  The
value may be a unit id, number, string, or symbol.  Defaults to
@code{0}, which means that no unit represents the side.  See below for
more details on self units.
@end deffn

@deffn SideProperty @code{units} list
This property is a weighted list of units that could be given to the
side during setup in order to satisfy the side's @code{start-with}
numbers.
@end deffn

@deffn SideProperty @code{treasury} mtype-value-list
This property is the quantity of each type of material belonging
to the side as a whole, independent of materials in specific units.
@end deffn

@deffn SideProperty @code{priority} n
The order in which the side will get to act, relative to other sides and
to units.  Defaults to @code{-1}.  Note that the @code{sequential}
variant will automatically cause side priority to be set to nonnegative
values, unless the value is already nonnegative.
@end deffn

@deffn SideProperty @code{action-priorities} (utype val)@dots{}
This property is the acting priority of units belonging to the side.
@end deffn

@deffn SideProperty @code{scores} (skid val)@dots{}
This property is the current values of any numeric scores being kept for
the side.  It is a list of pairs of scorekeeper id and value.  Defaults
to @code{()}.
@end deffn

@deffn SideProperty @code{attack-stats} n@dots{}
@end deffn
@deffn SideProperty @code{hit-stats} n@dots{}
These properties are the raw counts of attacks and hits, by attacking
and defending unit types.  Default to @code{()}.
@end deffn

@deffn SideProperty @code{gain-counts} n@dots{}
@end deffn
@deffn SideProperty @code{loss-counts} n@dots{}
These properties are the raw counts of unit gains and losses, organized
by unit type and gain/loss reason.
@end deffn

@deffn Form @code{independent-units} properties@dots{}
Like the @code{side} form, but sets properties for independent units.
@end deffn

@deffn SideProperty @code{ui-data} data@dots{}
This property contains interface-specific data for the side.  This is
mainly for preservation across game save/restores.  The property's value
has the form
@example
@code{((interface-type data) (interface-type data) ...)}
@end example
so that each interface can maintain its own data separately.
@end deffn

@deffn SideProperty @code{ai-data} data@dots{}
This property is information about the AIs associated with a side.  The
property's value has the form
@example
@code{((ai-type data) (ai-type data)
...)}
@end example
so that each type of AI can maintain its own data separately.  The form
and meaning of each AI's data is specific to it alone.
@end deffn

@deffn SideProperty @code{standing-order} data@dots{}
This property contains the list of standing orders for the side.
@end deffn

@deffn GlobalConstant @code{always}
This symbol indicates a standing order that is always to be executed
by a unit.
@end deffn
@deffn GlobalConstant @code{@@}
This symbol indicates a standing order that units of the specified
types are to execute when at a given location.
@end deffn
@deffn GlobalConstant @code{in}
This symbol indicates a standing order that units of the specified
types are to execute when occupying a given unit.
@end deffn
@deffn GlobalConstant @code{near}
This symbol indicates a standing order that units of the specified
types are to execute when within a given distance of a given location.
@end deffn

@node Independent Side

@subsection Independent Side

The independent side is in most ways a side like the others, but
in other ways it is incomplete.  For instance, independent units
act, well, independently of each other.

@deffn GlobalVariable @code{no-indepside-ingame} t/f
This variable is true if the game should not allow the players to make
the independent units active.  This is appropriate for historical games
where all the participating side are predefined, for instance.
@end deffn

@deffn GlobalVariable @code{indepside-has-ai} t/f
This is true if an AI should be created for the independent side.
@end deffn

@deffn GlobalVariable @code{indepside-can-build} t/f
This is true if independent units may construct new units.
@end deffn

@deffn GlobalVariable @code{indepside-can-develop} t/f
This is true if independent units may develop their technology.
@end deffn

@node Players

@subsection Players

Player objects are rarely necessary when building game designs; they
typically only appear in saved games, in order to ensure that the same
players get the same sides upon restoration.

@deffn SideProperty @code{player} id
This property is the unique identifier of a player that is running this
side.  Defaults to @code{0}, which means that no player has been
assigned to the side.
@end deffn

@deffn Form @code{player} [ id ] properties@dots{}
This form defines a player.  If the @var{id} is supplied and matches the
id of an existing player, then the player object is updated using the
@var{properties}, otherwise a new player object will be created, using
the given @var{id} if supplied, otherwise creating a new value.
@end deffn

@deffn GlobalVariable @code{player-sides-locked} t/f
This variable is @code{true} if the player/side assignment may not be
changed while the game is starting up.  Defaults to @code{false}.
@end deffn

The number of players must always be less than the number of sides
(sides without players just don't do anything).

@deffn PlayerProperty @code{name} str
This property identifies the player by name.
@end deffn

@deffn PlayerProperty @code{config-name} str
This property identifies a particular set of doctrine and other
definitions that the player is using.
@end deffn

@deffn PlayerProperty @code{display-name} str
This property identifies the display being used by the player's
interface.  The interpretation of this value is dependent on the
interface in use.
@end deffn

@deffn PlayerProperty @code{ai-type-name} str
This property is the type of AI that will play the side if requested or
necessary.  The set of choices depends on what has been compiled into
@i{Xconq}.  (The general-purpose AI type @code{"mplayer"} will usually
be available, but is not guaranteed.)  An @code{ai-type-name} of
@code{""} means that no AI will run this player.
@end deffn

@deffn PlayerProperty @code{password} str
This property is the encoding of a password that must be entered before
this player object can be reused successfully.
@end deffn

@deffn PlayerProperty @code{initial-advantage} n
This property is an initial relative strength at which the player should
start.  Some synthesis methods can use this to give more units or some
other advantage to each player according to the requested strength.
Defaults to @code{1}.
@end deffn

@deffn GlobalVariable @code{advantage-min} n
@end deffn
@deffn GlobalVariable @code{advantage-max} n
@end deffn
@deffn GlobalVariable @code{advantage-default} n
These variables set the bounds and default values for players' initial
advantages.  Default to @code{1}, @code{9999}, and @code{1},
respectively.
@end deffn

@i{Xconq} is not guaranteed to be able to be able to set up a game with
any combination of player advantages; the limits depend on the
capabilities and characteristics of the synthesis methods that use the
requested advantages in their calculations.

@node Rules of Side Configuration

@subsection Rules of Side Configuration

The properties of a side can come from a number of different sources
(here listed in order of precedence):

@itemize @bullet

@item
Interface-specific sources (X resources, Mac preferences).

@c @item
@c Game-specific form in player's configuration file.

@c @item
@c Generic form in player's configuration file.

@item
The @code{side} form for the side.

@item
The @code{side-defaults} form for the game.

@item
General program defaults.

@end itemize

Note that interface-specific and general config files can never alter
certain properties of a side, and can only alter others if they are not
locked.

@node Unit Forms

@section Unit Forms

The basic @code{unit} form creates or modifies a unit.

@deffn Form @code{unit} id [ type ] properties@dots{}
This form defines a unit.  If a numeric @var{id} is supplied and matches
the id of an existing unit, then that unit will be modified by
@var{properties}, and the optional @var{type} will be interpreted as a
new type for the unit.  Otherwise a new unit will be created, with
either @var{id} as its id or a arbitrarily-selected one if @var{id} is
already in use.  If the unit's id is newly-generated and no type has
been specified, then type #0 (first-defined type) will be the type of
the unit.  An id of @code{0} can never match an existing unit id, so
effect will be as if it had been omitted.
@end deffn

@deffn Form @var{unit-type-name} x y [ side-id ] properties@dots{}
This is an abbreviated form, in which the x,y position is required, and
an optional side id may be included.  The side id will come from
@code{unit-defaults} if not specified.  The @var{unit-type-name} may be
any valid unit type name or defined name.  This form always results in a
new unit.
@end deffn

Since there may be many units whose properties are similar, there is a
``default unit'' whose properties fill in missing properties in
individual unit declarations.

@deffn Form @code{unit-defaults} [ modifier ] properties@dots{}
This form sets the default values for all subsequent units read in, in
this and every other module not yet loaded.  The set of defaults is
additive, so for instance you can repeatedly change the default side of
units.  If the symbol @code{reset} has been supplied for the optional
@var{modifier}, then all the defaults will be changed to the basic
default values, as described in this manual.
@end deffn

@deffn Symbol @code{reset}
This is the symbol used to reset unit defaults; see above.
@end deffn

@deffn GlobalVariable @code{create-units-from-specs} t/f
When true, unit forms actually cause units to be created.  When false,
the unit forms are saved away and can be used later by a unit form to
supply values for properties.  Defaults to @code{true}.
@end deffn

@menu
* Unit Properties::
* Unit Action State::
* Unit Plan::
* Goal Types::
* Task Types::
@end menu

@node Unit Properties

@subsection Unit Properties

This section lists properties of individual units.  In general, they
default to the most common or reasonable values, so need not always be
specified, even in a saved game.

@deffn UnitProperty @code{@@} x y [ z ]
This property is the position of the unit.  Defaults to @code{-1,-1,0},
which causes the unit to be placed randomly.  The optional altitude
@var{z} can also be set separately with the property @code{z} below.  If
@i{z} is even and the unit is in the open, then the unit's altitude is
@i{z/2}; if @i{z} is odd, then @i{(z-1)/2} is the type of connection
terrain that the unit is on.
@end deffn

@deffn UnitProperty @code{z} z
This property is identical to the optional z part of the @code{@@}
property.
@end deffn

@deffn UnitProperty @code{s} side
This property is the side of the unit.  It can be either a side name,
noun, or adjective (string) or an id (number).  A value of @code{0} or
@code{"independent"} means that the unit is independent.
@end deffn

@deffn UnitProperty @code{os} side
This property is the original side of the unit.  It can be either a side
name, noun, or adjective (string), or an id (number).  A value of
@code{0} or @code{"independent"} means that the unit is/was originally
independent.  Defaults to the unit's actual side when first read in or
created.
@end deffn

@deffn UnitProperty @code{#} n
This property is the unique numeric id of the unit.  Defaults to a
game-selected value.
@end deffn

@deffn UnitProperty @code{n} str
This property is the name of the unit.
@end deffn

@deffn UnitProperty @code{nb} n
This property is the number of the unit, which starts at @code{1} and
goes up.  Defaults to @code{0}, which means that the unit is unnumbered.
@end deffn

@deffn UnitProperty @code{cp} n
This property is the current completeness of the unit.  If negative,
indicates that the unit will appear at a time and place specified by the
@code{appear} x-property.  Defaults to the @code{cp} for the type.
@end deffn

@deffn UnitProperty @code{hp} n
This property is the current hit points of the unit.  Will be restricted
to the range [0, hp-max].  An hp of 0 means that the unit is dead and
will not appear in the game.  Defaults to @code{hp-max} for the unit's
type.
@end deffn

@deffn UnitProperty @code{cxp} cxp
This property is the combat experience of the unit.  Experience starts
at 0 for new units and goes up with each engagement in combat.
@end deffn

@deffn UnitProperty @code{mo} n
This property is the morale of the unit.  Morale ranges from 0 to a
maximum set by @code{morale-max}.
@end deffn

@deffn UnitProperty @code{trk} n
This property is a bit vector indicating the sides that are currently
tracking the unit's movements.  The unit's own side is not included.
@end deffn

@deffn UnitProperty @code{m} mtype-value-list
This property is the amounts of supplies being carried by the unit.
Defaults to @code{0} for each material type.
@end deffn

@deffn UnitProperty @code{tp} utype-value-list
This property is the level of tooling to build each type of unit.
Defaults to @code{0} for each unit type.
@end deffn

@deffn UnitProperty @code{in} x
This property is the id, name, or symbol of the unit's transport.
Defaults to @code{0}, meaning that unit is not in any transport.
@end deffn

@deffn UnitProperty @code{opinions} side-value-list@dots{}
This property is the unit's true feelings towards each side, including
its own side.  Defaults to @code{0} for each side.
@end deffn

@deffn UnitProperty @code{appear} n
This property is the turn on which a unit will appear.  The unit's cp
must also be negative, and its position must be negatives of its
position.  Defaults to @code{-1}.
@end deffn

@deffn UnitProperty @code{disappear} n
This property is the turn on which a unit will disappear from the game.
Occupants will be ejected if possible; otherwise they will disappear
also.  Defaults to @code{-1}.
@end deffn

@deffn UnitProperty @code{autoplan} n
This property is true when the unit should choose its own research
topics.
@end deffn

@deffn UnitProperty @code{autobuild} n
This property is true when the unit should choose its own construction
task.
@end deffn

@deffn UnitProperty @code{autoresearch} n
This property is true when the unit should choose its own research
topics.
@end deffn

@deffn UnitProperty @code{creation-id} n
The ID of the unit created by this unit. Reset once the building stage 
starts.
@end deffn

@deffn UnitProperty @code{curadv} n
This property is the current advance that the unit is researching.
@end deffn

@deffn UnitProperty @code{popul} n
This property is the unit's population (currently unused).
@end deffn

@deffn UnitProperty @code{prod} mtype-value-list
This property is the unit's production for each material type.
@end deffn

@deffn UnitProperty @code{sym} symbol
This property is a symbol that is unique to this unit.  This symbol may
appear instead of a unit id, for instance as the value of the property
@code{in}.  Defaults to @code{()}.
@end deffn

@deffn UnitProperty @code{sides} list
This property is a list of side names that the unit may be given to
during setup.  (See side property @code{units}.)  Defaults to @code{()}.
@end deffn

@node Unit Action State

@subsection Unit Action State

@deffn UnitProperty @code{acp} n
This property is the number of action points left to the unit for this
turn.
@end deffn

@deffn UnitProperty @code{acp0} n
This property is the initial number of action points for this turn,
computed at the beginning of the turn.
@end deffn

@deffn UnitProperty @code{am} n
This property is the actual number of moves (cell entries) executed so
far in the current turn.
@end deffn

@deffn UnitProperty @code{a} action
This property is the next action that the unit will perform.
@end deffn

@node Unit Plan

@subsection Unit Plan

@deffn UnitProperty @code{plan} type [ creation-turn ] properties@dots{}
This property describes the unit's current plan.
@end deffn

@deffn PlanType @code{none}
A unit with this type of plan does nothing.  It is used when a side has
no player.
@end deffn

@deffn PlanType @code{passive}
This plan type is for units on a side that is being run directly by the
side.  This is the normal plan type for units when a human player is
playing.
@end deffn

@deffn PlanType @code{defensive}
This plan type is for units that defend areas or other units.
@end deffn

@deffn PlanType @code{offensive}
This plan type is for units that are to be aggressive.
@end deffn

@deffn PlanType @code{exploratory}
This plan type is for units that explore the world.
@end deffn

@deffn PlanType @code{colonizing}
This plan type is for units to build more units (like cities) that can
themselves build more units.
@end deffn

@deffn PlanType @code{improving}
This plan type is for units to improve themselves, such as by adding
special types of occupants.
@end deffn

@deffn PlanType @code{random}
A unit with this plan type will act randomly.
@end deffn

@deffn PlanProperty @code{goal} goal
This property is the main goal of a unit's plan.  Defaults to @code{()}.
@end deffn

@deffn PlanProperty @code{formation} goal
This property is the formation goal of a unit's plan.  If defined, it is
a position goal that the unit should try to achieve when it is not
trying to achieve the main goal.  Defaults to @code{()}.
@end deffn

@deffn PlanProperty @code{tasks} tasks@dots{}
This property is the complete task agenda for the unit's plan.  It is a
list of tasks.  Defaults to @code{()}.
@end deffn

@deffn PlanProperty @code{asleep} t/f
This property is true if the unit is asleep.  Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{reserve} t/f
This property is true if the unit is in reserve.  Defaults to
@code{false}.
@end deffn

@deffn PlanProperty @code{delayed} t/f
This property is true if the unit's activity has been delayed until all
others have acted.  Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{wait} t/f
This property is true if the unit is waiting for orders.  Defaults to
@code{false}.
@end deffn

@deffn PlanProperty @code{ai-control} t/f
This property is true if the unit can be controlled by any AI associated
with the side.  Defaults to @code{true}.
@end deffn

@deffn PlanProperty @code{supply-alarm} t/f
This property is true if the unit should react when supply is low.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{supply-is-low} t/f
This property is true if the unit considers its supply to be low.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{wait-transport} t/f
This property is true if the unit is waiting for transport.  Defaults to
@code{false}.
@end deffn

@deffn PlanProperty @code{initial-turn} turn
This property is the turn upon which a plan should go into effect.
@end deffn

@deffn PlanProperty @code{final-turn} turn
This property is the turn upon which a plan should be removed.  If the
value is @code{0}, then the plan is not scheduled to be removed.
@end deffn

@node Goal Types

@subsection Goal Types

The possible types of goals are these:

@deffn GoalType @code{no-goal}
@end deffn

@deffn GoalType @code{won-game}
@end deffn

@deffn GoalType @code{lost-game}
@end deffn

@deffn GoalType @code{world-is-known}
@end deffn

@deffn GoalType @code{vicinity-is-known}
@end deffn

@deffn GoalType @code{positions-known}
@end deffn

@deffn GoalType @code{cell-is-occupied}
@end deffn

@deffn GoalType @code{vicinity-is-held}
@end deffn

@deffn GoalType @code{has-unit-type}
@end deffn

@deffn GoalType @code{has-unit-type-near}
@end deffn

@deffn GoalType @code{has-material-type}
@end deffn

@deffn GoalType @code{keep-formation}
@end deffn

@deffn GoalType @code{find-spot-to-build}
@end deffn

@node Task Types

@subsection Task Types

This section lists all the types of tasks that a unit may perform.
Every task includes the two parameters @var{ex} and @var{re}; the first
is a record of how many times the task has been executed, and the second
records how many times the task has failed.  (@i{Xconq} will retry a
failed task several times before abandoning it.)

@deffn TaskType @code{build} ex re u n n2 unit-id
This type of task directs the unit to build @var{n} units of type
@var{u}.  @var{n2} is the number already built in the run and
@var{unit-id} is the (optional) id of a unit already being built.
@end deffn

@deffn TaskType @code{capture} ex re unit-id
@end deffn

@deffn TaskType @code{collect} m x y
This type of task directs the unit to acquire material of type @var{m}
at or around @var{x},@var{y} and to deliver it to the nearest unit that can
accept the material.
@end deffn

@deffn TaskType @code{disband} ex re
This type of task directs the unit to disband itself.
@end deffn

@deffn TaskType @code{hit-position} ex re x y z
This type of task directs the unit to attack or fire on any unfriendly
units at the given location.
@end deffn

@deffn TaskType @code{hit-unit} ex re unit-id
@end deffn

@deffn TaskType @code{move-dir} ex re dir n
This type of task directs the unit to move in direction @var{dir} for a
distance of @var{n} cells.
@end deffn

@deffn TaskType @code{move-to} ex re x y z dist
This type of task directs the unit to move to a distance of no more than
@var{dist} cells from the given location.
@end deffn

@deffn TaskType @code{occupy} ex re unit-id
This type of task directs the unit to attempt to enter the given
@var{unit-id}, moving adjacent to it first if necessary.
@end deffn

@deffn TaskType @code{pickup} ex re unit-id
This type of task directs the unit to move towards the given
@var{unit-id}.
@end deffn

@deffn TaskType @code{repair} ex re unit-id
@end deffn

@deffn TaskType @code{resupply} ex re
This type of task directs the unit to replenish its supplies, whether by
doing more production or by moving to another unit that has supplies
available.
@end deffn

@deffn TaskType @code{sentry} ex re n
This task type directs the unit to stay where it is for the next @var{n}
turns.
@end deffn

@node Agreements

@section Agreements

@deffn Form @code{agreement} [ id ] properties@dots{}
This form defines an agreement among a set of sides.  The name/id is a
unique internal identifier.
@end deffn

@deffn AgreementProperty @code{type-name} str
This property is the name of the general type of agreement, such a
trade.  Defaults to @code{""}.
@end deffn

@deffn AgreementProperty @code{title} str
This property is the player-visible name of the agreement.  Defaults to
@code{""}.
@end deffn

@deffn AgreementProperty @code{terms} forms@dots{}
This property is the list of terms of the agreement.  Defaults to
@code{()}.
@end deffn

@deffn AgreementProperty @code{drafters} side-list
This property is the set of sides writing the agreement.  Only drafting
sides may modify an agreement.
@end deffn

@deffn AgreementProperty @code{proposers} side-list
This property is the set of sides that initially proposed the agreement.
@end deffn

@deffn AgreementProperty @code{signers} side-list
Before the agreement is made, this property is the proposed list of
participants.  After the agreeement is made, this is the actual list of
participants.
@end deffn

@deffn AgreementProperty @code{willing-to-sign} side-list
This property is all the sides that have already agreed to this
agreement, on condition that all the other sides accept it.
@end deffn

@deffn AgreementProperty @code{known-to} side-list
This property is the set of sides that are to know about the agreement
when it is signed.
@end deffn

@deffn AgreementProperty @code{enforcement} form
@end deffn

@deffn AgreementProperty @code{state} state
@end deffn

@node Scorekeeper Forms

@section Scorekeeper Forms

Scorekeepers are the objects that manage scoring, winning, and losing.
A game design need not define any scorekeepers, and none are created by
default.  A scorekeeper may either maintain a numeric score that is used
at the end of the game to decide rankings, or simply declare a side to
have won or lost.  Perhaps it would be better to refer to scorekeepers as 
victory condition watchers.

@deffn Form @code{scorekeeper} name properties@dots{}
This form creates or modifies a scorekeeper with the given @var{name},
with the given @var{properties}.@*
NOTE: Specifying @var{name} is not supported (as of 2005/02/06).
@end deffn

@menu
* Scorekeeper Properties::
* Scorekeeper Bodies::
* Scorekeeper Functions::
* Scorekeeper Examples::
* Scorefile::
@end menu

@node Scorekeeper Properties

@subsection Scorekeeper Properties

@deffn ScorekeeperProperty @code{title} str
This property is a string that identifies the scorekeeper to the
players.  Defaults to @code{""}.
@end deffn

@deffn ScorekeeperProperty @code{when} (type [ exp ])
This property is when the scorekeeper will be checked or updated.
Defaults to @code{after-turn}.
@end deffn

@deffn ScorekeeperWhenType @code{before-turn} exp
This indicates that the scorekeeper will run at the start of each turn
matching @var{exp}, or after every turn if @var{exp} is not given.@*
NOTE: This property is currently ignored (as of 2005/01/23).
@end deffn

@deffn ScorekeeperWhenType @code{after-turn} exp
This indicates that the scorekeeper will run at the end of each turn
for which @var{exp} is true, or after every turn if @var{exp} is not 
given. If @var{exp} is a number rather than a full expression, then 
a test of @var{exp} >= current turn number will be made. See the examples 
subsection for a full expression.
@end deffn

@deffn ScorekeeperWhenType @code{after-event} exp
This indicates that the scorekeeper will run after every event
matching @var{exp}, or after every event if @var{exp} is not given.@*
NOTE: Specifying @var{exp} is not supported (as of 2005/01/23).
@end deffn

@deffn ScorekeeperWhenType @code{after-action} exp
This indicates that the scorekeeper will run at the end of each action
matching @var{exp}, or after every action if @var{exp} is not given.@*
NOTE: Specifying @var{exp} is not supported (as of 2005/01/23).
@end deffn

@deffn ScorekeeperProperty @code{applies-to} side-and-sideclass-list
This property is the set of sides or side classes to which the
scorekeeper applies.  Scorekeepers apply only to sides that are in the
game.  Defaults to @code{nil}, which means all sides.
@end deffn

@deffn ScorekeeperProperty @code{known-to} side-and-sideclass-list
This property is the list of sides that know about this scorekeeper, and
can see the value of the score for each side that it applies to.
Defaults to @code{nil}, which means all sides.@*
NOTE: This property is currently ignored (as of 2005/01/23).
@end deffn

@deffn ScorekeeperProperty @code{trigger} form
This property is an expression that is true when it is time to start
checking the scorekeeper's main test.  Once a scorekeeper is triggered,
it remains active.  Defaults to @code{false}.
@end deffn

@deffn ScorekeeperProperty @code{triggered} t/f
This property is true if the scorekeeper is currently triggered.
Defaults to @code{true}.
@end deffn

@deffn ScorekeeperProperty @code{do} forms@dots{}
This property is a list of forms to execute in order each time the
scorekeeper runs.  Defaults to @code{()}.
@end deffn

@deffn ScorekeeperProperty @code{keep-score} t/f
If this property is @code{false}, then no numeric score is kept.
Defaults to @code{true}.
@end deffn

@deffn ScorekeeperProperty @code{initial-score} value
This property is the value of the score upon game startup.  
@end deffn

@node Scorekeeper Bodies

@subsection Scorekeeper Bodies

The forms in the body (the @code{do} property) of the scorekeeper may be
any of the forms listed here.

@deffn ScorekeeperForm @code{last-side-wins}
If supplied as the only symbol in the body, then the scorekeeper
implements the usual ``last side left in the game wins'' behavior.
@end deffn

@deffn ScorekeeperForm @code{last-alliance-wins}
If supplied as the only symbol in the body, then the scorekeeper
implements the ``last alliance left in the game wins'' behavior.  For
the purposes of this scorekeeper, an alliance means that the sides in
the alliance all trust each other.
@end deffn

@deffn ScorekeeperForm @code{if} test action [ else-action ]
If the @var{test} evaluates to a non-@code{nil} result, then the
@var{action} will be done. Else, the @var{else-action} will be done, if 
there is one.
@end deffn

@deffn ScorekeeperForm @code{cond} (test actions@dots{}) @dots{}
This is like Lisp's cond.
@end deffn

@deffn ScorekeeperForm @code{win}
This scorekeeper action causes the side to win immediately.
@end deffn

@deffn ScorekeeperForm @code{lose}
This scorekeeper action causes the side to lose immediately.
@end deffn

@deffn ScorekeeperForm @code{end}
This scorekeeper action ends the game immediately, with a draw for all
remaining sides.
@end deffn

@deffn ScorekeeperForm @code{add-score} exp
This adds the result of evaluating @var{exp} to the score of the given
side.  The value may be a negative number. This form cannot be used 
with a non-numeric scorekeeper.
@end deffn

@deffn ScorekeeperForm @code{set-score} exp 
This sets the result of evaluating @var{exp} as the score of the given 
side.  The value may be a negative number.  This form cannot be used 
with a non-numeric scorekeeper.
@end deffn

@node Scorekeeper Functions

@subsection Scorekeeper Functions

Scorekeepers can use all of the general GDL functions such as 
@code{add}, @code{remove-list}, @code{>=}, etc@dots{}.  They can also 
use special functions, which are mentioned below.  Scorekeeper functions 
can be used in any place where a scorekeeper test expression is allowed. 
This means that they can be used in @code{when} conditions, in @code{if} 
test clauses, or the form of @code{set-score}, for example.

@deffn ScorekeeperFunction @code{turn}
This GDL keyword gives the current turn number.
@end deffn

@deffn ScorekeeperFunction @code{score}
This GDL keyword returns the current score in the current scorekeeper for 
the current side.  A warning will be produced if you attempt to use this 
keyword with a non-numeric scorekeeper.
@end deffn

@deffn ScorekeeperFunction @code{sum-uprop} types property
The result is the sum of the property values for all units of the given
type(s).  The property must be an integer value, such as @code{point-value}
or @code{hp-max}.  The @code{point-value} property is treated specially 
in that an unit's actual point assignment is used if it exists;  if the 
point assignment does not exist, then the summation behavior is the 
default, namely the value for the unit type is used.
@end deffn

@node Scorekeeper Examples

@subsection Scorekeeper Examples

One of the most simple and ubiquitous scorekeepers is:
@smallexample
(scorekeeper (do last-side-wins))
@end smallexample
This specifies that the last side standing will win. It should be noted 
that if the independent side is not being controlled by an AI, then it is 
not considered in this case. If the independent side is being controlled 
by an AI, then it is considered.

If you do not wish a side (such as an AI-controlled independent side) to be 
considered for a given scorekeeper, then you can use the @code{applies-to} 
property to restruct which sides the scorekeeper applies to.
@smallexample
(scorekeeper
  (applies-to (not "independent"))
  (do last-side-wins)
)
@end smallexample
The above says to apply the scorekeeper to every side except those belonging 
to the @code{"independent"} side class. By default, only the independent 
side belongs to that side class.

Alternatively, one can use side ID numbers.
@smallexample
(scorekeeper
  (applies-to (not 0))
  (do last-side-wins)
)
@end smallexample
This again excludes the independent side, but, this time, by its exact ID 
number rather than its side class (to which other sides could belong).

We can also talk in terms of inclusion rather than exclusion.
@smallexample
(scorekeeper
  (applies-to ("chaotic" 0))
  (do last-side-wins)
)
@end smallexample
This causes the scorekeeper to be applied to all sides belonging to the 
@code{"chaotic"} side class as well as the independent side.

And, we can include a side class, but exclude specific members of it.
@smallexample
(scorekeeper
  (applies-to (and "chaotic" (not (2 5 7))))
  (do last-side-wins)
)
@end smallexample
Note that the @code{and} is important. All boolean operators must be in 
the higher levels of the expression. Once a list of side classes and/or 
side ID numbers is encountered, then boolean evaluation is not performed 
at the level of the list or below it. The following example is INCORRECT:
@smallexample
(scorekeeper
  (applies-to ("chaotic" (not (2 5 7))))
  (do last-side-wins)
)
@end smallexample
As stated previously, the above example is INCORRECT. It is incorrect 
because the @code{not} appears inside a list of side classes and side ID 
numbers. Do not attempt to use this example.

If this seems confusing, you may wish to consider a list of side classes 
and side ID numbers as being shorthand for @code{or} boolean expressions.
Thus:
@smallexample
(scorekeeper
  (applies-to (1 2 3))
  (do last-side-wins)
)
@end smallexample
is equivalent to:
@smallexample
(scorekeeper
  (applies-to (or 1 (or 2 3)))
  (do last-side-wins)
)
@end smallexample

Now that we have pretty much beaten the @code{applies-to} horse to death, 
let us move on to @code{when} conditions. By default, @code{when} is 
assigned @code{nil}, and this is equivalent to @code{after-turn}. So:
@smallexample
(scorekeeper (do last-side-wins))
@end smallexample
is equivalent to:
@smallexample
(scorekeeper
  (when (after-turn))
  (do last-side-wins)
)
@end smallexample
is equivalent to:
@smallexample
(scorekeeper
  (when (after-turn nil))
  (do last-side-wins)
)
@end smallexample

With the turn-granularity scorekeepers, one can use a shorthand notation 
to specify that they should only run on or after a certain turn number.
@smallexample
(scorekeeper
  (when (after-turn 5))
  (do last-side-wins)
)
@end smallexample
In the above example, the scorekeeper will only be checked at the end of 
turn 5 and at the ends of all turns thereafter.

There is more verbose way of writing this, and this involves a full 
expression:
@smallexample
(scorekeeper
  (when (after-turn (>= turn 5)))
  (do last-side-wins)
)
@end smallexample
The @code{(>= turn 5)} is a test expression. @code{turn} is a keyword 
that gives back the current turn number.

Note that you can put together test expressions using the other available 
operators.
@smallexample
(scorekeeper
  (when (after-turn (<= turn 30)))
  (do last-side-wins)
)
@end smallexample
The above example only runs the scorekeeper at the end of the turn for the 
first 30 turns, and then the scorekeeper ceases to be relevant.

@smallexample
(scorekeeper 
  (title "Every Other Turn")
  (when (after-turn (/= (/ turn 2) (/ (+ turn 1) 2))))
  (applies-to (not "independent"))
  (do last-side-wins)
)
@end smallexample
Since we do not have a modulo arithmetic operator as of this writing 
(2005/02/06), if we want to get a scorekeeper to run at some interval, we 
must use a trick like the above. All above test does is check to see if 
our current turn number divided by some interval has the same quotient as 
the next turn number divided by the same interval. If yes, then the 
scorekeeper should not run. If no, then the scorekeeper should run.
Simply replacing @code{2} with @code{3} in the above when condition, you 
can make your scorekeeper run every third turn, and so and so forth.

Scorekeeper bodies can be simple, as already seen, or they can be quite 
sophisticated. Side scores can be manipulated and victory or loss can be 
forced based on some condition.

@smallexample
(scorekeeper
  (when (after-turn 20)) 
  (do (if (>= (sum-uprop victory-point point-value) 15) win))
)
@end smallexample
In the above example, the scorekeeper checks to see if the sum of the 
@code{point-value} property of @code{victory-point} units is greater than 
or equal to 15.  If so, then it declares the current side the winner 
(and, by extension, other sides as losers).

Suppose we wanted to modify the @i{Default} game.  We could state that 
any side having more than a certain number of points worth of nukes and 
capital ships wins.
@smallexample
(scorekeeper
  (do (if (>= (sum-uprop (cv bb nuke) point-value) 50) win))
)
@end smallexample

We could also do something rather bizarre such as:
@smallexample
(scorekeeper
  (do (if (>= (sum-uprop u* cp) 15000) end))
)
@end smallexample

The above example ends the game in a draw when any one side builds too much.

Scorekeepers can set or add to the score.

@smallexample
(scorekeeper
  (do (set-score (* turn 10)))
)
@end smallexample

The above scorekeeper sets the current side's score to be the turn number 
times @code{10}. Equivalently, one can write:
@smallexample
(scorekeeper
  (do (add-score 10))
)
@end smallexample

In this example, the scorekeeper adds 10 to the current side's score 
every turn.

Scorekeeper bodies can be even more complex.

@smallexample
(scorekeeper
  (do (
    (add-score 10)
    (if (> (* score turn) 1000) end)
    (if (= (sum-uprop capital-city point-value) 0) lose)
  ))
)
@end smallexample

So, putting everything together thus far, we might get something like:
@smallexample
; Last non-indep side standing wins.
(scorekeeper 1
  (title "Attrition Victory")
  (keep-score false)
  (applies-to (not "independent"))
  (do last-side-wins)
)
; First side to acquire 30 victory points wins.
(scorekeeper 2
  (title "Greedy Victory")
  (applies-to (not "independent"))
  (do (
    (set-score (sum-prop victory-point point-value))
    (if (>= score 30) win)
  ))
)
; First side to produce an overwhelming arsenal wins.
(scorekeeper 3
  (title "Inevitable Victory")
  (applies-to (not "independent"))
  (when (after-turn 50))
  (do (
    (set-score (/ (sum-uprop godlike-u* cp) 20))
    (if (>= score 40) win)
    (if (>= (sum-prop (append horde-u* nuke) cp) 30000) win)
  ))
)
; Any side that loses nearly all of its commanding units loses.
(scorekeeper 4
  (title "Loss by Collapsed Command")
  (keep-score false)
  (do (if (< (sum-uprop leader-u* point-value) 50) lose))
)
@end smallexample

@node Scorefile

@subsection Scorefile

@deffn GlobalVariable @code{scorefile-name} str
This variable supplies the name of the file to be used for recording
scores of people playing the game.  The default value is @code{""},
which disables the recording of scores.
@end deffn

@node History Forms

@section History Forms

All the important events in a game are logged into a history.

@deffn Form @code{evt} date type sides data
This form creates a single historical event.  The @var{date} is the turn
of the event's occurrence, while the @var{sides} is a bit mask of sides
that know about the event, or @code{all} if all sides know about it.
@end deffn

@deffn Symbol @code{all}
This is a shorthand for the bitmask of all sides in the game.
@end deffn

@deffn Form @code{exu} id type x y side props
This form defines an ``ex-unit'', which is a record of a unit that
existed previously.  It is similar to a unit, but has only a few
properties; type, id, position, side, name, and number.  Property names
and semantics are nearly identical to their counterparts for units.
@end deffn

@deffn EventType @code{log-started}
This event records when the recording of events began.  Multiple
instances of this may occur, for instance if logging were to be turned
off and then on again.
@end deffn

@deffn EventType @code{log-ended}
@end deffn

@deffn EventType @code{game-started}
This event records the actual start of the game.  There should only be
one in a game's history.
@end deffn

@deffn EventType @code{game-saved}
This event records that the game was saved.
@end deffn

@deffn EventType @code{game-restarted}
This event records that the game was restored and restarted from a saved
game.
@end deffn

@deffn EventType @code{game-ended}
@end deffn

@deffn EventType @code{side-joined} side
This event records when a side joined the game.
@end deffn

@deffn EventType @code{side-lost} side scorekeeper
This event records when a side lost.
@end deffn

@deffn EventType @code{side-won} side scorekeeper
This event records when a side won.
@end deffn

@deffn EventType @code{side-withdrew} side
This event records when a side withdrew from the game.
@end deffn

@deffn EventType @code{unit-created} side unit
This event records the creation of a unit.
@end deffn

@deffn EventType @code{unit-completed} side unit
This event records the completion of a unit.
@end deffn

@deffn EventType @code{unit-acquired}
This event records the acquisition of a unit, for instance as a gift
from another side.
@end deffn

@deffn EventType @code{unit-captured}
This event records the capture of a unit, as an outcome of combat or
from a direct attempt to capture.
@end deffn

@deffn EventType @code{unit-moved} unit x1 y1 x2 y2
This event records the movement of a unit.
@end deffn

@deffn EventType @code{unit-name-changed} unit1 unit2
This event records that a unit's name was changed.  @var{unit1} will be
an ex-unit representing the unit under its previous name.
@end deffn

@deffn EventType @code{unit-type-changed} unit1 unit2
This event records that a unit's type was changed.  @var{unit1} will be
an ex-unit representing the unit with its previous type.
@end deffn

@deffn EventType @code{unit-assaulted} unit1 unit2 x y
@end deffn

@deffn EventType @code{unit-damaged} unit hp1 hp2
This event records that a unit's hp was reduced from @var{hp1} to
@var{hp2}.
@end deffn

@deffn EventType @code{unit-killed} unit
@end deffn

@deffn EventType @code{unit-died-in-accident} unit
@end deffn

@deffn EventType @code{unit-died-from-temperature} unit
@end deffn

@deffn EventType @code{unit-vanished} unit
@end deffn

@deffn EventType @code{unit-wrecked} unit
@end deffn

@deffn EventType @code{unit-wrecked-in-accident} unit
@end deffn

@deffn EventType @code{unit-revolted} unit
@end deffn

@deffn EventType @code{unit-surrendered} unit
@end deffn

@deffn EventType @code{unit-garrisoned} unit
@end deffn

@deffn EventType @code{unit-disbanded} unit
@end deffn

@deffn EventType @code{unit-starved} unit
@end deffn

@deffn EventType @code{unit-left-world} unit
@end deffn

@deffn EventType @code{unit-merged} unit
@end deffn

@deffn EventType @code{unit-gone} unit
@end deffn

The following event types are the results of actions.

@deffn EventType @code{action-ok}
@end deffn

@deffn EventType @code{action-error}
@end deffn

@deffn EventType @code{cannot-do}
@end deffn

@deffn EventType @code{insufficient-acp}
@end deffn

@deffn EventType @code{insufficient-material}
@end deffn

@deffn EventType @code{too-far}
@end deffn

@deffn EventType @code{too-near}
@end deffn

@deffn EventType @code{action-done}
@end deffn

@deffn EventType @code{insufficient-mp}
@end deffn

@deffn EventType @code{blocking-zoc}
Unit was unable to move because of another unit's zone of control.
@end deffn

@deffn EventType @code{cannot-leave-world}
@end deffn

@deffn EventType @code{destination-full}
@end deffn

@deffn EventType @code{overrun-succeeded}
@end deffn

@deffn EventType @code{overrun-failed}
@end deffn

@deffn EventType @code{capture-succeeded}
@end deffn

@deffn EventType @code{capture-failed}
@end deffn

@deffn EventType @code{fire-into-outside-world}
@end deffn

@deffn EventType @code{build-completed}
@end deffn

@node Types in General

@section Types in General

Types are the foundation of @i{Xconq} game designs.  Nearly all the
rules and game parameters are associated with the unit, material,
terrain, and advance types.  There is no sort of type hierarchy;
instead, most forms allow sets of types to be used in the place of
single types.

Each type has an index associated with it, starting from 0.  This index
never appears directly, and cannot be set.  This does mean that types
have an order, so the order in which types are defined is sometimes
significant.  These cases will be noted.  The order is always the order
in which the types appear in the file.

@menu
* Type Names::
* Type Images::
* Documentation::
@end menu

@node Type Names

@subsection Type Names

The names of types need not be distinct from each other, but you run the
risk of player confusion if they share names.

@deffn TypeProperty @code{name} string
This property is the specific name of the type.  This name will be
displayed to players; the exact format is up to the interface, but will
typically depend on the name's length and the space available in the
display.  If no type names have been defined, the internal type name
(see below) will be used.  Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{long-name} string
This property is a fully spelled-out name for the type.  Defaults to
@code{""}.  (At present, this property is only defined for unit types.)
@end deffn

@deffn TypeProperty @code{short-name} string
This property is an abbreviated name of for the type.  Defaults to
@code{""}.  (At present, this property is only defined for unit types.)
@end deffn

@deffn TypeProperty @code{generic-name} string
This property is like @code{name}, but identifies the type less
specifically, and several types may have the same generic name.  If no
generic names are defined, then the regular type names will be used.
This is useful when making abbreviated lists, so that related types get
counted together.  Defaults to @code{""}.  (At present, this property is
only defined for unit types.)
@end deffn

As an example of the distinction between type names and generic type
name, the names of a automobile type might be @code{"1965 Mustang"},
@code{"Mustang"}, and @code{"M"}, while the generic name is
@code{"auto"}.  Then the interface could choose to display a parking lot
as containing either @code{"4 auto"} or @code{"2 Mustang 1 Edsel 1
Jeep"}.

Note that names specified as properties are strings only, and are not
defined as evaluable symbols.

@node Type Images

@subsection Type Images

The interpretation of these properties is entirely up to each interface;
see the appropriate interface documentation for details.

@deffn TypeProperty @code{image-name} str
This property is the name of the type's image.  If undefined or unusable
for some reason, the interface will display the type in some default
manner, such as a solid-color square or a string.

For example, in X11, the name might be the name of a file in the usual
bitmap format, as produced by the @var{bitmap} program.  The actual file
name is produced by appending @code{".b"}.  (The situation in X is
actually more complicated than this.)  See the interface documentation
for details on how the interface uses the image.
@end deffn

@deffn TypeProperty @code{char} str
This property supplies a single character for this type (all characters
after the first one in @var{str} are ignored).  Defaults to @code{""}.
(This property is not defined for advance types.)
@end deffn

@deffn UnitTypeProperty @code{generic-char} str
This property supplies a single generic character for this type (all
characters after the first one in @var{str} are ignored).  If defined,
displays will use the generic character in preference to the @code{char}
for the unit type, in contexts where the exact type is not important
(such as in lists of occupant types).  Defaults to @code{""}.  (This
property is only defined for unit types.)
@end deffn

@node Documentation

@subsection Documentation

@deffn TypeProperty @code{help} string
This property is a brief (preferably one-line) description of the type.
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{notes} strings@dots{}
This property is detailed documentation about the type.  The formatting
of the strings is up to the interface, but in general each string is a
separate line, the string @code{""} indicates a line break, and two
@code{""} in a row indicates a paragraph break.  Defaults to @code{()}.
@end deffn

@node Unit Types

@section Unit Types

@deffn Form @code{unit-type} symbol properties@dots{}
This form defines a new type of unit.  The @var{symbol} is required and
must be previously undefined.  The bindings in @var{properties} are then
added to the type one by one.  If no other name properties are defined,
the @var{symbol} may be displayed to players (see above).  You can
define no more than 126 types of units.
@end deffn

The @var{symbol} here becomes the unit type's ``internal type name''
which is guaranteed unique.  To make synonyms for the internal type
name, use @code{define}.

@deffn GlobalVariable @code{u*}
This variable evaluates to a list of all unit types, listed in the order
that they were defined.  This list always reflects the list of types at
the moment it is evaluated.
@end deffn

@deffn GlobalVariable @code{non-unit}
This variable evaluates to a value that is NOT a unit type.  This is
needed in several places to enable/disable features.  Use of this in any
other way is an error, and may or may not be detected before it causes a
crash.  (Although described as a variable, its value cannot be changed.)
@end deffn

@deffn UnitTypeProperty @code{name-internal} str
Internally used type name.
@end deffn

@menu
* Unit Naming::
* Availability::
* Class-Restricted Unit Types::
* Self-Unit Capable Units::
* Limits on Unit Quantities::
* Hit Points::
* Experience::
* Tech Levels vs Units::
* Opinions::
* Point Value::
* Advanced Units::
@end menu

@node Unit Naming

@subsection Unit Naming

@deffn UnitTypeProperty @code{namer} namer-id
This property is the namer that will be used to generate names for
units, if the unit's side does not have a namer, or the unit is
independent and not in any country.  Defaults to @code{0}, which leaves
the unit unnamed.
@end deffn

@deffn UnitTypeProperty @code{assign-number} t/f
This property is true if the unit should have a serial number assigned
to it by the side it belongs to.  Serial numbers are maintained for each
type on each side separately, start at 1 for the first unit of the type,
and increase by one each time.  Defaults to @code{true}.
@end deffn

@deffn UnitTypeProperty @code{description-format} list@dots{}
This property defines the different ways in which an instance or
instances of this type may be described textually.  This information may
be used in narrative descriptions and in informational displays.  Each
element of @var{list} is either a string to add literally to the unit's
description, or a symbol indicating the substitution of unit or unit
type properties.  The symbols are @code{name}, @code{position},
@code{side}, @code{side-adjective}, @code{side-name}, @code{type}.  If
@code{()}, then the instance will be described in a default fashion that
is equivalent to a format of @code{(side " " type " " name)}.  Defaults
to @code{()}.
@end deffn

@node Availability

@subsection Availability

It may be that a set of types is larger than strictly necessary for
a particular game.  You can make any type unavailable, which means
that irrespective of any other controls, that type cannot come into
play during a game.  You can also make it available only for particular
turns.

@deffn UnitTypeProperty @code{available} n
If the value of this property is greater than 0, then this type is
available in the game on or after turn @var{n}.  If the value is less
than 0, then the type is available, but only until turn @var{-n}.  If
the value is 0, then the type is never available.  Defaults to @code{1},
which means that the type is always available.
@end deffn

If a type becomes unavailable and there are units of that type in play,
then they will vanish immediately.

@node Class-Restricted Unit Types

@subsection Class-Restricted Unit Types

Sometimes the designer will want to make different sides have different
types of units.  Although this can be done by setting up scenarios
appropriately, that won't close all the loopholes that might allow a
side to get units that should only ever belong to another side.

The first step is to define a class for each side.  For instance, a side
named @code{"Rome"} might have a class @code{"Roman"}, while the sides
named @code{"Aedui"} and @code{"Parisii"} could both be in the class
@code{"barbarian"}.

@deffn UnitTypeProperty @code{possible-sides} exp
This property restricts the unit type to only be usable by a side
meeting the conditions of @var{exp}.  If @var{exp} is a string, it
restricts the unit type to only be usable by a side whose class includes
a matching string.  This may also be a boolean expression.  Independent
units belong to a side whose class is @code{"independent"}.  The default
of @code{""} allows the unit to belong to any side.
@end deffn

@node Self-Unit Capable Units

@subsection Self-Unit Capable Units

The self-unit can be any type, including one that cannot act; for
instance, a capital city could be the self-unit, thus making its defense
all-important for a player.

@deffn GlobalVariable @code{self-required} t/f
This variable is true if each side is required to have a self-unit at
all times.  However, if no unit of a suitable type is available when the
game begins, then none will be required.  Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{can-be-self} t/f
This property says that the type of unit can represent the side directly.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{self-changeable} t/f
This property is true if the player can choose to change a self-unit of
this type at any time.  Otherwise the self-unit can be changed only if
the current one dies.  Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{self-resurrects} t/f
This property is true if when the self-unit dies, another unit of an
allowable type becomes the self-unit automatically.  Defaults to
@code{false}.
@end deffn

Observe that these parameters can be used to develop various forms of
backup, so that a player can start out as a capital city, resurrect as a
town, change self to one of several towns, then lose when all the towns
are lost.

@deffn UnitTypeProperty @code{direct-control} t/f
This property is true if a unit of this type can be controlled by its
side automatically.  If false, then it must be within range of a unit
that can control it, and is itself under control by the side.  Defaults
to @code{true}.
@end deffn

@deffn TableUU @code{unit-control-chance-at} u1 u2 -> n%
@end deffn

@deffn TableUU @code{unit-control-chance-adjacent} u1 u2 -> n%
@end deffn

@deffn TableUU @code{unit-control-chance} u1 u2 -> n%
@end deffn

@deffn TableUU @code{unit-control-range} u1 u2 -> dist
This table gives the maximum distance from self-unit @var{u1} at which
units of type @var{u2} can be controlled directly.  Units further away
always act on their own.  If this value is < 0, then @var{u1} can never
directly control any other @var{u2} on the side.  Defaults to
@code{infinity}.
@end deffn

@node Limits on Unit Quantities

@subsection Limits on Unit Quantities

The effect of these is to prevent any extra units from being created or
from going over to a side, regardless of the reason.  This happens by
either preventing player actions that would result in exceeding a limit
(such as when building units), or by making the unit vanish instantly
(such as when capturing a unit).

@deffn GlobalVariable @code{units-in-game-max} n
This variable is the maximum number of all types of units, on all sides,
including independents, that may exist at any time, including initially.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

@deffn GlobalVariable @code{units-per-side-max} n
This variable is the maximum number of units (of all types together)
that any side may have, at any time.  Events that would cause the limit
to be exceeded, such as capturing a unit, result in either the unit
vanishing or becoming independent.  Defaults to @code{-1}, which means
that there is no limit.
@end deffn

There is no limit on the number of units that may be independent.

@deffn UnitTypeProperty @code{type-in-game-max} n
This property is the maximum total of the given type, for all sides
together.  Defaults to @code{-1}, which means that there is no limit.
@end deffn

@deffn UnitTypeProperty @code{type-per-side-max} n
This property is the maximum number of units of the given type allowed
to each side.  Defaults to @code{-1}, which means that there is no
limit.
@end deffn

@node Hit Points

@subsection Hit Points

A unit's hit points determine how healthy it is.  If a unit's hp goes
below 1, it is either @dfn{wrecked}, meaning that it changes to a new
type @code{wrecked-type} or else it @dfn{vanishes}, meaning that it is
completely cleared from the world.

@deffn UnitTypeProperty @code{hp-max} n
This property is the maximum number of hit points for (each part of) a
unit.  Completed units start with this many hit points.  Defaults to
@code{1}.
@end deffn

@deffn UnitTypeProperty @code{destruction-result} list
This property contains a weighted list, @var{list}, of possible destruction 
special outcomes, which are considered before deciding what to do with a 
destroyed unit. 
Defaults to @code{nil}.
If @code{nil} then the normal outcome is used.
Possible outcomes: @code{vanish} and @code{table}.
The @code{vanish} outcome means that the unit will simply disappear no 
matter what would normally happen to it.
The @code{table} outcome means determine the normal outcome by using any 
table lookups, etc....
@end deffn

@deffn UnitTypeProperty @code{wrecked-type} unit-type
This property is the type of unit that a unit with 0 hp will become.
For instance, a destroyed ``fort'' might become a ``rubble pile'' unit.
If its value is @code{non-unit}, then the destroyed unit just vanishes.
The @code{wrecked-type} of a type must be a different type.
Defaults to @code{non-unit}.
@end deffn

@deffn TableUU @code{wrecked-type-if-killed} u1 u2 -> u3
If an unit of type @var{u1} is killed by an unit of type @var{u2}, then 
make the wreck of @var{u1} be an unit of type @var{u3}.
Defaults to @code{non-unit}, which means that the value of 
@code{wrecked-type} will be used instead.
Overrides the value of @code{wrecked-type} if set to something other than 
@code{non-unit}.
@end deffn

@deffn TableUM @code{wrecked-type-if-starved} u1 m -> u3
If an unit of type @var{u1} starves to death for lack of a material of 
type @var{m}, then make the wrecked unit type be @var{u3}.
Defaults to @code{non-unit}, which means that the value of 
@code{wrecked-type} will be used instead.
Overrides the value of @code{wrecked-type} if set to something other than 
@code{non-unit}.
@end deffn

@deffn TableUT @code{wrecked-type-if-attrited} u1 t -> u3
If an unit of type @var{u1} dies from attrition due to a hostile terrain 
of type @var{t}, then make the wrecked type be @var{u3}.
Defaults to @code{non-unit}, which means that the value of 
@code{wrecked-type} will be used instead.
Overrides the value of @code{wrecked-type} if set to something other than 
@code{non-unit}.
@end deffn

The transformation to the wrecked type does not change position or name.
The transformed unit has full hp, supplies are conserved as much as
possible (any excess is destroyed), tooling is preserved, and any unit
plan is erased.  It has the same number of parts, or as many as possible
if that is fewer.  It may be that the wrecked type is on terrain that it
cannot survive on; in that case, it will be wrecked again, repeating
until the unit either vanishes or is in a viable position, or this
process has been repeated more times than the number of unit types
(prevents infinite loops).  Any excess occupants will be removed and
either placed in another nearby unit or in the open, or will vanish if
there is no other option.

@node Experience

@subsection Experience

@deffn UnitTypeProperty @code{cxp-max} cxp
This property is the maximum combat experience this type of unit can have.
@end deffn

@node Tech Levels vs Units

@subsection Tech Levels vs Units

Before it can do anything with a type of unit, the side must have the
appropriate tech level for that type, which is just a number ranging
from 0 up to @code{tech-level-max}.  Each type has a distinct tech
level.

Tech levels always increase (since they represent abstract knowledge
rather than physical plant).  Tech can be transferred freely to any
other side via the message @code{tech} [xref to messages].

For each unit type, the following parameters define the minimum tech
levels at which sides can do various things.

@deffn UnitTypeProperty @code{tech-to-see} tl
This property is the minimum tech level that a side must have before it
can see a unit of this type.
@end deffn

@deffn UnitTypeProperty @code{tech-to-own} tl
This property is the minimum tech level that a side must have in order
to have a unit of this type.
@end deffn

@deffn UnitTypeProperty @code{tech-from-ownership} tl
This property is the tech level that may be reached by acquiring a unit
of this type.  Since this is expressed as a minimum, multiple
acquisitions have no additional effect.
@end deffn

@deffn UnitTypeProperty @code{tech-to-use} tl
This property is the minimum tech level that a side must have in order
to give actions to this type of unit.
@end deffn

@deffn UnitTypeProperty @code{tech-to-build} tl
This property is the minimum tech level that a side must have in order
to build this type of unit.
@end deffn

@deffn UnitTypeProperty @code{tech-max} tl
This property is the absolute maximum tech level possible for this type.
@end deffn

@deffn TableUU @code{tech-crossover} u1 u2 -> n%
This table is the minimum tech level for @var{u2} that is guaranteed by
a particular tech level for @var{u1}, expressed as a percentage of the
@code{tech-max} for the types.  For instance, if @code{tech-crossover}
is 80, and the tech level for @var{u1} is 10 out of a max of 20, and the
max for @var{u2} is also 20, then the side has a tech for @var{u2} at
least 8.
@end deffn

It is possible to gain some tech level just by being in the same game
with a side that is more advanced.

@deffn UnitTypeProperty @code{tech-leakage} .01tl
This property is the amount of tech level gain per turn that can happen
to any side's tech level that is less than the max of all sides in the
game.  This only happens if at least one unit on the side has nonzero
coverage of a unit on a more advanced side.
@end deffn

@node Opinions

@subsection Opinions

@deffn UnitTypeProperty @code{opinion-min} n
@end deffn
@deffn UnitTypeProperty @code{opinion-max} n
These properties are the bounds of the strength of a unit's opinion
about the sides, both other sides and its own.
@end deffn

@deffn UnitTypeProperty @code{courage-min} n
@end deffn
@deffn UnitTypeProperty @code{courage-max} n
@end deffn

Morale is similar to opinion; it reflects the unit's opinion about
itself.

@deffn UnitTypeProperty @code{morale-max} n
This property is the maximum morale that the unit may have.
@end deffn

@deffn TableUT @code{morale-terrain-effect} u t -> n
This table is the effect of the terrain at a unit's location on its
morale.
@end deffn

@deffn UnitTypeProperty @code{morale-recovery} .01n
This property is the amount of morale increase for a unit each turn, in
1/100ths of a point of morale.  Defaults to @code{0}.
@end deffn

@node Point Value

@subsection Point Value

Point values provide an abstract way to characterize the overall
importance of a unit type.  Point values figure into some scorekeepers,
and are used by AIs.

@deffn UnitTypeProperty @code{point-value} n
This property is the ``value'' of a unit.  Defaults to @code{1}.
@end deffn

@node Advanced Units

@subsection Advanced Units

Advanced units have an additional set of behaviors and functions; they
are most like the cities in civilization-building games.

@deffn UnitTypeProperty @code{advanced} t/f
This property is true if the type is an advanced type.
@end deffn

@deffn TableUA @code{size-limit-without-advance} u a -> n
This table indicates the maximum size of a unit of type @var{u} if the
advance @var{a} has not been achieved.  Defaults to a large number.
@end deffn

@deffn TableUU @code{size-limit-without-occupant} u1 u2 -> n
This table indicates the maximum size of a unit of type @var{u1} if a
unit of type @var{u2} is not an occupant.  Defaults to a large number.
@end deffn

@deffn TableUM @code{unit-consumption-per-size} u m -> n
@end deffn

@deffn TableUM @code{unit-consumption-to-grow} u m -> n
@end deffn

@c should make a special section to define usage

Advanced units may use cells around them for production.

@deffn TableTM @code{production-from-terrain} t m -> n
This table defines how much production an advanced unit gains by using a
cell for production.  This production is actually done by the unit, and the
results are added directly to the unit's store of material; it is separate
from backdrop production by cells through @code{terrain-production}, which
adds to the cells' own material stores.
@end deffn

@deffn UnitTypeProperty @code{reach} n
This property is the radius out to which an advanced unit type may use
the terrain for production.
@end deffn

@deffn UnitProperty @code{reach} n
This property is the radius out to which an advanced unit may use the
terrain for production.  (This is always the same as the type property
currently.)
@end deffn

@deffn UnitProperty @code{size} n
This property is the size of the advanced unit.
@end deffn

@deffn UnitTypeProperty @code{use-own-cell} t/f
If true, then the advanced unit type automatically uses the cell it is
sitting on.
@end deffn

@deffn TableUA @code{advance-add-maxcells} u a -> n
This is the number of additional cells that the unit can use for
production if its side has the advance.
@end deffn

@deffn TableUA @code{advance-mult-maxcells} u a -> n
This is the percentage multiplier for the additional cells that the unit
can use for production if its side has the advance.  Defaults to
@code{100}.
@end deffn

@deffn TableUU @code{occ-add-maxcells} u1 u2 -> n
This is the number of additional cells that each occupant of type
@var{u2} adds to a unit of type @var{u1}.
@end deffn

@deffn TableUU @code{occ-multiply-maxcells} u1 u2 -> n
This is the percentage by which each occupant of type @var{u2} multiples
the production cells of a unit of type @var{u1}.  Defaults to
@code{100}.
@end deffn

@deffn UnitProperty @code{usedcells} n
This is a cache of the number of cells used by an advanced unit.
@end deffn

@deffn UnitProperty @code{maxcells} n
This is a cache of the maximum number of cells available to an advanced
unit.
@end deffn

@deffn TableUA @code{advance-add-production} u a -> n
This is the amount of additional production available to the unit if its
side has the advance.
@end deffn

@deffn TableUA @code{advance-multiply-production} u a -> n
This is the percentage by which an advance multiplies the production
of the unit.  Defaults to @code{100}.
@end deffn

@deffn TableUU @code{occupant-add-production} u1 u2 -> n
This is the amount of additional production available to the unit
of type @var{u1} due to each occupant of type @var{u2}.
@end deffn

@deffn TableUU @code{occupant-multiply-production} u1 u2 -> n
This is the percentage by which each occupant of type @var{u2}
multiplies the production of a unit of type @var{u1}.  Defaults to
@code{100}.
@end deffn

Materials produced by advanced units may be automatically converted
into other types, in proportions decided by the player.

@deffn TableMM @code{conversion} m1 m2 -> n
Values greater than zero in this table indicate that produced materials
of type @var{m1} can become materials of type @var{m2}.
@end deffn

@deffn TableMM @code{conversion-default} m1 m2 -> n
This table is the default conversion rate of material of type @var{m1}
into a material of type @var{m2}.
@end deffn

@node Terrain Types

@section Terrain Types

Terrain types are associated with the cells, borders, connections, and
coatings in a world.

@deffn Form @code{terrain-type} name properties@dots{}
This form defines a new type of terrain, named by @var{name}.  Details
are similar to those for unit types.
@end deffn

@deffn GlobalVariable @code{t*}
This variable evaluates to a list of all terrain types, listed in the
order that they were defined.
@end deffn

@deffn GlobalVariable @code{non-terrain}
This variable has a value that is guaranteed not to be a terrain type.
@end deffn

@menu
* Terrain Subtypes::
* Terrain Compatibility::
* Other Terrain Properties::
@end menu

@node Terrain Subtypes

@subsection Terrain Subtypes

Terrain can appear in four different roles: as the interior of a cell,
as a border between cells, as a connection between cells, or as a
coating overlaying the normal terrain.  The terrain subtype says which
role a type can play.

@deffn TerrainTypeProperty @code{subtype} subtype
This property is the role that the terrain type can appear in.  Defaults
to @code{cell}.
@end deffn

@deffn GlobalConstant @code{cell}
This constant indicates that terrain can fill a cell.  All units in the
open and with an altitude of 0 are assumed to be surrounded by the cell
terrain.
@end deffn

@deffn GlobalConstant @code{border}
This constant indicates that the terrain can be a border between two
cells.
@end deffn

@deffn GlobalConstant @code{connection}
This constant indicates that the terrain can be a connection between two
cells.
@end deffn

@deffn GlobalConstant @code{coating}
This constant indicates that the terrain can be a coating.  A
@dfn{coating} is a temporary terrain modification.  The classic example
is snow, which effectively changes some kinds of terrain, but not
completely and usually not permanently.  Cells can have varying
heaviness of each type of coating.
@end deffn

@deffn TableTT @code{coating-depth-min} t1 t2 -> n
In order for a coating @var{t1} to ``stick'', this table says much must
be added all at once to terrain @var{t2}.  A coating depth that drops
below this will disappear immediately.
@end deffn

@deffn TableTT @code{coating-depth-max} t1 t2 -> n
This table is the upper limit on coating depth.
@end deffn

Terrain types may have additional subtype attributes that are used only
during synthesis, to select appropriate subtypes for special purposes.

@deffn TerrainTypeProperty @code{subtype-x} n
This property is extra subtype information, used in synthesis.  Defaults
to @code{no-x}.
@end deffn

@deffn Symbol @code{no-x}
@end deffn

@deffn GlobalConstant @code{river-x}
This constant indicates that synthesis methods should treat this type as
a river.  The terrain type may be either a border or a connection.
@end deffn

@deffn GlobalConstant @code{valley-x}
This constant indicates that synthesis methods should treat this type as
a valley.
@end deffn

@deffn GlobalConstant @code{road-x}
This constant indicates that synthesis methods should treat this type as
a road.
@end deffn

@deffn TerrainTypeProperty @code{liquid} t/f
This property is true if the terrain type represents a liquid, which
means that adjacent cells of liquid must have the same elevation.
Defaults to @code{false}.
@end deffn

@node Terrain Compatibility

@subsection Terrain Compatibility

Terrain types are not always mutually compatible.  Incompatible types
may not be juxtaposed, either at game setup time or by unit action
during a game.

@deffn TableTT @code{adjacent-terrain-effect} t1 t2 -> t3
This table specifies what will happen to a cell of type @var{t1}
adjacent to a cell of type @var{t2}.  If @var{t3} is @code{non-terrain},
nothing will happen, otherwise it will become a cell of type @var{t3}.
Defaults to @code{non-terrain}.
@end deffn

@deffn TableTT @code{adjacent-terrain-effect-chance} t1 t2 -> n%
If a terrain change is specified in the @code{adjacent-terrain-effect} 
table, then the corresponding entry in this table determines the 
probability @var{n} of the terrain change effect succeeding. Defaults to 
@code{100%}.
@end deffn

@deffn TableTT @code{adjacent-terrain-effect-passes} t1 t2 -> n
If a terrain change is specified in the @code{adjacent-terrain-effect} 
table, then the corresponding entry in this table determines how many 
times this effect will be iterated by the terrain change code. Defaults 
to @code{-1}, which means that iterations will continue until no more 
changes occur or until the number of iterations is equal to the height of 
the map.
@end deffn

@deffn TableTT @code{adjacent-terrain-border} t1 t2 -> t3
If a cell terrain of type @var{t1} is adjacent to a cell terrain of type 
@var{t2}, then place a border of type @var{t3} between the cells. 
Defaults to @code{non-terrain}, which means that no border will be placed.@*
NOTE: Existing borders are deleted before the new border is placed.
@end deffn

@deffn TableTT @code{adjacent-terrain-border-chance} t1 t2 -> n%
If a border between @var{t1} and @var{t2} is specified in the 
@code{adjacent-terrain-border} table, then the corresponding entry in 
this table determines the probability of the new border actually being 
placed. Defaults to @code{100%}.
@end deffn

@deffn TableTT @code{adjacent-terrain-connection} t1 t2 -> t3
Similar to @code{adjacent-terrain-border}, but applied to connection
terrain.  Defaults to @code{non-terrain} (no connection will be placed), and
if a connection is placed, any existing connections will be removed.
@end deffn

@deffn TableTT @code{adjacent-terrain-connection-chance} t1 t2 -> n%
Similar to @code{adjacent-terrain-border-chance}, this specifies the chance
of a connection specified by @code{adjacent-terrain-connection} actually
being placed.  Defaults to @code{100%}.
@end deffn

Note that there is not a passes-limiting table for setting border 
terrain. This is because the border terrain algorithm executes in one 
pass, since border types are not dependent on neighboring border types.
Similarly, there is no passes-limiting table for connection terrain.

@node Other Terrain Properties

@subsection Other Terrain Properties

@deffn TerrainTypeProperty @code{elevation-min} elev
@end deffn
@deffn TerrainTypeProperty @code{elevation-max} elev
These properties define the minimum and maximum possible values for the
elevation in a cell of given terrain type.  Both default to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{temperature-min} n
@end deffn
@deffn TerrainTypeProperty @code{temperature-max} n
These properties define the minimum and maximum possible values for the
temperature in a cell of given terrain type.  Both default to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{wind-force-min} n
@end deffn
@deffn TerrainTypeProperty @code{wind-force-max} n
These properties define limits on wind force.  Both default to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{clouds-min} n
@end deffn
@deffn TerrainTypeProperty @code{clouds-max} n
These properties define limits on cloud density.  Both default to
@code{0}.
@end deffn

@node Material Types

@section Material Types

Materials are materials that are manipulated in mass quantities.  In
general, material types just index vectors of values attached to other
objects, such as unit supplies.

No more than 126 types of material may be defined.

@deffn Form @code{material-type} symbol properties@dots{}
This form defines a new type of material, named by @var{symbol}.
Details are similar to those for unit types.
@end deffn

@deffn GlobalVariable @code{m*}
This variable evaluates to a list of all material types, listed in the
same order as they were defined.
@end deffn

@deffn GlobalVariable @code{non-material}
This variable has a value that is never a material type.
@end deffn

@menu
* People::
@end menu

@node People

@subsection People

A material type can be designated as representing people.

@deffn MaterialTypeProperty @code{people} n
This property is the actual number of individuals represented by 1 of a
material.  If 0, then the material type does not have people associated
with it at all.
@end deffn

Multiple types of materials can represent different types of people, so
for example there could be one type @code{nomad} with 10
people/material, and another type @code{urbanite} with 10,000
people/material.

The basic cell capacities for materials also constrain people
materials. There can be an additional limit on the number of
individuals.

@deffn TerrainTypeProperty @code{people-max} n
This property is the maximum number of individuals allowed in a cell of
this type of terrain.  This is checked at the end of each turn; any
excess will be moved into adjacent cells or disappear entirely.
Defaults to @code{-1}, which allows any number of people in a cell.
@end deffn

@node Advance Types

@section Advance Types

Advances are scientific, economic, social, or any other type of
general accomplishment.  They can enable the construction of
particular types of units.  They are, however, different than tech points 
and development.

@deffn Form @code{advance-type} symbol properties@dots{}
This form defines a new type of advance, named by @var{symbol}.  
Naming details are similar to those for unit types.
@end deffn

@deffn GlobalVariable @code{a*}
This variable evaluates to a list of all advance types, listed in the
same order as they were defined.
@end deffn

@deffn GlobalVariable @code{non-advance}
This variable has a value that is never an advance type.
@end deffn

@deffn AdvanceTypeProperty @code{rp} n
This property is the number of research points necessary to achieve the
advance.  Defaults to @code{1}.
@end deffn

@deffn AdvanceTypeProperty @code{ai-next-goal} list
A weighted list of possible advances to select as a research goal 
if the current advance is completed and was a research goal. 
@end deffn

@deffn GlobalVariable @code{ai-initial-research-goals} list
A weighted list of possible advances to select as a research goal 
if none is currently set.
@end deffn

@node Static Relationships Between Types

@section Static Relationships Between Types

In general, static relationships are those that must always hold during
a turn.  @i{Xconq} will usually only test these when necessary, but this
is up to the implementation.  From the players' and designers' point of
view, these relationships can never be violated, even temporarily.

@menu
* Occupants and Transports::
* Units and Terrain::
* Units and Materials::
* Terrain and Materials::
* Units and Advances::
@end menu

@node Occupants and Transports

@subsection Occupants and Transports

A unit inside another unit is an ``occupant'' in a ``transport'', even
if the ``transport'' can never move.  There are two kinds of capacity.
Generic capacity is shared by all different types, while guaranteed
capacity is for a particular type only.

@deffn UnitTypeProperty @code{capacity} n
This property is the limit on the sum of sizes of units that may occupy
this type of unit, not counting the exclusive capacities.
@end deffn

@deffn TableUU @code{unit-size-as-occupant} u1 u2 -> n
This table is the ``size'' of a (full-sized) unit @var{u1} when it is in
a transport @var{u2}.  Defaults to @code{1}.
@end deffn

@deffn TableUU @code{unit-capacity-x} u1 u2 -> n
This table is the number of units of type @var{u2} that are guaranteed a
place in a unit of type @var{u1}.
@end deffn

@deffn TableUU @code{occupant-max} u1 u2 -> n
This table is the upper limit on the number of occupants of this type
(not counting @code{unit-capacity-x}).
@end deffn

@deffn UnitTypeProperty @code{occupant-total-max} n
This property is the upper limit on occupants of all types together.
Defaults to @code{-1}, which allows unlimited occupancy.
@end deffn

@deffn UnitTypeProperty @code{mobile-total-max} n
This property is the upper limit on the number of mobile units (speed >
0) allowed as occupants.  Defaults to @code{-1}, which allows unlimited
occupancy.
@end deffn

@deffn UnitTypeProperty @code{facility-total-max} n
This property is the upper limit on the number of facility units
(@code{facility} is true) allowed as occupants.  Defaults to @code{-1},
which allows unlimited occupancy.
@end deffn

Some incomplete units have occupancies for other units, while other
incomplete units must be completed before any other units may be in them.

@deffn TableUU @code{can-occupy-incomplete} u1 u2 -> t/f
If true, then an unit of type @var{u1} can be inside an incomplete unit of 
type @var{u2}.  Defaults to @code{false}.
@end deffn

A unit that is an occupant may not always have the same capabilities
as when it is out in the open.  Its vision, combat, construction, and
capacity may be affected.

@deffn TableUU @code{occupant-vision} u1 u2 -> n%
This is the effect on @var{u1}'s vision of being an occupant in a unit
of type @var{u2}.  If the value is 0, then @var{u1} is completely blind
while an occupant.  Defaults to @code{100}.
@end deffn

@deffn TableUU @code{occupant-combat} u1 u2 -> n%
This table defines the effect on the combat abilities of a unit of type
@var{u1} when an occupant in a unit of type @var{u2}.  If @code{0}, then
the occupant cannot attack or fire.  Defaults to @code{100}.
@end deffn

@deffn TableUU @code{occupant-can-construct} u1 u2 -> t/f
This table is @code{true} if @var{u1} can create or complete units while
an occupant of @var{u2}.  Defaults to @code{true}.
@end deffn

@deffn TableUU @code{occupant-can-have-occupants} u1 u2 -> t/f
This table is @code{true} if @var{u1} can have occupants of its own
while an occupant of @var{u2}.  Defaults to @code{true}.@*
@i{This table is no longer available.}
@end deffn

@deffn TableUU @code{can-recursively-wake} u1 u2 -> t/f
Determine whether a transport of type @var{u1} should wake an occupant 
of type @var{u2} when the transport is awakened for some reason.
Defaults to @code{true}.
@end deffn

@node Units and Terrain

@subsection Units and Terrain

This section describes relationships between units and terrain.  Units
can be set to disappear or be wrecked on particular types of terrain.
If the terrain can be occupied safely, there may be a limit on the
numbers of units that can be in the same cell.

@deffn TableUT @code{vanishes-on} u t -> t/f
This table is @code{true} if a unit @var{u} will disappear instantly if
it somehow ends up on terrain of type @var{t}.  Defaults to
@code{false}.
@end deffn

@deffn TableUT @code{wrecks-on} u t -> t/f
This table is @code{true} if a unit @var{u} will wreck instantly if it
somehow ends up on terrain of type @var{t}.  Defaults to @code{false}.
@end deffn

@deffn TerrainTypeProperty @code{capacity} n
This property is the limit on the sum of unit sizes that may share this
cell.  Defaults to @code{1}.
@end deffn

@deffn TableUT @code{unit-size-in-terrain} u t -> n
This table is the ``size'' of a (full-sized) unit @var{u} when it is
in/on the terrain @var{t}.  Defaults to @code{1}.@*
NOTE: This is not the same as the size property of an advanced unit.@*
NOTE: As of Xconq 7.5, this property is ignored for connection terrain
types. Connectors (roads, for example) now refer to @var{u}'s size in the
terrain that contains the connector rather than @var{u}'s size in
connector @var{t}.@*
NOTE: If you wish to prevent a unit's entry into @var{t}, then use the
@code{mp-to-enter-terrain} table, and not this one. The implication of
using @code{unit-size-in-terrain} to prevent entry is that the unit will
not be able to enter any connectors in @var{t} if @var{n} is set too
large.
@end deffn

@deffn TableUT @code{terrain-capacity-x} u t -> n
This table is the number of (full-sized) units of type @var{u} that are
guaranteed to have a place in the cell.
@end deffn

Note that the units' sides are irrelevant; the sizes of units of all
sides are added together.  Limits are calculated separately for the
connection and open terrain in a cell; however, it is possible for a
unit in a cell to override any capacity due to connections in that cell.

@deffn TableUT @code{capacity-negation} u t -> t/f
Defaults to @code{false}.@* 
@i{This table is no longer available.}
@end deffn

@deffn UnitTypeProperty @code{stack-order} n
This property is the relative position of this type of unit within a
stack of different units.  Larger values put units higher in the stack.
The exact values are unimportant, they are just used as sort keys.  The
use of this value is to ensure that particular types are ``seen first''
when looking at a cell, so for instance if a truck and a city are
stacked on the same cell, everybody will see the city and not the truck.
The owner of these units can still see them.  If the stack-order of two
units is the same, then the higher-numbered type will be higher in the
stack.
@end deffn

There is a possible bizarrity with stacking limits and units that can't
see each other when in the same hex, namely that a player could be
prevented from moving a unit into a cell that looks like it has enough
room.

@node Units and Materials

@subsection Units and Materials

Units can carry materials.

@deffn TableUM @code{unit-storage-x} u m -> n
This table is the space reserved specifically for each type of material.
@end deffn

Materials that represent people may surrender to a unit in their cell.

@deffn TableUT @code{people-surrender-chance} u t -> n%
This table is the base chance that people in terrain of type @var{t}
will change sides if a unit of type @var{u} is in their cell.
@end deffn

@deffn TableUM @code{people-surrender-effect} u m -> n
This is a multiplier that takes the people type into account.  Defaults
to @code{100}.
@end deffn

@node Terrain and Materials

@subsection Terrain and Materials

@deffn TableTM @code{terrain-storage-x} t m -> n
This table is the maximum amount of a material @var{m} that may be
present in a cell with terrain @var{t}.
@end deffn

@node Units and Advances

@subsection Units and Advances

@deffn TableUA @code{advance-needed-to-build} u a -> t/f
This table is true whenever the side must have achieved advance @var{a}
before it can being to construct units of type @var{u}.
@end deffn

@deffn UnitTypeProperty @code{obsolete} a
This property is the type of advance that makes a unit obsolete, meaning
that units of that type may longer be constructed (existing units are
unaffected though).  Defaults to @code{non-advance}, meaning that the
unit type is never obsolete.
@end deffn


@node Vision

@section Vision

The parameters in this section define how sides get information about the
world, units, and other sides.

@menu
* Basic Vision::
* Line of Sight::
* Tracking::
* Spying::
@end menu

@node Basic Vision

@subsection Basic Vision

@deffn GlobalVariable @code{see-all} t/f
This variable is @code{true} if everything in the world, units, terrain,
etc, is always visible at all times, including initially.  It takes
precedence over @i{all} other visibility and spying parameters.
Defaults to @code{false}.
@end deffn

@deffn GlobalVariable @code{see-terrain-always} t/f
If this variable is @code{true}, then any side that has seen the terrain
of a cell will be informed if that terrain ever changes.  Defaults to
@code{true}.
@end deffn

@deffn UnitTypeProperty @code{see-always} t/f
This property is @code{true} when a unit is always visible after it has
been seen once, so that side changes, movements, etc will be seen
forever afterwards.  If the unit moves into terrain that has not been
seen, then that terrain also becomes seen as well.  Defaults to
@code{false}.
@end deffn

@deffn UnitTypeProperty @code{see-occupants} t/f
This property is @code{true} when a unit's occupants are also seen
whenever the unit itself is under observation.  Defaults to
@code{false}.
@end deffn

@deffn UnitTypeProperty @code{spot-action} t/f
If this property is @code{true}, then the unit's chance to be seen by
other sides will be tested each time the unit acts in any way.  This
property is in addition to the check at the beginning of each turn.
Defaults to @code{true}.
@end deffn

The people in a cell effectively view (for their side) all units in that
cell.  Some units can hide from the people.

@deffn TableUM @code{people-see-chance} u m -> n%
This table is the chance that the people of the given type @var{m} will
see a unit of type @var{u}.  This will be evaluated for each people type
individually, once at the beginning of each turn, and once for each
populated cell that the unit enters during the turn.  Defaults to
@code{100}.
@end deffn

@deffn UnitTypeProperty @code{vision-range} dist
This property is the maximum range of vision coverage by the unit.  A
value of @code{-1} disables all vision, @code{0} means only units in the
same cell may be seen, and @code{1} means units in adjacent cells may be
seen.  Defaults to @code{1}.
@end deffn

@deffn TableUU @code{see-chance-at} u1 u2 -> n%
This table is the chance that a unit @var{u1} will see another sides's
unit of type @var{u2} when both are in the same cell.  Defaults to
@code{100}.
@end deffn

@deffn TableUU @code{see-chance-adjacent} u1 u2 -> n%
This table is the chance that a unit @var{u1} will see another sides's
unit of type @var{u2} when the two are in adjacent cells.  Defaults to
@code{100}.
@end deffn

@deffn TableUU @code{see-chance} u1 u2 -> n%
This table is the base chance that a unit @var{u1} will see a unit
@var{u2} in cells at distance 2 or greater.  Defaults to @code{100}.
@end deffn

@deffn TableUT @code{visibility} u t -> n
This table is the effect of terrain @var{t} on a unit @var{u}'s chances
of being seen.  Values less than 100 are reduced visibility, values
greater than 100 increase the unit's chances to be seen.  Defaults to
@code{100}.
@end deffn

@deffn TableUT @code{vision-night-effect} u t -> n
This table is the multiplier for unit @var{u}'s vision at night in each
type of terrain @var{t}.  Effect is to multiply with both vision range
and see-chance.  Defaults to @code{100}.
@end deffn

@deffn TableTM @code{see-material-always} t m -> t/f
Defaults to @code{true}.
@end deffn

@deffn GlobalVariable @code{see-weather-always} t/f
If true, then weather changes (in cells that have been seen) will always
be reported.  Defaults to @code{true}.
@end deffn

@deffn TableUU @code{see-mistake-chance} u1 u2 -> .01n%
This is the chance that a unit of type @var{u1} will see a unit of type
@var{u2} as some other type.  The type of unit seen instead is
determined by the table @code{looks-like}.
@end deffn

@deffn TableUU @code{see-mistake-range-min} u1 u2 -> n
This is the minimum range at which an unit of type @var{u1} can mistake 
an unit of type @var{u2} as some other type.
@end deffn

@deffn TableUU @code{looks-like} u1 u2 -> n
This table is the set of weights indicating which type @var{u2} a unit
of type @var{u1} is most likely to be mistaken for.  When a unit makes a
viewing mistake, then the program adds up all the weights and chooses
randomly according to weight.  Defaults to @code{0}, which means that
@var{u2} never looks like @var{u1}.
@end deffn

@node Line of Sight

@subsection Line of Sight

@deffn UnitTypeProperty @code{can-see-behind} t/f
This property is determines if elevations are ever an obstruction to the 
unit type. If @code{false}, then the unit cannot see behind higher 
elevations. Defaults to @code{true}.
@end deffn

@deffn TableUT @code{eye-height} u t -> elev
This property is the additional elevation above the unit's position that
a unit can see with, when in the given terrain.
@end deffn

@deffn TableUT @code{body-height} u t -> elev
This property is the effective height of the main visible part of a
unit, when in the given terrain.
@end deffn

@deffn TerrainTypeProperty @code{thickness} elev
This property is the thickness of the terrain, which is the difference
between the ``ground'' of the terrain and its top.
@end deffn

@node Tracking

@subsection Tracking

When is unit is being tracked, then the sides doing the tracking can see
the unit move around, even if the cell is not being covered by any of
the sides' own units.  If this is enabled, then particular units enable
tracking, and the chance of losing track depends on the terrain.

@deffn TableUU @code{track-chance} u1 u2 -> .01n%
This table gives the chance that @var{u1}'s side will be able to track a
unit of type @var{u2} that is within range (same or adjacent cell).
@end deffn

@deffn TableUT @code{lose-track-chance} u t -> .01n%
This table gives the chance that each side tracking a unit will lose
that track when the unit enters terrain of type @var{t}.
@end deffn

@node Spying

@subsection Spying

A unit type can also be specified to do spying automatically.  The
outcome of spying is calculated once/unit/turn, at the beginning of the
turn (after move calculation but before any players can do anything).
Spying can happen to any unit not on the spying unit's side.

@deffn UnitTypeProperty @code{spy-chance} .01n%
This property is the chance that the unit will be successful at spying.
@end deffn

@deffn UnitTypeProperty @code{spy-range} dist
This property is the maximum distance at which the unit will find out
something by spying.
@end deffn

@deffn TableUU @code{spy-quality} u1 u2 -> n%
This table gives the chance that @var{u1}'s spying will return
information about a unit of type @var{u2} that is within the spying
range.  Defaults to @code{100}.
@end deffn

@deffn TableUU @code{spy-track-chance} u1 u2 -> .01n%
This table is the chance that if @var{u1}'s spies return information
about a unit of type @var{u2}, the unit will also become tracked by the
spy's side.
@end deffn

@node Game Initialization

@section Game Initialization

Game initialization always starts by resetting all the game-defining
data structures to an empty state.  This means no types, no world, etc.
Then @i{Xconq} reads and interprets all of the game modules that have
been requested.  These modules may overwrite each other arbitrarily.
Then any command line or startup options are processed (this may involve
an interactive dialog), and the random number generator is initialized.
and players are matched with sides (any sides needed for players will be
created and named at this time).  @i{Xconq} then executes a number of
@i{synthesis methods} to do various kinds of setup.

(Some interfaces might allow for confirmation of the setup before
launching into the game proper, but this cannot be assumed.)

Since the details of good game synthesis can be complicated, synthesis
methods are simply wired-in pieces of code.  Each method is
self-contained; it assumes the game state to be valid, it will determine
its own applicability and produce a valid result.  It will also acquire
any data that it needs, so does not require any special setup; however,
a method may fail to run if it cannot find that data.  For instance, the
usual fractal terrain generator needs percentiles for each terrain type,
and will not function without them.  It may be that all the requested
synthesis methods fail; this is OK if @i{Xconq}'s data is present and
consistent, but otherwise @i{Xconq} will shut itself down, since it has
no remaining alternatives (think of this as a serious programming error
and fix the game design).

@node Synthesis Methods

@section Synthesis Methods

The synthesis method list specifies which methods will be run, and in
what order.  After they have all been run, @i{Xconq} runs a consistency
and completeness check.  For instance, there should be a world with
terrain everywhere.  Failure at this point is fatal; @i{Xconq} will
either exit or return to a game setup dialog.

@menu
* Synthesis Method List::
* Fractal World::
* Maze World::
* Random World::
* Earthlike World::
* Random Terrain Changes::
* Making Rivers::
* Making Roads::
* Making Countries::
* Making Independent Units::
* Making Weather::
* Making Initial Supply::
* Naming Geographical Features::
* Naming Units::
* Making a Random Date::
@end menu

@node Synthesis Method List

@subsection Synthesis Method List

@deffn GlobalVariable @code{synthesis-methods} method-list
This variable is a list of synthesis methods.  If the list is empty, no
synthesis methods will be run.
@end deffn

The list of synthesis methods is ordered, and many contain duplicates,
so that a method can be run multiple times during setup.  Note that most
of the existing methods will simply return if they detect that their
work has already been done, so multiple runs will have no effect.

The default synthesis method list is effectively
@example
(make-fractal-percentile-terrain
 make-countries
 make-independent-units
 make-roads
 make-rivers
 make-weather
 init-supplies
 name-geographical-features
 )
@end example

@deffn GlobalVariable @code{synthesis-done} list
This variable is a list of what methods were used, and how many times.
This is for the use of the save/restore machinery, should not normally
be manipulated by game designers.
@end deffn

@node Fractal World

@subsection Fractal World

The fractal world synthesizer can make a variety of natural-looking
terrain.  It relies on a number of parameters to govern a single
algorithm.

@deffn SynthesisMethod @code{make-fractal-percentile-terrain}
This method generates the terrain layer of a world.  It works by
generating two distinct layers of random blobs, known as the ``alt'' and
``wet'' layers, then decides on a terrain type for each cell.  If
elevations are defined, then this method will use the ``alt'' layer to
produce elevations.
@end deffn

@deffn GlobalVariable @code{alt-blob-density} n
@end deffn
@deffn GlobalVariable @code{wet-blob-density} n
These variables are the number of blobs to put down, expressed as number
per 10,000 cells.  Defaults to @code{500}.
@end deffn

@deffn GlobalVariable @code{alt-blob-size} n.f%
@end deffn
@deffn GlobalVariable @code{wet-blob-size} n.f%
These variables are the average number of cells in a blob, expressed as
number per 10,000 cells.  Defaults to @code{100}.
@end deffn

@deffn GlobalVariable @code{alt-blob-height} n
@end deffn
@deffn GlobalVariable @code{wet-blob-height} n
These variables are the amounts by which to increment or decrement
within a blob.  Defaults to @code{1000}.
@end deffn

@deffn GlobalVariable @code{alt-smoothing} n
@end deffn
@deffn GlobalVariable @code{wet-smoothing} n
These variables specify the number of averaging steps to perform after
the blobs have been generated.  Defaults to @code{2}.
@end deffn

@deffn TerrainTypeProperty @code{alt-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{alt-percentile-max} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-max} n%
These properties are the percentiles of elevations and moistures that
result in the given terrain type.  Percentile ranges may overlap, in
which case the earlier-defined terrain type will be used.  If a cell has
a alt and wet that does not fall in any of the ranges, then terrain type
0 will be used there and players will be warned.  Mins defaults to
@code{0}, maxes to @code{100}.
@end deffn

After the terrain has been assigned types, the method will give a single
type to all the cells on the edge of the area.

@deffn GlobalVariable @code{edge-terrain}
This variable is the type of terrain to fill in on all the edges of a
world.  The edges of a world have little or no effect on the game, but
the terrain type should be something distinctive, so that players can
recognize the edges easily.  (For instance, ice is usually a good choice
for edges, but probably not on a map of Antarctica!)  Defaults to
terrain type 0 (the first defined type).
@end deffn

@node Maze World

@subsection Maze World

A maze consists of a set of randomly placed ``rooms'' connected by
random passages.

@deffn SynthesisMethod @code{make-maze-terrain}
This method creates terrain that looks like a maze.  It starts by
randomly assigning terrain according to its @code{occurrence}, similarly
to @code{make-random-terrain} below, then carves out rooms and passages,
filling each of those with terrain types according to their respective
occurrences.
@end deffn

@deffn TerrainTypeProperty @code{maze-room-occurrence} n
This property is the weighted amount of this terrain type in rooms in
the maze.
@end deffn

@deffn TerrainTypeProperty @code{maze-passage-occurrence} n
This property is the weighted amount of this terrain type in passageways
in the maze.
@end deffn

@deffn GlobalVariable @code{maze-room-density} n
This variable is the fraction of the maze that is room, expressed as the
number of cells per 10,000 cells in the area.  Defaults to @code{1000}.
@end deffn

@deffn GlobalVariable @code{maze-passage-density} n
This variable is the fraction of the area that is passageway, expressed
as the number of cells per 10,000 cells in the area.  Defaults to
@code{3000}.
@end deffn

This method will apply edge terrain as a last step.

@node Random World

@subsection Random World

The random world generator just assigns terrain and elevations randomly.

@deffn SynthesisMethod @code{make-random-terrain}
This method generates completely random terrain.  It uses a simple
weighting to govern how much of each terrain type appears, and makes
random elevations as well.
@end deffn

@deffn TerrainTypeProperty @code{occurrence} n
This property is the percentage of the world that will be of this type,
if the terrain is cell terrain.  If the terrain is border or connection,
it is the probability (expressed as .01% increments) that any direction
of any cell will have that border or connection.  Defaults to @code{1}.
@end deffn

@node Earthlike World

@subsection Earthlike World

Earthlike generation uses algorithms that more closely approximate
realistic terrain.

@deffn SynthesisMethod @code{make-earthlike-terrain}
This method generates terrain that approximates what actually appears on
Earth.
@end deffn

@node Random Terrain Changes

@subsection Random Terrain Changes

Terrain generation methods may postprocess the generated terrain by
randomly changing cells of some types.

@deffn TableTT @code{terrain-density} t1 t2 -> .01n%
This table is the .01% chance that a cell of type @var{t1} will be
changed to type @var{t2}.
@end deffn

@node Making Rivers

@subsection Making Rivers

Rivers are borders or connections consisting of ``watery terrain'' that
run downhill to regions of water.

@deffn SynthesisMethod @code{make-rivers}
This method looks for a border or connection terrain type with a
@code{subtype-x} of @code{river-x}.  then uses the world's elevation
data to run rivers downhill (always choosing the lowest of possible
adjacent locations) until they reach cell terrain with a @code{subtype}
> 0.  This method will not run if there are no appropriate terrain
types, nor if there is no elevation data.
@end deffn

@deffn TerrainTypeProperty @code{river-chance} .01n%
This property is the chance that a river will start in or around a cell
of this terrain type.
@end deffn

@deffn GlobalVariable @code{river-sink-terrain} t
If the value of this variable is a terrain type, then a cell completely
surrounded by river will be changed to be this type.  Defaults to
@code{non-terrain}.
@end deffn

Note that the algorithm computes rivers in a deterministic way, so high
values of @code{river-chance} do not result in tangled rivers.

@node Making Roads

@subsection Making Roads

The road generation method makes networks of connection terrain between
particular unit types, usually those resembling cities.

@deffn SynthesisMethod @code{make-roads}
This methods synthesizes roads for an area.  For any connection type of
terrain, if no layer has been created for it already, and the type has a
@code{subtype-x} of 3, put down roads between any pair of units whose
@code{road-chance} is nonzero.  The method will attempt to share road
routes whenever possible, and choose terrain according to
@code{road-into-chance}.  In addition, the method may also generate spur
roads connecting units to existing roads, and run roads from one edge of
the area to another.
@end deffn

@deffn TableUU @code{road-chance} u1 u2 -> n%
This table is the chance that a road will be laid, running from a unit
of type @var{u1} to one of type @var{u2}.  Note that is not a
symmetrical relationship; since roads follow random paths, if the
@code{road-chance} causes a road to be laid from @var{u1} to @var{u2},
and another from @var{u2} to @var{u1}, it is quite possible that the
result will be two different roads connecting the two units.
@end deffn

@deffn TableTT @code{road-into-chance} t1 t2 -> n%
This table is the chance that a road will be chosen to pass from terrain
of type @var{t1} into terrain of type @var{t2}.
@end deffn

@deffn UnitTypeProperty @code{spur-chance} n%
This property is the percentage chance that the unit will get a spur
road running from the unit to the nearest existing road.
@end deffn

@deffn UnitTypeProperty @code{spur-range} dist
This property is the radius of the area that will be searched for an
existing road.  Defaults to @code{1}, which results in spurs connecting
only to roads in adjacent cells.
@end deffn

@deffn UnitTypeProperty @code{road-to-edge-chance} n%
This property is the percentage chance that the unit will have a road
running from the unit to some edge of the area.
@end deffn

@deffn GlobalVariable @code{edge-road-density} n
This variable is the density of roads that run from one area edge to
another, expressed as the number per 10,000 cells in the area.  (note,
not counting just edge cells).
@end deffn

@node Making Countries

@subsection Making Countries

The @code{make-countries} method sets up the starting units for each
side, placing them in a confined area, separated from the starting units
of other sides and taking terrain preferences into account.  If
requested, this method will also expand the country outwards by a
specified amount, possibly placing additional units in the process.

@deffn SynthesisMethod @code{make-countries}
This method works by looking for a likely place for the country,
randomly places a basic set of starting units within that area, then
expands the country outwards.  The parameters give you control over the
mix of terrain types in the country, as well as the size and relative
positions of the different countries.  This method runs on any side with
fewer units than it is supposed to start with, as given by the
parameters below.  It places groups of units at locations separated from
each other by specified distances.
@end deffn

@deffn GlobalVariable @code{country-radius-min} dist
This variable is the radius of the country's initial area.  Defaults to
@code{-1}, which allows the algorithm to calculate a ``reasonable''
country size appropriate to the given number of units.
@end deffn

@deffn GlobalVariable @code{country-separation-min} dist
@end deffn
@deffn GlobalVariable @code{country-separation-max} dist
These variables are the minimum and maximum distances of country centers
from each other, in cells.  If small, countries will mostly overlap; if
very large, then attempts to use small worlds will fail; if the max and
min are too close to each other, placements can also fail.  For both of
these, a value of @code{-1} disables their effect.  Both default to
@code{-1}.
@end deffn

The max separation bound needs to be satisfied for a country with
respect to only @i{one} other country, so for instance the final layout
may involve a long ``string'' of countries where the first and last
countries are very far apart from each other.  The minimum bound must be
satisfied for all pairs of countries.

@deffn TerrainTypeProperty @code{country-terrain-min} n
This property is the minimum amount of terrain that must be within the
country's initial radius.
@end deffn

@deffn TerrainTypeProperty @code{country-terrain-max} n
This property is the most terrain of the given type that may appear.  If
@code{-1}, then any amount may be present.  Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{start-with} n
@end deffn
@deffn UnitTypeProperty @code{independent-near-start} n
These properties set the number of units of the given type in a player's
country.  These units are randomly scattered within the initial radius,
and the @code{favored} table (see below) decides which terrains will be
used.  Units may be placed inside each other; in fact, units with no
favored terrain will be made into occupants if possible.

The independent units will be placed after the ones belonging to the
side, so on the average they will get the less desirable locations in
the country.  Unlike the randomly-scattered independent units, these
will be named using the side's namers.

Both default to @code{0}.
@end deffn

@deffn TableUT @code{favored-terrain} u t -> n%
This table sets the probability of the unit type being on the given type
of terrain at the outset.  A value of @code{0} is an absolute
prohibition against placing the unit on that type of terrain, thus every
game must specify at least one non-zero value for some terrain type and
some initial unit type.  Defaults to @code{100}.
@end deffn

Once the initial country area has been set up, then you can allow the
countries to expand outwards.  Expansion occurs at the same rate for all
countries.  Countries may expand into and through each other.  Expansion
occurs as a number of @var{steps}, each step increasing the radius of
countries by 1 all around.

@deffn TerrainTypeProperty @code{country-growth-chance} n%
This property is the chance that a country will expand onto an unclaimed
cell of the given terrain type.  Defaults to @code{100}.
@end deffn

@deffn TerrainTypeProperty @code{country-takeover-chance} n%
This property is the chance that a country will expand onto another
country's cell of the given terrain type.
@end deffn

@deffn UnitTypeProperty @code{unit-growth-chance} n.f%
This property is the chance that a unit of the given type will be placed
when the country expands onto a cell.  The unit will only be placed if
the @code{favored} chance is also true.
@end deffn

@deffn UnitTypeProperty @code{independent-growth-chance} n.f%
This property is the chance that an independent unit of the given type
will be placed when the country expands onto a cell.  The @code{favored}
chance is also evaluated.
@end deffn

@deffn UnitTypeProperty @code{unit-takeover-chance} n.f%
This property is the chance that a unit of the given type in another
country and belonging to another side will be given to the growing side.
@end deffn

@deffn UnitTypeProperty @code{independent-takeover-chance} n.f%
This property is the chance that an independent unit of the given type
in another country will be given to the growing side.
@end deffn

@deffn GlobalVariable @code{country-radius-max} dist
This variable is a cap on the country growth process.  Values between
@code{0} and @code{country-radius-min} prevent country growth entirely,
while a value of @code{-1} allows growth to encompass the entire world.
@end deffn

@deffn UnitTypeProperty @code{country-units-max} n
This property is a cap on the number of units given to the side's
country.  Defaults to @code{-1}, which disables any limit.
@end deffn

@deffn GlobalVariable @code{growth-stop-chance} n%
This variable is the chance that a country's growth will stop, if during
the current step no new cells were added to the country.
@end deffn

@deffn TerrainTypeProperty @code{country-people-chance} n%
This property is the chance that the people's side will be changed to
match that for the country they are in.  Defaults to @code{100}.
@end deffn

@node Making Independent Units

@subsection Making Independent Units

@deffn SynthesisMethod @code{make-independent-units}
This method scatters independent units randomly over the world.  This
method will not run if the specified density of independent units has
already been achieved, for instance from a predefined world or from
country placement.  Independent units that should be inside other
independents will be handled correctly.
@end deffn

@deffn TableUT @code{independent-density} u t -> .01n%
This table is the probability that an independent unit of
type @var{u} will be placed on a empty cell with terrain
of type @var{t}.
@end deffn

@deffn TerrainTypeProperty @code{independent-people-chance} .01n%
This property is the chance that the people of a cell with this terrain
type will be made independent.
@end deffn

@node Making Weather

@subsection Making Weather

Weather synthesis sets up an initial state for the weather.

@deffn SynthesisMethod @code{make-weather}
This method sets up weather-related layers, including temperature,
winds, and clouds.
@end deffn

@node Making Initial Supply

@subsection Making Initial Supply

By default, all units start out empty of materials.  The supply
initialization method gives each unit a starting supply, according to
the initial supply tables.

@deffn SynthesisMethod @code{make-initial-materials}
This method fills unit and cell supplies to specified levels.  It will
fill all units in existence at the moment it runs, including units that
have not appeared yet.  Similarly, all cells will be filled.
@end deffn

@deffn TableUM @code{unit-initial-supply} u m -> n
This table is the amount of each material that each unit will start out
with.  If the initial supply is greater than unit's capacity, then the
unit will just be filled to capacity.
@end deffn

Terrain cells may also have initial material levels.

@deffn TableTM @code{terrain-initial-supply} t m -> n
This table is the amount of material @var{m} that each cell with terrain
@var{t} will start out with.  This will be limited by the cell's
capacity.
@end deffn

Sides with treasuries may start with an initial amount.

@deffn MaterialTypeProperty @code{initial-treasury} n
This is the amount of each material type that a side's treasury
will start with.
@end deffn

@deffn GlobalVariable @code{indepside-has-treasury} t/f
This is true if the independent units have a common treasury.  (This may
be necessary if indeps may construct units, and those units need
treasury material.)
@end deffn

@deffn GlobalVariable @code{treasury-size} n
This is the size of each treasury.  All treasuries are the same size.
@end deffn

@node Naming Geographical Features

@subsection Naming Geographical Features

Although named geographical features don't affect the outcome of a game
in any way, they are useful for ``color'' and for identifying locations
more readably.

@deffn SynthesisMethod @code{name-geographical-features}
This method identifies and names regions as geographical features, such
as mountain ranges and islands.
@end deffn

@deffn GlobalVariable @code{feature-namers} feature-namer-list
This variable is a list of feature types and their associated namers.
This is used for features not intersecting any country with a namer for
the feature's type.  Defaults to @code{()}.
@end deffn

@deffn GlobalVariable @code{feature-types} feature-expr-list
This variable is a list of feature types that may be identified.  Each
list element has the form @code{(typename [name] [parameters])}, where
@var{typename} is from the list given below, @var{name} is the specific
name of the type (which is used in @code{feature-namers}, and
@var{parameters} is any optional parameters describing how to
identify features of that type.  Defaults to @code{()}.
@end deffn

@itemize @bullet

@item @code{peak} [name] [density]
This type causes the synthesizer to look for high points, at a density
of @var{density} per 10,000 cells (defaulting to 50).

@item @code{island} [name] [sizemax]
This type identifies areas of non-liquid terrain surrounded by liquid
terrain, up to @var{sizemax} (default 30) cells in size.

@item @code{lake} [name] [sizemax]
This type identifies areas of liquid terrain surrounded by non-liquid
terrain, up to @var{sizemax} (default 30) cells in size.

@item @code{bay} [name]
This type identifies cells that are liquid but at least 2/3 surrounded
by non-liquid terrain.

@end itemize

@node Naming Units

@subsection Naming Units

@deffn SynthesisMethod @code{name-units-randomly}
This method gives names to previously-unnamed units, using their usual
namers.
@end deffn

@node Making a Random Date

@subsection Making a Random Date

For extra color, games can be set up to start at a random date within a
given range.  If day or year effects are defined, this also has the
effect of making the game start at a random time of day or year.

@deffn SynthesisMethod @code{make-random-date}
This method generates a random starting date, within specified bounds.
@end deffn

@deffn GlobalVariable @code{initial-date-min} date
This variable is the earliest possible date for the game.  Defaults to
@code{""}.
@end deffn

@deffn GlobalVariable @code{initial-date-max} date
This variable is the latest possible date for the game.  Defaults to
@code{""}.
@end deffn

@node Setup Postprocessing

@section Setup Postprocessing

Some initialization steps will be done after all synthesis methods
have been run.  @i{Xconq} will always do these.

@menu
* Initial View::
@end menu

@node Initial View

@subsection Initial View

By default, each side starts out knowing only what its units can
normally see at the beginning of the first turn.  These parameters add
to that initial view.

@deffn GlobalVariable @code{terrain-seen} t/f
This variable is @code{true} if all the terrain of the world is known
initially.  Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{initial-seen-radius} dist
This property specifies the radius of the area seen around each of the
starting units.  It computes visibility of terrain (cells and borders)
only.  Defaults to @code{1} (which is a no-op if the unit's
@code{vision-range} is greater than or equal to 1).
@end deffn

@deffn UnitTypeProperty @code{already-seen} n%
This property is the chance to see units of this type at the beginning
of the game.  This applies only to units belonging to another side, and
on known terrain.  The effect is one-time, so if an @code{already-seen}
unit changes sides later on, other players will not see the change
unless they have the unit under observation for themselves.  Note that
@code{see-always} implies @code{already-seen}.
@end deffn

@deffn UnitTypeProperty @code{already-seen-independent} n%
This property is like @code{already-seen}, but applies to independent
units specifically.
@end deffn

@node Naming and Text Generation

@section Naming and Text Generation

@i{Xconq} can generate names for sides, units, and geographical
features.  Although most naming happens during game setup, names may be
assigned throughout the course of a game, both automatically and by
player request.

@menu
* Naming Sides::
* Namers::
* Naming Methods::
* Notices and Narratives::
@end menu

@node Naming Sides

@subsection Naming Sides

Side naming is special, because several different but related names
have to be produced. The use of a @dfn{side library} is a way to gain 
finer control over side names and their associated plural and 
possessive variations than one would have through the use of a 
@code{side-namer}.

@deffn GlobalVariable @code{side-library} side-info@dots{}
This variable is a weighted list of groups of side properties, each of
which may be used to fill in a side.
@end deffn

The form of each side name entry is basically a subset of the side's
properties:
@example
([ weight ] ... (name <name>) ... (color <colors>) ...)
@end example
Each entry can include as many or as few of the attributes as desired;
any missing will be filled in from the usual defaults.  The optional
@var{weight} is a number that adjusts the probability of selection of
the given side name set; it defaults to 1, and the probability is scaled
according to the sum of the weights for all the sides listed.  If any
property value is a namer, then the namer will be run.  (Note that if
multiple namers are specified, they cannot be guaranteed to coordinate
with each other, so you can end up with a side noun that is
inappropriate for its corresponding side name.)

@deffn GlobalVariable @code{side-color-library} side-info@dots{}
This variable is a weighted list of side color schemes, each of
which may be used to fill in a side's color scheme.  The values
from this list are only used if the entry from @code{side-library}
does not supply a color scheme.
@end deffn

@node Namers

@subsection Namers

Since one of the purposes of naming is to identify objects uniquely, any
name generator should be able to maintain some memory as to what has
been generated already.  The objects that do this are @dfn{namers}.

@deffn Form @code{namer} symbol/id method
This form defines an instance of a namer, with either the symbolic name
or numeric id.  If either matches the name or id of an existing namer,
then the old namer will be overwritten, otherwise a new one will be
created.  The @var{method} must be one of the naming methods listed
below.
@end deffn

@deffn GlobalVariable @code{default-namer} str
This namer may be used when another namer can no longer produce names,
such as a random namer that exhausts its list of possibilities.  At
present, it is used only with the @code{junky} and @code{random} naming
methods (presumably the @code{grammar} is inexhaustible!).
@end deffn

@node Naming Methods

@subsection Naming Methods

As with general synthesis, @i{Xconq} has a number of @dfn{naming methods}
available.

@deffn NamingMethod @code{random} names @dots{}
This method picks a name from the given list of names and removes that
name from the list.
@end deffn

@deffn NamingMethod @code{junky}
This method produces a gobbledy-gook name, very techy-looking.
@end deffn

@deffn NamingMethod @code{in-order} names @dots{}
This method pulls names from a list in the order that they appear.
@end deffn

@deffn NamingMethod @code{grammar} root max-length rules@dots{}
This method defines a grammar, where @var{root} is the root symbol,
@var{max-length} is a limit on the length of the generated names (in
characters), and @var{rules} is a list of rules of the form
@example
(@var{symbol} @var{rule-body})
@end example
The @var{rule-body} can have the following forms:
@example
(@var{rule-body} @var{rule-body} ...)
(or [ @var{weight} ] @var{rule-body} [ @var{weight} ] @var{rule-body} ...)
(capitalize @var{rule-body})
(reject @var{rule-body} string-or-sym ...)
symbol
string
@end example
@end deffn

The generation process for @code{or} works by substituting one of the
rule's alternatives for the symbol.  The probability of an alternative
being selected is arrived at by adding up the optional weights
@var{weight} (assuming missing weights to be @code{1}), and choosing
with a probability of the weight divided by the total sum of weights.
Thus the weights need not add up to any particular value.

If the list is not prefixed by any of the special symbols, then each
rule body in the list is expanded, and the results concatenated.

Strings and symbols that are not terminals get used directly.  If a
symbol in the rule's chosen expansion does not appear as the lefthand
side in any rule, then it will be handled as a string, otherwise it will
be expanded in turn.  If the symbol matches a namer's name, then that
namer will be run and its result incorporated.

@deffn GlobalConstant @code{or}
This designates a list of alternatives.
@end deffn

@deffn Symbol @code{capitalize}
Directs capitalization of the result generated by the rule body.
@end deffn

@deffn Symbol @code{reject}
A rule body headed by @code{reject} includes a list of substrings that
should not appear in a generated name; this is a convenient way to
filter out particularly unlovely results.  This works by retrying
generation if one of the listed strings appears in the name generated by
the rule body in the form.
@end deffn

@node Notices and Narratives

@subsection Notices and Narratives

@deffn GlobalVariable @code{action-notices} patterns
This variable is a list of patterns that an interface may use to
generate textual notices of unit actions.
Defaults to @code{()}.
@end deffn

@deffn GlobalVariable @code{action-movies} patterns
This variable is similar, but instead of generating text, the result
of a match is a designation of a movie (an animation or sound).
Defaults to @code{()}.
@end deffn

@deffn GlobalVariable @code{event-notices} patterns
This variable is a list of patterns that an interface may use to
generate textual notices of historical events.
Defaults to @code{()}.
@end deffn

@deffn GlobalVariable @code{event-narratives} patterns
This variable is similar, but its text is in the past tense.
Defaults to @code{()}.
@end deffn

@deffn GlobalVariable @code{event-movies} patterns
This variable is similar, but instead of generating text, the result
of a match is a designation of a movie (an animation or sound).
Defaults to @code{()}.
@end deffn

@node Actions

@section Actions

The parameters in this section define and regulate the various actions
that are available to units during a game.

Actions always start and complete (including all of their effects)
within the same turn, and a unit can only do one at a time.

All actions are potentially available to all units, but the parameters
can be set so as to deny any action type to any unit type.  See the
descriptions with each action type.

All action is limited by action points.  Each unit gets a certain number
at the beginning of each turn and expends them in the course of doing
things.  The usual expenditure is one point per action, but may be more,
as defined for each type of action.  A unit action must always consume
at least one action point.  Units can accumulate acp from turn to turn,
and they can also reduce acp below zero.

@menu
* Actions in General::
* Action Ordering::
* Movement Action::
* Entry Action::
* Develop Action::
* Toolup Action::
* Unit Creation Actions::
* Unit Completion Action::
* Repair Action::
* Material Production Action::
* Material Extraction Action::
* Material Transfer Action::
* Side Change Action::
* Disband Action::
* Type Change Action::
* Combat Actions::
* Capture Action::
* Detonation Action::
* Terrain Alteration Actions::
@end menu

@node Actions in General

@subsection Actions in General

@deffn UnitTypeProperty @code{acp-per-turn} acp
This property is the basic allowance of action points that a unit gets
each turn.
@end deffn

@deffn UnitTypeProperty @code{acp-min} acp
This property specifies how far into ``action debt'' a unit can go
during a turn before it is prevented entirely from acting.  A unit with
acp < 1 at the beginning of a turn cannot do anything at all.
@end deffn

@deffn UnitTypeProperty @code{acp-max} acp
This property is the maximum number of action points that a unit can
save up.  The value @code{-1} means that @code{acp-max} is equal to
@code{acp}.  Extra acp is silently lost.  Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{free-acp} acp
This is the amount by which the acp for some action can exceed the 
difference between the unit's currently available acp and its minimum acp, 
and still allow that action.  By default, no free acp is awarded.
@end deffn

Note that a unit with an acp of 0 and an acp-min of 0 is completely
unintelligent, about like a cow patty.  Cow patties can be useful for
blocking paths, hiding behind, and suchlike, and have the advantage that
once they're in place, you don't have to manage them.  Other units will
have to pick them up and put them down, of course.

@deffn TableUM @code{material-to-act} u m -> n
This table is a minimum amount of @var{m} needed for @var{u} to be able
to act.  The material is not consumed.
@end deffn

@deffn UnitTypeProperty @code{acp-damage-effect} interpolation-list
This property is the effect of a unit's hp on its acp.  The input value
is hp, while the output value is the acp to be added instead of
@code{acp-per-turn}.  This list does not extrapolate.  Defaults to
@code{()}.
@end deffn

@deffn TableUT @code{night-adds-acp} u t -> n
Action points can be added to an unit of type @var{u} if it is night 
at the cell of type @var{t} where it is located. Subtraction can be 
done as a negative addition.@*
NOTE: Currently applies only to cell terrain subtypes.@*
NOTE: This can generally be expected to be only applied at the start of 
a turn.
@end deffn

@deffn TableUT @code{night-multiplies-acp} u t -> .01n
Available action points can be multiplied against a factor @var{n} if 
an unit of type @var{u} is on a cell with terrain @var{t} when it is 
night. Defaults to @code{1.00}.@*
NOTE: Currently applies only to cell terrain subtypes.@*
NOTE: This can generally be expected to be only applied at the start of 
a turn.
@end deffn

@deffn TableUU @code{occupant-adds-acp} u1 u2 -> n
If an occupant of type @var{u2} is in a transport of type @var{u1}, 
then the occupant can confer @var{n} action points upon the transport.@*
NOTE: Presently, the available ACP of an unit is only updated at the 
beginning of turns. So, available ACP will not immediately change upon 
entry of the ACP-affecting occupant. This behvaior may change in the 
near future, so that the effect will be immediate.
@end deffn

@deffn TableUU @code{occupant-multiplies-acp} u1 u2 -> .01n
If an occupant of type @var{u2} is in a transport of type @var{u1}, 
then the occupant may have a multiplicative effect on the 
transport's action points by a factor @var{n}. Defaults to @code{1.00}.@*
NOTE: Presently, the available ACP of an unit is only updated at the 
beginning of turns. So, available ACP will not immediately change upon 
entry of the ACP-affecting occupant. This behvaior may change in the 
near future, so that the effect will be immediate.
@end deffn

@deffn UnitTypeProperty @code{acp-morale-effect} interpolation-list
This property is the effect of morale on acp.  The input value is
morale, and the result value is multiplied with acp, after it has been
modified for night effect, but before modification for temperature.  The
result is divided by 100, so an effect < 100 reduces acp, an effect of
100 has no effect, and an effect > 100 increases acp.  Defaults to
@code{()}.
@end deffn

@deffn UnitTypeProperty @code{acp-per-turn-min} acp
This property sets a lower limit on the effect of occupants, damage, and
other modifiers on the acp to be added at the beginning of the turn.
@end deffn

@deffn UnitTypeProperty @code{acp-per-turn-max} acp
This property sets the upper limit on the effect of occupants and other
modifiers to the acp added at the beginning of the turn.  Defaults to
@code{-1}, which indicates that there is no limit.
@end deffn

@deffn UnitTypeProperty @code{acp-independent} t/f
This property indicates that the unit's actions are to be limited by
materials, rather than by a fixed number of acp each turn.
@end deffn

@node Action Ordering

@subsection Action Ordering

@deffn GlobalVariable @code{use-side-priority} t/f
This variable is @code{true} if the sides may only act one at a time;
otherwise, all sides and units may move simultaneously during a turn.
Defaults to @code{false}.  This variable is also set by the
@code{sequential} variant.
@end deffn

@deffn UnitTypeProperty @code{action-priority} n
This property is the order in which units of this type will act.  Higher
numbers act earlier.  If the difference between the priority of one type
and another is greater than 100, then the earlier-acting units must
finish acting before the later-acting units, otherwise a player can
rearrange the actual acting order as desired.
@end deffn

@node Movement Action

@subsection Movement Action

Movement is the most common sort of action.
This section covers movement over open terrain;
the next section discusses interaction with transports.

The general theory of movement is that a unit not in a transport
crosses its current cell terrain to the edge of the cell,
crosses any border terrain, and then moves into the destination cell,
OR it moves onto connection terrain,
travels along connection terrain to the new cell, and maybe
moves off the connection.
If the unit starts in a transport, then the transport may ferry
the unit over some of the intervening terrain,
possibly as far as the unit's destination.

A unit's basic movement rate is defined by its @dfn{speed},
which is a ratio of the the unit's acp.
A speed of 100% means that the unit can potentially
enter as many cells as it has acp,
while a speed of 20% means that the unit uses at least
5 acp to enter a cell.

Movement can only succeed if several conditions are met:
the unit must be able to cross
the border terrain, the destination must be inside the world (but see below),
it must be able to exist on the terrain of the destination.

@deffn ActionType @code{move} x y z
This is the action that a unit performs to go from its current
location to the cell at @var{x},@var{y} at altitude @var{z}.
The destination must be within the @code{move-range} of the unit.
@end deffn

@deffn UnitTypeProperty @code{acp-to-move} acp
This property is the number of acp a unit uses to do one move action.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{speed} n
This property is the basic multiplier relating acp to the number
of cells that may be entered during a turn.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{speed-damage-effect} interpolation-list
This property is the unit's speed if it is damaged.
The input value is the unit's hp, while the result value is the
unit speed to use instead of @code{speed}.
Defaults to @code{()}.
@end deffn

@deffn TableUU @code{occupant-adds-speed} u1 u2 -> n%
Each value in this table is the amount of speed 
that an occupant @var{u2} adds to transport @var{u1}.
@end deffn

@deffn TableUU @code{occupant-multiplies-speed} u1 u2 -> n%
Each value in this table is the factor an occupant 
@var{u2} multiplies the accumulated speed (including 
additive effects) of a transport @var{u1} by.
Defaults to @code{100%}.
@end deffn

@deffn UnitTypeProperty @code{speed-wind-effect} list
This property is a list that describes the effect of wind on the unit's
speed.  The effect is calculated using a combination of the cells being
left and entered.
The format of the list is
@display
@code{((@var{angle-list} @value{value}) ...)}
@end display
where @i{angle-list} is a single number, list of number, or the symbol
@code{all}, and the @var{value} is either a number, or a list of the
form
@display
@code{((@var{force} @var{number}) (@var{force} @var{number}) ...)}
@end display
For hex areas, the angles are 0 for downwind (same direction), 1, 2, and
3 for directly upwind (opposite direction).  The @i{force} is the wind
force in the cell, and @i{number} is the multiplier for the speed, with
@code{100} having no effect, numbers less than @code{100} decreasing the
unit's speed, and numbers greater than @code{100} increasing it.
Defaults to @code{()}.
@end deffn

@deffn UnitTypeProperty @code{speed-min} mp
This property is the worst-case speed of a unit.
@end deffn

@deffn UnitTypeProperty @code{speed-max} mp
This property is the upper bound on a unit's movement in one turn. (?)
@end deffn

@deffn UnitTypeProperty @code{move-range} n
This property is the maximum distance allowed to the destination cell.
Defaults to @code{1}.
@end deffn

The product of a unit's acp and its speed is its available @dfn{movement points}.
Any move between cells will cost at least one movement point.
Some mp costs may be negative, but the total mp for a move will always
be at least 1.

@deffn TableUT @code{mp-to-leave-terrain} u t -> mp
This table is the mp cost to leave a cell of type @var{t}.
If @var{t} is a border type, this cost is never used.
If @var{t} is a connection type, this cost is the cost of leaving the
connection terrain for the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of leaving the cell.
@end deffn

@deffn TableUT @code{mp-to-enter-terrain} u t -> mp
This table is the mp cost to enter a cell of type @var{t}.
If @var{t} is a border type, this cost is the
cost of crossing the border.
If @var{t} is a connection type, this cost is the cost of entering the
connection terrain from the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of entering the cell.
Defaults to @code{1}.
@end deffn

@deffn TableUT @code{mp-to-traverse} u t -> mp
This table gives the cost to travel along a connection or border of the
given type.  (note that the other costs are irrelevant if unit starts
and ends its movement on the connection).

A special type of move known as a @dfn{border slide} can occur when the
endpoints of a border touch on the start and destination cells.  Sliding
works like normal movement that happens to end up on a nonadjacent cell.
Same rules for permissibility apply.  If the value is negative, then
border sliding is not possible.

Defaults to @code{-1}.
@end deffn

If both enter/traverse/leave and enter/leave movement is possible,
then @i{Xconq} will automatically choose the cheapest alternative.

Each unit type has a range of altitudes within which it normally operates.

@deffn TableUT @code{altitude-min} u t -> n
This table is the minimum altitude possible for each type of unit
on each type of terrain.
@end deffn

@deffn TableUT @code{altitude-max} u t -> n
This table is the maximum altitude possible for each type of unit
on each type of terrain.
@end deffn

@deffn UnitTypeProperty @code{mp-to-leave-world} mp
This property is an additional move cost to leave the world entirely.
To leave, the unit must be within its @code{move-range} of an edge, and
have sufficient mp to move into the terrain in the edge cell designated
as the destination of the move.  If the value is @code{-1}, then the
unit may never leave.  Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{free-mp} mp
This property is the amount by which the move points can ``go into the
red'' and still allow one more move.
@end deffn

ZOC is exerted only over units out in the open, has no effect on
occupants, unless they leave their transport.  Occupants can themselves
exert a ZOC, if @code{occupant-can-fight} is true.  ZOC applies to all
units on a hostile side.

@deffn TableUU @code{zoc-range} u1 u2 -> dist
This table is the maximum distance at which type @var{u1} exerts a ZOC
over type @var{u2}.  A value of @code{0} means that the unit controls
only its own cell, and a value of @code{-1} means that the unit does not
exert a ZOC at all.  Defaults to @code{0}.
@end deffn

@deffn TableUT @code{zoc-into-terrain} u t -> t/f
This table is @code{true} if the unit exerts its ZOC into terrain
@var{t}.  Defaults to @code{true}.
@end deffn

@deffn TableUT @code{zoc-from-terrain-effect} u t -> n
Defaults to @code{100}.
@end deffn

@deffn TableUU @code{mp-to-enter-zoc} u1 u2 -> mp
This table specifies extra movement points needed by a unit of type @var{u1}
to enter the ZOC of a unit of type @var{u2}.
@code{-1} prevents entry entirely.  Defaults to @code{-1}.
@end deffn

@deffn TableUU @code{mp-to-leave-zoc} u1 u2 -> mp
This table specifies extra movement points needed by a unit of type @var{u1}
to leave the ZOC of a unit of type @var{u2}.
@code{-1} should prevent departure entirely, but that is not currently
implemented; set a large value instead to achieve the same effect.  Defaults
to @code{0}.
@end deffn

@deffn TableUU @code{mp-to-traverse-zoc} u1 u2 -> mp
This table specifies extra movement points needed by a unit of type @var{u1}
to move within the ZOC of a unit of type @var{u2}.  @code{-1} should prevent
traversal entirely, but that is not currently implemented; set a large value
instead to achieve the same effect.  Defaults to @code{0}.
@end deffn

If multiple units exert a ZOC into the same cell, then the mp cost
adjustment for all ZOCs is the maximum of the different ZOC costs.

@deffn TableUU @code{mp-to-enter-own} u1 u2 -> mp
This table specifies extra movement points needed to enter a unit's own
cell, irrespective of ZOC.  @code{-1} prevents entry entirely.  Defaults
to @code{-1}.
@end deffn

Units may use up some of their materials when they move.  Consumption
happens after the move action, and only for successful moves.

@deffn TableUM @code{material-to-move} u m -> n
This table is the amount of each material that a unit of type @var{u}
must have in order to be able to move.
@end deffn

@deffn TableUM @code{consumption-per-move} u m -> n
This table is the amount of each material used by a unit to do one move
action.  The amount taken is independent of terrain.  If the unit has
less than the required amount of any of these materials, it is
immobilized until it gets more (this is tested before each move action;
note that this does not affect any other action, including entering and
leaving transports).
@end deffn

@deffn TableUT @code{control-range} u t -> dist
This table is the distance out to which a unit's entry into a cell
changes control of the surrounding terrain.  A distance of 0 means that
the unit only changes control for its own cell, while a distance of -1
means that the unit does not affect control.  Defaults to @code{-1}.

At present, the maximum value for this is 0 (in other words, a unit
cannot change control in adjacent cells).
@end deffn

@node Entry Action

@subsection Entry Action

Units can be inside other units, and have units inside them, in a
tree-like fashion.  There is no limit on the depth of the tree, but most
occupant-transport relationships have other limits.

@deffn ActionType @code{enter} unit
This is the action to enter the given @var{unit}.
@end deffn

@deffn UnitTypeProperty @code{acp-to-enter-unit} acp
This property is the number of acp a unit uses to do one entry action.
Defaults to @code{1}.
@end deffn

@deffn TableUU @code{can-enter-independent} u1 u2 -> t/f
This table is true if a unit @var{u1} can enter an independent unit
@var{u2}.  Defaults to @code{false}.@*
NOTE: The ability to enter an independent unit implies a form of trust 
between the independent unit, @var{u2}, and its non-independent occupant, 
@var{u1}. So, for example, @var{u1} can take supplies from @var{u2}.
@end deffn

Entering and leaving incur mp costs as does movment, but units with a
speed of 0 may enter and leave transports.

@deffn TableUU @code{mp-to-enter-unit} u1 u2 -> n
This table is the extra movement points required for @var{u1} to enter
the transport @var{u2}.
@end deffn

@deffn TableUU @code{mp-to-leave-unit} u1 u2 -> n
Similar to entry cost.
@end deffn

@deffn TableUU @code{ferry-on-entry} u1 u2 -> ferry-type
@end deffn
@deffn TableUU @code{ferry-on-departure} u1 u2 -> ferry-type
This table specifies how much intervening terrain the unit @var{u2}
entering or leaving transport @var{u1} will have to cross on its own
(and thus incur the terrain's mp costs and limitations).  Defaults to
@code{over-border}.
@end deffn

@deffn GlobalConstant @code{over-nothing}
This constant indicates no ferrying, occupant must pay all costs to go
to destination cell.
@end deffn

@deffn GlobalConstant @code{over-own}
This constant indicates that the transport ferries over terrain of its
own cell.
@end deffn

@deffn GlobalConstant @code{over-border}
This constant indicates that the transport ferries over any border
terrain also.
@end deffn

@deffn GlobalConstant @code{over-all}
This constant indicates that the transport ferries to destination cell,
effectively putting occupant on middle of cell, on connection terrain if
necessary.
@end deffn

@node Develop Action

@subsection Develop Action

Development is an action performed by a unit with the sole effect of
increasing its side's tech level.  Development cannot be performed by
independent units.

@deffn ActionType @code{develop} u
This is the action of developing the unit type @var{u}.  If the action
is valid, then the tech level of the side will increase.  Unit types
with any tech crossover will also have their tech levels adjusted.
@end deffn

@deffn UnitTypeProperty @code{acp-to-develop} acp
This property is the number of action points used up by one develop
action.  Defaults to @code{0}, which disallows development.
@end deffn

@deffn TableUU @code{tech-per-develop} u1 u2 -> .01n
This table is the gain in tech level resulting from a develop action,
expressed as 1/100 of a level.  This value is stochastic.
@end deffn

@deffn UnitTypeProperty @code{tech-per-turn-max} tl
This property is a ceiling on the total gain of tech level possible in
one turn for each side and this unit type.  Defaults to @code{9999}.
@end deffn

@deffn TableUM @code{material-to-develop} u m -> n
This table is the amount of each material a unit must have in order to
do any development.
@end deffn


@node Toolup Action

@subsection Toolup Action

There are several stages in the construction of a unit: tooling up,
creation, and completion.  Tooling up is where the building unit
prepares to build, creation is the step where the new unit comes into
existence, and completion is where the new unit is brought up to being
operational.

For the player, this is mostly automatic; if tooling must be done first,
a user command to build will generate the appropriate actions.

Once the technology has been achieved, a unit that intends to construct
other units may need to tool up.  This is expressed as @dfn{tool points}
or @dfn{tp}.  Tool points start at zero, can be increased by tooling
actions, and may gradually decline (representing wear and tear on the
equipment).

@deffn ActionType @code{toolup} u
This is the action of tooling up to build a unit of type @code{u}.  The
result is an increase in the tp for the acting unit.
@end deffn

@deffn TableUU @code{can-toolup-for} u1 u2 -> t/f
If true, then an unit of type @var{u1} can toolup to construct an unit 
of type @var{u2}.  Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{acp-to-toolup} acp
This property gives the number of acp needed to do a toolup action.
@end deffn

@deffn TableUM @code{material-to-toolup} u1 m -> n
The amount of a material type @var{m} required to be on hand, but not 
necessarily consumed, by an unit of type @var{u1} tooling up for any 
construction task.
@end deffn

@deffn TableUM @code{consumption-per-tooledup} u2 m -> n
The amount of a material type @var{m} that is consumed by one toolup action 
by the unit doing the tooling up, but based on, @var{u2}, 
the type of unit being tooled up for.
@end deffn

@deffn TableUM @code{consumption-per-tooledup} u1 m -> n
The amount of a material type @var{m} that is consumed by one toolup action 
by the unit doing the tooling up, based on its type, @var{u1}.
@end deffn

@deffn TableUM @code{consumption-per-tp} u1 m -> n
The amount of a material type @var{m} that is consumed by @code{1} TP worth 
of tooling by the unit doing the tooling up, based on its type, @var{u1}.
@end deffn

@deffn TableUU @code{tp-per-toolup} u1 u2 -> tp
This table is the number of tp gained by one tooling action.
@end deffn

@deffn TableUU @code{tp-to-build} u1 u2 -> tp
This table is the number of toolup points needed before a unit of type
@var{u1} can create or build a unit of type @var{u2}.
@end deffn

@deffn TableUU @code{tp-max} u1 u2 -> tp
This table is the maximum possible tooling.
@end deffn

@deffn TableUU @code{tp-attrition} u1 u2 -> tp
This table is the number of .01 tool points automatically lost at the
end of each turn.
@end deffn

@deffn TableUU @code{tp-crossover} u1 u2 -> n%
This table is the number of tool points for @var{u2} that is guaranteed
to exist, expressed as a percentage of the tool points for @var{u1}.

For instance, if @code{tp-crossover} is 80, and a unit's tool points for
@var{u1} is 10 out of a max of 20, and the max for @var{u2} is also 20,
then the unit will have tool points for @var{u2} at least 8.
@end deffn

@node Unit Creation Actions

@subsection Unit Creation Actions

When a constructing unit is tooled up, the create action creates a unit
immediately and puts it in its designated location, whether inside the
unit doing the building or somewhere nearby.  This new unit, however, is
incomplete, representing the keel of the ship or the surveyor's
lines for an airstrip.  Incomplete units are thus basically skeletons,
with some unit characteristics, but unable to move or act in any way.
They also cannot have any occupants, unless the occupants are of a type
that can complete the unit.  Those occupants do not derive any protection
or other advantages from occupying the incomplete unit, and they are not
affected by the @code{occupant-can-build} limitation.

@deffn ActionType @code{create-in} u unit
This action creates a new unit of type @var{u} occupying the given unit
@var{unit}.  The unit @var{unit} must have room for the new unit.
@end deffn

@deffn ActionType @code{create-at} u x y z
This action creates a new unit of type @var{u} in the open at
@var{x},@var{y},@var{z}.  The cell must have room for this new unit.
@end deffn

@deffn TableUU @code{can-create} u1 u2 -> t/f
If an unit of type @var{u1} can create an unit of type @var{u2}, 
then this it true.  Defaults to @code{false}.
@end deffn

@deffn TableUU @code{create-as-build} u1 u2 -> t/f
If you intend for creation to cost and construct at the same rate as 
building, then set this to true, and look at the @code{build} action 
documentation.  Defaults to @code{false}.
@end deffn

@deffn TableUU @code{acp-to-create} u1 u2 -> acp
This table is the acp used by a unit of type @var{u1} to create a a unit
of type @var{u2}. 
@end deffn

@deffn TableUU @code{create-range} u1 u2 -> dist
This table is the maximum distance at which a unit of type @var{u1} can
create a unit of type @var{u2}.
@end deffn

@deffn TableUU @code{cp-on-creation} u1 u2 -> cp
This table is the completeness of a unit of type @var{u2} when created
by a unit of type @var{u1}.  Defaults to @code{1}.
@end deffn

@deffn TableUM @code{material-to-create} u1 m -> n
This table is the total amount of a material type @var{m} required by 
a unit of type @var{u1} to create anything. This material is not 
consumed.
@end deffn

@deffn TableUM @code{consumption-on-creation} u2 m -> n
This table is the amount of a material type @var{m} consumed to create a
unit of type @var{u2}.
@end deffn

@deffn TableUM @code{consumption-per-create} u1 m -> n
This is the amount of a material type @var{m} consumed by an unit of type 
@var{u1} while creating any other unit.
This may be negative, in which case, the creator gains @var{m}.
@end deffn

@deffn TableUM @code{takes-from-treasury} u m -> t/f
This table is @code{true} if a constructing unit of type @var{u} can take
material @var{m} if its own supply is insufficient to meet the
@code{consumption-on-creation} or @code{consumption-per-build} (see
below) requirements.  It should be noted that, unless the storage 
capacity for the material is @code{0}, then the amount taken from the 
treasury is only sufficient to close the deficit between the amount of 
@var{m} an unit of type @var{u} has on hand and the amount of @var{m} that 
@var{u} can store.  If @var{u} has a @code{0} storage capacity for @var{m}, 
then an unlimited amount of @var{m} can be used from the treasury.
@end deffn

@deffn TableUM @code{treasury-gain-per-create} u m -> n
This is the amount of @var{m} gained when @var{u} is created.  This material 
is added to the treasury of the side that created @var{u}.  This is not yet
implemented.
@end deffn

@deffn TableUM @code{treasury-loss-per-create} u m -> n
This is the amount of @var{m} lost when @var{u} is created.  This material 
is taken from the treasury of the side that created @var{u}.  This is not yet
implemented.
@end deffn

@deffn TableUM @code{supply-on-creation} u m -> n
This table is the amount of supply of each material type @var{m} to give
a newly created unit of type @var{u}.  This supply is newly generated,
does not come from anywhere else.  (Note that players could cheat by
creating units, taking their supply, and never completing them.)
@end deffn

@deffn TableUU @code{morale-on-creation} u1 u2 -> n
This table is the ratio of morale of a unit of type @var{u2} to the
morale of its creator @var{u1}, with 100 meaning that the new unit has
the same morale as its creator.  Defaults to @code{100}.
@end deffn

@deffn TableUU @code{opinions-on-creation} u1 u2 -> n
This table is the ratio of the opinions of a unit of type @var{u2} to
the opinions of its creator @var{u1}, with 100 meaning that the new unit
has the same opinions as its creator.  Defaults to @code{100}.
@end deffn

@node Unit Completion Action

@subsection Unit Completion Action

Once an incomplete unit has been created, other units can help to
complete it.

@deffn ActionType @code{build} unit
This action adds to the completeness of @var{unit}.  If the unit becomes
complete, it will be given its initial supply, acp, name, etc.
@end deffn

@deffn TableUU @code{can-build} u1 u2 -> t/f
If an unit of type @var{u1} can build upon an unit of type @var{u2}, 
then this it true.  Defaults to @code{false}.
@end deffn

@deffn TableUU @code{acp-to-build} u1 u2 -> acp
This table is the acp used up by one build action by a unit of type
@var{u1} when buiding a unit of type @var{u2}.
@end deffn

@deffn TableUU @code{cp-per-build} u1 u2 -> cp
This table is the amount of completeness of a unit of type @var{u2}
added by each build action performed by a unit of type @var{u1}.
If @code{0}, then @var{u1} cannot contribute to completing @var{u2}.
Defaults to @code{1}.
@end deffn

@deffn TableUM @code{material-to-build} u1 m -> n
This table is the amount of any material type @var{m} that @var{u1}
must have in order to build anything at all.  This material is not 
consumed.
@end deffn

@deffn TableUM @code{consumption-per-build} u1 m -> n
This is the amount of material type @var{m} that is consumed by the 
building unit type @var{u1} while building any unit type.
This may be negative, in which case, @var{m} will be gained by the builder.
@end deffn

@deffn TableUM @code{consumption-per-built} u2 m -> n
This table is the amount of each material type @var{m} consumed by
the builder performing a single build action on a unit of type @var{u2}.  
This may be negative, in which case, @var{m} will be gained by the builder.
This is compatible with the @code{unit-consumption-per-cp} table.
@end deffn

@deffn TableUM @code{unit-consumption-per-cp} u2 m -> n
This table is the amount of each material type @var{m} consumed by
the builder adding 1 CP to a unit of type @var{u2}.  
This may be negative, in which case, @var{m} will be gained by the builder.
This is compatible with the @code{consumption-per-built} table.
@end deffn

@deffn TableUU @code{build-range} u1 u2 -> dist
This table is the maximum distance allowed between a unit of type
@var{u1} and the incomplete unit of type @var{u2} it is working on.
Defaults to @code{0}, which requires the two units to be in the same
cell.
@end deffn

At a given point, incomplete units can make progress towards completion
on their own.  This is automatic because incomplete units are unable to
act, and occurs at a constant specified rate.  Automatic completion
always occurs, even if other units are doing build actions at the same
time.  The incomplete unit must have any necessary supplies.

@deffn UnitTypeProperty @code{cp-to-self-build} cp
This property is the minimum completeness of the unit necessary before
it can work on itself.
@end deffn

@deffn UnitTypeProperty @code{cp-per-self-build} cp
This property is the completeness added each turn when a unit works on
itself.
@end deffn

@deffn TableUM @code{supply-on-completion} u m -> n
This table is the minimum amount of supply of each material type @var{m}
guaranteed to a newly completed unit of type @var{u}.  If not already
available to the unit, it will be newly generated.
@end deffn

@deffn UnitTypeProperty @code{cp-attrition} .01n%
This property is the chance that an incomplete unit will lose cp.  If
the unit loses all of its cp, it vanishes.
@end deffn

Cancelled build tasks can result in the disbanding of the incomplete
unit and recovery of the cp and materials in the unfinished unit.

@deffn GlobalVariable @code{disband-unfinished-units} t/f
This variable is true if incomplete units not being worked on are
automatically disbanded.
@end deffn

@deffn GlobalVariable @code{salvage-unfinished-cps} t/f
This is true if the disbanded incomplete unit returns its completeness
points.
@end deffn

@deffn UnitProperty @code{cpstash} n
This property records unused completeness points.
@end deffn

@deffn TableUU @code{builder-can-reuse-cp} u1 u2 -> t/f
This is true if a builder of type @var{u1} can use its cpstash to add to
the completeness of a unit of type @var{u2}.
@end deffn

@deffn GlobalVariable @code{salvage-unfinished-materials} t/f
This is true if the disbanded incomplete unit returns the materials used
while building it.
@end deffn

A creator which creates complete units or a builder which completes an 
incomplete unit may be absorbed by the completed unit. This kind of 
behavior is often useful for colonizer games, when one does not wish for 
the colonizer to continue to be around after it has colonized.

@deffn TableUU @code{constructor-absorbed-by} u1 u2 -> t/f
If true, then @code{hp-per-garrison} HP are taken out of the constructing 
unit when it completes an unit.  Note that this is not a guarantee that 
the constructor will vanish; its HP must go to 0 for that to happen.
Defaults to @code{false}.
@end deffn

An unit may automatically be given occupants upon completion.

@deffn TableUU @code{complete-occs-on-completion} u1 u2 -> .01n
The number of complete occupants of type @var{u2} placed inside an 
unit of type @var{u1} upon its completion.
The part to left of the decimal is the guaranteed number, 
and the part to right is the probability of one additional occ.
@end deffn

@deffn TableUU @code{incomplete-occs-on-completion} u1 u2 -> .01n
The number of incomplete occupants of type @var{u2} placed inside an 
unit of type @var{u1} upon its completion.
The part to left of the decimal is the guaranteed number, 
and the part to right is the probability of one additional occ.
@end deffn

@deffn TableUU @code{alt-complete-occs-on-completion} u1 u2 -> n
A supplementary (or alternative) number of complete occupants of type 
@var{u2} placed inside an unit of type @var{u1} upon its completion.
This is a Type 1 dice table. 
Dice rolls less than @code{0} are treated as @code{0}.
Note that this is a supplementary table, and so is additive with 
@code{complete-occs-on-completion} and not contradictory to it.
@end deffn

@deffn TableUU @code{alt-incomplete-occs-on-completion} u1 u2 -> n
A supplementary (or alternative) number of incomplete occupants of type 
@var{u2} placed inside an unit of type @var{u1} upon its completion.
This is a Type 1 dice table. 
Dice rolls less than @code{0} are treated as @code{0}.
Note that this is a supplementary table, and so is additive with 
@code{incomplete-occs-on-completion} and not contradictory to it.
@end deffn

@node Repair Action

@subsection Repair Action

Units can restore their own and each other's hp by doing repairs.
Repair requires a repair action.

@deffn ActionType @code{repair} unit
This is the action of repairing the given @var{unit}.
@end deffn

@deffn TableUU @code{can-repair} u1 u2 -> t/f
True, if an unit of type @var{u1} can repair an unit of type @var{u2}.
Defaults to @code{false}.
@end deffn

@deffn TableUU @code{acp-to-repair} u1 u2 -> acp
The number of action points used up by a unit of type @var{u1}
doing one repair action on a unit of type @var{u2}.
@end deffn

@deffn TableUU @code{hp-per-repair} u1 u2 -> .01hp
This table is the hundredths of a hp that a single repair action
by a unit of type @var{u1} restores to a unit of type @var{u2}.
The fraction of this over 100 is added to hp directly,
while the < 100 fraction is added probabilistically.
(For example, a value of @code{160}, or @code{1.60}, means that 1 hp 
will be added for each action, and there is a 60% chance for an additional 
1 hp to be added as well.)
@end deffn

Materials may be needed and/or consumed during repair.

@deffn TableUM @code{material-to-repair} u1 m -> n
This table is the amount of each material type @var{m} needed
for one repair action.
@end deffn

@deffn TableUM @code{consumption-per-repair} u1 m -> n
This table is the amount of each material type @var{m} 
used up by a repair action performed by the repairer unit of type @var{u1}.
@end deffn

@deffn TableUM @code{consumption-per-repaired} u2 m -> n
This table is the amount of each material type @var{m} 
used up by a repair action performed on the repairee unit of type @var{u2}.
@end deffn

The following are not really part of the repair action definition, since
they occur automatically, but they share many of the tables above.

@deffn TableUU @code{auto-repair} u1 u2 -> .01hp
This table is the amount of repair (in 1/100 hp) that @var{u1} will do
on any unit of type @var{u2} within range (@code{auto-repair-range}).
As with @code{hp-per-repair},
the < 1.00 part is average, and > 1.00 is guaranteed.
Material requirements and usage are as for repair actions.
Defaults to @code{0}, which disallows auto-repair.
@end deffn

@deffn TableUU @code{auto-repair-range} u1 u2 -> dist
This table is the distance out to which @var{u1} will auto-repair
any damaged @var{u2}.  A value of @code{0} requires the two units
to be in the same cell, while a value of @code{-1} means that
@var{u2} must be either an occupant or transport of @var{u1}.
@end deffn

@deffn UnitTypeProperty @code{hp-recovery} .01hp
This property is the number of 1/100 hp recovered per turn.  Recovery
happens automatically at the end of each turn.  The amount @i{n} / 100
is recovered automatically each turn, while @i{n} mod 100 is the percent
chance of recovering an additional 1 hit point.
@end deffn

@deffn UnitTypeProperty @code{hp-to-recover} hp
This property is the minimum number of hp that the unit must have for hp
recovery to work.
@end deffn

@node Material Production Action

@subsection Material Production Action

Units can produce materials by explicit action.

@deffn ActionType @code{produce} m
This action results in a quantity of material @var{m}
coming into existence.
@end deffn

@deffn TableUM @code{acp-to-produce} u m -> acp
This table is the acp used up by one @code{produce} action.
@end deffn

@deffn TableUM @code{material-per-production} u m -> n
This table is the amount of material produced by @var{u}
when acting to produce type @var{m}.
@end deffn

@deffn TableUM @code{material-to-produce} u m -> n
This table is the amount of each material a unit must have
in order to produce any material.  This material is not
consumed by the production action.
@end deffn

@node Material Extraction Action

@subsection Material Extraction Action

Units can extract materials from the terrain or from nearby units.

@deffn ActionType @code{extract} x y m n
This action results in the transfer of a quantity @var{n} of material
@var{m} from the cell at @var{x},@var{y}.
@end deffn

@deffn TableUM @code{acp-to-extract} u m -> acp
This table is the acp used up by one action to extract material
of type @var{m}.
@end deffn

@deffn TableUM @code{material-to-extract} u m -> acp
This table is the material required to do any extraction actions.
@end deffn

@node Material Transfer Action

@subsection Material Transfer Action

Although most movement of materials between units happens automatically
(see backdrop economy description), players can also do it explicitly.
Players can both take materials from other units, and give a unit's
materials to others.

@deffn ActionType @code{transfer} unit m n
This is the action of transferring supply to the given unit @var{unit}.
The desired amount is @var{n}; if @var{m} is a valid material type, then
only that type will be transferred, otherwise the action will transfer
all types of materials possible.  The actual transfer amounts may be
less than @var{n}.
@end deffn

@deffn TableUM @code{acp-to-unload} u1 m -> acp
@end deffn
@deffn TableUM @code{acp-to-load} u1 m -> acp
These tables are the number of action points used up by one material
transfer action from @var{u1} to @var{u2}.  The amount is independent of
the material type being transferred.  If either value is @code{0}, then
the material cannot be transferred.
@end deffn

@deffn TableUM @code{unload-max} u1 m -> n
@end deffn
@deffn TableUM @code{load-max} u2 m -> n
These two tables determine how much of material @var{m} can be
transferred out of a unit of type @var{u1} and into one of type @var{u2}
in one transfer action.  The actual quantity transferred by the action
is the minimum of these two values.  A value of @code{0} disallows
manual transfer.  Both default to @code{-1}, which allows any amount to
be transferred.
@end deffn

@node Side Change Action

@subsection Side Change Action

@deffn ActionType @code{change-side} side
This is the action of changing the unit's side to @var{side}.  The
@var{side} can be any allowable side, and the unit may be any unit
controlled by the actor's side.
@end deffn

@deffn UnitTypeProperty @code{acp-to-change-side} acp
If the value of this property is greater than 0, then this type of unit
can be ordered to change to another given side.  If the unit is not a
type that can act, then the side change happens immediately, instead of
as an action, and no acp cost is incurred.  The type must also be
allowed to be on the new side.
@end deffn

@node Disband Action

@subsection Disband Action

Disbanding is the voluntary and controlled destruction of a unit,
performed by the unit itself or another unit.  A disbanded unit always
vanishes, rather than changing to its @code{wrecked-type}.

@deffn ActionType @code{disband} unit
This is the action of removing hp from @var{unit}.  The unit will vanish
if all its hit points are gone.
@end deffn

@deffn UnitTypeProperty @code{acp-to-disband} acp
If the value of this property is greater than 0, then this is the acp
that will be used up to do one disband action.  If the unit is not a
type that can act, then the disband happens immediately, instead of as
an action, and no acp cost is incurred.
@end deffn

@deffn UnitTypeProperty @code{hp-per-disband} hp
This table is the number of hp lost in a disband action.  Defaults to
@code{0}, which disallows disbanding.
@end deffn

A disbanded unit can be scavenged for materials.

@deffn TableUM @code{supply-per-disband} u m -> n%
This table is the percentage of the unit's supply that is recovered from
a single disband action.  If the value is zero, then the unit's supply
will not be recovered by the disbanding process, and be lost
permanently.  If any supply remains when the unit's hp is 0, then that
supply will be lost also.  Defaults to @code{100}, which means that the
entire supply will be recovered on the first disband action.
@end deffn

Note that if an essential supply is 100% recovered before the unit is
completely disbanded, then it may die from starvation first.  A
partly-disbanded unit may still acquire supply from nearby units, via
the backdrop economy.

@deffn TableUM @code{recycleable-material} u m -> n
This table is the quantity of each type of material that becomes
available when a unit is completely disbanded.  The materials go to
transports, occupants, and nearby units, in that order.  Any materials
exceeding capacities of these units will be discarded.  These materials
become available only when the unit vanishes.
@end deffn

@node Type Change Action

@subsection Type Change Action

Units may change their type. This can be set up to happen automatically, or only with manual intervention from the player.

@deffn ActionType @code{change-type} u
This action changes the type of the actee unit to the type @var{u}.
Upon changing, the relationships of the unit with the world and
with other units will be recalculated; occupants that can no longer
stay in the unit will be ejected or disappear.  The unit itself
may vanish or wreck, if it is in the open on a terrain type that will
cause units of the new type to vanish or wreck.
@end deffn

@deffn TableUU @code{can-change-type-to} u1 u2 -> t/f
True, if a unit of type @var{u1} is allowed to be change its type to 
@var{u2}. If not allowed, then false. The default is @code{false}.
Not relevant for automatic change-type actions.
@end deffn

@deffn UnitTypeProperty @code{auto-upgrade-to} u
Automatically upgrade a unit to unit type @var{u} at the beginning of 
a turn if the change-type criteria are met for this upgrade. Defaults 
to @code{nonutype}.
@end deffn

@deffn TableUU @code{acp-to-change-type} u1 u2 -> acp
This table is the number of acp needed to change a unit of
type @var{u1} into a unit of type @var{u2}.
If the value is 0, then the change is never possible.
@end deffn

@deffn TableUU @code{occupants-to-change-type} u1 u2 -> n
The number of occupants of unit type @var{u2} required to change a 
unit of type @var{u1} into another unit type.
@end deffn

@deffn TableUA @code{advance-to-change-type} u a -> t/f
Indicate whether an advance type @var{a} is needed by a unit of type 
@var{u} to change type. The default is @code{false}.
@end deffn

@deffn TableUM @code{material-to-change-type} u m -> n
This is the amount of each material type @var{m} required for an 
unit of type @var{u} to change type.
@end deffn

@deffn TableUU @code{cxp-to-change-type} u1 u2 -> n
Minimum combat experience for a unit of type @var{u1} to change to 
unit type @var{u2}.
@end deffn

@deffn TableUU @code{size-to-change-type} u1 u2 -> n
Minimum size for a unit of type @var{u1} to change to unit type 
@var{u2}.
@end deffn

@deffn TableUU @code{turn-to-change-type} u1 u2 -> n
Minimum turn for a unit of type @var{u1} to change to unit type 
@var{u2}.
@end deffn

@node Combat Actions

@subsection Combat Actions

@i{Xconq} combat is somewhat abstract; the attacking player decides what sort
of attack to mount and perhaps when to retreat, but all else happens
automatically.

The attacker/defender distinction applies only to a single action.

@deffn ActionType @code{attack} unit commit
This action is a direct attack on the given @var{unit}, at a commitment
level of @var{commit}.  The @var{unit} must be known to the attacking
unit's side.
@end deffn

@deffn ActionType @code{overrun} x y z commit
This action is a combined attack/capture/move action.  The basic theory
of an overrun is that the actor will attack, capture, or co-occupy the
cell at @var{x},@var{y}, elevation @code{z}, with a commitment of
@var{commit}.  The exact effects depend on the types and sides of units
in the destination.
@end deffn

[The commitment levels are currently ignored.]

@deffn TableUU @code{acp-to-attack} u1 u2 -> acp
This table is the number of action points used up by a unit @var{u1}
when attacking a unit of type @var{u2}.  If the value is 0, attack is
not allowed.  Defaults to @code{1}.
@end deffn

@deffn TableUU @code{acp-to-defend} u1 u2 -> acp
This table is the number of action points used up by a unit @var{u1}
when defending against an attack by a unit of type @var{u2}.  If the
value is 0, attack is not allowed.  Defaults to @code{1}.
@end deffn

@deffn TableUU @code{attack-range-min} u1 u2 -> dist
This table is the minimum distance at which a unit can attack another.
A value of 0 means that units in the same cell can fight.
@end deffn

@deffn TableUU @code{attack-range} u1 u2 -> dist
This table is the maximum distance at which a unit can attack another.
A value of 1 means that units in adjacent cells may fight, while a value
of 0 means that only units in the same cell may fight.  Defaults to
@code{1}.
@end deffn

@deffn GlobalVariable @code{combat-model} n
This variable specifies the algorithm used for combat resolution.

A value of 0 specifies single attack/counterattack with odds determined
by the @code{hit-chance} table.

A value of 1 specifies multi-round combat with odds computed from attack
and defend strength, combat continuing until a participant is destroyed.
Combat model one is not fully described in this document.  For further
details beyond those here, look at the comments in table.def in the
xconq source code, at variables such as occupant-affects-attack,
occupant-affects-defense, transport-affects-attack,
transport-affects-defense, terrain-affects-attack,
terrain-affects-defense, neighbour-affects-attack, and
neighbour-affects-defense.  Plus of course the source code where the
variables are consulted (for example model_1_combat in kernel/combat.c).
@end deffn

One round of combat consists of an attack, a reaction, and a calculation
of effects.

The defender's reaction is completely automatic, and occurs as part of
the combat round.  The defender's side does not get a chance to decide
what to do until the next round, although doctrine may constrain the set
of reactions.

@deffn TableUU @code{surrender-chance-per-attack} u1 u2 -> n%
This table is the chance that @var{u2} will surrender to @var{u1}
immediately upon being attacked.
@end deffn

@deffn TableUU @code{withdraw-chance-per-attack} u1 u2 -> n%
This table is the chance that @var{u2} will retreat from @var{u1}
immediately upon being attacked.
@end deffn

@deffn TableUU @code{acp-for-retreat} u1 u2 -> acp
This table is the extra acp that @var{u2} can get in order to make a
withdrawal possible.
@end deffn

@deffn TableUU @code{counterattack} u1 u2 -> n
This table is the strength of a defender's reaction to an attack.  If 0,
the defender does not counterattack; if 100, the defender counterattacks
at the same level as if it attacked normally.  Defaults to @code{100}.
@end deffn

In an overrun action, if all the defending units are destroyed, the
attacker has sufficient acp and mp, and the destination is safe to
enter, then the attacker can move into the defenders' cell.

Firing is a kind of attack that can take place at a distance, involves
no commitment or counterattack, and for which the type of ammo may be
selected.

@deffn ActionType @code{fire-at} unit m
This is the action of firing at a given @var{unit}.  If @var{m} is a
valid material type, then that type will be used as ammo, otherwise all
available types will be used together.
@end deffn

@deffn ActionType @code{fire-into} x y z m
This is the action of firing into the cell at @var{x},@var{y}.  If @var{z} is
a valid altitude, then the fire will be concentrated on units at that
elevation.  If @var{m} is a valid material type, then that type will be
used as ammo, otherwise all available types will be used together.
@end deffn

@deffn UnitTypeProperty @code{acp-to-fire} acp
If this property is greater than 0, this type may attack by firing.
@end deffn

@deffn TableUU @code{acp-to-be-fired-on} u1 u2 -> acp
This table is the acp lost when a unit is being fired upon.  Defaults to
@code{1}.
@end deffn

@deffn UnitTypeProperty @code{range} dist
This property is the maximum distance in cells to which a unit can fire.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{range-min} dist
This property is the minimum distance in cells to which a unit can fire.
@end deffn

@deffn UnitTypeProperty @code{fire-angle-max} n%
This property is the highest angle at which a unit may fire, expressed
as a percentage of 45 degrees.  The default of @code{0} means that the
unit's fire has a flat trajectory and that the target must be on an
unobstructed straight line from the firing unit.  For values greater
than 0, this angle is used to calculate whether the parabolic trajectory
clears all intervening terrain.
@end deffn

Units can be on @dfn{overwatch}. Overwatch is a state where an unit will 
automatically fire at other units it sees moving.

@deffn TableUU @code{zoo-range} u1 u2 n
The maximum range for an unit of type @var{u1} to extend a zone-of-overwatch 
(ZOO) for units of type @var{u2}. If the fire @code{range} for @var{u1} is 
less than @var{n}, then that will be used instead. Defaults to @code{-1}.
@end deffn

@deffn TableUU @code{zoo-range-min} u1 u2 n
The minimum range for an unit of type @var{u1} to extend a ZOO for units of 
type @var{u2}. If the fire @code{range-min} for @var{u1} is greater than 
@var{n}, then that will be used instead. Defaults to @code{-1}.
@end deffn

@deffn TableUU @code{acp-for-overwatch} u1 u2 n
The amount of additional ACP that an unit of type @var{u1} receives in order 
to perform an overwatch firing against units of type @var{u2}.
@end deffn

@deffn TableUT @code{weapon-height} u t -> elev
This property is the effective height of a unit's weapons when in the
given terrain.
@end deffn

Both attack and fire combat calculate hits and damage in a similar way,
although they may use different tables.

@deffn TableUU @code{hit-chance} u1 u2 -> n%
This table is the basic chance that a unit of type @var{u1} will
actually hit a unit of type @var{u2}.  If the hit chance is @code{0},
then the unit may never attack a unit of that type.
@end deffn

@deffn TableUU @code{fire-hit-chance} u1 u2 -> n%
This table is the basic chance that fire from a unit of type @var{u1}
will actually hit a unit of type @var{u2}.  If the hit chance is
@code{0}, then the unit may never fire at a unit of that type.  If the
value is @code{-1}, then the value of this is the same as the value of
@code{hit-chance}.  Defaults to @code{-1}.
@end deffn

@deffn TableUT @code{attack-terrain-effect} u1 t -> n%
@end deffn
@deffn TableUT @code{defend-terrain-effect} u2 t -> n%
@end deffn
@deffn TableUT @code{fire-attack-terrain-effect} u1 t -> n%
@end deffn
@deffn TableUT @code{fire-defend-terrain-effect} u2 t -> n%
These tables specify the effect of attacker's and defender's respective
terrains on @code{hit-chance} or @code{fire-hit-chance}.  These chances
are multiplied with the basic hit chance.  Default to @code{100}.
@end deffn

@deffn TableUU @code{hit-cxp-effect} u1 u2 -> n
This table is the effect of combat experience on hit chance.  Its value
is interpolated according to actual experience (@var{n} is the effect
when @var{u1} is at its maximum possible experience), then multiplied
with the hit chance.  Defaults to @code{100}.
@end deffn

The effectiveness of fire may be less at long ranges.  If the range to
the target is greater than @code{hit-falloff-range}, the chance of
hitting it will be reduced by the interpolation between the short-range
chance and that chance multiplied by the value of
@code{hit-at-max-range-effect}.  For example, if a unit's range is 4,
its hit falloff range is 1, the basic hit chance is 60%, and the max
range effect is 50%, then its hit chance at range 2 is 50%, at range 3
is 40%, and at range 4 is 30%.

@deffn UnitTypeProperty @code{hit-falloff-range} n
This table is the maximum range at which the effectiveness of combat is
@i{not} affected by distance.  Defaults to @code{PROPHI}.
@end deffn

@deffn TableUU @code{hit-at-max-range-effect} u1 u2 -> n%
This is the multiplier for the effectiveness of firing at the maximum
range possible.  Defaults to @code{100}.
@end deffn

@deffn TableUU @code{damage} u1 u2 -> hp
The basic amount of damage caused by a successful attack.
This is a Type 1 dice table. 
Dice rolls less than @code{0} are treated as @code{0}.
@end deffn

@deffn TableUU @code{fire-damage} u1 u2 -> hp
The basic amount of damage caused by a successful firing.
This is a Type 1 dice table.
Dice rolls less than @code{0} are treated as @code{0}.
If the value is set to @code{-1}, then it is the same as @code{damage}. 
Defaults to @code{-1}.
@end deffn

@deffn TableUU @code{tp-damage} u1 u2 -> tp
The amount of damage to a unit's tooling caused by a successful attack.  
This is a Type 1 dice table.
Dice rolls less than @code{0} are treated as @code{0}.
@end deffn

@c Damage done by combat is always prorated by commitment; the table values
@c are for attacks at full commitment.

@deffn TableUU @code{damage-cxp-effect} u1 u2 -> n
This table is the effect of combat experience on damage.  Its value is
interpolated according to actual experience (so that @var{n} is the
effect when @var{u1} is at its maximum experience), then multiplied with
both the dice size and the addend of the damage spec.  Defaults to
@code{100}.
@end deffn

@deffn TableUU @code{hp-min} u1 u2 -> hp
This table is the lowest hp possible for @var{u1} from attacks by
@var{u2}.  Further attacks by @var{u2} are still valid, but can do no
further damage.
@end deffn

You can set a unit to use a material as ammo.

@deffn TableUM @code{consumption-per-attack} u1 m -> n
Specifies how much a material @var{m} will be used as ammunition 
when a unit @var{u1} is attacking.
@end deffn

@deffn TableUM @code{consumption-per-fire} u1 m -> n
Specifies how much a material @var{m} will be used as ammunition 
when a unit @var{u1} is firing.@*
NOTE: Set this to @code{-1}, if you wish to use the 
@code{consumption-per-attack} table for firing.
@end deffn

@deffn TableUM @code{hit-by} u2 m -> n 
The multiplier on the consumption of material @var{m} by a unit @var{u1}
when it is attacking or firing upon a unit @var{u2}.@*
NOTE: Normally, one would probably want to set this value to @code{1}, 
if it is desired that the ammo type @var{m} be consumed to hit @var{u2}.
However, @var{u2} can be made "tougher" by setting this multiplier 
higher, rather than by adjusting the @code{hit-chance} and 
@code{fire-hit-chance} tables.@*
NOTE: To prevent an ammo @var{m} from being consumed when hitting a 
unit @var{u2} (even if the attacker @var{u1} would normally consume this 
in an attack or firing) then leave the appropriate @code{hit-by} table 
entry at the default value @code{0}, or reset it to that.
@end deffn

If a unit @var{u1} is firing upon a unit @var{u2}, then @var{u1} 
will use the quantity of ammunition @var{m} specified in 
@code{consumption-per-fire} multiplied by the corresponding entry in 
@code{hit-by}, if the result is >= 0. Else, it will use the quantity of 
@var{m} specified in @code{consumption-per-attack} multiplied by the 
corresponding entry in @code{hit-by}.

@deffn TableUM @code{material-to-attack} u m -> n
This table is a minimum of each material type @var{m} that a unit must
have to engage in direct attack or to defend against it.  This minimum
is not necessarily used up in combat, it just needs to be present.
@end deffn

@deffn TableUM @code{material-to-fire} u m -> n
This table is a minimum of each material type @var{m} that a unit must
have to fire.  This minimum is not necessarily used up, it just needs to
be present.
@end deffn

Transports can protect their occupants, and vice versa.

@deffn TableUU @code{protection} u1 u2 -> n%
This table gives the effect of occupants of type @var{u1} on the chance
of another unit's attack hitting their transport @var{u2}, as well as
the effect of the transport @var{u1} on the chance that occupants of
type @var{u2} will be hit.

For the transport, this is a multiplier, where 100 has no protection,
values less than 100 decrease hit chance, and values greater than 100
increase it.  Each occupant will be taken into account when computing
transport's protection.

If the transport is the unit being hit, then the value of this table
is the probability that an occupant of type @var{u2} will be hit.

Defaults to @code{100}.
@end deffn

A transport's destruction may leave occupants stranded on hex, will do
some sort of auto-escape or die if terrain is hostile.

Units stacked together can protect each other.

@deffn TableUU @code{stack-protection} u1 u2 -> n%
This table is the effect of units of type @var{u1} on attacks on units
of type @var{u2} that are in the same cell.  The effect is similar to
that described for the @code{protection} table.  Defaults to @code{100}.
@end deffn

Units may also act to protect every other unit in a cell, whether
occupant, transport, or stack.

@deffn TableUU @code{cellwide-protection-for} u1 u2 -> n%
This table is the effect of any unit of type @var{u1} in the same cell
on attacks against any unit of type @var{u2} in the cell.  Defaults to
@code{100}.
@end deffn

@deffn TableUU @code{cellwide-protection-against} u1 u2 -> n%
This table is the effect of any unit of type @var{u1} on any attack on
any unit in the cell by units of type @var{u2}, expressed as a
percentage multiplier.  Defaults to @code{100}.
@end deffn

Several other side-effects of combat may also be defined.

Units can retreat if they are about to be damaged; the retreat attempt
is automatic, and will be in a valid direction that is away from the
attacker.  The retreat attempt will fail if there is no direction that
the unit may move, or if has insufficient materials, acp, etc to do the
movement.  If the attempt is successful, then the unit will not be
damaged; otherwise it must take the hit.

@deffn TableUU @code{retreat-chance} u1 u2 -> n%
This table is the chance that @var{u2} will attempt to retreat if it is
hit by @var{u1}.
@end deffn

Units may gain experience as a result of combat.

@deffn TableUU @code{cxp-per-combat} u1 u2 -> cxp
This table is the number of combat experience points gained by @var{u1}
by surviving a combat round with @var{u2}.  Both attackers and defenders
gain experience equally.
@end deffn

@deffn TableUU @code{cxp-per-destroy} u1 u2 -> cxp
This table is the number of combat experience points gained by @var{u1}
destroying @var{u2}.  This is in addition to any cxp gained due to combat.
@end deffn

The sides of the victorious and defeated units may be modified as an 
outcome of unit destruction.

@deffn TableUM @code{treasury-gain-per-destroy} u m -> n
This is the amount of @var{m} gained when @var{u} is destroyed in combat.
This material is added to the treasury of the side that destroyed @var{u}.
@end deffn

@deffn TableUM @code{treasury-loss-per-destroyed} u m -> n
This is the amount of @var{m} lost when @var{u} is destroyed in combat.
This material is taken from the treasury of the side of @var{u}.
@end deffn

Unit morale may change as a result of combat, either positively or
negatively.

@deffn TableUU @code{morale-hit} u1 u2 -> .01n
This table is the 100ths of morale gained as the result of a unit of
type @var{u1} successfully hitting a unit of type @var{u2}.  The part of
the number > 100 is gained always, the part modulo 100 is the
probability of gaining 1.
@end deffn

@deffn TableUU @code{morale-hit-by} u1 u2 -> .01n
This table is the 100ths of morale lost as the result of a unit of type
@var{u1} being hit by a unit of type @var{u2}.
@end deffn

In combat model 1, the outcome is determined by relative attack
and defense strengths.

@deffn UnitTypeProperty @code{attack} n
@end deffn
@deffn UnitTypeProperty @code{defend} n
These values represent the relative attack and defense strengths
of a unit type.
@end deffn

@deffn UnitTypeProperty @code{encounter-result} list
This property specifies other possible outcomes of an attack.
The @var{list} is an optionally weighted list of the form
@example
@code{( [ @var{weight} ] @var{result} @dots{} )}
@end example
Each @var{result} has one of the following forms:
@example
@code{(unit @var{type} @var{message})}
@code{(unit (@var{type} @var{side}) @var{message})}
@code{(vanish nil @var{message})}
@end example
If the chosen @var{result} starts with @code{unit}, then the encountered
unit changes type to the given type, and if the @var{side} is specified
(as a side id), then it will change side also.

If the chosen result starts with @code{vanish}, then the encountered
unit simply vanishes permanently.

At present, this property is only used in model 1 combat, where its
results are checked before combat.  Defaults to @code{()}.
@end deffn

@deffn Symbol @code{vanish}
This keyword indicates that the encounter result is for the encountered
unit to vanish.
@end deffn

@node Capture Action

@subsection Capture Action

A unit may attempt to capture another unit directly.
If successful, the captured unit's side changes to that of the capturing unit.

@deffn ActionType @code{capture} unit
This is the action of capturing the given @var{unit}.
@end deffn

@deffn TableUU @code{acp-to-capture} u1 u2 -> acp
This table is the number of acp used up by a @code{capture} action.
Defaults to @code{0}, which disallows capture.
@end deffn

@deffn TableUU @code{bridge} u1 u2 -> t/f
This table is true if a unit of type @var{u1} can be captured by a unit
of type @var{u2} even if @var{u1} is on a type of terrain impassable to
the capturing unit.  Defaults to @code{false}.
@end deffn

@deffn UnitProperty @code{match-transport-side} t/f
Whenever an unit's transport changes side, automatically try to match 
the unit's side to the transport's new side.
@end deffn

@deffn TableUU @code{capture-chance} u1 u2 -> n%
This table is the basic chance for @var{u1} to capture @var{u2}.
@end deffn

@deffn TableUU @code{independent-capture-chance} u1 u2 -> n%
This table is the basic chance for @var{u1} to capture an independent
unit of type @var{u2}.  If the value is @code{-1}, then the chance of
capture is given by the @code{capture-chance}.  Defaults to @code{-1}.
@end deffn

Normally, the @code{protection}, @code{stack-protection}, 
@code{cellwide-protection-for}, and @code{cellwide-protection-against} 
tables affect the computed capture chance. However, the use of these 
protection tables can be prohibited by setting the 
@code{protection-resists-capture} global variable to @code{false}.

@deffn GlobalVariable @code{protection-resists-capture} t/f
When set to false, this variable ensures that the various combat protection 
tables are _not_ used when computing the success/failure of a capture 
attempt. Defaults to @code{true} (to maintain legacy behavior of older 
games).
@end deffn

The following tables can affect capture, whether or not 
@code{protection-resists-capture} is set:

@deffn TableUU @code{occupant-allows-capture-by} u1 u2 -> n%
An occupant of type @var{u1} affects the capture chance of its transport 
by @var{n}% when an unit of type @var{u2} is attempting to capture the 
transport. Set to @code{0%} to disallow the transport's capture by 
@var{u2} when @var{u1} is present. Defaults to @code{100%}.
@end deffn

@deffn TableUU @code{stack-neighbor-allows-capture-by} u1 u2 -> n%
If an unit of type @var{u1} shares the same cell with another unit, then 
it may affect the capture chance of the other unit when an unit of type 
@var{u2} is attempting capture of the other unit. This table does not 
apply to occupants of the other unit. Set to @code{0%} to disallow capture 
of a neighbor by an unit of type @var{u2} when @var{u1} is present.
Defaults to @code{100%}.
@end deffn

@deffn TableUU @code{any-neighbor-allows-capture-by} u1 u2 -> n%
If an unit of type @var{u1} shares the same cell with another unit, then 
it may affect the capture chance of the other unit when an unit of type 
@var{u2} is attempting capture of the other unit. This applies to any  
other unit in the cell, including one that may be an occupant. Set to 
@code{0%} to disallow capture of a neighbor by an unit of type @var{u2} 
when @var{u1} is present. Defaults to @code{100%}.
@end deffn

@deffn TableUU @code{occupant-allows-capture-of} u1 u2 -> n%
An occupant of type @var{u1} can prevent capture of its transport of 
type @var{u2}. Set to @code{0%} to disallow capture of a transport of 
type @var{u2} when an occupant @var{u1} is in it. Defaults to 
@code{100%}.
@end deffn

@deffn TableUU @code{stack-neighbor-allows-capture-of} u1 u2 -> n%
An unit of type @var{u1} sharing the same cell as an unit of type @var{u2} 
may affect the capture outcome of the latter. This does not apply to 
occupants. Set to @code{0%} to disallow capture of @var{u2} when @var{u1} 
is in the same cell as it. Defaults to @code{100%}.
@end deffn

@deffn TableUU @code{any-neighbor-allows-capture-of} u1 u2 -> n%
An unit of type @var{u1} sharing the same cell as an unit of type @var{u2} 
may affect the capture outcome of the latter. This applies to occupants  
as well. Set to @code{0%} to disallow capture of @var{u2} when @var{u1} 
is in the same cell as it. Defaults to @code{100%}.
@end deffn

@deffn TableUU @code{scuttle-chance} u1 u2 -> n%
This table is the chance that @var{u1}, whose capture by @var{u2} is 
guaranteed, will destroy itself instead.  Scuttling is destructive, so 
@var{u1} changes to @code{wrecked-type}.  Occupants of an 
about-to-be-captured unit will also attempt to scuttle.
@end deffn

@deffn TableUU @code{occupant-escape-chance} u1 u2 -> n%
This table is the chance that an occupant @var{u1} will escape during
the capture of a unit of type @var{u2}.  Occupants that do not escape
are either captured themselves or destroyed, depending on their type and
the capturing unit's side.
@end deffn

@deffn TableUU @code{hp-to-garrison} u1 u2 -> n
This table is the number of hp that will be taken from the capturing
unit @var{u1} in order to guard a captured @var{u2}.  If the amount is
the unit's full hp, then the unit will vanish and any occupants will be
distributed to the captured unit, to open terrain, or will vanish
themselves if there is no other option.
@end deffn

@deffn TableUU @code{countercapture} u1 u2 -> n
This table defines the defending unit's reaction to the capture attempt.
If 0, then the unit does not react to the capture attempt.
@end deffn

Captures can also affect combat experience, but has different effects on
the capturing and captured units.

@deffn TableUU @code{cxp-per-capture} u1 u2 -> cxp
This table is the number of combat experience points gained by @var{u1}
for capturing @var{u2}.
@end deffn

@deffn UnitTypeProperty @code{cxp-on-capture-effect} n
This property gives the change in a unit's cxp due to being captured,
expressed as a multiplier.
Defaults to @code{100}.
@end deffn

The treasuries of the sides of the captor and prisoner units may be 
modified as a result of capture.

@deffn TableUM @code{treasury-gain-per-capture} u m -> n
This is the amount of @var{m} gained when @var{u} is captured in combat.
This material is added to the treasury of the side that destroyed @var{u}.
@end deffn

@deffn TableUM @code{treasury-loss-per-captured} u m -> n
This is the amount of @var{m} lost when @var{u} is captured in combat.
This material is taken from the treasury of the side of @var{u}.
@end deffn

Capture of an unit may result in its changing type.

@deffn TableUU @code{changed-type-if-captured} u1 u2 -> u3
If an unit of type @var{u1} is captured by an unit of type @var{u2}, then 
it will attempt to change into type @var{u3}. Defaults to @code{non-unit}, 
which means that no change of unit type will be attempted.
@end deffn

Capture of a unit may also yield an extra dividend of knowledge,
in the form of information known to the other side.

@deffn UnitTypeProperty @code{see-terrain-if-captured} n%
If the world's terrain is not already seen, this property is the chance
that the capturing side will get all of the terrain view collected
by the former side of the captured unit.  This does not apply to any
unit views, just terrain.
@end deffn

@deffn TableUU @code{see-others-if-captured} u1 u2 -> n%
This table is the chance that the capturing side will get a view of a
unit of type @var{u2} belonging to the other side.  The chance applies
to each unit of that type when a unit of type @var{u1} is captured.
@end deffn

@node Detonation Action

@subsection Detonation Action

Detonation is an action and/or behavior that causes damage
indiscriminately.  The action specifies the location of the detonation,
which may be in the unit's cell or an adjacent one.  A unit that
detonates loses hp, changing to its @code{wrecked-type} if it loses all
of its hp.  It also hits every unit within a specified radius.
Detonation may also affect terrain within a specified radius.

@deffn ActionType @code{detonate} x y z
This action detonates the actee at the given location @var{x},@var{y},@var{z}.
@end deffn

@deffn UnitTypeProperty @code{acp-to-detonate} acp
This property is the number of action points used by one detonate
action.  Defaults to @code{0}, which disallows detonation.
@end deffn

@deffn UnitTypeProperty @code{hp-per-detonation} hp
This property is the number of hp lost in each detonation.
@end deffn

@deffn TableUU @code{detonation-unit-range} u1 u2 -> dist
This table gives the range of effect from detonation of @var{u1}.  The
severity falls off according to the inverse square law extrapolated from
the adjacent cell damage.  (1/4 severity at range 2, 1/9 at 3, etc.)
@end deffn

@deffn TableUU @code{detonation-damage-at} u1 u2 -> hp
The severity of @var{u1}'s detonation on a unit @var{u2} in the same cell.
This is a Type 1 dice table. 
Dice rolls less than @code{0} are treated as @code{0}.
@end deffn

@deffn TableUU @code{detonation-damage-adjacent} u1 u2 -> hp
The severity of @var{u1}'s detonation on a unit @var{u2} in an adjacent cell.
This is a Type 1 dice table. 
Dice rolls less than @code{0} are treated as @code{0}.
@end deffn

@deffn TableUT @code{detonation-terrain-range} u t -> dist
This table specifies the maximum distance at which a detonation will
affect terrain of type @var{t}.
@end deffn

@deffn TableUT @code{detonation-terrain-damage-chance} u t -> n%
This is the chance that the detonation will have an effect on the
terrain.
@end deffn

@deffn TableTT @code{terrain-damaged-type} t1 t2 -> n
Relative chance that terrain of type @var{t1} damaged by a detonation
will change into another type @var{t2}.
@end deffn

@deffn TableUT @code{blasts-into-ttype} u t2 -> t/f
Is the new terrain type, @var{t2}, a valid outcome for a detonation of 
an unit of type @var{u}.  This is used in conjunction with 
@code{terrain-damaged-type}, and never independently.  
Defaults to @code{true}.
@end deffn

The following tables and properties can be used for units that cannot
detonate deliberately by doing a detonate action.

@deffn TableUU @code{detonate-on-hit} u1 u2 -> n%
This table is the chance that a hit on @var{u1} by a unit of type
@var{u2} will cause it to detonate (once).  Noncombat reductions in hp,
such as attrition, have no effect.
@end deffn

@deffn UnitTypeProperty @code{detonate-on-death} n%
This property is the chance that if this type is about to die from a
combat hit, it will detonate first.
@end deffn

@deffn UnitTypeProperty @code{detonate-on-attack} n%
This property is the chance that if this type scores a hit (and damages)
an enemy unit, it will detonate first.
@end deffn

@deffn TableUU @code{detonate-on-capture} u1 u2 -> n%
This table is the chance that a unit of type @var{u1} will detonate if a
capture by a unit of type @var{u2} is about to succeed.
@end deffn

@deffn TableUU @code{detonate-on-approach-range} u1 u2 -> dist
When a unit of type @var{u2} on a non-trusted [?] side appears at a
distance of @var{dist} or less, then @var{u1} will detonate.  If
@code{-1}, then unit will not detonate upon approach.  Defaults to
@code{-1}.
@end deffn

@deffn TableUT @code{detonation-accident-chance} u t -> n.f%
This table is the chance that the unit will detonate spontaneously.
This is checked once/turn, at the beginning of the turn, and also upon
each entry to a cell, if moving.
@end deffn

@node Terrain Alteration Actions

@subsection Terrain Alteration Actions

@deffn ActionType @code{alter-terrain} x y t
This action changes the type of the cell at @var{x},@var{y} to @var{t}.
@end deffn

@deffn ActionType @code{add-terrain} x y dir t
This action adds a connection or border of type @var{t} to the cell at
@var{x},@var{y}, in direction @var{dir}.
@end deffn

@deffn ActionType @code{remove-terrain} x y dir t
This action removes a connection or border of type @var{t} to the cell
at @var{x},@var{y}, in direction @var{dir}.
@end deffn

@deffn TableUT @code{acp-to-add-terrain} u t -> n
@end deffn
@deffn TableUT @code{acp-to-remove-terrain} u t -> n
For auxiliary terrain types, these tables are the costs to add or
remove.  For cell terrain, the costs of removing the old type and adding
the new type are added together.  If the value is 0, then that type of
terrain may not be added or removed.  As a special exception, cell
terrain may have a cost to remove of 0, so that the sum of add and
remove costs can be as low as 1; in that case, a value of -1 disallows
removal.  Both default to @code{0}.
@end deffn

@deffn TableUT @code{alter-terrain-range} u t -> n
This table is the maximum distance at which a unit can alter terrain
@var{t}.  Defaults to @code{0}, which means that the unit can change
only the terrain in its own cell.
@end deffn

Note that if @code{see-terrain-always} is false, then other sides will
not see the terrain change unless they are viewing the altered terrain.

@deffn TableUM @code{material-to-add-terrain} u m -> n
This table is the amount of material necessary to perform an
@code{add-terrain} or @code{alter-terrain} action.
@end deffn

@deffn TableUM @code{material-to-remove-terrain} u m -> n
This table is the amount of material necessary to perform a
@code{remove-terrain} action.
@end deffn

@deffn TableTM @code{consumption-per-add-terrain} t m -> n
This table is the amount of material @var{m} necessary for any unit to
add terrain of type @var{t}.
@end deffn

@deffn TableTM @code{material-per-remove-terrain} t m -> n
This table is the amount of material of type @var{m} that becomes
available as the result of removing terrain @var{t}.
@end deffn

@node Backdrop

@section Backdrop

This section describes the parameters affecting backdrop computations.

@menu
* Years and Days::
* Temperature Variation::
* Temperature Effects::
* Wind Variation::
* Unit Production and Consumption::
* Terrain Production and Consumption::
* Supply Lines::
* Side Research::
* Unit Research::
* Terrain Attrition::
* Terrain Accident::
* Unit Revolt::
* Unit Surrender::
@end menu

@node Years and Days

@subsection Years and Days

Cyclic changes in the environment are governed by a yearly cycle or a
daily cycle whose length must be defined.

@deffn WorldProperty @code{year-length} n
This property is the number of turns in an annual cycle.  If less than
@code{2}, then no seasonal effects will be calculated.
@end deffn

@deffn WorldProperty @code{day-length} n
This property is the number of turns in a single day.  If less than
@code{2}, then day and night will not be calculated.
@end deffn

Note that @code{year-length} and @code{day-length} are completely
independent of each other, and it is possible to have days that are
longer than years.

@deffn AreaProperty @code{initial-year-part} n
This property is the season of the first turn in the game.  This affects the 
sun position, if the sunlit region is dynamically changing.  In particular, 
this can be used to start the sun somewhere other than one of the equinoxes.
@end deffn

@deffn AreaProperty @code{initial-day-part} n
This property is the hour of the first turn in the game, in 100ths of a
day part.  This affects the sun position, if the sunlit region is 
dynamically changing.
@end deffn

@deffn GlobalVariable @code{season-names} list
This global is a list of which turns in a year should be called which
seasons.  It has the form @code{(... (n1 n2 name) ...)}.  Defaults to
@code{()}.

A twelve-turn year with four seasons would be
@example
((0 2 "winter") (3 5 "spring") (6 8 "summer") (9 11 "autumn"))
@end example
If any number ranges overlap, then the first match will be used, while
if a particular turn has no named season, then it will go unnamed in the
display.
@end deffn

@deffn UnitTypeProperty @code{acp-season-effect} interpolation-list
This property is the effect of the seasons on acp.  The input value is
the year part, and the result value is added to the basic
@code{acp-per-turn}.  Defaults to @code{()}.
@end deffn

@deffn WorldProperty @code{daylight-fraction} n%
This property is the percentage of the world's circumference that has
daylight.  Defaults to @code{50}.
@end deffn

@deffn WorldProperty @code{twilight-fraction} n%
This property is the percentage of the world's circumference that has
daylight and twilight.  Defaults to @code{60}.
@end deffn

@deffn AreaProperty @code{sun} x y
This property is the initial position of the sun over the area.
Defaults to the exact middle of the area.
@end deffn

@node Temperature Variation

@subsection Temperature Variation

@deffn TerrainTypeProperty @code{temperature-average} n
This property is the average temperature for each type of terrain.
@end deffn

@deffn TerrainTypeProperty @code{temperature-variability} n
This property is the amount of totally random variation in the
temperature in each cell.
@end deffn

@deffn GlobalVariable @code{temperature-year-cycle} ((x y) interpolation-list)@dots{}
This global is a list of interpolation lists used to set basic
temperatures at given points in the area.  The input value for each list
is the current year part, while the result is the temperature at
@var{x},@var{y}.  Then for each point in the area, its temperature is
the interpolation of the temperature at the two nearest given points.
Defaults to @code{()}.
@end deffn

@deffn TerrainTypeProperty @code{temperature-moderation-range} distance
This property is the radius of the area whose raw temperatures will be
averaged to get the actual temperature.  This can be very time-consuming
to calculate, so only values of 0 (no averaging) and 1 (average with
adjacent cells) are recommended.
@end deffn

@node Temperature Effects

@subsection Temperature Effects

@deffn UnitTypeProperty @code{acp-temperature-effect} interpolation-list
This property is the effect of temperature on acp.  The input value is
temperature, and the result value is multiplied with acp, after it has
been modified for night effect, but before modification for season.  The
result is divided by 100, so an effect < 100 reduces acp, an effect of
100 has no effect, and an effect > 100 increases acp.  Defaults to
@code{()}.
@end deffn

@deffn UnitTypeProperty @code{consumption-temperature-effect} interpolation-list
This property is the effect of temperature on material consumption.
Defaults to @code{()}.
@end deffn

@deffn UnitTypeProperty @code{temperature-attrition} interpolation-list
This property is the effect of temperature on a unit's hp.  The input
value is temperature, and the result value is the number of hp that the
unit will lose each turn at that temperature.  Defaults to @code{()}.
@end deffn

Transports can protect their occupants from temperature extremes.

@deffn TableUU @code{temperature-protection} u1 u2 -> t/f
This is true if transports of type @var{u1} protect occupants of type
@var{u2} from the effects of the cell's temperature.
@end deffn

@node Wind Variation

@subsection Wind Variation

The following parameters control random variation of the prevailing
winds in each cell.

@deffn TerrainTypeProperty @code{wind-force-average} n
This property is the average wind force in a type of terrain.
@end deffn

@deffn TerrainTypeProperty @code{wind-force-variability} n%
This property is the chance that the wind in a cell will increase or
decrease in force each turn.
@end deffn

@deffn TerrainTypeProperty @code{wind-variability} n%
This property is the chance that the wind in a cell will change
direction each turn.
@end deffn

@deffn GlobalVariable @code{wind-mix-range} n
This variable is the radius out to which winds interact.  If 0, then
winds in adjacent cells can vary independently of each other, and do not
interact in any way.
@end deffn

@node Unit Production and Consumption

@subsection Unit Production and Consumption

Units can be set to always produce some amount of material without
taking explicit action.

@deffn TableUM @code{base-production} u m -> n
This table is the basic amount of each material @var{m} produced by a
unit of type @var{u} in each turn.
@end deffn

@deffn TableUM @code{occupant-base-production} u m -> n
This table is the base production of each material @var{m} by a unit
of type @var{u} when it is an occupant of any other unit.  The default of
@code{-1} means to use the number from @code{base-production}.
@end deffn

@deffn TableUT @code{productivity} u t -> n%
This table is the percentage productivity of a unit of type @var{u} when
on terrain of type @var{t}.  This is multiplied with the basic
production rate to get actual material production, so productivity of
@code{0} completely disables production on that terrain type, and
productivity of @code{100} yields the rate specified by
@code{base-production}.  Defaults to @code{100}.
@end deffn

@deffn TableUT @code{productivity-adjacent} u t -> n%
This table is the percentage productivity of a unit of type @var{u}
when adjacent to terrain of type @var{t}.  The actual productivity
of a unit is a max of its productivity on its own cell and the adjacent
cells.
@end deffn

@deffn TableUM @code{productivity-min} u m -> n
@end deffn
@deffn TableUM @code{productivity-max} u m -> n
These tables are the lower and upper bounds on actual production after
multiplying by productivity.  Default to @code{0} and @code{9999},
respectively.
@end deffn

@deffn TableUM @code{base-consumption} u m -> n
This table sets the amount of materials consumed by the unit in a turn,
even if it doesn't move or do anything else.  This is a minimum rather than
an amount added to others, so movement will not cause the unit to consume
extra material until it reaches the base consumption.
@end deffn

@deffn TableUM @code{hp-per-starve} u m -> .01hp
If the unit runs out of a material that it must consume, this table
specifies how many 1/100 hp it will lose each turn that it is starving.
If starving for several reasons, loss is max of starvation losses, not
the sum.  This value is stochastic.
@end deffn

@deffn TableUM @code{consumption-as-occupant} u m -> n%
This table is the consumption by a unit of type @var{u1} when it is an
occupant, expressed as a percentage of its @code{base-consumption}.
This is useful for units such as planes which always consume fuel in the
air but not on the ground.  Defaults to @code{100}.
@end deffn

@deffn TableUM @code{gives-to-treasury} u m -> t/f
This table is true if units of type @var{u} are able to transfer
material of type @var{m} to the side's treasury.
@end deffn

@node Terrain Production and Consumption

@subsection Terrain Production and Consumption

Materials may be produced by cells, redistributed, and also taken up by
units.  Some amount of material may need to stay in the cell's storage,
or the type of terrain might change.  Exhaustion is tested after all
consumption has been accounted for.

@deffn TableTM @code{terrain-production} t m -> n
This table is the amount of each material @var{m} produced by a cell of
the given type @var{t} in each turn.  This refers to the material actually
produced by the cell itself, which goes into the cell's own materials store
and may be available through extraction actions or the backdrop economy.
Production by advanced units that use the cell is determined by the
@code{production-from-terrain} table.
@end deffn

@deffn TableTM @code{terrain-consumption} t m -> n
This table is the amount of material @var{m} consumed by a cell of type
@var{t} each turn.  If insufficient material is available, then the
terrain may change type.
@end deffn

@deffn TableTM @code{change-on-exhaustion-chance} t m -> n%
This table is the chance that a cell of type @var{t}, with no supply of
material of type @var{m}, will become exhausted and change to its
exhausted type.
@end deffn

@deffn TableTM @code{terrain-exhaustion-type} t1 m -> t2
If @var{t2} is not @code{non-terrain}, then this table says that any
cell with terrain @var{t1} that is exhausted will change to @var{t2}.
If several materials are exhausted in the same turn, then the
lowest-numbered material type will determine the new terrain type.
Defaults to @code{non-terrain}.
@end deffn

@deffn TableMM @code{people-consumption} m1 m2 -> n
This table is the base consumption per turn by people of type @var{m1}
of each other material type @var{m2}.
@end deffn

@deffn TableMM @code{people-production} m1 m2 -> n
This table is the people of type @var{m1} base production per turn of
each other material type @var{m2}.
@end deffn

@node Supply Lines

@subsection Supply Lines

In real life, material production and consumption rarely occur in the
same place at the same time.  For some games, the player must transfer
materials manually, by loading and unloading from units.  However, this
can be time-consuming and difficult, and is best reserved for scarce
and/or valuable materials.  For more common materials, @i{Xconq}
provides a @dfn{backdrop economy}, which moves materials around
automatically.

@deffn GlobalVariable @code{backdrop-model} n
Two models (potentially more in the future) are available for deciding
when and where to transfer materials in the backdrop economy, and they
support different features.  This variable chooses among the available
models.

The default, model @code{0}, supports only transfers among units
and between units and treasuries, according to @code{in-length},
@code{out-length}, and the treasury settings configured elsewhere.  It uses
a complicated set of rules to determine which units need supplies, based on
their consumption, production, doctrine, and other factors; and it tries to
keep material in treasuries instead of units to the extent possible.

Model @code{1} has a much different philosophical basis.  Instead of trying
to divine the designer's intent by examining the game rules, it attempts to be
as simple and predictable as possible; its basic rule is that materials
always flow wherever they can, from things that have more to things that
have less, in such a way as to level out any differences in material supply.
It treats treasuries simply as additional units with large capacity, linked
to all units that can access the treasuries.  If there are two
material-handling things (units, treasuries, or terrain cells) that
can transfer material, then model @code{1} will keep roughly the same amount
of material in each of them, unless that would see one filled beyond its
capacity or emptied below its resupply doctrine level, in which case they
will be as close to equal as possible given the limitations of the game rules.
@end deffn

@deffn TableUM @code{in-length} u1 m -> dist
@end deffn
@deffn TableUM @code{out-length} u2 m -> dist
These two tables together determine the length of supply lines between
units.  The given type of material can only be transferred from unit
type @var{u1} to unit type @var{u2} if the distance is less than the
minimum of the @code{in-length} of @var{u1} and the @code{out-length} of
@var{u2}.

For instance, the @code{in-length} for a fighter's fuel might be 3
cells, while the @code{out-length} of fuel from a city is 4 cells.  Then
the fighter will be constantly supplied with fuel when within 3 cells of
a city.  If the fighter's out-length is -1, it will never transfer any
fuel to the city.

An in- or out-length of @code{0} means that the two units must be in the
same cell, while a negative length disables the automatic transfer
completely.  Large @code{out-length} values should be used sparingly in model
@code{0}, since the algorithm uses the @code{out-length} to define a
radius of search for units to be resupplied; and model @code{0} ignores
@code{out-length} anyway in the case of materials its rules decide are
``scarce''.  Model @code{1} always obeys @code{out-length}, and large values
make no significant difference to its running time.  Both tables default to
@code{0}.
@end deffn

@deffn GlobalVariable @code{backdrop-ignore-doctrine} t/f
In model @code{1}, setting this variable @code{true} will allow the
algorithm to move material away from units even when the units are already
below the minimum levels set by their resupply doctrine.  Ignoring doctrine
is arguably the approach most consistent with the philosophy of model
@code{1}, which is to not attempt to judge which units are or are not needy
and only look at their current supply levels as raw numbers.  Nonetheless,
the default is @code{false}: material will never be moved away from a unit
already below its resupply level, to avoid surprising game designers or
players who might set a doctrine level and then wonder why units are being
drained below that level in the backdrop economy.  Which setting works best
in a given game design may have to be determined by trial and error.  Note
that this setting is specific to model @code{1}, and will have no effect in
model @code{0}.
@end deffn

The following six tables control automatic transfers involving terrain.
These tables are meaningful only in model @code{1} at present, although it
is possible that some future new model or enhancement to model @code{0} might
also use them.  There are two tables for each of three kinds of transfers:
terrain to unit, unit to terrain, and terrain to terrain.  Terrain to unit
transfers are similar to @code{extract} actions, but happen automatically
and without expenditure of any ACP, during the economy phase at the start
of each turn.  Unit to terrain transfers operate in the reverse direction,
with material automatically transferred from the unit's store to terrain;
such transfers are intended for special effects like poison gas.  Terrain to
terrain transfers allow material to diffuse across the landscape.

At present, there is no feature provided to limit terrain transfers according
to control or ownership, so if unit to terrain transfers are permitted, it is
entirely possible that a unit will transfer material to terrain and then
some other unit from some other side may pick it up by means of other
features, automatically or not, and either directly or after the material
has diffused through other intervening cells.

@deffn TableUM @code{terrain-to-unit-in-length} u m -> dist
Sets the maximum distance at which a unit can receive materials from
terrain in the backdrop economy, according to unit and material type.
Note that these transfers occur automatically and without expenditure of
ACP; deliberate transfers, possibly with an ACP cost, are handled by
@code{extract} actions and configured elsewhere.  Default is @code{-1},
which disables backdrop terrain to unit transfers.
Large values may
result in slow computation, but currently-planned, not yet implemented,
optimizations should eliminate that issue as long as no very-long-distance
transfers are actually permitted by the other tables.
@end deffn

@deffn TableTM @code{terrain-to-unit-out-length} t m -> dist
Sets the maximum distance for terrain to unit transfers according to terrain
type of the cell the material is taken from, and material type.  For the
transfer to be allowed, the distance must be less than or equal to the
smaller of the relevant @code{terrain-to-unit-in-length} and
@code{terrain-to-unit-out-length} values.  At present, only the cell terrain
type is examined (other kinds of terrain are ignored).  The default is the
maximum table value, so that terrain type has no effect on terrain to unit
transfers.  To make it impossible for units to receive a given material from
a given terrain type by automatic backdrop economy transfers, set the
relevant @code{terrain-to-unit-out-length} value to @code{-1}.
@end deffn

@deffn TableUM @code{unit-to-terrain-out-length} u m -> dist
Sets the maximum distance for unit to terrain transfers according to unit
type and material type.  As with @code{terrain-to-unit-in-length}, these
transfers occur automatically without player control.  Remember that
materials once transferred to cells are not automatically owned by any side,
and may be picked up by other sides.  Default is @code{-1}, which disables
such transfers.  Large values may result in slow computation, but
currently-planned, not yet implemented, optimizations should eliminate
that issue as long as no very-long-distance transfers are actually
permitted by the other tables.
@end deffn

@deffn TableTM @code{unit-to-terrain-in-length} t m -> dist
Sets the maximum distance for unit to terrain transfers according to cell
terrain type of the cell the material is transferred into, and material type.
As with @code{terrain-to-unit-out-length}, only the cell type is considered.
The default is the maximum table value, and setting a value to @code{-1}
disables automatic unit-to-terrain transfers of that material into that
terrain.
@end deffn

@deffn TableTM @code{terrain-to-terrain-out-length} t1 m -> dist
Maximum distance for automatic terrain to terrain transfers (diffusion) of
material m out of terrain type t1.  Default value @code{-1}, which disables
diffusion.  At present, only cell terrain is considered; however, a planned
enhancement will change the default value to @code{0} (still disabling
diffusion by default, because diffusion from a cell to itself has no effect)
and treat border, connection, and coating terrain as modifiers, so that the
actual out-length used will be the sum of the table values for the cell,
each coating, and each border or connection on the side nearest the
destination cell.
@end deffn

@deffn TableTM @code{terrain-to-terrain-in-length} t2 m ->dist
Maximum distance for automatic terrain to terrain transfers (diffusion) of
material m into terrain type t2.  Default value is @code{1}, allowing
transfers only between adjacent cells.  As with
@code{terrain-to-terrain-out-length} above, this presently only considers
cell type but a planned enhancement will make it consider borders,
connections, and coatings as well.
@end deffn

The following tables control an advanced supply line algorithm that
is implemented, but does not seem to work correctly.  They are listed
here for completeness.  The advanced supply line algorithm is activated by
the @code{supply} variant, and runs completely separately from the model
@code{0} or model @code{1} economy system described above.

@deffn Table @code{supply-capacity-deterioration}
@end deffn
@deffn Table @code{supply-capacity-threshold}
@end deffn
@deffn Table @code{supply-deterioration}
@end deffn
@deffn Table @code{supply-enemy-interdiction}
@end deffn
@deffn Table @code{supply-importance}
@end deffn
@deffn Table @code{supply-in-max}
@end deffn
@deffn Table @code{supply-interdiction-adjacent}
@end deffn
@deffn Table @code{supply-interdiction-adjacent-for-material}
@end deffn
@deffn Table @code{supply-interdiction-at}
@end deffn
@deffn Table @code{supply-interdiction-at-for-material}
@end deffn
@deffn Table @code{supply-in-threshold}
@end deffn
@deffn Table @code{supply-in-weight}
@end deffn
@deffn Table @code{supply-neutral-interdiction}
@end deffn
@deffn Table @code{supply-out-max}
@end deffn
@deffn Table @code{supply-out-threshold}
@end deffn
@deffn Table @code{supply-potential}
@end deffn
@deffn Table @code{supply-potential-terrain-effect}
@end deffn
@deffn Table @code{supply-starve-weight}
@end deffn
@deffn Table @code{occupant-supply-potential}
@end deffn

@node Side Research

@subsection Side Research

Sides may achieve advances by researching them.

@deffn GlobalVariable @code{side-can-research} t/f
This variable is true if the side can do research.
@end deffn

@deffn GlobalVariable @code{indepside-can-research} t/f
This variable is true if the independent side can do research.
@end deffn

@deffn TableAA @code{advance-needed-to-research} a1 a2 -> t/f
This table indicates whether advance @var{a1} needs @var{a2}
to have been achieved first.
@end deffn

@deffn TableAA @code{advance-precludes-advance} a1 a2 -> t/f
True, if researching @var{a1} prevents @var{a2} from being researched.
@end deffn

@deffn TableAA @code{advance-consumption-per-rp} a m -> n
This table is the amount of material type @var{m} consumed
to add one research point for @var{a}.
@end deffn

@node Unit Research

@subsection Unit Research

Units may work on advances as a backdrop activity, without
expending action points.

@deffn UnitTypeProperty @code{can-research} t/f
This property is true if the unit can work on advances in the
background.
@end deffn


@node Terrain Attrition

@subsection Terrain Attrition

Attrition is the automatic loss of hit points due to being in certain types
of terrain.  This runs once for each unit at the beginning of each turn.

@deffn TableUT @code{attrition} u t -> .01hp
This table is the rate of loss of hp per turn.
The terrain used is cell or connection terrain as appropriate for
the unit's position.
@end deffn

@node Terrain Accident

@subsection Terrain Accident

Accidents result in the damage or disappearance of a unit in the open
in some kinds of terrain.  This runs once at the beginning
of each turn, on each unit not in a transport.

@deffn TableUT @code{accident-hit-chance} u t -> .01n%
This table is the chance of the unit being hit while in the given terrain.
@end deffn

@deffn TableUT @code{accident-damage} u t -> hp
The HP that will be lost in an accident. 
This is a Type 1 dice table.
Dice rolls less than @code{0} are treated as @code{0}.
@end deffn

@deffn TableUT @code{accident-vanish-chance} u t -> .01n%
This table is the chance of the unit simply vanishing while in the given terrain.
@end deffn

@node Unit Revolt

@subsection Unit Revolt

Revolt is a spontaneous change of side,
occurring in place of a side-given unit action.
The new side may be none (independence) or another side.

@deffn UnitTypeProperty @code{revolt-chance} .01n%
This property is the chance for the unit to revolt spontaneously.
@end deffn

@deffn UnitTypeProperty @code{revolt-at-opinion-min} .01n%
This property is the chance for the unit to revolt when its opinion of
its current side is at its lowest possible level.  The chance is
interpolated for opinions between zero and the minimum.
@end deffn

@node Unit Surrender

@subsection Unit Surrender

@deffn TableUU @code{surrender-chance} u1 u2 -> .01n%
This table is the chance that a unit of type @var{u1} will change its side
to match the side of a unit @var{u2} that is within the @code{surrender-range}
for the two types.
@end deffn

@deffn TableUU @code{surrender-range} u1 u2 -> dist
This table is the distance out to which a unit of type @var{u1}
will surrender to a unit of type @var{u2}.
Defaults to @code{1}.
@end deffn

@node Behavior

@section Behavior

The AIs normally make their own decisions about how to play a game,
but they can also follow hints provided by the game design.

@deffn GlobalVariable @code{ai-may-resign} t/f
This variable is true if the AI can evaluate whether to resign and then
resign if it likes.  Otherwise, it will play until it wins or loses.
Defaults to @code{true}.
@end deffn

@deffn GlobalVariable @code{units-may-go-into-reserve} t/f
This variable is true if AI or plan execution can put a unit into
reserve for the remainder of a turn.  This can prevent unit confusion,
but can also put the side at a disadvantage if too many of its units
spend turns in reserve rather than doing something useful.  Defaults to
@code{true}.
@end deffn

@deffn UnitTypeProperty @code{ai-tactical-range} n
This is the range out to which AI and/or plan execution will look for
tactical opportunities, such as captures.  Defaults to @code{4}.
@end deffn

@deffn UnitTypeProperty @code{ai-peace-garrison} n
This is the number of occupants the AI should have as garrison for the
unit if there are no threats nearby.
@end deffn

@deffn UnitTypeProperty @code{ai-war-garrison} n
This is the number of occupants the AI should have as garrison for the
unit if there are threatening units nearby.  Defaults to @code{1}.
@end deffn

@deffn GlobalVariable @code{ai-advanced-unit-separation} n
This is the recommended distance between advanced units, ideally used
when constructing units are deciding where to build.  Defaults to
@code{3}.
@end deffn

@deffn GlobalVariable @code{ai-badtask-max-retries} n
This is the maximum number of times that task execution will be retried
when a task fails.  Defaults to @code{6}.
@end deffn

@deffn GlobalVariable @code{ai-badtask-remove-chance} n
This is the probability that a failing task will be removed from
the task agenda.  Defaults to @code{20}.
@end deffn

@deffn GlobalVariable @code{ai-badtask-reserve-chance} n
This is the probability that a unit whose task is failing will go into
reserve and try the task on the following turn.  Defaults to @code{6}.
@end deffn

@deffn GlobalVariable @code{ai-minimal-size-goal} n
The minimum size that an unit must be able to grow to in order for 
the AI to accept construction of it at a given location.
Defaults to @code{12}.
@end deffn

@deffn UnitTypeProperty @code{ground} t/f
@end deffn
@deffn UnitTypeProperty @code{naval} t/f
@end deffn
@deffn UnitTypeProperty @code{air} t/f
@end deffn
@deffn UnitTypeProperty @code{colonizer} t/f
@end deffn
@deffn UnitTypeProperty @code{facility} t/f
These properties identify a unit type as having particular uses and/or
characteristics.
@end deffn

@deffn UnitTypeProperty @code{minimal-sea-for-docks} n
The number of cells of sea terrain that must be present before an AI 
will consider building naval units. Defaults to @code{30}.
@end deffn

@node Game End

@section Game End

When a side loses, its units may suffer a variety of fates, including
revolt, surrender, wrecking, or disappearance.  Disappearance is the
default fate.  Each type of test is independent, but run in the order
wreck, vanish, surrender, revolt.

@deffn UnitTypeProperty @code{lost-wreck-chance} .01n%
This property is the .01% chance that a unit will be wrecked, as if it
had been hit in combat.  Once a unit is wrecked, it will not be
re-wrecked, even if the wrecked type has itself a nonzero
@code{lost-wreck-chance} property.  The other loss chances still apply,
however.
@end deffn

@deffn UnitTypeProperty @code{lost-vanish-chance} .01n%
This property is the .01% chance that a unit will vanish when the side
loses.  Defaults to @code{10000}.
@end deffn

@deffn TableUU @code{lost-surrender-chance} u1 u2 -> .01n%
This table is the .01% chance that a unit of type @var{u1} on a losing
side will surrender to an adjacent unit of type @var{u2}.
@end deffn

@deffn UnitTypeProperty @code{lost-revolt-chance} .01n%
This property is the .01% chance that a unit on a losing side will
revolt and go over to some other side, as per the backdrop activity.
@end deffn

@node Dates and Time

@section Dates and Time

@deffn GlobalVariable @code{turn} n
This variable is the number of the current turn.
@end deffn

Note that the first turn of a game is actually turn 1.  Pre-game
activities happen during ``turn 0''.

@menu
* Game Length::
* Calendar::
* Real Time::
@end menu

@node Game Length

@subsection Game Length

@deffn GlobalVariable @code{last-turn} n
This variable is the number of the last turn.  Defaults to @code{-1},
which means that there is no limit on the number of turns.
@end deffn

@deffn GlobalVariable @code{extra-turn-chance} n%
This variable is the chance that the game will go one more turn after
the @code{last-turn}.
@end deffn

@i{Xconq} is currently limited to games of 32,767 turns.

@node Calendar

@subsection Calendar

You can make @i{Xconq} display game time as a calendar date, rather than
as a simple turn number.

@deffn GlobalVariable @code{calendar} type data@dots{}
This variable is the description of the calendar type that will be used.
If the variable is @code{()} or the type is @code{number}, then turns
will be reported numerically starting from @code{1}.  If @code{usual},
then the standard Gregorian calendar will be used.  Defaults to
@code{()}.

If the numeric or @code{number} calendar is in use, then a @var{data} of
@code{"cycle"} will yield @code{"cycle 1"}, @code{"cycle 2"}, etc.
@end deffn

For the @code{usual} calendar, the @var{data} defines how long a turn
is, in terms of the calendar.  For instance, a time measure of
@code{day} (and a base date of @code{"1 Jan 1900"}) will result in turns
@code{"1 Jan 1900"}, @code{"2 Jan 1900"}, etc, while a date unit of
@code{year} will yield just @code{"1900"}, @code{"1901"}, and so forth.

The full form of the @var{data} is
@example
(@var{date-step-range1} @var{date-step-range2} ...)
@end example
where each @var{date-step-range} has the form
@example
( [ @var{start} @var{end} ] @var{type} [ @var{multiple} ] )
@end example
where @var{type} has the values @var{second}, @var{minute}, @var{hour},
@var{day}, @var{week}, @var{month}, @var{season}, or @var{year}, where
@var{multiple} is the number of that type in eah turn, and where
@var{start} and @var{end} define the ranges of turns to use for the
given type and multiple of the date.  (The ranges are useful for
telescoping time periods, such as in civilization-building games where
early turns might advance by 50 years each, and later turns by only a
year.)

@deffn Symbol @code{number}
@end deffn
@deffn Symbol @code{usual}
@end deffn

@deffn GlobalVariable @code{initial-date} str
This variable is the date, in the specified calendar system, of the
first turn.  Defaults to @code{""}, which has the effect of setting the
initial date to be whatever the calendar does with turn number 1.
@end deffn

@node Real Time

@subsection Real Time

A game may also be limited in real time.

@deffn GlobalVariable @code{real-time-for-game} seconds
@end deffn

@deffn GlobalVariable @code{real-time-per-turn} seconds
@end deffn

@deffn GlobalVariable @code{real-time-per-side} seconds
@end deffn

@deffn GlobalVariable @code{elapsed-real-time} seconds
This is the difference in real time between the start of the game
and its current state.
@end deffn

@node Image Families

@section Image Families

The @code{imf} form defines graphical images in a platform-independent
way.  An @i{image family} is a named collection of images of varying
sizes and depths.

@deffn Form @code{imf} name [ properties ] [ images ]
This form declares an image family to exist, with the name @var{name}
and @var{properties}, and consisting of the specified @var{images}.
Each image has the form
@display
@code{((@var{w} @var{h} @var{special}) [ @var{properties} ] (@var{type} @var{data}...) ...)}
@end display
where @var{w} and @var{h} are its width and height, respectively,
@var{special} indicates special characteristics of the image, the
@var{type} may be one of @code{color}, @code{mono}, @code{mask}, or
@code{file}, and the @var{data} consists of strings of hexadecimal
digits.  The data strings may include slashes, which have no effect on
interpretation, but are useful to indicate each row of an image.  Color
images may also have additional properties, which come between the
@var{type} and the @var{data}.

The family's @var{name} may consist only of alphabetic characters,
decimal digits, and hyphens or underscores.  Upper- and lower-case
characters are equivalent, as are hyphens and underscores.  The
canonical form of the name is lowercase with hyphens.

Multiple forms with the same name may occur, and each adds to the
family, overwriting individual image parts that are of the same size and
depth.
@end deffn

@deffn Symbol @code{tile}
If this symbol appears following the dimensions of an image, it
indicates that the image is a pattern tile rather than a single image.
@end deffn

@deffn Symbol @code{border}
If this symbol appears following the dimensions of an image, it
indicates that the image is a set of images for border terrain.  Borders
have 16 subimages, each showing a different sort of junction between
cells.
@end deffn

@deffn Symbol @code{connection}
If this symbol appears following the dimensions of an image, it
indicates that the image is a set of images for connection terrain.
Connections have 64 subimages, each for a different pattern of
connectons to adjacent cells.
@end deffn

@deffn Symbol @code{transition}
This symbol indicates that the terrain is a transition pattern
used to blend two types of terrain.  Transitions consist of
at least 4 subimages, and may have several variants that can
be chosen randomly.
@end deffn

@deffn ImageProperty @code{actual} w h
This property is the actual size of the image data.
@end deffn

@deffn ImageProperty @code{embed} name
This property specifies that another image, similar to the image family
named by @var{name}, is already embedded within the image, and so
@i{Xconq} need not superimpose such an image itself.  This may occur
when an image has a ``builtin'' side emblem, or is readily identifiable
as belonging to a particular side, and it would be redundant for
@i{Xconq} to add an emblem when displaying a unit.
@end deffn

@deffn ImageProperty @code{embed-at} x y
This property specifies that the area of the image at @i{x,y} is
suitable for the display of an emblem.
@end deffn

@deffn ImageProperty @code{embed-size} w h
This property specifies the dimensions of the area available for an
emblem.
@end deffn

@deffn ImageProperty @code{x} n [ x y ]
This property specifies that the image includes @var{n} variant
subimages, any of which may be randomly chosen by an interface.  The
optional numbers @var{x} and @var{y} indicate the offset of each
subimage, so for instance an x of 32 and a y of 0 indicates a horizontal
strip of images, each 32 pixels apart.  Their values default to the
width of the image and 0, respectively.
@end deffn

@deffn ImageProperty @code{notes} list
This property is for designer notes about the image.
@end deffn

@deffn ImageProperty @code{mono} data @dots{}
This property indicates that the data represents a monochrome image.
@end deffn

@deffn ImageProperty @code{mask} data @dots{}
This property indicates that the data represents a mask.
@end deffn

@deffn ImageProperty @code{color} [ properties ] data @dots{}
This property indicates that the data represents a color image.
@end deffn

@deffn ColorImageProperty @code{pixel-size} n
This property is the number of bits used to encode each pixel.
@end deffn

@deffn ColorImageProperty @code{palette} [ (index r g b) @dots{} ]
This property is the color palette that should be used with the image.
@end deffn

@deffn ImageProperty @code{file} filename [ @code{std} ] [ x y ]
This property indicates that the image data is in a file named
@var{filename}.  @var{filename} must contain a recognized type of image
(GIF only, at present).  The optional @var{x} and @var{y} indicate the
position of the upper left corner of the image within the larger picture
contained in the file.

If the optional symbol @code{std} precedes the position values, then the
numbers are relative positions in a file image that is assumed to be a
grid of images all the same size.  It is also assumed that images are
separated by two pixels on all sides, so the pixel position is @code{2 +
(x * (img_width + 2))}.

File images do not have explicit masks, but may instead have key colors
that will be used to compute the mask.  Key colors are indicated by 2x2
pixel blocks in the upper left corner of the file image.  Any number of
key colors may be defined; the end of the list is indicated by a block
of the same color as the first block.  (See @file{images/river44x48.gif}
for an example with many key colors.)
@end deffn

@deffn Symbol @code{std}
This symbol, when in a @code{file} property, indicates that the
file image is laid out in a standard grid pattern. (see above)
@end deffn

Note that for the purposes of stability and change tracking, tools that
generate image families use a more restricted format.  This format
requires a separate imf form for each size of image, the size is on the
same line as the imf name, and each image/mask is on a separate line,
indented by 2. (See the existing library imf files for further detail.)

@node Other Forms

@section Other Forms

GDL forms in this section are those that do not really fit anywhere
else.

@menu
* Default Display Style::
* The Random State::
* Debugging Support::
@end menu

@node Default Display Style

@subsection Default Display Style

The exact style of display depends on the user interface and on user
preferences, but for some games, you may want to encourage a particular
style by making it be the default.

@deffn GlobalVariable @code{unseen-char} str
This variable is a string whose first character will be used to
represent unexplored terrain.  If the string consists of two characters,
the second char will be scattered throughout a field of the first char.
Defaults to @code{" ?"}.  (At present, this is used only by the curses
interface.)
@end deffn

@deffn GlobalVariable @code{unseen-color} str
This variable is the name of a color that will be used to represent
unexplored terrain.  Defaults to @code{"black"}.
@end deffn

@deffn GlobalVariable @code{grid-color} str
This variable is the name of a color to use to draw the cell-separating
grid.  Defaults to @code{"dark-gray"}.
@end deffn

@deffn GlobalVariable @code{unit-name-color} str
This variable is the name of a color to use when drawing unit names and
numbers.  Defaults to @code{"white"}.
@end deffn

@deffn GlobalVariable @code{unit-gbox-border-color} str
This is the color to use around the border of a transport's grouping box.
Defaults to @code{"black"}.
@end deffn

@deffn GlobalVariable @code{unit-gbox-fill-color} str
This is the color to use inside a transport's grouping box.
Defaults to @code{"white"}.
@end deffn

@deffn UnitTypeProperty @code{construction-border-color} str
This is the color that frames an unit during its construction.
Defaults to @code{"SandyBrown"}.
@end deffn

@deffn UnitTypeProperty @code{construction-fill-color} str
This is the color that is shown behind an unit during its construction.
Defaults to @code{"brown"}.
@end deffn

@deffn GlobalVariable @code{contour-color} str
This variable is the name of a color to use to draw the elevation
contour lines.  Defaults to @code{"saddle-brown"}.
@end deffn

@deffn GlobalVariable @code{meridian-color} str
This variable is the name of a color to use to draw meridians of
latitude and longitude.  Defaults to @code{"black"}.
@end deffn

@deffn GlobalVariable @code{frontline-color} str
This variable is the name of a color to use to draw country borders
against other countries.  Defaults to @code{"red"}.
@end deffn

@deffn GlobalVariable @code{country-border-color} str
This variable is the name of a color to use to draw country borders
against unpopulated areas.  Defaults to @code{"pink"}.
@end deffn

@deffn GlobalVariable @code{shoreline-color} str
This variable is the name of a color to use to draw shorelines (liquid
adjacent to non-liquid terrain).  Defaults to @code{"blue"}.
@end deffn

@deffn TableTT @code{drawable-terrain} t1 t2 -> t/f
This table is true when terrain of type @var{t1} should be drawn over
terrain of @var{t2}.  In practice, you would set this to @code{false} to
suppress the drawing of terrain that extends into an inappropriate
types, such as river connections protuding into lakes or seas.  Defaults
to @code{true}.
@end deffn

@deffn MaterialTypeProperty @code{resource-icon} n
This is a value between 1 and 4 that indicates that a material type is
to be drawn in each cell indicating that an advanced unit is producing
material in that cell.  The value is used by the Mac interface to select
one of several icons.
@end deffn

@node The Random State

@subsection The Random State

It is useful to be able to restart the random number generator
consistently.

@deffn GlobalVariable @code{random-state} n
This variable is the state of the random number generator.  If this is
not used, then the initial state of the random number generator will be
set in a system-dependent way.
@end deffn

@node Debugging Support

@subsection Debugging Support

@deffn Form @code{print} value
This form prints to a console or file (depending on the interface) the
object @var{value}, in GDL syntax.
@end deffn

@node Files and Directories

@section Files and Directories

This section defines file and directory structure for using GDL.  This
is not required; for instance, an implementation may choose to handle
GDL by reading it from strings compiled into the program.  However, the
standard @i{Xconq} library and implementation does adhere to the
conventions described here.

A game module is a set of forms in a text file, which has an extension
of @code{.g}.

By convention, the first form in the file is a @code{game-module} form
that defines properties of the module.  If the interface has any sort of
preview for a particular module, it can then read only the first form,
rather than the entire file.

Some interfaces include a game selection dialog, which lists a set of
games from which to choose, along with a little information about each.
The file @code{game.dir} in the library directory contains this list,
which is simply a list of module name strings:
@example
(  ;; games that should appear in new game selection dialogs
"1756"
"cave"
"cherbourg"
"classic"
"coral-sea"
"crater-lake"
)
@end example

@i{Xconq} does not currently enforce any sort of standard on file names,
but for maximum portability, the file name should not include mixed
case, it should consist only of alphabetic and numeric characters and
hyphen, and should be less than 12 characters in length, with 8 of those
distinct from any other name in the same directory.  Since @i{Xconq}
implementations typically use the file name as a way to find modules,
these restrictions should apply to module names as well.

Image files are library files with the extension @code{.imf}.  Usually
each image file contains a group of images related in some way, perhaps
by a common theme or by use in a particular game. @i{Xconq}
implementations find images either by a method specific to the platform
(such as resource files), or by looking up the image's location in the
image directory @code{imf.dir}.  The image directory is just a set of
pairs of image name and imf file, with markers at beginning and end of
the file:
@example
ImageFamilyName FileName
amulet fantasy.imf
ant insects.imf
anvil-and-crown fantasy.imf
ap standard.imf
archer ancient.imf
. .
@end example
Note that while @code{game.dir} is a GDL-syntax form, @code{imf.dir} is
not.  It should rarely be necessary to modify @code{imf.dir} directly;
the scripts @code{makedir.sh} and @code{makedir.pl} in the standard
library directory are Unix shell and Perl scripts, each of which will
generate @code{imf.dir} from a given list of files, such as @code{*.imf}
in the library.  You should run one of these after adding a new image to
a library image file.

