1@node Reference Manual 2 3@chapter Reference Manual 4 5This manual is the complete description of GDL. The style is somewhat 6terse; for more detail on how to use GDL to design games, see the 7previous chapter. 8 9Please note that the current version of @i{Xconq} may not fully 10implement all of the constructs or combinations of constructs described 11here. Any such omissions should be regarded as bugs and reported as 12such. 13 14@menu 15* Language Syntax:: 16* Game Module Forms:: 17* World and Area Forms:: 18* Side and Player Forms:: 19* Unit Forms:: 20* Agreements:: 21* Scorekeeper Forms:: 22* History Forms:: 23* Types in General:: 24* Unit Types:: 25* Terrain Types:: 26* Material Types:: 27* Advance Types:: 28* Static Relationships Between Types:: 29* Vision:: 30* Game Initialization:: 31* Synthesis Methods:: 32* Setup Postprocessing:: 33* Naming and Text Generation:: 34* Actions:: 35* Backdrop:: 36* Behavior:: 37* Game End:: 38* Dates and Time:: 39* Image Families:: 40* Other Forms:: 41* Files and Directories:: 42@end menu 43 44@node Language Syntax 45 46@section Language Syntax 47 48GDL is intended to be an easily used, yet powerful, tool for people who 49have little programming experience, but who wish to design Xconq game 50modules. For those who have programmed in Lisp before, GDL uses a 51similar syntax, but @emph{knowledge of Lisp is not required} to 52develop Xconq games. Elements of GDL include such things as numbers, 53lists, and tables. 54 55Formally, GDL is a @emph{declarative}, or nonprocedural, language, rather 56than an imperative language. This means that most of the time, you can 57declare lists, tables, and forms (which will be discussed later) in 58any order you like. There are two significant, though not unreasonable, 59restrictions however. The first is that any symbol, such as a variable 60or the name of a type, must be defined before it is used. The second is 61that a symbol must be used in an appropriate context or scope. This is 62basically to say that you can only assign properties to things for 63which those properties would make sense. Keep in mind that definitions 64can be overwritten with the use of @code{set} and @code{add} (which will 65also be discussed later), and the order in which they are used is 66important. 67 68@menu 69* Lexical Elements:: 70* Conventions Used:: 71* Forms and Evaluation:: 72* Tables:: 73* Modifying Objects:: 74* Symbols:: 75* Lists:: 76* Arithmetic Operations:: 77* Arithmetic Comparisons:: 78* Boolean Comparisons:: 79@end menu 80 81@node Lexical Elements 82 83@subsection Lexical Elements 84 85The Xconq interpreter parses GDL declarations into various lexical 86elements, or tokens. These include numbers, strings, symbols, 87comment delimiters, and list/form/table delimiters. 88 89Numbers are introduced by a decimal digit, plus, or minus signs. They 90may contain only decimal digits, a decimal point, and be followed 91(immediately, no whitespace allowed) by a percent sign. Numbers are 92used where integer quantities, percentages (which may meaningfully 93exceed 100% in many cases), or parts per 10,000 (0.01% increments) are 94expected. Typically numbers are positive. Unless otherwise stated, 95the default value for properties that take numeric values is @code{0}. 96Also of interest is the fact that @code{-1} is often used to indicate 97special behavior of a property or table element, such as "turning off" 98the property, or inheriting a value set in another table. Examples of 99numeric values include the following: @code{99}, @code{65.2%}, 100@code{4.00}, and @code{-1}. 101 102Strings are sequences of characters (letters, digits, punctuation marks, 103etc...) enclosed by doublequotes (@code{"}). 104They may contain any character except ASCII NUL (@code{'\0'}). To 105include a doublequote, use backslash, as in @code{"a \"quoted\" 106string"}. To include a nonprinting or eight-bit character (often 107associated with international characters or ANSI graphics), use 108backslash followed by three octal digits, which will be interpreted as 109an eight-bit character code. (This is mostly the same syntax as in C.) 110Note that game design files may be passed over networks and between 111different kinds of computer systems, so non-ASCII characters should not 112be inserted verbatim into strings. In places where string values are 113expected, the default is @code{""}, unless otherwise stated. 114 115Symbols are sequences of characters that don't include any of the other 116special characters. If you wish to include such characters in a symbol, 117enclose it in vertical bars, for example @code{|foo bar|}. (The bars 118are not part of the symbol.) Symbols are case-sensitive, but this will 119be changed eventually. Examples of symbols include: @code{acp-per-turn}, 120@code{|coastal waters|}, and @code{size}. 121 122Numbers, strings, and symbols all belong to a kind called an @dfn{atom}. 123There are other elements of GDL which are not atoms; these are comments 124and lists. 125 126Comments are enclosed either within @code{#| |#}, or else extend from a 127semicolon @code{;} to the end of the line. A comment is equivalent to 128whitespace, so @code{a#|bcd|#e} is the same as @code{a e}, not 129@code{ae}. The @code{#| |#} style comments can be nested (placed inside 130one another) without trouble, and are allowed to extend across multiple 131lines. Note that @code{#} by itself is nothing special and can be used as 132a normal character in, say, a symbol. 133 134Lists are a sequence of atoms and/or other lists enclosed in parentheses. 135Empty lists can either be represented by the symbol @code{nil} or by the 136list @code{()}. There is nothing similar to the ``dotted pairs'' of Lisp; 137if you don't know what dotted pairs are, then don't worry about it. 138Tables and forms, both of which will be discussed in more detail later, 139are delimited by parentheses in the same manner as lists. Indeed, forms 140can be thought of as lists that start with a special symbol, or keyword. 141Lists might look like @code{(100 90 0)}, @code{("Lansing" "Denver")}, 142@code{((10 0 10) (5 10 15))}, @code{(cv bb dd)}, @code{("1 atom")}, or 143@code{nil}. Some examples of things which are not lists are 144@code{"1 atom"}, which, like it says, is one atom, and: @* 145@code{(10 20 ; This comment can cause problems. )} @* 146because everything past the semicolon is ignored. An acceptable 147alternative would be: @* 148@code{(10 20 #| This comment will not cause problems. |#)} 149 150All of the things mentioned above may range up to a very large size. In 151particular, numbers can generally hold values up to 32767 (sometimes 152referred to as TABHI or PROPHI in the documentation), though most 153games use values such as @code{99}, @code{999}, or @code{9999} for a value 154which is too large to ever be reached. 155Most tables are limited to be 127x127 at largest (which is really quite 156large); this is due to @i{Xconq's} present internal constraints on the 157number of unit types, terrain types, et cetera, that may be defined. 158Although strings and symbols are allowed to be quite large, one should 159exercise caution and keep them around a 100 characters or less in length, 160lest bugs (or ``unexpected features'') be tempted to emerge. 161 162True/false values are just numbers, with no special characteristics. 163 164@deffn GlobalConstant @code{true} 165@end deffn 166@deffn GlobalConstant @code{false} 167These constants are symbolic forms for @code{1} and @code{0}. They are 168identical to numbers, but more descriptive for parameters that are 169boolean-valued. 170@end deffn 171 172Unit, material, and terrain types are distinct objects. However, they 173can be considered to have numeric ``indices'' assigned in order of the 174types' definition. These numbers are not directly visible in GDL, but 175they often affect sorting and ordering. 176 177You may also supply numbers as @var{dice specs}, which are used in 178several tables. The syntax is the familiar 179@code{@var{nn}d@var{mm}[+@var{oo}]}, where @var{nn} is the number of 180dice to throw, @var{mm} is the number of values on each die, and the 181optional @var{oo} is an value to be added to the result. The die are 1820-based, so for instance @code{3d6} yields values between 0 and 15, 183while @code{3d6+3} is equivalent to the result of rolling 3 6-sided 184dice. The range of each value is severely limited; @var{nn} may range 185from 0 to 7, @var{mm} from 0 to 15, and @var{oo} from 0 to 127. 186Internally, dice specs are normal integers, in the range 16384 to 32767. 187 188@node Conventions Used 189 190@subsection Conventions Used 191 192Descriptions of values in this manual follow the conventions listed here. 193 194For parameters described as @var{t/f}, both @code{1}, @code{0} and 195@code{true}, @code{false} may be used. Parameters described as @var{n} 196and @var{n%} are numbers. Parameters described as @var{dist} or 197@var{length} are also numbers, but are in the unit of measure for 198lengths. Parameters described as @var{str} or @var{string} are strings. 199 200Parameters described as @var{u} or @var{ui}, @var{m} or @var{mi}, and 201@var{t} or @var{ti}, are values that must be unit, material, or terrain 202types, respectively. 203 204Parameters described as @var{utype-value-list} match unit types with 205values. They can have several forms: 206 207@itemize @bullet 208 209@item 210@code{(n1 n2 ...)} matches @code{n1} with type 0, etc in order. 211 212@item 213@code{((u1 n1) (u2 n2) ...)} evaluates @code{u1} to get a unit type, 214then matches it with @code{n1}. @code{u1} etc may also be a list of 215types, in which case all the types get matched with @code{n1}. 216 217@end itemize 218 219Other types of lists, such as those defined as @var{side-value-list}, 220are interpreted similarly. For all of these, multiple assignments to 221the same type etc will overwrite quietly. 222 223List values described as @var{interpolation-list} are lists of pairs 224used to derive numerical values by interpolating between the listed 225values. The form of an interpolation list is always @code{((key1 val1) 226(key2 val2) ...))}, where @var{keyi} and @var{vali} are numbers. If the 227input value @var{inp} to an interpolation matches @var{keyi}, the result 228value is @var{vali}. If it is between @var{keyi} and @var{keyi+1}, then 229the result is gotten by linear interpolation, with the result value 230falling somewhere between @var{vali} and @var{vali+1}. Fractional 231values always round down. The @var{keyi} must occur in non-decreasing 232order; it is legitimate for two consecutive keys to be identical, in 233which the result value will be the value associated with the first key. 234If the input value is outside the domain specified by the keys, the 235result depends on the particular parameter; some will extrapolate in 236some appropriate fashion, while others will generate an error or 237warning. To be safe, one should set up key-value pairs for the min and 238max of the input domain. 239 240One place where an interpolation list is used is the 241@code{acp-damage-effect} property that may be assigned to unit types. 242Suppose we have a unit type named @code{battleship}, which has 30 hit 243points and 6 action points when fully healthy. When the battleship 244reaches various levels of damage, we want to affect its ability to 245act to simulate such things as a gun turret or propeller being destroyed. 246To do this, we can assign the @code{acp-damage-effect} property in 247perhaps the following way: @* 248@smallexample 249(unit-type battleship 250(acp-damage-effect ((0 0) (10 2) (20 4) (30 6))) 251) 252@end smallexample 253Now how many action points will the battleship have when it has 15 254hit points? The answer should be 3 action points. When it has 14 hit 255points? 2 action points (remember that fractional parts round down). 256When it has 16 hit points? Again, 3 action points. When it has 10 257hit points? 2 action points (this can be read directly from the 258interpolation list). When it has 4 hit points? 0 action points. 259 260Some values may be boolean expressions. Boolean expressions are lists 261headed by the keywords @code{and}, @code{or}, and @code{not}, and may 262nest recursively. For instance, the expression 263@example 264(and (or false (not false)) true) 265@end example 266is always true. In some contexts, values other than @code{true} and 267@code{false} may appear, in which case the interpretation of those 268values depends on the context. 269 270Some numeric values are @var{stochastic}, meaning that they are partly 271fixed and partly probabilistic in effect. The most common form of this 272is values where the part > 100 is divided by 100, while the value mod 273100 is the probability to add 1 to the first part. Thus a value of 425 274works out to a value of 4, 3/4 of the time, and to 5, 1/4 of the time, 275on average. 276 277Unless otherwise stated, all numeric values default to @code{0}, all 278string values default to @code{""}, and all form values default to 279@code{()}. If one of these defaults has a notable consequence, such as 280inability to perform some action, that will be mentioned. 281 282@node Forms and Evaluation 283 284@subsection Forms and Evaluation 285 286A @dfn{form} is any single expression that appears in the file. 287A GDL file consists of a sequence of forms. Most forms of interest will 288be lists whose first element is a symbol identifying the form. For 289instance, a form beginning with the symbol @code{side} declares a side 290object. When the file containing such a form is read, @i{Xconq} will 291create a side object and fill in any properties as specified by the 292form. (Properties are like properties or attributes - most GDL objects 293have some.) 294 295In most contexts, @i{Xconq} will @dfn{evaluate} an expression before 296using it, such as when filling in an object's property. Numbers and 297strings evaluate to themselves, while symbols evaluate to their 298bindings, as set by @code{set} or @code{define}. Lists evaluate to a 299list of the same length, but with all the elements evaluated, unless the 300first element of the list is a function. In that case, the remaining 301elements of the list are evaluated and given to the function, and its 302result will be the result. 303 304@node Tables 305 306@subsection Tables 307 308A @dfn{table} is a two-dimensional array of values indexed by types. 309Indices can be any pair of unit, material, or terrain type. The set of 310tables is fixed by @i{Xconq}, and all are described below. 311 312@deffn Form @code{table} table-name items@dots{} 313This is the general form to fill in a table. The table named by 314@var{table-name} is filled in from the @var{items}. If an item is an 315atom, then every position in the table is filled in with that item, 316overwriting any previously-specified values. If an item is a list, it 317must be a three-element list of the form @code{(@var{type1} @var{type2} 318@var{value})}. If both @var{type1} and @var{type2} are single types, 319then @var{value} will be put into the table at the position indexed by 320the two types. If one of @var{type1} or @var{type2} evaluates to a 321list, @i{Xconq} will iterate over all members of the list while keeping 322the other type constant, while if both @var{type1} and @var{type2} are 323lists, then @i{Xconq} will iterate over all pairs from the two lists. 324The values used during iteration depend on whether the @var{value} is a 325list. If @var{value} is an atom, then that value will just be used on 326every iteration. If a list, then @i{Xconq} will use successive elements 327of the list while iterating. 328 329If the first member of @var{items} is the symbol @code{add}, then the 330rest of the items will add to the existing contents of the table rather 331than clearing to its default value first. 332@end deffn 333 334The following forms are all equivalent: 335@example 336(table foo (a y 1) (b y 2) (c y 3) (a z 9) (b z 9) (c z 9)) 337 338(table foo ((a b c) y (1 2 3)) ((a b c) (z) 9)) 339 340(define v1 (a b c)) 341(table foo (v1 y (1 2 3)) (v1 z 9)) 342 343(table foo ((a b c) (y z) ((1 2 3) (9 9 9)))) 344 345(table foo (a y 1) (b y 2) (c y 3)) 346(table foo add ((a b c) z 9)) 347@end example 348 349@node Modifying Objects 350 351@subsection Modifying Objects 352 353Since forms normally define or create new objects, GDL defines the 354@code{add} form to modify existing objects. 355 356@deffn Form @code{add} objects property new-values@dots{} 357This form evaluates the atom or list @var{objects} to arrive at the set 358of objects to be modified. Then it uses the @var{new-values} to write 359new data into the property named @var{property} of those objects. The 360@var{new-values} may be a single number or string, or a list. 361@end deffn 362 363@node Symbols 364 365@subsection Symbols 366 367Most of the symbols used in a game module are the predefined ones 368described in this manual. Others are attached to types when the types 369are defined, and still others name objects like units and sides. You 370can also define and set your own symbols to arbitrary values. 371 372@deffn Form @code{define} symbol value 373This form defines the symbol @var{symbol} to be bound to the result of 374evaluating @var{value}. If @var{symbol} is already defined, @i{Xconq} 375will issue a warning, and ignore this form. 376@end deffn 377 378@deffn Form @code{set} symbol value 379This form rebinds the already-bound symbol @var{symbol} to be bound to 380the result of evaluating @var{value}. If @var{symbol} is @emph{not} 381bound already, then @i{Xconq} will issue a warning, but proceed anyway. 382@end deffn 383 384@deffn Form @code{undefine} symbol 385This form destroys any binding of the @var{symbol}. This is allowed for 386any symbol, including already-unbound symbols. 387@end deffn 388 389@node Lists 390 391@subsection Lists 392 393Some transformations can be performed on lists. All of these are transforms 394are non-destructive, which is to say that the original list is not altered, 395but a new list with the transformation applied is returned as a result. 396 397@deffn Function @code{quote} form@dots{} 398This function prevents any evaluation of @var{form}. (This implies that 399the abovementioned evaluation of the argument list does @i{not} happen 400for this ``function''.) 401@end deffn 402 403@deffn Function @code{list} form@dots{} 404This function makes a list out of all the @var{form}. 405@end deffn 406 407@deffn Function @code{append} form@dots{} 408NOTE: If you are not a Lisp programmer, be cautious about inferring what this 409function does based on its name.@* 410This function "appends" all the @var{form} (which may be lists or not) 411into a single list. Another way to state the above is: @code{append} 412gathers everything following it into one list, "flattening out" any lists 413it encounters, and returns the result. 414@end deffn 415 416@deffn Function @code{remove} item list 417This function removes @var{item} from every place that it occurs in 418@var{list}, returning the resulting list. If @var{item} is not found in 419@var{list}, then @var{list} is returned. 420@end deffn 421 422@deffn Function @code{remove-list} list1 list2 423This function removes each item of list @var{list1} from every place that 424it occurs in @var{list2}, returning the resulting list. If no item in 425@var{list1} is found in @var{list2}, then @var{list2} is returned. 426@end deffn 427 428Some examples of the above commands: 429 430The following three are all equivalent examples of quoting; they leave the 431list contents unevaluated when the list is first read.@* 432@code{(quote not "independent")}@* 433@code{'(not "independent")}@* 434@code{`(not "independent")}@* 435 436Quoting is useful for things that should not be evaluated immediately, but 437may be used Xconq later during run time (after the game has been read in).@* 438These things include @code{synthesis-methods} and @code{possible-sides}. 439 440Here is an example of appending:@* 441@code{(define light-sea-u* (destroyer frigate))}@* 442@code{(define heavy-sea-u* (battleship carrier))}@* 443@code{(define sea-u* (append light-sea-u* heavy-sea-u*))}@* 444In the above, two lists are defined. Then those two lists are joined 445into a single list, @code{sea-u*}. Note that @code{sea-u*} would 446be equivalent to the following definition:@* 447@code{(define sea-u* (destroyer frigate battleship carrier))}@* 448and not:@* 449@code{(define sea-u* ((destroyer frigate) (battleship carrier)))}@* 450because the lists were flattened. 451 452Here is another example of appending:@* 453@code{(define wyrms (red-wyrms blue-wyrms green-wyrms))}@* 454@code{(define dragons (append wyrms dragon-turtle))}@* 455In this case @code{wyrms} is a list, while @code{dragon-turtle} might be 456an atom. The definition of @code{dragons} would therefore be equivalent to:@* 457@code{(define dragons (red-wyrms blue-wyrms green-wyrms dragon-turtle))} 458 459Here is an example of removing a single item:@* 460@code{(define land-combat-u* (infantry mechinf cavalry armor))}@* 461@code{(define motor-land-combat-u* (remove infantry land-combat-u*))}@* 462The definition of @code{motor-land-combat-u*} would then be equivalent to:@* 463@code{(define motor-land-combat-u* (mechinf cavalry armor))} 464 465@c Ex-ter-min-ate! Ex-ter-min-ate! 466Here is an example of removing multiple items:@* 467@code{(define monsters (daleks sontarans cybermen ice-warriors))}@* 468@code{(define bad-robots (remove-list (sontarans ice-warriors) monsters))} 469 470And here is a more sophisticated example of removing and appending:@* 471@code{(define nco-ranks (chief senior-chief master-chief))}@* 472@code{(define low-ranks (ensign lieutenant-jg lieutenant commander))}@* 473@code{(define high-ranks (captain commodore r-admiral v-admiral admiral))}@* 474@code{(define rank-sets (nco-ranks low-ranks high-ranks))}@* 475@code{(define com-ranks (append (remove nco-ranks rank-sets)))}@* 476which is equivalent to:@* 477@code{(define com-ranks (append low-ranks high-ranks))}@* 478which is equivalent to:@* 479@code{(define com-ranks (ensign lieutenant-jg lieutenant commander captain commodore r-admiral v-admiral admiral))}@* 480One should note that in the above example, a list, @code{nco-ranks}, was 481treated as the item to remove. 482 483The above example can also be done in terms of @code{remove-list} instead:@* 484@code{(define all-ranks (append nco-ranks low-ranks high-ranks))}@* 485@code{(define com-ranks (remove-list nco-ranks all-ranks))} 486 487@node Arithmetic Operations 488 489@subsection Arithmetic Operations 490 491GDL supports some basic mathematical operations. Addition, subtraction, 492multiplication, and division are all available. To use an operator, it 493must be at the start of a new form; everything after it until the end of 494that form will be interpreted as operands. 495 496All four of the basic operators can operate on numbers, lists of numbers, 497and symbols which are bound to either numbers or lists of numbers, and 498any combination thereof. The only constraint is that all lists must be the 499same lengths as one another, with the exception that empty lists are allowed 500and will simply be skipped over. When a number is operated with a list, 501that number is operated with each item of the list. When a list is 502operated with a list, each item of the first operand list is operated 503with the item in the corresponding position of the second operand list. 504Thus, when a number is operated with a number, a number is always returned 505as the result. When a number is operated with a list or vice versa, a list 506is always returned as the result. When a list is operated with a list, then 507another list is always returned as the result. 508 509Operators forms can be nested inside one another. Multiple operators 510within the same operator form are not allowed. Precedence is determined 511by evaluating the innermost (most deeply nested) operators first. 512Association is from left to right. 513 514The results of operations are still subject to the same constraints as 515numbers and lists produced without operations. Value limits, such as 516@code{32767} and @code{-32768}, still apply. Because of this, you should 517be careful not to multiply, add, or subtract quantities that are too large 518in numeric magnitude or you may end up with undesired results. 519 520Another thing to note about numbers is that, to Xconq, @code{10}, 521@code{10%}, and @code{0.10} are all the same thing. Likewise for 522@code{400}, @code{400%}, and @code{4.00}. Generally, when designing a 523game, you should not have to worry about how these number representations 524are handled internally; that is for the Xconq code writers to worry about. 525However, if you are doing math on numbers, this knowledge does come into 526play, unfortunately. For instance, if you use GDL to multiply a plain 527integer by a percent, you will not get a result that is a percentage of the 528integer. Some of the examples below will show you the correct way to deal 529with this and other similar situations. Also note that dice specs are 530treated as numbers internally in Xconq, and so there is a special way to 531manipulate them as well. Again, this will be demonstrated in the examples 532below. 533 534@deffn Function @code{+} operands@dots{} 535Sums all of the @var{operands} together. If only one operand is present, 536then that operand is returned unaltered. If no operands are present, then 537the additive identity, @code{0}, is returned. 538@end deffn 539 540@deffn Function @code{-} operand1 operands@dots{} 541Subtracts all of the @var{operands} from @var{operand1}. If only 542@var{operand1} is present, then @code{0} minus @var{operand1} is 543returned. If no operands are present, then it returns @code{nil}. 544@end deffn 545 546@deffn Function @code{*} operands@dots{} 547Multiplies all the operands together. Must have at least two operands 548to multiply, or else it returns @code{nil}, except when no operands 549are specified, in which case it returns the multiplicative identity, 550@code{1}. 551@end deffn 552 553@deffn Function @code{/} operand1 operands@dots{} 554Divides all of the @var{operands} into @var{operand1}. If less than 555two operands are present, then it returns @code{nil}.@* 556NOTE: Unlike Common Lisp, GDL does not support rational numbers, and 557therefore it is not possible for division with a single operand to return 558the reciprocal of that operand as Common Lisp implementations do. 559Furthermore, since all arithmetic is integer arithmetic in GDL, values 560between integers cannot be represented; numbers between @code{0} and 561@code{1} will appear as @code{0}. 562@end deffn 563 564Here are some examples of addition:@* 565@code{(+ 1 1)}@* 566 returns @code{2}@* 567@code{(+ 1 2 3 4 5)}@* 568 returns @code{15}@* 569@code{(+ 1 (-1 2))}@* 570 returns @code{(0 3)}@* 571@code{(+ (50% 75%) 25%)}@* 572 returns @code{(75% 100%)}@* 573@code{(+ (0.33 0.67) (0.67 1.33))}@* 574 returns @code{(1.00 2.00)}@* 575@code{(define FOOD_RATS_LOSS 20%)}@* 576@code{(define FOOD_ROT_LOSS 10%)}@* 577@code{(define FODD_LOSS (+ FOOD_RATS_LOSS FOOD_ROT_LOSS))}@* 578 is the same as@* 579@code{(define FOOD_LOSS 30%)}@* 580@code{(+ (10 20) (30 40) (50 60) (70 80) (90 0))}@* 581 returns @code{(250 200)}@* 582@code{(+ 10 25 (+ 20 25))}@* 583 returns @code{80}@* 584@code{(+ -4)}@* 585 returns @code{-4}@* 586@code{(+ 190)}@* 587 returns @code{190}@* 588@code{(+)}@* 589 returns @code{0} 590 591Here are some examples of subtraction:@* 592@code{(- 10 5)}@* 593 returns @code{5}@* 594@code{(- 15 5 4 3 2)}@* 595 returns @code{1}@* 596@code{(- 10 (4 5))}@* 597 returns @code{(6 5)}@* 598@code{(- (10 15) 10)}@* 599 returns @code{(0 5)}@* 600@code{(- (1.00 1.50) (0.25 0.45))}@* 601 returns @code{(0.75 1.05)}@* 602@code{(- 50%)}@* 603 returns @code{-50%}@* 604@code{(define burden 25%)}@* 605@code{(define speed-effect (- burden))}@* 606 is equivalent to@* 607@code{(define speed-effect -25%)} 608 609Here are some examples of multiplication:@* 610@code{(* 5 5)}@* 611 returns @code{25}@* 612@code{(* 5 4 3 2 1)}@* 613 returns @code{120}@* 614@code{(* -1 (5 10))}@* 615 returns @code{(-5 -10)}@* 616@code{(* (25% 50%) 5)}@* 617 returns @code{(125% 250%)}@* 618@code{(* (2.00 5.00) (10 5))}@* 619 returns @code{(20.00 25.00)}@* 620@code{(*)}@* 621 returns @code{1} 622 623Here are some examples of division:@* 624@code{(/ 14 2)}@* 625 returns @code{7}@* 626@code{(/ 15 2)}@* 627 also returns @code{7}@* 628@code{(/ 80 100)}@* 629 returns @code{0}@* 630@code{(/ 12 (6 4 3 2))}@* 631 returns @code{(2 3 4 6)}@* 632@code{(/ (15 10) 5)}@* 633 returns @code{(3 2)}@* 634@code{(/ (100% 250%) (2 5))}@* 635 returns @code{(50% 50%)} 636 637To take a percentage of a number, you need to do something like the 638following:@* 639@code{(/ (* 4 50%) 100)}@* 640 which returns @code{2} 641 642To properly multiply a number by a decimal factor, you must do something 643like the following:@* 644@code{(/ (* 5 4.00) 100)}@* 645 which returns @code{20}@* 646@code{(/ (* 40 0.25) 100)}@* 647 which returns @code{10}@* 648@code{(/ (* 3.00 3.00) 100)}@* 649 which returns @code{9.00}, or @code{900} if you prefer to see it that way 650 651To properly multiply a number by a fraction, try something like the 652following:@* 653@code{(/ (* full-speed 4) 5)}@* 654 which returns four-fifths of @code{full-speed} 655 656[ TODO: Write examples of dice spec manipulation. ] 657 658@node Arithmetic Comparisons 659 660@subsection Arithmetic Comparisons 661 662Xconq supports most of the typical Lisp arithmetic comparison operators 663in GDL. In the case where only one expression is present in the comparison 664form, the result is always non-@code{nil}. If any comparison fails, the 665result is @code{nil}. If no comparison fails, then a true result like 666Lisp's @code{t} is returned. 667 668@deffn Function @code{=} exp@dots{} 669Test if all expressions are equal. 670@end deffn 671 672@deffn Function @code{/=} exp@dots{} 673Test if any expression is not equal to another one. 674@end deffn 675 676@deffn Function @code{>} exp@dots{} 677Test if the list of expressions is monotonically decreasing. 678@end deffn 679 680@deffn Function @code{>=} exp@dots{} 681Test if the list of expressions is monotonically nondecreasing. 682@end deffn 683 684@deffn Function @code{<} exp@dots{} 685Test if the list of expressions is monotonically increasing. 686@end deffn 687 688@deffn Function @code{<=} exp@dots{} 689Test if the list of expressions is monotonically nonincreasing. 690@end deffn 691 692@node Boolean Comparisons 693 694@subsection Boolean Comparisons 695 696Xconq supports the three primary boolean comparisons. These comparisons 697are used in places such scorekeepers tests. However, boolean comparisons 698are also used in side-and-side-class lists, and these follow special 699evaluations rules which do not conform to those listed below. Always pay 700attention to the context of the boolean expression so that you can 701understand its evaluation behavior. 702 703@deffn Function @code{and} exp@dots{} 704The result is the last expression if all the operands are non-@code{nil}. 705If any are false, then the result is @code{nil}. 706@end deffn 707 708@deffn Function @code{or} exp@dots{} 709The result is the first non-@code{nil} expression. 710If all are false, then the result is @code{nil}. 711@end deffn 712 713@deffn Function @code{not} exp 714The result is @code{nil}, if the expression is non-@code{nil}. 715Otherwise, the result is equivalent to Lisp's @code{t}. 716@end deffn 717 718@node Game Module Forms 719 720@section Game Module Forms 721 722The game module declaration supplies information about the file as a 723whole. It is optional; if missing, @i{Xconq} will get the module's name 724from its file name, and supply defaults for the other properties. 725 726@deffn Form @code{game-module} [ name ] properties@dots{} 727This form defines the properties of this game module. The optional 728@var{name} is a string that will be used to look up the module in 729libraries. If the @var{name} is supplied, then this form is considered 730to be the definition of the module, and overwrites any 731@code{game-module} form previously appearing in this file. If 732@var{name} is missing, then this form will modify the existing 733description of the module. Although are currently no restrictions 734enforced on the length or character set of a module name, @i{Xconq} may 735warn about a name that does not match the name of the file containing 736these forms. 737@c ; see @xref{Files and Directories} for more detail. 738@end deffn 739 740@deffn ModuleProperty @code{title} string 741If defined, this property is the name by which the module will be 742displayed to players. It is not used internally, so the name can be 743modified freely (unlike the module's name, which may appear in other 744modules). Defaults to the module's name. 745@end deffn 746 747@deffn ModuleProperty @code{blurb} string 748This property is a one-line description that users will see when they 749are deciding whether to play the module. It will be displayed without 750any modification: 751@example 752Welcome to my nightmare! (version 1.0 with stronger goblins) 753@end example 754@end deffn 755 756@deffn ModuleProperty @code{picture-name} string 757This property is the name of a picture that may be displayed along with 758the module's blurb, by those interfaces that support such pictures. 759@end deffn 760 761@deffn ModuleProperty @code{base-game} t/f 762@end deffn 763 764@deffn ModuleProperty @code{instructions} strings@dots{} 765This property is a list of strings that are the instructions on how to 766play the game. 767@end deffn 768 769@deffn ModuleProperty @code{notes} strings@dots{} 770This property is a list of strings comprising the set of detailed 771player's notes for the module. Both the list and each string in the 772list can be of any length. When displayed, the strings are all 773concatenated together, so the division into strings here is just for 774convenience. How these are displayed is up to the interface, but in 775general an empty string signals a new paragraph. 776@end deffn 777 778@deffn ModuleProperty @code{design-notes} strings@dots{} 779This property is a list of strings that are notes addressed to game 780designers. 781@end deffn 782 783@deffn ModuleProperty @code{version} string 784This property is the version of the module. Defaults to @code{""}, 785which indicates that the module's version is undefined. 786@end deffn 787 788@deffn ModuleProperty @code{base-module} name 789This property is the name of a module that must be loaded first. It is 790similar in effect to @code{include}. 791@end deffn 792 793@deffn ModuleProperty @code{default-base-module} name 794This property specifies the name of a module that will be loaded if when 795this module is loaded, no types are defined yet. 796 797This is to allow a module to be used both as a standalone game and as a 798data source for other games. This is true of many maps, for instance. 799@end deffn 800 801@deffn ModuleProperty @code{original-module} name 802@end deffn 803@deffn ModuleProperty @code{original-version} string 804@end deffn 805@deffn ModuleProperty @code{original-variants} list 806These properties record the module's name, version, and variant 807selections before a game save. They are needed to record the game in 808the scorefile usefully. 809@end deffn 810 811@menu 812* Module Variants:: 813* Including Other Modules:: 814* Conditional Loading:: 815@end menu 816 817@node Module Variants 818 819@subsection Module Variants 820 821Variants are options chosen by players at the start of a game. A 822generic variant includes information that will be used for displaying 823the choice to players, the acceptable range of choices, a default 824choice, and additional forms that may be evaluated if particular values 825were chosen. Variant values are always numbers. 826 827@deffn ModuleProperty @code{variants} items@dots{} 828This property defines named variants on this module. Variants appear as 829startup options for the game. Each item has the form 830@example 831([ @var{name} ] @var{type} [ @var{help} ] [ @var{range/default} ] [ @var{clauses} ]) 832@end example 833The optional @var{name} is a string used to identify the choice to the 834players, the @var{type} says what sort of change is being enabled, 835@var{help} is an optional help string, @var{range/default} supplies a 836range of values and a default value among them, and @var{clauses} is a 837list of the form @code{(@var{value} @var{forms}@dots{})}, where the 838@var{forms} are executed while reading if the value of the variant was 839chosen to be @var{value}. A game module may specify any number of 840variants. Defaults to @code{()}. 841@end deffn 842 843A number of commonly useful variant types are predefined. 844 845@deffn VariantType @code{world-size} [ width [ height [ circumf [ lat [ lon ] ] ] ] ] [ clauses ] 846This variant allows players to choose the size of the world. The sizes 847will default to the values in this variant's data. (@var{width} and 848@var{height} can be lists of the form @code{(lo dflt hi)}, with the 849obvious interpretation??) 850@end deffn 851 852@deffn VariantType @code{world-seen} [ dflt ] [ clauses ] 853This variant allows players to choose whether the terrain of the world 854will be known at the start of the game. The default setting will be the 855value @code{dflt}, which may be either @code{true} or @code{false}. 856@end deffn 857 858@deffn VariantType @code{see-all} [ dflt ] [ clauses ] 859This variant allows players to choose whether everything will be seen 860always, as with the global variable @code{see-all}. The default is set 861by @code{dflt}. 862@end deffn 863 864@deffn VariantType @code{sequential} [ dflt ] [ clauses ] 865This variant allows players to choose whether to move simultaneously 866during a turn, or one at a time. The default is set by @var{dflt}. The 867variant works by setting @code{use-side-priority}. 868@end deffn 869 870@deffn VariantType @code{real-time} [ total [ perside [ perturn ] ] ] [ clauses ] 871This variant allows players to choose realtime limits on the game. The 872value will default to the values in this variant's data. 873@c but what about upper/lower limits? 874@end deffn 875 876@deffn VariantType @code{economy} 877This variant enables/disables the backdrop economy. 878@end deffn 879 880@deffn VariantType @code{supply} 881This variant enables/disables the advanced supply line system. 882@end deffn 883 884@node Including Other Modules 885 886@subsection Including Other Modules 887 888You can include one game module in another. 889 890@deffn Form @code{include} module-name [ variant-settings ] 891This form has the effect of inserting the contents of @var{module-name} 892into the current position in the module. @code{game-module} forms in 893the included module are not inserted, although they are remembered and 894may appear in displays. @i{Xconq} will fail completely if the included 895module cannot be found. 896 897Unlike C etc, the same module cannot be included more than once; you 898will get a warning and the module will not be loaded. 899@end deffn 900 901Note that the module names are not file names, so that system-specific 902features like directories and devices cannot be included. The mapping 903between module name and file name is interface-specific, so if you want 904to distribute a module, you should make sure all the module names don't 905have anything nonportable embedded. Alphanumeric characters and hyphens 906are guaranteed to be portable; mixed-case names are not. 907 908@node Conditional Loading 909 910@subsection Conditional Loading 911 912You can control which forms in a module are actually evaluated by using 913conditional loading. 914 915@deffn Form @code{if} test-form sym 916@end deffn 917@deffn Form @code{else} sym 918@end deffn 919@deffn Form @code{end-if} sym 920If @var{test-form} evaluates to @code{true}, then all subsequent forms, 921up until the matching @code{else} or @code{end-if}, will be evaluated. 922If @code{false}, then the forms will be read but not evaluated. All 923forms inside the conditional must be syntactically correct. 924@end deffn 925 926@node World and Area Forms 927 928@section World and Area Forms 929 930The world consists of one @dfn{area}, which is regular in shape and 931consists of a number of @dfn{cells}. Each cell has a type of terrain 932and a number of optional data values. Each kind of per-cell data will 933be called a @dfn{layer} of the area. 934 935@deffn Form @code{world} [ circumference ] properties@dots{} 936This form defines the properties of the world as a whole. 937@end deffn 938 939@deffn Form @code{area} [ width [ height ] ] [ restriction ] properties@dots{} 940This form defines the playing area of the world. The @var{restriction} 941identifies how to get data for this area from subsequent forms that are 942based on larger areas. 943@end deffn 944 945@menu 946* World Properties:: 947* Area Properties:: 948* Layers:: 949* Distances and Elevations:: 950* Temperatures:: 951* Winds:: 952* Clouds:: 953* User:: 954@end menu 955 956@node World Properties 957 958@subsection World Properties 959 960@deffn WorldProperty @code{circumference} dist 961This property is the distance in cells around the entire world (as a 962sphere). Default is @code{360}. 963@end deffn 964 965@deffn WorldProperty @code{axial-tilt} n 966This property defines the extremes of seasonal changes. 967If this is positive and the sunlit region is dynamically changing throughout 968the year, then the sun starts at the vernal equinox. If this is negative and 969the sunlit region is dynamically changing throughout the year, then the sun 970starts at the autumnal equinox. 971@end deffn 972 973@node Area Properties 974 975@subsection Area Properties 976 977@deffn AreaProperty @code{width} n 978@end deffn 979@deffn AreaProperty @code{height} n 980These properties are the width and height of the world, as measured in 981cells. Allowable values range from 3x3 up to 32767x32767, which is one 982billion cells! If only one of these is given, then the other defaults 983to the same value. If neither has been given, then they default to 984@code{60} and @code{30}, respectively. 985@end deffn 986 987In the case of a cylinder, the world wraps around in the x direction, 988and the width is the diameter of the cylinder, while the height is just 989the height in the usual sense. A hexagon world is flat on the top and 990bottom; its width is measured across the middle height, which is the 991largest span, and height is the same as for cylinders. Here are some 992crude pictures, first of an 8x6 cylinder: 993@example 994# # # # # # # # 995 : : + + : : : : 996: : : + ^ : : : 997 : : : : : : : : 998: : : : ^ : : : 999 # # # # # # # # 1000@end example 1001 1002This world is an 8x7 hexagon: 1003@example 1004 # # # # # 1005 # : + + : # 1006 # : : + ^ : # 1007# : : + ^ : : # 1008 # : : : : : # 1009 # : : ^ : # 1010 # # # # # 1011@end example 1012 1013There are two kinds of properties that an area may have: scalar values 1014such as latitude, and layer values such as terrain and elevation. 1015 1016@deffn AreaProperty @code{latitude} n 1017This property is the offset, in cells, from the equator of the middle of 1018the area (height / 2). 1019@end deffn 1020 1021@deffn AreaProperty @code{longitude} n 1022This property is the offset, in cells, from the ``Greenwich Meridian'' 1023of the world. 1024@end deffn 1025 1026@deffn AreaProperty @code{projection} n 1027This property defines the mapping from the world to the area. The 1028default value of @code{0} maps lat,long positions to x,y coordinates 1029directly (with the effect of stretching high latitude terrain 1030horizontally). A value of @code{1} bends x coordinates in towards the 1031middle of the area, proportionally to the latitude (meridians will be 1032curved in a familiar fashion). 1033@end deffn 1034 1035@deffn AreaRestriction @code{restrict} w h x y | @code{reset} 1036This is a special subform that specifies that subsequent layers in an 1037area of size @var{w} x @var{h} will be offset by @var{x},@var{y} and then read 1038into the actual area. (This is useful for setting up a scenario that 1039needs only a subset of a full map.) 1040 1041If the restriction specifies @code{reset} rather than four numbers, 1042it means to cancel the restriction and return to normal area layer 1043processing. 1044 1045Note that an area restriction is not a property, and must always appear 1046before any properties in an area form. 1047@end deffn 1048 1049@node Layers 1050 1051@subsection Layers 1052 1053@dfn{Layers} constitute the bulk of data about an area of the world. 1054Each layer assigns a value to each cell in the area; examples include 1055cell terrain, temperatures, elevations, and so forth. Since there may 1056be many cells in a layer with the same values, each layer uses a common 1057run-length encoding scheme. In this scheme, each horizontal band of 1058cells is a separate text string, and the contents of the string encode 1059individual numeric values, one for each cell. The encoding uses the 1060characters @code{a..~} and @code{:..[} for 0 through 63, and decimal 1061digits followed by commas (or the end of the string) for all other 1062numbers. An optional @code{-} is allowed, and indicates a negative 1063value. Runs of constant value are prefixed with their length, in 1064decimal. The character @code{*} separates run lengths from values 1065expressed as digits. Thus, the string 1066@example 1067"40adaa100,2*-99" 1068@end example 1069represents 46 values in all: 40 zeroes, a three, 2 more zeros, a 100, 1070and two -99s. Although this format is quite unreadable, it has the 1071advantages of compactness and portability; the expectation is that most 1072layer editing will be done on-line. Note that the run encoding is 1073entirely optional. 1074 1075The following subforms at the beginning of layer data have special 1076effects. 1077 1078@deffn LayerSubform @code{constant} n 1079This subform causes every value in the layer to be set to @var{n}. 1080@end deffn 1081 1082@deffn LayerSubform @code{subarea} x y w h 1083This subform indicates that the layer data should be positioned at the 1084given rectangle in the layer. 1085@end deffn 1086 1087@deffn LayerSubform @code{xform} mul add 1088This subform has the effect of first multiplying the raw value by 1089@var{mul}, then adding @var{add} and storing the result into the layer. 1090@end deffn 1091 1092@deffn LayerSubform @code{by-bits} 1093@end deffn 1094 1095@deffn LayerSubform @code{by-char} str 1096This subform specifies that the characters in @var{str} give the 1097encodings of values in the layer. The first character in @var{str} 1098encodes 0, the second encodes 1, and so forth. 1099@end deffn 1100 1101@deffn LayerSubform @code{by-name} name-list 1102[what is the syntax of name-list exactly?] 1103This subform is for generic worlds that are useful across multiple game 1104designs. It has the syntax @code{((sym1 n1) (sym2 n2) ...)}, where 1105@var{symi} is either a symbol or number that is the real value in the 1106layer, and @var{ni} is the value used in the layer's encoding. For 1107example, in the terrain layer, this allows for the matching of terrain 1108types by name, so that if, say, the ``sea'' terrain type was type #0 in 1109one game and type #4 in another, the world would have sea in all the 1110same places after it was read in. In practice, only a few worlds are 1111this general. If a value appears in the layer's data that is not 1112listed, that value will simply go into the layer verbatim. 1113@end deffn 1114 1115@deffn AreaProperty @code{terrain} layer-data@dots{} 1116This property is the actual layer of terrain types for cells. 1117@end deffn 1118 1119@deffn AreaProperty @code{aux-terrain} terrain-type layer-data@dots{} 1120This property fills in values for borders, connections, and coatings. 1121For border and connection terrain, the value is a six-bit number 1122(0..63), with a bit turned on in each direction that there is a border 1123or connection. For coating types, the value is the depth of the 1124coating. 1125@end deffn 1126 1127@deffn AreaProperty @code{features} feature-list layer-data@dots{} 1128This property specifies the nature and location of all geographical 1129features. The @var{feature-list} is a list of lists, where each sublist 1130has the form @code{([@var{id}] @var{typename} @var{name})} where 1131@var{id} is the numerical id referenced in the layer data (defaults to 1132feature's position in the @var{feature-list}), @var{typename} is a 1133symbol or string giving the general type of feature (such as 1134@code{continent}), and @var{name} is the name of the feature (such as 1135@code{"Asia"}). If the name includes the string @code{"%T"}, then the 1136feature's type will be substituted at that position; so for instance the 1137name @code{"%T of Mexico"} with a type @code{gulf} results in a 1138displayed name @code{"Gulf of Mexico"}. 1139@end deffn 1140 1141@deffn AreaProperty @code{material} material-type layer-data@dots{} 1142This property declares the quantity of the given @var{material-type} in 1143each cell of the area. 1144@end deffn 1145 1146@deffn AreaProperty @code{people-sides} layer-data@dots{} 1147This property says which side the people of each cell are on. A 1148@var{side-encoding} of @code{exact} assigns 0 to independence (no side), 11491 to the first side, and so forth; otherwise, the encoding is a list of 1150side names/ids and numbers. 1151@end deffn 1152 1153@deffn AreaProperty @code{control-sides} layer-data@dots{} 1154This property says which side controls each cell. The encoding is the 1155same as for @code{people-sides}. 1156@end deffn 1157 1158@node Distances and Elevations 1159 1160@subsection Distances and Elevations 1161 1162The unit of elevation is arbitrary, with its relation to cells defined by the 1163area's cell width. 1164 1165@deffn AreaProperty @code{elevations} layer-data@dots{} 1166This property is the world elevation data itself. If any elevation 1167falls outside the min/max elevation range for the terrain type of the 1168cell, then it will be truncated appropriately. 1169@end deffn 1170 1171@deffn AreaProperty @code{cell-width} elev 1172This property is the distance across a single cell, expressed as units 1173of elevation. Defaults to @code{1}. 1174@end deffn 1175 1176@node Temperatures 1177 1178@subsection Temperatures 1179 1180Each type of terrain has a temperature range in which it may be found. 1181Any calculation that would fall outside this range will be clipped. 1182 1183The temperature can be set to have a given value at a given elevation. 1184All air temperatures will be interpolated appropriately. 1185 1186@deffn GlobalVariable @code{temperature-floor} n 1187This variable is the lowest possible temperature. 1188@end deffn 1189 1190@deffn GlobalVariable @code{temperature-floor-elevation} n 1191This variable is the value of elevation at which the temperature is 1192always at @code{temperature-floor}. 1193@end deffn 1194 1195@deffn AreaProperty @code{temperatures} layer-data@dots{} 1196This property contains the temperature data itself. If any temperature 1197falls outside the min/max temperature range, then it will be truncated 1198appropriately. 1199@end deffn 1200 1201@node Winds 1202 1203@subsection Winds 1204 1205Winds are defined as having a nonnegative force and a direction. 1206 1207@deffn AreaProperty @code{winds} layer-data@dots{} 1208This property contains the force and direction of the prevailing winds 1209in each cell. 1210@end deffn 1211 1212@node Clouds 1213 1214@subsection Clouds 1215 1216Cloud cover is defined as a layer over the terrain, with a bottom and 1217top and density for each cell. 1218 1219@deffn AreaProperty @code{clouds} layer-data@dots{} 1220This property is the degree of cloud cover over each cell. A value of 1221@code{0} corresponds to clear skies. 1222@end deffn 1223 1224@deffn AreaProperty @code{cloud-bottoms} layer-data@dots{} 1225This property is the altitude above the ground of the bottoms of the 1226clouds. 1227@end deffn 1228 1229@deffn AreaProperty @code{cloud-heights} layer-data@dots{} 1230This property is the vertical thickness of the cloud cover in each cell. 1231@end deffn 1232 1233@node User 1234 1235@subsection User 1236 1237Advanced units' use of the surrounding area is recorded in the user 1238layer. 1239 1240@deffn AreaProperty @code{user} layer-data@dots{} 1241This property indicates which unit is using which cells for production. 1242@end deffn 1243 1244@node Side and Player Forms 1245 1246@section Side and Player Forms 1247 1248@deffn Form @code{side} [ id ] properties@dots{} 1249This form has the effect of declaring a side to exist. If the number or 1250symbol @var{id} is supplied and matches that of a side that has already 1251been created, then the properties will modify the pre-existing side. 1252Otherwise a new side object will be created, with a arbitrarily-chosen 1253numeric id ranging between 1 and @code{sides-max}. If the given 1254@var{id} is a symbol, then the side's numeric id will be bound to that 1255symbol. 1256@end deffn 1257 1258@deffn GlobalVariable @code{sides-min} n 1259The minimum number of sides that are required for a game. A new game 1260cannot be started with fewer than @code{sides-min} sides. Defaults to 1261@code{1}. 1262@end deffn 1263 1264@deffn GlobalVariable @code{sides-max} n 1265The maximum number of sides that are allowed in a game. This is a limit 1266which is set by the designer of the game module. @i{Xconq} also has a 1267built-in upper limit (@code{MAXSIDES}), and this is typically @code{15}. 1268Defaults to @code{MAXSIDES}. 1269@end deffn 1270 1271@deffn GlobalVariable @code{sides-wanted} n 1272The ideal number of sides for a game. This is the initial number of sides 1273that a new game will have during side setup. This should be between 1274@code{sides-min} and @code{sides-max}, inclusive. Defaults to @code{2}. 1275@end deffn 1276 1277@deffn Form @code{side-defaults} properties@dots{} 1278This form sets the defaults for all newly-created sides declared 1279subsequently. These defaults will be set before the new side's 1280properties are interpreted. This form has no effect on existing sides 1281or on side declarations that modify existing sides. 1282@end deffn 1283 1284@menu 1285* Side Name Properties:: 1286* Side Class:: 1287* Status in Game:: 1288* Side Relationships:: 1289* Numbering Units:: 1290* Side-Specific Namers:: 1291* Side Tech Levels:: 1292* Side Views:: 1293* Interaction:: 1294* Doctrine:: 1295* Other Side Properties:: 1296* Independent Side:: 1297* Players:: 1298* Rules of Side Configuration:: 1299@end menu 1300 1301@node Side Name Properties 1302 1303@subsection Side Name Properties 1304 1305If the game design allows, all of these properties can be set at startup 1306by the players (see <side config> and below). Omission of some of these 1307results in suppression or substitution, depending on the interface and 1308the situation. Omission of all name properties allows the side to go 1309unmentioned, which is useful when the concept of ``side'' is useless or 1310confusing to a player (as in some adventure games). All of these 1311properties may be set at any time by any player. 1312 1313@deffn SideProperty @code{name} str 1314This property is the proper name of a side, as a country or alliance 1315name. Examples include @code{"Axis"} and @code{"Hyperborea"}. 1316@end deffn 1317 1318@deffn SideProperty @code{long-name} str 1319This property is the long form of a side's name, as in @code{"People's 1320Republic of Hyperborea"}. Defaults to be the same as the side's name. 1321@end deffn 1322 1323@deffn SideProperty @code{short-name} str 1324This property is an short name or acronym for the side, often just the 1325letters of the long name, as in @code{"PRH"}. 1326@end deffn 1327 1328@deffn SideProperty @code{noun} str 1329This property is the name of an individual unit or person belonging to 1330the side. Defaults to @code{""}, which suppresses any mention of the 1331side when (textually) describing the individual. 1332@end deffn 1333 1334@deffn SideProperty @code{plural-noun} str 1335This property is what you would call a group of individuals. Defaults 1336to the most common plural form of the @code{noun} (in English, the 1337default pluralizer adds an ``s''), so any alternative plural noun, such 1338as @code{"Chinese"}, will need an explicit @code{plural-noun} value. 1339@end deffn 1340 1341@deffn SideProperty @code{adjective} str 1342This property is an adjective that can be used of individuals on the 1343side, as in @code{"Spanish"}. Defaults to @code{""}, which suppresses 1344use of the adjective. 1345@end deffn 1346 1347As a complete example, a side named @code{"Poland"} would have a long 1348name @code{"Kingdom of Poland"}, short name @code{"Po"}, noun 1349@code{"Pole"}, plural noun @code{"Poles"}, and adjective 1350@code{"Polish"}. 1351 1352Alternatively, one can specify a side namer to do the work of naming 1353sides. 1354 1355@deffn GlobalVariable @code{side-namer} namer-id 1356The name of a known namer that will be used to generate the names of 1357all the sides (except the independent side). Defaults to 1358@code{default-side-names}. 1359@end deffn 1360 1361@deffn SideProperty @code{color} str 1362This property is a comma-separated list of colors that represents the 1363side. Defaults to @code{"black"}. 1364@end deffn 1365 1366@deffn SideProperty @code{emblem-name} str 1367This property is the name of a graphical icon that represents the side. 1368An emblem name of @code{"none"} suppresses any emblem display for the 1369side. Defaults to @code{""}, which gives the side a randomly-selected 1370emblem. 1371@end deffn 1372 1373@deffn SideProperty @code{names-locked} t/f 1374If the value of this property is @code{true}, then the player cannot 1375modify any of the side's names. Defaults to @code{false}. 1376@end deffn 1377 1378@node Side Class 1379 1380@subsection Side Class 1381 1382@deffn SideProperty @code{class} str 1383This property is a side's class, which is a keyword that characterizes 1384the side. Any number of sides may be in the same class. 1385@end deffn 1386 1387@node Status in Game 1388 1389@subsection Status in Game 1390 1391Once a side is in the game, it can never be totally removed. However, 1392sides can become inactive. 1393 1394@deffn SideProperty @code{active} t/f 1395This property is @code{true} if the side is still actively participating 1396in the game. If the side has won, lost, or simply withdrew, this will 1397be @code{false}. Any units on a side not in the game are effectively 1398frozen statues; they don't do anything, and are untouchable by anyone 1399else. Defaults to @code{true}. 1400@end deffn 1401 1402@deffn SideProperty @code{status} lose/draw/win 1403This property tells how this side did in the game. Defaults to 1404@code{draw}. 1405@end deffn 1406 1407@deffn GlobalConstant @code{win} 1408@end deffn 1409@deffn GlobalConstant @code{draw} 1410@end deffn 1411@deffn GlobalConstant @code{lose} 1412These constants are the different possible values for a side's status. 1413@end deffn 1414 1415@deffn SideProperty @code{ever-active} t/f 1416This property records if the side was ever active during the course of a 1417game. Sides that were never active (perhaps because they are used in 1418some scenarios of a game design but not others) will not be recorded in 1419the scorefile. 1420@end deffn 1421 1422@deffn SideProperty @code{advantage} n 1423@end deffn 1424@deffn SideProperty @code{advantage-min} n 1425@end deffn 1426@deffn SideProperty @code{advantage-max} n 1427Initial and min/max limits on advantage for the side. All default to 1428the values of the corresponding global variables. 1429@end deffn 1430 1431@node Side Relationships 1432 1433@subsection Side Relationships 1434 1435By default, sides are neutral with respect to each other. 1436 1437@dfn{Control} is a situation where one side can observe and move another 1438side's units, but not vice versa. The controlling side can also just 1439take the units of the controlled side. If the controlled side loses or 1440resigns, then the controlling side automatically gets everything. Both 1441sides must agree to this relationship. 1442 1443@deffn SideProperty @code{controlled-by} side 1444This property refers to the side controlling this one. If 0, then the 1445side is not under control. 1446@end deffn 1447 1448The closest side relationship is one of trust. A trusted side unit's 1449may do anything at any time, including entering and leaving units on the 1450other side, consuming the other side's materials, and so forth. 1451 1452@deffn SideProperty @code{trusts} side-value-list 1453This property is true for any side that is trusted by this side. Note 1454that this relationship need not be symmetrical. Defaults to 1455@code{false} for all sides. 1456@end deffn 1457 1458Note that these parameters apply only to relationships as enforced by 1459@i{Xconq}. In an actual game, both human and robot sides can make 1460agreements and have positive/negative opinions about the other sides. 1461 1462@deffn SideProperty @code{trades} side-value-list 1463This property defines the trading relationship with other sides. 1464@end deffn 1465 1466@node Numbering Units 1467 1468@subsection Numbering Units 1469 1470@deffn SideProperty @code{next-numbers} utype-value-list 1471This property gives the next serial numbers that will be assigned to 1472units acquired by this side. Defaults to @code{1} for each unit type 1473(Dijkstra notwithstanding, that's still where people start numbering 1474things). 1475@end deffn 1476 1477If the unit is of a type that gets numbered (@code{assign-number} 1478property is true), then any unit of that type, acquired by any means 1479whatsoever, will be assigned the @code{next-numbers} value for that type 1480and @code{next-numbers} will be incremented. 1481 1482@node Side-Specific Namers 1483 1484@subsection Side-Specific Namers 1485 1486A side can have its own set of namers (see below) that will be used for 1487units and geographical features associated with that side. 1488 1489@deffn SideProperty @code{unit-namers} utype-value-list 1490This property specifies which namers will be used with which types that 1491the side starts out with or creates new units. These will not be run 1492automatically on captured units or gifts. 1493@end deffn 1494 1495@deffn SideProperty @code{feature-namers} feature-type-value-list 1496This property specifies which namers to use with which geographical 1497features in the side's initial country (if if has one). Defaults to 1498@code{()}. 1499@end deffn 1500 1501@node Side Tech Levels 1502 1503@subsection Side Tech Levels 1504 1505The tech level of a side determines what it can do with each type of unit. 1506 1507@deffn SideProperty @code{tech} utype-value-list 1508This property assigns a tech level to each unit type named. 1509@end deffn 1510 1511@deffn SideProperty @code{init-tech} utype-value-list 1512This property is the tech level at the beginning of the current turn. 1513@end deffn 1514 1515@deffn SideProperty @code{advances-done} atype-value-list 1516This property is the state of the side's research on each advance. A 1517value of -1 indicates that the advance has been achieved. 1518@end deffn 1519 1520@deffn SideProperty @code{advance-goal} atype 1521The research goal that the side is presently working toward. 1522@end deffn 1523 1524@deffn SideProperty @code{current-advance} atype 1525The research topic that the side is presently working on. 1526@end deffn 1527 1528@node Side Views 1529 1530@subsection Side Views 1531 1532View-related properties record the side's knowledge about the world, 1533other units, weather, etc. 1534 1535These properties are necessary only if the relevant globals are set a 1536certain way (@code{see-all} is false, etc). 1537 1538@deffn SideProperty @code{terrain-view} layer-data@dots{} 1539This property is the side's current knowledge of the world's terrain. 1540Defaults to @code{()}. 1541@end deffn 1542 1543@deffn SideProperty @code{terrain-view-dates} layer-data@dots{} 1544This property is the dates of the side's current knowledge of the 1545world's terrain. Defaults to @code{()}. 1546@end deffn 1547 1548@deffn SideProperty @code{aux-terrain-view} ttype layer-data@dots{} 1549This property is the side's current knowledge of the world's aux terrain 1550of type @var{ttype}. Defaults to @code{()}. 1551@end deffn 1552 1553@deffn SideProperty @code{aux-terrain-view-dates} ttype layer-data@dots{} 1554This property is the dates of the side's current knowledge of the 1555world's aux terrain of type @var{ttype}. Defaults to @code{()}. 1556@end deffn 1557 1558@deffn SideProperty @code{unit-views} unit-view@dots{} 1559This property is the side's current knowledge of the positions of units 1560in the world. It is a list of @var{unit-view} objects, where each has 1561the forms @code{(type side id x y)}. Defaults to @code{()}. 1562@end deffn 1563 1564@deffn SideProperty @code{material-view} mtype layer-data@dots{} 1565This property is the side's current knowledge of the amounts of each 1566type of material at each location in the world. Defaults to @code{()}. 1567@end deffn 1568 1569@deffn SideProperty @code{material-view-dates} ttype layer-data@dots{} 1570Defaults to @code{()}. 1571@end deffn 1572 1573If the weather is not always known and up-to-date, then the following 1574properties what is known and when the information was recorded. 1575 1576@deffn SideProperty @code{temperature-view} layer-data@dots{} 1577Defaults to @code{()}. 1578@end deffn 1579 1580@deffn SideProperty @code{temperature-view-dates} layer-data@dots{} 1581Defaults to @code{()}. 1582@end deffn 1583 1584@deffn SideProperty @code{cloud-view} layer-data@dots{} 1585Defaults to @code{()}. 1586@end deffn 1587 1588@deffn SideProperty @code{cloud-bottom-view} layer-data@dots{} 1589Defaults to @code{()}. 1590@end deffn 1591 1592@deffn SideProperty @code{cloud-height-view} layer-data@dots{} 1593Defaults to @code{()}. 1594@end deffn 1595 1596@deffn SideProperty @code{cloud-view-dates} layer-data@dots{} 1597Defaults to @code{()}. 1598@end deffn 1599 1600@deffn SideProperty @code{wind-view} layer-data@dots{} 1601Defaults to @code{()}. 1602@end deffn 1603 1604@deffn SideProperty @code{wind-view-dates} layer-data@dots{} 1605Defaults to @code{()}. 1606@end deffn 1607 1608@node Interaction 1609 1610@subsection Interaction 1611 1612@deffn SideProperty @code{initial-center-at} x y 1613This property is the preferred location at which to center the first map 1614displayed by an interface. 1615@end deffn 1616 1617@deffn SideProperty @code{turn-time-used} seconds 1618This property is the number of (real) seconds that this side has been 1619moving units during the present turn. 1620@end deffn 1621 1622@deffn SideProperty @code{total-time-used} seconds 1623This property is the number of (real) seconds that this side has been 1624moving units during the course of the game. 1625@end deffn 1626 1627@deffn SideProperty @code{timeouts} n 1628This property is the number of ``time outs'' a side gets for the game. 1629@end deffn 1630 1631@deffn SideProperty @code{timeouts-used} n 1632This property is the number of ``time outs'' a side has already used up. 1633@end deffn 1634 1635@deffn SideProperty @code{finished-turn} t/f 1636This property is true if the side has declared that it is finished 1637moving things during this turn. Defaults to @code{false}. 1638@end deffn 1639 1640@deffn SideProperty @code{willing-to-draw} t/f 1641This property is true if the side will go along with any other side that 1642wants to end the game in a draw. Defaults to @code{false}. 1643@end deffn 1644 1645@node Doctrine 1646 1647@subsection Doctrine 1648 1649Doctrines are objects that units consult to decide about individual 1650behavior. 1651 1652@deffn SideProperty @code{doctrines} utype-property-groups@dots{} 1653This property is the side's unit-type-specific doctrine. Each 1654@var{utype-property-group} has the form @code{(@var{unit-types} 1655doctrine)}. Defaults to @code{()}. 1656@end deffn 1657 1658@deffn SideProperty @code{doctrines-locked} t/f 1659This property says whether the docrine-unit type correspondence for the 1660side may be altered during the game. This property does not control 1661whether or not the properties of the doctrines may be altered. Defaults 1662to @code{false}. 1663@end deffn 1664 1665@deffn SideProperty @code{default-doctrine} doctrine-id 1666This property is the base doctrine that applies to all unit types by 1667default. 1668@end deffn 1669 1670@deffn Form @code{doctrine} [ id ] properties@dots{} 1671This form creates a doctrine with the given id and properties. 1672@end deffn 1673 1674@deffn DoctrineProperty @code{resupply-percent} n% 1675This property indicates that when the level of a operationally-consumed 1676material is at @var{n%} of capacity, try to resupply. Defaults to 1677@code{50}. 1678@end deffn 1679 1680@deffn DoctrineProperty @code{rearm-percent} n% 1681This property indicates that when the level of a combat-consumed 1682material is at @var{n%} of capacity, try to resupply. 1683@end deffn 1684 1685@deffn DoctrineProperty @code{repair-percent} n% 1686This property indicates that when the unit's hp is at @var{n%} of max, 1687make a plan to repair. 1688@end deffn 1689 1690@deffn DoctrineProperty @code{construction-run} type-value-list 1691This property is the default number of units to build when construction 1692has been requested. 1693@end deffn 1694 1695@deffn DoctrineProperty @code{locked} t/f 1696This property is true if the properties of the doctrine cannot be 1697modified by the side's player during the game. Defaults to 1698@code{false}. 1699@end deffn 1700 1701@node Other Side Properties 1702 1703@subsection Other Side Properties 1704 1705@deffn SideProperty @code{self-unit} unit 1706This property identifies a unit that represents the side itself. The 1707value may be a unit id, number, string, or symbol. Defaults to 1708@code{0}, which means that no unit represents the side. See below for 1709more details on self units. 1710@end deffn 1711 1712@deffn SideProperty @code{units} list 1713This property is a weighted list of units that could be given to the 1714side during setup in order to satisfy the side's @code{start-with} 1715numbers. 1716@end deffn 1717 1718@deffn SideProperty @code{treasury} mtype-value-list 1719This property is the quantity of each type of material belonging 1720to the side as a whole, independent of materials in specific units. 1721@end deffn 1722 1723@deffn SideProperty @code{priority} n 1724The order in which the side will get to act, relative to other sides and 1725to units. Defaults to @code{-1}. Note that the @code{sequential} 1726variant will automatically cause side priority to be set to nonnegative 1727values, unless the value is already nonnegative. 1728@end deffn 1729 1730@deffn SideProperty @code{action-priorities} (utype val)@dots{} 1731This property is the acting priority of units belonging to the side. 1732@end deffn 1733 1734@deffn SideProperty @code{scores} (skid val)@dots{} 1735This property is the current values of any numeric scores being kept for 1736the side. It is a list of pairs of scorekeeper id and value. Defaults 1737to @code{()}. 1738@end deffn 1739 1740@deffn SideProperty @code{attack-stats} n@dots{} 1741@end deffn 1742@deffn SideProperty @code{hit-stats} n@dots{} 1743These properties are the raw counts of attacks and hits, by attacking 1744and defending unit types. Default to @code{()}. 1745@end deffn 1746 1747@deffn SideProperty @code{gain-counts} n@dots{} 1748@end deffn 1749@deffn SideProperty @code{loss-counts} n@dots{} 1750These properties are the raw counts of unit gains and losses, organized 1751by unit type and gain/loss reason. 1752@end deffn 1753 1754@deffn Form @code{independent-units} properties@dots{} 1755Like the @code{side} form, but sets properties for independent units. 1756@end deffn 1757 1758@deffn SideProperty @code{ui-data} data@dots{} 1759This property contains interface-specific data for the side. This is 1760mainly for preservation across game save/restores. The property's value 1761has the form 1762@example 1763@code{((interface-type data) (interface-type data) ...)} 1764@end example 1765so that each interface can maintain its own data separately. 1766@end deffn 1767 1768@deffn SideProperty @code{ai-data} data@dots{} 1769This property is information about the AIs associated with a side. The 1770property's value has the form 1771@example 1772@code{((ai-type data) (ai-type data) 1773...)} 1774@end example 1775so that each type of AI can maintain its own data separately. The form 1776and meaning of each AI's data is specific to it alone. 1777@end deffn 1778 1779@deffn SideProperty @code{standing-order} data@dots{} 1780This property contains the list of standing orders for the side. 1781@end deffn 1782 1783@deffn GlobalConstant @code{always} 1784This symbol indicates a standing order that is always to be executed 1785by a unit. 1786@end deffn 1787@deffn GlobalConstant @code{@@} 1788This symbol indicates a standing order that units of the specified 1789types are to execute when at a given location. 1790@end deffn 1791@deffn GlobalConstant @code{in} 1792This symbol indicates a standing order that units of the specified 1793types are to execute when occupying a given unit. 1794@end deffn 1795@deffn GlobalConstant @code{near} 1796This symbol indicates a standing order that units of the specified 1797types are to execute when within a given distance of a given location. 1798@end deffn 1799 1800@node Independent Side 1801 1802@subsection Independent Side 1803 1804The independent side is in most ways a side like the others, but 1805in other ways it is incomplete. For instance, independent units 1806act, well, independently of each other. 1807 1808@deffn GlobalVariable @code{no-indepside-ingame} t/f 1809This variable is true if the game should not allow the players to make 1810the independent units active. This is appropriate for historical games 1811where all the participating side are predefined, for instance. 1812@end deffn 1813 1814@deffn GlobalVariable @code{indepside-has-ai} t/f 1815This is true if an AI should be created for the independent side. 1816@end deffn 1817 1818@deffn GlobalVariable @code{indepside-can-build} t/f 1819This is true if independent units may construct new units. 1820@end deffn 1821 1822@deffn GlobalVariable @code{indepside-can-develop} t/f 1823This is true if independent units may develop their technology. 1824@end deffn 1825 1826@node Players 1827 1828@subsection Players 1829 1830Player objects are rarely necessary when building game designs; they 1831typically only appear in saved games, in order to ensure that the same 1832players get the same sides upon restoration. 1833 1834@deffn SideProperty @code{player} id 1835This property is the unique identifier of a player that is running this 1836side. Defaults to @code{0}, which means that no player has been 1837assigned to the side. 1838@end deffn 1839 1840@deffn Form @code{player} [ id ] properties@dots{} 1841This form defines a player. If the @var{id} is supplied and matches the 1842id of an existing player, then the player object is updated using the 1843@var{properties}, otherwise a new player object will be created, using 1844the given @var{id} if supplied, otherwise creating a new value. 1845@end deffn 1846 1847@deffn GlobalVariable @code{player-sides-locked} t/f 1848This variable is @code{true} if the player/side assignment may not be 1849changed while the game is starting up. Defaults to @code{false}. 1850@end deffn 1851 1852The number of players must always be less than the number of sides 1853(sides without players just don't do anything). 1854 1855@deffn PlayerProperty @code{name} str 1856This property identifies the player by name. 1857@end deffn 1858 1859@deffn PlayerProperty @code{config-name} str 1860This property identifies a particular set of doctrine and other 1861definitions that the player is using. 1862@end deffn 1863 1864@deffn PlayerProperty @code{display-name} str 1865This property identifies the display being used by the player's 1866interface. The interpretation of this value is dependent on the 1867interface in use. 1868@end deffn 1869 1870@deffn PlayerProperty @code{ai-type-name} str 1871This property is the type of AI that will play the side if requested or 1872necessary. The set of choices depends on what has been compiled into 1873@i{Xconq}. (The general-purpose AI type @code{"mplayer"} will usually 1874be available, but is not guaranteed.) An @code{ai-type-name} of 1875@code{""} means that no AI will run this player. 1876@end deffn 1877 1878@deffn PlayerProperty @code{password} str 1879This property is the encoding of a password that must be entered before 1880this player object can be reused successfully. 1881@end deffn 1882 1883@deffn PlayerProperty @code{initial-advantage} n 1884This property is an initial relative strength at which the player should 1885start. Some synthesis methods can use this to give more units or some 1886other advantage to each player according to the requested strength. 1887Defaults to @code{1}. 1888@end deffn 1889 1890@deffn GlobalVariable @code{advantage-min} n 1891@end deffn 1892@deffn GlobalVariable @code{advantage-max} n 1893@end deffn 1894@deffn GlobalVariable @code{advantage-default} n 1895These variables set the bounds and default values for players' initial 1896advantages. Default to @code{1}, @code{9999}, and @code{1}, 1897respectively. 1898@end deffn 1899 1900@i{Xconq} is not guaranteed to be able to be able to set up a game with 1901any combination of player advantages; the limits depend on the 1902capabilities and characteristics of the synthesis methods that use the 1903requested advantages in their calculations. 1904 1905@node Rules of Side Configuration 1906 1907@subsection Rules of Side Configuration 1908 1909The properties of a side can come from a number of different sources 1910(here listed in order of precedence): 1911 1912@itemize @bullet 1913 1914@item 1915Interface-specific sources (X resources, Mac preferences). 1916 1917@c @item 1918@c Game-specific form in player's configuration file. 1919 1920@c @item 1921@c Generic form in player's configuration file. 1922 1923@item 1924The @code{side} form for the side. 1925 1926@item 1927The @code{side-defaults} form for the game. 1928 1929@item 1930General program defaults. 1931 1932@end itemize 1933 1934Note that interface-specific and general config files can never alter 1935certain properties of a side, and can only alter others if they are not 1936locked. 1937 1938@node Unit Forms 1939 1940@section Unit Forms 1941 1942The basic @code{unit} form creates or modifies a unit. 1943 1944@deffn Form @code{unit} id [ type ] properties@dots{} 1945This form defines a unit. If a numeric @var{id} is supplied and matches 1946the id of an existing unit, then that unit will be modified by 1947@var{properties}, and the optional @var{type} will be interpreted as a 1948new type for the unit. Otherwise a new unit will be created, with 1949either @var{id} as its id or a arbitrarily-selected one if @var{id} is 1950already in use. If the unit's id is newly-generated and no type has 1951been specified, then type #0 (first-defined type) will be the type of 1952the unit. An id of @code{0} can never match an existing unit id, so 1953effect will be as if it had been omitted. 1954@end deffn 1955 1956@deffn Form @var{unit-type-name} x y [ side-id ] properties@dots{} 1957This is an abbreviated form, in which the x,y position is required, and 1958an optional side id may be included. The side id will come from 1959@code{unit-defaults} if not specified. The @var{unit-type-name} may be 1960any valid unit type name or defined name. This form always results in a 1961new unit. 1962@end deffn 1963 1964Since there may be many units whose properties are similar, there is a 1965``default unit'' whose properties fill in missing properties in 1966individual unit declarations. 1967 1968@deffn Form @code{unit-defaults} [ modifier ] properties@dots{} 1969This form sets the default values for all subsequent units read in, in 1970this and every other module not yet loaded. The set of defaults is 1971additive, so for instance you can repeatedly change the default side of 1972units. If the symbol @code{reset} has been supplied for the optional 1973@var{modifier}, then all the defaults will be changed to the basic 1974default values, as described in this manual. 1975@end deffn 1976 1977@deffn Symbol @code{reset} 1978This is the symbol used to reset unit defaults; see above. 1979@end deffn 1980 1981@deffn GlobalVariable @code{create-units-from-specs} t/f 1982When true, unit forms actually cause units to be created. When false, 1983the unit forms are saved away and can be used later by a unit form to 1984supply values for properties. Defaults to @code{true}. 1985@end deffn 1986 1987@menu 1988* Unit Properties:: 1989* Unit Action State:: 1990* Unit Plan:: 1991* Goal Types:: 1992* Task Types:: 1993@end menu 1994 1995@node Unit Properties 1996 1997@subsection Unit Properties 1998 1999This section lists properties of individual units. In general, they 2000default to the most common or reasonable values, so need not always be 2001specified, even in a saved game. 2002 2003@deffn UnitProperty @code{@@} x y [ z ] 2004This property is the position of the unit. Defaults to @code{-1,-1,0}, 2005which causes the unit to be placed randomly. The optional altitude 2006@var{z} can also be set separately with the property @code{z} below. If 2007@i{z} is even and the unit is in the open, then the unit's altitude is 2008@i{z/2}; if @i{z} is odd, then @i{(z-1)/2} is the type of connection 2009terrain that the unit is on. 2010@end deffn 2011 2012@deffn UnitProperty @code{z} z 2013This property is identical to the optional z part of the @code{@@} 2014property. 2015@end deffn 2016 2017@deffn UnitProperty @code{s} side 2018This property is the side of the unit. It can be either a side name, 2019noun, or adjective (string) or an id (number). A value of @code{0} or 2020@code{"independent"} means that the unit is independent. 2021@end deffn 2022 2023@deffn UnitProperty @code{os} side 2024This property is the original side of the unit. It can be either a side 2025name, noun, or adjective (string), or an id (number). A value of 2026@code{0} or @code{"independent"} means that the unit is/was originally 2027independent. Defaults to the unit's actual side when first read in or 2028created. 2029@end deffn 2030 2031@deffn UnitProperty @code{#} n 2032This property is the unique numeric id of the unit. Defaults to a 2033game-selected value. 2034@end deffn 2035 2036@deffn UnitProperty @code{n} str 2037This property is the name of the unit. 2038@end deffn 2039 2040@deffn UnitProperty @code{nb} n 2041This property is the number of the unit, which starts at @code{1} and 2042goes up. Defaults to @code{0}, which means that the unit is unnumbered. 2043@end deffn 2044 2045@deffn UnitProperty @code{cp} n 2046This property is the current completeness of the unit. If negative, 2047indicates that the unit will appear at a time and place specified by the 2048@code{appear} x-property. Defaults to the @code{cp} for the type. 2049@end deffn 2050 2051@deffn UnitProperty @code{hp} n 2052This property is the current hit points of the unit. Will be restricted 2053to the range [0, hp-max]. An hp of 0 means that the unit is dead and 2054will not appear in the game. Defaults to @code{hp-max} for the unit's 2055type. 2056@end deffn 2057 2058@deffn UnitProperty @code{cxp} cxp 2059This property is the combat experience of the unit. Experience starts 2060at 0 for new units and goes up with each engagement in combat. 2061@end deffn 2062 2063@deffn UnitProperty @code{mo} n 2064This property is the morale of the unit. Morale ranges from 0 to a 2065maximum set by @code{morale-max}. 2066@end deffn 2067 2068@deffn UnitProperty @code{trk} n 2069This property is a bit vector indicating the sides that are currently 2070tracking the unit's movements. The unit's own side is not included. 2071@end deffn 2072 2073@deffn UnitProperty @code{m} mtype-value-list 2074This property is the amounts of supplies being carried by the unit. 2075Defaults to @code{0} for each material type. 2076@end deffn 2077 2078@deffn UnitProperty @code{tp} utype-value-list 2079This property is the level of tooling to build each type of unit. 2080Defaults to @code{0} for each unit type. 2081@end deffn 2082 2083@deffn UnitProperty @code{in} x 2084This property is the id, name, or symbol of the unit's transport. 2085Defaults to @code{0}, meaning that unit is not in any transport. 2086@end deffn 2087 2088@deffn UnitProperty @code{opinions} side-value-list@dots{} 2089This property is the unit's true feelings towards each side, including 2090its own side. Defaults to @code{0} for each side. 2091@end deffn 2092 2093@deffn UnitProperty @code{appear} n 2094This property is the turn on which a unit will appear. The unit's cp 2095must also be negative, and its position must be negatives of its 2096position. Defaults to @code{-1}. 2097@end deffn 2098 2099@deffn UnitProperty @code{disappear} n 2100This property is the turn on which a unit will disappear from the game. 2101Occupants will be ejected if possible; otherwise they will disappear 2102also. Defaults to @code{-1}. 2103@end deffn 2104 2105@deffn UnitProperty @code{autoplan} n 2106This property is true when the unit should choose its own research 2107topics. 2108@end deffn 2109 2110@deffn UnitProperty @code{autobuild} n 2111This property is true when the unit should choose its own construction 2112task. 2113@end deffn 2114 2115@deffn UnitProperty @code{autoresearch} n 2116This property is true when the unit should choose its own research 2117topics. 2118@end deffn 2119 2120@deffn UnitProperty @code{creation-id} n 2121The ID of the unit created by this unit. Reset once the building stage 2122starts. 2123@end deffn 2124 2125@deffn UnitProperty @code{curadv} n 2126This property is the current advance that the unit is researching. 2127@end deffn 2128 2129@deffn UnitProperty @code{popul} n 2130This property is the unit's population (currently unused). 2131@end deffn 2132 2133@deffn UnitProperty @code{prod} mtype-value-list 2134This property is the unit's production for each material type. 2135@end deffn 2136 2137@deffn UnitProperty @code{sym} symbol 2138This property is a symbol that is unique to this unit. This symbol may 2139appear instead of a unit id, for instance as the value of the property 2140@code{in}. Defaults to @code{()}. 2141@end deffn 2142 2143@deffn UnitProperty @code{sides} list 2144This property is a list of side names that the unit may be given to 2145during setup. (See side property @code{units}.) Defaults to @code{()}. 2146@end deffn 2147 2148@node Unit Action State 2149 2150@subsection Unit Action State 2151 2152@deffn UnitProperty @code{acp} n 2153This property is the number of action points left to the unit for this 2154turn. 2155@end deffn 2156 2157@deffn UnitProperty @code{acp0} n 2158This property is the initial number of action points for this turn, 2159computed at the beginning of the turn. 2160@end deffn 2161 2162@deffn UnitProperty @code{am} n 2163This property is the actual number of moves (cell entries) executed so 2164far in the current turn. 2165@end deffn 2166 2167@deffn UnitProperty @code{a} action 2168This property is the next action that the unit will perform. 2169@end deffn 2170 2171@node Unit Plan 2172 2173@subsection Unit Plan 2174 2175@deffn UnitProperty @code{plan} type [ creation-turn ] properties@dots{} 2176This property describes the unit's current plan. 2177@end deffn 2178 2179@deffn PlanType @code{none} 2180A unit with this type of plan does nothing. It is used when a side has 2181no player. 2182@end deffn 2183 2184@deffn PlanType @code{passive} 2185This plan type is for units on a side that is being run directly by the 2186side. This is the normal plan type for units when a human player is 2187playing. 2188@end deffn 2189 2190@deffn PlanType @code{defensive} 2191This plan type is for units that defend areas or other units. 2192@end deffn 2193 2194@deffn PlanType @code{offensive} 2195This plan type is for units that are to be aggressive. 2196@end deffn 2197 2198@deffn PlanType @code{exploratory} 2199This plan type is for units that explore the world. 2200@end deffn 2201 2202@deffn PlanType @code{colonizing} 2203This plan type is for units to build more units (like cities) that can 2204themselves build more units. 2205@end deffn 2206 2207@deffn PlanType @code{improving} 2208This plan type is for units to improve themselves, such as by adding 2209special types of occupants. 2210@end deffn 2211 2212@deffn PlanType @code{random} 2213A unit with this plan type will act randomly. 2214@end deffn 2215 2216@deffn PlanProperty @code{goal} goal 2217This property is the main goal of a unit's plan. Defaults to @code{()}. 2218@end deffn 2219 2220@deffn PlanProperty @code{formation} goal 2221This property is the formation goal of a unit's plan. If defined, it is 2222a position goal that the unit should try to achieve when it is not 2223trying to achieve the main goal. Defaults to @code{()}. 2224@end deffn 2225 2226@deffn PlanProperty @code{tasks} tasks@dots{} 2227This property is the complete task agenda for the unit's plan. It is a 2228list of tasks. Defaults to @code{()}. 2229@end deffn 2230 2231@deffn PlanProperty @code{asleep} t/f 2232This property is true if the unit is asleep. Defaults to @code{false}. 2233@end deffn 2234 2235@deffn PlanProperty @code{reserve} t/f 2236This property is true if the unit is in reserve. Defaults to 2237@code{false}. 2238@end deffn 2239 2240@deffn PlanProperty @code{delayed} t/f 2241This property is true if the unit's activity has been delayed until all 2242others have acted. Defaults to @code{false}. 2243@end deffn 2244 2245@deffn PlanProperty @code{wait} t/f 2246This property is true if the unit is waiting for orders. Defaults to 2247@code{false}. 2248@end deffn 2249 2250@deffn PlanProperty @code{ai-control} t/f 2251This property is true if the unit can be controlled by any AI associated 2252with the side. Defaults to @code{true}. 2253@end deffn 2254 2255@deffn PlanProperty @code{supply-alarm} t/f 2256This property is true if the unit should react when supply is low. 2257Defaults to @code{false}. 2258@end deffn 2259 2260@deffn PlanProperty @code{supply-is-low} t/f 2261This property is true if the unit considers its supply to be low. 2262Defaults to @code{false}. 2263@end deffn 2264 2265@deffn PlanProperty @code{wait-transport} t/f 2266This property is true if the unit is waiting for transport. Defaults to 2267@code{false}. 2268@end deffn 2269 2270@deffn PlanProperty @code{initial-turn} turn 2271This property is the turn upon which a plan should go into effect. 2272@end deffn 2273 2274@deffn PlanProperty @code{final-turn} turn 2275This property is the turn upon which a plan should be removed. If the 2276value is @code{0}, then the plan is not scheduled to be removed. 2277@end deffn 2278 2279@node Goal Types 2280 2281@subsection Goal Types 2282 2283The possible types of goals are these: 2284 2285@deffn GoalType @code{no-goal} 2286@end deffn 2287 2288@deffn GoalType @code{won-game} 2289@end deffn 2290 2291@deffn GoalType @code{lost-game} 2292@end deffn 2293 2294@deffn GoalType @code{world-is-known} 2295@end deffn 2296 2297@deffn GoalType @code{vicinity-is-known} 2298@end deffn 2299 2300@deffn GoalType @code{positions-known} 2301@end deffn 2302 2303@deffn GoalType @code{cell-is-occupied} 2304@end deffn 2305 2306@deffn GoalType @code{vicinity-is-held} 2307@end deffn 2308 2309@deffn GoalType @code{has-unit-type} 2310@end deffn 2311 2312@deffn GoalType @code{has-unit-type-near} 2313@end deffn 2314 2315@deffn GoalType @code{has-material-type} 2316@end deffn 2317 2318@deffn GoalType @code{keep-formation} 2319@end deffn 2320 2321@deffn GoalType @code{find-spot-to-build} 2322@end deffn 2323 2324@node Task Types 2325 2326@subsection Task Types 2327 2328This section lists all the types of tasks that a unit may perform. 2329Every task includes the two parameters @var{ex} and @var{re}; the first 2330is a record of how many times the task has been executed, and the second 2331records how many times the task has failed. (@i{Xconq} will retry a 2332failed task several times before abandoning it.) 2333 2334@deffn TaskType @code{build} ex re u n n2 unit-id 2335This type of task directs the unit to build @var{n} units of type 2336@var{u}. @var{n2} is the number already built in the run and 2337@var{unit-id} is the (optional) id of a unit already being built. 2338@end deffn 2339 2340@deffn TaskType @code{capture} ex re unit-id 2341@end deffn 2342 2343@deffn TaskType @code{collect} m x y 2344This type of task directs the unit to acquire material of type @var{m} 2345at or around @var{x},@var{y} and to deliver it to the nearest unit that can 2346accept the material. 2347@end deffn 2348 2349@deffn TaskType @code{disband} ex re 2350This type of task directs the unit to disband itself. 2351@end deffn 2352 2353@deffn TaskType @code{hit-position} ex re x y z 2354This type of task directs the unit to attack or fire on any unfriendly 2355units at the given location. 2356@end deffn 2357 2358@deffn TaskType @code{hit-unit} ex re unit-id 2359@end deffn 2360 2361@deffn TaskType @code{move-dir} ex re dir n 2362This type of task directs the unit to move in direction @var{dir} for a 2363distance of @var{n} cells. 2364@end deffn 2365 2366@deffn TaskType @code{move-to} ex re x y z dist 2367This type of task directs the unit to move to a distance of no more than 2368@var{dist} cells from the given location. 2369@end deffn 2370 2371@deffn TaskType @code{occupy} ex re unit-id 2372This type of task directs the unit to attempt to enter the given 2373@var{unit-id}, moving adjacent to it first if necessary. 2374@end deffn 2375 2376@deffn TaskType @code{pickup} ex re unit-id 2377This type of task directs the unit to move towards the given 2378@var{unit-id}. 2379@end deffn 2380 2381@deffn TaskType @code{repair} ex re unit-id 2382@end deffn 2383 2384@deffn TaskType @code{resupply} ex re 2385This type of task directs the unit to replenish its supplies, whether by 2386doing more production or by moving to another unit that has supplies 2387available. 2388@end deffn 2389 2390@deffn TaskType @code{sentry} ex re n 2391This task type directs the unit to stay where it is for the next @var{n} 2392turns. 2393@end deffn 2394 2395@node Agreements 2396 2397@section Agreements 2398 2399@deffn Form @code{agreement} [ id ] properties@dots{} 2400This form defines an agreement among a set of sides. The name/id is a 2401unique internal identifier. 2402@end deffn 2403 2404@deffn AgreementProperty @code{type-name} str 2405This property is the name of the general type of agreement, such a 2406trade. Defaults to @code{""}. 2407@end deffn 2408 2409@deffn AgreementProperty @code{title} str 2410This property is the player-visible name of the agreement. Defaults to 2411@code{""}. 2412@end deffn 2413 2414@deffn AgreementProperty @code{terms} forms@dots{} 2415This property is the list of terms of the agreement. Defaults to 2416@code{()}. 2417@end deffn 2418 2419@deffn AgreementProperty @code{drafters} side-list 2420This property is the set of sides writing the agreement. Only drafting 2421sides may modify an agreement. 2422@end deffn 2423 2424@deffn AgreementProperty @code{proposers} side-list 2425This property is the set of sides that initially proposed the agreement. 2426@end deffn 2427 2428@deffn AgreementProperty @code{signers} side-list 2429Before the agreement is made, this property is the proposed list of 2430participants. After the agreeement is made, this is the actual list of 2431participants. 2432@end deffn 2433 2434@deffn AgreementProperty @code{willing-to-sign} side-list 2435This property is all the sides that have already agreed to this 2436agreement, on condition that all the other sides accept it. 2437@end deffn 2438 2439@deffn AgreementProperty @code{known-to} side-list 2440This property is the set of sides that are to know about the agreement 2441when it is signed. 2442@end deffn 2443 2444@deffn AgreementProperty @code{enforcement} form 2445@end deffn 2446 2447@deffn AgreementProperty @code{state} state 2448@end deffn 2449 2450@node Scorekeeper Forms 2451 2452@section Scorekeeper Forms 2453 2454Scorekeepers are the objects that manage scoring, winning, and losing. 2455A game design need not define any scorekeepers, and none are created by 2456default. A scorekeeper may either maintain a numeric score that is used 2457at the end of the game to decide rankings, or simply declare a side to 2458have won or lost. Perhaps it would be better to refer to scorekeepers as 2459victory condition watchers. 2460 2461@deffn Form @code{scorekeeper} name properties@dots{} 2462This form creates or modifies a scorekeeper with the given @var{name}, 2463with the given @var{properties}.@* 2464NOTE: Specifying @var{name} is not supported (as of 2005/02/06). 2465@end deffn 2466 2467@menu 2468* Scorekeeper Properties:: 2469* Scorekeeper Bodies:: 2470* Scorekeeper Functions:: 2471* Scorekeeper Examples:: 2472* Scorefile:: 2473@end menu 2474 2475@node Scorekeeper Properties 2476 2477@subsection Scorekeeper Properties 2478 2479@deffn ScorekeeperProperty @code{title} str 2480This property is a string that identifies the scorekeeper to the 2481players. Defaults to @code{""}. 2482@end deffn 2483 2484@deffn ScorekeeperProperty @code{when} (type [ exp ]) 2485This property is when the scorekeeper will be checked or updated. 2486Defaults to @code{after-turn}. 2487@end deffn 2488 2489@deffn ScorekeeperWhenType @code{before-turn} exp 2490This indicates that the scorekeeper will run at the start of each turn 2491matching @var{exp}, or after every turn if @var{exp} is not given.@* 2492NOTE: This property is currently ignored (as of 2005/01/23). 2493@end deffn 2494 2495@deffn ScorekeeperWhenType @code{after-turn} exp 2496This indicates that the scorekeeper will run at the end of each turn 2497for which @var{exp} is true, or after every turn if @var{exp} is not 2498given. If @var{exp} is a number rather than a full expression, then 2499a test of @var{exp} >= current turn number will be made. See the examples 2500subsection for a full expression. 2501@end deffn 2502 2503@deffn ScorekeeperWhenType @code{after-event} exp 2504This indicates that the scorekeeper will run after every event 2505matching @var{exp}, or after every event if @var{exp} is not given.@* 2506NOTE: Specifying @var{exp} is not supported (as of 2005/01/23). 2507@end deffn 2508 2509@deffn ScorekeeperWhenType @code{after-action} exp 2510This indicates that the scorekeeper will run at the end of each action 2511matching @var{exp}, or after every action if @var{exp} is not given.@* 2512NOTE: Specifying @var{exp} is not supported (as of 2005/01/23). 2513@end deffn 2514 2515@deffn ScorekeeperProperty @code{applies-to} side-and-sideclass-list 2516This property is the set of sides or side classes to which the 2517scorekeeper applies. Scorekeepers apply only to sides that are in the 2518game. Defaults to @code{nil}, which means all sides. 2519@end deffn 2520 2521@deffn ScorekeeperProperty @code{known-to} side-and-sideclass-list 2522This property is the list of sides that know about this scorekeeper, and 2523can see the value of the score for each side that it applies to. 2524Defaults to @code{nil}, which means all sides.@* 2525NOTE: This property is currently ignored (as of 2005/01/23). 2526@end deffn 2527 2528@deffn ScorekeeperProperty @code{trigger} form 2529This property is an expression that is true when it is time to start 2530checking the scorekeeper's main test. Once a scorekeeper is triggered, 2531it remains active. Defaults to @code{false}. 2532@end deffn 2533 2534@deffn ScorekeeperProperty @code{triggered} t/f 2535This property is true if the scorekeeper is currently triggered. 2536Defaults to @code{true}. 2537@end deffn 2538 2539@deffn ScorekeeperProperty @code{do} forms@dots{} 2540This property is a list of forms to execute in order each time the 2541scorekeeper runs. Defaults to @code{()}. 2542@end deffn 2543 2544@deffn ScorekeeperProperty @code{keep-score} t/f 2545If this property is @code{false}, then no numeric score is kept. 2546Defaults to @code{true}. 2547@end deffn 2548 2549@deffn ScorekeeperProperty @code{initial-score} value 2550This property is the value of the score upon game startup. 2551@end deffn 2552 2553@node Scorekeeper Bodies 2554 2555@subsection Scorekeeper Bodies 2556 2557The forms in the body (the @code{do} property) of the scorekeeper may be 2558any of the forms listed here. 2559 2560@deffn ScorekeeperForm @code{last-side-wins} 2561If supplied as the only symbol in the body, then the scorekeeper 2562implements the usual ``last side left in the game wins'' behavior. 2563@end deffn 2564 2565@deffn ScorekeeperForm @code{last-alliance-wins} 2566If supplied as the only symbol in the body, then the scorekeeper 2567implements the ``last alliance left in the game wins'' behavior. For 2568the purposes of this scorekeeper, an alliance means that the sides in 2569the alliance all trust each other. 2570@end deffn 2571 2572@deffn ScorekeeperForm @code{if} test action [ else-action ] 2573If the @var{test} evaluates to a non-@code{nil} result, then the 2574@var{action} will be done. Else, the @var{else-action} will be done, if 2575there is one. 2576@end deffn 2577 2578@deffn ScorekeeperForm @code{cond} (test actions@dots{}) @dots{} 2579This is like Lisp's cond. 2580@end deffn 2581 2582@deffn ScorekeeperForm @code{win} 2583This scorekeeper action causes the side to win immediately. 2584@end deffn 2585 2586@deffn ScorekeeperForm @code{lose} 2587This scorekeeper action causes the side to lose immediately. 2588@end deffn 2589 2590@deffn ScorekeeperForm @code{end} 2591This scorekeeper action ends the game immediately, with a draw for all 2592remaining sides. 2593@end deffn 2594 2595@deffn ScorekeeperForm @code{add-score} exp 2596This adds the result of evaluating @var{exp} to the score of the given 2597side. The value may be a negative number. This form cannot be used 2598with a non-numeric scorekeeper. 2599@end deffn 2600 2601@deffn ScorekeeperForm @code{set-score} exp 2602This sets the result of evaluating @var{exp} as the score of the given 2603side. The value may be a negative number. This form cannot be used 2604with a non-numeric scorekeeper. 2605@end deffn 2606 2607@node Scorekeeper Functions 2608 2609@subsection Scorekeeper Functions 2610 2611Scorekeepers can use all of the general GDL functions such as 2612@code{add}, @code{remove-list}, @code{>=}, etc@dots{}. They can also 2613use special functions, which are mentioned below. Scorekeeper functions 2614can be used in any place where a scorekeeper test expression is allowed. 2615This means that they can be used in @code{when} conditions, in @code{if} 2616test clauses, or the form of @code{set-score}, for example. 2617 2618@deffn ScorekeeperFunction @code{turn} 2619This GDL keyword gives the current turn number. 2620@end deffn 2621 2622@deffn ScorekeeperFunction @code{score} 2623This GDL keyword returns the current score in the current scorekeeper for 2624the current side. A warning will be produced if you attempt to use this 2625keyword with a non-numeric scorekeeper. 2626@end deffn 2627 2628@deffn ScorekeeperFunction @code{sum-uprop} types property 2629The result is the sum of the property values for all units of the given 2630type(s). The property must be an integer value, such as @code{point-value} 2631or @code{hp-max}. The @code{point-value} property is treated specially 2632in that an unit's actual point assignment is used if it exists; if the 2633point assignment does not exist, then the summation behavior is the 2634default, namely the value for the unit type is used. 2635@end deffn 2636 2637@node Scorekeeper Examples 2638 2639@subsection Scorekeeper Examples 2640 2641One of the most simple and ubiquitous scorekeepers is: 2642@smallexample 2643(scorekeeper (do last-side-wins)) 2644@end smallexample 2645This specifies that the last side standing will win. It should be noted 2646that if the independent side is not being controlled by an AI, then it is 2647not considered in this case. If the independent side is being controlled 2648by an AI, then it is considered. 2649 2650If you do not wish a side (such as an AI-controlled independent side) to be 2651considered for a given scorekeeper, then you can use the @code{applies-to} 2652property to restruct which sides the scorekeeper applies to. 2653@smallexample 2654(scorekeeper 2655 (applies-to (not "independent")) 2656 (do last-side-wins) 2657) 2658@end smallexample 2659The above says to apply the scorekeeper to every side except those belonging 2660to the @code{"independent"} side class. By default, only the independent 2661side belongs to that side class. 2662 2663Alternatively, one can use side ID numbers. 2664@smallexample 2665(scorekeeper 2666 (applies-to (not 0)) 2667 (do last-side-wins) 2668) 2669@end smallexample 2670This again excludes the independent side, but, this time, by its exact ID 2671number rather than its side class (to which other sides could belong). 2672 2673We can also talk in terms of inclusion rather than exclusion. 2674@smallexample 2675(scorekeeper 2676 (applies-to ("chaotic" 0)) 2677 (do last-side-wins) 2678) 2679@end smallexample 2680This causes the scorekeeper to be applied to all sides belonging to the 2681@code{"chaotic"} side class as well as the independent side. 2682 2683And, we can include a side class, but exclude specific members of it. 2684@smallexample 2685(scorekeeper 2686 (applies-to (and "chaotic" (not (2 5 7)))) 2687 (do last-side-wins) 2688) 2689@end smallexample 2690Note that the @code{and} is important. All boolean operators must be in 2691the higher levels of the expression. Once a list of side classes and/or 2692side ID numbers is encountered, then boolean evaluation is not performed 2693at the level of the list or below it. The following example is INCORRECT: 2694@smallexample 2695(scorekeeper 2696 (applies-to ("chaotic" (not (2 5 7)))) 2697 (do last-side-wins) 2698) 2699@end smallexample 2700As stated previously, the above example is INCORRECT. It is incorrect 2701because the @code{not} appears inside a list of side classes and side ID 2702numbers. Do not attempt to use this example. 2703 2704If this seems confusing, you may wish to consider a list of side classes 2705and side ID numbers as being shorthand for @code{or} boolean expressions. 2706Thus: 2707@smallexample 2708(scorekeeper 2709 (applies-to (1 2 3)) 2710 (do last-side-wins) 2711) 2712@end smallexample 2713is equivalent to: 2714@smallexample 2715(scorekeeper 2716 (applies-to (or 1 (or 2 3))) 2717 (do last-side-wins) 2718) 2719@end smallexample 2720 2721Now that we have pretty much beaten the @code{applies-to} horse to death, 2722let us move on to @code{when} conditions. By default, @code{when} is 2723assigned @code{nil}, and this is equivalent to @code{after-turn}. So: 2724@smallexample 2725(scorekeeper (do last-side-wins)) 2726@end smallexample 2727is equivalent to: 2728@smallexample 2729(scorekeeper 2730 (when (after-turn)) 2731 (do last-side-wins) 2732) 2733@end smallexample 2734is equivalent to: 2735@smallexample 2736(scorekeeper 2737 (when (after-turn nil)) 2738 (do last-side-wins) 2739) 2740@end smallexample 2741 2742With the turn-granularity scorekeepers, one can use a shorthand notation 2743to specify that they should only run on or after a certain turn number. 2744@smallexample 2745(scorekeeper 2746 (when (after-turn 5)) 2747 (do last-side-wins) 2748) 2749@end smallexample 2750In the above example, the scorekeeper will only be checked at the end of 2751turn 5 and at the ends of all turns thereafter. 2752 2753There is more verbose way of writing this, and this involves a full 2754expression: 2755@smallexample 2756(scorekeeper 2757 (when (after-turn (>= turn 5))) 2758 (do last-side-wins) 2759) 2760@end smallexample 2761The @code{(>= turn 5)} is a test expression. @code{turn} is a keyword 2762that gives back the current turn number. 2763 2764Note that you can put together test expressions using the other available 2765operators. 2766@smallexample 2767(scorekeeper 2768 (when (after-turn (<= turn 30))) 2769 (do last-side-wins) 2770) 2771@end smallexample 2772The above example only runs the scorekeeper at the end of the turn for the 2773first 30 turns, and then the scorekeeper ceases to be relevant. 2774 2775@smallexample 2776(scorekeeper 2777 (title "Every Other Turn") 2778 (when (after-turn (/= (/ turn 2) (/ (+ turn 1) 2)))) 2779 (applies-to (not "independent")) 2780 (do last-side-wins) 2781) 2782@end smallexample 2783Since we do not have a modulo arithmetic operator as of this writing 2784(2005/02/06), if we want to get a scorekeeper to run at some interval, we 2785must use a trick like the above. All above test does is check to see if 2786our current turn number divided by some interval has the same quotient as 2787the next turn number divided by the same interval. If yes, then the 2788scorekeeper should not run. If no, then the scorekeeper should run. 2789Simply replacing @code{2} with @code{3} in the above when condition, you 2790can make your scorekeeper run every third turn, and so and so forth. 2791 2792Scorekeeper bodies can be simple, as already seen, or they can be quite 2793sophisticated. Side scores can be manipulated and victory or loss can be 2794forced based on some condition. 2795 2796@smallexample 2797(scorekeeper 2798 (when (after-turn 20)) 2799 (do (if (>= (sum-uprop victory-point point-value) 15) win)) 2800) 2801@end smallexample 2802In the above example, the scorekeeper checks to see if the sum of the 2803@code{point-value} property of @code{victory-point} units is greater than 2804or equal to 15. If so, then it declares the current side the winner 2805(and, by extension, other sides as losers). 2806 2807Suppose we wanted to modify the @i{Default} game. We could state that 2808any side having more than a certain number of points worth of nukes and 2809capital ships wins. 2810@smallexample 2811(scorekeeper 2812 (do (if (>= (sum-uprop (cv bb nuke) point-value) 50) win)) 2813) 2814@end smallexample 2815 2816We could also do something rather bizarre such as: 2817@smallexample 2818(scorekeeper 2819 (do (if (>= (sum-uprop u* cp) 15000) end)) 2820) 2821@end smallexample 2822 2823The above example ends the game in a draw when any one side builds too much. 2824 2825Scorekeepers can set or add to the score. 2826 2827@smallexample 2828(scorekeeper 2829 (do (set-score (* turn 10))) 2830) 2831@end smallexample 2832 2833The above scorekeeper sets the current side's score to be the turn number 2834times @code{10}. Equivalently, one can write: 2835@smallexample 2836(scorekeeper 2837 (do (add-score 10)) 2838) 2839@end smallexample 2840 2841In this example, the scorekeeper adds 10 to the current side's score 2842every turn. 2843 2844Scorekeeper bodies can be even more complex. 2845 2846@smallexample 2847(scorekeeper 2848 (do ( 2849 (add-score 10) 2850 (if (> (* score turn) 1000) end) 2851 (if (= (sum-uprop capital-city point-value) 0) lose) 2852 )) 2853) 2854@end smallexample 2855 2856So, putting everything together thus far, we might get something like: 2857@smallexample 2858; Last non-indep side standing wins. 2859(scorekeeper 1 2860 (title "Attrition Victory") 2861 (keep-score false) 2862 (applies-to (not "independent")) 2863 (do last-side-wins) 2864) 2865; First side to acquire 30 victory points wins. 2866(scorekeeper 2 2867 (title "Greedy Victory") 2868 (applies-to (not "independent")) 2869 (do ( 2870 (set-score (sum-prop victory-point point-value)) 2871 (if (>= score 30) win) 2872 )) 2873) 2874; First side to produce an overwhelming arsenal wins. 2875(scorekeeper 3 2876 (title "Inevitable Victory") 2877 (applies-to (not "independent")) 2878 (when (after-turn 50)) 2879 (do ( 2880 (set-score (/ (sum-uprop godlike-u* cp) 20)) 2881 (if (>= score 40) win) 2882 (if (>= (sum-prop (append horde-u* nuke) cp) 30000) win) 2883 )) 2884) 2885; Any side that loses nearly all of its commanding units loses. 2886(scorekeeper 4 2887 (title "Loss by Collapsed Command") 2888 (keep-score false) 2889 (do (if (< (sum-uprop leader-u* point-value) 50) lose)) 2890) 2891@end smallexample 2892 2893@node Scorefile 2894 2895@subsection Scorefile 2896 2897@deffn GlobalVariable @code{scorefile-name} str 2898This variable supplies the name of the file to be used for recording 2899scores of people playing the game. The default value is @code{""}, 2900which disables the recording of scores. 2901@end deffn 2902 2903@node History Forms 2904 2905@section History Forms 2906 2907All the important events in a game are logged into a history. 2908 2909@deffn Form @code{evt} date type sides data 2910This form creates a single historical event. The @var{date} is the turn 2911of the event's occurrence, while the @var{sides} is a bit mask of sides 2912that know about the event, or @code{all} if all sides know about it. 2913@end deffn 2914 2915@deffn Symbol @code{all} 2916This is a shorthand for the bitmask of all sides in the game. 2917@end deffn 2918 2919@deffn Form @code{exu} id type x y side props 2920This form defines an ``ex-unit'', which is a record of a unit that 2921existed previously. It is similar to a unit, but has only a few 2922properties; type, id, position, side, name, and number. Property names 2923and semantics are nearly identical to their counterparts for units. 2924@end deffn 2925 2926@deffn EventType @code{log-started} 2927This event records when the recording of events began. Multiple 2928instances of this may occur, for instance if logging were to be turned 2929off and then on again. 2930@end deffn 2931 2932@deffn EventType @code{log-ended} 2933@end deffn 2934 2935@deffn EventType @code{game-started} 2936This event records the actual start of the game. There should only be 2937one in a game's history. 2938@end deffn 2939 2940@deffn EventType @code{game-saved} 2941This event records that the game was saved. 2942@end deffn 2943 2944@deffn EventType @code{game-restarted} 2945This event records that the game was restored and restarted from a saved 2946game. 2947@end deffn 2948 2949@deffn EventType @code{game-ended} 2950@end deffn 2951 2952@deffn EventType @code{side-joined} side 2953This event records when a side joined the game. 2954@end deffn 2955 2956@deffn EventType @code{side-lost} side scorekeeper 2957This event records when a side lost. 2958@end deffn 2959 2960@deffn EventType @code{side-won} side scorekeeper 2961This event records when a side won. 2962@end deffn 2963 2964@deffn EventType @code{side-withdrew} side 2965This event records when a side withdrew from the game. 2966@end deffn 2967 2968@deffn EventType @code{unit-created} side unit 2969This event records the creation of a unit. 2970@end deffn 2971 2972@deffn EventType @code{unit-completed} side unit 2973This event records the completion of a unit. 2974@end deffn 2975 2976@deffn EventType @code{unit-acquired} 2977This event records the acquisition of a unit, for instance as a gift 2978from another side. 2979@end deffn 2980 2981@deffn EventType @code{unit-captured} 2982This event records the capture of a unit, as an outcome of combat or 2983from a direct attempt to capture. 2984@end deffn 2985 2986@deffn EventType @code{unit-moved} unit x1 y1 x2 y2 2987This event records the movement of a unit. 2988@end deffn 2989 2990@deffn EventType @code{unit-name-changed} unit1 unit2 2991This event records that a unit's name was changed. @var{unit1} will be 2992an ex-unit representing the unit under its previous name. 2993@end deffn 2994 2995@deffn EventType @code{unit-type-changed} unit1 unit2 2996This event records that a unit's type was changed. @var{unit1} will be 2997an ex-unit representing the unit with its previous type. 2998@end deffn 2999 3000@deffn EventType @code{unit-assaulted} unit1 unit2 x y 3001@end deffn 3002 3003@deffn EventType @code{unit-damaged} unit hp1 hp2 3004This event records that a unit's hp was reduced from @var{hp1} to 3005@var{hp2}. 3006@end deffn 3007 3008@deffn EventType @code{unit-killed} unit 3009@end deffn 3010 3011@deffn EventType @code{unit-died-in-accident} unit 3012@end deffn 3013 3014@deffn EventType @code{unit-died-from-temperature} unit 3015@end deffn 3016 3017@deffn EventType @code{unit-vanished} unit 3018@end deffn 3019 3020@deffn EventType @code{unit-wrecked} unit 3021@end deffn 3022 3023@deffn EventType @code{unit-wrecked-in-accident} unit 3024@end deffn 3025 3026@deffn EventType @code{unit-revolted} unit 3027@end deffn 3028 3029@deffn EventType @code{unit-surrendered} unit 3030@end deffn 3031 3032@deffn EventType @code{unit-garrisoned} unit 3033@end deffn 3034 3035@deffn EventType @code{unit-disbanded} unit 3036@end deffn 3037 3038@deffn EventType @code{unit-starved} unit 3039@end deffn 3040 3041@deffn EventType @code{unit-left-world} unit 3042@end deffn 3043 3044@deffn EventType @code{unit-merged} unit 3045@end deffn 3046 3047@deffn EventType @code{unit-gone} unit 3048@end deffn 3049 3050The following event types are the results of actions. 3051 3052@deffn EventType @code{action-ok} 3053@end deffn 3054 3055@deffn EventType @code{action-error} 3056@end deffn 3057 3058@deffn EventType @code{cannot-do} 3059@end deffn 3060 3061@deffn EventType @code{insufficient-acp} 3062@end deffn 3063 3064@deffn EventType @code{insufficient-material} 3065@end deffn 3066 3067@deffn EventType @code{too-far} 3068@end deffn 3069 3070@deffn EventType @code{too-near} 3071@end deffn 3072 3073@deffn EventType @code{action-done} 3074@end deffn 3075 3076@deffn EventType @code{insufficient-mp} 3077@end deffn 3078 3079@deffn EventType @code{blocking-zoc} 3080Unit was unable to move because of another unit's zone of control. 3081@end deffn 3082 3083@deffn EventType @code{cannot-leave-world} 3084@end deffn 3085 3086@deffn EventType @code{destination-full} 3087@end deffn 3088 3089@deffn EventType @code{overrun-succeeded} 3090@end deffn 3091 3092@deffn EventType @code{overrun-failed} 3093@end deffn 3094 3095@deffn EventType @code{capture-succeeded} 3096@end deffn 3097 3098@deffn EventType @code{capture-failed} 3099@end deffn 3100 3101@deffn EventType @code{fire-into-outside-world} 3102@end deffn 3103 3104@deffn EventType @code{build-completed} 3105@end deffn 3106 3107@node Types in General 3108 3109@section Types in General 3110 3111Types are the foundation of @i{Xconq} game designs. Nearly all the 3112rules and game parameters are associated with the unit, material, 3113terrain, and advance types. There is no sort of type hierarchy; 3114instead, most forms allow sets of types to be used in the place of 3115single types. 3116 3117Each type has an index associated with it, starting from 0. This index 3118never appears directly, and cannot be set. This does mean that types 3119have an order, so the order in which types are defined is sometimes 3120significant. These cases will be noted. The order is always the order 3121in which the types appear in the file. 3122 3123@menu 3124* Type Names:: 3125* Type Images:: 3126* Documentation:: 3127@end menu 3128 3129@node Type Names 3130 3131@subsection Type Names 3132 3133The names of types need not be distinct from each other, but you run the 3134risk of player confusion if they share names. 3135 3136@deffn TypeProperty @code{name} string 3137This property is the specific name of the type. This name will be 3138displayed to players; the exact format is up to the interface, but will 3139typically depend on the name's length and the space available in the 3140display. If no type names have been defined, the internal type name 3141(see below) will be used. Defaults to @code{""}. 3142@end deffn 3143 3144@deffn TypeProperty @code{long-name} string 3145This property is a fully spelled-out name for the type. Defaults to 3146@code{""}. (At present, this property is only defined for unit types.) 3147@end deffn 3148 3149@deffn TypeProperty @code{short-name} string 3150This property is an abbreviated name of for the type. Defaults to 3151@code{""}. (At present, this property is only defined for unit types.) 3152@end deffn 3153 3154@deffn TypeProperty @code{generic-name} string 3155This property is like @code{name}, but identifies the type less 3156specifically, and several types may have the same generic name. If no 3157generic names are defined, then the regular type names will be used. 3158This is useful when making abbreviated lists, so that related types get 3159counted together. Defaults to @code{""}. (At present, this property is 3160only defined for unit types.) 3161@end deffn 3162 3163As an example of the distinction between type names and generic type 3164name, the names of a automobile type might be @code{"1965 Mustang"}, 3165@code{"Mustang"}, and @code{"M"}, while the generic name is 3166@code{"auto"}. Then the interface could choose to display a parking lot 3167as containing either @code{"4 auto"} or @code{"2 Mustang 1 Edsel 1 3168Jeep"}. 3169 3170Note that names specified as properties are strings only, and are not 3171defined as evaluable symbols. 3172 3173@node Type Images 3174 3175@subsection Type Images 3176 3177The interpretation of these properties is entirely up to each interface; 3178see the appropriate interface documentation for details. 3179 3180@deffn TypeProperty @code{image-name} str 3181This property is the name of the type's image. If undefined or unusable 3182for some reason, the interface will display the type in some default 3183manner, such as a solid-color square or a string. 3184 3185For example, in X11, the name might be the name of a file in the usual 3186bitmap format, as produced by the @var{bitmap} program. The actual file 3187name is produced by appending @code{".b"}. (The situation in X is 3188actually more complicated than this.) See the interface documentation 3189for details on how the interface uses the image. 3190@end deffn 3191 3192@deffn TypeProperty @code{char} str 3193This property supplies a single character for this type (all characters 3194after the first one in @var{str} are ignored). Defaults to @code{""}. 3195(This property is not defined for advance types.) 3196@end deffn 3197 3198@deffn UnitTypeProperty @code{generic-char} str 3199This property supplies a single generic character for this type (all 3200characters after the first one in @var{str} are ignored). If defined, 3201displays will use the generic character in preference to the @code{char} 3202for the unit type, in contexts where the exact type is not important 3203(such as in lists of occupant types). Defaults to @code{""}. (This 3204property is only defined for unit types.) 3205@end deffn 3206 3207@node Documentation 3208 3209@subsection Documentation 3210 3211@deffn TypeProperty @code{help} string 3212This property is a brief (preferably one-line) description of the type. 3213Defaults to @code{""}. 3214@end deffn 3215 3216@deffn TypeProperty @code{notes} strings@dots{} 3217This property is detailed documentation about the type. The formatting 3218of the strings is up to the interface, but in general each string is a 3219separate line, the string @code{""} indicates a line break, and two 3220@code{""} in a row indicates a paragraph break. Defaults to @code{()}. 3221@end deffn 3222 3223@node Unit Types 3224 3225@section Unit Types 3226 3227@deffn Form @code{unit-type} symbol properties@dots{} 3228This form defines a new type of unit. The @var{symbol} is required and 3229must be previously undefined. The bindings in @var{properties} are then 3230added to the type one by one. If no other name properties are defined, 3231the @var{symbol} may be displayed to players (see above). You can 3232define no more than 126 types of units. 3233@end deffn 3234 3235The @var{symbol} here becomes the unit type's ``internal type name'' 3236which is guaranteed unique. To make synonyms for the internal type 3237name, use @code{define}. 3238 3239@deffn GlobalVariable @code{u*} 3240This variable evaluates to a list of all unit types, listed in the order 3241that they were defined. This list always reflects the list of types at 3242the moment it is evaluated. 3243@end deffn 3244 3245@deffn GlobalVariable @code{non-unit} 3246This variable evaluates to a value that is NOT a unit type. This is 3247needed in several places to enable/disable features. Use of this in any 3248other way is an error, and may or may not be detected before it causes a 3249crash. (Although described as a variable, its value cannot be changed.) 3250@end deffn 3251 3252@deffn UnitTypeProperty @code{name-internal} str 3253Internally used type name. 3254@end deffn 3255 3256@menu 3257* Unit Naming:: 3258* Availability:: 3259* Class-Restricted Unit Types:: 3260* Self-Unit Capable Units:: 3261* Limits on Unit Quantities:: 3262* Hit Points:: 3263* Experience:: 3264* Tech Levels vs Units:: 3265* Opinions:: 3266* Point Value:: 3267* Advanced Units:: 3268@end menu 3269 3270@node Unit Naming 3271 3272@subsection Unit Naming 3273 3274@deffn UnitTypeProperty @code{namer} namer-id 3275This property is the namer that will be used to generate names for 3276units, if the unit's side does not have a namer, or the unit is 3277independent and not in any country. Defaults to @code{0}, which leaves 3278the unit unnamed. 3279@end deffn 3280 3281@deffn UnitTypeProperty @code{assign-number} t/f 3282This property is true if the unit should have a serial number assigned 3283to it by the side it belongs to. Serial numbers are maintained for each 3284type on each side separately, start at 1 for the first unit of the type, 3285and increase by one each time. Defaults to @code{true}. 3286@end deffn 3287 3288@deffn UnitTypeProperty @code{description-format} list@dots{} 3289This property defines the different ways in which an instance or 3290instances of this type may be described textually. This information may 3291be used in narrative descriptions and in informational displays. Each 3292element of @var{list} is either a string to add literally to the unit's 3293description, or a symbol indicating the substitution of unit or unit 3294type properties. The symbols are @code{name}, @code{position}, 3295@code{side}, @code{side-adjective}, @code{side-name}, @code{type}. If 3296@code{()}, then the instance will be described in a default fashion that 3297is equivalent to a format of @code{(side " " type " " name)}. Defaults 3298to @code{()}. 3299@end deffn 3300 3301@node Availability 3302 3303@subsection Availability 3304 3305It may be that a set of types is larger than strictly necessary for 3306a particular game. You can make any type unavailable, which means 3307that irrespective of any other controls, that type cannot come into 3308play during a game. You can also make it available only for particular 3309turns. 3310 3311@deffn UnitTypeProperty @code{available} n 3312If the value of this property is greater than 0, then this type is 3313available in the game on or after turn @var{n}. If the value is less 3314than 0, then the type is available, but only until turn @var{-n}. If 3315the value is 0, then the type is never available. Defaults to @code{1}, 3316which means that the type is always available. 3317@end deffn 3318 3319If a type becomes unavailable and there are units of that type in play, 3320then they will vanish immediately. 3321 3322@node Class-Restricted Unit Types 3323 3324@subsection Class-Restricted Unit Types 3325 3326Sometimes the designer will want to make different sides have different 3327types of units. Although this can be done by setting up scenarios 3328appropriately, that won't close all the loopholes that might allow a 3329side to get units that should only ever belong to another side. 3330 3331The first step is to define a class for each side. For instance, a side 3332named @code{"Rome"} might have a class @code{"Roman"}, while the sides 3333named @code{"Aedui"} and @code{"Parisii"} could both be in the class 3334@code{"barbarian"}. 3335 3336@deffn UnitTypeProperty @code{possible-sides} exp 3337This property restricts the unit type to only be usable by a side 3338meeting the conditions of @var{exp}. If @var{exp} is a string, it 3339restricts the unit type to only be usable by a side whose class includes 3340a matching string. This may also be a boolean expression. Independent 3341units belong to a side whose class is @code{"independent"}. The default 3342of @code{""} allows the unit to belong to any side. 3343@end deffn 3344 3345@node Self-Unit Capable Units 3346 3347@subsection Self-Unit Capable Units 3348 3349The self-unit can be any type, including one that cannot act; for 3350instance, a capital city could be the self-unit, thus making its defense 3351all-important for a player. 3352 3353@deffn GlobalVariable @code{self-required} t/f 3354This variable is true if each side is required to have a self-unit at 3355all times. However, if no unit of a suitable type is available when the 3356game begins, then none will be required. Defaults to @code{false}. 3357@end deffn 3358 3359@deffn UnitTypeProperty @code{can-be-self} t/f 3360This property says that the type of unit can represent the side directly. 3361Defaults to @code{false}. 3362@end deffn 3363 3364@deffn UnitTypeProperty @code{self-changeable} t/f 3365This property is true if the player can choose to change a self-unit of 3366this type at any time. Otherwise the self-unit can be changed only if 3367the current one dies. Defaults to @code{false}. 3368@end deffn 3369 3370@deffn UnitTypeProperty @code{self-resurrects} t/f 3371This property is true if when the self-unit dies, another unit of an 3372allowable type becomes the self-unit automatically. Defaults to 3373@code{false}. 3374@end deffn 3375 3376Observe that these parameters can be used to develop various forms of 3377backup, so that a player can start out as a capital city, resurrect as a 3378town, change self to one of several towns, then lose when all the towns 3379are lost. 3380 3381@deffn UnitTypeProperty @code{direct-control} t/f 3382This property is true if a unit of this type can be controlled by its 3383side automatically. If false, then it must be within range of a unit 3384that can control it, and is itself under control by the side. Defaults 3385to @code{true}. 3386@end deffn 3387 3388@deffn TableUU @code{unit-control-chance-at} u1 u2 -> n% 3389@end deffn 3390 3391@deffn TableUU @code{unit-control-chance-adjacent} u1 u2 -> n% 3392@end deffn 3393 3394@deffn TableUU @code{unit-control-chance} u1 u2 -> n% 3395@end deffn 3396 3397@deffn TableUU @code{unit-control-range} u1 u2 -> dist 3398This table gives the maximum distance from self-unit @var{u1} at which 3399units of type @var{u2} can be controlled directly. Units further away 3400always act on their own. If this value is < 0, then @var{u1} can never 3401directly control any other @var{u2} on the side. Defaults to 3402@code{infinity}. 3403@end deffn 3404 3405@node Limits on Unit Quantities 3406 3407@subsection Limits on Unit Quantities 3408 3409The effect of these is to prevent any extra units from being created or 3410from going over to a side, regardless of the reason. This happens by 3411either preventing player actions that would result in exceeding a limit 3412(such as when building units), or by making the unit vanish instantly 3413(such as when capturing a unit). 3414 3415@deffn GlobalVariable @code{units-in-game-max} n 3416This variable is the maximum number of all types of units, on all sides, 3417including independents, that may exist at any time, including initially. 3418Defaults to @code{-1}, which means that there is no limit. 3419@end deffn 3420 3421@deffn GlobalVariable @code{units-per-side-max} n 3422This variable is the maximum number of units (of all types together) 3423that any side may have, at any time. Events that would cause the limit 3424to be exceeded, such as capturing a unit, result in either the unit 3425vanishing or becoming independent. Defaults to @code{-1}, which means 3426that there is no limit. 3427@end deffn 3428 3429There is no limit on the number of units that may be independent. 3430 3431@deffn UnitTypeProperty @code{type-in-game-max} n 3432This property is the maximum total of the given type, for all sides 3433together. Defaults to @code{-1}, which means that there is no limit. 3434@end deffn 3435 3436@deffn UnitTypeProperty @code{type-per-side-max} n 3437This property is the maximum number of units of the given type allowed 3438to each side. Defaults to @code{-1}, which means that there is no 3439limit. 3440@end deffn 3441 3442@node Hit Points 3443 3444@subsection Hit Points 3445 3446A unit's hit points determine how healthy it is. If a unit's hp goes 3447below 1, it is either @dfn{wrecked}, meaning that it changes to a new 3448type @code{wrecked-type} or else it @dfn{vanishes}, meaning that it is 3449completely cleared from the world. 3450 3451@deffn UnitTypeProperty @code{hp-max} n 3452This property is the maximum number of hit points for (each part of) a 3453unit. Completed units start with this many hit points. Defaults to 3454@code{1}. 3455@end deffn 3456 3457@deffn UnitTypeProperty @code{parts-max} n 3458This property declares that a unit is really an aggregate of @var{n} 3459smaller identical units. Defaults to @code{1}. 3460@end deffn 3461 3462@deffn UnitTypeProperty @code{destruction-result} list 3463This property contains a weighted list, @var{list}, of possible destruction 3464special outcomes, which are considered before deciding what to do with a 3465destroyed unit. 3466Defaults to @code{nil}. 3467If @code{nil} then the normal outcome is used. 3468Possible outcomes: @code{vanish} and @code{table}. 3469The @code{vanish} outcome means that the unit will simply disappear no 3470matter what would normally happen to it. 3471The @code{table} outcome means determine the normal outcome by using any 3472table lookups, etc.... 3473@end deffn 3474 3475@deffn UnitTypeProperty @code{wrecked-type} unit-type 3476This property is the type of unit that a unit with 0 hp will become. 3477For instance, a destroyed ``fort'' might become a ``rubble pile'' unit. 3478If its value is @code{non-unit}, then the destroyed unit just vanishes. 3479The @code{wrecked-type} of a type must be a different type. 3480Defaults to @code{non-unit}. 3481@end deffn 3482 3483@deffn TableUU @code{wrecked-type-if-killed} u1 u2 -> u3 3484If an unit of type @var{u1} is killed by an unit of type @var{u2}, then 3485make the wreck of @var{u1} be an unit of type @var{u3}. 3486Defaults to @code{non-unit}, which means that the value of 3487@code{wrecked-type} will be used instead. 3488Overrides the value of @code{wrecked-type} if set to something other than 3489@code{non-unit}. 3490@end deffn 3491 3492@deffn TableUM @code{wrecked-type-if-starved} u1 m -> u3 3493If an unit of type @var{u1} starves to death for lack of a material of 3494type @var{m}, then make the wrecked unit type be @var{u3}. 3495Defaults to @code{non-unit}, which means that the value of 3496@code{wrecked-type} will be used instead. 3497Overrides the value of @code{wrecked-type} if set to something other than 3498@code{non-unit}. 3499@end deffn 3500 3501@deffn TableUT @code{wrecked-type-if-attrited} u1 t -> u3 3502If an unit of type @var{u1} dies from attrition due to a hostile terrain 3503of type @var{t}, then make the wrecked type be @var{u3}. 3504Defaults to @code{non-unit}, which means that the value of 3505@code{wrecked-type} will be used instead. 3506Overrides the value of @code{wrecked-type} if set to something other than 3507@code{non-unit}. 3508@end deffn 3509 3510The transformation to the wrecked type does not change position or name. 3511The transformed unit has full hp, supplies are conserved as much as 3512possible (any excess is destroyed), tooling is preserved, and any unit 3513plan is erased. It has the same number of parts, or as many as possible 3514if that is fewer. It may be that the wrecked type is on terrain that it 3515cannot survive on; in that case, it will be wrecked again, repeating 3516until the unit either vanishes or is in a viable position, or this 3517process has been repeated more times than the number of unit types 3518(prevents infinite loops). Any excess occupants will be removed and 3519either placed in another nearby unit or in the open, or will vanish if 3520there is no other option. 3521 3522@node Experience 3523 3524@subsection Experience 3525 3526@deffn UnitTypeProperty @code{cxp-max} cxp 3527This property is the maximum combat experience this type of unit can have. 3528@end deffn 3529 3530@node Tech Levels vs Units 3531 3532@subsection Tech Levels vs Units 3533 3534Before it can do anything with a type of unit, the side must have the 3535appropriate tech level for that type, which is just a number ranging 3536from 0 up to @code{tech-level-max}. Each type has a distinct tech 3537level. 3538 3539Tech levels always increase (since they represent abstract knowledge 3540rather than physical plant). Tech can be transferred freely to any 3541other side via the message @code{tech} [xref to messages]. 3542 3543For each unit type, the following parameters define the minimum tech 3544levels at which sides can do various things. 3545 3546@deffn UnitTypeProperty @code{tech-to-see} tl 3547This property is the minimum tech level that a side must have before it 3548can see a unit of this type. 3549@end deffn 3550 3551@deffn UnitTypeProperty @code{tech-to-own} tl 3552This property is the minimum tech level that a side must have in order 3553to have a unit of this type. 3554@end deffn 3555 3556@deffn UnitTypeProperty @code{tech-from-ownership} tl 3557This property is the tech level that may be reached by acquiring a unit 3558of this type. Since this is expressed as a minimum, multiple 3559acquisitions have no additional effect. 3560@end deffn 3561 3562@deffn UnitTypeProperty @code{tech-to-use} tl 3563This property is the minimum tech level that a side must have in order 3564to give actions to this type of unit. 3565@end deffn 3566 3567@deffn UnitTypeProperty @code{tech-to-build} tl 3568This property is the minimum tech level that a side must have in order 3569to build this type of unit. 3570@end deffn 3571 3572@deffn UnitTypeProperty @code{tech-max} tl 3573This property is the absolute maximum tech level possible for this type. 3574@end deffn 3575 3576@deffn TableUU @code{tech-crossover} u1 u2 -> n% 3577This table is the minimum tech level for @var{u2} that is guaranteed by 3578a particular tech level for @var{u1}, expressed as a percentage of the 3579@code{tech-max} for the types. For instance, if @code{tech-crossover} 3580is 80, and the tech level for @var{u1} is 10 out of a max of 20, and the 3581max for @var{u2} is also 20, then the side has a tech for @var{u2} at 3582least 8. 3583@end deffn 3584 3585It is possible to gain some tech level just by being in the same game 3586with a side that is more advanced. 3587 3588@deffn UnitTypeProperty @code{tech-leakage} .01tl 3589This property is the amount of tech level gain per turn that can happen 3590to any side's tech level that is less than the max of all sides in the 3591game. This only happens if at least one unit on the side has nonzero 3592coverage of a unit on a more advanced side. 3593@end deffn 3594 3595@node Opinions 3596 3597@subsection Opinions 3598 3599@deffn UnitTypeProperty @code{opinion-min} n 3600@end deffn 3601@deffn UnitTypeProperty @code{opinion-max} n 3602These properties are the bounds of the strength of a unit's opinion 3603about the sides, both other sides and its own. 3604@end deffn 3605 3606@deffn UnitTypeProperty @code{courage-min} n 3607@end deffn 3608@deffn UnitTypeProperty @code{courage-max} n 3609@end deffn 3610 3611Morale is similar to opinion; it reflects the unit's opinion about 3612itself. 3613 3614@deffn UnitTypeProperty @code{morale-max} n 3615This property is the maximum morale that the unit may have. 3616@end deffn 3617 3618@deffn TableUT @code{morale-terrain-effect} u t -> n 3619This table is the effect of the terrain at a unit's location on its 3620morale. 3621@end deffn 3622 3623@deffn UnitTypeProperty @code{morale-recovery} .01n 3624This property is the amount of morale increase for a unit each turn, in 36251/100ths of a point of morale. Defaults to @code{0}. 3626@end deffn 3627 3628@node Point Value 3629 3630@subsection Point Value 3631 3632Point values provide an abstract way to characterize the overall 3633importance of a unit type. Point values figure into some scorekeepers, 3634and are used by AIs. 3635 3636@deffn UnitTypeProperty @code{point-value} n 3637This property is the ``value'' of a unit. Defaults to @code{1}. 3638@end deffn 3639 3640@node Advanced Units 3641 3642@subsection Advanced Units 3643 3644Advanced units have an additional set of behaviors and functions; they 3645are most like the cities in civilization-building games. 3646 3647@deffn UnitTypeProperty @code{advanced} t/f 3648This property is true if the type is an advanced type. 3649@end deffn 3650 3651@deffn TableUA @code{size-limit-without-advance} u a -> n 3652This table indicates the maximum size of a unit of type @var{u} if the 3653advance @var{a} has not been achieved. Defaults to a large number. 3654@end deffn 3655 3656@deffn TableUU @code{size-limit-without-occupant} u1 u2 -> n 3657This table indicates the maximum size of a unit of type @var{u1} if a 3658unit of type @var{u2} is not an occupant. Defaults to a large number. 3659@end deffn 3660 3661@deffn TableUM @code{unit-consumption-per-size} u m -> n 3662@end deffn 3663 3664@deffn TableUM @code{unit-consumption-to-grow} u m -> n 3665@end deffn 3666 3667@c should make a special section to define usage 3668 3669Advanced units may use cells around them for production. 3670 3671@deffn TableTM @code{production-from-terrain} t m -> n 3672This table defines how much production an advanced unit gains by using a 3673cell for production. This production is actually done by the unit, and the 3674results are added directly to the unit's store of material; it is separate 3675from backdrop production by cells through @code{terrain-production}, which 3676adds to the cells' own material stores. 3677@end deffn 3678 3679@deffn UnitTypeProperty @code{reach} n 3680This property is the radius out to which an advanced unit type may use 3681the terrain for production. 3682@end deffn 3683 3684@deffn UnitProperty @code{reach} n 3685This property is the radius out to which an advanced unit may use the 3686terrain for production. (This is always the same as the type property 3687currently.) 3688@end deffn 3689 3690@deffn UnitProperty @code{size} n 3691This property is the size of the advanced unit. 3692@end deffn 3693 3694@deffn UnitTypeProperty @code{use-own-cell} t/f 3695If true, then the advanced unit type automatically uses the cell it is 3696sitting on. 3697@end deffn 3698 3699@deffn TableUA @code{advance-add-maxcells} u a -> n 3700This is the number of additional cells that the unit can use for 3701production if its side has the advance. 3702@end deffn 3703 3704@deffn TableUA @code{advance-mult-maxcells} u a -> n 3705This is the percentage multiplier for the additional cells that the unit 3706can use for production if its side has the advance. Defaults to 3707@code{100}. 3708@end deffn 3709 3710@deffn TableUU @code{occ-add-maxcells} u1 u2 -> n 3711This is the number of additional cells that each occupant of type 3712@var{u2} adds to a unit of type @var{u1}. 3713@end deffn 3714 3715@deffn TableUU @code{occ-multiply-maxcells} u1 u2 -> n 3716This is the percentage by which each occupant of type @var{u2} multiples 3717the production cells of a unit of type @var{u1}. Defaults to 3718@code{100}. 3719@end deffn 3720 3721@deffn UnitProperty @code{usedcells} n 3722This is a cache of the number of cells used by an advanced unit. 3723@end deffn 3724 3725@deffn UnitProperty @code{maxcells} n 3726This is a cache of the maximum number of cells available to an advanced 3727unit. 3728@end deffn 3729 3730@deffn TableUA @code{advance-add-production} u a -> n 3731This is the amount of additional production available to the unit if its 3732side has the advance. 3733@end deffn 3734 3735@deffn TableUA @code{advance-multiply-production} u a -> n 3736This is the percentage by which an advance multiplies the production 3737of the unit. Defaults to @code{100}. 3738@end deffn 3739 3740@deffn TableUU @code{occupant-add-production} u1 u2 -> n 3741This is the amount of additional production available to the unit 3742of type @var{u1} due to each occupant of type @var{u2}. 3743@end deffn 3744 3745@deffn TableUU @code{occupant-multiply-production} u1 u2 -> n 3746This is the percentage by which each occupant of type @var{u2} 3747multiplies the production of a unit of type @var{u1}. Defaults to 3748@code{100}. 3749@end deffn 3750 3751Materials produced by advanced units may be automatically converted 3752into other types, in proportions decided by the player. 3753 3754@deffn TableMM @code{conversion} m1 m2 -> n 3755Values greater than zero in this table indicate that produced materials 3756of type @var{m1} can become materials of type @var{m2}. 3757@end deffn 3758 3759@deffn TableMM @code{conversion-default} m1 m2 -> n 3760This table is the default conversion rate of material of type @var{m1} 3761into a material of type @var{m2}. 3762@end deffn 3763 3764@node Terrain Types 3765 3766@section Terrain Types 3767 3768Terrain types are associated with the cells, borders, connections, and 3769coatings in a world. 3770 3771@deffn Form @code{terrain-type} name properties@dots{} 3772This form defines a new type of terrain, named by @var{name}. Details 3773are similar to those for unit types. 3774@end deffn 3775 3776@deffn GlobalVariable @code{t*} 3777This variable evaluates to a list of all terrain types, listed in the 3778order that they were defined. 3779@end deffn 3780 3781@deffn GlobalVariable @code{non-terrain} 3782This variable has a value that is guaranteed not to be a terrain type. 3783@end deffn 3784 3785@menu 3786* Terrain Subtypes:: 3787* Terrain Compatibility:: 3788* Other Terrain Properties:: 3789@end menu 3790 3791@node Terrain Subtypes 3792 3793@subsection Terrain Subtypes 3794 3795Terrain can appear in four different roles: as the interior of a cell, 3796as a border between cells, as a connection between cells, or as a 3797coating overlaying the normal terrain. The terrain subtype says which 3798role a type can play. 3799 3800@deffn TerrainTypeProperty @code{subtype} subtype 3801This property is the role that the terrain type can appear in. Defaults 3802to @code{cell}. 3803@end deffn 3804 3805@deffn GlobalConstant @code{cell} 3806This constant indicates that terrain can fill a cell. All units in the 3807open and with an altitude of 0 are assumed to be surrounded by the cell 3808terrain. 3809@end deffn 3810 3811@deffn GlobalConstant @code{border} 3812This constant indicates that the terrain can be a border between two 3813cells. 3814@end deffn 3815 3816@deffn GlobalConstant @code{connection} 3817This constant indicates that the terrain can be a connection between two 3818cells. 3819@end deffn 3820 3821@deffn GlobalConstant @code{coating} 3822This constant indicates that the terrain can be a coating. A 3823@dfn{coating} is a temporary terrain modification. The classic example 3824is snow, which effectively changes some kinds of terrain, but not 3825completely and usually not permanently. Cells can have varying 3826heaviness of each type of coating. 3827@end deffn 3828 3829@deffn TableTT @code{coating-depth-min} t1 t2 -> n 3830In order for a coating @var{t1} to ``stick'', this table says much must 3831be added all at once to terrain @var{t2}. A coating depth that drops 3832below this will disappear immediately. 3833@end deffn 3834 3835@deffn TableTT @code{coating-depth-max} t1 t2 -> n 3836This table is the upper limit on coating depth. 3837@end deffn 3838 3839Terrain types may have additional subtype attributes that are used only 3840during synthesis, to select appropriate subtypes for special purposes. 3841 3842@deffn TerrainTypeProperty @code{subtype-x} n 3843This property is extra subtype information, used in synthesis. Defaults 3844to @code{no-x}. 3845@end deffn 3846 3847@deffn Symbol @code{no-x} 3848@end deffn 3849 3850@deffn GlobalConstant @code{river-x} 3851This constant indicates that synthesis methods should treat this type as 3852a river. The terrain type may be either a border or a connection. 3853@end deffn 3854 3855@deffn GlobalConstant @code{valley-x} 3856This constant indicates that synthesis methods should treat this type as 3857a valley. 3858@end deffn 3859 3860@deffn GlobalConstant @code{road-x} 3861This constant indicates that synthesis methods should treat this type as 3862a road. 3863@end deffn 3864 3865@deffn TerrainTypeProperty @code{liquid} t/f 3866This property is true if the terrain type represents a liquid, which 3867means that adjacent cells of liquid must have the same elevation. 3868Defaults to @code{false}. 3869@end deffn 3870 3871@node Terrain Compatibility 3872 3873@subsection Terrain Compatibility 3874 3875Terrain types are not always mutually compatible. Incompatible types 3876may not be juxtaposed, either at game setup time or by unit action 3877during a game. 3878 3879@deffn TableTT @code{adjacent-terrain-effect} t1 t2 -> t3 3880This table specifies what will happen to a cell of type @var{t1} 3881adjacent to a cell of type @var{t2}. If @var{t3} is @code{non-terrain}, 3882nothing will happen, otherwise it will become a cell of type @var{t3}. 3883Defaults to @code{non-terrain}. 3884@end deffn 3885 3886@deffn TableTT @code{adjacent-terrain-effect-chance} t1 t2 -> n% 3887If a terrain change is specified in the @code{adjacent-terrain-effect} 3888table, then the corresponding entry in this table determines the 3889probability @var{n} of the terrain change effect succeeding. Defaults to 3890@code{100%}. 3891@end deffn 3892 3893@deffn TableTT @code{adjacent-terrain-effect-passes} t1 t2 -> n 3894If a terrain change is specified in the @code{adjacent-terrain-effect} 3895table, then the corresponding entry in this table determines how many 3896times this effect will be iterated by the terrain change code. Defaults 3897to @code{-1}, which means that iterations will continue until no more 3898changes occur or until the number of iterations is equal to the height of 3899the map. 3900@end deffn 3901 3902@deffn TableTT @code{adjacent-terrain-border} t1 t2 -> t3 3903If a cell terrain of type @var{t1} is adjacent to a cell terrain of type 3904@var{t2}, then place a border of type @var{t3} between the cells. 3905Defaults to @code{non-terrain}, which means that no border will be placed.@* 3906NOTE: Existing borders are deleted before the new border is placed. 3907@end deffn 3908 3909@deffn TableTT @code{adjacent-terrain-border-chance} t1 t2 -> n% 3910If a border between @var{t1} and @var{t2} is specified in the 3911@code{adjacent-terrain-border} table, then the corresponding entry in 3912this table determines the probability of the new border actually being 3913placed. Defaults to @code{100%}. 3914@end deffn 3915 3916@deffn TableTT @code{adjacent-terrain-connection} t1 t2 -> t3 3917Similar to @code{adjacent-terrain-border}, but applied to connection 3918terrain. Defaults to @code{non-terrain} (no connection will be placed), and 3919if a connection is placed, any existing connections will be removed. 3920@end deffn 3921 3922@deffn TableTT @code{adjacent-terrain-connection-chance} t1 t2 -> n% 3923Similar to @code{adjacent-terrain-border-chance}, this specifies the chance 3924of a connection specified by @code{adjacent-terrain-connection} actually 3925being placed. Defaults to @code{100%}. 3926@end deffn 3927 3928Note that there is not a passes-limiting table for setting border 3929terrain. This is because the border terrain algorithm executes in one 3930pass, since border types are not dependent on neighboring border types. 3931Similarly, there is no passes-limiting table for connection terrain. 3932 3933@node Other Terrain Properties 3934 3935@subsection Other Terrain Properties 3936 3937@deffn TerrainTypeProperty @code{elevation-min} elev 3938@end deffn 3939@deffn TerrainTypeProperty @code{elevation-max} elev 3940These properties define the minimum and maximum possible values for the 3941elevation in a cell of given terrain type. Both default to @code{0}. 3942@end deffn 3943 3944@deffn TerrainTypeProperty @code{temperature-min} n 3945@end deffn 3946@deffn TerrainTypeProperty @code{temperature-max} n 3947These properties define the minimum and maximum possible values for the 3948temperature in a cell of given terrain type. Both default to @code{0}. 3949@end deffn 3950 3951@deffn TerrainTypeProperty @code{wind-force-min} n 3952@end deffn 3953@deffn TerrainTypeProperty @code{wind-force-max} n 3954These properties define limits on wind force. Both default to @code{0}. 3955@end deffn 3956 3957@deffn TerrainTypeProperty @code{clouds-min} n 3958@end deffn 3959@deffn TerrainTypeProperty @code{clouds-max} n 3960These properties define limits on cloud density. Both default to 3961@code{0}. 3962@end deffn 3963 3964@node Material Types 3965 3966@section Material Types 3967 3968Materials are materials that are manipulated in mass quantities. In 3969general, material types just index vectors of values attached to other 3970objects, such as unit supplies. 3971 3972No more than 126 types of material may be defined. 3973 3974@deffn Form @code{material-type} symbol properties@dots{} 3975This form defines a new type of material, named by @var{symbol}. 3976Details are similar to those for unit types. 3977@end deffn 3978 3979@deffn GlobalVariable @code{m*} 3980This variable evaluates to a list of all material types, listed in the 3981same order as they were defined. 3982@end deffn 3983 3984@deffn GlobalVariable @code{non-material} 3985This variable has a value that is never a material type. 3986@end deffn 3987 3988@menu 3989* People:: 3990@end menu 3991 3992@node People 3993 3994@subsection People 3995 3996A material type can be designated as representing people. 3997 3998@deffn MaterialTypeProperty @code{people} n 3999This property is the actual number of individuals represented by 1 of a 4000material. If 0, then the material type does not have people associated 4001with it at all. 4002@end deffn 4003 4004Multiple types of materials can represent different types of people, so 4005for example there could be one type @code{nomad} with 10 4006people/material, and another type @code{urbanite} with 10,000 4007people/material. 4008 4009The basic cell capacities for materials also constrain people 4010materials. There can be an additional limit on the number of 4011individuals. 4012 4013@deffn TerrainTypeProperty @code{people-max} n 4014This property is the maximum number of individuals allowed in a cell of 4015this type of terrain. This is checked at the end of each turn; any 4016excess will be moved into adjacent cells or disappear entirely. 4017Defaults to @code{-1}, which allows any number of people in a cell. 4018@end deffn 4019 4020@node Advance Types 4021 4022@section Advance Types 4023 4024Advances are scientific, economic, social, or any other type of 4025general accomplishment. They can enable the construction of 4026particular types of units. They are, however, different than tech points 4027and development. 4028 4029@deffn Form @code{advance-type} symbol properties@dots{} 4030This form defines a new type of advance, named by @var{symbol}. 4031Naming details are similar to those for unit types. 4032@end deffn 4033 4034@deffn GlobalVariable @code{a*} 4035This variable evaluates to a list of all advance types, listed in the 4036same order as they were defined. 4037@end deffn 4038 4039@deffn GlobalVariable @code{non-advance} 4040This variable has a value that is never an advance type. 4041@end deffn 4042 4043@deffn AdvanceTypeProperty @code{rp} n 4044This property is the number of research points necessary to achieve the 4045advance. Defaults to @code{1}. 4046@end deffn 4047 4048@deffn AdvanceTypeProperty @code{ai-next-goal} list 4049A weighted list of possible advances to select as a research goal 4050if the current advance is completed and was a research goal. 4051@end deffn 4052 4053@deffn GlobalVariable @code{ai-initial-research-goals} list 4054A weighted list of possible advances to select as a research goal 4055if none is currently set. 4056@end deffn 4057 4058@node Static Relationships Between Types 4059 4060@section Static Relationships Between Types 4061 4062In general, static relationships are those that must always hold during 4063a turn. @i{Xconq} will usually only test these when necessary, but this 4064is up to the implementation. From the players' and designers' point of 4065view, these relationships can never be violated, even temporarily. 4066 4067@menu 4068* Occupants and Transports:: 4069* Units and Terrain:: 4070* Units and Materials:: 4071* Terrain and Materials:: 4072* Units and Advances:: 4073@end menu 4074 4075@node Occupants and Transports 4076 4077@subsection Occupants and Transports 4078 4079A unit inside another unit is an ``occupant'' in a ``transport'', even 4080if the ``transport'' can never move. There are two kinds of capacity. 4081Generic capacity is shared by all different types, while guaranteed 4082capacity is for a particular type only. 4083 4084@deffn UnitTypeProperty @code{capacity} n 4085This property is the limit on the sum of sizes of units that may occupy 4086this type of unit, not counting the exclusive capacities. 4087@end deffn 4088 4089@deffn TableUU @code{unit-size-as-occupant} u1 u2 -> n 4090This table is the ``size'' of a (full-sized) unit @var{u1} when it is in 4091a transport @var{u2}. Defaults to @code{1}. 4092@end deffn 4093 4094@deffn TableUU @code{unit-capacity-x} u1 u2 -> n 4095This table is the number of units of type @var{u2} that are guaranteed a 4096place in a unit of type @var{u1}. 4097@end deffn 4098 4099@deffn TableUU @code{occupant-max} u1 u2 -> n 4100This table is the upper limit on the number of occupants of this type 4101(not counting @code{unit-capacity-x}). 4102@end deffn 4103 4104@deffn UnitTypeProperty @code{occupant-total-max} n 4105This property is the upper limit on occupants of all types together. 4106Defaults to @code{-1}, which allows unlimited occupancy. 4107@end deffn 4108 4109@deffn UnitTypeProperty @code{mobile-total-max} n 4110This property is the upper limit on the number of mobile units (speed > 41110) allowed as occupants. Defaults to @code{-1}, which allows unlimited 4112occupancy. 4113@end deffn 4114 4115@deffn UnitTypeProperty @code{facility-total-max} n 4116This property is the upper limit on the number of facility units 4117(@code{facility} is true) allowed as occupants. Defaults to @code{-1}, 4118which allows unlimited occupancy. 4119@end deffn 4120 4121Some incomplete units have occupancies for other units, while other 4122incomplete units must be completed before any other units may be in them. 4123 4124@deffn TableUU @code{can-occupy-incomplete} u1 u2 -> t/f 4125If true, then an unit of type @var{u1} can be inside an incomplete unit of 4126type @var{u2}. Defaults to @code{false}. 4127@end deffn 4128 4129A unit that is an occupant may not always have the same capabilities 4130as when it is out in the open. Its vision, combat, construction, and 4131capacity may be affected. 4132 4133@deffn TableUU @code{occupant-vision} u1 u2 -> n% 4134This is the effect on @var{u1}'s vision of being an occupant in a unit 4135of type @var{u2}. If the value is 0, then @var{u1} is completely blind 4136while an occupant. Defaults to @code{100}. 4137@end deffn 4138 4139@deffn TableUU @code{occupant-combat} u1 u2 -> n% 4140This table defines the effect on the combat abilities of a unit of type 4141@var{u1} when an occupant in a unit of type @var{u2}. If @code{0}, then 4142the occupant cannot attack or fire. Defaults to @code{100}. 4143@end deffn 4144 4145@deffn TableUU @code{occupant-can-construct} u1 u2 -> t/f 4146This table is @code{true} if @var{u1} can create or complete units while 4147an occupant of @var{u2}. Defaults to @code{true}. 4148@end deffn 4149 4150@deffn TableUU @code{occupant-can-have-occupants} u1 u2 -> t/f 4151This table is @code{true} if @var{u1} can have occupants of its own 4152while an occupant of @var{u2}. Defaults to @code{true}.@* 4153@i{This table is no longer available.} 4154@end deffn 4155 4156@deffn TableUU @code{can-recursively-wake} u1 u2 -> t/f 4157Determine whether a transport of type @var{u1} should wake an occupant 4158of type @var{u2} when the transport is awakened for some reason. 4159Defaults to @code{true}. 4160@end deffn 4161 4162@node Units and Terrain 4163 4164@subsection Units and Terrain 4165 4166This section describes relationships between units and terrain. Units 4167can be set to disappear or be wrecked on particular types of terrain. 4168If the terrain can be occupied safely, there may be a limit on the 4169numbers of units that can be in the same cell. 4170 4171@deffn TableUT @code{vanishes-on} u t -> t/f 4172This table is @code{true} if a unit @var{u} will disappear instantly if 4173it somehow ends up on terrain of type @var{t}. Defaults to 4174@code{false}. 4175@end deffn 4176 4177@deffn TableUT @code{wrecks-on} u t -> t/f 4178This table is @code{true} if a unit @var{u} will wreck instantly if it 4179somehow ends up on terrain of type @var{t}. Defaults to @code{false}. 4180@end deffn 4181 4182@deffn TerrainTypeProperty @code{capacity} n 4183This property is the limit on the sum of unit sizes that may share this 4184cell. Defaults to @code{1}. 4185@end deffn 4186 4187@deffn TableUT @code{unit-size-in-terrain} u t -> n 4188This table is the ``size'' of a (full-sized) unit @var{u} when it is 4189in/on the terrain @var{t}. Defaults to @code{1}.@* 4190NOTE: This is not the same as the size property of an advanced unit.@* 4191NOTE: As of Xconq 7.5, this property is ignored for connection terrain 4192types. Connectors (roads, for example) now refer to @var{u}'s size in the 4193terrain that contains the connector rather than @var{u}'s size in 4194connector @var{t}.@* 4195NOTE: If you wish to prevent a unit's entry into @var{t}, then use the 4196@code{mp-to-enter-terrain} table, and not this one. The implication of 4197using @code{unit-size-in-terrain} to prevent entry is that the unit will 4198not be able to enter any connectors in @var{t} if @var{n} is set too 4199large. 4200@end deffn 4201 4202@deffn TableUT @code{terrain-capacity-x} u t -> n 4203This table is the number of (full-sized) units of type @var{u} that are 4204guaranteed to have a place in the cell. 4205@end deffn 4206 4207Note that the units' sides are irrelevant; the sizes of units of all 4208sides are added together. Limits are calculated separately for the 4209connection and open terrain in a cell; however, it is possible for a 4210unit in a cell to override any capacity due to connections in that cell. 4211 4212@deffn TableUT @code{capacity-negation} u t -> t/f 4213Defaults to @code{false}.@* 4214@i{This table is no longer available.} 4215@end deffn 4216 4217@deffn UnitTypeProperty @code{stack-order} n 4218This property is the relative position of this type of unit within a 4219stack of different units. Larger values put units higher in the stack. 4220The exact values are unimportant, they are just used as sort keys. The 4221use of this value is to ensure that particular types are ``seen first'' 4222when looking at a cell, so for instance if a truck and a city are 4223stacked on the same cell, everybody will see the city and not the truck. 4224The owner of these units can still see them. If the stack-order of two 4225units is the same, then the higher-numbered type will be higher in the 4226stack. 4227@end deffn 4228 4229There is a possible bizarrity with stacking limits and units that can't 4230see each other when in the same hex, namely that a player could be 4231prevented from moving a unit into a cell that looks like it has enough 4232room. 4233 4234@node Units and Materials 4235 4236@subsection Units and Materials 4237 4238Units can carry materials. 4239 4240@deffn TableUM @code{unit-storage-x} u m -> n 4241This table is the space reserved specifically for each type of material. 4242@end deffn 4243 4244Materials that represent people may surrender to a unit in their cell. 4245 4246@deffn TableUT @code{people-surrender-chance} u t -> n% 4247This table is the base chance that people in terrain of type @var{t} 4248will change sides if a unit of type @var{u} is in their cell. 4249@end deffn 4250 4251@deffn TableUM @code{people-surrender-effect} u m -> n 4252This is a multiplier that takes the people type into account. Defaults 4253to @code{100}. 4254@end deffn 4255 4256@node Terrain and Materials 4257 4258@subsection Terrain and Materials 4259 4260@deffn TableTM @code{terrain-storage-x} t m -> n 4261This table is the maximum amount of a material @var{m} that may be 4262present in a cell with terrain @var{t}. 4263@end deffn 4264 4265@node Units and Advances 4266 4267@subsection Units and Advances 4268 4269@deffn TableUA @code{advance-needed-to-build} u a -> t/f 4270This table is true whenever the side must have achieved advance @var{a} 4271before it can being to construct units of type @var{u}. 4272@end deffn 4273 4274@deffn UnitTypeProperty @code{obsolete} a 4275This property is the type of advance that makes a unit obsolete, meaning 4276that units of that type may longer be constructed (existing units are 4277unaffected though). Defaults to @code{non-advance}, meaning that the 4278unit type is never obsolete. 4279@end deffn 4280 4281 4282@node Vision 4283 4284@section Vision 4285 4286The parameters in this section define how sides get information about the 4287world, units, and other sides. 4288 4289@menu 4290* Basic Vision:: 4291* Line of Sight:: 4292* Tracking:: 4293* Spying:: 4294@end menu 4295 4296@node Basic Vision 4297 4298@subsection Basic Vision 4299 4300@deffn GlobalVariable @code{see-all} t/f 4301This variable is @code{true} if everything in the world, units, terrain, 4302etc, is always visible at all times, including initially. It takes 4303precedence over @i{all} other visibility and spying parameters. 4304Defaults to @code{false}. 4305@end deffn 4306 4307@deffn GlobalVariable @code{see-terrain-always} t/f 4308If this variable is @code{true}, then any side that has seen the terrain 4309of a cell will be informed if that terrain ever changes. Defaults to 4310@code{true}. 4311@end deffn 4312 4313@deffn UnitTypeProperty @code{see-always} t/f 4314This property is @code{true} when a unit is always visible after it has 4315been seen once, so that side changes, movements, etc will be seen 4316forever afterwards. If the unit moves into terrain that has not been 4317seen, then that terrain also becomes seen as well. Defaults to 4318@code{false}. 4319@end deffn 4320 4321@deffn UnitTypeProperty @code{see-occupants} t/f 4322This property is @code{true} when a unit's occupants are also seen 4323whenever the unit itself is under observation. Defaults to 4324@code{false}. 4325@end deffn 4326 4327@deffn UnitTypeProperty @code{spot-action} t/f 4328If this property is @code{true}, then the unit's chance to be seen by 4329other sides will be tested each time the unit acts in any way. This 4330property is in addition to the check at the beginning of each turn. 4331Defaults to @code{true}. 4332@end deffn 4333 4334The people in a cell effectively view (for their side) all units in that 4335cell. Some units can hide from the people. 4336 4337@deffn TableUM @code{people-see-chance} u m -> n% 4338This table is the chance that the people of the given type @var{m} will 4339see a unit of type @var{u}. This will be evaluated for each people type 4340individually, once at the beginning of each turn, and once for each 4341populated cell that the unit enters during the turn. Defaults to 4342@code{100}. 4343@end deffn 4344 4345@deffn UnitTypeProperty @code{vision-range} dist 4346This property is the maximum range of vision coverage by the unit. A 4347value of @code{-1} disables all vision, @code{0} means only units in the 4348same cell may be seen, and @code{1} means units in adjacent cells may be 4349seen. Defaults to @code{1}. 4350@end deffn 4351 4352@deffn TableUU @code{see-chance-at} u1 u2 -> n% 4353This table is the chance that a unit @var{u1} will see another sides's 4354unit of type @var{u2} when both are in the same cell. Defaults to 4355@code{100}. 4356@end deffn 4357 4358@deffn TableUU @code{see-chance-adjacent} u1 u2 -> n% 4359This table is the chance that a unit @var{u1} will see another sides's 4360unit of type @var{u2} when the two are in adjacent cells. Defaults to 4361@code{100}. 4362@end deffn 4363 4364@deffn TableUU @code{see-chance} u1 u2 -> n% 4365This table is the base chance that a unit @var{u1} will see a unit 4366@var{u2} in cells at distance 2 or greater. Defaults to @code{100}. 4367@end deffn 4368 4369@deffn TableUT @code{visibility} u t -> n 4370This table is the effect of terrain @var{t} on a unit @var{u}'s chances 4371of being seen. Values less than 100 are reduced visibility, values 4372greater than 100 increase the unit's chances to be seen. Defaults to 4373@code{100}. 4374@end deffn 4375 4376@deffn TableUT @code{vision-night-effect} u t -> n 4377This table is the multiplier for unit @var{u}'s vision at night in each 4378type of terrain @var{t}. Effect is to multiply with both vision range 4379and see-chance. Defaults to @code{100}. 4380@end deffn 4381 4382@deffn TableTM @code{see-material-always} t m -> t/f 4383Defaults to @code{true}. 4384@end deffn 4385 4386@deffn GlobalVariable @code{see-weather-always} t/f 4387If true, then weather changes (in cells that have been seen) will always 4388be reported. Defaults to @code{true}. 4389@end deffn 4390 4391@deffn TableUU @code{see-mistake-chance} u1 u2 -> .01n% 4392This is the chance that a unit of type @var{u1} will see a unit of type 4393@var{u2} as some other type. The type of unit seen instead is 4394determined by the table @code{looks-like}. 4395@end deffn 4396 4397@deffn TableUU @code{see-mistake-range-min} u1 u2 -> n 4398This is the minimum range at which an unit of type @var{u1} can mistake 4399an unit of type @var{u2} as some other type. 4400@end deffn 4401 4402@deffn TableUU @code{looks-like} u1 u2 -> n 4403This table is the set of weights indicating which type @var{u2} a unit 4404of type @var{u1} is most likely to be mistaken for. When a unit makes a 4405viewing mistake, then the program adds up all the weights and chooses 4406randomly according to weight. Defaults to @code{0}, which means that 4407@var{u2} never looks like @var{u1}. 4408@end deffn 4409 4410@node Line of Sight 4411 4412@subsection Line of Sight 4413 4414@deffn UnitTypeProperty @code{can-see-behind} t/f 4415This property is determines if elevations are ever an obstruction to the 4416unit type. If @code{false}, then the unit cannot see behind higher 4417elevations. Defaults to @code{true}. 4418@end deffn 4419 4420@deffn TableUT @code{eye-height} u t -> elev 4421This property is the additional elevation above the unit's position that 4422a unit can see with, when in the given terrain. 4423@end deffn 4424 4425@deffn TableUT @code{body-height} u t -> elev 4426This property is the effective height of the main visible part of a 4427unit, when in the given terrain. 4428@end deffn 4429 4430@deffn TerrainTypeProperty @code{thickness} elev 4431This property is the thickness of the terrain, which is the difference 4432between the ``ground'' of the terrain and its top. 4433@end deffn 4434 4435@node Tracking 4436 4437@subsection Tracking 4438 4439When is unit is being tracked, then the sides doing the tracking can see 4440the unit move around, even if the cell is not being covered by any of 4441the sides' own units. If this is enabled, then particular units enable 4442tracking, and the chance of losing track depends on the terrain. 4443 4444@deffn TableUU @code{track-chance} u1 u2 -> .01n% 4445This table gives the chance that @var{u1}'s side will be able to track a 4446unit of type @var{u2} that is within range (same or adjacent cell). 4447@end deffn 4448 4449@deffn TableUT @code{lose-track-chance} u t -> .01n% 4450This table gives the chance that each side tracking a unit will lose 4451that track when the unit enters terrain of type @var{t}. 4452@end deffn 4453 4454@node Spying 4455 4456@subsection Spying 4457 4458A unit type can also be specified to do spying automatically. The 4459outcome of spying is calculated once/unit/turn, at the beginning of the 4460turn (after move calculation but before any players can do anything). 4461Spying can happen to any unit not on the spying unit's side. 4462 4463@deffn UnitTypeProperty @code{spy-chance} .01n% 4464This property is the chance that the unit will be successful at spying. 4465@end deffn 4466 4467@deffn UnitTypeProperty @code{spy-range} dist 4468This property is the maximum distance at which the unit will find out 4469something by spying. 4470@end deffn 4471 4472@deffn TableUU @code{spy-quality} u1 u2 -> n% 4473This table gives the chance that @var{u1}'s spying will return 4474information about a unit of type @var{u2} that is within the spying 4475range. Defaults to @code{100}. 4476@end deffn 4477 4478@deffn TableUU @code{spy-track-chance} u1 u2 -> .01n% 4479This table is the chance that if @var{u1}'s spies return information 4480about a unit of type @var{u2}, the unit will also become tracked by the 4481spy's side. 4482@end deffn 4483 4484@node Game Initialization 4485 4486@section Game Initialization 4487 4488Game initialization always starts by resetting all the game-defining 4489data structures to an empty state. This means no types, no world, etc. 4490Then @i{Xconq} reads and interprets all of the game modules that have 4491been requested. These modules may overwrite each other arbitrarily. 4492Then any command line or startup options are processed (this may involve 4493an interactive dialog), and the random number generator is initialized. 4494and players are matched with sides (any sides needed for players will be 4495created and named at this time). @i{Xconq} then executes a number of 4496@i{synthesis methods} to do various kinds of setup. 4497 4498(Some interfaces might allow for confirmation of the setup before 4499launching into the game proper, but this cannot be assumed.) 4500 4501Since the details of good game synthesis can be complicated, synthesis 4502methods are simply wired-in pieces of code. Each method is 4503self-contained; it assumes the game state to be valid, it will determine 4504its own applicability and produce a valid result. It will also acquire 4505any data that it needs, so does not require any special setup; however, 4506a method may fail to run if it cannot find that data. For instance, the 4507usual fractal terrain generator needs percentiles for each terrain type, 4508and will not function without them. It may be that all the requested 4509synthesis methods fail; this is OK if @i{Xconq}'s data is present and 4510consistent, but otherwise @i{Xconq} will shut itself down, since it has 4511no remaining alternatives (think of this as a serious programming error 4512and fix the game design). 4513 4514@node Synthesis Methods 4515 4516@section Synthesis Methods 4517 4518The synthesis method list specifies which methods will be run, and in 4519what order. After they have all been run, @i{Xconq} runs a consistency 4520and completeness check. For instance, there should be a world with 4521terrain everywhere. Failure at this point is fatal; @i{Xconq} will 4522either exit or return to a game setup dialog. 4523 4524@menu 4525* Synthesis Method List:: 4526* Fractal World:: 4527* Maze World:: 4528* Random World:: 4529* Earthlike World:: 4530* Random Terrain Changes:: 4531* Making Rivers:: 4532* Making Roads:: 4533* Making Countries:: 4534* Making Independent Units:: 4535* Making Weather:: 4536* Making Initial Supply:: 4537* Naming Geographical Features:: 4538* Naming Units:: 4539* Making a Random Date:: 4540@end menu 4541 4542@node Synthesis Method List 4543 4544@subsection Synthesis Method List 4545 4546@deffn GlobalVariable @code{synthesis-methods} method-list 4547This variable is a list of synthesis methods. If the list is empty, no 4548synthesis methods will be run. 4549@end deffn 4550 4551The list of synthesis methods is ordered, and many contain duplicates, 4552so that a method can be run multiple times during setup. Note that most 4553of the existing methods will simply return if they detect that their 4554work has already been done, so multiple runs will have no effect. 4555 4556The default synthesis method list is effectively 4557@example 4558(make-fractal-percentile-terrain 4559 make-countries 4560 make-independent-units 4561 make-roads 4562 make-rivers 4563 make-weather 4564 init-supplies 4565 name-geographical-features 4566 ) 4567@end example 4568 4569@deffn GlobalVariable @code{synthesis-done} list 4570This variable is a list of what methods were used, and how many times. 4571This is for the use of the save/restore machinery, should not normally 4572be manipulated by game designers. 4573@end deffn 4574 4575@node Fractal World 4576 4577@subsection Fractal World 4578 4579The fractal world synthesizer can make a variety of natural-looking 4580terrain. It relies on a number of parameters to govern a single 4581algorithm. 4582 4583@deffn SynthesisMethod @code{make-fractal-percentile-terrain} 4584This method generates the terrain layer of a world. It works by 4585generating two distinct layers of random blobs, known as the ``alt'' and 4586``wet'' layers, then decides on a terrain type for each cell. If 4587elevations are defined, then this method will use the ``alt'' layer to 4588produce elevations. 4589@end deffn 4590 4591@deffn GlobalVariable @code{alt-blob-density} n 4592@end deffn 4593@deffn GlobalVariable @code{wet-blob-density} n 4594These variables are the number of blobs to put down, expressed as number 4595per 10,000 cells. Defaults to @code{500}. 4596@end deffn 4597 4598@deffn GlobalVariable @code{alt-blob-size} n.f% 4599@end deffn 4600@deffn GlobalVariable @code{wet-blob-size} n.f% 4601These variables are the average number of cells in a blob, expressed as 4602number per 10,000 cells. Defaults to @code{100}. 4603@end deffn 4604 4605@deffn GlobalVariable @code{alt-blob-height} n 4606@end deffn 4607@deffn GlobalVariable @code{wet-blob-height} n 4608These variables are the amounts by which to increment or decrement 4609within a blob. Defaults to @code{1000}. 4610@end deffn 4611 4612@deffn GlobalVariable @code{alt-smoothing} n 4613@end deffn 4614@deffn GlobalVariable @code{wet-smoothing} n 4615These variables specify the number of averaging steps to perform after 4616the blobs have been generated. Defaults to @code{2}. 4617@end deffn 4618 4619@deffn TerrainTypeProperty @code{alt-percentile-min} n% 4620@end deffn 4621@deffn TerrainTypeProperty @code{alt-percentile-max} n% 4622@end deffn 4623@deffn TerrainTypeProperty @code{wet-percentile-min} n% 4624@end deffn 4625@deffn TerrainTypeProperty @code{wet-percentile-max} n% 4626These properties are the percentiles of elevations and moistures that 4627result in the given terrain type. Percentile ranges may overlap, in 4628which case the earlier-defined terrain type will be used. If a cell has 4629a alt and wet that does not fall in any of the ranges, then terrain type 46300 will be used there and players will be warned. Mins defaults to 4631@code{0}, maxes to @code{100}. 4632@end deffn 4633 4634After the terrain has been assigned types, the method will give a single 4635type to all the cells on the edge of the area. 4636 4637@deffn GlobalVariable @code{edge-terrain} 4638This variable is the type of terrain to fill in on all the edges of a 4639world. The edges of a world have little or no effect on the game, but 4640the terrain type should be something distinctive, so that players can 4641recognize the edges easily. (For instance, ice is usually a good choice 4642for edges, but probably not on a map of Antarctica!) Defaults to 4643terrain type 0 (the first defined type). 4644@end deffn 4645 4646@node Maze World 4647 4648@subsection Maze World 4649 4650A maze consists of a set of randomly placed ``rooms'' connected by 4651random passages. 4652 4653@deffn SynthesisMethod @code{make-maze-terrain} 4654This method creates terrain that looks like a maze. It starts by 4655randomly assigning terrain according to its @code{occurrence}, similarly 4656to @code{make-random-terrain} below, then carves out rooms and passages, 4657filling each of those with terrain types according to their respective 4658occurrences. 4659@end deffn 4660 4661@deffn TerrainTypeProperty @code{maze-room-occurrence} n 4662This property is the weighted amount of this terrain type in rooms in 4663the maze. 4664@end deffn 4665 4666@deffn TerrainTypeProperty @code{maze-passage-occurrence} n 4667This property is the weighted amount of this terrain type in passageways 4668in the maze. 4669@end deffn 4670 4671@deffn GlobalVariable @code{maze-room-density} n 4672This variable is the fraction of the maze that is room, expressed as the 4673number of cells per 10,000 cells in the area. Defaults to @code{1000}. 4674@end deffn 4675 4676@deffn GlobalVariable @code{maze-passage-density} n 4677This variable is the fraction of the area that is passageway, expressed 4678as the number of cells per 10,000 cells in the area. Defaults to 4679@code{3000}. 4680@end deffn 4681 4682This method will apply edge terrain as a last step. 4683 4684@node Random World 4685 4686@subsection Random World 4687 4688The random world generator just assigns terrain and elevations randomly. 4689 4690@deffn SynthesisMethod @code{make-random-terrain} 4691This method generates completely random terrain. It uses a simple 4692weighting to govern how much of each terrain type appears, and makes 4693random elevations as well. 4694@end deffn 4695 4696@deffn TerrainTypeProperty @code{occurrence} n 4697This property is the percentage of the world that will be of this type, 4698if the terrain is cell terrain. If the terrain is border or connection, 4699it is the probability (expressed as .01% increments) that any direction 4700of any cell will have that border or connection. Defaults to @code{1}. 4701@end deffn 4702 4703@node Earthlike World 4704 4705@subsection Earthlike World 4706 4707Earthlike generation uses algorithms that more closely approximate 4708realistic terrain. 4709 4710@deffn SynthesisMethod @code{make-earthlike-terrain} 4711This method generates terrain that approximates what actually appears on 4712Earth. 4713@end deffn 4714 4715@node Random Terrain Changes 4716 4717@subsection Random Terrain Changes 4718 4719Terrain generation methods may postprocess the generated terrain by 4720randomly changing cells of some types. 4721 4722@deffn TableTT @code{terrain-density} t1 t2 -> .01n% 4723This table is the .01% chance that a cell of type @var{t1} will be 4724changed to type @var{t2}. 4725@end deffn 4726 4727@node Making Rivers 4728 4729@subsection Making Rivers 4730 4731Rivers are borders or connections consisting of ``watery terrain'' that 4732run downhill to regions of water. 4733 4734@deffn SynthesisMethod @code{make-rivers} 4735This method looks for a border or connection terrain type with a 4736@code{subtype-x} of @code{river-x}. then uses the world's elevation 4737data to run rivers downhill (always choosing the lowest of possible 4738adjacent locations) until they reach cell terrain with a @code{subtype} 4739> 0. This method will not run if there are no appropriate terrain 4740types, nor if there is no elevation data. 4741@end deffn 4742 4743@deffn TerrainTypeProperty @code{river-chance} .01n% 4744This property is the chance that a river will start in or around a cell 4745of this terrain type. 4746@end deffn 4747 4748@deffn GlobalVariable @code{river-sink-terrain} t 4749If the value of this variable is a terrain type, then a cell completely 4750surrounded by river will be changed to be this type. Defaults to 4751@code{non-terrain}. 4752@end deffn 4753 4754Note that the algorithm computes rivers in a deterministic way, so high 4755values of @code{river-chance} do not result in tangled rivers. 4756 4757@node Making Roads 4758 4759@subsection Making Roads 4760 4761The road generation method makes networks of connection terrain between 4762particular unit types, usually those resembling cities. 4763 4764@deffn SynthesisMethod @code{make-roads} 4765This methods synthesizes roads for an area. For any connection type of 4766terrain, if no layer has been created for it already, and the type has a 4767@code{subtype-x} of 3, put down roads between any pair of units whose 4768@code{road-chance} is nonzero. The method will attempt to share road 4769routes whenever possible, and choose terrain according to 4770@code{road-into-chance}. In addition, the method may also generate spur 4771roads connecting units to existing roads, and run roads from one edge of 4772the area to another. 4773@end deffn 4774 4775@deffn TableUU @code{road-chance} u1 u2 -> n% 4776This table is the chance that a road will be laid, running from a unit 4777of type @var{u1} to one of type @var{u2}. Note that is not a 4778symmetrical relationship; since roads follow random paths, if the 4779@code{road-chance} causes a road to be laid from @var{u1} to @var{u2}, 4780and another from @var{u2} to @var{u1}, it is quite possible that the 4781result will be two different roads connecting the two units. 4782@end deffn 4783 4784@deffn TableTT @code{road-into-chance} t1 t2 -> n% 4785This table is the chance that a road will be chosen to pass from terrain 4786of type @var{t1} into terrain of type @var{t2}. 4787@end deffn 4788 4789@deffn UnitTypeProperty @code{spur-chance} n% 4790This property is the percentage chance that the unit will get a spur 4791road running from the unit to the nearest existing road. 4792@end deffn 4793 4794@deffn UnitTypeProperty @code{spur-range} dist 4795This property is the radius of the area that will be searched for an 4796existing road. Defaults to @code{1}, which results in spurs connecting 4797only to roads in adjacent cells. 4798@end deffn 4799 4800@deffn UnitTypeProperty @code{road-to-edge-chance} n% 4801This property is the percentage chance that the unit will have a road 4802running from the unit to some edge of the area. 4803@end deffn 4804 4805@deffn GlobalVariable @code{edge-road-density} n 4806This variable is the density of roads that run from one area edge to 4807another, expressed as the number per 10,000 cells in the area. (note, 4808not counting just edge cells). 4809@end deffn 4810 4811@node Making Countries 4812 4813@subsection Making Countries 4814 4815The @code{make-countries} method sets up the starting units for each 4816side, placing them in a confined area, separated from the starting units 4817of other sides and taking terrain preferences into account. If 4818requested, this method will also expand the country outwards by a 4819specified amount, possibly placing additional units in the process. 4820 4821@deffn SynthesisMethod @code{make-countries} 4822This method works by looking for a likely place for the country, 4823randomly places a basic set of starting units within that area, then 4824expands the country outwards. The parameters give you control over the 4825mix of terrain types in the country, as well as the size and relative 4826positions of the different countries. This method runs on any side with 4827fewer units than it is supposed to start with, as given by the 4828parameters below. It places groups of units at locations separated from 4829each other by specified distances. 4830@end deffn 4831 4832@deffn GlobalVariable @code{country-radius-min} dist 4833This variable is the radius of the country's initial area. Defaults to 4834@code{-1}, which allows the algorithm to calculate a ``reasonable'' 4835country size appropriate to the given number of units. 4836@end deffn 4837 4838@deffn GlobalVariable @code{country-separation-min} dist 4839@end deffn 4840@deffn GlobalVariable @code{country-separation-max} dist 4841These variables are the minimum and maximum distances of country centers 4842from each other, in cells. If small, countries will mostly overlap; if 4843very large, then attempts to use small worlds will fail; if the max and 4844min are too close to each other, placements can also fail. For both of 4845these, a value of @code{-1} disables their effect. Both default to 4846@code{-1}. 4847@end deffn 4848 4849The max separation bound needs to be satisfied for a country with 4850respect to only @i{one} other country, so for instance the final layout 4851may involve a long ``string'' of countries where the first and last 4852countries are very far apart from each other. The minimum bound must be 4853satisfied for all pairs of countries. 4854 4855@deffn TerrainTypeProperty @code{country-terrain-min} n 4856This property is the minimum amount of terrain that must be within the 4857country's initial radius. 4858@end deffn 4859 4860@deffn TerrainTypeProperty @code{country-terrain-max} n 4861This property is the most terrain of the given type that may appear. If 4862@code{-1}, then any amount may be present. Defaults to @code{-1}. 4863@end deffn 4864 4865@deffn UnitTypeProperty @code{start-with} n 4866@end deffn 4867@deffn UnitTypeProperty @code{independent-near-start} n 4868These properties set the number of units of the given type in a player's 4869country. These units are randomly scattered within the initial radius, 4870and the @code{favored} table (see below) decides which terrains will be 4871used. Units may be placed inside each other; in fact, units with no 4872favored terrain will be made into occupants if possible. 4873 4874The independent units will be placed after the ones belonging to the 4875side, so on the average they will get the less desirable locations in 4876the country. Unlike the randomly-scattered independent units, these 4877will be named using the side's namers. 4878 4879Both default to @code{0}. 4880@end deffn 4881 4882@deffn TableUT @code{favored-terrain} u t -> n% 4883This table sets the probability of the unit type being on the given type 4884of terrain at the outset. A value of @code{0} is an absolute 4885prohibition against placing the unit on that type of terrain, thus every 4886game must specify at least one non-zero value for some terrain type and 4887some initial unit type. Defaults to @code{100}. 4888@end deffn 4889 4890Once the initial country area has been set up, then you can allow the 4891countries to expand outwards. Expansion occurs at the same rate for all 4892countries. Countries may expand into and through each other. Expansion 4893occurs as a number of @var{steps}, each step increasing the radius of 4894countries by 1 all around. 4895 4896@deffn TerrainTypeProperty @code{country-growth-chance} n% 4897This property is the chance that a country will expand onto an unclaimed 4898cell of the given terrain type. Defaults to @code{100}. 4899@end deffn 4900 4901@deffn TerrainTypeProperty @code{country-takeover-chance} n% 4902This property is the chance that a country will expand onto another 4903country's cell of the given terrain type. 4904@end deffn 4905 4906@deffn UnitTypeProperty @code{unit-growth-chance} n.f% 4907This property is the chance that a unit of the given type will be placed 4908when the country expands onto a cell. The unit will only be placed if 4909the @code{favored} chance is also true. 4910@end deffn 4911 4912@deffn UnitTypeProperty @code{independent-growth-chance} n.f% 4913This property is the chance that an independent unit of the given type 4914will be placed when the country expands onto a cell. The @code{favored} 4915chance is also evaluated. 4916@end deffn 4917 4918@deffn UnitTypeProperty @code{unit-takeover-chance} n.f% 4919This property is the chance that a unit of the given type in another 4920country and belonging to another side will be given to the growing side. 4921@end deffn 4922 4923@deffn UnitTypeProperty @code{independent-takeover-chance} n.f% 4924This property is the chance that an independent unit of the given type 4925in another country will be given to the growing side. 4926@end deffn 4927 4928@deffn GlobalVariable @code{country-radius-max} dist 4929This variable is a cap on the country growth process. Values between 4930@code{0} and @code{country-radius-min} prevent country growth entirely, 4931while a value of @code{-1} allows growth to encompass the entire world. 4932@end deffn 4933 4934@deffn UnitTypeProperty @code{country-units-max} n 4935This property is a cap on the number of units given to the side's 4936country. Defaults to @code{-1}, which disables any limit. 4937@end deffn 4938 4939@deffn GlobalVariable @code{growth-stop-chance} n% 4940This variable is the chance that a country's growth will stop, if during 4941the current step no new cells were added to the country. 4942@end deffn 4943 4944@deffn TerrainTypeProperty @code{country-people-chance} n% 4945This property is the chance that the people's side will be changed to 4946match that for the country they are in. Defaults to @code{100}. 4947@end deffn 4948 4949@node Making Independent Units 4950 4951@subsection Making Independent Units 4952 4953@deffn SynthesisMethod @code{make-independent-units} 4954This method scatters independent units randomly over the world. This 4955method will not run if the specified density of independent units has 4956already been achieved, for instance from a predefined world or from 4957country placement. Independent units that should be inside other 4958independents will be handled correctly. 4959@end deffn 4960 4961@deffn TableUT @code{independent-density} u t -> .01n% 4962This table is the probability that an independent unit of 4963type @var{u} will be placed on a empty cell with terrain 4964of type @var{t}. 4965@end deffn 4966 4967@deffn TerrainTypeProperty @code{independent-people-chance} .01n% 4968This property is the chance that the people of a cell with this terrain 4969type will be made independent. 4970@end deffn 4971 4972@node Making Weather 4973 4974@subsection Making Weather 4975 4976Weather synthesis sets up an initial state for the weather. 4977 4978@deffn SynthesisMethod @code{make-weather} 4979This method sets up weather-related layers, including temperature, 4980winds, and clouds. 4981@end deffn 4982 4983@node Making Initial Supply 4984 4985@subsection Making Initial Supply 4986 4987By default, all units start out empty of materials. The supply 4988initialization method gives each unit a starting supply, according to 4989the initial supply tables. 4990 4991@deffn SynthesisMethod @code{make-initial-materials} 4992This method fills unit and cell supplies to specified levels. It will 4993fill all units in existence at the moment it runs, including units that 4994have not appeared yet. Similarly, all cells will be filled. 4995@end deffn 4996 4997@deffn TableUM @code{unit-initial-supply} u m -> n 4998This table is the amount of each material that each unit will start out 4999with. If the initial supply is greater than unit's capacity, then the 5000unit will just be filled to capacity. 5001@end deffn 5002 5003Terrain cells may also have initial material levels. 5004 5005@deffn TableTM @code{terrain-initial-supply} t m -> n 5006This table is the amount of material @var{m} that each cell with terrain 5007@var{t} will start out with. This will be limited by the cell's 5008capacity. 5009@end deffn 5010 5011Sides with treasuries may start with an initial amount. 5012 5013@deffn MaterialTypeProperty @code{initial-treasury} n 5014This is the amount of each material type that a side's treasury 5015will start with. 5016@end deffn 5017 5018@deffn GlobalVariable @code{indepside-has-treasury} t/f 5019This is true if the independent units have a common treasury. (This may 5020be necessary if indeps may construct units, and those units need 5021treasury material.) 5022@end deffn 5023 5024@deffn GlobalVariable @code{treasury-size} n 5025This is the size of each treasury. All treasuries are the same size. 5026@end deffn 5027 5028@node Naming Geographical Features 5029 5030@subsection Naming Geographical Features 5031 5032Although named geographical features don't affect the outcome of a game 5033in any way, they are useful for ``color'' and for identifying locations 5034more readably. 5035 5036@deffn SynthesisMethod @code{name-geographical-features} 5037This method identifies and names regions as geographical features, such 5038as mountain ranges and islands. 5039@end deffn 5040 5041@deffn GlobalVariable @code{feature-namers} feature-namer-list 5042This variable is a list of feature types and their associated namers. 5043This is used for features not intersecting any country with a namer for 5044the feature's type. Defaults to @code{()}. 5045@end deffn 5046 5047@deffn GlobalVariable @code{feature-types} feature-expr-list 5048This variable is a list of feature types that may be identified. Each 5049list element has the form @code{(typename [name] [parameters])}, where 5050@var{typename} is from the list given below, @var{name} is the specific 5051name of the type (which is used in @code{feature-namers}, and 5052@var{parameters} is any optional parameters describing how to 5053identify features of that type. Defaults to @code{()}. 5054@end deffn 5055 5056@itemize @bullet 5057 5058@item @code{peak} [name] [density] 5059This type causes the synthesizer to look for high points, at a density 5060of @var{density} per 10,000 cells (defaulting to 50). 5061 5062@item @code{island} [name] [sizemax] 5063This type identifies areas of non-liquid terrain surrounded by liquid 5064terrain, up to @var{sizemax} (default 30) cells in size. 5065 5066@item @code{lake} [name] [sizemax] 5067This type identifies areas of liquid terrain surrounded by non-liquid 5068terrain, up to @var{sizemax} (default 30) cells in size. 5069 5070@item @code{bay} [name] 5071This type identifies cells that are liquid but at least 2/3 surrounded 5072by non-liquid terrain. 5073 5074@end itemize 5075 5076@node Naming Units 5077 5078@subsection Naming Units 5079 5080@deffn SynthesisMethod @code{name-units-randomly} 5081This method gives names to previously-unnamed units, using their usual 5082namers. 5083@end deffn 5084 5085@node Making a Random Date 5086 5087@subsection Making a Random Date 5088 5089For extra color, games can be set up to start at a random date within a 5090given range. If day or year effects are defined, this also has the 5091effect of making the game start at a random time of day or year. 5092 5093@deffn SynthesisMethod @code{make-random-date} 5094This method generates a random starting date, within specified bounds. 5095@end deffn 5096 5097@deffn GlobalVariable @code{initial-date-min} date 5098This variable is the earliest possible date for the game. Defaults to 5099@code{""}. 5100@end deffn 5101 5102@deffn GlobalVariable @code{initial-date-max} date 5103This variable is the latest possible date for the game. Defaults to 5104@code{""}. 5105@end deffn 5106 5107@node Setup Postprocessing 5108 5109@section Setup Postprocessing 5110 5111Some initialization steps will be done after all synthesis methods 5112have been run. @i{Xconq} will always do these. 5113 5114@menu 5115* Initial View:: 5116@end menu 5117 5118@node Initial View 5119 5120@subsection Initial View 5121 5122By default, each side starts out knowing only what its units can 5123normally see at the beginning of the first turn. These parameters add 5124to that initial view. 5125 5126@deffn GlobalVariable @code{terrain-seen} t/f 5127This variable is @code{true} if all the terrain of the world is known 5128initially. Defaults to @code{false}. 5129@end deffn 5130 5131@deffn UnitTypeProperty @code{initial-seen-radius} dist 5132This property specifies the radius of the area seen around each of the 5133starting units. It computes visibility of terrain (cells and borders) 5134only. Defaults to @code{1} (which is a no-op if the unit's 5135@code{vision-range} is greater than or equal to 1). 5136@end deffn 5137 5138@deffn UnitTypeProperty @code{already-seen} n% 5139This property is the chance to see units of this type at the beginning 5140of the game. This applies only to units belonging to another side, and 5141on known terrain. The effect is one-time, so if an @code{already-seen} 5142unit changes sides later on, other players will not see the change 5143unless they have the unit under observation for themselves. Note that 5144@code{see-always} implies @code{already-seen}. 5145@end deffn 5146 5147@deffn UnitTypeProperty @code{already-seen-independent} n% 5148This property is like @code{already-seen}, but applies to independent 5149units specifically. 5150@end deffn 5151 5152@node Naming and Text Generation 5153 5154@section Naming and Text Generation 5155 5156@i{Xconq} can generate names for sides, units, and geographical 5157features. Although most naming happens during game setup, names may be 5158assigned throughout the course of a game, both automatically and by 5159player request. 5160 5161@menu 5162* Naming Sides:: 5163* Namers:: 5164* Naming Methods:: 5165* Notices and Narratives:: 5166@end menu 5167 5168@node Naming Sides 5169 5170@subsection Naming Sides 5171 5172Side naming is special, because several different but related names 5173have to be produced. The use of a @dfn{side library} is a way to gain 5174finer control over side names and their associated plural and 5175possessive variations than one would have through the use of a 5176@code{side-namer}. 5177 5178@deffn GlobalVariable @code{side-library} side-info@dots{} 5179This variable is a weighted list of groups of side properties, each of 5180which may be used to fill in a side. 5181@end deffn 5182 5183The form of each side name entry is basically a subset of the side's 5184properties: 5185@example 5186([ weight ] ... (name <name>) ... (color <colors>) ...) 5187@end example 5188Each entry can include as many or as few of the attributes as desired; 5189any missing will be filled in from the usual defaults. The optional 5190@var{weight} is a number that adjusts the probability of selection of 5191the given side name set; it defaults to 1, and the probability is scaled 5192according to the sum of the weights for all the sides listed. If any 5193property value is a namer, then the namer will be run. (Note that if 5194multiple namers are specified, they cannot be guaranteed to coordinate 5195with each other, so you can end up with a side noun that is 5196inappropriate for its corresponding side name.) 5197 5198@deffn GlobalVariable @code{side-color-library} side-info@dots{} 5199This variable is a weighted list of side color schemes, each of 5200which may be used to fill in a side's color scheme. The values 5201from this list are only used if the entry from @code{side-library} 5202does not supply a color scheme. 5203@end deffn 5204 5205@node Namers 5206 5207@subsection Namers 5208 5209Since one of the purposes of naming is to identify objects uniquely, any 5210name generator should be able to maintain some memory as to what has 5211been generated already. The objects that do this are @dfn{namers}. 5212 5213@deffn Form @code{namer} symbol/id method 5214This form defines an instance of a namer, with either the symbolic name 5215or numeric id. If either matches the name or id of an existing namer, 5216then the old namer will be overwritten, otherwise a new one will be 5217created. The @var{method} must be one of the naming methods listed 5218below. 5219@end deffn 5220 5221@deffn GlobalVariable @code{default-namer} str 5222This namer may be used when another namer can no longer produce names, 5223such as a random namer that exhausts its list of possibilities. At 5224present, it is used only with the @code{junky} and @code{random} naming 5225methods (presumably the @code{grammar} is inexhaustible!). 5226@end deffn 5227 5228@node Naming Methods 5229 5230@subsection Naming Methods 5231 5232As with general synthesis, @i{Xconq} has a number of @dfn{naming methods} 5233available. 5234 5235@deffn NamingMethod @code{random} names @dots{} 5236This method picks a name from the given list of names and removes that 5237name from the list. 5238@end deffn 5239 5240@deffn NamingMethod @code{junky} 5241This method produces a gobbledy-gook name, very techy-looking. 5242@end deffn 5243 5244@deffn NamingMethod @code{in-order} names @dots{} 5245This method pulls names from a list in the order that they appear. 5246@end deffn 5247 5248@deffn NamingMethod @code{grammar} root max-length rules@dots{} 5249This method defines a grammar, where @var{root} is the root symbol, 5250@var{max-length} is a limit on the length of the generated names (in 5251characters), and @var{rules} is a list of rules of the form 5252@example 5253(@var{symbol} @var{rule-body}) 5254@end example 5255The @var{rule-body} can have the following forms: 5256@example 5257(@var{rule-body} @var{rule-body} ...) 5258(or [ @var{weight} ] @var{rule-body} [ @var{weight} ] @var{rule-body} ...) 5259(capitalize @var{rule-body}) 5260(reject @var{rule-body} string-or-sym ...) 5261symbol 5262string 5263@end example 5264@end deffn 5265 5266The generation process for @code{or} works by substituting one of the 5267rule's alternatives for the symbol. The probability of an alternative 5268being selected is arrived at by adding up the optional weights 5269@var{weight} (assuming missing weights to be @code{1}), and choosing 5270with a probability of the weight divided by the total sum of weights. 5271Thus the weights need not add up to any particular value. 5272 5273If the list is not prefixed by any of the special symbols, then each 5274rule body in the list is expanded, and the results concatenated. 5275 5276Strings and symbols that are not terminals get used directly. If a 5277symbol in the rule's chosen expansion does not appear as the lefthand 5278side in any rule, then it will be handled as a string, otherwise it will 5279be expanded in turn. If the symbol matches a namer's name, then that 5280namer will be run and its result incorporated. 5281 5282@deffn GlobalConstant @code{or} 5283This designates a list of alternatives. 5284@end deffn 5285 5286@deffn Symbol @code{capitalize} 5287Directs capitalization of the result generated by the rule body. 5288@end deffn 5289 5290@deffn Symbol @code{reject} 5291A rule body headed by @code{reject} includes a list of substrings that 5292should not appear in a generated name; this is a convenient way to 5293filter out particularly unlovely results. This works by retrying 5294generation if one of the listed strings appears in the name generated by 5295the rule body in the form. 5296@end deffn 5297 5298@node Notices and Narratives 5299 5300@subsection Notices and Narratives 5301 5302@deffn GlobalVariable @code{action-notices} patterns 5303This variable is a list of patterns that an interface may use to 5304generate textual notices of unit actions. 5305Defaults to @code{()}. 5306@end deffn 5307 5308@deffn GlobalVariable @code{action-movies} patterns 5309This variable is similar, but instead of generating text, the result 5310of a match is a designation of a movie (an animation or sound). 5311Defaults to @code{()}. 5312@end deffn 5313 5314@deffn GlobalVariable @code{event-notices} patterns 5315This variable is a list of patterns that an interface may use to 5316generate textual notices of historical events. 5317Defaults to @code{()}. 5318@end deffn 5319 5320@deffn GlobalVariable @code{event-narratives} patterns 5321This variable is similar, but its text is in the past tense. 5322Defaults to @code{()}. 5323@end deffn 5324 5325@deffn GlobalVariable @code{event-movies} patterns 5326This variable is similar, but instead of generating text, the result 5327of a match is a designation of a movie (an animation or sound). 5328Defaults to @code{()}. 5329@end deffn 5330 5331@node Actions 5332 5333@section Actions 5334 5335The parameters in this section define and regulate the various actions 5336that are available to units during a game. 5337 5338Actions always start and complete (including all of their effects) 5339within the same turn, and a unit can only do one at a time. 5340 5341All actions are potentially available to all units, but the parameters 5342can be set so as to deny any action type to any unit type. See the 5343descriptions with each action type. 5344 5345All action is limited by action points. Each unit gets a certain number 5346at the beginning of each turn and expends them in the course of doing 5347things. The usual expenditure is one point per action, but may be more, 5348as defined for each type of action. A unit action must always consume 5349at least one action point. Units can accumulate acp from turn to turn, 5350and they can also reduce acp below zero. 5351 5352@menu 5353* Actions in General:: 5354* Action Ordering:: 5355* Movement Action:: 5356* Entry Action:: 5357* Develop Action:: 5358* Toolup Action:: 5359* Unit Creation Actions:: 5360* Unit Completion Action:: 5361* Repair Action:: 5362* Material Production Action:: 5363* Material Extraction Action:: 5364* Material Transfer Action:: 5365* Side Change Action:: 5366* Disband Action:: 5367* Part Transfer Action:: 5368* Type Change Action:: 5369* Combat Actions:: 5370* Capture Action:: 5371* Detonation Action:: 5372* Terrain Alteration Actions:: 5373@end menu 5374 5375@node Actions in General 5376 5377@subsection Actions in General 5378 5379@deffn UnitTypeProperty @code{acp-per-turn} acp 5380This property is the basic allowance of action points that a unit gets 5381each turn. 5382@end deffn 5383 5384@deffn UnitTypeProperty @code{acp-min} acp 5385This property specifies how far into ``action debt'' a unit can go 5386during a turn before it is prevented entirely from acting. A unit with 5387acp < 1 at the beginning of a turn cannot do anything at all. 5388@end deffn 5389 5390@deffn UnitTypeProperty @code{acp-max} acp 5391This property is the maximum number of action points that a unit can 5392save up. The value @code{-1} means that @code{acp-max} is equal to 5393@code{acp}. Extra acp is silently lost. Defaults to @code{-1}. 5394@end deffn 5395 5396@deffn UnitTypeProperty @code{free-acp} acp 5397This is the amount by which the acp for some action can exceed the 5398difference between the unit's currently available acp and its minimum acp, 5399and still allow that action. By default, no free acp is awarded. 5400@end deffn 5401 5402Note that a unit with an acp of 0 and an acp-min of 0 is completely 5403unintelligent, about like a cow patty. Cow patties can be useful for 5404blocking paths, hiding behind, and suchlike, and have the advantage that 5405once they're in place, you don't have to manage them. Other units will 5406have to pick them up and put them down, of course. 5407 5408@deffn TableUM @code{material-to-act} u m -> n 5409This table is a minimum amount of @var{m} needed for @var{u} to be able 5410to act. The material is not consumed. 5411@end deffn 5412 5413@deffn UnitTypeProperty @code{acp-damage-effect} interpolation-list 5414This property is the effect of a unit's hp on its acp. The input value 5415is hp, while the output value is the acp to be added instead of 5416@code{acp-per-turn}. This list does not extrapolate. Defaults to 5417@code{()}. 5418@end deffn 5419 5420@deffn TableUT @code{night-adds-acp} u t -> n 5421Action points can be added to an unit of type @var{u} if it is night 5422at the cell of type @var{t} where it is located. Subtraction can be 5423done as a negative addition.@* 5424NOTE: Currently applies only to cell terrain subtypes.@* 5425NOTE: This can generally be expected to be only applied at the start of 5426a turn. 5427@end deffn 5428 5429@deffn TableUT @code{night-multiplies-acp} u t -> .01n 5430Available action points can be multiplied against a factor @var{n} if 5431an unit of type @var{u} is on a cell with terrain @var{t} when it is 5432night. Defaults to @code{1.00}.@* 5433NOTE: Currently applies only to cell terrain subtypes.@* 5434NOTE: This can generally be expected to be only applied at the start of 5435a turn. 5436@end deffn 5437 5438@deffn TableUU @code{occupant-adds-acp} u1 u2 -> n 5439If an occupant of type @var{u2} is in a transport of type @var{u1}, 5440then the occupant can confer @var{n} action points upon the transport.@* 5441NOTE: Presently, the available ACP of an unit is only updated at the 5442beginning of turns. So, available ACP will not immediately change upon 5443entry of the ACP-affecting occupant. This behvaior may change in the 5444near future, so that the effect will be immediate. 5445@end deffn 5446 5447@deffn TableUU @code{occupant-multiplies-acp} u1 u2 -> .01n 5448If an occupant of type @var{u2} is in a transport of type @var{u1}, 5449then the occupant may have a multiplicative effect on the 5450transport's action points by a factor @var{n}. Defaults to @code{1.00}.@* 5451NOTE: Presently, the available ACP of an unit is only updated at the 5452beginning of turns. So, available ACP will not immediately change upon 5453entry of the ACP-affecting occupant. This behvaior may change in the 5454near future, so that the effect will be immediate. 5455@end deffn 5456 5457@deffn UnitTypeProperty @code{acp-morale-effect} interpolation-list 5458This property is the effect of morale on acp. The input value is 5459morale, and the result value is multiplied with acp, after it has been 5460modified for night effect, but before modification for temperature. The 5461result is divided by 100, so an effect < 100 reduces acp, an effect of 5462100 has no effect, and an effect > 100 increases acp. Defaults to 5463@code{()}. 5464@end deffn 5465 5466@deffn UnitTypeProperty @code{acp-per-turn-min} acp 5467This property sets a lower limit on the effect of occupants, damage, and 5468other modifiers on the acp to be added at the beginning of the turn. 5469@end deffn 5470 5471@deffn UnitTypeProperty @code{acp-per-turn-max} acp 5472This property sets the upper limit on the effect of occupants and other 5473modifiers to the acp added at the beginning of the turn. Defaults to 5474@code{-1}, which indicates that there is no limit. 5475@end deffn 5476 5477@deffn UnitTypeProperty @code{acp-independent} t/f 5478This property indicates that the unit's actions are to be limited by 5479materials, rather than by a fixed number of acp each turn. 5480@end deffn 5481 5482@node Action Ordering 5483 5484@subsection Action Ordering 5485 5486@deffn GlobalVariable @code{use-side-priority} t/f 5487This variable is @code{true} if the sides may only act one at a time; 5488otherwise, all sides and units may move simultaneously during a turn. 5489Defaults to @code{false}. This variable is also set by the 5490@code{sequential} variant. 5491@end deffn 5492 5493@deffn UnitTypeProperty @code{action-priority} n 5494This property is the order in which units of this type will act. Higher 5495numbers act earlier. If the difference between the priority of one type 5496and another is greater than 100, then the earlier-acting units must 5497finish acting before the later-acting units, otherwise a player can 5498rearrange the actual acting order as desired. 5499@end deffn 5500 5501@node Movement Action 5502 5503@subsection Movement Action 5504 5505Movement is the most common sort of action. 5506This section covers movement over open terrain; 5507the next section discusses interaction with transports. 5508 5509The general theory of movement is that a unit not in a transport 5510crosses its current cell terrain to the edge of the cell, 5511crosses any border terrain, and then moves into the destination cell, 5512OR it moves onto connection terrain, 5513travels along connection terrain to the new cell, and maybe 5514moves off the connection. 5515If the unit starts in a transport, then the transport may ferry 5516the unit over some of the intervening terrain, 5517possibly as far as the unit's destination. 5518 5519A unit's basic movement rate is defined by its @dfn{speed}, 5520which is a ratio of the the unit's acp. 5521A speed of 100% means that the unit can potentially 5522enter as many cells as it has acp, 5523while a speed of 20% means that the unit uses at least 55245 acp to enter a cell. 5525 5526Movement can only succeed if several conditions are met: 5527the unit must be able to cross 5528the border terrain, the destination must be inside the world (but see below), 5529it must be able to exist on the terrain of the destination. 5530 5531@deffn ActionType @code{move} x y z 5532This is the action that a unit performs to go from its current 5533location to the cell at @var{x},@var{y} at altitude @var{z}. 5534The destination must be within the @code{move-range} of the unit. 5535@end deffn 5536 5537@deffn UnitTypeProperty @code{acp-to-move} acp 5538This property is the number of acp a unit uses to do one move action. 5539Defaults to @code{1}. 5540@end deffn 5541 5542@deffn UnitTypeProperty @code{speed} n 5543This property is the basic multiplier relating acp to the number 5544of cells that may be entered during a turn. 5545Defaults to @code{100}. 5546@end deffn 5547 5548@deffn UnitTypeProperty @code{speed-damage-effect} interpolation-list 5549This property is the unit's speed if it is damaged. 5550The input value is the unit's hp, while the result value is the 5551unit speed to use instead of @code{speed}. 5552Defaults to @code{()}. 5553@end deffn 5554 5555@deffn TableUU @code{occupant-adds-speed} u1 u2 -> n% 5556Each value in this table is the amount of speed 5557that an occupant @var{u2} adds to transport @var{u1}. 5558@end deffn 5559 5560@deffn TableUU @code{occupant-multiplies-speed} u1 u2 -> n% 5561Each value in this table is the factor an occupant 5562@var{u2} multiplies the accumulated speed (including 5563additive effects) of a transport @var{u1} by. 5564Defaults to @code{100%}. 5565@end deffn 5566 5567@deffn UnitTypeProperty @code{speed-wind-effect} list 5568This property is a list that describes the effect of wind on the unit's 5569speed. The effect is calculated using a combination of the cells being 5570left and entered. 5571The format of the list is 5572@display 5573@code{((@var{angle-list} @value{value}) ...)} 5574@end display 5575where @i{angle-list} is a single number, list of number, or the symbol 5576@code{all}, and the @var{value} is either a number, or a list of the 5577form 5578@display 5579@code{((@var{force} @var{number}) (@var{force} @var{number}) ...)} 5580@end display 5581For hex areas, the angles are 0 for downwind (same direction), 1, 2, and 55823 for directly upwind (opposite direction). The @i{force} is the wind 5583force in the cell, and @i{number} is the multiplier for the speed, with 5584@code{100} having no effect, numbers less than @code{100} decreasing the 5585unit's speed, and numbers greater than @code{100} increasing it. 5586Defaults to @code{()}. 5587@end deffn 5588 5589@deffn UnitTypeProperty @code{speed-min} mp 5590This property is the worst-case speed of a unit. 5591@end deffn 5592 5593@deffn UnitTypeProperty @code{speed-max} mp 5594This property is the upper bound on a unit's movement in one turn. (?) 5595@end deffn 5596 5597@deffn UnitTypeProperty @code{move-range} n 5598This property is the maximum distance allowed to the destination cell. 5599Defaults to @code{1}. 5600@end deffn 5601 5602The product of a unit's acp and its speed is its available @dfn{movement points}. 5603Any move between cells will cost at least one movement point. 5604Some mp costs may be negative, but the total mp for a move will always 5605be at least 1. 5606 5607@deffn TableUT @code{mp-to-leave-terrain} u t -> mp 5608This table is the mp cost to leave a cell of type @var{t}. 5609If @var{t} is a border type, this cost is never used. 5610If @var{t} is a connection type, this cost is the cost of leaving the 5611connection terrain for the open terrain of the cell. 5612If @var{t} is a coating type, then this value adds to the cost 5613of leaving the cell. 5614@end deffn 5615 5616@deffn TableUT @code{mp-to-enter-terrain} u t -> mp 5617This table is the mp cost to enter a cell of type @var{t}. 5618If @var{t} is a border type, this cost is the 5619cost of crossing the border. 5620If @var{t} is a connection type, this cost is the cost of entering the 5621connection terrain from the open terrain of the cell. 5622If @var{t} is a coating type, then this value adds to the cost 5623of entering the cell. 5624Defaults to @code{1}. 5625@end deffn 5626 5627@deffn TableUT @code{mp-to-traverse} u t -> mp 5628This table gives the cost to travel along a connection or border of the 5629given type. (note that the other costs are irrelevant if unit starts 5630and ends its movement on the connection). 5631 5632A special type of move known as a @dfn{border slide} can occur when the 5633endpoints of a border touch on the start and destination cells. Sliding 5634works like normal movement that happens to end up on a nonadjacent cell. 5635Same rules for permissibility apply. If the value is negative, then 5636border sliding is not possible. 5637 5638Defaults to @code{-1}. 5639@end deffn 5640 5641If both enter/traverse/leave and enter/leave movement is possible, 5642then @i{Xconq} will automatically choose the cheapest alternative. 5643 5644Each unit type has a range of altitudes within which it normally operates. 5645 5646@deffn TableUT @code{altitude-min} u t -> n 5647This table is the minimum altitude possible for each type of unit 5648on each type of terrain. 5649@end deffn 5650 5651@deffn TableUT @code{altitude-max} u t -> n 5652This table is the maximum altitude possible for each type of unit 5653on each type of terrain. 5654@end deffn 5655 5656@deffn UnitTypeProperty @code{mp-to-leave-world} mp 5657This property is an additional move cost to leave the world entirely. 5658To leave, the unit must be within its @code{move-range} of an edge, and 5659have sufficient mp to move into the terrain in the edge cell designated 5660as the destination of the move. If the value is @code{-1}, then the 5661unit may never leave. Defaults to @code{-1}. 5662@end deffn 5663 5664@deffn UnitTypeProperty @code{free-mp} mp 5665This property is the amount by which the move points can ``go into the 5666red'' and still allow one more move. 5667@end deffn 5668 5669ZOC is exerted only over units out in the open, has no effect on 5670occupants, unless they leave their transport. Occupants can themselves 5671exert a ZOC, if @code{occupant-can-fight} is true. ZOC applies to all 5672units on a hostile side. 5673 5674@deffn TableUU @code{zoc-range} u1 u2 -> dist 5675This table is the maximum distance at which type @var{u1} exerts a ZOC 5676over type @var{u2}. A value of @code{0} means that the unit controls 5677only its own cell, and a value of @code{-1} means that the unit does not 5678exert a ZOC at all. Defaults to @code{0}. 5679@end deffn 5680 5681@deffn TableUT @code{zoc-into-terrain} u t -> t/f 5682This table is @code{true} if the unit exerts its ZOC into terrain 5683@var{t}. Defaults to @code{true}. 5684@end deffn 5685 5686@deffn TableUT @code{zoc-from-terrain-effect} u t -> n 5687Defaults to @code{100}. 5688@end deffn 5689 5690@deffn TableUU @code{mp-to-enter-zoc} u1 u2 -> mp 5691This table specifies extra movement points needed to enter the ZOC. 5692@code{-1} prevents entry entirely. Defaults to @code{-1}. 5693@end deffn 5694 5695@deffn TableUU @code{mp-to-leave-zoc} u1 u2 -> mp 5696This table specifies extra movement points needed to leave the ZOC. 5697@code{-1} prevents departure entirely. 5698@end deffn 5699 5700@deffn TableUU @code{mp-to-traverse-zoc} u1 u2 -> mp 5701This table specifies extra movement points needed to move within the 5702ZOC. @code{-1} prevents traversal entirely. 5703@end deffn 5704 5705If multiple units exert a ZOC into the same cell, then the mp cost is 5706the maximum of the different ZOC costs. 5707 5708@deffn TableUU @code{mp-to-enter-own} u1 u2 -> mp 5709This table specifies extra movement points needed to enter a unit's own 5710cell, irrespective of ZOC. @code{-1} prevents entry entirely. Defaults 5711to @code{-1}. 5712@end deffn 5713 5714Units may use up some of their materials when they move. Consumption 5715happens after the move action, and only for successful moves. 5716 5717@deffn TableUM @code{material-to-move} u m -> n 5718This table is the amount of each material that a unit of type @var{u} 5719must have in order to be able to move. 5720@end deffn 5721 5722@deffn TableUM @code{consumption-per-move} u m -> n 5723This table is the amount of each material used by a unit to do one move 5724action. The amount taken is independent of terrain. If the unit has 5725less than the required amount of any of these materials, it is 5726immobilized until it gets more (this is tested before each move action; 5727note that this does not affect any other action, including entering and 5728leaving transports). 5729@end deffn 5730 5731@deffn TableUT @code{control-range} u t -> dist 5732This table is the distance out to which a unit's entry into a cell 5733changes control of the surrounding terrain. A distance of 0 means that 5734the unit only changes control for its own cell, while a distance of -1 5735means that the unit does not affect control. Defaults to @code{-1}. 5736 5737At present, the maximum value for this is 0 (in other words, a unit 5738cannot change control in adjacent cells). 5739@end deffn 5740 5741@node Entry Action 5742 5743@subsection Entry Action 5744 5745Units can be inside other units, and have units inside them, in a 5746tree-like fashion. There is no limit on the depth of the tree, but most 5747occupant-transport relationships have other limits. 5748 5749@deffn ActionType @code{enter} unit 5750This is the action to enter the given @var{unit}. 5751@end deffn 5752 5753@deffn UnitTypeProperty @code{acp-to-enter-unit} acp 5754This property is the number of acp a unit uses to do one entry action. 5755Defaults to @code{1}. 5756@end deffn 5757 5758@deffn TableUU @code{can-enter-independent} u1 u2 -> t/f 5759This table is true if a unit @var{u1} can enter an independent unit 5760@var{u2}. Defaults to @code{false}.@* 5761NOTE: The ability to enter an independent unit implies a form of trust 5762between the independent unit, @var{u2}, and its non-independent occupant, 5763@var{u1}. So, for example, @var{u1} can take supplies from @var{u2}. 5764@end deffn 5765 5766Entering and leaving incur mp costs as does movment, but units with a 5767speed of 0 may enter and leave transports. 5768 5769@deffn TableUU @code{mp-to-enter-unit} u1 u2 -> n 5770This table is the extra movement points required for @var{u1} to enter 5771the transport @var{u2}. 5772@end deffn 5773 5774@deffn TableUU @code{mp-to-leave-unit} u1 u2 -> n 5775Similar to entry cost. 5776@end deffn 5777 5778@deffn TableUU @code{ferry-on-entry} u1 u2 -> ferry-type 5779@end deffn 5780@deffn TableUU @code{ferry-on-departure} u1 u2 -> ferry-type 5781This table specifies how much intervening terrain the unit @var{u2} 5782entering or leaving transport @var{u1} will have to cross on its own 5783(and thus incur the terrain's mp costs and limitations). Defaults to 5784@code{over-border}. 5785@end deffn 5786 5787@deffn GlobalConstant @code{over-nothing} 5788This constant indicates no ferrying, occupant must pay all costs to go 5789to destination cell. 5790@end deffn 5791 5792@deffn GlobalConstant @code{over-own} 5793This constant indicates that the transport ferries over terrain of its 5794own cell. 5795@end deffn 5796 5797@deffn GlobalConstant @code{over-border} 5798This constant indicates that the transport ferries over any border 5799terrain also. 5800@end deffn 5801 5802@deffn GlobalConstant @code{over-all} 5803This constant indicates that the transport ferries to destination cell, 5804effectively putting occupant on middle of cell, on connection terrain if 5805necessary. 5806@end deffn 5807 5808@node Develop Action 5809 5810@subsection Develop Action 5811 5812Development is an action performed by a unit with the sole effect of 5813increasing its side's tech level. Development cannot be performed by 5814independent units. 5815 5816@deffn ActionType @code{develop} u 5817This is the action of developing the unit type @var{u}. If the action 5818is valid, then the tech level of the side will increase. Unit types 5819with any tech crossover will also have their tech levels adjusted. 5820@end deffn 5821 5822@deffn UnitTypeProperty @code{acp-to-develop} acp 5823This property is the number of action points used up by one develop 5824action. Defaults to @code{0}, which disallows development. 5825@end deffn 5826 5827@deffn TableUU @code{tech-per-develop} u1 u2 -> .01n 5828This table is the gain in tech level resulting from a develop action, 5829expressed as 1/100 of a level. This value is stochastic. 5830@end deffn 5831 5832@deffn UnitTypeProperty @code{tech-per-turn-max} tl 5833This property is a ceiling on the total gain of tech level possible in 5834one turn for each side and this unit type. Defaults to @code{9999}. 5835@end deffn 5836 5837@deffn TableUM @code{material-to-develop} u m -> n 5838This table is the amount of each material a unit must have in order to 5839do any development. 5840@end deffn 5841 5842 5843@node Toolup Action 5844 5845@subsection Toolup Action 5846 5847There are several stages in the construction of a unit: tooling up, 5848creation, and completion. Tooling up is where the building unit 5849prepares to build, creation is the step where the new unit comes into 5850existence, and completion is where the new unit is brought up to being 5851operational. 5852 5853For the player, this is mostly automatic; if tooling must be done first, 5854a user command to build will generate the appropriate actions. 5855 5856Once the technology has been achieved, a unit that intends to construct 5857other units may need to tool up. This is expressed as @dfn{tool points} 5858or @dfn{tp}. Tool points start at zero, can be increased by tooling 5859actions, and may gradually decline (representing wear and tear on the 5860equipment). 5861 5862@deffn ActionType @code{toolup} u 5863This is the action of tooling up to build a unit of type @code{u}. The 5864result is an increase in the tp for the acting unit. 5865@end deffn 5866 5867@deffn TableUU @code{can-toolup-for} u1 u2 -> t/f 5868If true, then an unit of type @var{u1} can toolup to construct an unit 5869of type @var{u2}. Defaults to @code{false}. 5870@end deffn 5871 5872@deffn UnitTypeProperty @code{acp-to-toolup} acp 5873This property gives the number of acp needed to do a toolup action. 5874@end deffn 5875 5876@deffn TableUM @code{material-to-toolup} u1 m -> n 5877The amount of a material type @var{m} required to be on hand, but not 5878necessarily consumed, by an unit of type @var{u1} tooling up for any 5879construction task. 5880@end deffn 5881 5882@deffn TableUM @code{consumption-per-tooledup} u2 m -> n 5883The amount of a material type @var{m} that is consumed by one toolup action 5884by the unit doing the tooling up, but based on, @var{u2}, 5885the type of unit being tooled up for. 5886@end deffn 5887 5888@deffn TableUM @code{consumption-per-tooledup} u1 m -> n 5889The amount of a material type @var{m} that is consumed by one toolup action 5890by the unit doing the tooling up, based on its type, @var{u1}. 5891@end deffn 5892 5893@deffn TableUM @code{consumption-per-tp} u1 m -> n 5894The amount of a material type @var{m} that is consumed by @code{1} TP worth 5895of tooling by the unit doing the tooling up, based on its type, @var{u1}. 5896@end deffn 5897 5898@deffn TableUU @code{tp-per-toolup} u1 u2 -> tp 5899This table is the number of tp gained by one tooling action. 5900@end deffn 5901 5902@deffn TableUU @code{tp-to-build} u1 u2 -> tp 5903This table is the number of toolup points needed before a unit of type 5904@var{u1} can create or build a unit of type @var{u2}. 5905@end deffn 5906 5907@deffn TableUU @code{tp-max} u1 u2 -> tp 5908This table is the maximum possible tooling. 5909@end deffn 5910 5911@deffn TableUU @code{tp-attrition} u1 u2 -> tp 5912This table is the number of .01 tool points automatically lost at the 5913end of each turn. 5914@end deffn 5915 5916@deffn TableUU @code{tp-crossover} u1 u2 -> n% 5917This table is the number of tool points for @var{u2} that is guaranteed 5918to exist, expressed as a percentage of the tool points for @var{u1}. 5919 5920For instance, if @code{tp-crossover} is 80, and a unit's tool points for 5921@var{u1} is 10 out of a max of 20, and the max for @var{u2} is also 20, 5922then the unit will have tool points for @var{u2} at least 8. 5923@end deffn 5924 5925@node Unit Creation Actions 5926 5927@subsection Unit Creation Actions 5928 5929When a constructing unit is tooled up, the create action creates a unit 5930immediately and puts it in its designated location, whether inside the 5931unit doing the building or somewhere nearby. This new unit, however, is 5932incomplete, representing the keel of the ship or the surveyor's 5933lines for an airstrip. Incomplete units are thus basically skeletons, 5934with some unit characteristics, but unable to move or act in any way. 5935They also cannot have any occupants, unless the occupants are of a type 5936that can complete the unit. Those occupants do not derive any protection 5937or other advantages from occupying the incomplete unit, and they are not 5938affected by the @code{occupant-can-build} limitation. 5939 5940@deffn ActionType @code{create-in} u unit 5941This action creates a new unit of type @var{u} occupying the given unit 5942@var{unit}. The unit @var{unit} must have room for the new unit. 5943@end deffn 5944 5945@deffn ActionType @code{create-at} u x y z 5946This action creates a new unit of type @var{u} in the open at 5947@var{x},@var{y},@var{z}. The cell must have room for this new unit. 5948@end deffn 5949 5950@deffn TableUU @code{can-create} u1 u2 -> t/f 5951If an unit of type @var{u1} can create an unit of type @var{u2}, 5952then this it true. Defaults to @code{false}. 5953@end deffn 5954 5955@deffn TableUU @code{create-as-build} u1 u2 -> t/f 5956If you intend for creation to cost and construct at the same rate as 5957building, then set this to true, and look at the @code{build} action 5958documentation. Defaults to @code{false}. 5959@end deffn 5960 5961@deffn TableUU @code{acp-to-create} u1 u2 -> acp 5962This table is the acp used by a unit of type @var{u1} to create a a unit 5963of type @var{u2}. 5964@end deffn 5965 5966@deffn TableUU @code{create-range} u1 u2 -> dist 5967This table is the maximum distance at which a unit of type @var{u1} can 5968create a unit of type @var{u2}. 5969@end deffn 5970 5971@deffn TableUU @code{cp-on-creation} u1 u2 -> cp 5972This table is the completeness of a unit of type @var{u2} when created 5973by a unit of type @var{u1}. Defaults to @code{1}. 5974@end deffn 5975 5976@deffn TableUM @code{material-to-create} u1 m -> n 5977This table is the total amount of a material type @var{m} required by 5978a unit of type @var{u1} to create anything. This material is not 5979consumed. 5980@end deffn 5981 5982@deffn TableUM @code{consumption-on-creation} u2 m -> n 5983This table is the amount of a material type @var{m} consumed to create a 5984unit of type @var{u2}. 5985@end deffn 5986 5987@deffn TableUM @code{consumption-per-create} u1 m -> n 5988This is the amount of a material type @var{m} consumed by an unit of type 5989@var{u1} while creating any other unit. 5990This may be negative, in which case, the creator gains @var{m}. 5991@end deffn 5992 5993@deffn TableUM @code{takes-from-treasury} u m -> t/f 5994This table is @code{true} if a constructing unit of type @var{u} can take 5995material @var{m} if its own supply is insufficient to meet the 5996@code{consumption-on-creation} or @code{consumption-per-build} (see 5997below) requirements. It should be noted that, unless the storage 5998capacity for the material is @code{0}, then the amount taken from the 5999treasury is only sufficient to close the deficit between the amount of 6000@var{m} an unit of type @var{u} has on hand and the amount of @var{m} that 6001@var{u} can store. If @var{u} has a @code{0} storage capacity for @var{m}, 6002then an unlimited amount of @var{m} can be used from the treasury. 6003@end deffn 6004 6005@deffn TableUM @code{treasury-gain-per-create} u m -> n 6006This is the amount of @var{m} gained when @var{u} is created. This material 6007is added to the treasury of the side that created @var{u}. This is not yet 6008implemented. 6009@end deffn 6010 6011@deffn TableUM @code{treasury-loss-per-create} u m -> n 6012This is the amount of @var{m} lost when @var{u} is created. This material 6013is taken from the treasury of the side that created @var{u}. This is not yet 6014implemented. 6015@end deffn 6016 6017@deffn TableUM @code{supply-on-creation} u m -> n 6018This table is the amount of supply of each material type @var{m} to give 6019a newly created unit of type @var{u}. This supply is newly generated, 6020does not come from anywhere else. (Note that players could cheat by 6021creating units, taking their supply, and never completing them.) 6022@end deffn 6023 6024@deffn TableUU @code{morale-on-creation} u1 u2 -> n 6025This table is the ratio of morale of a unit of type @var{u2} to the 6026morale of its creator @var{u1}, with 100 meaning that the new unit has 6027the same morale as its creator. Defaults to @code{100}. 6028@end deffn 6029 6030@deffn TableUU @code{opinions-on-creation} u1 u2 -> n 6031This table is the ratio of the opinions of a unit of type @var{u2} to 6032the opinions of its creator @var{u1}, with 100 meaning that the new unit 6033has the same opinions as its creator. Defaults to @code{100}. 6034@end deffn 6035 6036@node Unit Completion Action 6037 6038@subsection Unit Completion Action 6039 6040Once an incomplete unit has been created, other units can help to 6041complete it. 6042 6043@deffn ActionType @code{build} unit 6044This action adds to the completeness of @var{unit}. If the unit becomes 6045complete, it will be given its initial supply, acp, name, etc. 6046@end deffn 6047 6048@deffn TableUU @code{can-build} u1 u2 -> t/f 6049If an unit of type @var{u1} can build upon an unit of type @var{u2}, 6050then this it true. Defaults to @code{false}. 6051@end deffn 6052 6053@deffn TableUU @code{acp-to-build} u1 u2 -> acp 6054This table is the acp used up by one build action by a unit of type 6055@var{u1} when buiding a unit of type @var{u2}. 6056@end deffn 6057 6058@deffn TableUU @code{cp-per-build} u1 u2 -> cp 6059This table is the amount of completeness of a unit of type @var{u2} 6060added by each completion action performed by a unit of type @var{u1}. 6061If @code{0}, then @var{u1} cannot contribute to completing @var{u2}. 6062Defaults to @code{1}. 6063@end deffn 6064 6065@deffn TableUM @code{material-to-build} u1 m -> n 6066This table is the amount of any material type @var{m} that @var{u1} 6067must have in order to build anything at all. This material is not 6068consumed. 6069@end deffn 6070 6071@deffn TableUM @code{consumption-per-build} u1 m -> n 6072This is the amount of material type @var{m} that is consumed by the 6073building unit type @var{u1} while building any unit type. 6074This may be negative, in which case, @var{m} will be gained by the builder. 6075@end deffn 6076 6077@deffn TableUM @code{consumption-per-built} u2 m -> n 6078This table is the amount of each material type @var{m} consumed by 6079the builder performing a single build action on a unit of type @var{u2}. 6080This may be negative, in which case, @var{m} will be gained by the builder. 6081This is compatible with the @code{unit-consumption-per-cp} table. 6082@end deffn 6083 6084@deffn TableUM @code{unit-consumption-per-cp} u2 m -> n 6085This table is the amount of each material type @var{m} consumed by 6086the builder adding 1 CP to a unit of type @var{u2}. 6087This may be negative, in which case, @var{m} will be gained by the builder. 6088This is compatible with the @code{consumption-per-built} table. 6089@end deffn 6090 6091@deffn TableUU @code{build-range} u1 u2 -> dist 6092This table is the maximum distance allowed between a unit of type 6093@var{u1} and the incomplete unit of type @var{u2} it is working on. 6094Defaults to @code{0}, which requires the two units to be in the same 6095cell. 6096@end deffn 6097 6098At a given point, incomplete units can make progress towards completion 6099on their own. This is automatic because incomplete units are unable to 6100act, and occurs at a constant specified rate. Automatic completion 6101always occurs, even if other units are doing build actions at the same 6102time. The incomplete unit must have any necessary supplies. 6103 6104@deffn UnitTypeProperty @code{cp-to-self-build} cp 6105This property is the minimum completeness of the unit necessary before 6106it can work on itself. 6107@end deffn 6108 6109@deffn UnitTypeProperty @code{cp-per-self-build} cp 6110This property is the completeness added each turn when a unit works on 6111itself. 6112@end deffn 6113 6114@deffn TableUM @code{supply-on-completion} u m -> n 6115This table is the minimum amount of supply of each material type @var{m} 6116guaranteed to a newly completed unit of type @var{u}. If not already 6117available to the unit, it will be newly generated. 6118@end deffn 6119 6120@deffn UnitTypeProperty @code{cp-attrition} .01n% 6121This property is the chance that an incomplete unit will lose cp. If 6122the unit loses all of its cp, it vanishes. 6123@end deffn 6124 6125Cancelled build tasks can result in the disbanding of the incomplete 6126unit and recovery of the cp and materials in the unfinished unit. 6127 6128@deffn GlobalVariable @code{disband-unfinished-units} t/f 6129This variable is true if incomplete units not being worked on are 6130automatically disbanded. 6131@end deffn 6132 6133@deffn GlobalVariable @code{salvage-unfinished-cps} t/f 6134This is true if the disbanded incomplete unit returns its completeness 6135points. 6136@end deffn 6137 6138@deffn UnitProperty @code{cpstash} n 6139This property records unused completeness points. 6140@end deffn 6141 6142@deffn TableUU @code{builder-can-reuse-cp} u1 u2 -> t/f 6143This is true if a builder of type @var{u1} can use its cpstash to add to 6144the completeness of a unit of type @var{u2}. 6145@end deffn 6146 6147@deffn GlobalVariable @code{salvage-unfinished-materials} t/f 6148This is true if the disbanded incomplete unit returns the materials used 6149while building it. 6150@end deffn 6151 6152A creator which creates complete units or a builder which completes an 6153incomplete unit may be absorbed by the completed unit. This kind of 6154behavior is often useful for colonizer games, when one does not wish for 6155the colonizer to continue to be around after it has colonized. 6156 6157@deffn TableUU @code{constructor-absorbed-by} u1 u2 -> t/f 6158If true, then @code{hp-per-garrison} HP are taken out of the constructing 6159unit when it completes an unit. Note that this is not a guarantee that 6160the constructor will vanish; its HP must go to 0 for that to happen. 6161Defaults to @code{false}. 6162@end deffn 6163 6164An unit may automatically be given occupants upon completion. 6165 6166@deffn TableUU @code{complete-occs-on-completion} u1 u2 -> n 6167The number of complete occupants of type @var{u2} placed inside an 6168unit of type @var{u1} upon its completion. 6169@end deffn 6170 6171@deffn TableUU @code{incomplete-occs-on-completion} u1 u2 -> n 6172The number of incomplete occupants of type @var{u2} placed inside an 6173unit of type @var{u1} upon its completion. 6174@end deffn 6175 6176@node Repair Action 6177 6178@subsection Repair Action 6179 6180Units can restore their own and each other's hp by doing repairs. 6181Repair requires a repair action. 6182 6183@deffn ActionType @code{repair} unit 6184This is the action of repairing the given @var{unit}. 6185@end deffn 6186 6187@deffn TableUU @code{can-repair} u1 u2 -> t/f 6188True, if an unit of type @var{u1} can repair an unit of type @var{u2}. 6189Defaults to @code{false}. 6190@end deffn 6191 6192@deffn TableUU @code{acp-to-repair} u1 u2 -> acp 6193The number of action points used up by a unit of type @var{u1} 6194doing one repair action on a unit of type @var{u2}. 6195@end deffn 6196 6197@deffn TableUU @code{hp-per-repair} u1 u2 -> .01hp 6198This table is the hundredths of a hp that a single repair action 6199by a unit of type @var{u1} restores to a unit of type @var{u2}. 6200The fraction of this over 100 is added to hp directly, 6201while the < 100 fraction is added probabilistically. 6202(For example, a value of @code{160}, or @code{1.60}, means that 1 hp 6203will be added for each action, and there is a 60% chance for an additional 62041 hp to be added as well.) 6205@end deffn 6206 6207Materials may be needed and/or consumed during repair. 6208 6209@deffn TableUM @code{material-to-repair} u1 m -> n 6210This table is the amount of each material type @var{m} needed 6211for one repair action. 6212@end deffn 6213 6214@deffn TableUM @code{consumption-per-repair} u1 m -> n 6215This table is the amount of each material type @var{m} 6216used up by a repair action performed by the repairer unit of type @var{u1}. 6217@end deffn 6218 6219@deffn TableUM @code{consumption-per-repaired} u2 m -> n 6220This table is the amount of each material type @var{m} 6221used up by a repair action performed on the repairee unit of type @var{u2}. 6222@end deffn 6223 6224The following are not really part of the repair action definition, since 6225they occur automatically, but they share many of the tables above. 6226 6227@deffn TableUU @code{auto-repair} u1 u2 -> .01hp 6228This table is the amount of repair (in 1/100 hp) that @var{u1} will do 6229on any unit of type @var{u2} within range (@code{auto-repair-range}). 6230As with @code{hp-per-repair}, 6231the < 1.00 part is average, and > 1.00 is guaranteed. 6232Material requirements and usage are as for repair actions. 6233Defaults to @code{0}, which disallows auto-repair. 6234@end deffn 6235 6236@deffn TableUU @code{auto-repair-range} u1 u2 -> dist 6237This table is the distance out to which @var{u1} will auto-repair 6238any damaged @var{u2}. A value of @code{0} requires the two units 6239to be in the same cell, while a value of @code{-1} means that 6240@var{u2} must be either an occupant or transport of @var{u1}. 6241@end deffn 6242 6243@deffn UnitTypeProperty @code{hp-recovery} .01hp 6244This property is the number of 1/100 hp recovered per turn. Recovery 6245happens automatically at the end of each turn. The amount @i{n} / 100 6246is recovered automatically each turn, while @i{n} mod 100 is the percent 6247chance of recovering an additional 1 hit point. 6248@end deffn 6249 6250@deffn UnitTypeProperty @code{hp-to-recover} hp 6251This property is the minimum number of hp that the unit must have for hp 6252recovery to work. 6253@end deffn 6254 6255@node Material Production Action 6256 6257@subsection Material Production Action 6258 6259Units can produce materials by explicit action. 6260 6261@deffn ActionType @code{produce} m 6262This action results in a quantity of material @var{m} 6263coming into existence. 6264@end deffn 6265 6266@deffn TableUM @code{acp-to-produce} u m -> acp 6267This table is the acp used up by one @code{produce} action. 6268@end deffn 6269 6270@deffn TableUM @code{material-per-production} u m -> n 6271This table is the amount of material produced by @var{u} 6272when acting to produce type @var{m}. 6273@end deffn 6274 6275@deffn TableUM @code{material-to-produce} u m -> n 6276This table is the amount of each material a unit must have 6277in order to produce any material. This material is not 6278consumed by the production action. 6279@end deffn 6280 6281@node Material Extraction Action 6282 6283@subsection Material Extraction Action 6284 6285Units can extract materials from the terrain or from nearby units. 6286 6287@deffn ActionType @code{extract} x y m n 6288This action results in the transfer of a quantity @var{n} of material 6289@var{m} from the cell at @var{x},@var{y}. 6290@end deffn 6291 6292@deffn TableUM @code{acp-to-extract} u m -> acp 6293This table is the acp used up by one action to extract material 6294of type @var{m}. 6295@end deffn 6296 6297@deffn TableUM @code{material-to-extract} u m -> acp 6298This table is the material required to do any extraction actions. 6299@end deffn 6300 6301@node Material Transfer Action 6302 6303@subsection Material Transfer Action 6304 6305Although most movement of materials between units happens automatically 6306(see backdrop economy description), players can also do it explicitly. 6307Players can both take materials from other units, and give a unit's 6308materials to others. 6309 6310@deffn ActionType @code{transfer} unit m n 6311This is the action of transferring supply to the given unit @var{unit}. 6312The desired amount is @var{n}; if @var{m} is a valid material type, then 6313only that type will be transferred, otherwise the action will transfer 6314all types of materials possible. The actual transfer amounts may be 6315less than @var{n}. 6316@end deffn 6317 6318@deffn TableUM @code{acp-to-unload} u1 m -> acp 6319@end deffn 6320@deffn TableUM @code{acp-to-load} u1 m -> acp 6321These tables are the number of action points used up by one material 6322transfer action from @var{u1} to @var{u2}. The amount is independent of 6323the material type being transferred. If either value is @code{0}, then 6324the material cannot be transferred. 6325@end deffn 6326 6327@deffn TableUM @code{unload-max} u1 m -> n 6328@end deffn 6329@deffn TableUM @code{load-max} u2 m -> n 6330These two tables determine how much of material @var{m} can be 6331transferred out of a unit of type @var{u1} and into one of type @var{u2} 6332in one transfer action. The actual quantity transferred by the action 6333is the minimum of these two values. A value of @code{0} disallows 6334manual transfer. Both default to @code{-1}, which allows any amount to 6335be transferred. 6336@end deffn 6337 6338@node Side Change Action 6339 6340@subsection Side Change Action 6341 6342@deffn ActionType @code{change-side} side 6343This is the action of changing the unit's side to @var{side}. The 6344@var{side} can be any allowable side, and the unit may be any unit 6345controlled by the actor's side. 6346@end deffn 6347 6348@deffn UnitTypeProperty @code{acp-to-change-side} acp 6349If the value of this property is greater than 0, then this type of unit 6350can be ordered to change to another given side. If the unit is not a 6351type that can act, then the side change happens immediately, instead of 6352as an action, and no acp cost is incurred. The type must also be 6353allowed to be on the new side. 6354@end deffn 6355 6356@node Disband Action 6357 6358@subsection Disband Action 6359 6360Disbanding is the voluntary and controlled destruction of a unit, 6361performed by the unit itself or another unit. A disbanded unit always 6362vanishes, rather than changing to its @code{wrecked-type}. 6363 6364@deffn ActionType @code{disband} unit 6365This is the action of removing hp from @var{unit}. The unit will vanish 6366if all its hit points are gone. 6367@end deffn 6368 6369@deffn UnitTypeProperty @code{acp-to-disband} acp 6370If the value of this property is greater than 0, then this is the acp 6371that will be used up to do one disband action. If the unit is not a 6372type that can act, then the disband happens immediately, instead of as 6373an action, and no acp cost is incurred. 6374@end deffn 6375 6376@deffn UnitTypeProperty @code{hp-per-disband} hp 6377This table is the number of hp lost in a disband action. Defaults to 6378@code{0}, which disallows disbanding. 6379@end deffn 6380 6381A disbanded unit can be scavenged for materials. 6382 6383@deffn TableUM @code{supply-per-disband} u m -> n% 6384This table is the percentage of the unit's supply that is recovered from 6385a single disband action. If the value is zero, then the unit's supply 6386will not be recovered by the disbanding process, and be lost 6387permanently. If any supply remains when the unit's hp is 0, then that 6388supply will be lost also. Defaults to @code{100}, which means that the 6389entire supply will be recovered on the first disband action. 6390@end deffn 6391 6392Note that if an essential supply is 100% recovered before the unit is 6393completely disbanded, then it may die from starvation first. A 6394partly-disbanded unit may still acquire supply from nearby units, via 6395the backdrop economy. 6396 6397@deffn TableUM @code{recycleable-material} u m -> n 6398This table is the quantity of each type of material that becomes 6399available when a unit is completely disbanded. The materials go to 6400transports, occupants, and nearby units, in that order. Any materials 6401exceeding capacities of these units will be discarded. These materials 6402become available only when the unit vanishes. 6403@end deffn 6404 6405@node Part Transfer Action 6406 6407@subsection Part Transfer Action 6408 6409Units of variable size can transfer parts of themselves to other 6410units, or create a new unit. 6411 6412@deffn ActionType @code{transfer-part} n unit 6413This action moves @var{n} parts of the actee to @var{unit}, 6414or creates a new unit if @var{unit} is omitted. 6415If @var{n} is negative, this takes from @var{unit} instead. 6416If the action takes all the parts of any involved unit, 6417then it vanishes. 6418@end deffn 6419 6420@deffn TableUU @code{can-transfer-parts-to} u1 u2 t/f 6421If @var{u1} can transfer parts to @var{u2}, then set this to @code{true}. 6422@end deffn 6423 6424@deffn UnitTypeProperty @code{acp-to-transfer-part} acp 6425This property is the number of acp used up by the unit 6426when doing a part transfer action. 6427@end deffn 6428 6429@node Type Change Action 6430 6431@subsection Type Change Action 6432 6433Units may change their type. This can be set up to happen automatically, or only with manual intervention from the player. 6434 6435@deffn ActionType @code{change-type} u 6436This action changes the type of the actee unit to the type @var{u}. 6437Upon changing, the relationships of the unit with the world and 6438with other units will be recalculated; occupants that can no longer 6439stay in the unit will be ejected or disappear. The unit itself 6440may vanish or wreck, if it is in the open on a terrain type that will 6441cause units of the new type to vanish or wreck. 6442@end deffn 6443 6444@deffn TableUU @code{can-change-type-to} u1 u2 -> t/f 6445True, if a unit of type @var{u1} is allowed to be change its type to 6446@var{u2}. If not allowed, then false. The default is @code{false}. 6447Not relevant for automatic change-type actions. 6448@end deffn 6449 6450@deffn UnitTypeProperty @code{auto-upgrade-to} u 6451Automatically upgrade a unit to unit type @var{u} at the beginning of 6452a turn if the change-type criteria are met for this upgrade. Defaults 6453to @code{nonutype}. 6454@end deffn 6455 6456@deffn TableUU @code{acp-to-change-type} u1 u2 -> acp 6457This table is the number of acp needed to change a unit of 6458type @var{u1} into a unit of type @var{u2}. 6459If the value is 0, then the change is never possible. 6460@end deffn 6461 6462@deffn TableUU @code{occupants-to-change-type} u1 u2 -> n 6463The number of occupants of unit type @var{u2} required to change a 6464unit of type @var{u1} into another unit type. 6465@end deffn 6466 6467@deffn TableUA @code{advance-to-change-type} u a -> t/f 6468Indicate whether an advance type @var{a} is needed by a unit of type 6469@var{u} to change type. The default is @code{false}. 6470@end deffn 6471 6472@deffn TableUM @code{material-to-change-type} u m -> n 6473This is the amount of each material type @var{m} required for an 6474unit of type @var{u} to change type. 6475@end deffn 6476 6477@deffn TableUU @code{cxp-to-change-type} u1 u2 -> n 6478Minimum combat experience for a unit of type @var{u1} to change to 6479unit type @var{u2}. 6480@end deffn 6481 6482@deffn TableUU @code{size-to-change-type} u1 u2 -> n 6483Minimum size for a unit of type @var{u1} to change to unit type 6484@var{u2}. 6485@end deffn 6486 6487@deffn TableUU @code{turn-to-change-type} u1 u2 -> n 6488Minimum turn for a unit of type @var{u1} to change to unit type 6489@var{u2}. 6490@end deffn 6491 6492@node Combat Actions 6493 6494@subsection Combat Actions 6495 6496@i{Xconq} combat is somewhat abstract; the attacking player decides what sort 6497of attack to mount and perhaps when to retreat, but all else happens 6498automatically. 6499 6500The attacker/defender distinction applies only to a single action. 6501 6502@deffn ActionType @code{attack} unit commit 6503This action is a direct attack on the given @var{unit}, at a commitment 6504level of @var{commit}. The @var{unit} must be known to the attacking 6505unit's side. 6506@end deffn 6507 6508@deffn ActionType @code{overrun} x y z commit 6509This action is a combined attack/capture/move action. The basic theory 6510of an overrun is that the actor will attack, capture, or co-occupy the 6511cell at @var{x},@var{y}, elevation @code{z}, with a commitment of 6512@var{commit}. The exact effects depend on the types and sides of units 6513in the destination. 6514@end deffn 6515 6516[The commitment levels are currently ignored.] 6517 6518@deffn TableUU @code{acp-to-attack} u1 u2 -> acp 6519This table is the number of action points used up by a unit @var{u1} 6520when attacking a unit of type @var{u2}. If the value is 0, attack is 6521not allowed. Defaults to @code{1}. 6522@end deffn 6523 6524@deffn TableUU @code{acp-to-defend} u1 u2 -> acp 6525This table is the number of action points used up by a unit @var{u1} 6526when defending against an attack by a unit of type @var{u2}. If the 6527value is 0, attack is not allowed. Defaults to @code{1}. 6528@end deffn 6529 6530@deffn TableUU @code{attack-range-min} u1 u2 -> dist 6531This table is the minimum distance at which a unit can attack another. 6532A value of 0 means that units in the same cell can fight. 6533@end deffn 6534 6535@deffn TableUU @code{attack-range} u1 u2 -> dist 6536This table is the maximum distance at which a unit can attack another. 6537A value of 1 means that units in adjacent cells may fight, while a value 6538of 0 means that only units in the same cell may fight. Defaults to 6539@code{1}. 6540@end deffn 6541 6542@deffn GlobalVariable @code{combat-model} n 6543This variable specifies the algorithm used for combat resolution. 6544 6545A value of 0 specifies single attack/counterattack with odds determined 6546by the @code{hit-chance} table. 6547 6548A value of 1 specifies multi-round combat with odds computed from attack 6549and defend strength, combat continuing until a participant is destroyed. 6550Combat model one is not fully described in this document. For further 6551details beyond those here, look at the comments in table.def in the 6552xconq source code, at variables such as occupant-affects-attack, 6553occupant-affects-defense, transport-affects-attack, 6554transport-affects-defense, terrain-affects-attack, 6555terrain-affects-defense, neighbour-affects-attack, and 6556neighbour-affects-defense. Plus of course the source code where the 6557variables are consulted (for example model_1_combat in kernel/combat.c). 6558@end deffn 6559 6560One round of combat consists of an attack, a reaction, and a calculation 6561of effects. 6562 6563The defender's reaction is completely automatic, and occurs as part of 6564the combat round. The defender's side does not get a chance to decide 6565what to do until the next round, although doctrine may constrain the set 6566of reactions. 6567 6568@deffn TableUU @code{surrender-chance-per-attack} u1 u2 -> n% 6569This table is the chance that @var{u2} will surrender to @var{u1} 6570immediately upon being attacked. 6571@end deffn 6572 6573@deffn TableUU @code{withdraw-chance-per-attack} u1 u2 -> n% 6574This table is the chance that @var{u2} will retreat from @var{u1} 6575immediately upon being attacked. 6576@end deffn 6577 6578@deffn TableUU @code{acp-for-retreat} u1 u2 -> acp 6579This table is the extra acp that @var{u2} can get in order to make a 6580withdrawal possible. 6581@end deffn 6582 6583@deffn TableUU @code{counterattack} u1 u2 -> n 6584This table is the strength of a defender's reaction to an attack. If 0, 6585the defender does not counterattack; if 100, the defender counterattacks 6586at the same level as if it attacked normally. Defaults to @code{100}. 6587@end deffn 6588 6589In an overrun action, if all the defending units are destroyed, the 6590attacker has sufficient acp and mp, and the destination is safe to 6591enter, then the attacker can move into the defenders' cell. 6592 6593Firing is a kind of attack that can take place at a distance, involves 6594no commitment or counterattack, and for which the type of ammo may be 6595selected. 6596 6597@deffn ActionType @code{fire-at} unit m 6598This is the action of firing at a given @var{unit}. If @var{m} is a 6599valid material type, then that type will be used as ammo, otherwise all 6600available types will be used together. 6601@end deffn 6602 6603@deffn ActionType @code{fire-into} x y z m 6604This is the action of firing into the cell at @var{x},@var{y}. If @var{z} is 6605a valid altitude, then the fire will be concentrated on units at that 6606elevation. If @var{m} is a valid material type, then that type will be 6607used as ammo, otherwise all available types will be used together. 6608@end deffn 6609 6610@deffn UnitTypeProperty @code{acp-to-fire} acp 6611If this property is greater than 0, this type may attack by firing. 6612@end deffn 6613 6614@deffn TableUU @code{acp-to-be-fired-on} u1 u2 -> acp 6615This table is the acp lost when a unit is being fired upon. Defaults to 6616@code{1}. 6617@end deffn 6618 6619@deffn UnitTypeProperty @code{range} dist 6620This property is the maximum distance in cells to which a unit can fire. 6621Defaults to @code{1}. 6622@end deffn 6623 6624@deffn UnitTypeProperty @code{range-min} dist 6625This property is the minimum distance in cells to which a unit can fire. 6626@end deffn 6627 6628@deffn UnitTypeProperty @code{fire-angle-max} n% 6629This property is the highest angle at which a unit may fire, expressed 6630as a percentage of 45 degrees. The default of @code{0} means that the 6631unit's fire has a flat trajectory and that the target must be on an 6632unobstructed straight line from the firing unit. For values greater 6633than 0, this angle is used to calculate whether the parabolic trajectory 6634clears all intervening terrain. 6635@end deffn 6636 6637Units can be on @dfn{overwatch}. Overwatch is a state where an unit will 6638automatically fire at other units it sees moving. 6639 6640@deffn TableUU @code{zoo-range} u1 u2 n 6641The maximum range for an unit of type @var{u1} to extend a zone-of-overwatch 6642(ZOO) for units of type @var{u2}. If the fire @code{range} for @var{u1} is 6643less than @var{n}, then that will be used instead. Defaults to @code{-1}. 6644@end deffn 6645 6646@deffn TableUU @code{zoo-range-min} u1 u2 n 6647The minimum range for an unit of type @var{u1} to extend a ZOO for units of 6648type @var{u2}. If the fire @code{range-min} for @var{u1} is greater than 6649@var{n}, then that will be used instead. Defaults to @code{-1}. 6650@end deffn 6651 6652@deffn TableUU @code{acp-for-overwatch} u1 u2 n 6653The amount of additional ACP that an unit of type @var{u1} receives in order 6654to perform an overwatch firing against units of type @var{u2}. 6655@end deffn 6656 6657@deffn TableUT @code{weapon-height} u t -> elev 6658This property is the effective height of a unit's weapons when in the 6659given terrain. 6660@end deffn 6661 6662Both attack and fire combat calculate hits and damage in a similar way, 6663although they may use different tables. 6664 6665@deffn TableUU @code{hit-chance} u1 u2 -> n% 6666This table is the basic chance that a unit of type @var{u1} will 6667actually hit a unit of type @var{u2}. If the hit chance is @code{0}, 6668then the unit may never attack a unit of that type. 6669@end deffn 6670 6671@deffn TableUU @code{fire-hit-chance} u1 u2 -> n% 6672This table is the basic chance that fire from a unit of type @var{u1} 6673will actually hit a unit of type @var{u2}. If the hit chance is 6674@code{0}, then the unit may never fire at a unit of that type. If the 6675value is @code{-1}, then the value of this is the same as the value of 6676@code{hit-chance}. Defaults to @code{-1}. 6677@end deffn 6678 6679@deffn TableUT @code{attack-terrain-effect} u1 t -> n% 6680@end deffn 6681@deffn TableUT @code{defend-terrain-effect} u2 t -> n% 6682@end deffn 6683@deffn TableUT @code{fire-attack-terrain-effect} u1 t -> n% 6684@end deffn 6685@deffn TableUT @code{fire-defend-terrain-effect} u2 t -> n% 6686These tables specify the effect of attacker's and defender's respective 6687terrains on @code{hit-chance} or @code{fire-hit-chance}. These chances 6688are multiplied with the basic hit chance. Default to @code{100}. 6689@end deffn 6690 6691@deffn TableUU @code{hit-cxp-effect} u1 u2 -> n 6692This table is the effect of combat experience on hit chance. Its value 6693is interpolated according to actual experience (@var{n} is the effect 6694when @var{u1} is at its maximum possible experience), then multiplied 6695with the hit chance. Defaults to @code{100}. 6696@end deffn 6697 6698The effectiveness of fire may be less at long ranges. If the range to 6699the target is greater than @code{hit-falloff-range}, the chance of 6700hitting it will be reduced by the interpolation between the short-range 6701chance and that chance multiplied by the value of 6702@code{hit-at-max-range-effect}. For example, if a unit's range is 4, 6703its hit falloff range is 1, the basic hit chance is 60%, and the max 6704range effect is 50%, then its hit chance at range 2 is 50%, at range 3 6705is 40%, and at range 4 is 30%. 6706 6707@deffn UnitTypeProperty @code{hit-falloff-range} n 6708This table is the maximum range at which the effectiveness of combat is 6709@i{not} affected by distance. Defaults to @code{PROPHI}. 6710@end deffn 6711 6712@deffn TableUU @code{hit-at-max-range-effect} u1 u2 -> n% 6713This is the multiplier for the effectiveness of firing at the maximum 6714range possible. Defaults to @code{100}. 6715@end deffn 6716 6717@deffn TableUU @code{damage} u1 u2 -> hp 6718This table is the basic amount of damage caused by a successful attack. 6719The value is a dice spec. Defaults to @code{1}. 6720@end deffn 6721 6722@deffn TableUU @code{fire-damage} u1 u2 -> hp 6723This table is the basic amount of damage caused by a successful firing. 6724The value is a dice spec. If the value is @code{-1}, then it is the 6725same as @code{damage}. Defaults to @code{-1}. 6726@end deffn 6727 6728@deffn TableUU @code{tp-damage} u1 u2 -> tp 6729This table is the amount of damage to a unit's tooling caused by a 6730successful attack. The value is a dice spec. 6731@end deffn 6732 6733@c Damage done by combat is always prorated by commitment; the table values 6734@c are for attacks at full commitment. 6735 6736@deffn TableUU @code{damage-cxp-effect} u1 u2 -> n 6737This table is the effect of combat experience on damage. Its value is 6738interpolated according to actual experience (so that @var{n} is the 6739effect when @var{u1} is at its maximum experience), then multiplied with 6740both the dice size and the addend of the damage spec. Defaults to 6741@code{100}. 6742@end deffn 6743 6744@deffn TableUU @code{hp-min} u1 u2 -> hp 6745This table is the lowest hp possible for @var{u1} from attacks by 6746@var{u2}. Further attacks by @var{u2} are still valid, but can do no 6747further damage. 6748@end deffn 6749 6750You can set a unit to use a material as ammo. 6751 6752@deffn TableUM @code{consumption-per-attack} u1 m -> n 6753Specifies how much a material @var{m} will be used as ammunition 6754when a unit @var{u1} is attacking. 6755@end deffn 6756 6757@deffn TableUM @code{consumption-per-fire} u1 m -> n 6758Specifies how much a material @var{m} will be used as ammunition 6759when a unit @var{u1} is firing.@* 6760NOTE: Set this to @code{-1}, if you wish to use the 6761@code{consumption-per-attack} table for firing. 6762@end deffn 6763 6764@deffn TableUM @code{hit-by} u2 m -> n 6765The multiplier on the consumption of material @var{m} by a unit @var{u1} 6766when it is attacking or firing upon a unit @var{u2}.@* 6767NOTE: Normally, one would probably want to set this value to @code{1}, 6768if it is desired that the ammo type @var{m} be consumed to hit @var{u2}. 6769However, @var{u2} can be made "tougher" by setting this multiplier 6770higher, rather than by adjusting the @code{hit-chance} and 6771@code{fire-hit-chance} tables.@* 6772NOTE: To prevent an ammo @var{m} from being consumed when hitting a 6773unit @var{u2} (even if the attacker @var{u1} would normally consume this 6774in an attack or firing) then leave the appropriate @code{hit-by} table 6775entry at the default value @code{0}, or reset it to that. 6776@end deffn 6777 6778If a unit @var{u1} is firing upon a unit @var{u2}, then @var{u1} 6779will use the quantity of ammunition @var{m} specified in 6780@code{consumption-per-fire} multiplied by the corresponding entry in 6781@code{hit-by}, if the result is >= 0. Else, it will use the quantity of 6782@var{m} specified in @code{consumption-per-attack} multiplied by the 6783corresponding entry in @code{hit-by}. 6784 6785@deffn TableUM @code{material-to-attack} u m -> n 6786This table is a minimum of each material type @var{m} that a unit must 6787have to engage in direct attack or to defend against it. This minimum 6788is not necessarily used up in combat, it just needs to be present. 6789@end deffn 6790 6791@deffn TableUM @code{material-to-fire} u m -> n 6792This table is a minimum of each material type @var{m} that a unit must 6793have to fire. This minimum is not necessarily used up, it just needs to 6794be present. 6795@end deffn 6796 6797Transports can protect their occupants, and vice versa. 6798 6799@deffn TableUU @code{protection} u1 u2 -> n% 6800This table gives the effect of occupants of type @var{u1} on the chance 6801of another unit's attack hitting their transport @var{u2}, as well as 6802the effect of the transport @var{u1} on the chance that occupants of 6803type @var{u2} will be hit. 6804 6805For the transport, this is a multiplier, where 100 has no protection, 6806values less than 100 decrease hit chance, and values greater than 100 6807increase it. Each occupant will be taken into account when computing 6808transport's protection. 6809 6810If the transport is the unit being hit, then the value of this table 6811is the probability that an occupant of type @var{u2} will be hit. 6812 6813Defaults to @code{100}. 6814@end deffn 6815 6816A transport's destruction may leave occupants stranded on hex, will do 6817some sort of auto-escape or die if terrain is hostile. 6818 6819Units stacked together can protect each other. 6820 6821@deffn TableUU @code{stack-protection} u1 u2 -> n% 6822This table is the effect of units of type @var{u1} on attacks on units 6823of type @var{u2} that are in the same cell. The effect is similar to 6824that described for the @code{protection} table. Defaults to @code{100}. 6825@end deffn 6826 6827Units may also act to protect every other unit in a cell, whether 6828occupant, transport, or stack. 6829 6830@deffn TableUU @code{cellwide-protection-for} u1 u2 -> n% 6831This table is the effect of any unit of type @var{u1} in the same cell 6832on attacks against any unit of type @var{u2} in the cell. Defaults to 6833@code{100}. 6834@end deffn 6835 6836@deffn TableUU @code{cellwide-protection-against} u1 u2 -> n% 6837This table is the effect of any unit of type @var{u1} on any attack on 6838any unit in the cell by units of type @var{u2}, expressed as a 6839percentage multiplier. Defaults to @code{100}. 6840@end deffn 6841 6842Several other side-effects of combat may also be defined. 6843 6844Units can retreat if they are about to be damaged; the retreat attempt 6845is automatic, and will be in a valid direction that is away from the 6846attacker. The retreat attempt will fail if there is no direction that 6847the unit may move, or if has insufficient materials, acp, etc to do the 6848movement. If the attempt is successful, then the unit will not be 6849damaged; otherwise it must take the hit. 6850 6851@deffn TableUU @code{retreat-chance} u1 u2 -> n% 6852This table is the chance that @var{u2} will attempt to retreat if it is 6853hit by @var{u1}. 6854@end deffn 6855 6856Units may gain experience as a result of combat. 6857 6858@deffn TableUU @code{cxp-per-combat} u1 u2 -> cxp 6859This table is the number of combat experience points gained by @var{u1} 6860by surviving a combat round with @var{u2}. Both attackers and defenders 6861gain experience equally. 6862@end deffn 6863 6864@deffn TableUU @code{cxp-per-destroy} u1 u2 -> cxp 6865This table is the number of combat experience points gained by @var{u1} 6866destroying @var{u2}. This is in addition to any cxp gained due to combat. 6867@end deffn 6868 6869The sides of the victorious and defeated units may be modified as an 6870outcome of unit destruction. 6871 6872@deffn TableUM @code{treasury-gain-per-destroy} u m -> n 6873This is the amount of @var{m} gained when @var{u} is destroyed in combat. 6874This material is added to the treasury of the side that destroyed @var{u}. 6875@end deffn 6876 6877@deffn TableUM @code{treasury-loss-per-destroyed} u m -> n 6878This is the amount of @var{m} lost when @var{u} is destroyed in combat. 6879This material is taken from the treasury of the side of @var{u}. 6880@end deffn 6881 6882Unit morale may change as a result of combat, either positively or 6883negatively. 6884 6885@deffn TableUU @code{morale-hit} u1 u2 -> .01n 6886This table is the 100ths of morale gained as the result of a unit of 6887type @var{u1} successfully hitting a unit of type @var{u2}. The part of 6888the number > 100 is gained always, the part modulo 100 is the 6889probability of gaining 1. 6890@end deffn 6891 6892@deffn TableUU @code{morale-hit-by} u1 u2 -> .01n 6893This table is the 100ths of morale lost as the result of a unit of type 6894@var{u1} being hit by a unit of type @var{u2}. 6895@end deffn 6896 6897In combat model 1, the outcome is determined by relative attack 6898and defense strengths. 6899 6900@deffn UnitTypeProperty @code{attack} n 6901@end deffn 6902@deffn UnitTypeProperty @code{defend} n 6903These values represent the relative attack and defense strengths 6904of a unit type. 6905@end deffn 6906 6907@deffn UnitTypeProperty @code{encounter-result} list 6908This property specifies other possible outcomes of an attack. 6909The @var{list} is an optionally weighted list of the form 6910@example 6911@code{( [ @var{weight} ] @var{result} @dots{} )} 6912@end example 6913Each @var{result} has one of the following forms: 6914@example 6915@code{(unit @var{type} @var{message})} 6916@code{(unit (@var{type} @var{side}) @var{message})} 6917@code{(vanish nil @var{message})} 6918@end example 6919If the chosen @var{result} starts with @code{unit}, then the encountered 6920unit changes type to the given type, and if the @var{side} is specified 6921(as a side id), then it will change side also. 6922 6923If the chosen result starts with @code{vanish}, then the encountered 6924unit simply vanishes permanently. 6925 6926At present, this property is only used in model 1 combat, where its 6927results are checked before combat. Defaults to @code{()}. 6928@end deffn 6929 6930@deffn Symbol @code{vanish} 6931This keyword indicates that the encounter result is for the encountered 6932unit to vanish. 6933@end deffn 6934 6935@node Capture Action 6936 6937@subsection Capture Action 6938 6939A unit may attempt to capture another unit directly. 6940If successful, the captured unit's side changes to that of the capturing unit. 6941 6942@deffn ActionType @code{capture} unit 6943This is the action of capturing the given @var{unit}. 6944@end deffn 6945 6946@deffn TableUU @code{acp-to-capture} u1 u2 -> acp 6947This table is the number of acp used up by a @code{capture} action. 6948Defaults to @code{0}, which disallows capture. 6949@end deffn 6950 6951@deffn TableUU @code{bridge} u1 u2 -> t/f 6952This table is true if a unit of type @var{u1} can be captured by a unit 6953of type @var{u2} even if @var{u1} is on a type of terrain impassable to 6954the capturing unit. Defaults to @code{false}. 6955@end deffn 6956 6957@deffn UnitProperty @code{match-transport-side} t/f 6958Whenever an unit's transport changes side, automatically try to match 6959the unit's side to the transport's new side. 6960@end deffn 6961 6962@deffn TableUU @code{capture-chance} u1 u2 -> n% 6963This table is the basic chance for @var{u1} to capture @var{u2}. 6964@end deffn 6965 6966@deffn TableUU @code{independent-capture-chance} u1 u2 -> n% 6967This table is the basic chance for @var{u1} to capture an independent 6968unit of type @var{u2}. If the value is @code{-1}, then the chance of 6969capture is given by the @code{capture-chance}. Defaults to @code{-1}. 6970@end deffn 6971 6972Normally, the @code{protection}, @code{stack-protection}, 6973@code{cellwide-protection-for}, and @code{cellwide-protection-against} 6974tables affect the computed capture chance. However, the use of these 6975protection tables can be prohibited by setting the 6976@code{protection-resists-capture} global variable to @code{false}. 6977 6978@deffn GlobalVariable @code{protection-resists-capture} t/f 6979When set to false, this variable ensures that the various combat protection 6980tables are _not_ used when computing the success/failure of a capture 6981attempt. Defaults to @code{true} (to maintain legacy behavior of older 6982games). 6983@end deffn 6984 6985The following tables can affect capture, whether or not 6986@code{protection-resists-capture} is set: 6987 6988@deffn TableUU @code{occupant-allows-capture-by} u1 u2 -> n% 6989An occupant of type @var{u1} affects the capture chance of its transport 6990by @var{n}% when an unit of type @var{u2} is attempting to capture the 6991transport. Set to @code{0%} to disallow the transport's capture by 6992@var{u2} when @var{u1} is present. Defaults to @code{100%}. 6993@end deffn 6994 6995@deffn TableUU @code{stack-neighbor-allows-capture-by} u1 u2 -> n% 6996If an unit of type @var{u1} shares the same cell with another unit, then 6997it may affect the capture chance of the other unit when an unit of type 6998@var{u2} is attempting capture of the other unit. This table does not 6999apply to occupants of the other unit. Set to @code{0%} to disallow capture 7000of a neighbor by an unit of type @var{u2} when @var{u1} is present. 7001Defaults to @code{100%}. 7002@end deffn 7003 7004@deffn TableUU @code{any-neighbor-allows-capture-by} u1 u2 -> n% 7005If an unit of type @var{u1} shares the same cell with another unit, then 7006it may affect the capture chance of the other unit when an unit of type 7007@var{u2} is attempting capture of the other unit. This applies to any 7008other unit in the cell, including one that may be an occupant. Set to 7009@code{0%} to disallow capture of a neighbor by an unit of type @var{u2} 7010when @var{u1} is present. Defaults to @code{100%}. 7011@end deffn 7012 7013@deffn TableUU @code{occupant-allows-capture-of} u1 u2 -> n% 7014An occupant of type @var{u1} can prevent capture of its transport of 7015type @var{u2}. Set to @code{0%} to disallow capture of a transport of 7016type @var{u2} when an occupant @var{u1} is in it. Defaults to 7017@code{100%}. 7018@end deffn 7019 7020@deffn TableUU @code{stack-neighbor-allows-capture-of} u1 u2 -> n% 7021An unit of type @var{u1} sharing the same cell as an unit of type @var{u2} 7022may affect the capture outcome of the latter. This does not apply to 7023occupants. Set to @code{0%} to disallow capture of @var{u2} when @var{u1} 7024is in the same cell as it. Defaults to @code{100%}. 7025@end deffn 7026 7027@deffn TableUU @code{any-neighbor-allows-capture-of} u1 u2 -> n% 7028An unit of type @var{u1} sharing the same cell as an unit of type @var{u2} 7029may affect the capture outcome of the latter. This applies to occupants 7030as well. Set to @code{0%} to disallow capture of @var{u2} when @var{u1} 7031is in the same cell as it. Defaults to @code{100%}. 7032@end deffn 7033 7034@deffn TableUU @code{scuttle-chance} u1 u2 -> n% 7035This table is the chance that @var{u1}, whose capture by @var{u2} is 7036guaranteed, will destroy itself instead. Scuttling is destructive, so 7037@var{u1} changes to @code{wrecked-type}. Occupants of an 7038about-to-be-captured unit will also attempt to scuttle. 7039@end deffn 7040 7041@deffn TableUU @code{occupant-escape-chance} u1 u2 -> n% 7042This table is the chance that an occupant @var{u1} will escape during 7043the capture of a unit of type @var{u2}. Occupants that do not escape 7044are either captured themselves or destroyed, depending on their type and 7045the capturing unit's side. 7046@end deffn 7047 7048@deffn TableUU @code{hp-to-garrison} u1 u2 -> n 7049This table is the number of hp that will be taken from the capturing 7050unit @var{u1} in order to guard a captured @var{u2}. If the amount is 7051the unit's full hp, then the unit will vanish and any occupants will be 7052distributed to the captured unit, to open terrain, or will vanish 7053themselves if there is no other option. 7054@end deffn 7055 7056@deffn TableUU @code{countercapture} u1 u2 -> n 7057This table defines the defending unit's reaction to the capture attempt. 7058If 0, then the unit does not react to the capture attempt. 7059@end deffn 7060 7061Captures can also affect combat experience, but has different effects on 7062the capturing and captured units. 7063 7064@deffn TableUU @code{cxp-per-capture} u1 u2 -> cxp 7065This table is the number of combat experience points gained by @var{u1} 7066for capturing @var{u2}. 7067@end deffn 7068 7069@deffn UnitTypeProperty @code{cxp-on-capture-effect} n 7070This property gives the change in a unit's cxp due to being captured, 7071expressed as a multiplier. 7072Defaults to @code{100}. 7073@end deffn 7074 7075The treasuries of the sides of the captor and prisoner units may be 7076modified as a result of capture. 7077 7078@deffn TableUM @code{treasury-gain-per-capture} u m -> n 7079This is the amount of @var{m} gained when @var{u} is captured in combat. 7080This material is added to the treasury of the side that destroyed @var{u}. 7081@end deffn 7082 7083@deffn TableUM @code{treasury-loss-per-captured} u m -> n 7084This is the amount of @var{m} lost when @var{u} is captured in combat. 7085This material is taken from the treasury of the side of @var{u}. 7086@end deffn 7087 7088Capture of an unit may result in its changing type. 7089 7090@deffn TableUU @code{changed-type-if-captured} u1 u2 -> u3 7091If an unit of type @var{u1} is captured by an unit of type @var{u2}, then 7092it will attempt to change into type @var{u3}. Defaults to @code{non-unit}, 7093which means that no change of unit type will be attempted. 7094@end deffn 7095 7096Capture of a unit may also yield an extra dividend of knowledge, 7097in the form of information known to the other side. 7098 7099@deffn UnitTypeProperty @code{see-terrain-if-captured} n% 7100If the world's terrain is not already seen, this property is the chance 7101that the capturing side will get all of the terrain view collected 7102by the former side of the captured unit. This does not apply to any 7103unit views, just terrain. 7104@end deffn 7105 7106@deffn TableUU @code{see-others-if-captured} u1 u2 -> n% 7107This table is the chance that the capturing side will get a view of a 7108unit of type @var{u2} belonging to the other side. The chance applies 7109to each unit of that type when a unit of type @var{u1} is captured. 7110@end deffn 7111 7112@node Detonation Action 7113 7114@subsection Detonation Action 7115 7116Detonation is an action and/or behavior that causes damage 7117indiscriminately. The action specifies the location of the detonation, 7118which may be in the unit's cell or an adjacent one. A unit that 7119detonates loses hp, changing to its @code{wrecked-type} if it loses all 7120of its hp. It also hits every unit within a specified radius. 7121Detonation may also affect terrain within a specified radius. 7122 7123@deffn ActionType @code{detonate} x y z 7124This action detonates the actee at the given location @var{x},@var{y},@var{z}. 7125@end deffn 7126 7127@deffn UnitTypeProperty @code{acp-to-detonate} acp 7128This property is the number of action points used by one detonate 7129action. Defaults to @code{0}, which disallows detonation. 7130@end deffn 7131 7132@deffn UnitTypeProperty @code{hp-per-detonation} hp 7133This property is the number of hp lost in each detonation. 7134@end deffn 7135 7136@deffn TableUU @code{detonation-unit-range} u1 u2 -> dist 7137This table gives the range of effect from detonation of @var{u1}. The 7138severity falls off according to the inverse square law extrapolated from 7139the adjacent cell damage. (1/4 severity at range 2, 1/9 at 3, etc.) 7140@end deffn 7141 7142@deffn TableUU @code{detonation-damage-at} u1 u2 -> hp 7143This table is the severity of @var{u1}'s hit on a unit @var{u2} in the 7144same cell. 7145@end deffn 7146 7147@deffn TableUU @code{detonation-damage-adjacent} u1 u2 -> hp 7148This table is the severity of @var{u1}'s hit on a unit @var{u2} in an 7149adjacent cell. 7150@end deffn 7151 7152@deffn TableUT @code{detonation-terrain-range} u t -> dist 7153This table specifies the maximum distance at which a detonation will 7154affect terrain of type @var{t}. 7155@end deffn 7156 7157@deffn TableUT @code{detonation-terrain-damage-chance} u t -> n% 7158This is the chance that the detonation will have an effect on the 7159terrain. 7160@end deffn 7161 7162@deffn TableTT @code{terrain-damaged-type} t1 t2 -> n 7163Relative chance that terrain of type @var{t1} damaged by a detonation 7164will change into another type @var{t2}. 7165@end deffn 7166 7167The following tables and properties can be used for units that cannot 7168detonate deliberately by doing a detonate action. 7169 7170@deffn TableUU @code{detonate-on-hit} u1 u2 -> n% 7171This table is the chance that a hit on @var{u1} by a unit of type 7172@var{u2} will cause it to detonate (once). Noncombat reductions in hp, 7173such as attrition, have no effect. 7174@end deffn 7175 7176@deffn UnitTypeProperty @code{detonate-on-death} n% 7177This property is the chance that if this type is about to die from a 7178combat hit, it will detonate first. 7179@end deffn 7180 7181@deffn UnitTypeProperty @code{detonate-on-attack} n% 7182This property is the chance that if this type scores a hit (and damages) 7183an enemy unit, it will detonate first. 7184@end deffn 7185 7186@deffn TableUU @code{detonate-on-capture} u1 u2 -> n% 7187This table is the chance that a unit of type @var{u1} will detonate if a 7188capture by a unit of type @var{u2} is about to succeed. 7189@end deffn 7190 7191@deffn TableUU @code{detonate-on-approach-range} u1 u2 -> dist 7192When a unit of type @var{u2} on a non-trusted [?] side appears at a 7193distance of @var{dist} or less, then @var{u1} will detonate. If 7194@code{-1}, then unit will not detonate upon approach. Defaults to 7195@code{-1}. 7196@end deffn 7197 7198@deffn TableUT @code{detonation-accident-chance} u t -> n.f% 7199This table is the chance that the unit will detonate spontaneously. 7200This is checked once/turn, at the beginning of the turn, and also upon 7201each entry to a cell, if moving. 7202@end deffn 7203 7204@node Terrain Alteration Actions 7205 7206@subsection Terrain Alteration Actions 7207 7208@deffn ActionType @code{alter-terrain} x y t 7209This action changes the type of the cell at @var{x},@var{y} to @var{t}. 7210@end deffn 7211 7212@deffn ActionType @code{add-terrain} x y dir t 7213This action adds a connection or border of type @var{t} to the cell at 7214@var{x},@var{y}, in direction @var{dir}. 7215@end deffn 7216 7217@deffn ActionType @code{remove-terrain} x y dir t 7218This action removes a connection or border of type @var{t} to the cell 7219at @var{x},@var{y}, in direction @var{dir}. 7220@end deffn 7221 7222@deffn TableUT @code{acp-to-add-terrain} u t -> n 7223@end deffn 7224@deffn TableUT @code{acp-to-remove-terrain} u t -> n 7225For auxiliary terrain types, these tables are the costs to add or 7226remove. For cell terrain, the costs of removing the old type and adding 7227the new type are added together. If the value is 0, then that type of 7228terrain may not be added or removed. As a special exception, cell 7229terrain may have a cost to remove of 0, so that the sum of add and 7230remove costs can be as low as 1; in that case, a value of -1 disallows 7231removal. Both default to @code{0}. 7232@end deffn 7233 7234@deffn TableUT @code{alter-terrain-range} u t -> n 7235This table is the maximum distance at which a unit can alter terrain 7236@var{t}. Defaults to @code{0}, which means that the unit can change 7237only the terrain in its own cell. 7238@end deffn 7239 7240Note that if @code{see-terrain-always} is false, then other sides will 7241not see the terrain change unless they are viewing the altered terrain. 7242 7243@deffn TableUM @code{material-to-add-terrain} u m -> n 7244This table is the amount of material necessary to perform an 7245@code{add-terrain} or @code{alter-terrain} action. 7246@end deffn 7247 7248@deffn TableUM @code{material-to-remove-terrain} u m -> n 7249This table is the amount of material necessary to perform a 7250@code{remove-terrain} action. 7251@end deffn 7252 7253@deffn TableTM @code{consumption-per-add-terrain} t m -> n 7254This table is the amount of material @var{m} necessary for any unit to 7255add terrain of type @var{t}. 7256@end deffn 7257 7258@deffn TableTM @code{material-per-remove-terrain} t m -> n 7259This table is the amount of material of type @var{m} that becomes 7260available as the result of removing terrain @var{t}. 7261@end deffn 7262 7263@node Backdrop 7264 7265@section Backdrop 7266 7267This section describes the parameters affecting backdrop computations. 7268 7269@menu 7270* Years and Days:: 7271* Temperature Variation:: 7272* Temperature Effects:: 7273* Wind Variation:: 7274* Unit Production and Consumption:: 7275* Terrain Production and Consumption:: 7276* Supply Lines:: 7277* Side Research:: 7278* Unit Research:: 7279* Terrain Attrition:: 7280* Terrain Accident:: 7281* Unit Revolt:: 7282* Unit Surrender:: 7283@end menu 7284 7285@node Years and Days 7286 7287@subsection Years and Days 7288 7289Cyclic changes in the environment are governed by a yearly cycle or a 7290daily cycle whose length must be defined. 7291 7292@deffn WorldProperty @code{year-length} n 7293This property is the number of turns in an annual cycle. If less than 7294@code{2}, then no seasonal effects will be calculated. 7295@end deffn 7296 7297@deffn WorldProperty @code{day-length} n 7298This property is the number of turns in a single day. If less than 7299@code{2}, then day and night will not be calculated. 7300@end deffn 7301 7302Note that @code{year-length} and @code{day-length} are completely 7303independent of each other, and it is possible to have days that are 7304longer than years. 7305 7306@deffn AreaProperty @code{initial-year-part} n 7307This property is the season of the first turn in the game. This affects the 7308sun position, if the sunlit region is dynamically changing. In particular, 7309this can be used to start the sun somewhere other than one of the equinoxes. 7310@end deffn 7311 7312@deffn AreaProperty @code{initial-day-part} n 7313This property is the hour of the first turn in the game, in 100ths of a 7314day part. This affects the sun position, if the sunlit region is 7315dynamically changing. 7316@end deffn 7317 7318@deffn GlobalVariable @code{season-names} list 7319This global is a list of which turns in a year should be called which 7320seasons. It has the form @code{(... (n1 n2 name) ...)}. Defaults to 7321@code{()}. 7322 7323A twelve-turn year with four seasons would be 7324@example 7325((0 2 "winter") (3 5 "spring") (6 8 "summer") (9 11 "autumn")) 7326@end example 7327If any number ranges overlap, then the first match will be used, while 7328if a particular turn has no named season, then it will go unnamed in the 7329display. 7330@end deffn 7331 7332@deffn UnitTypeProperty @code{acp-season-effect} interpolation-list 7333This property is the effect of the seasons on acp. The input value is 7334the year part, and the result value is added to the basic 7335@code{acp-per-turn}. Defaults to @code{()}. 7336@end deffn 7337 7338@deffn WorldProperty @code{daylight-fraction} n% 7339This property is the percentage of the world's circumference that has 7340daylight. Defaults to @code{50}. 7341@end deffn 7342 7343@deffn WorldProperty @code{twilight-fraction} n% 7344This property is the percentage of the world's circumference that has 7345daylight and twilight. Defaults to @code{60}. 7346@end deffn 7347 7348@deffn AreaProperty @code{sun} x y 7349This property is the initial position of the sun over the area. 7350Defaults to the exact middle of the area. 7351@end deffn 7352 7353@node Temperature Variation 7354 7355@subsection Temperature Variation 7356 7357@deffn TerrainTypeProperty @code{temperature-average} n 7358This property is the average temperature for each type of terrain. 7359@end deffn 7360 7361@deffn TerrainTypeProperty @code{temperature-variability} n 7362This property is the amount of totally random variation in the 7363temperature in each cell. 7364@end deffn 7365 7366@deffn GlobalVariable @code{temperature-year-cycle} ((x y) interpolation-list)@dots{} 7367This global is a list of interpolation lists used to set basic 7368temperatures at given points in the area. The input value for each list 7369is the current year part, while the result is the temperature at 7370@var{x},@var{y}. Then for each point in the area, its temperature is 7371the interpolation of the temperature at the two nearest given points. 7372Defaults to @code{()}. 7373@end deffn 7374 7375@deffn TerrainTypeProperty @code{temperature-moderation-range} distance 7376This property is the radius of the area whose raw temperatures will be 7377averaged to get the actual temperature. This can be very time-consuming 7378to calculate, so only values of 0 (no averaging) and 1 (average with 7379adjacent cells) are recommended. 7380@end deffn 7381 7382@node Temperature Effects 7383 7384@subsection Temperature Effects 7385 7386@deffn UnitTypeProperty @code{acp-temperature-effect} interpolation-list 7387This property is the effect of temperature on acp. The input value is 7388temperature, and the result value is multiplied with acp, after it has 7389been modified for night effect, but before modification for season. The 7390result is divided by 100, so an effect < 100 reduces acp, an effect of 7391100 has no effect, and an effect > 100 increases acp. Defaults to 7392@code{()}. 7393@end deffn 7394 7395@deffn UnitTypeProperty @code{consumption-temperature-effect} interpolation-list 7396This property is the effect of temperature on material consumption. 7397Defaults to @code{()}. 7398@end deffn 7399 7400@deffn UnitTypeProperty @code{temperature-attrition} interpolation-list 7401This property is the effect of temperature on a unit's hp. The input 7402value is temperature, and the result value is the number of hp that the 7403unit will lose each turn at that temperature. Defaults to @code{()}. 7404@end deffn 7405 7406Transports can protect their occupants from temperature extremes. 7407 7408@deffn TableUU @code{temperature-protection} u1 u2 -> t/f 7409This is true if transports of type @var{u1} protect occupants of type 7410@var{u2} from the effects of the cell's temperature. 7411@end deffn 7412 7413@node Wind Variation 7414 7415@subsection Wind Variation 7416 7417The following parameters control random variation of the prevailing 7418winds in each cell. 7419 7420@deffn TerrainTypeProperty @code{wind-force-average} n 7421This property is the average wind force in a type of terrain. 7422@end deffn 7423 7424@deffn TerrainTypeProperty @code{wind-force-variability} n% 7425This property is the chance that the wind in a cell will increase or 7426decrease in force each turn. 7427@end deffn 7428 7429@deffn TerrainTypeProperty @code{wind-variability} n% 7430This property is the chance that the wind in a cell will change 7431direction each turn. 7432@end deffn 7433 7434@deffn GlobalVariable @code{wind-mix-range} n 7435This variable is the radius out to which winds interact. If 0, then 7436winds in adjacent cells can vary independently of each other, and do not 7437interact in any way. 7438@end deffn 7439 7440@node Unit Production and Consumption 7441 7442@subsection Unit Production and Consumption 7443 7444Units can be set to always produce some amount of material without 7445taking explicit action. 7446 7447@deffn TableUM @code{base-production} u m -> n 7448This table is the basic amount of each material @var{m} produced by a 7449unit of type @var{u} in each turn. 7450@end deffn 7451 7452@deffn TableUM @code{occupant-base-production} u m -> n 7453This table is the base production of each material @var{m} by a unit 7454of type @var{u} when it is an occupant of any other unit. The default of 7455@code{-1} means to use the number from @code{base-production}. 7456@end deffn 7457 7458@deffn TableUT @code{productivity} u t -> n% 7459This table is the percentage productivity of a unit of type @var{u} when 7460on terrain of type @var{t}. This is multiplied with the basic 7461production rate to get actual material production, so productivity of 7462@code{0} completely disables production on that terrain type, and 7463productivity of @code{100} yields the rate specified by 7464@code{base-production}. Defaults to @code{100}. 7465@end deffn 7466 7467@deffn TableUT @code{productivity-adjacent} u t -> n% 7468This table is the percentage productivity of a unit of type @var{u} 7469when adjacent to terrain of type @var{t}. The actual productivity 7470of a unit is a max of its productivity on its own cell and the adjacent 7471cells. 7472@end deffn 7473 7474@deffn TableUM @code{productivity-min} u m -> n 7475@end deffn 7476@deffn TableUM @code{productivity-max} u m -> n 7477These tables are the lower and upper bounds on actual production after 7478multiplying by productivity. Default to @code{0} and @code{9999}, 7479respectively. 7480@end deffn 7481 7482@deffn TableUM @code{base-consumption} u m -> n 7483This table sets the amount of materials consumed by the unit in a turn, 7484even if it doesn't move or do anything else. This is a minimum rather than 7485an amount added to others, so movement will not cause the unit to consume 7486extra material until it reaches the base consumption. 7487@end deffn 7488 7489@deffn TableUM @code{hp-per-starve} u m -> .01hp 7490If the unit runs out of a material that it must consume, this table 7491specifies how many 1/100 hp it will lose each turn that it is starving. 7492If starving for several reasons, loss is max of starvation losses, not 7493the sum. This value is stochastic. 7494@end deffn 7495 7496@deffn TableUM @code{consumption-as-occupant} u m -> n% 7497This table is the consumption by a unit of type @var{u1} when it is an 7498occupant, expressed as a percentage of its @code{base-consumption}. 7499This is useful for units such as planes which always consume fuel in the 7500air but not on the ground. Defaults to @code{100}. 7501@end deffn 7502 7503@deffn TableUM @code{gives-to-treasury} u m -> t/f 7504This table is true if units of type @var{u} are able to transfer 7505material of type @var{m} to the side's treasury. 7506@end deffn 7507 7508@node Terrain Production and Consumption 7509 7510@subsection Terrain Production and Consumption 7511 7512Materials may be produced by cells, redistributed, and also taken up by 7513units. Some amount of material may need to stay in the cell's storage, 7514or the type of terrain might change. Exhaustion is tested after all 7515consumption has been accounted for. 7516 7517@deffn TableTM @code{terrain-production} t m -> n 7518This table is the amount of each material @var{m} produced by a cell of 7519the given type @var{t} in each turn. This refers to the material actually 7520produced by the cell itself, which goes into the cell's own materials store 7521and may be available through extraction actions or the backdrop economy. 7522Production by advanced units that use the cell is determined by the 7523@code{production-from-terrain} table. 7524@end deffn 7525 7526@deffn TableTM @code{terrain-consumption} t m -> n 7527This table is the amount of material @var{m} consumed by a cell of type 7528@var{t} each turn. If insufficient material is available, then the 7529terrain may change type. 7530@end deffn 7531 7532@deffn TableTM @code{change-on-exhaustion-chance} t m -> n% 7533This table is the chance that a cell of type @var{t}, with no supply of 7534material of type @var{m}, will become exhausted and change to its 7535exhausted type. 7536@end deffn 7537 7538@deffn TableTM @code{terrain-exhaustion-type} t1 m -> t2 7539If @var{t2} is not @code{non-terrain}, then this table says that any 7540cell with terrain @var{t1} that is exhausted will change to @var{t2}. 7541If several materials are exhausted in the same turn, then the 7542lowest-numbered material type will determine the new terrain type. 7543Defaults to @code{non-terrain}. 7544@end deffn 7545 7546@deffn TableMM @code{people-consumption} m1 m2 -> n 7547This table is the base consumption per turn by people of type @var{m1} 7548of each other material type @var{m2}. 7549@end deffn 7550 7551@deffn TableMM @code{people-production} m1 m2 -> n 7552This table is the people of type @var{m1} base production per turn of 7553each other material type @var{m2}. 7554@end deffn 7555 7556@node Supply Lines 7557 7558@subsection Supply Lines 7559 7560In real life, material production and consumption rarely occur in the 7561same place at the same time. For some games, the player must transfer 7562materials manually, by loading and unloading from units. However, this 7563can be time-consuming and difficult, and is best reserved for scarce 7564and/or valuable materials. For more common materials, @i{Xconq} 7565provides a @dfn{backdrop economy}, which moves materials around 7566automatically. 7567 7568@deffn GlobalVariable @code{backdrop-model} n 7569Two models (potentially more in the future) are available for deciding 7570when and where to transfer materials in the backdrop economy, and they 7571support different features. This variable chooses among the available 7572models. 7573 7574The default, model @code{0}, supports only transfers among units 7575and between units and treasuries, according to @code{in-length}, 7576@code{out-length}, and the treasury settings configured elsewhere. It uses 7577a complicated set of rules to determine which units need supplies, based on 7578their consumption, production, doctrine, and other factors; and it tries to 7579keep material in treasuries instead of units to the extent possible. 7580 7581Model @code{1} has a much different philosophical basis. Instead of trying 7582to divine the designer's intent by examining the game rules, it attempts to be 7583as simple and predictable as possible; its basic rule is that materials 7584always flow wherever they can, from things that have more to things that 7585have less, in such a way as to level out any differences in material supply. 7586It treats treasuries simply as additional units with large capacity, linked 7587to all units that can access the treasuries. If there are two 7588material-handling things (units, treasuries, or terrain cells) that 7589can transfer material, then model @code{1} will keep roughly the same amount 7590of material in each of them, unless that would see one filled beyond its 7591capacity or emptied below its resupply doctrine level, in which case they 7592will be as close to equal as possible given the limitations of the game rules. 7593@end deffn 7594 7595@deffn TableUM @code{in-length} u1 m -> dist 7596@end deffn 7597@deffn TableUM @code{out-length} u2 m -> dist 7598These two tables together determine the length of supply lines between 7599units. The given type of material can only be transferred from unit 7600type @var{u1} to unit type @var{u2} if the distance is less than the 7601minimum of the @code{in-length} of @var{u1} and the @code{out-length} of 7602@var{u2}. 7603 7604For instance, the @code{in-length} for a fighter's fuel might be 3 7605cells, while the @code{out-length} of fuel from a city is 4 cells. Then 7606the fighter will be constantly supplied with fuel when within 3 cells of 7607a city. If the fighter's out-length is -1, it will never transfer any 7608fuel to the city. 7609 7610An in- or out-length of @code{0} means that the two units must be in the 7611same cell, while a negative length disables the automatic transfer 7612completely. Large @code{out-length} values should be used sparingly in model 7613@code{0}, since the algorithm uses the @code{out-length} to define a 7614radius of search for units to be resupplied; and model @code{0} ignores 7615@code{out-length} anyway in the case of materials its rules decide are 7616``scarce''. Model @code{1} always obeys @code{out-length}, and large values 7617make no significant difference to its running time. Both tables default to 7618@code{0}. 7619@end deffn 7620 7621@deffn GlobalVariable @code{backdrop-ignore-doctrine} t/f 7622In model @code{1}, setting this variable @code{true} will allow the 7623algorithm to move material away from units even when the units are already 7624below the minimum levels set by their resupply doctrine. Ignoring doctrine 7625is arguably the approach most consistent with the philosophy of model 7626@code{1}, which is to not attempt to judge which units are or are not needy 7627and only look at their current supply levels as raw numbers. Nonetheless, 7628the default is @code{false}: material will never be moved away from a unit 7629already below its resupply level, to avoid surprising game designers or 7630players who might set a doctrine level and then wonder why units are being 7631drained below that level in the backdrop economy. Which setting works best 7632in a given game design may have to be determined by trial and error. Note 7633that this setting is specific to model @code{1}, and will have no effect in 7634model @code{0}. 7635@end deffn 7636 7637The following six tables control automatic transfers involving terrain. 7638These tables are meaningful only in model @code{1} at present, although it 7639is possible that some future new model or enhancement to model @code{0} might 7640also use them. There are two tables for each of three kinds of transfers: 7641terrain to unit, unit to terrain, and terrain to terrain. Terrain to unit 7642transfers are similar to @code{extract} actions, but happen automatically 7643and without expenditure of any ACP, during the economy phase at the start 7644of each turn. Unit to terrain transfers operate in the reverse direction, 7645with material automatically transferred from the unit's store to terrain; 7646such transfers are intended for special effects like poison gas. Terrain to 7647terrain transfers allow material to diffuse across the landscape. 7648 7649At present, there is no feature provided to limit terrain transfers according 7650to control or ownership, so if unit to terrain transfers are permitted, it is 7651entirely possible that a unit will transfer material to terrain and then 7652some other unit from some other side may pick it up by means of other 7653features, automatically or not, and either directly or after the material 7654has diffused through other intervening cells. 7655 7656@deffn TableUM @code{terrain-to-unit-in-length} u m -> dist 7657Sets the maximum distance at which a unit can receive materials from 7658terrain in the backdrop economy, according to unit and material type. 7659Note that these transfers occur automatically and without expenditure of 7660ACP; deliberate transfers, possibly with an ACP cost, are handled by 7661@code{extract} actions and configured elsewhere. Default is @code{-1}, 7662which disables backdrop terrain to unit transfers. 7663Large values may 7664result in slow computation, but currently-planned, not yet implemented, 7665optimizations should eliminate that issue as long as no very-long-distance 7666transfers are actually permitted by the other tables. 7667@end deffn 7668 7669@deffn TableTM @code{terrain-to-unit-out-length} t m -> dist 7670Sets the maximum distance for terrain to unit transfers according to terrain 7671type of the cell the material is taken from, and material type. For the 7672transfer to be allowed, the distance must be less than or equal to the 7673smaller of the relevant @code{terrain-to-unit-in-length} and 7674@code{terrain-to-unit-out-length} values. At present, only the cell terrain 7675type is examined (other kinds of terrain are ignored). The default is the 7676maximum table value, so that terrain type has no effect on terrain to unit 7677transfers. To make it impossible for units to receive a given material from 7678a given terrain type by automatic backdrop economy transfers, set the 7679relevant @code{terrain-to-unit-out-length} value to @code{-1}. 7680@end deffn 7681 7682@deffn TableUM @code{unit-to-terrain-out-length} u m -> dist 7683Sets the maximum distance for unit to terrain transfers according to unit 7684type and material type. As with @code{terrain-to-unit-in-length}, these 7685transfers occur automatically without player control. Remember that 7686materials once transferred to cells are not automatically owned by any side, 7687and may be picked up by other sides. Default is @code{-1}, which disables 7688such transfers. Large values may result in slow computation, but 7689currently-planned, not yet implemented, optimizations should eliminate 7690that issue as long as no very-long-distance transfers are actually 7691permitted by the other tables. 7692@end deffn 7693 7694@deffn TableTM @code{unit-to-terrain-in-length} t m -> dist 7695Sets the maximum distance for unit to terrain transfers according to cell 7696terrain type of the cell the material is transferred into, and material type. 7697As with @code{terrain-to-unit-out-length}, only the cell type is considered. 7698The default is the maximum table value, and setting a value to @code{-1} 7699disables automatic unit-to-terrain transfers of that material into that 7700terrain. 7701@end deffn 7702 7703@deffn TableTM @code{terrain-to-terrain-out-length} t1 m -> dist 7704Maximum distance for automatic terrain to terrain transfers (diffusion) of 7705material m out of terrain type t1. Default value @code{-1}, which disables 7706diffusion. At present, only cell terrain is considered; however, a planned 7707enhancement will change the default value to @code{0} (still disabling 7708diffusion by default, because diffusion from a cell to itself has no effect) 7709and treat border, connection, and coating terrain as modifiers, so that the 7710actual out-length used will be the sum of the table values for the cell, 7711each coating, and each border or connection on the side nearest the 7712destination cell. 7713@end deffn 7714 7715@deffn TableTM @code{terrain-to-terrain-in-length} t2 m ->dist 7716Maximum distance for automatic terrain to terrain transfers (diffusion) of 7717material m into terrain type t2. Default value is @code{1}, allowing 7718transfers only between adjacent cells. As with 7719@code{terrain-to-terrain-out-length} above, this presently only considers 7720cell type but a planned enhancement will make it consider borders, 7721connections, and coatings as well. 7722@end deffn 7723 7724The following tables control an advanced supply line algorithm that 7725is implemented, but does not seem to work correctly. They are listed 7726here for completeness. The advanced supply line algorithm is activated by 7727the @code{supply} variant, and runs completely separately from the model 7728@code{0} or model @code{1} economy system described above. 7729 7730@deffn Table @code{supply-capacity-deterioration} 7731@end deffn 7732@deffn Table @code{supply-capacity-threshold} 7733@end deffn 7734@deffn Table @code{supply-deterioration} 7735@end deffn 7736@deffn Table @code{supply-enemy-interdiction} 7737@end deffn 7738@deffn Table @code{supply-importance} 7739@end deffn 7740@deffn Table @code{supply-in-max} 7741@end deffn 7742@deffn Table @code{supply-interdiction-adjacent} 7743@end deffn 7744@deffn Table @code{supply-interdiction-adjacent-for-material} 7745@end deffn 7746@deffn Table @code{supply-interdiction-at} 7747@end deffn 7748@deffn Table @code{supply-interdiction-at-for-material} 7749@end deffn 7750@deffn Table @code{supply-in-threshold} 7751@end deffn 7752@deffn Table @code{supply-in-weight} 7753@end deffn 7754@deffn Table @code{supply-neutral-interdiction} 7755@end deffn 7756@deffn Table @code{supply-out-max} 7757@end deffn 7758@deffn Table @code{supply-out-threshold} 7759@end deffn 7760@deffn Table @code{supply-potential} 7761@end deffn 7762@deffn Table @code{supply-potential-terrain-effect} 7763@end deffn 7764@deffn Table @code{supply-starve-weight} 7765@end deffn 7766@deffn Table @code{occupant-supply-potential} 7767@end deffn 7768 7769@node Side Research 7770 7771@subsection Side Research 7772 7773Sides may achieve advances by researching them. 7774 7775@deffn GlobalVariable @code{side-can-research} t/f 7776This variable is true if the side can do research. 7777@end deffn 7778 7779@deffn GlobalVariable @code{indepside-can-research} t/f 7780This variable is true if the independent side can do research. 7781@end deffn 7782 7783@deffn TableAA @code{advance-needed-to-research} a1 a2 -> t/f 7784This table indicates whether advance @var{a1} needs @var{a2} 7785to have been achieved first. 7786@end deffn 7787 7788@deffn TableAA @code{advance-precludes-advance} a1 a2 -> t/f 7789True, if researching @var{a1} prevents @var{a2} from being researched. 7790@end deffn 7791 7792@deffn TableAA @code{advance-consumption-per-rp} a m -> n 7793This table is the amount of material type @var{m} consumed 7794to add one research point for @var{a}. 7795@end deffn 7796 7797@node Unit Research 7798 7799@subsection Unit Research 7800 7801Units may work on advances as a backdrop activity, without 7802expending action points. 7803 7804@deffn UnitTypeProperty @code{can-research} t/f 7805This property is true if the unit can work on advances in the 7806background. 7807@end deffn 7808 7809 7810@node Terrain Attrition 7811 7812@subsection Terrain Attrition 7813 7814Attrition is the automatic loss of hit points due to being in certain types 7815of terrain. This runs once for each unit at the beginning of each turn. 7816 7817@deffn TableUT @code{attrition} u t -> .01hp 7818This table is the rate of loss of hp per turn. 7819The terrain used is cell or connection terrain as appropriate for 7820the unit's position. 7821@end deffn 7822 7823@node Terrain Accident 7824 7825@subsection Terrain Accident 7826 7827Accidents result in the damage or disappearance of a unit in the open 7828in some kinds of terrain. This runs once at the beginning 7829of each turn, on each unit not in a transport. 7830 7831@deffn TableUT @code{accident-hit-chance} u t -> .01n% 7832This table is the chance of the unit being hit while in the given terrain. 7833@end deffn 7834 7835@deffn TableUT @code{accident-damage} u t -> hp 7836This table is the hp that will be lost in an accident. The value is a dice spec. 7837@end deffn 7838 7839@deffn TableUT @code{accident-vanish-chance} u t -> .01n% 7840This table is the chance of the unit simply vanishing while in the given terrain. 7841@end deffn 7842 7843@node Unit Revolt 7844 7845@subsection Unit Revolt 7846 7847Revolt is a spontaneous change of side, 7848occurring in place of a side-given unit action. 7849The new side may be none (independence) or another side. 7850 7851@deffn UnitTypeProperty @code{revolt-chance} .01n% 7852This property is the chance for the unit to revolt spontaneously. 7853@end deffn 7854 7855@deffn UnitTypeProperty @code{revolt-at-opinion-min} .01n% 7856This property is the chance for the unit to revolt when its opinion of 7857its current side is at its lowest possible level. The chance is 7858interpolated for opinions between zero and the minimum. 7859@end deffn 7860 7861@node Unit Surrender 7862 7863@subsection Unit Surrender 7864 7865@deffn TableUU @code{surrender-chance} u1 u2 -> .01n% 7866This table is the chance that a unit of type @var{u1} will change its side 7867to match the side of a unit @var{u2} that is within the @code{surrender-range} 7868for the two types. 7869@end deffn 7870 7871@deffn TableUU @code{surrender-range} u1 u2 -> dist 7872This table is the distance out to which a unit of type @var{u1} 7873will surrender to a unit of type @var{u2}. 7874Defaults to @code{1}. 7875@end deffn 7876 7877@node Behavior 7878 7879@section Behavior 7880 7881The AIs normally make their own decisions about how to play a game, 7882but they can also follow hints provided by the game design. 7883 7884@deffn GlobalVariable @code{ai-may-resign} t/f 7885This variable is true if the AI can evaluate whether to resign and then 7886resign if it likes. Otherwise, it will play until it wins or loses. 7887Defaults to @code{true}. 7888@end deffn 7889 7890@deffn GlobalVariable @code{units-may-go-into-reserve} t/f 7891This variable is true if AI or plan execution can put a unit into 7892reserve for the remainder of a turn. This can prevent unit confusion, 7893but can also put the side at a disadvantage if too many of its units 7894spend turns in reserve rather than doing something useful. Defaults to 7895@code{true}. 7896@end deffn 7897 7898@deffn UnitTypeProperty @code{ai-tactical-range} n 7899This is the range out to which AI and/or plan execution will look for 7900tactical opportunities, such as captures. Defaults to @code{4}. 7901@end deffn 7902 7903@deffn UnitTypeProperty @code{ai-peace-garrison} n 7904This is the number of occupants the AI should have as garrison for the 7905unit if there are no threats nearby. 7906@end deffn 7907 7908@deffn UnitTypeProperty @code{ai-war-garrison} n 7909This is the number of occupants the AI should have as garrison for the 7910unit if there are threatening units nearby. Defaults to @code{1}. 7911@end deffn 7912 7913@deffn GlobalVariable @code{ai-advanced-unit-separation} n 7914This is the recommended distance between advanced units, ideally used 7915when constructing units are deciding where to build. Defaults to 7916@code{3}. 7917@end deffn 7918 7919@deffn GlobalVariable @code{ai-badtask-max-retries} n 7920This is the maximum number of times that task execution will be retried 7921when a task fails. Defaults to @code{6}. 7922@end deffn 7923 7924@deffn GlobalVariable @code{ai-badtask-remove-chance} n 7925This is the probability that a failing task will be removed from 7926the task agenda. Defaults to @code{20}. 7927@end deffn 7928 7929@deffn GlobalVariable @code{ai-badtask-reserve-chance} n 7930This is the probability that a unit whose task is failing will go into 7931reserve and try the task on the following turn. Defaults to @code{6}. 7932@end deffn 7933 7934@deffn GlobalVariable @code{ai-minimal-size-goal} n 7935The minimum size that an unit must be able to grow to in order for 7936the AI to accept construction of it at a given location. 7937Defaults to @code{12}. 7938@end deffn 7939 7940@deffn UnitTypeProperty @code{ground} t/f 7941@end deffn 7942@deffn UnitTypeProperty @code{naval} t/f 7943@end deffn 7944@deffn UnitTypeProperty @code{air} t/f 7945@end deffn 7946@deffn UnitTypeProperty @code{colonizer} t/f 7947@end deffn 7948@deffn UnitTypeProperty @code{facility} t/f 7949These properties identify a unit type as having particular uses and/or 7950characteristics. 7951@end deffn 7952 7953@deffn UnitTypeProperty @code{minimal-sea-for-docks} n 7954The number of cells of sea terrain that must be present before an AI 7955will consider building naval units. Defaults to @code{30}. 7956@end deffn 7957 7958@node Game End 7959 7960@section Game End 7961 7962When a side loses, its units may suffer a variety of fates, including 7963revolt, surrender, wrecking, or disappearance. Disappearance is the 7964default fate. Each type of test is independent, but run in the order 7965wreck, vanish, surrender, revolt. 7966 7967@deffn UnitTypeProperty @code{lost-wreck-chance} .01n% 7968This property is the .01% chance that a unit will be wrecked, as if it 7969had been hit in combat. Once a unit is wrecked, it will not be 7970re-wrecked, even if the wrecked type has itself a nonzero 7971@code{lost-wreck-chance} property. The other loss chances still apply, 7972however. 7973@end deffn 7974 7975@deffn UnitTypeProperty @code{lost-vanish-chance} .01n% 7976This property is the .01% chance that a unit will vanish when the side 7977loses. Defaults to @code{10000}. 7978@end deffn 7979 7980@deffn TableUU @code{lost-surrender-chance} u1 u2 -> .01n% 7981This table is the .01% chance that a unit of type @var{u1} on a losing 7982side will surrender to an adjacent unit of type @var{u2}. 7983@end deffn 7984 7985@deffn UnitTypeProperty @code{lost-revolt-chance} .01n% 7986This property is the .01% chance that a unit on a losing side will 7987revolt and go over to some other side, as per the backdrop activity. 7988@end deffn 7989 7990@node Dates and Time 7991 7992@section Dates and Time 7993 7994@deffn GlobalVariable @code{turn} n 7995This variable is the number of the current turn. 7996@end deffn 7997 7998Note that the first turn of a game is actually turn 1. Pre-game 7999activities happen during ``turn 0''. 8000 8001@menu 8002* Game Length:: 8003* Calendar:: 8004* Real Time:: 8005@end menu 8006 8007@node Game Length 8008 8009@subsection Game Length 8010 8011@deffn GlobalVariable @code{last-turn} n 8012This variable is the number of the last turn. Defaults to @code{-1}, 8013which means that there is no limit on the number of turns. 8014@end deffn 8015 8016@deffn GlobalVariable @code{extra-turn-chance} n% 8017This variable is the chance that the game will go one more turn after 8018the @code{last-turn}. 8019@end deffn 8020 8021@i{Xconq} is currently limited to games of 32,767 turns. 8022 8023@node Calendar 8024 8025@subsection Calendar 8026 8027You can make @i{Xconq} display game time as a calendar date, rather than 8028as a simple turn number. 8029 8030@deffn GlobalVariable @code{calendar} type data@dots{} 8031This variable is the description of the calendar type that will be used. 8032If the variable is @code{()} or the type is @code{number}, then turns 8033will be reported numerically starting from @code{1}. If @code{usual}, 8034then the standard Gregorian calendar will be used. Defaults to 8035@code{()}. 8036 8037If the numeric or @code{number} calendar is in use, then a @var{data} of 8038@code{"cycle"} will yield @code{"cycle 1"}, @code{"cycle 2"}, etc. 8039@end deffn 8040 8041For the @code{usual} calendar, the @var{data} defines how long a turn 8042is, in terms of the calendar. For instance, a time measure of 8043@code{day} (and a base date of @code{"1 Jan 1900"}) will result in turns 8044@code{"1 Jan 1900"}, @code{"2 Jan 1900"}, etc, while a date unit of 8045@code{year} will yield just @code{"1900"}, @code{"1901"}, and so forth. 8046 8047The full form of the @var{data} is 8048@example 8049(@var{date-step-range1} @var{date-step-range2} ...) 8050@end example 8051where each @var{date-step-range} has the form 8052@example 8053( [ @var{start} @var{end} ] @var{type} [ @var{multiple} ] ) 8054@end example 8055where @var{type} has the values @var{second}, @var{minute}, @var{hour}, 8056@var{day}, @var{week}, @var{month}, @var{season}, or @var{year}, where 8057@var{multiple} is the number of that type in eah turn, and where 8058@var{start} and @var{end} define the ranges of turns to use for the 8059given type and multiple of the date. (The ranges are useful for 8060telescoping time periods, such as in civilization-building games where 8061early turns might advance by 50 years each, and later turns by only a 8062year.) 8063 8064@deffn Symbol @code{number} 8065@end deffn 8066@deffn Symbol @code{usual} 8067@end deffn 8068 8069@deffn GlobalVariable @code{initial-date} str 8070This variable is the date, in the specified calendar system, of the 8071first turn. Defaults to @code{""}, which has the effect of setting the 8072initial date to be whatever the calendar does with turn number 1. 8073@end deffn 8074 8075@node Real Time 8076 8077@subsection Real Time 8078 8079A game may also be limited in real time. 8080 8081@deffn GlobalVariable @code{real-time-for-game} seconds 8082@end deffn 8083 8084@deffn GlobalVariable @code{real-time-per-turn} seconds 8085@end deffn 8086 8087@deffn GlobalVariable @code{real-time-per-side} seconds 8088@end deffn 8089 8090@deffn GlobalVariable @code{elapsed-real-time} seconds 8091This is the difference in real time between the start of the game 8092and its current state. 8093@end deffn 8094 8095@node Image Families 8096 8097@section Image Families 8098 8099The @code{imf} form defines graphical images in a platform-independent 8100way. An @i{image family} is a named collection of images of varying 8101sizes and depths. 8102 8103@deffn Form @code{imf} name [ properties ] [ images ] 8104This form declares an image family to exist, with the name @var{name} 8105and @var{properties}, and consisting of the specified @var{images}. 8106Each image has the form 8107@display 8108@code{((@var{w} @var{h} @var{special}) [ @var{properties} ] (@var{type} @var{data}...) ...)} 8109@end display 8110where @var{w} and @var{h} are its width and height, respectively, 8111@var{special} indicates special characteristics of the image, the 8112@var{type} may be one of @code{color}, @code{mono}, @code{mask}, or 8113@code{file}, and the @var{data} consists of strings of hexadecimal 8114digits. The data strings may include slashes, which have no effect on 8115interpretation, but are useful to indicate each row of an image. Color 8116images may also have additional properties, which come between the 8117@var{type} and the @var{data}. 8118 8119The family's @var{name} may consist only of alphabetic characters, 8120decimal digits, and hyphens or underscores. Upper- and lower-case 8121characters are equivalent, as are hyphens and underscores. The 8122canonical form of the name is lowercase with hyphens. 8123 8124Multiple forms with the same name may occur, and each adds to the 8125family, overwriting individual image parts that are of the same size and 8126depth. 8127@end deffn 8128 8129@deffn Symbol @code{tile} 8130If this symbol appears following the dimensions of an image, it 8131indicates that the image is a pattern tile rather than a single image. 8132@end deffn 8133 8134@deffn Symbol @code{border} 8135If this symbol appears following the dimensions of an image, it 8136indicates that the image is a set of images for border terrain. Borders 8137have 16 subimages, each showing a different sort of junction between 8138cells. 8139@end deffn 8140 8141@deffn Symbol @code{connection} 8142If this symbol appears following the dimensions of an image, it 8143indicates that the image is a set of images for connection terrain. 8144Connections have 64 subimages, each for a different pattern of 8145connectons to adjacent cells. 8146@end deffn 8147 8148@deffn Symbol @code{transition} 8149This symbol indicates that the terrain is a transition pattern 8150used to blend two types of terrain. Transitions consist of 8151at least 4 subimages, and may have several variants that can 8152be chosen randomly. 8153@end deffn 8154 8155@deffn ImageProperty @code{actual} w h 8156This property is the actual size of the image data. 8157@end deffn 8158 8159@deffn ImageProperty @code{embed} name 8160This property specifies that another image, similar to the image family 8161named by @var{name}, is already embedded within the image, and so 8162@i{Xconq} need not superimpose such an image itself. This may occur 8163when an image has a ``builtin'' side emblem, or is readily identifiable 8164as belonging to a particular side, and it would be redundant for 8165@i{Xconq} to add an emblem when displaying a unit. 8166@end deffn 8167 8168@deffn ImageProperty @code{embed-at} x y 8169This property specifies that the area of the image at @i{x,y} is 8170suitable for the display of an emblem. 8171@end deffn 8172 8173@deffn ImageProperty @code{embed-size} w h 8174This property specifies the dimensions of the area available for an 8175emblem. 8176@end deffn 8177 8178@deffn ImageProperty @code{x} n [ x y ] 8179This property specifies that the image includes @var{n} variant 8180subimages, any of which may be randomly chosen by an interface. The 8181optional numbers @var{x} and @var{y} indicate the offset of each 8182subimage, so for instance an x of 32 and a y of 0 indicates a horizontal 8183strip of images, each 32 pixels apart. Their values default to the 8184width of the image and 0, respectively. 8185@end deffn 8186 8187@deffn ImageProperty @code{notes} list 8188This property is for designer notes about the image. 8189@end deffn 8190 8191@deffn ImageProperty @code{mono} data @dots{} 8192This property indicates that the data represents a monochrome image. 8193@end deffn 8194 8195@deffn ImageProperty @code{mask} data @dots{} 8196This property indicates that the data represents a mask. 8197@end deffn 8198 8199@deffn ImageProperty @code{color} [ properties ] data @dots{} 8200This property indicates that the data represents a color image. 8201@end deffn 8202 8203@deffn ColorImageProperty @code{pixel-size} n 8204This property is the number of bits used to encode each pixel. 8205@end deffn 8206 8207@deffn ColorImageProperty @code{palette} [ (index r g b) @dots{} ] 8208This property is the color palette that should be used with the image. 8209@end deffn 8210 8211@deffn ImageProperty @code{file} filename [ @code{std} ] [ x y ] 8212This property indicates that the image data is in a file named 8213@var{filename}. @var{filename} must contain a recognized type of image 8214(GIF only, at present). The optional @var{x} and @var{y} indicate the 8215position of the upper left corner of the image within the larger picture 8216contained in the file. 8217 8218If the optional symbol @code{std} precedes the position values, then the 8219numbers are relative positions in a file image that is assumed to be a 8220grid of images all the same size. It is also assumed that images are 8221separated by two pixels on all sides, so the pixel position is @code{2 + 8222(x * (img_width + 2))}. 8223 8224File images do not have explicit masks, but may instead have key colors 8225that will be used to compute the mask. Key colors are indicated by 2x2 8226pixel blocks in the upper left corner of the file image. Any number of 8227key colors may be defined; the end of the list is indicated by a block 8228of the same color as the first block. (See @file{images/river44x48.gif} 8229for an example with many key colors.) 8230@end deffn 8231 8232@deffn Symbol @code{std} 8233This symbol, when in a @code{file} property, indicates that the 8234file image is laid out in a standard grid pattern. (see above) 8235@end deffn 8236 8237Note that for the purposes of stability and change tracking, tools that 8238generate image families use a more restricted format. This format 8239requires a separate imf form for each size of image, the size is on the 8240same line as the imf name, and each image/mask is on a separate line, 8241indented by 2. (See the existing library imf files for further detail.) 8242 8243@node Other Forms 8244 8245@section Other Forms 8246 8247GDL forms in this section are those that do not really fit anywhere 8248else. 8249 8250@menu 8251* Default Display Style:: 8252* The Random State:: 8253* Debugging Support:: 8254@end menu 8255 8256@node Default Display Style 8257 8258@subsection Default Display Style 8259 8260The exact style of display depends on the user interface and on user 8261preferences, but for some games, you may want to encourage a particular 8262style by making it be the default. 8263 8264@deffn GlobalVariable @code{unseen-char} str 8265This variable is a string whose first character will be used to 8266represent unexplored terrain. If the string consists of two characters, 8267the second char will be scattered throughout a field of the first char. 8268Defaults to @code{" ?"}. (At present, this is used only by the curses 8269interface.) 8270@end deffn 8271 8272@deffn GlobalVariable @code{unseen-color} str 8273This variable is the name of a color that will be used to represent 8274unexplored terrain. Defaults to @code{"black"}. 8275@end deffn 8276 8277@deffn GlobalVariable @code{grid-color} str 8278This variable is the name of a color to use to draw the cell-separating 8279grid. Defaults to @code{"dark-gray"}. 8280@end deffn 8281 8282@deffn GlobalVariable @code{unit-name-color} str 8283This variable is the name of a color to use when drawing unit names and 8284numbers. Defaults to @code{"white"}. 8285@end deffn 8286 8287@deffn GlobalVariable @code{unit-gbox-border-color} str 8288This is the color to use around the border of a transport's grouping box. 8289Defaults to @code{"black"}. 8290@end deffn 8291 8292@deffn GlobalVariable @code{unit-gbox-fill-color} str 8293This is the color to use inside a transport's grouping box. 8294Defaults to @code{"white"}. 8295@end deffn 8296 8297@deffn UnitTypeProperty @code{construction-border-color} str 8298This is the color that frames an unit during its construction. 8299Defaults to @code{"SandyBrown"}. 8300@end deffn 8301 8302@deffn UnitTypeProperty @code{construction-fill-color} str 8303This is the color that is shown behind an unit during its construction. 8304Defaults to @code{"brown"}. 8305@end deffn 8306 8307@deffn GlobalVariable @code{contour-color} str 8308This variable is the name of a color to use to draw the elevation 8309contour lines. Defaults to @code{"saddle-brown"}. 8310@end deffn 8311 8312@deffn GlobalVariable @code{meridian-color} str 8313This variable is the name of a color to use to draw meridians of 8314latitude and longitude. Defaults to @code{"black"}. 8315@end deffn 8316 8317@deffn GlobalVariable @code{frontline-color} str 8318This variable is the name of a color to use to draw country borders 8319against other countries. Defaults to @code{"red"}. 8320@end deffn 8321 8322@deffn GlobalVariable @code{country-border-color} str 8323This variable is the name of a color to use to draw country borders 8324against unpopulated areas. Defaults to @code{"pink"}. 8325@end deffn 8326 8327@deffn GlobalVariable @code{shoreline-color} str 8328This variable is the name of a color to use to draw shorelines (liquid 8329adjacent to non-liquid terrain). Defaults to @code{"blue"}. 8330@end deffn 8331 8332@deffn TableTT @code{drawable-terrain} t1 t2 -> t/f 8333This table is true when terrain of type @var{t1} should be drawn over 8334terrain of @var{t2}. In practice, you would set this to @code{false} to 8335suppress the drawing of terrain that extends into an inappropriate 8336types, such as river connections protuding into lakes or seas. Defaults 8337to @code{true}. 8338@end deffn 8339 8340@deffn MaterialTypeProperty @code{resource-icon} n 8341This is a value between 1 and 4 that indicates that a material type is 8342to be drawn in each cell indicating that an advanced unit is producing 8343material in that cell. The value is used by the Mac interface to select 8344one of several icons. 8345@end deffn 8346 8347@node The Random State 8348 8349@subsection The Random State 8350 8351It is useful to be able to restart the random number generator 8352consistently. 8353 8354@deffn GlobalVariable @code{random-state} n 8355This variable is the state of the random number generator. If this is 8356not used, then the initial state of the random number generator will be 8357set in a system-dependent way. 8358@end deffn 8359 8360@node Debugging Support 8361 8362@subsection Debugging Support 8363 8364@deffn Form @code{print} value 8365This form prints to a console or file (depending on the interface) the 8366object @var{value}, in GDL syntax. 8367@end deffn 8368 8369@node Files and Directories 8370 8371@section Files and Directories 8372 8373This section defines file and directory structure for using GDL. This 8374is not required; for instance, an implementation may choose to handle 8375GDL by reading it from strings compiled into the program. However, the 8376standard @i{Xconq} library and implementation does adhere to the 8377conventions described here. 8378 8379A game module is a set of forms in a text file, which has an extension 8380of @code{.g}. 8381 8382By convention, the first form in the file is a @code{game-module} form 8383that defines properties of the module. If the interface has any sort of 8384preview for a particular module, it can then read only the first form, 8385rather than the entire file. 8386 8387Some interfaces include a game selection dialog, which lists a set of 8388games from which to choose, along with a little information about each. 8389The file @code{game.dir} in the library directory contains this list, 8390which is simply a list of module name strings: 8391@example 8392( ;; games that should appear in new game selection dialogs 8393"1756" 8394"cave" 8395"cherbourg" 8396"classic" 8397"coral-sea" 8398"crater-lake" 8399) 8400@end example 8401 8402@i{Xconq} does not currently enforce any sort of standard on file names, 8403but for maximum portability, the file name should not include mixed 8404case, it should consist only of alphabetic and numeric characters and 8405hyphen, and should be less than 12 characters in length, with 8 of those 8406distinct from any other name in the same directory. Since @i{Xconq} 8407implementations typically use the file name as a way to find modules, 8408these restrictions should apply to module names as well. 8409 8410Image files are library files with the extension @code{.imf}. Usually 8411each image file contains a group of images related in some way, perhaps 8412by a common theme or by use in a particular game. @i{Xconq} 8413implementations find images either by a method specific to the platform 8414(such as resource files), or by looking up the image's location in the 8415image directory @code{imf.dir}. The image directory is just a set of 8416pairs of image name and imf file, with markers at beginning and end of 8417the file: 8418@example 8419ImageFamilyName FileName 8420amulet fantasy.imf 8421ant insects.imf 8422anvil-and-crown fantasy.imf 8423ap standard.imf 8424archer ancient.imf 8425. . 8426@end example 8427Note that while @code{game.dir} is a GDL-syntax form, @code{imf.dir} is 8428not. It should rarely be necessary to modify @code{imf.dir} directly; 8429the scripts @code{makedir.sh} and @code{makedir.pl} in the standard 8430library directory are Unix shell and Perl scripts, each of which will 8431generate @code{imf.dir} from a given list of files, such as @code{*.imf} 8432in the library. You should run one of these after adding a new image to 8433a library image file. 8434 8435
