This is ./xcdesign.info, produced by makeinfo version 4.8 from
./xcdesign.texi.

INFO-DIR-SECTION Games
START-INFO-DIR-ENTRY
* Xcdesign: (xcdesign.info).	Designing Games with Xconq.
END-INFO-DIR-ENTRY
   This file documents the design of games for Xconq.

   Copyright (C) 1987-1989, 1991-2000 Stanley T. Shebs

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public
License", and this permission notice, may be included in translations
approved by the Free Software Foundation instead of in the original
English.


File: xcdesign.info,  Node: Top,  Next: Introduction,  Up: (dir)

Top
***

This manual is a full description of how to design games for Xconq.  We
will assume that you are already familiar with playing games in Xconq;
if not, you should try a few different games in the standard library,
so as to get more of a feel for the game system.

* Menu:

* Introduction::
* Game Design::
* Reference Manual::
* Summary of GDL Syntax::
* Permuted Index of GDL Symbols::
* Glossary::
* Index::


File: xcdesign.info,  Node: Introduction,  Next: Game Design,  Prev: Top,  Up: Top

1 Introduction
**************

In this manual, you'll learn how to design new kinds of games with
Xconq.  Xconq has been designed to support the use of a variety of
techniques to design, construct, and test your game idea.  These
techniques range from text file editing to online painting; in most
cases, you will use a combination of techniques to build a complete
game.

   As the person customizing Xconq, you will be called the "designer".
This term also indicates the primary activity, which will be to Design
The Game.  The capabilities described in this manual are merely tools;
it is up to you the designer to exercise discretion and judgement in
using them.

   You design games using Xconq's Game Design Language (GDL).  GDL is
Xconq's common language for defining all parts of a game, from the
entry in the menu that players select games from, down to the last tiny
detail of a saved game.  GDL resembles Lisp, although (at the present
time) it is not a procedural language; there are no functions and very
few control constructs.  Instead, the contents of a file guide the
creation or modification of Xconq objects representing types, tables,
units, and so forth.  While a game is being played, Xconq uses this
data to decide what to do and what to allow players to do.  Players
never actually see GDL directly.

   In this manual, "you" always means you the designer, and players will
be referred to as "players" or "users".  The distinction is important;
as the game designer, you will encounter and deal with many technical
issues relating to the inner workings of Xconq, but if you master those
issues, your players will see only a fun game to play.

   A final caveat before plunging in: Xconq is an experiment in the
design and construction of configurable games.  This means I have had
limited prior art on which to build, and there are lots of odd corners
that have never been tested or even thought about.  In this spirit, I
would like to hear about weird cases, and ideas for how to handle them.

   Chapter 2, "Designing Games with Xconq" is an explanatory guide for
building and modifying Xconq game designs, using both Game Design
Language (GDL) and online editing tools.

   Chapter 3, "Reference Manual" is the complete definition of GDL.  It
includes the syntax and semantics of all parts of the language.

   Appendices include a summary of GDL syntax, a permuted index of GDL
symbols, and a glossary of terms.


File: xcdesign.info,  Node: Game Design,  Next: Reference Manual,  Prev: Introduction,  Up: Top

2 Designing Games with Xconq
****************************

This chapter is an introduction to the process of designing games for
Xconq.  First we will build a simple but complete game, then we will go
through the major parts of a design and see how it all works.  Sections
on specific techniques and the use of online design tools follow.

   Note that this chapter does not formally define any of the GDL
constructs mentioned.  You may find the complete formal definitions in
the reference manual in the next chapter.

* Menu:

* A Tutorial Example::
* Types::
* Setting up a Game::
* Designing the World::
* Designing the Sides::
* Setting up the Units::
* Setup Miscellany::
* Units and Actions::
* Unit Movement::
* Unit Construction::
* Unit Combat::
* Unit Manipulation::
* Material Manipulation::
* Terrain Manipulation::
* Vision Parameters::
* Designing Backdrop Weather::
* Designing Backdrop Economy::
* Adding Random Events::
* Designing the Interface::
* Designing the Text::
* Designing the Graphics::
* Game Module Organization::
* Building New Games::
* Debugging Designs::
* Tricks and Techniques::
* Designing with the Common Interface::
* Designing with the Mac Interface::


File: xcdesign.info,  Node: A Tutorial Example,  Next: Types,  Up: Game Design

2.1 A Tutorial Example
======================

Before delving into the depths of the language, let's look at an
example.  Suppose you just finished watching a Godzilla movie, complete
with roaring monsters, panic-stricken mobs, fire trucks putting out
flames, and so forth, and were inspired to design a game around this
theme.

* Menu:

* Basic Definitions::
* Adding Movement::
* Buildings and Rubble Piles::
* Human Units::
* The Scenario::


File: xcdesign.info,  Node: Basic Definitions,  Next: Adding Movement,  Up: A Tutorial Example

2.1.1 Basic Definitions
-----------------------

Start by opening up a file, calling it something like `g-vs-t.g', or
some other name appropriate for your type of machine, and then type
this into it:
     (game-module "g-vs-t"
       (title "Godzilla vs Tokyo")
       (blurb "Godzilla stomps on Tokyo")
     )

   This is a GDL "form".  It declares the name of the game to be
`"g-vs-t"', gives it a title that prospective players will see in
menus, plus a short description or "blurb".  The blurb should tell
prospective players what the game is all about, perhaps whether it is
simple or complex, or whether it is one-player or multi-player.  Both
title and blurb are examples of "properties", which are like slots in
structures.

   The `game-module' form is optional but recommended; some interfaces
use it to add the game to a list of games that players can choose from.

   The general syntax of `game-module' form is similar to that used by
nearly all GDL forms; it amounts to a definition of an "object" (such
as a game module or a unit type) with "properties" (such as name,
description, speed, etc).  Some properties are required, and appear at
fixed positions, while others are optional and can be specified in any
order, so they are introduced by name.  The general format, then, looks
like
     (<object> ... <required properties> ...
       ...
       (<property name> <property value>)
       ...
       )
   There are very few exceptions to this general syntax rule.

   (People often have trouble with parentheses in Lisp, but if you
follow the same kinds of indentation rules that you always use in C or
Pascal, then you will encounter no additional trouble.  Also, many
editors such as Emacs are intelligent enough to indicate when
parentheses match, and automatically do proper indentation.)

   Now the first thing you'll need is a monster.  In Xconq, each unit
has a type, and you define the characteristics attached to the type.
     (unit-type monster)
   This declares a new unit type named `monster', but says nothing else
about it.  Let's use this more interesting form instead:
     (unit-type monster
       (image-name "monster")
       (help "crushes, crumbles, and chomps")
       (start-with 1)
     )
   This shows the usual way of describing the monster.  In this case,
`image-name' is a property that specifies the name of the icon that
will be used to display a monster.  (Xconq comes with a library of over
700 icons, of which "monster"; it looks a little like Godzilla.)  The
property `start-with' says that each side should start out with one
monster.  This isn't quite right, because there should only be one side
with a monster, and this will give each side a monster to start out
with, but we'll see how to fix that later on.

   We also need at least one type of terrain for the world:
     (terrain-type street (image-name "gray"))

   These two forms are actually sufficient by themselves to start up a
game.  (Go ahead and try it.)  However, you'll notice that the game is
not very interesting.  Although each player gets a monster, and the
world consists of all-street terrain, nobody can actually _do_
anything, and turns just whiz by, since the defaults basically turn off
all possible actions.


File: xcdesign.info,  Node: Adding Movement,  Next: Buildings and Rubble Piles,  Prev: Basic Definitions,  Up: A Tutorial Example

2.1.2 Adding Movement
---------------------

OK, let's give the monsters the ability to act by putting this form into
the file:
     (add monster acp-per-turn 4)

   The `add' form is very useful; it says to modify the existing type
named `monster', setting the property `acp-per-turn' to 4, overwriting
whatever value might have been there previously.  The `acp-per-turn'
property gives the monster the ability to act, up to 4 actions in each
turn.  By default, the ability to act is 1-1 with the speed of the
unit, so the monster can also move into a new cell 4 times each turn.
If you run the game now, you will find that your monster can now get
around just fine.

   Why 4?  Actually, at this point the exact value doesn't matter, since
nothing else is happening.  If the speed is 1, then the turns go faster;
if the speed is 10, then they go slower and more action happens in a
single turn.  In a complete design however, the exact speed of each unit
can be a critical design parameter, and for this game, I figured that a
speed of 4 allowed a monster to cover several cells in a hurry while not
being able to get too far.  Also, I'm planning to make panic-stricken
mobs have a speed of 1, which is the slowest possible.  Making actions
1-1 with speed is usually the right thing to do, since then a player
will get to move 4 times each turn (later on we will see reasons for
other combinations of values).

   The `add' form works on most types of objects.  It has the general
syntax
     (add <type(s)/object(s)> <property name> <value(s)>)
   The type or object may be a list, in which the value is either given
to all members of the list, or if it is a list itself, then the list of
values is matched up with the list of types.


File: xcdesign.info,  Node: Buildings and Rubble Piles,  Next: Human Units,  Prev: Adding Movement,  Up: A Tutorial Example

2.1.3 Buildings and Rubble Piles
--------------------------------

To give the monster something to do besides walk around, add buildings
as a new unit type:
     (unit-type building (image-name "city20"))

     (table independent-density (building street 500))
   The `building' type uses an icon that is normally used for a
20th-century city, but it has the right look.  The
`independent-density' table says how many buildings will be scattered
across in the world.  The `table' form consists of the name of the
table followed by one or several three-part lists; the two indexes into
the table, and a value.  In this case, one index is a unit type
`building', the other is a terrain type `street', and the value is
`500', which means that we will get about 500 buildings placed on a
100x100 world (look up the definition of this table in the index).  You
need some for testing purposes, otherwise you won't see any when you
start up the game.

   We're going to let buildings default to not being able to do
anything, since that seems like a reasonable behavior for buildings
(although Baba Yaga's hut might be fun...).

   By default, buildings act strictly as obstacles; monsters cannot
touch them, push them out of the way, or walk over them.  In real(?)
life of course, monsters hit buildings, so we have to define a sort of
combat.
     (table hit-chance
       (monster building 90)
       (building monster 10)
       )

     (table damage
       (monster building 1)
       (building monster 3)
       )

     (add (monster building) hp-max (100 3))
   The `hit-chance' and `damage' tables are the two basic tables
defining combat.  The hit chance is simply the percent chance that an
attack will succeed, while the damage is the number of hit points that
will be lost in a successful attack.  The unit property `hp-max' is the
maximum number of hit points that a unit can have, and by default, that
is also what units normally start with.

   Note that the `add' form allows lists in addition to single types
and values, in which case it just matches up the two lists.  The `add'
tries to be smart about this sort of thing; see its official definition
for all the possibilities.

   The net effect of these three forms is to say that a monster has a
90% chance of hitting a building and causing 1 hp of damage; three such
hits destroy the building.  A monster's knuckle might occasionally be
skinned doing this; a 10% chance of 3/100 hp damage is not usually
dangerous, and feels a little more realistic without complicating
things for the player.

   Now you can start up a game, and have your monster go over and bash
on buildings.  Simulated wanton destruction!

   By default, a destroyed building vanishes, leaving only empty terrain
behind.  If you want to leave an obstacle, define a new unit type and
let the destroyed building turn into it:
     (unit-type rubble-pile)

     (add building wrecked-type rubble-pile)
   (Incidentally, you need to add the unit-type before any tables are
defined, so that Xconq knows how big the tables need to be.)

   In practice, you have to be careful to define the behavior of rubble
piles.  What happens when a monster hits a rubble pile?  Can the rubble
pile be cleared away?  Does it affect movement?  Try these things in a
game now and see what happens; sometimes the behavior will be sensible,
and sometimes not.

   For instance, you will observe that the default behavior is for the
rubble pile to be an impenetrable obstacle!  The monster can't hit it,
and can't stand on it, and in fact can't do anything at all.  OK, let's
fix it.  Monsters are agile enough to climb over all sorts of things, so
the right thing is to let the monster co-occupy the cell that the rubble
pile is in.  The default is to only allow one unit in a cell, but this
can be changed:
     (table unit-size-in-terrain (rubble-pile t* 0))
   This says that while all other units have a size of 1, rubble piles
only have a size of 0.  By default, each terrain type has a capacity of
1, so this allows one unit and any number of rubble piles to stack
together in a cell.

   If you try this out, you'll find that the monster can now cross over
rubble piles, but still has to bash buildings in order to get them out
of the way.

   Incidentally, it can cause problems to set a unit size to zero,
because it allows infinite stacking.  Since buildings and rubble piles
don't move, there will never be more than one in a cell, but Xconq will
happily let hundreds of units share the same cell, which works, but
causes no end of headaches for players confronted with overloaded
displays.


File: xcdesign.info,  Node: Human Units,  Next: The Scenario,  Prev: Buildings and Rubble Piles,  Up: A Tutorial Example

2.1.4 Human Units
-----------------

Now you've got an "interactive experience" but no game; there's no
challenge or goal.  You could maybe make a two-or-more-player game where
the players race to see who can flatten the mostest the fastest, but
that's still not too interesting to anyone past the age of 5.  Instead,
we need to make some units for the people bravely (or not so bravely)
resisting the monster's depredations:
     (unit-type mob (name "panic-stricken mob") (image-name "mob"))
     (unit-type |fire truck| (image-name "firetruck"))
     (unit-type |national guard| (image-name "soldiers"))
   Note that a type's name may have an embedded space, but then you
have to put vertical bars around the whole symbol.  Things are starting
to get complicated, so let's define some shorter synonyms:
     (define f |fire truck|)
     (define g |national guard|)

     (define humans (mob f g))
   You can use the newly defined symbols `f' and `g' anywhere in place
of the original type names.  The symbol `humans' is a list of types,
and will be useful in filling several propertys at once.

   As with monsters, all these new units should be able to move:
     (add humans acp-per-turn (1 6 2))
   The speeds here are adjusted so that monsters can chase and run down
(and presumably trample to smithereens) mobs and guards, but fire trucks
will be able to race away.

   Also note the use of a three-element list that matches up with the
three elements in the `humans' list.  This is a very useful features of
GDL, and used heavily.  It can also be a problem, since if you add or
remove elements from the list `humans', every list that it is supposed
to match up with also has to change.  Fortunately, Xconq will tell you
if any lists do not match up because they are of different lengths.

   We still need to define some interaction, since monsters and humans
can make faces at each other, and get in each other's way, but otherwise
cannot interact.
     (table hit-chance add
       (monster humans 50)
       (humans monster (0 10 70))
       )
   This time we have to say "add table" because we've already defined
the `hit-chance' table and now just want to augment it.  (Be sure to
place this form after the first `hit-chance' table definition.)

   As with the addition of properties, we can use a list in place of a
single type.

   Last but not least, we need a scorekeeper to say how winning and
losing will happen.  This is a simple(-minded?) game, so a standard
type will be sufficient:
     (scorekeeper (do last-side-wins))
   The `do' property of a scorekeeper may include some rather elaborate
tests, but all we want to is to say that the last side left standing
should be the winner, and the symbol `last-side-wins' does just that.

   There might be a bit of a problem with this in practice, since in
order to win, the monster has to stomp on all the humans, including fire
trucks.  But fire trucks can always outrun the monster, and cannot
attack it directly either, which leads to a stalemate.  You can fix this
by zeroing the point value of fire trucks:
     (add f point-value 0)
   Now, when all the mobs and guards have been stomped, the monster wins
automatically, no matter how many fire trucks are left.


File: xcdesign.info,  Node: The Scenario,  Prev: Human Units,  Up: A Tutorial Example

2.1.5 The Scenario
------------------

As it now stands, your game design requires Xconq to generate all kinds
of stuff randomly, such as the initial set of units, terrain, and so
forth.  However, we _are_ doing a monster movie, so random combinations
of monsters and people and terrain don't usually make sense.  Instead
of trying to define a "reasonable" random setup, we should define a
scenario, either by starting a random game, modifying, and saving it,
or by text editing.  Since online scenario creation is hard to describe
in the manual, let's do it with GDL instead.

   To define a scenario, we generally need three things: sides, units,
and terrain.  Now the basic monster movie idea puts one monster up
against a bunch of people acting together, so that suggests two sides:

     (side 1)

     (side 2 (name "Tokyo") (adjective "Japanese"))

   The `1' and `2' identify the two sides uniquely, since we'll have to
match units up with them in a moment.  The side that plays the monster
is really a convenience; players should just be aware of the one
monster unit, so we don't need any sort of names.  The other side has
many units, which should be qualified as `"Japanese"', and the side as
a whole really represents the city of Tokyo, so use that for the side's
name.

   Now for the units:

     (unit monster (s 1) (n "Godzilla"))

     (unit f (s 2))
     (unit f (s 2))

     (building 9 10 2)

     (define b building)  ; abbreviate for compactness' sake

     (b 10 10 2)
     (b 11 10 2 (n "K-Mart"))
     (b 12 12 2 (n "Tokyo Hilton"))
     (b 13 12 2 (n "Hideyoshi's Rice Farm"))
     (b 14 12 2 (n "Apple Japan"))
     ;; ... need lots of buildings ...

   This example shows two syntaxes for defining units: the first is
introduced by the symbol `unit' and requires only a unit type (or an
id, see the definition in xxx), while the second is introduced by the
unit type name itself and requires a position and side.  The second form
is more compact and thus suitable for setting up large numbers of units,
while the first form is more flexible, and can be used to modify an
already-created unit.  In both cases, the required data may be followed
by optional properties in the usual way.

   Also, since the word "building" is a little longwinded, I defined the
symbol "b" to evaluate to "building".  GDL has very few predefined
variables, so you can use almost anything, including weird stuff like
"&" and "=".  Property names like `s' and `n' are NOT predefined
variables, so you can use those too if you like.

   At this point, you should have a basic game scenario, with one player
being Godzilla, and the other trying to keep it from running amuck and
flattening all of Tokyo.  Have fun!

   You can enhance this scenario in all kinds of ways, depending on how
ambitious you want to get.  Given the basic silliness of the premise,
though, it would be more worthwhile to enhance the silliness and speed
up the pace, rather than to add features and details.  For instance,
name the buildings after all the laughingstock places you know of in
your own town.

   To see where you could go with this, look at the library's `monster'
game and its `tokyo' scenario, which include fires, different kinds of
terrain, and other goodies.


File: xcdesign.info,  Node: Types,  Next: Setting up a Game,  Prev: A Tutorial Example,  Up: Game Design

2.2 Types
=========

Types are the foundation of all Xconq game designs.  Types are like
classes in object-oriented programming but simpler; each set of types is
fixed and used only in a particular way by Xconq.  A game design
defines types of units, materials, and terrain.  Only materials are
optional; every game design must define at least one unit type and one
terrain type.

   Types in GDL are simple compared to most other languages.  There is
no inheritance, no subtyping, no coercions or conversions.  This is not
a real limitation, since game designs are usually too small to make
effective use of any sort of inheritance.  Also, game design is an
exacting activity; inheritance is often difficult to control
satisfactorily.  You can use lists of types to simulate inheritance as
necessary; this is actually more flexible, because you can have any
number of lists with any set of types in each.  It may not seem as
efficient, but GDL is only used during startup, and is almost entirely
array- and struct-based during the game.  (A few places, such as
scorekeeping, examine GDL forms during play.)

   Types are defined one at a time in the game module file.  Each type
gets an index from 0 on up, in order of the type's appearance in the
file.  Although this is not normally visible to you or to the player,
some error messages and other places will make reference to raw type
indices.  Each category of type - unit, material, and terrain is indexed
individually.

* Menu:

* Designing Unit Types::
* Designing Terrain Types::
* Designing Material Types::
* Setting up Type Relationships::
* Stacking::
* Defining Occupants and Transports::
* Hints on Types::


File: xcdesign.info,  Node: Designing Unit Types,  Next: Designing Terrain Types,  Up: Types

2.2.1 Designing Unit Types
--------------------------

Unit types define what the players get to play with.  Unit types can
include almost anything; people, buildings, airplanes, monsters, arrows,
boulders, you name it.

   The basic form of a unit type definition is so:
     (unit-type TYPE-NAME (PROPERTY-NAME PROPERTY-VALUE) ...)
   The appearance of this form in a file means you are adding a new and
distinct type, which has no relation to any other types defined before
and after this one.  The TYPE-NAME must be a unique symbol, such as
`building' or `|fire truck|'. (Note that you can set things up so that
players never see the TYPE-NAME anywhere, so don't worry if your
preferred name conflicts with something else, just choose another
name.)  The PROPERTY-NAME and PROPERTY-VALUE pairs are entirely
optional.  They can always be defined or changed later in the file.
There is little advantage one way or another.

   This particular syntax - keyword followed by name or other identifier
followed by property/value pairs - will be used for most GDL
definitions.

   The number of unit types is limited.  The exact limit depends on the
implementation, but is guaranteed to be at least 127.  This is a huge
number of types in practice; the only situations where this might be
needed would be a fantasy-type game with many types of items and
monsters.  For empire-building games, 8-16 unit types is far more
reasonable.  Keep in mind that with lots of types, players have more to
keep track of, internal data structures will be larger and take longer
to work with, and designing the game will take more time and energy.
Consider also that Xconq gives you a lot of properties that you can set
individually for each unit type, so that when other game systems might
require a distinct types, Xconq lets you use the same type with
different propertys.  For instance, in a fantasy game you wouldn't need
to define "young dragons" and "old dragons" as distinct types, instead
you can vary the hit points or experience of a generic "dragon" type.


File: xcdesign.info,  Node: Designing Terrain Types,  Next: Designing Material Types,  Prev: Designing Unit Types,  Up: Types

2.2.2 Designing Terrain Types
-----------------------------

Each cell in the world has a terrain type.  This type should be thought
of as the predominant contents of the cell, whether it be open ground,
forest, city streets, or the vacuum of deep space.  The type can be
anything you want, and should be adapted to fit the game you're
designing.  Sure, the real world has swamps, but if you're designing a
game set in the Sahara, don't bother defining a swamp terrain type.
Also, the type doesn't carry any preconceptions about elevation or
climate, so you can have swamps at 20,000 feet just as easily as at sea
level.

   The limit on the number of terrain types is large (up to about 127,
depending on the implementation), but in practice, 6-10 types offer
variety without being confusing.  Ideally, several of those types will
be uncommon in the world, so that map displays will consist mostly of
3-4 types of terrain.

   Some game designs involve entities that are very large and do not
move around.  Such entities could plausibly be represented either as
non-moving units or as a distinct terrain type.  To make the right
choice, you need to consider the special characteristics you want to
implement.  Terrain cannot (usually) be changed during the game, nor can
it be moved, but units can be damaged or belong to different sides.  A
realistic example of this choice occurs in the monster game - should a
destroyed building become a "rubble-pile" unit or should the building
stand on rubble-pile terrain and vanish when it is destroyed?  Both
choices are plausible; if the rubble-pile is a unit, then the original
building is then on top of an empty city block, and after the building
is destroyed, the rubble-pile unit can itself be cleaned off, exposing
the empty city block again.  However, you have to decide whether the
rubble-pile unit belongs to a side, how it interacts with other units,
and so forth.  Rubble-pile terrain is simpler, but the players then get
descriptions of brand-new buildings sitting in the midst of
rubble-piles, which is confusing.  This is a case where there is no
"right" answer.


File: xcdesign.info,  Node: Designing Material Types,  Next: Setting up Type Relationships,  Prev: Designing Terrain Types,  Up: Types

2.2.3 Designing Material Types
------------------------------

Material types are the simplest to define.  They have only a few
properties of their own; most of the time they just index tables along
with the other types.  Materials do not act on their own in any way;
instead, players manipulate materials as part of doing other actions.
For instance, you can specify that movement, combat, and even a unit's
very survival depends on having a supply of some material, or that some
material is ammo and consumed gradually when fighting.

   The use of materials is pretty much up to you.  You don't have to
define any material types at all, and game designs with materials are
usually more complicated.  However, the increase in realism is often
worth it; with materials you can limit player activity and/or make some
actions more "expensive" than others.

   As with the other types, you can define up to about 127 material
types, but that would be enough to model the entire global economy
accurately! (and take all week to compute a single turn...)  1-3 types
is reasonable.


File: xcdesign.info,  Node: Setting up Type Relationships,  Next: Stacking,  Prev: Designing Material Types,  Up: Types

2.2.4 Setting up Type Relationships
-----------------------------------

The next sections describe the "static" relationships between types of
objects, meaning those relations which must always hold, both in the
initial setup and throughout a game.


File: xcdesign.info,  Node: Stacking,  Next: Defining Occupants and Transports,  Prev: Setting up Type Relationships,  Up: Types

2.2.5 Stacking
--------------

By default, Xconq allows only one unit in each cell at a time.  This
has the advantage of simplicity, but also makes some bizarre
situations, such as the ability of a merchant ship to prevent an
airplane from passing overhead or a submarine from passing underneath.

   To fix this, you can allow players to stack several units in the
same cell.  This is governed by several tables, which give you control
over which and how many of each type can stack together in which kinds
of terrain.  The basic idea is that a cell has a certain amount of room
for units, as specified by the terrain type property `capacity', and
each unit has a certain size in the cell, according to the table
`unit-size-in-terrain'.

     (add (plains canyons) capacity (10 2))

     (table unit-size-in-terrain
       ((indians town) plains (1 5))
       ((indians town) canyons (1 2))
       )

   In this example, a player can fit 10 indians or 2 towns into a
plains cell, or else one town and 5 indians, while canyons allow only 2
indians or one town.

   In addition, some unit types may be able to count on a terrain type
providing a guaranteed place; for this, you can use the unit/terrain
table `terrain-capacity-x'.  This table (which defaults to 0) allows
the specified number of units of each type to be in each type of
terrain, irrespective of who else is there.  For instance, a space
station could be given space via
     (table terrain-capacity-x (space-station t* 10000))
   So while units on the ground are piling together and being
constrained by capacity, space stations overhead can stack together
freely (space is pretty big, after all).


File: xcdesign.info,  Node: Defining Occupants and Transports,  Next: Hints on Types,  Prev: Stacking,  Up: Types

2.2.6 Defining Occupants and Transports
---------------------------------------

Occupants and transports work similarly to stacking in terrain; there
is both a specialized capacity and a generic capacity that units' sizes
count against.

     (add (transport carrier) capacity (8 4))

     (table unit-size-as-occupant
       ((infantry armor) transport (1 2))
       ((fighter bomber) carrier (1 4))
       )

     (table unit-capacity-x
       (carrier fighter 4)
       )

   It may be that all the different sizes interact so that you can't
prevent huge numbers of small units being able to occupy a single
transport.  To fix this, use `occupants-max'.

   Transport is a physical relationship, so for instance one cannot use
transports to define a convoy whose acp-per-turn is determined by its
slowest member.  (This doesn't mean you can't define a convoy type, but
you will have to pick an arbitrary speed for it.)

   Watch out for unexpected side effects of setting the `capacity' but
not the `unit-size-as-occupant'!  Since `unit-size-as-occupant'
defaults to 1, then a unit with a nonzero capacity can by default take
on any other type as an occupant!

   Also, don't let units carry others of their own type.  Not only is
this of doubtful meaning, Xconq is not guaranteed to cope well with
this situation, since it allows infinite recursion in the
occupant-transport relation.  Ditto for loops; "A can carry B which can
carry C which can carry A".


File: xcdesign.info,  Node: Hints on Types,  Prev: Defining Occupants and Transports,  Up: Types

2.2.7 Hints on Types
--------------------

It is tempting to try to define independent sets of types, each in a
separate module, and glue them together somehow.  However, this doesn't
work well in practice, because in a game, the types interact in
unexpected ways.  Suppose, for example, that you define a set of
airplane types that you want to be generic enough to use with several
different games.  The assessment of those types may vary drastically
from game to game; in one, airplanes are 100 times faster than any
other sort of unit, so that moving airplanes takes up 99% of game play,
while in another, the same set of airplane types are too weak to be of
any interest to players.

   There is a standard set of terrain types called `"stdterr"'.  This
set has a mix of the types found most useful for "Empire-type" games,
and Earth-like percentages for random world generation.


File: xcdesign.info,  Node: Setting up a Game,  Next: Designing the World,  Prev: Types,  Up: Game Design

2.3 Setting up a Game
=====================

You have a spectrum of options for how Xconq will set up a game based
on your design.  At the one end, you can build a scenario that
specifies everything exactly, down to the last unit.  Lest you think
this is too restrictive to be interesting, consider that this is how
chess works...  At the other end of the spectrum, you can let Xconq
manufacture everything, starting only with a handful of numbers that
you supply.

   The next several sections describe the alternatives available for
game setup.  It is important to understand what is possible, because in
general the character of an Xconq game will depend strongly on the
initial setup, and players will be very angry (with you!) if they
discover, several hours into a hard-fought game, that they've been
given a grossly unfair starting position.


File: xcdesign.info,  Node: Designing the World,  Next: Designing the Sides,  Prev: Setting up a Game,  Up: Game Design

2.4 Designing the World
=======================

The Xconq world/area is a two-dimensional grid of fixed shape and size.
You can treat it as representing part of a planet in space, and set up
parameters simulating that, or just make it be itself and not address
the question of the surrounding context.  The appropriate choice
depends on how much realism and complexity you need.  Most computer
games don't bother with this detail; for instance, a game set in an
underground dungeon doesn't usually need to compute daylight, weather,
or seasons.  However, these same details may be very useful for games
set outdoors.

* Menu:

* World Shape and Size::
* World Terrain::
* Synthesizing World Terrain::
* Rivers::
* Roads::
* Independent Units::
* Altitudes and Elevations::
* World Setup Miscellany::


File: xcdesign.info,  Node: World Shape and Size,  Next: World Terrain,  Up: Designing the World

2.4.1 World Shape and Size
--------------------------

Once you've decided whether the area is to be part of a planet or not,
you can address the question of size and shape.  You have two choices
for shape: hexagon and cylinder.  (See the players chapter for pictures
of these.)  The important thing for you as a designer is that the
cylinder wraps around, while the hexagon is bounded on all sides.  One
consequence is that games involving pursuit will be quite different; on
a cylinder, the chase can go 'round and 'round forever, while on a
hexagon, a fleeing unit could be cornered.  Cylinders have a
disadvantage in that there is no obvious "starting place" for
coordinates, scrolling, etc, so there is a navigation and orientation
problem for players, especially if the world is randomly generated and
not the familiar continents of the Earth.  In fact, players will often
not even realize that a world is a cylinder and will assume that the
edge of the display is the edge of the world!  To make a cylindrical
area, set the circumference of the world equal to the width of the
area.  Otherwise, the area will be handled as a hexagon.

   You can choose either to set a fixed size using the `area' form, or
allow players to set the actual size via the `world-size' variant, in
which case you can define the allowable range of sizes.

   Worlds need not be really large.  Larger worlds are harder for
players to manage, they take longer to display, and can consume
prodigious amounts of memory (since they are represented as arrays
internally, for speed).  The ideal range of sizes depends primarily on
the size and speed of units.  A 60x60 area in a game with units whose
speed is 1 means that they will take 60 turns to cross, while units with
a speed of 20 take only 3 turns, so they make the world "feel smaller".
As another example, in the standard game, a 20x20 area allows player to
come to grips quickly, but it also means that each player's units might
be within attack range right from the outset, which has a drastic
effect on strategy.  For exploration-oriented games, larger worlds are
more interesting.


File: xcdesign.info,  Node: World Terrain,  Next: Synthesizing World Terrain,  Prev: World Shape and Size,  Up: Designing the World

2.4.2 World Terrain
-------------------

The best technique for designing the terrain of a world is to use the
designer tools provided with Xconq.  The details of how these tools
work depends on the interface, but in general they resemble the tools
found in paint programs.  Some interfaces also give you the option of
rescaling the map, so that you can fine-tune the size and positioning of
the terrain.

   Another technique is to write a program that translates data from
another source (such as NASA satellite data) into Xconq format.
However, if you take a rectangular array of data and just wrap an `area
(terrain ...))' form around it, then everything will appear to be
tilting to the left.  To fix this, have your program map the cell at
`x, y' in the rectangular array to `x - y / 2, y' before writing.  You
must discard values whose new `x' coordinate is negative, or else wrap
them around to the right side of the area, although that is usually
only reasonable for cylindrical areas.

   The crudest technique is to try to build terrain by using a text
editor.  The coordinate system is Cartesian oblique, with the y axis
tilted to form a 60-degree angle with the x axis, so it can be
difficult to relate typed-in characters to the final appearance.
Landforms in the file should appear to be leaning to the left, if they
are to appear upright during play.  However, sometimes text editing is
necessary, for instance when you need to change every instance of a
terrain type to something else.  (Incidentally, some of the large
real-world maps in the library were produced by coding all the terrain
types from an atlas onto graph paper, typing them in, then fixing the
tilt as described above.)

   Incidentally, areas should have some distinguishing terrain around
the edges; this prevents player confusion that sometimes happens when
there is no other clue as to where the edge might be.  However, this is
not enforced by Xconq, and you can put whatever you like along the
edges.  Randomly generated worlds normally use the value of the global
variable `edge-terrain'.


File: xcdesign.info,  Node: Synthesizing World Terrain,  Next: Rivers,  Prev: World Terrain,  Up: Designing the World

2.4.3 Synthesizing World Terrain
--------------------------------

The random way to get terrain for a world is to use one of several
synthesis methods built into Xconq.

   Totally random terrain is available via the synthesis method
`make-random-terrain'.  This just randomly chooses a terrain type for
each cell, using the weights in the `occurrence' property of each type.
An `occurrence' of 0 means that the type will never be placed
anywhere.  This method produces a sort of speckly-looking world, and is
better for testing than for actual play.  Still, if you have two types
`vacuum' and `solar-system', then a form like
     (add (vacuum solar-system) occurrence (20 1))
   will give you a nice starfield for a space game.

   The fractal world method `make-fractal-percentile-terrain' descends
from the most venerable part of Xconq (it was once a piece of Atari
Basic code).  It uses a fractal algorithm along with percentile-based
terrain classification to make realistic-looking worlds with terrain and
elevations.

   To use this method, you first specify how many, what size, and what
height of blobs to splash onto the world, and how many times to average
cells with their neighbors.  Then you specify the subdivision of all the
possible altitudes and moisture levels into different kinds of terrain.
For instance, desert in the standard terrain ranges from sea level
(`alt-percentile-min' = 70%) to high elevations (`alt-percentile-max' =
93%) but only in the lowest percentiles of moisture
(`wet-percentile-min' = 0%, `wet-percentile-max' = 20%).  It is
important that all percentiles be assigned to some terrain type, or the
map generator will complain and subsitute terrain type 0 (the
first-defined type); when designing terrain percentiles, it is helpful
to make a chart with altitude percentiles 0-100 on one axis and
moisture percentiles on the other.  Note that overlapping on this chart
is OK, and the terrain generator will pick the lowest-numbered terrain.
Also note that you don't have to include every terrain type.

   The `alt' numbers are also used to compute elevations for games that
need them, but the `wet' numbers need not have anything to do with
water at all; they could just as easily represent smog levels or
vegetation densities.  If you only want to use one of the two layers,
just set the percentiles for the other to be 0 - 100 for all terrain
types.

   [should have an example]

   The method `make-maze-terrain' produces a maze consisting of a mix
of "solid", "passageway", and "room" terrain.  It uses the
`maze-room-density' and `maze-passage-density' properties of each
terrain type to decide how much of each to use for rooms and passages.
The method first does random terrain generation, using the `occurrence'
property to decide how much of each terrain to put down (remember that
`occurrence' defaults to 1 for all terrain types).  Then it carves out
rooms, and passageways between them.  The passages and rooms are
guaranteed to be completely connected.

   The method `make-earth-like-terrain' attempts to model the natural
processes and generate terrain as similar as possible to what is
observed on Earth today.

   You should note that at least one method for synthesizing terrain
must be available, unless you can guarantee that terrain will be loaded
from a file.  The following subsections describe optional additional
synthesis methods that you can include.


File: xcdesign.info,  Node: Rivers,  Next: Roads,  Prev: Synthesizing World Terrain,  Up: Designing the World

2.4.4 Rivers
------------

You can use the `make-rivers' method to add rivers to the world.
Rivers are basically water features that depend on terrain elevations,
so they won't be generated unless both a river terrain type (either
border or connection) and elevation data is available.  You get them by
specifying a nonzero chance for some type of terrain to be the location
of a headwater (`river-chance').

   Xconq doesn't have any intuition about the behavior of water; it
will happily trace rivers all the the way down to the bottom of the sea.
Use the `liquid' property to tell `make-rivers' what types that rivers
cannot touch.  The method still traces the river's course, and resumes
modifying terrain when possible, which means that the river can appear
as both the inlet and outlet from a lake.


File: xcdesign.info,  Node: Roads,  Next: Independent Units,  Prev: Rivers,  Up: Designing the World

2.4.5 Roads
-----------

The `make-roads' method is a fairly generic method.  It just picks
pairs of units randomly and runs a road between them, attempting to
share road segments and route through favorable terrain.  Although
simplistic, the results look pretty good.

   You can make short bridges by tweaking the road density
appropriately.  Just allow roads from land to water, and water to land,
but not from water to water.

   Note that this method is only useful if there are actually units for
the roads to connect.


File: xcdesign.info,  Node: Independent Units,  Next: Altitudes and Elevations,  Prev: Roads,  Up: Designing the World

2.4.6 Independent Units
-----------------------

For many games, it is useful to have independent units scattered
randomly across the world.  For instance, gold mines and treasure
hoards would be good for an exploration game, and independent castles
for a medieval game.  You can set this up with the
`make-independent-units' method.


File: xcdesign.info,  Node: Altitudes and Elevations,  Next: World Setup Miscellany,  Prev: Independent Units,  Up: Designing the World

2.4.7 Altitudes and Elevations
------------------------------

Xconq is basically a 2-dimensional game, but you can emulate a third
dimension by defining elevations for terrain and altitudes for units
above and below the terrain.

   The main use of altitudes is to control interactions between certain
kinds of units, particularly aircraft.  For instance, a high-altitude
bomber should be able to pass over a ship and under a satellite with
impunity.  In general, you define the "operating altitudes" of a unit,
so in the example above, you could say that a ship is always at the
surface, bombers operate at 1-10 km, and satellites at 100-10,000 km.
If a unit has more than one operating level, then it can move up and
down by normal movement actions.

   Also, most details such as speed and material consumption are the
same for a unit at any altitude.  (Yes, such things vary in real life,
but the effects are usually minor within the unit's normal operating
range.)

   Altitudes have a significant effect on combat.  A unit at some
altitude can only attack units at a specific range of altitudes up and
down.  Using the example again, you could define fighter aircraft to
operate at 0-20km and be able to attack up and down 5km, while bombers
can attack up to 10km down (i.e. down to the ground), but not up.
Satellites remain invulnerable.

   All this applies equally to units underground and undersea.

   [need info about setting up other layers]


File: xcdesign.info,  Node: World Setup Miscellany,  Prev: Altitudes and Elevations,  Up: Designing the World

2.4.8 World Setup Miscellany
----------------------------

For additional flavor, with no effect on game play, you can identify
and name geographical features in the world.

   For predefined areas, just add the `features' layer and either fill
in manually, or with a design tool.  I find that the most efficient
approach is to make a list of all the features that I want to be in the
world, set up the list manually along with layer data saying that all
parts of the area are unnamed (all 0s), then read in the world + feature
layer and use the online feature painting to define the shape of the
feature.

   For random areas, the synthesis method `name-geographical-features'
does the work.  You can use a side property `feature-namers' and a
global variable, also called `feature-namers'.  Both of these map
feature types to namers (for "namers", see below).  The list of types
of features to try to identify is in the global `feature-types'.  The
basic idea is that the synthesizer looks for the types of features
requested, then names them using the appropriate namer.

   Here is what the standard game does to generate funny names for
lakes, but the more-anonymous "Peak 4532" for mountain tops:
     (set feature-types (("peak") ("lake")))

     (set feature-namers (("lake" "generic-lake-names")))

     (namer generic-lake-names (grammar root 10
       (root (or 5 (foo "Lake " generic-names)
                 1 (generic-names " Lake")
                 ))
       (foo "")  ; works around a bug
       ))

     (include "ng-weird")


File: xcdesign.info,  Node: Designing the Sides,  Next: Setting up the Units,  Prev: Designing the World,  Up: Game Design

2.5 Designing the Sides
=======================

Sides represent the players in a game.  They also serve as a repository
of information shared by units, such as technology and knowledge of the
world.

   You should first decide how much about the sides will be predefined.
If you're doing Eastern Front scenarios, it's very easy; you have
Russians and Germans and that's it.  If you're doing a science-fiction
empire-building free-for-all, you may not have to specify anything more
than a random side name generator.

* Menu:

* Predefined Sides::
* Side Library::
* Limits on Sides::
* Hints on Sides::


File: xcdesign.info,  Node: Predefined Sides,  Next: Side Library,  Up: Designing the Sides

2.5.1 Predefined Sides
----------------------

For scenarios and similarly-restrictive games, the game design should
create the sides directly, as in this example:
     (side (name "Germany") ... (colors "black,gray") ...)

     (side (name "Russia") ... (colors "red") ...)

   Since the initialization machinery allows matching any player with
any side, you can get away with being really vague.  This will create
four sides but not say anything about them:
     (side)
     (side)
     (side)
     (side)

   If you're going to have predefined units on each side, then you
should add an id to each side:
     (side 1 (name "Germany") ... (colors "black,gray") ...)

     (side 2 (name "Russia") ... (colors "red") ...)
   Instead of `1' and `2', you can also use, say, `ge' and `ru'; ids
can be either symbols or numbers.


File: xcdesign.info,  Node: Side Library,  Next: Limits on Sides,  Prev: Predefined Sides,  Up: Designing the Sides

2.5.2 Side Library
------------------

If your game design does not predefine all the sides, you can define a
"side library" using the `side-library' variable.  Basically the
library is a weighted list of collections of side properties, each
formatted as a side definition.  Xconq will use this library for any
player that is allowed in the game but who does not have a side already,
and select a side with a probability determined by the weights.  Each
item in the library will be used up to a limit that can be specified
with each item; if the library has been exhausted before all the sides
have been created, then the extra sides will just be assigned general
defaults for their properties.

   The side library here makes futuristic sides for players, making two
of the sides most likely, but allowing others as well:
     (set side-library '(
       (10 (name "Federation") (adjective "Federation") (class "fed"))
       (10 (name "Klingon Empire") (noun "Klingon") (class "klingon"))
       (5 (noun "Romulan") (class "romulan"))
       ((noun "Ferengi") (class "fed"))
       ((noun "Vulcan") (class "fed"))
       ))
   Note that if the game design limits certain unit types to certain
sides, the choice of sides will be more than just a cosmetic issue.


File: xcdesign.info,  Node: Limits on Sides,  Next: Hints on Sides,  Prev: Side Library,  Up: Designing the Sides

2.5.3 Limits on Sides
---------------------

So that you can put upper and lower bounds on the number of sides in
your game, GDL includes the variables `sides-min' and `sides-max'.  As
you might expect, every game design must allow at least one side.  The
upper limit on sides depends on the implementation, but is at least 7.
Large numbers of sides can make a player's life very complicated, not
to mention consuming vast quantities of memory, so you should try to
limit the number of sides as much as possible.

   Another important limit is based on the notion of "side classes".
Each side can have a side class, and multiple sides can belong to the
same class.  For instance, sides named `"Hyperborean"' and `"Germanic"'
could both have class `"barbarian"'.  The value of side classes is that
unit types have a property `possible-sides' that limits which side
class(es) a type can belong to.  This is very important for any game in
which different players should have fundamentally different sorts of
units.  To continue the barbarians example, it is basically impossible
for any barbarian side to have even one Roman legion, whether by
construction, capture, or even surrender.  So you can do something like
     (add legion possible-sides "roman")

     ...

     (side 1 (name "Rome") (class "roman"))
     (side 2 (name "Germania") (class "barbarian"))
     (side 3 (name "Hyperborea") (class "barbarian"))
   and ensure that Roman legions are always Roman.


File: xcdesign.info,  Node: Hints on Sides,  Prev: Limits on Sides,  Up: Designing the Sides

2.5.4 Hints on Sides
--------------------

Note that players tend to identify with the sides they're playing, so a
game should allow for as much personalization as possible.  On the
other hand, some scenarios derive part of their flavor from
predefinitions.  For instance, a scenario with sides named "German" and
"Russian", with appropriate colors and emblems, doesn't have quite the
same feel when players rename them to "Subgenii" and "Simpsons".

   A side can have a huge amount of state data, such as the current
view.  This rarely needs to be included in its entirety; synthesis
methods will usually suffice to set view data correctly.  Since total
security is impossible with a predefined world, setting a side to have
only a partial view won't necessarily be useful to keep players from
knowing what that world really looks like.


File: xcdesign.info,  Node: Setting up the Units,  Next: Setup Miscellany,  Prev: Designing the Sides,  Up: Game Design

2.6 Setting up the Units
========================

Once you've decided how to handle sides in your game, you can move on to
the initial unit setup.  Initial unit setup is very important, since it
has a major bearing on how the rest of the game will go, and can be done
in a number of different ways.

* Menu:

* Predefined Units::
* Making Countries for Players::
* Initial Supply::


File: xcdesign.info,  Node: Predefined Units,  Next: Making Countries for Players,  Up: Setting up the Units

2.6.1 Predefined Units
----------------------

GDL allows you to define everything about every starting unit in the
game.  This is a powerful approach, but requires much preparation.  An
advantage of predefined units is that there are no unpleasant surprises.
For instance, suppose you designed an empire game with ships and cities,
but a random setup leaves some players entirely landlocked.  Not only
will those players be _very_ unhappy, they might come looking for you
before they've calmed down!

   Asking for initial units is pretty easy, you can either type them
into a file or create them directly, using the appropriate designer
tool in a game.
     (city)
     (city 11 12 1)
     (city (n "Brigadoon"))
     (city (@ 10 10) (n "New York"))
     (city (@ 20 10) (n "London") (hp 22))
   The only info that you absolutely have to supply is the unit's type.
If the position is missing, the unit will be placed at a random
location.  If the side number/name is missing, the unit will be
independent or on the first possible side.

   While the type, position, and side of units is important, exact
values of the other properties are rarely important for a scenario.
Also, a unit with fewer filled-in properties can be used in different
games.  For instance, a list of the present-day major cities worldwide
really needs only name and location for each; the game design can fill
in everything else.  One way to do this would be to set up an
appropriate `unit-defaults' just before including the module.

   To make units start inside transports, you need to specify the `t#'
property for the occupant, and have its value be the id number or name
of some other unit.  Your players may get an error message if the
occupant is not of an allowed type for the transport to hold.


File: xcdesign.info,  Node: Making Countries for Players,  Next: Initial Supply,  Prev: Predefined Units,  Up: Setting up the Units

2.6.2 Making Countries for Players
----------------------------------

Despite the advantages of predefining initial units, this doesn't help
when you want variable groups of units to appear in a randomly-generated
world.  Instead, you should use the `make-countries' synthesis method.
The basic idea is that the method picks a good location for each side's
country, scatters an initial set of units around that location, then
possibly grows the country outwards.  You can do anything from small
widely-separated countries to an interlocking nightmare resembling
pre-Bismarck Germany.  Because of this, and because of the requirement
that this method generate random setups that are as fair as possible,
you have a great many parameters to work with.  These parameters should
be tuned carefully - you will probably need to generate and study lots
of initial setups, especially if your parameters constrain the
countries very tightly; the method cannot backtrack to fix a poor
combination of placements.

   The first step in country generation is to select a location for each
side's country.  The location is a point that is the "center" of the
country (the exact value will be unimportant to players, and is not used
outside this method).  The constraints are that the center of each
country is farther than `country-separation-min' from the center of
every other country, that the center is within `country-separation-max'
of at least one other country, and that the given initial area of the
country (as defined by `country-radius-min') includes numbers of cells
of each terrain type bounded by `country-terrain-min' and
`country-terrain-max'.

   The reason for the separation constraints is that having countries
too close together or too far apart can create serious problems.
Consider the poor soul who gets tightly sandwiched between two enemies,
thus becoming lunchmeat, ha ha, or the
not-quite-so-poor-but-still-unlucky player who ends up on the wrong
side of a very large world.  (Keep in mind that your players may ask
for a much larger world than you were thinking of when you designed the
game.)

   The terrain constraints help you put the country in a reasonable mix
of terrain.  For instance, if you want to ensure that your countries
include some land, but be on the coast rather than inland, then you
should say that the country must have a minimum of 1 sea cell and 1 land
cell.  (In practice, the values should be higher, so you don't get small
islands being used as entire countries and lakes being considered the
ocean.)  Keep in mind that these constraints may be impossible to
satisfy, for instance if a particular world does not have enough of the
sort of terrain that is being required in a country.  If the basic
placement constraints fail, Xconq will just pick a random location,
warn about it, and then leave it up to the players to decide on whether
to play the game "as it lies".
     ;;; Keep countries close together, but not too close.

     (set country-separation-min 20)
     (set country-separation-max 25)

   Once Xconq has decided on locations for each country, it then places
the initial stock of units.  You define this initial stock via the unit
properties `start-with' and `independent-near-start'.  The `start-with'
units start out belonging to the side, while the
`independent-near-start' units are independent.  The locations of these
units are random within `country-radius-min' of the center, but are
weighted according to the table `favored-terrain'.  This table is very
important; it is the percent chance that a unit of a given type will be
placed in terrain of the given type.  100 is guaranteed to work, and 0
is an absolute prohibition.  Since `make-countries' tries repeatedly to
place each `start-with' unit until it succeeds, then even terrain with
a `favored-terrain' value of only 10% will get used if there is no
other choice, so the table affects the distribution of units rather
than the number that get placed.  If a starting unit cannot be placed
on any available terrain, but can be an occupant, then Xconq will
attempt to put it inside some unit already present.  This is a good way
to begin a game with aircraft at airports rather than in the air.

   The upshot is that all this will do a reasonable layout if the
parameters are set reasonably.  If, however, `favored-terrain' is never
> 0 for the `start-with' units and the country terrain, but there is
some other terrain type for which this would work, Xconq will change
the terrain.

   This example is from the "classic" Xconq game:
     (set country-radius-min 3)

     (add city start-with 1)
     (add town independent-near-start 5)

     (table favored-terrain 0
       ((town city) plains 100)
       (town (desert forest mountains) (20 30 20))
       )

   The net effect is to give each player one city outright and 5 towns
nearby.  Although created independent, these towns can be easily taken
over right at the beginning of a game, so they are a kind of "warmup"
(like the pushing of pawns at the beginning of a chess game).  The
`favored-terrain' table allows cities to appear only in plains, while
giving more options to towns, since they can appear in deserts,
forests, and mountains.  Even so, towns are 5 times more likely to be in
plains, which is reasonable.

   In addition to defining a country by placing units, you can also have
the synthesizer add people to the country.  People in the country don't
usually have a lot of effect on a game, but are useful for heightened
realism.  You can have people on your side report on units passing
through their cells by setting `people-see-chance'.  To set up people,
use `country-people-chance' to define the probability of terrain in
your country getting people.  For most games, you will want to set this
to a high probability for land types, and to 0 for sea terrain types.

   The optional last step in country generation is to grow the countries
outwards from the initial area.  This is basically a simple simulation
of the historical forces that give countries their variety of shapes.
You enable this by setting `country-radius-max' to a value greater than
the minimum country radius.  The algorithm works by deciding whether to
add to the country each cell at each distance from the country's
center.  The chance depends on the terrain type (via the terrain
property `country-growth-chance') and whether the cell has already been
given to another country.  If the cell belongs to another country
already (as detected by looking at its people), the algorithm uses
`country-takeover-chance' to get the probability of change.  Once a
cell has been given to the country, then the method decides whether to
add a sided or independent unit to the cell (`unit-growth-chance' and
`independent-growth-chance', respectively), or whether to change the
side of an existing unit (`unit-takeover-chance' and
`independent-takeover-chance').  Country growth stops when the absolute
maximum radius has been reached.  However, you can make it stop early
if no cells are being added to the country, by setting
`growth-stop-chance'.

   This example is from one of the variants of the standard game:

     (game-module "standard"
       ...
       (variants
        ...
         ("Large Countries" eval
          (set country-radius-max 100)
          )
       ))

   The resulting effect is to make all the countries border on each
directly.


File: xcdesign.info,  Node: Initial Supply,  Prev: Making Countries for Players,  Up: Setting up the Units

2.6.3 Initial Supply
--------------------

In games involving materials, you have to decide how much will be in the
game at the beginning.  If materials are at all significant (and if
they're not, why include them in the game?), then you need to ensure
that the initial amounts are set up correctly.

   The key table for this is `unit-initial-supply'.  By default, all
units start out empty of all supplies.  This may not be a good default
for materials that units consume, however; if the production process is
too slow, then your initial units may starve at the beginning of the
game.  This can be especially annoying if the initial units starve only
because they ended up on less-favored terrain.  To avoid this, you can
add a clause like `(u* m* 9999)', which, if material capacities are all
less than 9999, causes initial units to start out full.  Note that this
applies to all units, irrespective of side.

   In addition, if you want your game to be based on resource
extraction, you can also set `terrain-initial-supply' to give amounts of
materials to each cell in the world. [mention exhausted-type here?]


File: xcdesign.info,  Node: Setup Miscellany,  Next: Units and Actions,  Prev: Setting up the Units,  Up: Game Design

2.7 Setup Miscellany
====================

This section describes random things.

* Menu:

* Technology::
* Setting up Self-Units::


File: xcdesign.info,  Node: Technology,  Next: Setting up Self-Units,  Up: Setup Miscellany

2.7.1 Technology
----------------

Technology, or tech for short, is useful when technological development
is important to a game.  There are several ways to use it.

   One use of tech is to track the results of research.  You do this by
setting the initial tech of a side to (say) 0, then requiring a certain
tech (say 60) in order to build a desired type.  If a research action
adds 1 to a side's tech, then it will take 60 research actions to gain
the necessary level.  The number of turns, of course, depending on how
many actions the researcher can do each turn, and how many researchers
are available.  So for instance, 10 researching units results in the
work being done in 6 turns instead.  You can limit this schedule
acceleration by setting `tech-per-turn-max'.

   Another use of tech is to differentiate sides.  Suppose you want to
do a game involving earthlings and space aliens.  The aliens can have
satellites overhead that earthlings don't even know are there, they have
equipment earthlings couldn't use even if they were able to capture it.
However, earth scientists might learn something from it.  To do all
this, use `tech-to-see' and friends.

   Tech is fundamentally tied to unit types.  However, many games have a
number of unit types that share technology.  For instance, advances in
bomber technology usually lead to advances in fighter and surveillance
aircraft.  The `tech-crossover' table is available for this purpose.


File: xcdesign.info,  Node: Setting up Self-Units,  Prev: Technology,  Up: Setup Miscellany

2.7.2 Setting up Self-Units
---------------------------

Normally a player runs the side as a whole, and all the units on that
side are disposable and interchangeable.  However, you require one unit
to represent the player personally among the units of the player's side;
this unit is the "self-unit".  What this means is that if that unit is
captured or dies, the player loses the game instantly.  All the other
units on the side will behave normally as for losing, either going over
to the side that captured the player, becoming independent, or
disbanding.

   The idea is to increase the player's motivation for
self-preservation.  This is useful to introduce a risk of capture,
assassination, and so forth.  It also prevents bizarre and unrealistic
strategies in some games.

   For instance, it sometimes happens in empire-building games that
players end up switching countries, because each captured another's
country and neglected to defend their own.  If each player got one
capital city, and that city were to be a self-unit, then the owner
would have to defend it at all costs!

   To make this happen, you could do something like this:
     (set self-unit-required true)

     (add capital-city can-be-self true)

     (add capital-city start-with 1)


File: xcdesign.info,  Node: Units and Actions,  Next: Unit Movement,  Prev: Setup Miscellany,  Up: Game Design

2.8 Units and Actions
=====================

Players can do all kinds of things with their units.  They can push the
units around, they can make units build things, they can get into
fights, or they can just let them sit around.  You as the designer
decide which kinds of things make sense in your game, then set up the
action parameters appropriately.  Is moving through swamps going to be
slow?  Can a small town build any kind of ship, or just small ones?
How often can Godzilla breathe fire?

   Now, what the players work with is the interface, which can do all
kinds of intelligent things - whatever makes sense for that interface.
However, no matter what the interface, no matter what kind of play
automation, player input eventually breaks down into unit actions.  The
set of action types is predefined and can't be changed.  They are also
very primitive.  Each action takes a number of arguments, such as the
type of unit to build or the location to move to, the action just
happens and either succeeds or fails on the spot.  There are no actions
that take longer than one turn to complete, and a unit can perform only
one action at a time.  This may seem horribly restrictive, but actions
are just the low-level building blocks;  players rarely see actions
directly.  You have to be aware of them because the game design
specifies which unit types are capable of which actions.  Each Xconq
interface will adjust itself to disallow input that would result in
types of actions that you have prohibited.

   The number of actions that a unit can do in one turn is limited by
its action points.  A unit with zero action points cannot do anything
at all.  A unit with lots of action points can do lots of actions,
unless each action costs many action points.  You can define the action
point cost of each type of action for each unit type.  In some cases,
the cost will also depend on the action's arguments.

   Acp is actually a little like a bank account, since by not doing
anything for awhile, a unit can accumulate extra acp (up to `acp-max'),
and it can go into debt temporarily, down to `acp-min' (which may be a
negative value).  A unit in "action debt" at the beginning of a turn
cannot move or do anything else, and must wait for a turn when its acp
goes positive again.  This can be a simple way to implement both
fatigued units and units that can do more if they plan for it.

   Actions always include both an actor and an object.  The actor is
the brains, and that is whose acp gets used up, but the object has the
action actually happen to it.  This is so animate units (like humans)
can manipulate inanimate units (like swords).  You enable this by
setting the acp of the inanimate to zero, but requiring nonzero acp in
the various `acp-to-' tables.

   In most cases, the actor and actee are the same unit.


File: xcdesign.info,  Node: Unit Movement,  Next: Unit Construction,  Prev: Units and Actions,  Up: Game Design

2.9 Unit Movement
=================

Movement is the most important action type.  There are actually two
distinct types of actions; one to enter a cell, and one to enter a unit.

   Each unit has a speed which is determined at the beginning of the
turn and determines how many cells it can enter during the turn.
However, terrain, borders, and other obstacles can consume extra
movement points.

* Menu:

* Unit Speed::
* Movement Costs::
* Entering Transports::
* Border Slides::
* Leaving the Area::
* Free Moves::
* Zone of Control::


File: xcdesign.info,  Node: Unit Speed,  Next: Movement Costs,  Up: Unit Movement

2.9.1 Unit Speed
----------------

Units have a base speed `speed' which is the ratio of mp to acp.  You
can set damaged units to move more slowly.  You can also allow
occupants to add to the speed, up to the `speed-max' limit.

   You can define wind-affected units by defining speed in each
direction (max-speed only, do others proportionally).  Would need 4
distinct mp costs plus a formula to relate to wind strength.  Wind
speed defined as "how far a particle of air moves in a turn".  Unit
examples include balloons, dirigibles, sailing ships, floating cities.


File: xcdesign.info,  Node: Movement Costs,  Next: Entering Transports,  Prev: Unit Speed,  Up: Unit Movement

2.9.2 Movement Costs
--------------------

Typically the cell entry cost will be the most useful to adjust,
although the departure cost can be useful in representing units mired
in jungle mud and taking a long time to escape onto clear terrain.

   Be aware that complicated entry/exit costs are confusing to players,
and AIs may not take them into account very well either.  Using
`free-mp' helps players use up all their acp.


File: xcdesign.info,  Node: Entering Transports,  Next: Border Slides,  Prev: Movement Costs,  Up: Unit Movement

2.9.3 Entering Transports
-------------------------

Different kinds of transports have different ways for units to get on
and off.  For instance, ships can dock, or use their boats to enable
land units to get on and off.  The tables `ferry-on-entry' and
`ferry-on-departure' specify how much terrain units will have to cross
on their own.

   [example]

   Observe that enter/leave costs can be used to make one-way trips.
For instance, paratroops jumping out of a plane should be able to leave
cheaply, but have an entry cost so high that they can only reboard in a
later turn.


File: xcdesign.info,  Node: Border Slides,  Next: Leaving the Area,  Prev: Entering Transports,  Up: Unit Movement

2.9.4 Border Slides
-------------------

One of the problems with Xconq borders and connections is that neither
works exactly like a sea strait.  Consider the Straits of Gibraltar.
They are so narrow that one can see the other side, but nevertheless
impose a formidable barrier to landlubbers.  At the same time, ships
can pass through readily, if not secretly.  If cells in the world are
60 miles across, then making an all-sea cell is a gross exaggeration.
However, adding a water border only prevents both land and sea movement!
To get around all this, Xconq allows a special kind of move called a
"border slide".  Basically, if both the destination cell and the border
whose endpoints touch the start and end cells are allowable terrain for
a unit, then the unit can move to the destination cell in one move.
However, it incurs a special cost in addition to the normal entry and
leave costs for the terrain in the two cells (but not the border
crossing cost, since the border is not being crossed, exactly).  This
cost is in the table `mp-to-traverse'.  Border sliding should usually
be somewhat expensive, both because of the distance (the unit ends up
two cells away after only one move), and because of the real-life
difficulties of passing through a narrow strait.  Note that border
sliding does not escape the units on either side of the border, since
the unit doing the sliding will still be adjacent to the cells on each
side of the border it slid through.


File: xcdesign.info,  Node: Leaving the Area,  Next: Free Moves,  Prev: Border Slides,  Up: Unit Movement

2.9.5 Leaving the Area
----------------------

This feature can be useful in allowing a non-disbandable unit type to
escape capture or otherwise retire from action.


File: xcdesign.info,  Node: Free Moves,  Next: Zone of Control,  Prev: Leaving the Area,  Up: Unit Movement

2.9.6 Free Moves
----------------

This is most useful in emulating some board games, or to prevent clever
players from exploiting a mess of move costs.  The default of `-1' is
the most playable, since player will always be able to use all of their
mp.  Otherwise, there may be situations in which a unit has a few acp
left, but not enough to go anywhere, and so they end up being wasted.
The free move does not actually get subtracted from the unit's acp, it
just doesn't let lack of acp forbid the move.


File: xcdesign.info,  Node: Zone of Control,  Prev: Free Moves,  Up: Unit Movement

2.9.7 Zone of Control
---------------------

Sometimes a unit can by its presence alone affect the movement of
unfriendly units in the vicinity, perhaps by requiring them to hide or
to move carefully in order to pass by, or even to prevent entry
altogether.  This is called the "zone of control" or ZOC.

   Exerting a ZOC requires no action, nor any particular capability on
on the part of the unit exerting the ZOC.  For instance, a toothless
fort could still cause raiders to sneak by carefully (at least if they
didn't know that it was toothless).


File: xcdesign.info,  Node: Unit Construction,  Next: Unit Combat,  Prev: Unit Movement,  Up: Game Design

2.10 Unit Construction
======================

Construction is very important to empire-building and similar strategic
games.  The construction of a unit may involve as many as four different
kinds of actions.  This is so you can make construction be an expensive
long-term process.

   The basic construction is unit creation.  A player might have to do
research and toolup actions in order to prepare for creation, and might
also have to do completion actions, if the created unit is not ready to
use.

   Normally the interface will just have a single "Build <type>"
command, which then results in a task that issues appropriate actions,
so players don't necessarily see all these different actions.

* Menu:

* Researching::
* Tooling Up::
* Creation::
* Completion::
* Repair::


File: xcdesign.info,  Node: Researching,  Next: Tooling Up,  Up: Unit Construction

2.10.1 Researching
------------------

Some types of units may be relatively easy to build, once you know how,
but at the same time that type totally changes the balance of the game.
The atomic bomb in WWII is the classic example; once it became
available, everything changed.

   To allow research, set `acp-to-research' to 1 or more.


File: xcdesign.info,  Node: Tooling Up,  Next: Creation,  Prev: Researching,  Up: Unit Construction

2.10.2 Tooling Up
-----------------

Toolup costs are what you use to represent the overhead of changing
construction.  Quite often it does not need to be set.  Its primary use
is to encourage players to commit to grand strategy once chosen,
because the cost of changing would be prohibitive.


File: xcdesign.info,  Node: Creation,  Next: Completion,  Prev: Tooling Up,  Up: Unit Construction

2.10.3 Creation
---------------

You enable creation of new units by setting `acp-to-create' to 1 or
more.  The location of the newly created unit will depend on both the
types involved and how the interface works, since both `create-in' and
`create-at' actions are available.  For instance, the new unit
immediately takes up space, so if creating unit is already full, then
the interface should have issued a `create-at' action to put the new
unit outside the creator but still stacked in the same cell.  If this
is still too restrictive, and you want to allow players to create units
in nearby cells, you can set `create-range' to values higher than the
default of 0.

   In order to represent the material costs of creation, you can set a
minimum requirement, via `material-to-create', and an amount to be
consumed, via `consumption-on-creation'.  You could think of
`material-to-create' as representing catalysts or work force, while
`consumption-on-creation' is the raw material that becomes part of the
new unit.

   Finally, you can set the `supply-on-creation' to have new material
created and given to the new unit.  This is useful for abstract
materials (such as "enthusiasm") that are somehow ubiquitous.  You
should be careful with this one, because if the new material is
transferrable between units, then players could collect a stockpile of
the material by creating units, stealing their supply, and never
finishing them.


File: xcdesign.info,  Node: Completion,  Next: Repair,  Prev: Creation,  Up: Unit Construction

2.10.4 Completion
-----------------

By default, newly created units are complete and ready-to-use.  This is
rarely a good idea in a game design, since even 1 acp-per-turn creators
can then create another brand-new unit on each turn.  If you're going
to allow that, then you should include something else to keep players
from being swamped by overpopulation.  You can set high accident or
attrition rates, make creation require scarce materials, or make the
creators be scarce.

   The best way to slow down unit creation is to create incomplete
units and then require `build' actions to finish them.  Completeness is
defined in terms of completeness points (cp) that you can set for each
type.  A build action then just adds to completeness points.
Incomplete units do in fact exist as units, so for instance they can be
captured and completed by another side.

   As with creation, you have to set `acp-to-build' to 1 or more just
to enable build actions.

   In order to regulate the rate of completion, you have to set the
`cp-max' of the unit types being constructed, which defines the point
at which the unit will be complete, and then fill in `cp-on-creation'
and `cp-per-build'.  The most straightforward approach is to set
`cp-max' to be the number of turns you want to have between each unit
being constructed, then let `cp-on-creation' and `cp-per-build' both be
1.

   You can set `build-range' so that several units can cooperate to
accelerate construction of a unit.  There are no maximum rate limits
set on this, but it's unlikely that players will ever be able to
achieve much acceleration, because of the limit on the distance between
the builder and the unit.  For instance, the default range of 0 implies
that multiple builders of a unit have to be in the same cell, which may
in turn be constrained by stacking limits.

   As with creation, you can also set values in `material-to-build' and
`consumption-per-build' to govern material requirements and usage.

   You can also allow units to complete themselves.  For instance,
large ships often use part of their soon-to-be crew to help finish the
last stages of fitting out.  You set this up via `cp-to-self-build' and
`cp-per-self-build'.  Since incomplete units are incapable of doing any
actions, this is a totally automatic process that happens at the
beginning of each turn.  Self-building and normal building can proceed
simultaneously, so you can use this to accelerate the final stages of
construction.

   Finally, newly completed units can have materials created for them,
as defined by `supply-on-creation'.


File: xcdesign.info,  Node: Repair,  Prev: Completion,  Up: Unit Construction

2.10.5 Repair
-------------

Players' units will inevitably become damaged, whether in combat, from
accidents, or from other causes.

   There are two ways that units recover hp; either automatically, as
defined by `hp-recovery', or by the explicit action `repair'.
Automatic recovery is good for that part of damage that a unit can fix
just by the passage of time.  It's always good for playability, since a
player just needs to "rest" the unit in order for it to get better.

   On the other hand, the decision to repair may need to be a difficult
one, and impact both tactical and strategic planning.  For instance, a
badly damaged battleship can choose to go on fighting and risk being
sunk, or withdraw for repairs and perhaps jeopardize the campaign it is
supporting.

   In such cases, you can allow explicit repair actions, via the table
`acp-to-repair'.  You can set the repair rate via `hp-per-repair'.  You
can also specify how healthy the repairer must be, via `hp-to-repair'.
Units can repair themselves.


File: xcdesign.info,  Node: Unit Combat,  Next: Unit Manipulation,  Prev: Unit Construction,  Up: Game Design

2.11 Unit Combat
================

Not all games require fighting.  Races and exploration can be lots of
fun, and don't require players to be bashing each other.  However, the
excitement of most Xconq games derives from the chances of going up
against an opponent directly.

   Combat includes five distinct action types that a player may choose
from, not counting detonation, and you specify the characteristics of
each.  "Attack" is hand-to-hand with another unit, "capture" attempts
to change the side without damaging, "fire-at" hits a unit without
getting entangled, while "fire-into" hits everything in a targeted cell.
Finally, "overrun" is an attempt to occupy a cell, doing whatever
combination of attack, capture, and movement is necessary.

   To specify what kinds of battles are possible, you begin by setting
the `hit-chance' of some unit vs another unit to any value greater than
zero.  A hit probability of zero completely disallows attack.  A hit
probability of 100 is a guaranteed hit.  In practice, you will probably
need to specify most hit probabilities individually.

   [describe mods to hit prob?]

   Next you need to set the damage done by a hit.  The default value is
1 hp, which is a good starting place but not always particularly
realistic.

   [describe variation parms]

   As usual, you can define the action point cost of combat, via
`acp-to-attack' and `acp-to-defend'.  The use of separate tables for
attacker and defender allows for some extra flexibility.  This is
important, because sometimes you want to allow combat to keep a
defender busy and soak up its acp, while at other times attempts to
engage in combat should be shrugged off.  Consider battleships vs
infantry; although combat between the two rarely causes much damage, an
attack by a battleship will cause the infantry to keep their heads
down, and preventing them from doing much else, while the return rifle
fire is unlikely to disturb the battleship much!

   Describing simple hit probabilities and damage is oftentimes
sufficient for a game.  It's simple; players can learn the numbers by
heart.  It's more efficient, because there's no need to manage lots of
ongoing battles.  However, there are endless numbers of situations
where this basic model is unsatisfactory, so let's move on to the
available enhancements.

   The basic parameter for the firing actions is `range' of the unit,
which is the greatest reach possible.  You can also set a `range-min',
which is useful for ballistic missiles, certain kinds of artillery, and
magic spells that can't be used for close-in fighting; you can't fire
at a unit that is less than `range-min' cells away.

   Also, you can define how transports and occupants affect each other
in combat.  The effects can be both positive and negative, and extend
both from occupants to their transport and from the transport to its
occupants.  The table `transport-protection' defines the percentage of
hit damage (by any unit type) that gets passed through to each occupant.
If 0, then the transport is perfect protection. If 100, then each
occupant gets the same hit as the transport did.  [Ideally, protection
is a prorating on a table value from occupant vs attacking unit.]  Note
that an occupant cannot be attacked directly from outside its transport.

   If you want to make combat dependent on having a supply of ammo, use
the tables `hits-with' and `hit-by'.  The material type need not be
explicitly designated as ammo, but both the hitting and hit units must
agree that the same type is effectual (we assume that the attacking
unit is smart enough not to use material types that have no effect on
the target unit).

   [need a combat-supply usage in addition]

* Menu:

* Capture::
* Detonation::


File: xcdesign.info,  Node: Capture,  Next: Detonation,  Up: Unit Combat

2.11.1 Capture
--------------

Capture is both a distinct action type and a possible consequence of
normal combat.  As an action, it is useful for both "bloodless"
captures and the collecting of objects from a dungeon floor.

   To allow explicit attempts to capture, set `acp-to-capture' to 1 or
more.

   Whether the capture attempt is explicit or a consequence of combat,
its basic probability of success is derived from the table
`capture-chance'.  If the unit being captured is independent, there is
a separate table `independent-capture-chance'; if its value is the
default of -1, then the value of `capture-chance' will be used instead.

   For capture attempts that are going to succeed, you can allow the
victim a chance to wreck itself first, by setting `scuttle-chance'.

   The main effect of capture is simply to change the side of the unit
that was captured.  If the unit cannot be on the capturing side, then
it will vanish instead.  In any case, the occupants will also be
captured or vanish, although you give them a chance to escape first via
`occupant-escape-chance'.  They will also attempt to scuttle themselves
if possible.

   You can also require a sacrifice from the capturing unit, via the
table `hp-to-garrison'.  This is the number of hp that will be taken
from the capturing unit.  You can set it to the unit's `hp-max' to make
it disappear entirely.  Although this table is inspired by realism, it
can also serve a pragmatic purpose, namely to prevent a single unit from
capturing an entire country without being affected at all!  You should
set this table according to the "feel" you want for the game, since it
can have a major effect on speed and pacing of the play.

   As with normal combat, the experience of both the capturing and
captured unit may change.  For the capturing unit, this is a gain
defined by `cxp-per-capture', while the effect on the capturing unit is
set by `cxp-on-capture-effect', which is a multiplier (defaulting to
100) that may increase or decrease experience.  In practice, a decrease
is more realistic, representing perhaps the replacement of ship or
airplane crews, although a increase might be more appropriate for
mercenaries whose response to capture is simply to go to work for the
new bosses!


File: xcdesign.info,  Node: Detonation,  Prev: Capture,  Up: Unit Combat

2.11.2 Detonation
-----------------

Detonation is both a type of action `detonate' and an automatic
behavior.

   Detonation can damage both the detonating unit (though it need not)
and any units around its point of detonation, which may or may not be
its location.  You set it up by defining `acp-to-detonate' to one or
more, set `hp-per-detonation' to express the amount of damage done to
the detonating unit, then fill in the detonation damage tables
`detonation-damage-at' and `detonation-damage-adjacent' to say how
badly each type of nearby unit will be hit.  You can define the exact
radius of effect via `detonation-range'.  The effects on occupants of
nearby units will be adjusted according to the same protection/ablation
tables as for combat.

   You can also set detonation to trigger on various kinds of events,
such as damage to the detonating unit (`detonate-on-hit', death of the
detonating units (`detonate-on-death'), impending capture
(`detonate-on-capture'), and proximity of certain types of units
(`detonate-on-approach').  You can also set a chance that a unit will
detonate spontaneously, via `detonation-accident-chance'.

   In order to model the catastrophic effects of the worst explosives,
you can set `terrain-damage' to indicate how terrain types will change.

   A minefield could be implemented by defining a detonating unit that
loses some small percentage of its hp every time a unit hits it, while
hitting the other unit automatically.

   A simple trap would auto-detonate only once, then change to a "sprung
trap" type.  Then the right kind of unit could come along and do a
change type action to reset it.


File: xcdesign.info,  Node: Unit Manipulation,  Next: Material Manipulation,  Prev: Unit Combat,  Up: Game Design

2.12 Unit Manipulation
======================

The actions in this group are a mixed bag of manipulations.  If they
need to be in your game, then the need will be obvious, otherwise they
are pretty much optional.

* Menu:

* Transferring Unit Parts Action::
* Changing Side::
* Changing Type::
* Disbanding::


File: xcdesign.info,  Node: Transferring Unit Parts Action,  Next: Changing Side,  Up: Unit Manipulation

2.12.1 Transferring Unit Parts Action
-------------------------------------

Any unit whose `parts-max' is greater than the default of 1 is a
multi-part unit, and its hp denotes size rather than amount of damage.
Armies and fleets are two kinds of units which can be usefully defined
as multi-part.

   Players will very often want to merge or detach parts of a multi-part
unit, and there is an action `transfer-part' provided for that.  You
can control the cost of the action by setting `acp-to-transfer-part'.


File: xcdesign.info,  Node: Changing Side,  Next: Changing Type,  Prev: Transferring Unit Parts Action,  Up: Unit Manipulation

2.12.2 Changing Side
--------------------

Side changing is like capturing, but players can only do it to units
that they control.  The action is `change-side', and you enable by
setting `acp-to-change-side' to 1 or more.  This will also enable side
changing for units that cannot normally act.

   Side changing is especially useful for alliances in multi-player
games, so it should usually be enabled.  On the other hand, it should
not be too cheap; you should consider what side changing really means
in the game's context.

   For instance, even in the close British/American alliance during
WWII, armies never actually changed sides; British ground units were
always British, and American ground units always American.  On the
other hand, ships and bases could be traded back and forth with only a
cost in time and expense.


File: xcdesign.info,  Node: Changing Type,  Next: Disbanding,  Prev: Changing Side,  Up: Unit Manipulation

2.12.3 Changing Type
--------------------

In some games, it will be useful to have a notion of promotion or
upgrade for units.  You can implement this by allowing players to do a
`change-type' action.

   You enable this via the `acp-to-change-type' table.


File: xcdesign.info,  Node: Disbanding,  Prev: Changing Type,  Up: Unit Manipulation

2.12.4 Disbanding
-----------------

Sometimes a player will want to get rid of a unit, perhaps because some
type has been overproduced and is tying up valuable resources, or to
prevent it from falling into enemy hands.

   You can allow this by setting `acp-to-disband' to 1 or more.

   You can control the rate of disbanding with `hp-per-disband'.  You
may, for instance, want to allow the deliberate destruction of large
units, such as battleships, but you don't necessarily want disbanding
to be a convenient way of preventing their capture.  Setting
`hp-to-disband' so as to require several turns to get rid of a unit
will accomplish this.  The table `supply-per-disband' will allow you to
govern the rate of recovery of the unit's supplies during the
disbanding process.

   It is also possible to make disbanding a way to recover materials
that were consumed in the construction of the unit, by using the table
`recycleable-material'.  Care should be taken that creation and
disbanding of units is not a convenient way to manufacture lots of a
material; players will use the loophole if it exists!

   It should usually not be possible to disband something large like a
city, otherwise a clever player might try to eliminate it as a
strategic target, but most mobile units should be easily disbanded.
This is especially helpful in an "construction spiral" game, where the
winning player(s) can accumulate large numbers of useless units.


File: xcdesign.info,  Node: Material Manipulation,  Next: Terrain Manipulation,  Prev: Unit Manipulation,  Up: Game Design

2.13 Material Manipulation
==========================

You can allow players to produce materials by explicit action, and you
can control how they transfer materials between units.

   Note that you can usually have a reasonable game without requiring
all the players to become shipping clerks.  The automated production
and transfer parameters (see xxx) are almost always sufficient for a
game.  Explicit action should be limited to games where material
limitations are so severe that they impact strategy directly, and
players have to make hard choices between producing materials and doing
other actions, on a turn-by-turn basis.

   You can define "stevedore" units by setting both rate and acp such
that the u1 -> stevedore -> u2 transfer is faster and cheaper than the
basic u1 -> u2 rate.  Then players can use the stevedores to speed up
transfers.


File: xcdesign.info,  Node: Terrain Manipulation,  Next: Vision Parameters,  Prev: Material Manipulation,  Up: Game Design

2.14 Terrain Manipulation
=========================

In a few games, you will want to let players alter the terrain.  This
needs to be done judiciously, since a cell of terrain generally
represents a vast area, and the simulated time in Xconq is generally
too short for major terraforming operations.  However, building bridges
and digging moats can be reasonable additions to a game.

   Since actions are always completed quickly, and there is no concept
of "partly modified terrain", you will probably have to come up with a
trick to make terrain modification be slow.  One way is make the acp
(or material?) cost very high.  Another way is to make the alteration
happen by removing a material, such as clearcutting a forest, then
letting the action make the actual change to clear terrain.


File: xcdesign.info,  Node: Vision Parameters,  Next: Designing Backdrop Weather,  Prev: Terrain Manipulation,  Up: Game Design

2.15 Vision Parameters
======================

Vision is an important part of Xconq.  Information need not come for
free in your game design, and you can design the parameters to control
how much players can get.  The possibilities range from total knowledge
as in board games, where nothing is secret except the enemy's heart, to
games where much of the play hinges on who knows what, and when.

   When deciding what visibility model to use, keep in mind that one of
the hallmarks of games in the Xconq genre is the exploration of the
world during the initial phase of a game.  Not only do many players
enjoy the adventure of exploring a new world, but the progress of
exploration servers as a handy note-taking device for players searching
for other players.  If all the terrain starts out visible, but the
location of the enemy is unknown, it can be difficult to keep track of
what's been examined!

* Menu:

* Seeing All::
* Coverage::
* Setting the Initial View::
* Vision Range::


File: xcdesign.info,  Node: Seeing All,  Next: Coverage,  Up: Vision Parameters

2.15.1 Seeing All
-----------------

The simplest thing to do is to set `see-all' to `true'.  Then every
player sees all the terrain, everybody's units, everybody's occupants,
the whole world and everything in it.  This makes Xconq like a
conventional video or board game, which is sometimes just what you
want.  Also, since the view matches the world, the game is simpler for
players, who need not concern themselves with possibly out-of-date
information.  Finally, `see-all' is more efficient in time and space,
since the general visibility calculations need never be done or
recorded.  Many games include `see-all' as one of their variants.

   You may also find `see-all' to be a useful game debugging aid, since
you can watch what is happening everywhere in the world.  But, remember
that any AIs will most likely adjust their strategy and not bother with
patrolling or guesswork about the enemy, and you won't be able to debug
the other viewing parameters either!


File: xcdesign.info,  Node: Coverage,  Next: Setting the Initial View,  Prev: Seeing All,  Up: Vision Parameters

2.15.2 Coverage
---------------

Still, much of the fun in Xconq is the potential for surprise.  The
theory of visibility in Xconq is that each side has a layer of
coverage, which basically just counts the eyeballs looking at each cell.
As your units move around, the coverage in each cell goes up and down.
Any cell with a coverage of zero is not currently being viewed by any of
the side's units.

   The unit property `see-always' is useful for units like towns, which
are unlikely to disappear secretly.

   These two parameters apply recursively, so for instance a city could
be `see-always' and `see-occupants', while a building in the city is
`see-always' and not `see-occupants', with the net effect that units
inside a city can be seen by everybody, but not when they enter a
building.


File: xcdesign.info,  Node: Setting the Initial View,  Next: Vision Range,  Prev: Coverage,  Up: Vision Parameters

2.15.3 Setting the Initial View
-------------------------------

The initial view represents the knowledge assumed to have been gathered
over the period of time preceding the game.  By default, players start
out knowing only the immediate vicinity of their initial units and
people.

   One way to change this is to set `terrain-seen' to true, or to add
it as an available variant for the game; in either case, all terrain in
the world becomes known to all sides.  This is good for realism,
especially for real-world games since about 1900, when very little of
the Earth remained unexplored.  `terrain-seen' can radically change the
dynamics of a game; for instance, the standard game changes from
explore-and-conquer to all-out combat.

   If making everything visible is too much, Xconq lets you set a
radius `initial-seen-radius' around each initial unit, within which the
unit's side knows everything.  This is useful if your initial units are
somewhat scattered, so as to avoid gaps of unknown terrain in between.
Also, any people on your side view both their cell and all the adjacent
cells.

   Once you've chosen how much terrain is visible, you can control which
units are visible.  The `see-always' property mentioned above affects
initial visibility, but in addition there is `already-seen' and
`already-seen-independent', which apply to units on sides or on no
side, respectively.  These properties are percentage chances, so you
can randomize how many are known.  For example, in peacetime everybody
typically knows the location of a navy's surface ships, but when the war
starts they scatter to sea and operate more securely, so for those
`see-always' should be 0 and `already-seen' should be 100.  However,
submarines are always more secretive, and perhaps only 1/4 are known to
other sides, so an `already-seen' of 25 makes sense.  Another example
might be monster's lairs, whose positions might be known by reputation,
but if something happens to them, the news does not get flashed around
the world!


File: xcdesign.info,  Node: Vision Range,  Prev: Setting the Initial View,  Up: Vision Parameters

2.15.4 Vision Range
-------------------

The default vision range (`vision-range') is 1, which basically means
that a unit can see into adjacent cells but no further.  You can set
this to higher values, which is useful for tactical- and person-level
games with line-of-sight (LOS) rules.

   You can also set the vision range of a unit to 0, which means that it
can only see things in its own cell.  However, as a special case, when
such a unit enters a new cell, Xconq will show the terrain of each
adjacent cell, but not any units that might be present.  This is so
players can decide which way to move without having to plunge blindly
into unknown terrain or do some sort of awkward "adjacent cell
examination" action before moving.  This only provides information
about terrain and units that are seen if the terrain is seen.


File: xcdesign.info,  Node: Designing Backdrop Weather,  Next: Designing Backdrop Economy,  Prev: Vision Parameters,  Up: Game Design

2.16 Designing Backdrop Weather
===============================

[The four temperature extremes are independent of each other, so you
can make higher latitude temperatures vary drastically with the season,
while equatorial temperatures are much more stable; or vice versa.

   Average temperature usually varies more slowly over some kinds of
terrain than others.  For instance, oceanic circulation moderates
temperature swings in terrain that is near open ocean.]


File: xcdesign.info,  Node: Designing Backdrop Economy,  Next: Adding Random Events,  Prev: Designing Backdrop Weather,  Up: Game Design

2.17 Designing Backdrop Economy
===============================

Economy in Xconq means pushing materials around.  So if you want an
economy in your game design, you have to define at least one type of
material.  To define the economy, you have to decide where materials
come from, how they get moved around, and how they get used up.

* Menu:

* Creating Materials::
* Movement of Materials::
* Consuming Materials::


File: xcdesign.info,  Node: Creating Materials,  Next: Movement of Materials,  Up: Designing Backdrop Economy

2.17.1 Creating Materials
-------------------------

Materials come into existence by being placed in units or terrain
during setup, by being produced by units or terrain, and by appearing
in newly-created units.


File: xcdesign.info,  Node: Movement of Materials,  Next: Consuming Materials,  Prev: Creating Materials,  Up: Designing Backdrop Economy

2.17.2 Movement of Materials
----------------------------

Once in existence, players can move materials around by explicit action.
You can also define automated material movement that uses supply and
demand.  The tables `in-length' and `out-length' control the distance
over which materials will move each turn.


File: xcdesign.info,  Node: Consuming Materials,  Prev: Movement of Materials,  Up: Designing Backdrop Economy

2.17.3 Consuming Materials
--------------------------

Materials exist to be consumed (unless they are relevant to a
scorekeeper).  You can set how much each kind of action uses, as well
as how much is needed as a prerequisite, sort of like a catalyst.  You
can also set consumption due to existence alone, plus what happens to a
unit when its supply of a material runs out.


File: xcdesign.info,  Node: Adding Random Events,  Next: Designing the Interface,  Prev: Designing Backdrop Economy,  Up: Game Design

2.18 Adding Random Events
=========================

What simulation game would be complete without random events?  Random
events are handled somewhat similarly to synthesis methods, in that you
set the value of the variable `random-events' to a list of the methods
that you want run.  Note that you must still ensure that the
probabilities for the events on your list are nonzero!

   Superficially, random events just introduce some unpredictability
into a game.  However, adding it just for its own sake is not a good
idea; in the worst case, the game becomes the infamous "dice-rolling
contest", where nothing matters except luck.  Random events are more
valuable when they introduce risk, and players have to balance that
risk against their goals.  As an example, random losses of cities in
the standard game would be pointless, since players have to have them,
and there would be a chance that all of a player's cities would
disappear, causing the player to lose for no good reason at all.  On
the other hand, the chance of losing an expensive capital ship in
shallow coastal waters is enough to motivate the player to keep them
well out to sea.

   In the past, bugs or unexpected behavior in random event routines
have resulted in hard-to-reproduce problems.  For the sake of
debugging, you should test the game with random event probabilities set
very high, perhaps as a variant so it can still be played normally.

* Menu:

* Accident Parameters::
* Attrition Parameters::
* Revolt Parameters::
* Surrender Parameters::


File: xcdesign.info,  Node: Accident Parameters,  Next: Attrition Parameters,  Up: Adding Random Events

2.18.1 Accident Parameters
--------------------------

The name of the accident method is `accidents-in-terrain'.  Accidents
should be restricted to definite hazardous situations, to go along with
movement constraints - for instance, carriers and battleships in
shallow water should have a small chance to hit a rock and sink.

   You can specify two kinds of accident; a damaging accident, which
hits the unit as if it were in combat, or a vanishing accident, in
which the unit disapppears instantly.

   Damaging accidents occur according to the `accident-hit-chance'
table, and damage the unit according to `accident-damage'.  The
interpretation of these is similar to their combat counterparts.  The
`accident-vanish-chance' table sets the probability for the unit to
simply vanish without a trace.


File: xcdesign.info,  Node: Attrition Parameters,  Next: Revolt Parameters,  Prev: Accident Parameters,  Up: Adding Random Events

2.18.2 Attrition Parameters
---------------------------

Attrition is a sort of higher-probability/lower-damage type of
accident.  It is useful for armies in hostile terrain, where deserters
and casualties slowly reduce its strength.

   Attrition can be useful for "aging" a unit, if you need to keep the
unit from being around too long.


File: xcdesign.info,  Node: Revolt Parameters,  Next: Surrender Parameters,  Prev: Attrition Parameters,  Up: Adding Random Events

2.18.3 Revolt Parameters
------------------------

Revolts are spontaneous changes of side, independent of any other
consideration.  Since there is no way to protect against this, the
chance should usually be very small, less than .01; even a small chance
of will cause players to maintain reserves just in case.


File: xcdesign.info,  Node: Surrender Parameters,  Prev: Revolt Parameters,  Up: Adding Random Events

2.18.4 Surrender Parameters
---------------------------

The method's name is `units-surrender'; when it runs, it checks each
unit to see if it is within `surrender-range' of a unit on an
unfriendly side, and if the `surrender-chance' occurs, then the unit
will change to the side of the other unit.  Occupants will also
evaluate their surrender/scuttle/escape chances, and behave accordingly.


File: xcdesign.info,  Node: Designing the Interface,  Next: Designing the Text,  Prev: Adding Random Events,  Up: Game Design

2.19 Designing the Interface
============================

So far, the game design machinery has been focused on semantics.  The
other part of the game design defines how it actually appears to the
players.  This part of the design can be more loosely designed, which
is good, because you cannot guarantee that your game design will only
ever be run with a particular interface, and there is a wide variety of
interfaces.  You could, for instance, define an elaborate set of color
graphical icons and patterns, only to find that most of your players
only have black-and-white displays.  Xconq itself will always be able
to cope with your omissions, but it will be forced to synthesize
inferior substitutes.

   Game designs have three general categories of interface elements
that they can specify: text, graphics, and animations.  Text elements
are just strings describing objects and events in a readable form,
while graphics consist of small icons and patterns primarily
representing units and terrain.  Animations are used to illustrate
events as they happen, and may include sounds.


File: xcdesign.info,  Node: Designing the Text,  Next: Designing the Graphics,  Prev: Designing the Interface,  Up: Game Design

2.20 Designing the Text
=======================

Although Xconq is primarily a graphical game system, it is complex
enough that the graphics alone are insufficient to describe what is
going on.

   All text that players see is issued by "text generators", which are
objects that, when given appropriate inputs, produce text fragments
that can be used by the interface to produce a textual display.  Each
text generator has a number of parameters that may be used to select
one of several rules [etc]

* Menu:

* Describing Objects::
* Describing Events::
* Generating Names::
* Grammar Examples::


File: xcdesign.info,  Node: Describing Objects,  Next: Describing Events,  Up: Designing the Text

2.20.1 Describing Objects
-------------------------

[fill in]


File: xcdesign.info,  Node: Describing Events,  Next: Generating Names,  Prev: Describing Objects,  Up: Designing the Text

2.20.2 Describing Events
------------------------

[fill in]


File: xcdesign.info,  Node: Generating Names,  Next: Grammar Examples,  Prev: Describing Events,  Up: Designing the Text

2.20.3 Generating Names
-----------------------

One of Xconq's special features is its extensive machinery for
generating names of things.  You can generate names for sides, units,
and geographical features.  The possibilities range from a simple list
of strings up to context-free grammars and arbitrary code modules.
Naming happens throughout the game, as nameable objects are created, but
is mostly done during initialization.


File: xcdesign.info,  Node: Grammar Examples,  Prev: Generating Names,  Up: Designing the Text

2.20.4 Grammar Examples
-----------------------

Here is a very simple grammar:
     (namer (grammar root 40
       (root (or 1 (the animal in the thing)))
       (animal (or cat dog sheep))
       (thing (or hat umbrella fold))
       ))
   It makes phrases like `"the cat in the hat"', `"the dog in the
umbrella"', and `"the sheep in the hat"'.

   This example is more realistic:
     ;;; German-like place name generator.

     ;;; Conventional combos most common, random syllables rare.
     ;;; Needs more conventional words to combine?

     (namer german-place-names (grammar root 50
       (root (or 95 (name)
                  5 ("Bad " name)
                  ))
       (name (or 40 (prefix suffix)
                 20 (both suffix)
                 20 (prefix both)
                  5 (prefix both suffix)
                 10 (syll suffix)
                 10 (prefix syll suffix)
             ))
       (prefix (or
             schwarz blau grun gelb rot roth braun weiss
             wolf neu alt alten salz hoch uber nieder gross klein
             west ost nord sud
             ;; from real names
             frank dussel chem stras mut
             ))
       (suffix (or
             dorf torf heim holz hof burg stedt haus hausen
             bruck brueck bach tal thal furt
             ;; these aren't so great
             ach ingen nitz
             ))
       (both (or
             feld stadt stein see schwein schloss wasser eisen berg
             ))
       ;; Generate random syllables
       (syll (or 40 (startsyll vowel endsyll) 5 (vowel endsyll)))
       (startsyll (or 30 startcons 10 startdiph))
       (startcons (or b k d f g l m n r 5 s 3 t))
       (startdiph (or bl kl fl gl 5 sl 3 sch 2 schl
                      br dr kr fr gr 2 schr 3 tr 2 th 2 thr))
       (vowel (or 6 a ae 2 au 5 e 2 ei 2 ie 6 i 3 o oe 2 u ue))
       (endsyll (or 4 b 5 l 3 n 4 r 4 t
                    bs ls ns rs ts 3 ch 3 ck
                    lb lck lch lk lz ln lt lth ltz
                    rb rck rch rn rt rth rtz
                    ss sz 2 th tz
       	))
       ))
   This generator usually takes normal German words and glues a couple
together, making names like `"Schwarzburg"', `"Nordbruck"', and `"Bad
Salzwasser"', but it will occasionally make a completely random
syllable using common German phonemes, then glue it into a name,
resulting in names like `"Biefeld"' and `"Salzgloelthach"'.  Yes, that
last one is unpronounceable even for Germans, but the generator doesn't
know that!

   Since there is no special handling to ensure non-garbled names, it
generally does not work particularly well to try to build names from
vowels and consonants.  Either random selection from a list or putting
together syllables seems to do better, with perhaps a single totally
random syllable thrown in.  Don't forget that this is a generator, not a
recognizer or parser, so you don't have to be able to handle every
possible name; just enough to make an interesting variety.

   Recursive rules, where a symbol expands into a sequence mentioning
that same symbol, will work, but they are not recommended.  Although the
generator has a builtin limiter to keep from looping forever, in
general there is no way to avoid getting awful names like
`"Feldbruckbruckbruck"'.  Instead, you can just add extra rules, one
for each desired length, so for instance you have a rule for 2-syllable
names, one for 3-syllable names, one for 4 syllables, etc.  Another
advantage is that you can set the probability of each length of name
separately, and thus lower the probability of longer names, so that
they only appear once in a while and you save the poor players from
being continuously tongue-tangled!


File: xcdesign.info,  Node: Designing the Graphics,  Next: Game Module Organization,  Prev: Designing the Text,  Up: Game Design

2.21 Designing the Graphics
===========================

Xconq is fundamentally a graphical game; but fortunately, you don't
have to do gnarly graphics hacking to get the pretty pictures!  The
basic graphics handling is built into the interface subroutines of
Xconq.  What you do have to do is to choose or design the basic images.

   Xconq will always attempt to generate some sort of default display
for your new game design, but it's likely to be pretty ugly.  So your
goal here is just to make the display look good.  First off you should
decide about the overall appearance.  Do you want things to be generally
light or dark?  Garish or subtle?  Conventional or exotic?  This is a
good time to cruise the image libraries and to look at the graphics of
other games.  Sometimes the theme decides a lot for you - how could you
display anything other than a red star on a Soviet tank?  You also need
to think about whether you want to concentrate on b/w or color displays,
although again Xconq will try to do something reasonable for both.

   You have to choose three sets of images: terrain patterns or images,
unit icons, and side emblems.  The terrain patterns have to tile
properly, since they may be used to fill in large areas, while both unit
icons and side emblems are single icons.  You can optionally choose
solid colors for terrain, and to "colorize" unit icons and side emblems.

   Once you have chosen and specified a set of images, you have to try
them out in various combinations in real games.  What you'll most likely
discover is that they don't always mix like you imagined.  That
cool-looking emblem for a side disappears against the background of
space, or two unit icons are nearly indistinguishable on the map.  At
this point, you have to start making some choices.  Either substitute
some different images, or design new ones of your own.

   Color choices are tricky.  Again, the total effect can be quite
different from what you imagined, plus you should be careful about the
variety of displays that your game runs on, or you may be getting
complaints about how your "olive" more closely resembles "puke gray"!

   Here is an example of unit icons:
     (add (infantry town city) image-name ("soldiers" "town20" "city20"))
   In general, an icon name should describe the literal appearance of
the image, instead of the type that you want it to represent.  The
`"soldiers"' icon, for instance, just shows a row of soldiers; in one
game the icon can be used to represent infantry, in another, armies in
general, and in another, the national guard.  There is an `"infantry"'
image also, but it is the standard "crossed bandoliers" symbol, and is
really only sensible for specialized military games.

   Here is an example of a terrain pattern:
     (terrain-type plains
       (color "green") (image-name "plains") (char "+")
       )

   The `"plains"' is defined in `terrain.imf', as basically a blank 8x8
tile with two pixels turned on, which textures things somewhat:
     (imf "plains" ((8 8 tile)
       (color (pixel-size 1) (row-bytes 1)
        (palette (0 7969 46995 5169) (1 0 25775 4528))
        "00/40/00/00/00/04/00/00")
       (mono "00/40/00/00/00/04/00/00")))

   For extra fine control on color displays, you can also set the
colors of unseen terrain and the grid separating cells, via the globals
`grid-color' and `unseen-color'.

   Note that some display systems (such as the X Window System) allow
users to customize most or all of their colors, so individuals may
override your choices.  Not much you can do about that though!

* Menu:

* Image Format::
* Image Design Tools::
* Image Design Hints::


File: xcdesign.info,  Node: Image Format,  Next: Image Design Tools,  Up: Designing the Graphics

2.21.1 Image Format
-------------------

     (imf "example" ((8 8) (mono "0011223344556677")))

   [describe when fleshed out]

   It may happen that you will want to add an image that is similar to
an existing image.  While you can replace the existing image, you may
alter the appearance of some other game for the worse (perhaps its image
colors have been designed to work together).

   The first rule of image naming is to choose the name to describe the
image literally.  For instance, you may have designed an anchor image
that is to represent a port.  However, you should name the image
"anchor" and not "port", so that it may be used in other games.  Second,
if the image should have a difference appearance in different eras or
contexts, you should append that as a qualifier to the basic image name;
so a soldier image from the American Civil War era (1861-1865) would be
"soldier-acw".

   Some images are more symbolic than pictorial, such as standard
military symbology.  In those cases the order should be
function-size-individual, so as to get images with names like `inf-bn'
for an infantry battalion or `armor-div-7th' for an image representing
the 7th Armored Division specifically.

   If you want your image to be specific to a particular game, and not
to share with any other games (or be affected by image changes to
accommodate them), prefix your image with the name or abbreviation for
the game.

   To summarize, here are the recommended name formats:
     [<game>-]<picture>[-<era>]
     [<game>-]<function>[-<size>][-<era>][-<side/individual>]

   Finally, if your image has no obvious way to distinguish it, then you
must append a distinguishing number.  So multiple generic dragon images
are "dragon", "dragon-2", "dragon-3", and so forth.

   None of these naming rules are enforced by the software; they exist
to bring some semblance of order to a large and complicated image
library.


File: xcdesign.info,  Node: Image Design Tools,  Next: Image Design Hints,  Prev: Image Format,  Up: Designing the Graphics

2.21.2 Image Design Tools
-------------------------

Whether you use platform-specific paint/draw programs, or you collect
images in other formats, you will need to translate these into imf
format, and then integrate into the existing library.  Typically, each
platform includes a tools to help with this; for instance, the Unix
program `x2imf' reads X11 bitmap files and produces imf files, while
the Mac program `IMFApp' allows both previewing of images and
translation between imf files and Mac resources.

   As an additional aid, the program `imf2imf' is a Unix program that
transforms a single imf file with many images into a set of files each
with one image, and vice versa.  This is useful when merging sets of
images together:

     imf2imf foo.imf --explode -o tmp

     <copy other files into tmp dir>

     imf2imf tmp/*.imf >newfoo.imf


File: xcdesign.info,  Node: Image Design Hints,  Prev: Image Design Tools,  Up: Designing the Graphics

2.21.3 Image Design Hints
-------------------------

The design of each graphical image can and should be somewhat
independent of the basic game design; this allows for reuse of pictures.

   The first thing you should do is to check the image library on your
machine.  The image you're looking for may already be there, but perhaps
under a different name.  Even if you don't find it, you may notice an
image that is close enough to be a good starting point.  The Xconq
image library presently includes hundreds of images, so the chances are
pretty good that you'll find something useful.

   The second thing to do is to look around for images in some other
format, and to massage them into a usable form.

   Designing images from scratch should be your last resort.  Designing
good images and patterns is a specialized and demanding category of
artwork that I'm not going to go into here.  My best advice is to learn
from the pros, and don't be afraid to experiment.


File: xcdesign.info,  Node: Game Module Organization,  Next: Building New Games,  Prev: Designing the Graphics,  Up: Game Design

2.22 Game Module Organization
=============================

Each separate file is known as a "game module" or just "module".  A
module has a name, displayed name, an advertising-style blurb, a
version, and designer notes.

   This is an example of an elaborately-declared game module with no
actual content:
     (game-module "foobar"
       (title "Foo of Bar")
       (blurb "An exciting game with lots of cliffhanging suspense")
       (version "1.3")
       (program-version (>= "7.0.3"))
       ;; other properties?
       (complete-game true)
     )

     ;;; contents here

     (game-module (notes (
       "This is just a sample game."
       ""
       "It's not really as interesting as the blurb makes out."
       )))

     (game-module (design-notes (
       "This is commentary addressed to other designers."
       "Also a good place to mention things to work on."
       )))
   The `notes' and `design-notes' could have been supplied with the
first `game-module' declaration, but in practice, putting the player
and designer notes at the end of the file keeps them out of the way.
You can supply any number of `game-module' declarations in a file.
Only the first need include a name.

   The game module format is only loosely structured.  In general,
anything that you might want to reuse or combine in different ways
should be a separate module.  Good candidates include text generators
and maps of real terrain.  Unfortunately, they don't always
mix-and-match as well as you might like!

   The following are the generally preferred module names:

   Terrain-only modules should be named `t-'xxx.

   Lists of units should be named `u-'xxx or `ob-'xxx (for "order of
battle").

   Name generators should be name `ng-'xxx.

   When supplying a year in the module name, use four digits, unless
the rest of the name makes the century clear (WWII scenarios are pretty
much guaranteed to be in the 20th century!).


File: xcdesign.info,  Node: Building New Games,  Next: Debugging Designs,  Prev: Game Module Organization,  Up: Game Design

2.23 Building New Games
=======================

There are at least three ways to make a new game design: use Xconq
commands to "play" a game and then save it, create and text-edit the
text files defining a game, or write and run special-purpose programs
that create games.  A combination of these techniques will likely prove
the most useful, since each alone has both strengths and weaknesses.
For instance, text editing may seem like a crude approach, but is the
only way to produce certain types of scenarios, and text editors have
many facilities (such as regular expression replacement) not directly
available in Xconq.  On the other hand, maintenance of the correct
transport/occupant relationships between units is hard to do while
editing text, but comes for free when using Xconq itself.

* Menu:

* Building Scenarios::
* Designer Mode::
* Saving Scenarios::
* Preparing a Game for Use::
* Installing a Game::
* Playtesting::
* Safety::
* Balance::
* Complexity::
* Combinations::


File: xcdesign.info,  Node: Building Scenarios,  Next: Designer Mode,  Up: Building New Games

2.23.1 Building Scenarios
-------------------------

The easiest way to customize Xconq is to build a scenario.  A scenario
is basically a saved game from which irrelevant details, such as the
list of players, has been omitted.  Typically this will include
tweaking details, removing random irrelevant junk, and generally tuning
things.

   One way to do this would just be to start a normal game, save it, and
then dig through the saved game and edit it, since the saved game is
itself a game module.  Sometimes this is easy, more likely it will be
quite hard and error-prone.  A better way is available, in the form of
"designer mode".


File: xcdesign.info,  Node: Designer Mode,  Next: Saving Scenarios,  Prev: Building Scenarios,  Up: Building New Games

2.23.2 Designer Mode
--------------------

There are two ways to get into designer mode; one is to start up a game
with the appropriate option (`-design' under Unix), which makes every
player with a display a designer, the other is to switch on a flag
after the game has started.  Being a designer is a property of a side,
so in theory a game could have a designer and several other human
players, or even multiple designers (this might be useful in having
assistants to help with the construction of large scenarios, or just to
have displays open to each side's view of the scenario).  AIs
effectively sit out the game while designers are present.

   Designer mode enables an additional set of commands on the menu or
map control panel, as well as removing some restrictions on the use of
normal commands.  It also enables more elaborate game saving machinery,
so you can save only the parts of a game that you want to make into a
scenario.

   Modifications to normal commands include the permission to look at
and do any command on any unit, including independents and units
belonging to other sides.  For instance, any unit can be renamed at any
time by any designer in the game.  The modications include the
following:

   * Move commands can put any unit at any destination instantly.

   * Any unit can be put on any side.

   * Any unit can be disbanded instantly.

   * Any terrain can changed to any type.

   Some interfaces may also provide additional tool palettes and the
like.


File: xcdesign.info,  Node: Saving Scenarios,  Next: Preparing a Game for Use,  Prev: Designer Mode,  Up: Building New Games

2.23.3 Saving Scenarios
-----------------------

If you're not in designer mode, then saving the game will save
absolutely everything.  In designer mode, the interface should ask you
what parts of the game you want to save, and what to name the module.

   If you don't save everything, then you should start up another game
just to confirm that you got what you wanted, before shutting down the
Xconq that you're designing with.  Sometimes you won't have saved what
you thought you did...  It's also a good idea to keep a backup copy of
data, especially the indecipherable area layers; use the nesting
comments ` #| |# ' around the old stuff, only delete when you're sure
it's no longer of interest.


File: xcdesign.info,  Node: Preparing a Game for Use,  Next: Installing a Game,  Prev: Saving Scenarios,  Up: Building New Games

2.23.4 Preparing a Game for Use
-------------------------------

Once you've constructed a game, you should bring it to a state where it
can be given to other Xconq players.  I recommend copying a standard
software release strategy.  This means documenting how to play the game,
documenting how it works internally, removing unused junk and dubious
features, simplifying where possible, resolving open issues if possible,
documenting them as known problems if not.  This gets you to the point
of having an "alpha" or "beta" version (the terms are not precise!).
These can be given to other people for testing, but should be clearly
identified as test versions, because your testers may pass copies along
to others without you knowing about it.  After some playtesting (see
below), edit your game into its final form, call it 1.0 and release it
to the world!

   After you release your game, you may get some feedback about
unanticipated problems.  When you resolve these, and want to make a new
release, be sure to give it a distinct version number.  This will be
important to deciding whether subsequent complaints are about your new
release or some older one.  If you always put the version number into
the `version' property of the `game-module' form, then it will be
displayed to players when they ask for help on the game.


File: xcdesign.info,  Node: Installing a Game,  Next: Playtesting,  Prev: Preparing a Game for Use,  Up: Building New Games

2.23.5 Installing a Game
------------------------

Once the scenario is constructed and saved, you can install it in the
library and otherwise do as you like with it.  See the interface
documents for platform-specific installation details; in general, just
copying the files into the `lib' directory will suffice.


File: xcdesign.info,  Node: Playtesting,  Next: Safety,  Prev: Installing a Game,  Up: Building New Games

2.23.6 Playtesting
------------------

Playtesting is extremely important, even for simple game!  You should
try as many combinations of startup options as possible - for instance,
the combo of two humans and one machine might reveal a peculiarity that
is not observed in a two-person game.  You can solve many problems by
adding more restrictions.  Since the scenario is your concept, you are
free to make whatever decisions are necessary to realize that concept;
if somebody complains, they are free to make their own designs.

   Playtesting is the time when you may have to sacrifice realism and
favorite theories for playability.  Listen to and watch yourself and
your testers as the game is played.  For instance, you might have
included a city out in the boonies, but in the game it never does
anybody much good, while still requiring some amount of attention
regularly.  Lose it.

   Game startup can be confusing to players if they all start out with
lots of units needing to be told what to do.  One solution is to put
most units on automatic behaviors that expire in a turn or two, so that
novices gradually hear from all the units, while experts can still
override right from the outset.  Another approach is to make units
independent and allow them to be captured early on.  Still another
approach is to make units come in as reinforcements at preset times and
locations.  Since players will form their strongest impressions of a
game based on its appearance at startup, attention to this will pay off.


File: xcdesign.info,  Node: Safety,  Next: Balance,  Prev: Playtesting,  Up: Building New Games

2.23.7 Safety
-------------

While generally safe - Xconq shouldn't crash while you are designing
nor upon starting up your scenario - you can do silly things, like
loading a submarine with battleships as passengers.  Xconq won't
complain, but it may behave very strangely.  For instance, a unit might
be able to travel with a transport and leave it, but not be able to get
back on again.

   One way to test a game is to remove all the scorekeepers and make all
the players be AI-controlled.  The AI code will then act totally
randomly, thus exercising parts of your design that you may not have
thought much about.  A convenient way to try out various scorekeepers is
to put them in variants, then select them upon startup.


File: xcdesign.info,  Node: Balance,  Next: Complexity,  Prev: Safety,  Up: Building New Games

2.23.8 Balance
--------------

Game design often involves subtle questions of balance which will only
be revealed by repeated play of the game.

   Although as many of the game parameters as possible are checked,
there is plenty of room for subtle loopholes.  You should think
carefully about the consequences of each parameter, being particularly
sensitive to degenerate winning strategies.  Most common are units that
are too powerful, too fast, or are built so quickly that they overwhelm
any opposition.  Players should always be a little "hungry"; not able to
get quite as many units or as much material as they would really like.


File: xcdesign.info,  Node: Complexity,  Next: Combinations,  Prev: Balance,  Up: Building New Games

2.23.9 Complexity
-----------------

Although GDL is a powerful language, you should avoid designing a game
that is too complex to be humanly playable.  A single game can literally
define millions of different parameters, each with a range including 100
to 10,000 distinct values.  It is clearly possible to spend many years
exploring just a single set of these!  For more playable and enjoyable
games, either pick a single thing to treat in detail, or else do
everything in a simplified way.  For instance, if you want elaborate
movement and combat rules, avoid or even eliminate materials and
associated material handling rules.

   Another thing to keep in mind is that the introduction of a new type
may have far-reaching consequences. For instance, an additional unit
type will need its interactions with all other unit types defined, as
well as with terrain and materials, and those new interactions may in
turn affect others.  One approach is to introduce a new type as a slight
modification of an existing type, then to share most of the definitions.
Another thing you can do is to put complexity into the variants, so
players with a taste for punishment can indulge themselves, while
leaving the basic game as more of a fun thing.


File: xcdesign.info,  Node: Combinations,  Prev: Complexity,  Up: Building New Games

2.23.10 Combinations
--------------------

Many of the 700-plus game parameters were chosen for their ability to
combine in interesting ways, rather than for obvious usefulness.  For
instance, construction in a city can by default generate an infinite
stream of units.  But suppose you want to put a limit on the numbers of
that type of unit?  One way is to define a material that is essential
for construction of that type, let the builder have an initial supply,
but provide no way to get more of that material.  When it runs out, no
more units!

   Another trick is to motivate an activity by making it a prerequisite
to the basic builtin goal of defeating the other player.  The age of
discovery worked this way.  The kings of that time weren't interested in
new lands per se; they wanted exploitable possessions, that could be
used to get gold, to buy armies big enough to defeat their neighbors.
You could describe this situation almost exactly, by making gold a
material, obtainable only by the discovery and capture of independent
gold mine units, which are thinly scattered over the world and can be
found only by careful exploration.

   Be inventive!  Studying the predefined games should suggest many
tricks; the "Tricks and Techniques" section below describes even more.
Be sure to document the trick carefully, or the next time you work on
the game, you might break it, resulting in unhappy players wondering why
their usual strategies don't work anymore.


File: xcdesign.info,  Node: Debugging Designs,  Next: Tricks and Techniques,  Prev: Building New Games,  Up: Game Design

2.24 Debugging Designs
======================

Completely new game designs usually have a number of bugs.  There are
several stages of trouble that you may encounter.  First, the Xconq may
fail to read a game module completely.  It will try to report what
happened, but if for instance you left out a closing parenthesis, you
may get some strange error messages.  This is just plain old syntax
error trouble.

   Once you've successfuly read in your new game, bring up the online
help and scan through to see if the values present are what you thought.
Sometimes the reader does not interpret a module in the way you thought
it would.  The `print' form is useful for debugging at this point; it
can show you whether a defined symbol has the value you thought it did.

   However, the most serious problems with games are play balance
issues.  Some can be found out by watching a machine player attached to
a display, since its decisions are based on perceived values of the
units.  The most subtle bugs can only be uncovered by extensive play
interspersed with judicious alteration of parameters.  I find it useful
to play for a while, then review and adjust the game parameters all at
once, thus avoiding tweaking one parameter only to find that it results
in another being inconsistent.  Parameters interact in many ways - you
should keep this in mind when experimenting.

   Something else to keep in mind at this point is that playability
should outweigh realism.  For example, real-life airplanes can travel
1,000 times faster than a person walking on the ground, but airplanes
that could move 1,000 cells in a turn would be ridiculous (try it out,
Xconq will let you do this!).


File: xcdesign.info,  Node: Tricks and Techniques,  Next: Designing with the Common Interface,  Prev: Debugging Designs,  Up: Game Design

2.25 Tricks and Techniques
==========================

This section discusses specific kinds of design problems and ways that
you might solve them in Xconq.  These are merely suggestions; in the
past, game designers have come up with all sorts of ingenious ideas.  If
you come up with one yourself, please pass it along!

* Menu:

* Limiting Unit Quantities::
* Handicapping::
* Buying the Initial Setup::
* Leaders::
* Navigable Rivers::
* What Ranges for Values?::
* Fatigue::
* Brainless Units and Scorekeeping::
* Days and Years::
* GDL Optimization::
* Conversion from Xconq 5::
* Xconq 5.x Setproduct::
* Even More::


File: xcdesign.info,  Node: Limiting Unit Quantities,  Next: Handicapping,  Up: Tricks and Techniques

2.25.1 Limiting Unit Quantities
-------------------------------

In some cases you may want to constrain the total number of units in
play, perhaps because of performance reasons, or because some type
tends to proliferate more than is desirable, or because your game
concept requires a hard limit on the number of units.  You have several
ways to do this.

   Xconq does give you several parameters that put a simple cap on
total numbers, either by unit type or for all units, and per side or
for all sides together.  You can also define a material type that is
essential to the creation, completion, or operation of units, and make
that material be hard to come by.  Iron to make ships, gold to pay
armies, or food to feed armies could all work this way.  If the only
source of the limiting material is an initial supply in a starting
unit, then this is a hard limit; if production of the limiting material
is slow, then the limit is softer but still very real.

   Limits on unit quantities have some interesting uses beyond the
obvious ones.  For instance, a useful type that is limited to at most a
single instance could be a sort of "football" where the side that has
the one unit finds itself being chased after by all the other sides
trying to get it.  You could make a WWII-era game with "Oppenheimer" as
the only scientist who knows how to make an atomic bomb (I know, it's
not realistic), and have the different sides trying to kidnap him.


File: xcdesign.info,  Node: Handicapping,  Next: Buying the Initial Setup,  Prev: Limiting Unit Quantities,  Up: Tricks and Techniques

2.25.2 Handicapping
-------------------

Very rarely will the Xconq players in a game all be at the same skill
level.  Sometimes this is OK, since weaker players really do learn more
from their losses than their wins.  However, when the goal is to have
fun, or when the difference in abilities is extreme, you can balance
things out in several different ways.

   One simple approach is just to design an imbalanced scenario,
document it as such, and let players choose the stronger and weaker
sides as desired.  In many cases this should be sufficient; for
instance, accurate historical simulations.

   The next most simple solution is to set up sides or side classes and
fill random properties differently.  Weaker players could choose a side
with more technology or whose class allows more powerful units.  This
isn't very adjustable, since all the sides and their property values
have to be predefined.

   To enable the most precise match of player abilities, you can use the
`initial-advantage' property of player objects.  This property is a
relative value, defaulting to 1, and indicates how strong the initial
unit setup should be relative to the other players.  For instance, if a
three-player game includes advantages of 2/3/7, then the second player
will have three units for each two of the first player while the third
player (the weakest) will have seven.  The implementation of relative
advantages is up to game synthesis, so for example the `make-countries'
will adjust all the numbers of initial units to match the requested
advantages.  Note that this affects only the initial setup, and only
certain synthesis methods.  Once a game has started, all sides are
always on an equal footing.


File: xcdesign.info,  Node: Buying the Initial Setup,  Next: Leaders,  Prev: Handicapping,  Up: Tricks and Techniques

2.25.3 Buying the Initial Setup
-------------------------------

A common form of game setup is to give each player a quantity of
"money" of some sort, then give them a menu from which to buy things.
The way you would implement this in Xconq is similar to the method for
limiting unit quantities - make the money be an initial supply of a
special material type not used for any other purpose.  This initial
supply should be given to a first unit that each player starts with.
This first unit could be something like the adventurer in a fantasy game
who starts with a pot of money, so the first unit is also the most
important one, or perhaps a little dummy unit that buys the other units
and then is of little interest thereafter, sort of like the national
bank for the player's country.

   Here's an example:
     (unit-type adventurer
       (start-with 1)
       )
     (unit-type shop
       (start-with 1)
       )

     (unit-type sword)
     (unit-type armor)
     (unit-type boat)

     (material-type money)

     (table initial-supply (adventurer money 200))

     (table acp-to-create (shop (sword armor boat) 1))

     (table material-to-create ((sword armor boat) money (20 100 1000)))
   The shop can't do anything besides create items when given money.
The adventurer starts with the money and has to give it to his/her shop,
then order the shop to create the items desired.  The shop will create
completed items instantly, ready for the adventurer to use.  A slight
simplification would be for the shop to start with the money itself.

   Note that this can't be extended to buy extra intrinsic qualities,
such as hit points or action points.


File: xcdesign.info,  Node: Leaders,  Next: Navigable Rivers,  Prev: Buying the Initial Setup,  Up: Tricks and Techniques

2.25.4 Leaders
--------------

Some games, particularly wargames set in Napoleonic times or earlier,
feature the concept of a "leader" as the sole individual who can make
things happen.  Without a general or field marshal, the army won't move.
Whether or not this is truly realistic, it does have the effect of
focusing the game on key individuals!

   One way to do this is to make the leader be a self-unit and limit the
distance of direct control over other unit types.  Another way is give
armies 0 acp and allow leaders to push them around, and still another
way is to use leaders as occupants that add to an army's speed.


File: xcdesign.info,  Node: Navigable Rivers,  Next: What Ranges for Values?,  Prev: Leaders,  Up: Tricks and Techniques

2.25.5 Navigable Rivers
-----------------------

The concept of a navigable unbridged river is a real problem for Xconq.
Non-navigable rivers are easily done as border terrain, and navigable
rivers with lots of bridges can be connections (since by their nature,
connections can never prevent movement).  But a navigable river that
can't be crossed easily is more of a problem.  One way is to make a
chain of adjacent cells of a water terrain type.  However, this can be
quite unrealistic if cells represent large areas, say 10-100 km across;
you can end up with continents consisting of more river than land.  In
some cases, you can define a "river valley" terrain type where both
vessels and ground units can exist, with the river border terrain along
just one edge of the valley.

   You can also allow border sliding.  Border sliding allows a ship to
pass along the length of a border, but it does require the ship to be in
compatible terrain at both ends of the border.  So define the river as
a chain of alternating water cells and water borders connecting them
together.  Then the river acts as a barrier to units wanting to cross,
while allowing them to see over to the other side, and at the same time
ships can pass up and down the river freely (modulo any ZOC exerted by
units on either side).


File: xcdesign.info,  Node: What Ranges for Values?,  Next: Fatigue,  Prev: Navigable Rivers,  Up: Tricks and Techniques

2.25.6 What Ranges for Values?
------------------------------

One of the problems that you encounter when defining a lot of
interrelated units with lots of properties and tables is to decide
where to start out with the numbers.  There are a couple ways to get
started.

   First, you can start from real-world numbers.  Let's say your game
concept is based on turns that last about one day, and you want to use
worlds with cells that are about 10 miles across.  Now a person in good
shape can walk about 2 miles per hour, or 20 miles in a day, which
comes out to 2 cells/turn as `acp-per-turn' for units on foot.  This
allows a speed of 1 cell/turn for injured, tired, or overburdened
persons, via the various speed modifiers.  However, if this same game
includes automobiles and airplanes, then using the same calculation, we
get automobiles that can move 60 cells/turn and airplanes that can move
600 cells/turn!  The massive disparity in speeds makes for poor
playing; every turn each airplane will make 300 moves while the foot
traveller makes 1.  To make the game work, you'd have to make airplanes
slower (they have to refuel a lot perhaps) or make people faster (nobody
walks anywhere anymore).  So the real-world numbers approach isn't
foolproof.

   Another way to go is to start with the smallest values and work up.
For instance, in the monster game above, you could assume that the mob
moves the slowest, and give it a speed of 1.  Then you say that the
national guard should be able to move twice as fast, and give it a
speed of 2.  Then the monster should be able to chase and catch mobs
and guards that run away, so you give it a speed of 3 or more.  This
approach is more painstaking, particularly when lots of numbers are
involved.

   You can use both approaches together as well, working with real-world
numbers until they get too weird, then adjust to make relative values
sensible, then do some more real-world calculations.  As always, only
playtesting is the final arbiter.  Once the numbers "feel" right in a
game, only the obsessive-compulsives will care about their exact values.


File: xcdesign.info,  Node: Fatigue,  Next: Brainless Units and Scorekeeping,  Prev: What Ranges for Values?,  Up: Tricks and Techniques

2.25.7 Fatigue
--------------

Players are often unmerciful to their units, moving them nonstop, going
into battle after battle, never a thought for how tired the poor units
might be.  Although Xconq does not include fatigue as a basic concept,
it does have several ways to implement the effects of fatigue.

   One way is to use acp debt.  If you allow the acp to go negative
during a turn, then the player can work the unit really hard for one
turn, then it has to rest until its acp builds up to positive levels
again.  While acp is negative, the unit can take no action on its own.
Over a period of time, the effect is that of a unit that can only do so
much, but can exert itself when needed.

   Another way to do fatigue is via a material type, perhaps called
"energy" or "enthusiasm".  As an abstract sort of material, don't let
energy be passed around (unless you want to have "infectious
enthusiasm", might be useful sometimes for leaders and morale builders).
Units need energy in order to move, and can consume energy faster than
they produce.  For instance, if a unit has a speed of 3 hexes/turn,
consumes 2 units of energy per move, and only produces 4 units of energy
each turn, then on the average the unit will only be able to move 2
hexes in each turn, although if it saves up energy, then it can move
the full 3 hexes.  Since different kinds of terrain can have differing
productivity, you can also make some kinds of terrain be more tiring
than others.  A resort hotel unit could also be allowed to transfer
energy to its residents, restoring them faster than a Motel 6.


File: xcdesign.info,  Node: Brainless Units and Scorekeeping,  Next: Days and Years,  Prev: Fatigue,  Up: Tricks and Techniques

2.25.8 Brainless Units and Scorekeeping
---------------------------------------

One special case to watch out for occurs in games with "unintelligent"
units, that is, they have an acp of 0.  If a side loses all of its units
except for the unintelligent ones, the player will not be able to do
anything except wait for the game to end.  This might be OK, for
instance if the idea of the game allows for a side to own a particular
unit, whether or not it can do anything with it (perhaps the unit is a
fort, and a side can win if it owns the fort, even at the cost of all
its other units).  Usually, however, the side ought to just lose, in
which case you will need to define a special scorekeeper that requires
each side to have at least one of some sort of unit with acp > 0, or
else it loses.


File: xcdesign.info,  Node: Days and Years,  Next: GDL Optimization,  Prev: Brainless Units and Scorekeeping,  Up: Tricks and Techniques

2.25.9 Days and Years
---------------------

[should go elsewhere]

   The Xconq world can be made to revolve around its sun and to rotate
on its axis. [etc]

   To get a realistic hour-by-hour simulation, say
     (world
       (day-length 24)
       (year-length 8766) ; this is 365.25 days
       )


File: xcdesign.info,  Node: GDL Optimization,  Next: Conversion from Xconq 5,  Prev: Days and Years,  Up: Tricks and Techniques

2.25.10 GDL Optimization
------------------------

The `add' form is very powerful and very useful for making groups of
objects share some data.  The grouping also helps the designer to see
how sets of numbers compare to each other.  In other words, instead of
having multiple forms:
     (unit-type foo
       ...
       (acp-per-turn 3)
       ...)
     (unit-type bar
       ...
       (acp-per-turn 49)
       ...)
     (unit-type baz
       ...
       (acp-per-turn 2)
       ...)
   you can say
     (add (foo bar baz) acp-per-turn (3 49 2))
   to get the same effect.

   To get an inheritance-like effect, you can append lists of types
together, as in
     (define mammal (dog cat cow))
     (define bird (hawk eagle condor))
     (define animal (append mammal bird fishie))
   which results in a list of seven types.  It is possible to append
different kinds of objects together.


File: xcdesign.info,  Node: Conversion from Xconq 5,  Next: Xconq 5.x Setproduct,  Prev: GDL Optimization,  Up: Tricks and Techniques

2.25.11 Conversion from Xconq 5
-------------------------------

There are many scenarios extant from the version 5 of Xconq.  Many of
them are good games despite some of the quirks of version 5 that they
had to work around.  Converting these scenarios to the new GDL syntax
should provide some great new modules and at any rate provide a
goldmine of ideas for updated Xconq game modules.

   A set of conversion scripts are provided that will help to ease the
transition from version 5 to version 7, but they won't save you from
learning the new GDL syntax or features.  These scripts will NOT
generate working games modules, but they will generate valid GDL
syntax, and thereby spare you much tedium in conversion.

   The first thing to consider is the naming of the files/modules.
There are already some loose guidelines for naming version 7 game
modules (*note Game Module Organization::).  Terrain or worlds should
be in modules named `t-xxx.g'.  These are roughly equivalent to version
5 `.map' files.  Collections of units, such as the cities to populate
world maps, should be in files named `u-xxx.g', where `xxx' generally
identifies which map they go with in addition to a general identifier
(e.g. `1942').  Name generators are in files of the form `ng-xxx.g',
but you probably don't know or care about these yet.  And finally, if
you are building a set of scenarios based on a core set of rules, you
should consider a naming scheme that will link them all together so
that players can find them easily.

   Having said all that, let's get on to the conversion.  The conversion
scripts go somewhat blindly on the assumption that you've split
everything up in the "standard" way.  That is, assuming that you've got
a spiffy big scenario, that it comes in three parts: a period
definition, a map and a scenario file.  If not, if you've _dared_ to
combine some of these files, you should split them manually before
starting the automated part of the conversion.

   Convert the map using `map2g'.  You want to use the -o option and
your new t-something name and the -b with a full pathname to the period
file that has the terrain type definitions in it.  This allows `map2g'
to set the default base module and the get the appropriate character
list for creating the map file.  The generated world will have its
circumference set to match the width of the generated area, i.e. it
will wrap from side to side.  This is because all maps are cylindrical
in version 5.

   Next, do a pass over the `.scn' file with `scn2g'.  Again you should
use -o to get the naming the way you want it.  This should leave you
with a very pretty set of units and a very rough hack at a set of
victory conditions (i.e. scorekeepers).  The scorekeepers will need to
be completely reworked, since they work rather differently in version 7.

   Now the home stretch, convert the `.per' file with `per2g'.  Keep an
eye on the output.  If it complains about "unknown keywords" then you've
probably used one of the more obscure features of version 5.  Don't
panic because your obscurity will be preserved-commented out-in the
resulting game module.  Now you have to edit the module and start
sorting out the bits that `per2g' couldn't handle.  Search for
occurances of FIX.  These are lines inserted by `per2g' to note places
that need your attention.  `per2g' may have done nothing to the line
except comment it out, or it may have done a partial (or partially
correct) conversion, or it may have done a complete and valid
conversion but wishes to call your attention to related forms that can
be added.

   For this process you are going to need to have the documentation
close at hand to make sure you get the syntax right.  The best thing to
do is read thru this chapter of the manual and then have the Reference
Manual chapter on hand while editing the module.

   Generally the place to start will be the `make' and `maker' lines
from the old period definition.  These are not converted at all by
`per2g' (because the machinery has changed so radically in version 7),
but are often essential to being able to start up a game.  From there
you can work your way through the rest of the file with frequent
references to the manual and occasional test runs.  Check out the
debugging tips in this chapter.


File: xcdesign.info,  Node: Xconq 5.x Setproduct,  Next: Even More,  Prev: Conversion from Xconq 5,  Up: Tricks and Techniques

2.25.12 Xconq 5.x Setproduct
----------------------------

Xconq version 5 had a sometimes-useful flag called "setproduct" that
could be set to false, with the effect that any attempts to change
construction were disabled.  So for instance, a city that was set by a
scenario to build bombers would then build bombers throughout the game.
The advantages were both in realism (retooling a factory can be very
time-consuming) and in playability (no construction planning required).

   To emulate this in version 7, you can set `acp-to-toolup' to be zero
for cities, but at the same time require 1 tp for each type that the
city can construct.  In the scenario, set the value of the city's
tooling to be 1 for the one or more types that you want it to
specialize in (maybe switching between fighters and bombers should be
possible, but not to submarines).  Players can then start and stop
construction as desired, but are limited to only particular types.
Even captured independent cities can be limited in what they can be
used to construct.


File: xcdesign.info,  Node: Even More,  Prev: Xconq 5.x Setproduct,  Up: Tricks and Techniques

2.25.13 Even More
-----------------

An unwanted unit in a shared library file could be gotten rid of by
matching on id or name and then setting hp to 0; `(unit "Corinth" (hp
0))', for instance, would eliminate Corinth from an ancient Greek game.

   Elevation data, while interesting to include, can take up a lot of
space and be more detailed than necessary.  The parameters here allow
you to restrict elevations to a smaller range of values, which will
allow for more compact encoding and simpler games.  For instance, a
game set in rolling countryside doesn't need a huge range of
elevations; you could set elevations to range from 0 to 300 meters, in
30-meter increments.  Then only 4 bits will be needed to encode each
value, and yet the player will still see reasonable values like "150
meters", and formulas for temperature and other elevation dependent
data will be correct.

   Note that just because a player controls a side doesn't mean that the
controlled side can be taken out of the game; for one thing, certain
types of units will not change sides under any circumstances.

   People materials should usually not be directly movable between
units.

   ZOC should be less than combat range usually, since it means that
exerter should be able to control ground (but could attack further in
multiple turns).  ZOC levels should be only those reachable by the unit.

   With all the costs of moving around, it may be that a unit has
movement points left, but not enough to meet the full cost of a desired
move action.  You can allow player extra movement points to complete
the action by setting `free-mp' to effectively add the needed mp.

   A hit on a complete unit should reduce by whole cp/hp, otherwise it
will appear to be incomplete.  Xconq will not fix this, you have to
arrange all the numbers yourself, or run the risk of player confusion.

   Bases should "anti-protect" aircraft in games involving both, but
fighters should protect the base.


File: xcdesign.info,  Node: Designing with the Common Interface,  Next: Designing with the Mac Interface,  Prev: Tricks and Techniques,  Up: Game Design

2.26 Designing with the Common Interface
========================================

The common interface includes both the Unix/X11 and Windows versions;
game design works the same for both.

   The common interface provides a "design mode" that allows you to do
many game design tasks interactively.  At present, you can use it to
lay out maps, specify the contents of the different area layers, and
set up units.  You can then save chosen elements of the design into a
file.

* Menu:

* Common Interface Design Mode::
* Common Interface Design Palette::
* Common Interface Design Save::
* Common Interface Image Families::


File: xcdesign.info,  Node: Common Interface Design Mode,  Next: Common Interface Design Palette,  Up: Designing with the Common Interface

2.26.1 Common Interface Design Mode
-----------------------------------

There are several ways to get into design mode; you can specify
`-design' on the command line, you can choose Design from the Edit
menu, or you can type in the long command `design'.  When you do any of
these, several things will happen: the side list will mark your side as
a designer, the Show All item in the View menu will appear, and you
will get a popup window with a palette of designer's tools.  The popup
applies to all maps equally.

   The identification in the side list is for the benefit of other
players, since it is actually possible to enable designing in a
multi-player game.

   The Show All view control allows you to see everything accurately.
It is switchable so you can compare what things look like to the player
vs what they are in reality.  This is also important for side view
painting, which is useful for exploration-based scenarios.

   Note that the online design mode is powerful, with few restrictions.
This means you can scramble things if you're not careful.  Frequent
saves are a good idea.


File: xcdesign.info,  Node: Common Interface Design Palette,  Next: Common Interface Design Save,  Prev: Common Interface Design Mode,  Up: Designing with the Common Interface

2.26.2 Common Interface Design Palette
--------------------------------------

The design palette consists of a number of buttons next to a varying
frame whose contents vary depending on the button pressed.  Each button
corresponds to a different sort of painting/placement mode.

`Normal'
     This mode corresponds to normal survey mode.  This mode is mainly
     for moving units around.  You can move a unit by left-clicking to
     select it, then right-clicking on the desired destination.  You
     can even right-click on another unit to have the selected unit
     become an occupant.

`Paint Terrain'
     In this mode, clicking and dragging in any map paints terrain,
     just as if you were using a standard paint program.  The varying
     frame displays samples of the terrain, as well as two popups, one
     for "foreground" terrain and one for "background" terrain.  The
     foreground type is what normally gets painted.  However, if you
     click on a cell of the foreground type, you will paint the
     background type into the cell, and will continue to do so when you
     drag the mouse.  This makes it easy to toggle when you're
     fine-tuning a coastline and so forth.  (It's easier to use than to
     describe!)

     You can also select border and connection types to paint, in which
     case clicking toggles the existence of the border or connection.
     The background terrain type is not used while painting borders and
     connections.

     Note that you don't need to follow terrain/terrain or unit/terrain
     compatibility rules while painting; you can paint sea underneath a
     city if you like, or rivers through icefields.  However, the city
     will quietly disappear from the game when you start up the
     modified module.

`Place Unit'
     In this mode, clicking on a map creates and places a unit.  Popups
     in the varying frame let you specify type and side.

     As with terrain painting, compatibility rules are not enforced.

`Paint People'
     This mode lets you specify the side of the people in each cell.
     The varying frame's popup lets you choose the side, then
     clicking/dragging paints.  Clicking on a cell with people on a
     different side converts them to your selected side, while if the
     people are on your selected side, then the cell becomes empty (not
     independent!).

`Paint Control'
     This mode is very similar to the people-painting mode, but applies
     to the control layer instead.

`Paint Feature'
     This mode is for painting geographical features.  You choose the
     feature from a popup menu.  You can also create new features and
     edit the name of any feature.

     You should turn on the display of display feature boundaries.  The
     feature you're painting have its boundaries drawn red, while the
     other boundaries will be gray.

`Paint Material'
     [not yet implemented]

`Paint Elevation'
     Use this mode to set terrain elevations.

`Paint Temperature'
     Use this mode to set temperatures.

`Paint Clouds'
     Use this mode to set cloud cover.

`Paint Winds'
     Use this mode to set winds.

`Paint View'
     Use this mode to paint the side view.  At present, this only works
     on the designing side's view.  In his mode, the paintbrush toggles
     the view between unknown and an accurate view of the terrain and
     units in each cell.  Turn off the Show All option on the View menu
     to see the effect of this; unknown terrain will still be visible,
     but dimmed.  You need to switch out of designer mode to see
     exactly what it will look like to a game player.


   Below the buttons is a popup with a numeric label.  This sets the
radius of the paint brush.  A radius 0 brush affects only a single
cell, while radius 1 applies to the cell and all adjacent, and so
forth.  The radius goes up to 9, which is spectacularly large for most
maps, and always at risk of painting over something you wanted.  A
brush size of 2-3 is more useful for roughing-in shapes.  There is
currently no undo for painting, so be careful!


File: xcdesign.info,  Node: Common Interface Design Save,  Next: Common Interface Image Families,  Prev: Common Interface Design Palette,  Up: Designing with the Common Interface

2.26.3 Common Interface Design Save
-----------------------------------

If you go to save the game while designing, you will get a much more
elaborate dialog than for normal saving.  Use the checkboxes to decide
which elements of the design to save.


File: xcdesign.info,  Node: Common Interface Image Families,  Prev: Common Interface Design Save,  Up: Designing with the Common Interface

2.26.4 Common Interface Image Families
--------------------------------------

X11 Xconq can use images in either its portable image family format, or
as bitmaps.  However, since images in portable format will work with
other interfaces, you should only use bitmaps while prototyping, and
translate them into portable form using `x2imf'.

   To translate image families into bitmaps, use the tool `imf2x'.

   The program `xshowimf' displays image families.

   Control the display of three-color images (mono+mask) with the
resource `maskColor' (see `XShowimf-co.ad' or with the command-line
argument `-mc'.

   To edit the image families, do something like
     mkdir tmp
     xshowimf [imf/xbm/xpm files...] -o tmpdir &
     (cd tmpdir; xpaint) &


File: xcdesign.info,  Node: Designing with the Mac Interface,  Prev: Designing with the Common Interface,  Up: Game Design

2.27 Designing with the Mac Interface
=====================================

Designer's tools and capabilities are available via the Design item in
the Edit menu, or by typing `design' into the Command window.  The
display changes to show you everything in the world, you get a number of
special privileges (such as the ability to look at and move ANY unit),
and you get a designer's tools palette.

* Menu:

* Using the Palette::
* Mac Interface Images::
* IMFApp::
* Mac Interface Sounds::


File: xcdesign.info,  Node: Using the Palette,  Next: Mac Interface Images,  Up: Designing with the Mac Interface

2.27.1 Using the Palette
------------------------

In general, palette items use Option-click and Option-Shift-click to
cycle through possible values, and many also have a popup menu.  Also
note that the selection can be changed without changing the tool; you
have to click in the tool and get a heavy border around it before the
tool is actually changed.  Each type of designer tool has a distinct
cursor when over a map window, so look for that as well.

`Normal'
     In this mode the mouse behaves just as in normal survey mode.

`Painting Terrain'
     If you select the terrain item in the palette, then
     clicking/dragging in a map paints the current terrain type
     displayed in the palette (Option-clicking the terrain item cycles
     through all the types, Shift-Option-click does the same thing in
     reverse order).  The background terrain type can be cycled via
     Command-click and Command-Shift-click.

`Creating Units'
     The unit item includes a popup of all unit types.  Use it to
     select the unit type you want to create, then clicking on a map
     window will place the unit at that location.  Unit placement
     ignores stacking limits, terrain compatibility, and other issues,
     so you may be able to place a unit but not have it successfully
     appear there when a player tries to use the game module.

     The side item includes a popup with all the sides listed,
     including the "independent" side.  Use it to set the side with
     which a new unit will be created.  Not all units are allowed on
     all sides - Xconq marks the sides that are allowed with the
     current unit type, and the unit types that are allowed with the
     current side.

`Painting People'
     If you select the side item in the palette, you can click/drag in
     a map to set the side of the people in the cells clicked or
     dragged over.

     Note that the chosen side affect either people painting or unit
     creation, depending on which item is selected as the painting tool.

`Creating Named Features'
     The features item in the palette includes several buttons and a
     popup menu that displays all the features currently defined.  You
     can click on the buttons to create, destroy, and rename a feature.
     You can add or remove cells of a feature by painting in any map.

`Setting Brush Size'
     The Brush item sets the area of effect of the painting tools.  A
     brush radius of 0 (the default) results in painting affecting only
     the cell in which the mouse is clicked or dragged, while a radius
     of 1 causes the adjacent cells to be affected also.  Adjust the
     brush size up and down by option-clicking and
     option-shift-clicking in the brush item.

`Painting Elevations'
     You can set the elevations of terrain by selecting the elevations
     item in the palette, then painting in any map.

`Painting Views'
     When you select this item, you get a tool that toggles the
     designing side's view of a cell.  The toggle goes between unknown
     terrain and an accurate view of the cell and any units in it.



File: xcdesign.info,  Node: Mac Interface Images,  Next: IMFApp,  Prev: Using the Palette,  Up: Designing with the Mac Interface

2.27.2 Mac Interface Images
---------------------------

If you want to change the icons and pictures in an existing game, or if
you want to define new ones, you can do this either with a resource
editor such as ResEdit, or with a resource compiler such as Rez, or by
editing the portable "imf" files.  Xconq can use PICTs, icons, and
patterns to draw with; collectively these will be called "images".  A
group of images that all represent different views of the same thing is
an "image family".  The concept is similar to the icon families used by
Macintosh programs, but is much more general, since you can have any
number of images of different sizes and depths, as well as images
embedded in each other.

2.27.2.1 Icons and Patterns
...........................

The resource file `:lib-mac:Images' is the main repository of Mac
imagery.  You can resource-edit this file, close it, start up Xconq,
and see the results.  For instance, if you want to improve the
appearance of the "city20" image, you will find a 32x32 `'cicn'' with
that name as well as a 16x16 'sicn'.  You can modify these as you like.
Note that the 'sicn' includes a mask sicn, as does the `'cicn''.  Masks
are optional, but improve the appearance of the images.  If you have a
new type in a game and you want an image for it, just create a
resource, such as a `'cicn'', give it the name of the type or its
`image-name' property, and you're done.

   The standard resource types for images are `'cicn'', `'ICON'', `'PAT
'', `'ppat'', `'SICN'', and `'PICT''.  If a resource of one of these
types has a name matching the `image-name' (or the type name if no
image name is defined) of a type in a game, then Xconq will use that
resource.  There are two additional resource types: `'XCic'' and
`'XCif''.  The `'XCic'' resources are named colors that can be referred
to via `color' properties of types and sides.  `'XCif'' resources are
raw image family forms in GDL syntax.  If the contents of an image
family can be totally defined by the standard resource types, then
there need not be an `'XCif'' resource, but if an image has any
embedded subimages, or a specific location for subimages, then this
information will be in the `'XCif'' resource.  You can edit by defining
this resource type as `'TEXT'', which will give you a text editor for
the resource, or by just opening the `'TEXT'' editor on the resource.
For more details about the syntax of image families in GDL, see the
reference manual.

   Warning: don't ever make a `'cicn'' with id 256!  For some reason,
if there is a `'cicn'' 256 in either the application or in any of the
resource files that it has open, the small color icons in both the
apple menu (far left) and the application menu (far right) become small
unrecognizable blobs.  This effect seems to be innocuous behaviorwise,
but the appearance is poor, and users choose menu items by looking at
those icons, so trashing them is a bad thing to do.

2.27.2.2 Game Preview Pictures
..............................

If the Resources file has a PICT whose name is "<game-name> game", then
if a player selects <game-name> in the new game dialog, this PICT will
be displayed in the dialog.  This is useful to give prospective players
more of an idea of what the game might be like, plus it's a chance to
show off your artistry!  (If you're a lousy artist, just make a screen
shot of the map and use that.)  The area for the picture is about 200
pixels across and 100 high; pictures smaller than that will be
centered, while larger pictures will be clipped to fit.


File: xcdesign.info,  Node: IMFApp,  Next: Mac Interface Sounds,  Prev: Mac Interface Images,  Up: Designing with the Mac Interface

2.27.3 IMFApp
-------------

IMFApp is a utility for examining and converting the image families
used by Xconq.

   The general concept of image families is similar to that of the
Finder icon families, where several depths and sizes of an icon are
available for use in different situations.  Xconq adds extra complexity
to the concept by including tiling patterns, by allowing icons to be
embedded in each other, and by using the same image families on several
different platforms.

   The platform-independent format would be hard to edit, so IMFApp
includes functions to convert between the common format and Mac
resources.  These functions are available from the File Menu.

   In addition, IMFApp also allows you to look at the images.  You can
control the images' size, overlay, and use of color.  The primary use
for this is to test how an image works in various situations.  Also, if
you design games, this is a good place to start when choosing images
for your game.  Since there are hundreds of images available already,
the chances are good that the images you want have already been
designed.

   The File menu has items to open and save imf and resource files.
New clears any existing images.  Opening multiple files merges their
contents.

   The Edit menu is not used.

   The View menu includes all image appearance controls.  Everything in
this menu affects only the _display_ of the images, and does not, in
any way, affect the image families themselves.  Display options include
size of images, color/mono, name, mask, background/emblem images, and
more.


File: xcdesign.info,  Node: Mac Interface Sounds,  Prev: IMFApp,  Up: Designing with the Mac Interface

2.27.4 Mac Interface Sounds
---------------------------

Mac Xconq handles sounds in a very simple way.  The resource file
`:lib-mac:Sounds' includes a number of named `'snd '' resources.  If an
event movie includes a form like `(sound "pop")', then the event
occurs, Mac Xconq will look for a sound resource named `pop' and play
it.


File: xcdesign.info,  Node: Reference Manual,  Next: Summary of GDL Syntax,  Prev: Game Design,  Up: Top

3 Reference Manual
******************

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

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

* Menu:

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


File: xcdesign.info,  Node: Language Syntax,  Next: Game Module Forms,  Up: Reference Manual

3.1 Language Syntax
===================

GDL resembles Lisp, but instead of defining functions, the contents of a
file declare certain objects (such as units and unit types) to exist,
and specify values for their properties.  In other words, GDL is
_nonprocedural_.  This means that most of the time, you can list the
various forms in any order you like.  The main restriction is that any
symbol, such as a variable or the name of a type, must be defined
before it is used.  Also, forms such as `set' and `add', that set the
value of a variable or property, always overwrite the previous data
irreversibly, so ordering of these is very important.

* Menu:

* Lexical Elements::
* Conventions Used::
* Forms and Evaluation::
* Tables::
* Modifying Objects::
* Symbols::
* Lists::


File: xcdesign.info,  Node: Lexical Elements,  Next: Conventions Used,  Up: Language Syntax

3.1.1 Lexical Elements
----------------------

Numbers are introduced by a decimal digit, plus, or minus signs.  They
may contain only decimal digits, a decimal point, and be followed
(immediately, no whitespace allowed) by a percent sign.

   Strings are sequences of characters enclosed by doublequotes (`"').
They may contain any character except ASCII NUL (`'\0'').  To include a
doublequote, use backslash, as in `"a \"quoted\" string"'.  To include
a nonprinting or eight-bit character, use backslash followed by three
octal digits, which will be interpreted as an eight-bit character code.
(This is mostly the same syntax as in C.)  Note that game design files
may be passed over networks and between different kinds of computer
systems, so non-ASCII characters should not be inserted verbatim into
strings.

   Symbols are sequences of characters that don't include any of the
other special characters.  If you wish to include such characters in a
symbol, enclose it in vertical bars, for example `|foo bar|'.  (The bars
are not part of the symbol.)  Symbols are case-sensitive, but this will
be changed eventually.

   Lists are a sequence of expressions enclosed in parentheses.  The
empty list is either `nil' or `()'.  "Dotted pairs" are not allowed.
Anything that is not a list is an "atom".

   All of these objects may range up to a very large size.  (You may
still run into bugs if you make strings or symbols over about 100 chars
in length.)

   Comments are enclosed either within `#| |#' (which nests properly,
like Common Lisp and unlike C), or else extend from a semicolon `;' to
the end of the line.  A comment is equivalent to whitespace, so
`(a#|bcd|#e)' is the same as `(a e)', not `(ae)'.

   `#' by itself is a normal token.

   True/false values are just the integers 0 and 1, with no special
characteristics.

 -- GlobalConstant: `true'

 -- GlobalConstant: `false'
     These constants are symbolic forms for `1' and `0'.  They are
     identical to numbers, but more descriptive for parameters that are
     boolean-valued.

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

   You may also supply numbers as DICE SPECS, which are used in several
tables.  The syntax is the familiar `NNdMM[+OO]', where NN is the
number of dice to throw, MM is the number of values on each die, and the
optional OO is an value to be added to the result.  The die are
0-based, so for instance `3d6' yields values between 0 and 15, while
`3d6+3' is equivalent to the result of rolling 3 6-sided dice.  The
range of each value is severely limited; NN may range from 0 to 7, MM
from 0 to 15, and OO from 0 to 127.  Internally, dice specs are normal
integers, in the range 16384 to 32767.


File: xcdesign.info,  Node: Conventions Used,  Next: Forms and Evaluation,  Prev: Lexical Elements,  Up: Language Syntax

3.1.2 Conventions Used
----------------------

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

   For parameters described as T/F, both `1', `0' and `true', `false'
may be used.  Parameters described as N and N% are numbers.  Parameters
described as DIST or LENGTH are also numbers, but are in the unit of
measure for lengths.  Parameters described as STR or STRING are strings.

   Parameters described as U or UI, M or MI, and T or TI, are values
that must be unit, material, or terrain types, respectively.

   Parameters described as UTYPE-VALUE-LIST match unit types with
values.  They can have several forms:

   * `(n1 n2 ...)' matches `n1' with type 0, etc in order.

   * `((u1 n1) (u2 n2) ...)' evaluates `u1' to get a unit type, then
     matches it with `n1'.  `u1' etc may also be a list of types, in
     which case all the types get matched with `n1'.


   Other types of lists, such as those defined as SIDE-VALUE-LIST, are
interpreted similarly.  For all of these, multiple assignments to the
same type etc will overwrite quietly.

   List values described as INTERPOLATION-LIST are lists of pairs used
to derive numerical values by interpolating between the listed values.
The form of an interpolation list is always `((key1 val1) (key2 val2)
...))', where KEYI and VALI are numbers.  If the input value INP to an
interpolation matches KEYI, the result value is VALI.  If it is between
KEYI and KEYI+1, then the result is gotten by linear interpolation,
with the result value falling somewhere between VALI and VALI+1.
Fractional values always round down.  The KEYI must occur in
non-decreasing order; it is legitimate for two consecutive keys to be
identical, in which the result value will be the value associated with
the first key.  If the input value is outside the domain specified by
the keys, the result depends on the particular parameter; some will
extrapolate in some appropriate fashion, while others will generate an
error or warning.

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

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

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


File: xcdesign.info,  Node: Forms and Evaluation,  Next: Tables,  Prev: Conventions Used,  Up: Language Syntax

3.1.3 Forms and Evaluation
--------------------------

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

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


File: xcdesign.info,  Node: Tables,  Next: Modifying Objects,  Prev: Forms and Evaluation,  Up: Language Syntax

3.1.4 Tables
------------

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

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

     If the first member of ITEMS is the symbol `add', then the rest of
     the items will add to the existing contents of the table rather
     than clearing to its default value first.

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

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

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

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

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


File: xcdesign.info,  Node: Modifying Objects,  Next: Symbols,  Prev: Tables,  Up: Language Syntax

3.1.5 Modifying Objects
-----------------------

Since forms normally define or create new objects, GDL defines the
`add' form to modify existing objects.

 -- Form: `add' objects property new-values...
     This form evaluates the atom or list OBJECTS to arrive at the set
     of objects to be modified.  Then it uses the NEW-VALUES to write
     new data into the property named PROPERTY of those objects.  The
     NEW-VALUES may be a single number or string, or a list.


File: xcdesign.info,  Node: Symbols,  Next: Lists,  Prev: Modifying Objects,  Up: Language Syntax

3.1.6 Symbols
-------------

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

 -- Form: `define' symbol value
     This form defines the symbol SYMBOL to be bound to the result of
     evaluating VALUE.  If SYMBOL is already defined, Xconq will issue
     a warning, and ignore this form.

 -- Form: `set' symbol value
     This form rebinds the already-bound symbol SYMBOL to be bound to
     the result of evaluating VALUE.  If SYMBOL is _not_ bound already,
     then Xconq will issue a warning, but proceed anyway.

 -- Form: `undefine' symbol
     This form destroys any binding of the SYMBOL.  This is allowed for
     any symbol, including already-unbound symbols.


File: xcdesign.info,  Node: Lists,  Prev: Symbols,  Up: Language Syntax

3.1.7 Lists
-----------

 -- Function: `quote' form...
     This function prevents any evaluation of FORM.  (This implies that
     the abovementioned evaluation of the argument list does not happen
     for this "function".)

 -- Function: `list' form...
     This function makes a list out of all the FORM.

 -- Function: `append' form...
     This function appends all the FORM (which may be lists or not)
     into a single list.  Non-lists will appear as though they were
     single-element lists.

 -- Function: `remove' list1 list2
     This function removes the members of LIST1 from LIST2, returning
     the result.


File: xcdesign.info,  Node: Game Module Forms,  Next: World and Area Forms,  Prev: Language Syntax,  Up: Reference Manual

3.2 Game Module Forms
=====================

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

 -- Form: `game-module' [ name ] properties...
     This form defines the properties of this game module.  The optional
     NAME is a string that will be used to look up the module in
     libraries.  If the NAME is supplied, then this form is considered
     to be the definition of the module, and overwrites any
     `game-module' form previously appearing in this file.  If NAME is
     missing, then this form will modify the existing description of
     the module.  Although are currently no restrictions enforced on
     the length or character set of a module name, Xconq may warn about
     a name that does not match the name of the file containing these
     forms.

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

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

 -- ModuleProperty: `picture-name' string
     This property is the name of a picture that may be displayed along
     with the module's blurb, by those interfaces that support such
     pictures.

 -- ModuleProperty: `base-game' t/f

 -- ModuleProperty: `instructions' strings...
     This property is a list of strings that are the instructions on
     how to play the game.

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

 -- ModuleProperty: `design-notes' strings...
     This property is a list of strings that are notes addressed to game
     designers.

 -- ModuleProperty: `version' string
     This property is the version of the module.  Defaults to `""',
     which indicates that the module's version is undefined.

 -- ModuleProperty: `base-module' name
     This property is the name of a module that must be loaded first.
     It is similar in effect to `include'.

 -- ModuleProperty: `default-base-module' name
     This property specifies the name of a module that will be loaded
     if when this module is loaded, no types are defined yet.

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

 -- ModuleProperty: `original-module' name

 -- ModuleProperty: `original-version' string

 -- ModuleProperty: `original-variants' list
     These properties record the module's name, version, and variant
     selections before a game save.  They are needed to record the game
     in the scorefile usefully.

* Menu:

* Module Variants::
* Including Other Modules::
* Conditional Loading::


File: xcdesign.info,  Node: Module Variants,  Next: Including Other Modules,  Up: Game Module Forms

3.2.1 Module Variants
---------------------

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

 -- ModuleProperty: `variants' items...
     This property defines named variants on this module.  Variants
     appear as startup options for the game.  Each item has the form
          ([ NAME ] TYPE [ HELP ] [ RANGE/DEFAULT ] [ CLAUSES ])
     The optional NAME is a string used to identify the choice to the
     players, the TYPE says what sort of change is being enabled, HELP
     is an optional help string, RANGE/DEFAULT supplies a range of
     values and a default value among them, and CLAUSES is a list of
     the form `(VALUE FORMS...)', where the FORMS are executed while
     reading if the value of the variant was chosen to be VALUE.  A
     game module may specify any number of variants.  Defaults to `()'.

   A number of commonly useful variant types are predefined.

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

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

 -- VariantType: `see-all' [ dflt ] [ clauses ]
     This variant allows players to choose whether everything will be
     seen always, as with the global variable `see-all'.  The default
     is set by `dflt'.

 -- VariantType: `sequential' [ dflt ] [ clauses ]
     This variant allows players to choose whether to move
     simultaneously during a turn, or one at a time.  The default is
     set by DFLT.  The variant works by setting `use-side-priority'.

 -- VariantType: `real-time' [ total [ perside [ perturn ] ] ] [
          clauses ]
     This variant allows players to choose realtime limits on the game.
     The value will default to the values in this variant's data.

 -- VariantType: `economy'
     This variant enables/disables the advanced supply line system.

 -- VariantType: `supply'
     This variant enables/disables the advanced supply line system.


File: xcdesign.info,  Node: Including Other Modules,  Next: Conditional Loading,  Prev: Module Variants,  Up: Game Module Forms

3.2.2 Including Other Modules
-----------------------------

You can include one game module in another.

 -- Form: `include' module-name [ variant-settings ]
     This form has the effect of inserting the contents of MODULE-NAME
     into the current position in the module.  `game-module' forms in
     the included module are not inserted, although they are remembered
     and may appear in displays.  Xconq will fail completely if the
     included module cannot be found.

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

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


File: xcdesign.info,  Node: Conditional Loading,  Prev: Including Other Modules,  Up: Game Module Forms

3.2.3 Conditional Loading
-------------------------

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

 -- Form: `if' test-form sym

 -- Form: `else' sym

 -- Form: `end-if' sym
     If TEST-FORM evaluates to `true', then all subsequent forms, up
     until the matching `else' or `end-if', will be evaluated.  If
     `false', then the forms will be read but not evaluated.  All forms
     inside the conditional must be syntactically correct.


File: xcdesign.info,  Node: World and Area Forms,  Next: Side and Player Forms,  Prev: Game Module Forms,  Up: Reference Manual

3.3 World and Area Forms
========================

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

 -- Form: `world' [ circumference ] properties...
     This form defines the properties of the world as a whole.

 -- Form: `area' [ width [ height ] ] [ restriction ] properties...
     This form defines the playing area of the world.  The RESTRICTION
     identifies how to get data for this area from subsequent forms
     that are based on larger areas.

* Menu:

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


File: xcdesign.info,  Node: World Properties,  Next: Area Properties,  Up: World and Area Forms

3.3.1 World Properties
----------------------

 -- WorldProperty: `circumference' dist
     This property is the distance in cells around the entire world (as
     a sphere).  Default is `360'.

 -- WorldProperty: `axial-tilt' n
     This property defines the extremes of seasonal changes.


File: xcdesign.info,  Node: Area Properties,  Next: Layers,  Prev: World Properties,  Up: World and Area Forms

3.3.2 Area Properties
---------------------

 -- AreaProperty: `width' n

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

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

   This world is an 8x7 hexagon:
        # # # # #
       # : + + : #
      # : : + ^ : #
     # : : + ^ : : #
      # : : : : : #
       # : : ^ : #
        # # # # #

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

 -- AreaProperty: `latitude' n
     This property is the offset, in cells, from the equator of the
     middle of the area (height / 2).

 -- AreaProperty: `longitude' n
     This property is the offset, in cells, from the "Greenwich
     Meridian" of the world.

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

 -- AreaRestriction: `restrict' w h x y | `reset'
     This is a special subform that specifies that subsequent layers in
     an area of size W x H will be offset by X,Y and then read into the
     actual area.  (This is useful for setting up a scenario that needs
     only a subset of a full map.)

     If the restriction specifies `reset' rather than four numbers, it
     means to cancel the restriction and return to normal area layer
     processing.

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


File: xcdesign.info,  Node: Layers,  Next: Distances and Elevations,  Prev: Area Properties,  Up: World and Area Forms

3.3.3 Layers
------------

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

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

 -- LayerSubform: `constant' n
     This subform causes every value in the layer to be set to N.

 -- LayerSubform: `subarea' x y w h
     This subform indicates that the layer data should be positioned at
     the given rectangle in the layer.

 -- LayerSubform: `xform' mul add
     This subform has the effect of first multiplying the raw value by
     MUL, then adding ADD and storing the result into the layer.

 -- LayerSubform: `by-bits'

 -- LayerSubform: `by-char' str
     This subform specifies that the characters in STR give the
     encodings of values in the layer.  The first character in STR
     encodes 0, the second encodes 1, and so forth.

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

 -- AreaProperty: `terrain' layer-data...
     This property is the actual layer of terrain types for cells.

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

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

 -- AreaProperty: `material' material-type layer-data...
     This property declares the quantity of the given MATERIAL-TYPE in
     each cell of the area.

 -- AreaProperty: `people-sides' layer-data...
     This property says which side the people of each cell are on.  A
     SIDE-ENCODING of `exact' assigns 0 to independence (no side), 1 to
     the first side, and so forth; otherwise, the encoding is a list of
     side names/ids and numbers.

 -- AreaProperty: `control-sides' layer-data...
     This property says which side controls each cell.  The encoding is
     the same as for `people-sides'.


File: xcdesign.info,  Node: Distances and Elevations,  Next: Temperatures,  Prev: Layers,  Up: World and Area Forms

3.3.4 Distances and Elevations
------------------------------

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

 -- AreaProperty: `elevations' layer-data...
     This property is the world elevation data itself.  If any elevation
     falls outside the min/max elevation range for the terrain type of
     the cell, then it will be truncated appropriately.

 -- AreaProperty: `cell-width' elev
     This property is the distance across a single cell, expressed as
     units of elevation.  Defaults to `1'.


File: xcdesign.info,  Node: Temperatures,  Next: Winds,  Prev: Distances and Elevations,  Up: World and Area Forms

3.3.5 Temperatures
------------------

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

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

 -- GlobalVariable: `temperature-floor' n
     This variable is the lowest possible temperature.

 -- GlobalVariable: `temperature-floor-elevation' n
     This variable is the value of elevation at which the temperature is
     always at `temperature-floor'.

 -- AreaProperty: `temperatures' layer-data...
     This property contains the temperature data itself.  If any
     temperature falls outside the min/max temperature range, then it
     will be truncated appropriately.


File: xcdesign.info,  Node: Winds,  Next: Clouds,  Prev: Temperatures,  Up: World and Area Forms

3.3.6 Winds
-----------

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

 -- AreaProperty: `winds' layer-data...
     This property contains the force and direction of the prevailing
     winds in each cell.


File: xcdesign.info,  Node: Clouds,  Next: User,  Prev: Winds,  Up: World and Area Forms

3.3.7 Clouds
------------

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

 -- AreaProperty: `clouds' layer-data...
     This property is the degree of cloud cover over each cell.  A
     value of `0' corresponds to clear skies.

 -- AreaProperty: `cloud-bottoms' layer-data...
     This property is the altitude above the ground of the bottoms of
     the clouds.

 -- AreaProperty: `cloud-heights' layer-data...
     This property is the vertical thickness of the cloud cover in each
     cell.


File: xcdesign.info,  Node: User,  Prev: Clouds,  Up: World and Area Forms

3.3.8 User
----------

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

 -- AreaProperty: `user' layer-data...
     This property indicates which unit is using which cells for
     production.


File: xcdesign.info,  Node: Side and Player Forms,  Next: Unit Forms,  Prev: World and Area Forms,  Up: Reference Manual

3.4 Side and Player Forms
=========================

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

 -- GlobalVariable: `sides-min' n

 -- GlobalVariable: `sides-max' n
     These variables are the minimum and maximum number of sides that
     may exist in a game.  Defaults are to `1' and the internal
     parameter `MAXSIDES', which is usually around 7.  `MAXSIDES' can
     only be changed by recompiling Xconq.

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

* Menu:

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


File: xcdesign.info,  Node: Side Name Properties,  Next: Side Class,  Up: Side and Player Forms

3.4.1 Side Name Properties
--------------------------

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

 -- SideProperty: `name' str
     This property is the proper name of a side, as a country or
     alliance name.  Examples include `"Axis"' and `"Hyperborea"'.

 -- SideProperty: `long-name' str
     This property is the long form of a side's name, as in `"People's
     Republic of Hyperborea"'.  Defaults to be the same as the side's
     name.

 -- SideProperty: `short-name' str
     This property is an short name or acronym for the side, often just
     the letters of the long name, as in `"PRH"'.

 -- SideProperty: `noun' str
     This property is the name of an individual unit or person
     belonging to the side.  Defaults to `""', which suppresses any
     mention of the side when (textually) describing the individual.

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

 -- SideProperty: `adjective' str
     This property is an adjective that can be used of individuals on
     the side, as in `"Spanish"'.  Defaults to `""', which suppresses
     use of the adjective.

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

 -- SideProperty: `color' str
     This property is a comma-separated list of colors that represents
     the side.  Defaults to `"black"'.

 -- SideProperty: `emblem-name' str
     This property is the name of a graphical icon that represents the
     side.  An emblem name of `"none"' suppresses any emblem display
     for the side.  Defaults to `""', which gives the side a
     randomly-selected emblem.

 -- SideProperty: `names-locked' t/f
     If the value of this property is `true', then the player cannot
     modify any of the side's names.  Defaults to `false'.


File: xcdesign.info,  Node: Side Class,  Next: Status in Game,  Prev: Side Name Properties,  Up: Side and Player Forms

3.4.2 Side Class
----------------

 -- SideProperty: `class' str
     This property is a side's class, which is a keyword that
     characterizes the side.  Any number of sides may be in the same
     class.


File: xcdesign.info,  Node: Status in Game,  Next: Side Relationships,  Prev: Side Class,  Up: Side and Player Forms

3.4.3 Status in Game
--------------------

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

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

 -- SideProperty: `status' lose/draw/win
     This property tells how this side did in the game.  Defaults to
     `draw'.

 -- GlobalConstant: `win'

 -- GlobalConstant: `draw'

 -- GlobalConstant: `lose'
     These constants are the different possible values for a side's
     status.

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

 -- SideProperty: `advantage' n

 -- SideProperty: `advantage-min' n

 -- SideProperty: `advantage-max' n
     Initial and min/max limits on advantage for the side.  All default
     to the values of the corresponding global variables.


File: xcdesign.info,  Node: Side Relationships,  Next: Numbering Units,  Prev: Status in Game,  Up: Side and Player Forms

3.4.4 Side Relationships
------------------------

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

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

 -- SideProperty: `controlled-by' side
     This property refers to the side controlling this one.  If 0, then
     the side is not under control.

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

 -- SideProperty: `trusts' side-value-list
     This property is true for any side that is trusted by this side.
     Note that this relationship need not be symmetrical.  Defaults to
     `false' for all sides.

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

 -- SideProperty: `trades' side-value-list
     This property defines the trading relationship with other sides.


File: xcdesign.info,  Node: Numbering Units,  Next: Side-Specific Namers,  Prev: Side Relationships,  Up: Side and Player Forms

3.4.5 Numbering Units
---------------------

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

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


File: xcdesign.info,  Node: Side-Specific Namers,  Next: Side Tech Levels,  Prev: Numbering Units,  Up: Side and Player Forms

3.4.6 Side-Specific Namers
--------------------------

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

 -- SideProperty: `unit-namers' utype-value-list
     This property specifies which namers will be used with which types
     that the side starts out with or creates new units.  These will
     not be run automatically on captured units or gifts.

 -- SideProperty: `feature-namers' feature-type-value-list
     This property specifies which namers to use with which geographical
     features in the side's initial country (if if has one).  Defaults
     to `()'.


File: xcdesign.info,  Node: Side Tech Levels,  Next: Side Views,  Prev: Side-Specific Namers,  Up: Side and Player Forms

3.4.7 Side Tech Levels
----------------------

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

 -- SideProperty: `tech' utype-value-list
     This property assigns a tech level to each unit type named.

 -- SideProperty: `init-tech' utype-value-list
     This property is the tech level at the beginning of the current
     turn.

 -- SideProperty: `advance' atype-value-list
     This property is the state of the side's research on each advance.
     A value of -1 indicates that the advance has been achieved.


File: xcdesign.info,  Node: Side Views,  Next: Interaction,  Prev: Side Tech Levels,  Up: Side and Player Forms

3.4.8 Side Views
----------------

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

   These properties are necessary only if the relevant globals are set a
certain way (`see-all' is false, etc).

 -- SideProperty: `terrain-view' layer-data...
     This property is the side's current knowledge of the world's
     terrain.  Defaults to `()'.

 -- SideProperty: `terrain-view-dates' layer-data...
     This property is the dates of the side's current knowledge of the
     world's terrain.  Defaults to `()'.

 -- SideProperty: `aux-terrain-view' ttype layer-data...
     This property is the side's current knowledge of the world's aux
     terrain of type TTYPE.  Defaults to `()'.

 -- SideProperty: `aux-terrain-view-dates' ttype layer-data...
     This property is the dates of the side's current knowledge of the
     world's aux terrain of type TTYPE.  Defaults to `()'.

 -- SideProperty: `unit-views' unit-view...
     This property is the side's current knowledge of the positions of
     units in the world.  It is a list of UNIT-VIEW objects, where each
     has the forms `(type side id x y)'.  Defaults to `()'.

 -- SideProperty: `material-view' mtype layer-data...
     This property is the side's current knowledge of the amounts of
     each type of material at each location in the world.  Defaults to
     `()'.

 -- SideProperty: `material-view-dates' ttype layer-data...
     Defaults to `()'.

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

 -- SideProperty: `temperature-view' layer-data...
     Defaults to `()'.

 -- SideProperty: `temperature-view-dates' layer-data...
     Defaults to `()'.

 -- SideProperty: `cloud-view' layer-data...
     Defaults to `()'.

 -- SideProperty: `cloud-bottom-view' layer-data...
     Defaults to `()'.

 -- SideProperty: `cloud-height-view' layer-data...
     Defaults to `()'.

 -- SideProperty: `cloud-view-dates' layer-data...
     Defaults to `()'.

 -- SideProperty: `wind-view' layer-data...
     Defaults to `()'.

 -- SideProperty: `wind-view-dates' layer-data...
     Defaults to `()'.


File: xcdesign.info,  Node: Interaction,  Next: Doctrine,  Prev: Side Views,  Up: Side and Player Forms

3.4.9 Interaction
-----------------

 -- SideProperty: `initial-center-at' x y
     This property is the preferred location at which to center the
     first map displayed by an interface.

 -- SideProperty: `turn-time-used' seconds
     This property is the number of (real) seconds that this side has
     been moving units during the present turn.

 -- SideProperty: `total-time-used' seconds
     This property is the number of (real) seconds that this side has
     been moving units during the course of the game.

 -- SideProperty: `timeouts' n
     This property is the number of "time outs" a side gets for the
     game.

 -- SideProperty: `timeouts-used' n
     This property is the number of "time outs" a side has already used
     up.

 -- SideProperty: `finished-turn' t/f
     This property is true if the side has declared that it is finished
     moving things during this turn.  Defaults to `false'.

 -- SideProperty: `willing-to-draw' t/f
     This property is true if the side will go along with any other
     side that wants to end the game in a draw.  Defaults to `false'.


File: xcdesign.info,  Node: Doctrine,  Next: Other Side Properties,  Prev: Interaction,  Up: Side and Player Forms

3.4.10 Doctrine
---------------

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

 -- SideProperty: `doctrines' utype-property-groups...
     This property is the side's unit-type-specific doctrine.  Each
     UTYPE-PROPERTY-GROUP has the form `(UNIT-TYPES doctrine)'.
     Defaults to `()'.

 -- SideProperty: `doctrines-locked' t/f
     This property says whether the docrine-unit type correspondence
     for the side may be altered during the game.  This property does
     not control whether or not the properties of the doctrines may be
     altered.  Defaults to `false'.

 -- SideProperty: `default-doctrine' doctrine-id
     This property is the base doctrine that applies to all unit types
     by default.

 -- Form: `doctrine' [ id ] properties...
     This form creates a doctrine with the given id and properties.

 -- DoctrineProperty: `resupply-percent' n%
     This property indicates that when the level of a
     operationally-consumed material is at N% of capacity, try to
     resupply.  Defaults to `50'.

 -- DoctrineProperty: `rearm-percent' n%
     This property indicates that when the level of a combat-consumed
     material is at N% of capacity, try to resupply.

 -- DoctrineProperty: `repair-percent' n%
     This property indicates that when the unit's hp is at N% of max,
     make a plan to repair.

 -- DoctrineProperty: `construction-run' type-value-list
     This property is the default number of units to build when
     construction has been requested.

 -- DoctrineProperty: `locked' t/f
     This property is true if the properties of the doctrine cannot be
     modified by the side's player during the game.  Defaults to
     `false'.


File: xcdesign.info,  Node: Other Side Properties,  Next: Independent Side,  Prev: Doctrine,  Up: Side and Player Forms

3.4.11 Other Side Properties
----------------------------

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

 -- SideProperty: `units' list
     This property is a weighted list of units that could be given to
     the side during setup in order to satisfy the side's `start-with'
     numbers.

 -- SideProperty: `treasury' mtype-value-list
     This property is the quantity of each type of material belonging
     to the side as a whole, independent of materials in specific units.

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

 -- SideProperty: `action-priorities' (utype val)...
     This property is the acting priority of units belonging to the
     side.

 -- SideProperty: `scores' (skid val)...
     This property is the current values of any numeric scores being
     kept for the side.  It is a list of pairs of scorekeeper id and
     value.  Defaults to `()'.

 -- SideProperty: `attack-stats' n...

 -- SideProperty: `hit-stats' n...
     These properties are the raw counts of attacks and hits, by
     attacking and defending unit types.  Default to `()'.

 -- SideProperty: `gain-counts' n...

 -- SideProperty: `loss-counts' n...
     These properties are the raw counts of unit gains and losses,
     organized by unit type and gain/loss reason.

 -- Form: `independent-units' properties...
     Like the `side' form, but sets properties for independent units.

 -- SideProperty: `ui-data' data...
     This property contains interface-specific data for the side.  This
     is mainly for preservation across game save/restores.  The
     property's value has the form
          `((interface-type data) (interface-type data) ...)'
     so that each interface can maintain its own data separately.

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

 -- SideProperty: `standing-order' data...
     This property contains the list of standing orders for the side.

 -- GlobalConstant: `always'
     This symbol indicates a standing order that is always to be
     executed by a unit.

 -- GlobalConstant: `@'
     This symbol indicates a standing order that units of the specified
     types are to execute when at a given location.

 -- GlobalConstant: `in'
     This symbol indicates a standing order that units of the specified
     types are to execute when occupying a given unit.

 -- GlobalConstant: `near'
     This symbol indicates a standing order that units of the specified
     types are to execute when within a given distance of a given
     location.


File: xcdesign.info,  Node: Independent Side,  Next: Players,  Prev: Other Side Properties,  Up: Side and Player Forms

3.4.12 Independent Side
-----------------------

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

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

 -- GlobalVariable: `indepside-has-ai' t/f
     This is true if an AI should be created for the independent side.

 -- GlobalVariable: `indepside-can-build' t/f
     This is true if independent units may construct new units.

 -- GlobalVariable: `indepside-can-develop' t/f
     This is true if independent units may develop their technology.


File: xcdesign.info,  Node: Players,  Next: Rules of Side Configuration,  Prev: Independent Side,  Up: Side and Player Forms

3.4.13 Players
--------------

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

 -- SideProperty: `player' id
     This property is the unique identifier of a player that is running
     this side.  Defaults to `0', which means that no player has been
     assigned to the side.

 -- Form: `player' [ id ] properties...
     This form defines a player.  If the ID is supplied and matches the
     id of an existing player, then the player object is updated using
     the PROPERTIES, otherwise a new player object will be created,
     using the given ID if supplied, otherwise creating a new value.

 -- GlobalVariable: `player-sides-locked' t/f
     This variable is `true' if the player/side assignment may not be
     changed while the game is starting up.  Defaults to `false'.

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

 -- PlayerProperty: `name' str
     This property identifies the player by name.

 -- PlayerProperty: `config-name' str
     This property identifies a particular set of doctrine and other
     definitions that the player is using.

 -- PlayerProperty: `display-name' str
     This property identifies the display being used by the player's
     interface.  The interpretation of this value is dependent on the
     interface in use.

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

 -- PlayerProperty: `password' str
     This property is the encoding of a password that must be entered
     before this player object can be reused successfully.

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

 -- GlobalVariable: `advantage-min' n

 -- GlobalVariable: `advantage-max' n

 -- GlobalVariable: `advantage-default' n
     These variables set the bounds and default values for players'
     initial advantages.  Default to `1', `9999', and `1', respectively.

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


File: xcdesign.info,  Node: Rules of Side Configuration,  Prev: Players,  Up: Side and Player Forms

3.4.14 Rules of Side Configuration
----------------------------------

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

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

   * The `side' form for the side.

   * The `side-defaults' form for the game.

   * General program defaults.


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


File: xcdesign.info,  Node: Unit Forms,  Next: Agreements,  Prev: Side and Player Forms,  Up: Reference Manual

3.5 Unit Forms
==============

The basic `unit' form creates or modifies a unit.

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

 -- Form: UNIT-TYPE-NAME x y [ side-id ] properties...
     This is an abbreviated form, in which the x,y position is
     required, and an optional side id may be included.  The side id
     will come from `unit-defaults' if not specified.  The
     UNIT-TYPE-NAME may be any valid unit type name or defined name.
     This form always results in a new unit.

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

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

 -- Symbol: `reset'
     This is the symbol used to reset unit defaults; see above.

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

* Menu:

* Unit Properties::
* Unit Action State::
* Unit Plan::
* Goal Types::
* Task Types::


File: xcdesign.info,  Node: Unit Properties,  Next: Unit Action State,  Up: Unit Forms

3.5.1 Unit Properties
---------------------

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

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

 -- UnitProperty: `z' z
     This property is identical to the optional z part of the `@'
     property.

 -- UnitProperty: `s' side
     This property is the side of the unit.  It can be either a side
     name, noun, or adjective (string) or an id (number).  A value of
     `0' or `"independent"' means that the unit is independent.

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

 -- UnitProperty: `#' n
     This property is the unique numeric id of the unit.  Defaults to a
     game-selected value.

 -- UnitProperty: `n' str
     This property is the name of the unit.

 -- UnitProperty: `nb' n
     This property is the number of the unit, which starts at `1' and
     goes up.  Defaults to `0', which means that the unit is unnumbered.

 -- UnitProperty: `cp' n
     This property is the current completeness of the unit.  If
     negative, indicates that the unit will appear at a time and place
     specified by the `appear' x-property.  Defaults to the `cp-max'
     for the type.

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

 -- UnitProperty: `cxp' cxp
     This property is the combat experience of the unit.  Experience
     starts at 0 for new units and goes up with each engagement in
     combat.

 -- UnitProperty: `mo' n
     This property is the morale of the unit.  Morale ranges from 0 to a
     maximum set by `morale-max'.

 -- UnitProperty: `trk' n
     This property is a bit vector indicating the sides that are
     currently tracking the unit's movements.  The unit's own side is
     not included.

 -- UnitProperty: `m' mtype-value-list
     This property is the amounts of supplies being carried by the unit.
     Defaults to `0' for each material type.

 -- UnitProperty: `tp' utype-value-list
     This property is the level of tooling to build each type of unit.
     Defaults to `0' for each unit type.

 -- UnitProperty: `in' x
     This property is the id, name, or symbol of the unit's transport.
     Defaults to `0', meaning that unit is not in any transport.

 -- UnitProperty: `opinions' side-value-list...
     This property is the unit's true feelings towards each side,
     including its own side.  Defaults to `0' for each side.

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

 -- UnitProperty: `disappear' n
     This property is the turn on which a unit will disappear from the
     game.  Occupants will be ejected if possible; otherwise they will
     disappear also.  Defaults to `-1'.

 -- UnitProperty: `autoplan' n
     This property is true when the unit should choose its own research
     topics.

 -- UnitProperty: `autobuild' n
     This property is true when the unit should choose its own
     construction task.

 -- UnitProperty: `autoresearch' n
     This property is true when the unit should choose its own research
     topics.

 -- UnitProperty: `curadv' n
     This property is the current advance that the unit is researching.

 -- UnitProperty: `popul' n
     This property is the unit's population (currently unused).

 -- UnitProperty: `prod' mtype-value-list
     This property is the unit's production for each material type.

 -- UnitProperty: `sym' symbol
     This property is a symbol that is unique to this unit.  This
     symbol may appear instead of a unit id, for instance as the value
     of the property `in'.  Defaults to `()'.

 -- UnitProperty: `sides' list
     This property is a list of side names that the unit may be given to
     during setup.  (See side property `units'.)  Defaults to `()'.


File: xcdesign.info,  Node: Unit Action State,  Next: Unit Plan,  Prev: Unit Properties,  Up: Unit Forms

3.5.2 Unit Action State
-----------------------

 -- UnitProperty: `acp' n
     This property is the number of action points left to the unit for
     this turn.

 -- UnitProperty: `acp0' n
     This property is the initial number of action points for this turn,
     computed at the beginning of the turn.

 -- UnitProperty: `am' n
     This property is the actual number of moves (cell entries)
     executed so far in the current turn.

 -- UnitProperty: `a' action
     This property is the next action that the unit will perform.


File: xcdesign.info,  Node: Unit Plan,  Next: Goal Types,  Prev: Unit Action State,  Up: Unit Forms

3.5.3 Unit Plan
---------------

 -- UnitProperty: `plan' type [ creation-turn ] properties...
     This property describes the unit's current plan.

 -- PlanType: `none'
     A unit with this type of plan does nothing.  It is used when a
     side has no player.

 -- PlanType: `passive'
     This plan type is for units on a side that is being run directly
     by the side.  This is the normal plan type for units when a human
     player is playing.

 -- PlanType: `defensive'
     This plan type is for units that defend areas or other units.

 -- PlanType: `offensive'
     This plan type is for units that are to be aggressive.

 -- PlanType: `exploratory'
     This plan type is for units that explore the world.

 -- PlanType: `colonizing'
     This plan type is for units to build more units (like cities) that
     can themselves build more units.

 -- PlanType: `improving'
     This plan type is for units to improve themselves, such as by
     adding special types of occupants.

 -- PlanType: `random'
     A unit with this plan type will act randomly.

 -- PlanProperty: `goal' goal
     This property is the main goal of a unit's plan.  Defaults to `()'.

 -- PlanProperty: `formation' goal
     This property is the formation goal of a unit's plan.  If defined,
     it is a position goal that the unit should try to achieve when it
     is not trying to achieve the main goal.  Defaults to `()'.

 -- PlanProperty: `tasks' tasks...
     This property is the complete task agenda for the unit's plan.  It
     is a list of tasks.  Defaults to `()'.

 -- PlanProperty: `asleep' t/f
     This property is true if the unit is asleep.  Defaults to `false'.

 -- PlanProperty: `reserve' t/f
     This property is true if the unit is in reserve.  Defaults to
     `false'.

 -- PlanProperty: `delayed' t/f
     This property is true if the unit's activity has been delayed
     until all others have acted.  Defaults to `false'.

 -- PlanProperty: `wait' t/f
     This property is true if the unit is waiting for orders.  Defaults
     to `false'.

 -- PlanProperty: `ai-control' t/f
     This property is true if the unit can be controlled by any AI
     associated with the side.  Defaults to `true'.

 -- PlanProperty: `supply-alarm' t/f
     This property is true if the unit should react when supply is low.
     Defaults to `false'.

 -- PlanProperty: `supply-is-low' t/f
     This property is true if the unit considers its supply to be low.
     Defaults to `false'.

 -- PlanProperty: `wait-transport' t/f
     This property is true if the unit is waiting for transport.
     Defaults to `false'.

 -- PlanProperty: `initial-turn' turn
     This property is the turn upon which a plan should go into effect.

 -- PlanProperty: `final-turn' turn
     This property is the turn upon which a plan should be removed.  If
     the value is `0', then the plan is not scheduled to be removed.


File: xcdesign.info,  Node: Goal Types,  Next: Task Types,  Prev: Unit Plan,  Up: Unit Forms

3.5.4 Goal Types
----------------

The possible types of goals are these:

 -- GoalType: `no-goal'

 -- GoalType: `won-game'

 -- GoalType: `lost-game'

 -- GoalType: `world-is-known'

 -- GoalType: `vicinity-is-known'

 -- GoalType: `positions-known'

 -- GoalType: `cell-is-occupied'

 -- GoalType: `vicinity-is-held'

 -- GoalType: `has-unit-type'

 -- GoalType: `has-unit-type-near'

 -- GoalType: `has-material-type'

 -- GoalType: `keep-formation'

 -- GoalType: `find-spot-to-build'


File: xcdesign.info,  Node: Task Types,  Prev: Goal Types,  Up: Unit Forms

3.5.5 Task Types
----------------

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

 -- TaskType: `build' ex re u n n2 unit-id
     This type of task directs the unit to build N units of type U.  N2
     is the number already built in the run and UNIT-ID is the
     (optional) id of a unit already being built.

 -- TaskType: `capture' ex re unit-id

 -- TaskType: `collect' m x y
     This type of task directs the unit to acquire material of type M
     at or around X,Y and to deliver it to the nearest unit that can
     accept the material.

 -- TaskType: `disband' ex re
     This type of task directs the unit to disband itself.

 -- TaskType: `hit-position' ex re x y z
     This type of task directs the unit to attack or fire on any
     unfriendly units at the given location.

 -- TaskType: `hit-unit' ex re unit-id

 -- TaskType: `move-dir' ex re dir n
     This type of task directs the unit to move in direction DIR for a
     distance of N cells.

 -- TaskType: `move-to' ex re x y z dist
     This type of task directs the unit to move to a distance of no
     more than DIST cells from the given location.

 -- TaskType: `occupy' ex re unit-id
     This type of task directs the unit to attempt to enter the given
     UNIT-ID, moving adjacent to it first if necessary.

 -- TaskType: `pickup' ex re unit-id
     This type of task directs the unit to move towards the given
     UNIT-ID.

 -- TaskType: `repair' ex re unit-id

 -- TaskType: `resupply' ex re
     This type of task directs the unit to replenish its supplies,
     whether by doing more production or by moving to another unit that
     has supplies available.

 -- TaskType: `sentry' ex re n
     This task type directs the unit to stay where it is for the next N
     turns.


File: xcdesign.info,  Node: Agreements,  Next: Scorekeeper Forms,  Prev: Unit Forms,  Up: Reference Manual

3.6 Agreements
==============

 -- Form: `agreement' [ id ] properties...
     This form defines an agreement among a set of sides.  The name/id
     is a unique internal identifier.

 -- AgreementProperty: `type-name' str
     This property is the name of the general type of agreement, such a
     trade.  Defaults to `""'.

 -- AgreementProperty: `title' str
     This property is the player-visible name of the agreement.
     Defaults to `""'.

 -- AgreementProperty: `terms' forms...
     This property is the list of terms of the agreement.  Defaults to
     `()'.

 -- AgreementProperty: `drafters' side-list
     This property is the set of sides writing the agreement.  Only
     drafting sides may modify an agreement.

 -- AgreementProperty: `proposers' side-list
     This property is the set of sides that initially proposed the
     agreement.

 -- AgreementProperty: `signers' side-list
     Before the agreement is made, this property is the proposed list of
     participants.  After the agreeement is made, this is the actual
     list of participants.

 -- AgreementProperty: `willing-to-sign' side-list
     This property is all the sides that have already agreed to this
     agreement, on condition that all the other sides accept it.

 -- AgreementProperty: `known-to' side-list
     This property is the set of sides that are to know about the
     agreement when it is signed.

 -- AgreementProperty: `enforcement' form

 -- AgreementProperty: `state' state


File: xcdesign.info,  Node: Scorekeeper Forms,  Next: History Forms,  Prev: Agreements,  Up: Reference Manual

3.7 Scorekeeper Forms
=====================

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

 -- Form: `scorekeeper' name properties...
     This form creates or modifies a scorekeeper with the given NAME,
     with the given PROPERTIES.

* Menu:

* Scorekeeper Properties::
* Scorekeeper Bodies::
* Scorekeeper Functions::
* Scorefile::


File: xcdesign.info,  Node: Scorekeeper Properties,  Next: Scorekeeper Bodies,  Up: Scorekeeper Forms

3.7.1 Scorekeeper Properties
----------------------------

 -- ScorekeeperProperty: `title' str
     This property is a string that identifies the scorekeeper to the
     players.  Defaults to `""'.

 -- ScorekeeperProperty: `when' (type [ exp ])
     This property is when the scorekeeper will be checked or updated.
     Defaults to `after-turn'.

 -- ScorekeeperWhenType: `before-turn' exp
     This indicates that the scorekeeper will run at the start of each
     turn matching EXP, or after every turn if EXP is not given.

 -- ScorekeeperWhenType: `after-turn' exp
     This indicates that the scorekeeper will run at the end of each
     turn matching EXP, or after every turn if EXP is not given.

 -- ScorekeeperWhenType: `after-event' exp
     This indicates that the scorekeeper will run after every event
     matching EXP, or after every event if EXP is not given.

 -- ScorekeeperWhenType: `after-action' exp
     This indicates that the scorekeeper will run at the end of each
     action matching EXP, or after every action if EXP is not given.

 -- ScorekeeperProperty: `applies-to' side-list
     This property is the set of sides or side classes to which the
     scorekeeper applies.  Scorekeepers apply only to sides that are in
     the game.  Defaults to `side*'.

 -- ScorekeeperProperty: `known-to' side-list
     This property is the list of sides that know about this
     scorekeeper, and can see the value of the score for each side that
     it applies to.  Defaults to `side*'.

 -- ScorekeeperProperty: `trigger' form
     This property is an expression that is true when it is time to
     start checking the scorekeeper's main test.  Once a scorekeeper is
     triggered, it remains active.  Defaults to `false'.

 -- ScorekeeperProperty: `triggered' t/f
     This property is true if the scorekeeper is currently triggered.
     Defaults to `true'.

 -- ScorekeeperProperty: `do' forms...
     This property is a list of forms to execute in order each time the
     scorekeeper runs.  Defaults to `()'.

 -- ScorekeeperProperty: `initial' value
     This property is the value of the score upon game startup.  If this
     value is `-9999', the scorekeeper does not maintain a numeric
     score.  Defaults to `-9999'.


File: xcdesign.info,  Node: Scorekeeper Bodies,  Next: Scorekeeper Functions,  Prev: Scorekeeper Properties,  Up: Scorekeeper Forms

3.7.2 Scorekeeper Bodies
------------------------

The forms in the body (the `do' property) of the scorekeeper may be any
of the forms listed here.

 -- ScorekeeperForm: `last-side-wins'
     If supplied as the only symbol in the body, then the scorekeeper
     implements the usual "last side left in the game wins" behavior.

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

 -- ScorekeeperForm: `if' test action
     If the test evaluates to `true' or any nonzero number, then the
     action will be done.

 -- ScorekeeperForm: `cond' (test actions...) ...
     This is like Lisp's cond.

 -- ScorekeeperForm: `win' [ sides ] [ own-message ] [ other-message ]
     This scorekeeper action causes the side to win immediately.

 -- ScorekeeperForm: `lose' [ sides ] [ own-message ] [ other-message ]
     This scorekeeper action causes the side to lose immediately.

 -- ScorekeeperForm: `end' [ message ]
     This scorekeeper action ends the game immediately, with a draw for
     all remaining sides.

 -- ScorekeeperForm: `add' exp [ side ]
     This adds the result of evaluating EXP to the score of the given
     side.  The value may be a negative number.


File: xcdesign.info,  Node: Scorekeeper Functions,  Next: Scorefile,  Prev: Scorekeeper Bodies,  Up: Scorekeeper Forms

3.7.3 Scorekeeper Functions
---------------------------

 -- ScorekeeperFunction: `and' exps
     The result is true if all the operands are true.

 -- ScorekeeperFunction: `or' exps
     The result is true if any of the operands are true.

 -- ScorekeeperFunction: `not' exp

 -- ScorekeeperFunction: `=' exp1 exp2

 -- ScorekeeperFunction: `/=' exp1 exp2

 -- ScorekeeperFunction: `>' exp1 exp2

 -- ScorekeeperFunction: `>=' exp1 exp2

 -- ScorekeeperFunction: `<' exp1 exp2

 -- ScorekeeperFunction: `<=' exp1 exp2

 -- ScorekeeperFunction: `sum' types property [ test ]
     The result is the sum of the property values for all units of the
     given type(s).  The optional TEST filters the set of units being
     tested.


File: xcdesign.info,  Node: Scorefile,  Prev: Scorekeeper Functions,  Up: Scorekeeper Forms

3.7.4 Scorefile
---------------

 -- GlobalVariable: `scorefile-name' str
     This variable supplies the name of the file to be used for
     recording scores of people playing the game.  The default value is
     `""', which disables the recording of scores.


File: xcdesign.info,  Node: History Forms,  Next: Types in General,  Prev: Scorekeeper Forms,  Up: Reference Manual

3.8 History Forms
=================

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

 -- Form: `evt' date type sides data
     This form creates a single historical event.  The DATE is the turn
     of the event's occurrence, while the SIDES is a bit mask of sides
     that know about the event, or `all' if all sides know about it.

 -- Symbol: `all'
     This is a shorthand for the bitmask of all sides in the game.

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

 -- EventType: `log-started'
     This event records when the recording of events began.  Multiple
     instances of this may occur, for instance if logging were to be
     turned off and then on again.

 -- EventType: `log-ended'

 -- EventType: `game-started'
     This event records the actual start of the game.  There should
     only be one in a game's history.

 -- EventType: `game-saved'
     This event records that the game was saved.

 -- EventType: `game-restarted'
     This event records that the game was restored and restarted from a
     saved game.

 -- EventType: `game-ended'

 -- EventType: `side-joined' side
     This event records when a side joined the game.

 -- EventType: `side-lost' side scorekeeper
     This event records when a side lost.

 -- EventType: `side-won' side scorekeeper
     This event records when a side won.

 -- EventType: `side-withdrew' side
     This event records when a side withdrew from the game.

 -- EventType: `unit-created' side unit
     This event records the creation of a unit.

 -- EventType: `unit-completed' side unit
     This event records the completion of a unit.

 -- EventType: `unit-acquired'
     This event records the acquisition of a unit, for instance as a
     gift from another side.

 -- EventType: `unit-captured'
     This event records the capture of a unit, as an outcome of combat
     or from a direct attempt to capture.

 -- EventType: `unit-moved' unit x1 y1 x2 y2
     This event records the movement of a unit.

 -- EventType: `unit-name-changed' unit1 unit2
     This event records that a unit's name was changed.  UNIT1 will be
     an ex-unit representing the unit under its previous name.

 -- EventType: `unit-type-changed' unit1 unit2
     This event records that a unit's type was changed.  UNIT1 will be
     an ex-unit representing the unit with its previous type.

 -- EventType: `unit-assaulted' unit1 unit2 x y

 -- EventType: `unit-damaged' unit hp1 hp2
     This event records that a unit's hp was reduced from HP1 to HP2.

 -- EventType: `unit-killed' unit

 -- EventType: `unit-died-in-accident' unit

 -- EventType: `unit-died-from-temperature' unit

 -- EventType: `unit-vanished' unit

 -- EventType: `unit-wrecked' unit

 -- EventType: `unit-wrecked-in-accident' unit

 -- EventType: `unit-revolted' unit

 -- EventType: `unit-surrendered' unit

 -- EventType: `unit-garrisoned' unit

 -- EventType: `unit-disbanded' unit

 -- EventType: `unit-starved' unit

 -- EventType: `unit-left-world' unit

 -- EventType: `unit-merged' unit

 -- EventType: `unit-gone' unit

   The following event types are the results of actions.

 -- EventType: `action-ok'

 -- EventType: `action-error'

 -- EventType: `cannot-do'

 -- EventType: `insufficient-acp'

 -- EventType: `insufficient-material'

 -- EventType: `too-far'

 -- EventType: `too-near'

 -- EventType: `action-done'

 -- EventType: `insufficient-mp'

 -- EventType: `blocking-zoc'
     Unit was unable to move because of another unit's zone of control.

 -- EventType: `cannot-leave-world'

 -- EventType: `destination-full'

 -- EventType: `overrun-succeeded'

 -- EventType: `overrun-failed'

 -- EventType: `capture-succeeded'

 -- EventType: `capture-failed'

 -- EventType: `fire-into-outside-world'

 -- EventType: `build-completed'


File: xcdesign.info,  Node: Types in General,  Next: Unit Types,  Prev: History Forms,  Up: Reference Manual

3.9 Types in General
====================

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

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

* Menu:

* Type Names::
* Type Images::
* Documentation::


File: xcdesign.info,  Node: Type Names,  Next: Type Images,  Up: Types in General

3.9.1 Type Names
----------------

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

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

 -- TypeProperty: `long-name' string
     This property is a fully spelled-out name for the type.  Defaults
     to `""'.  (At present, this property is only defined for unit
     types.)

 -- TypeProperty: `short-name' string
     This property is an abbreviated name of for the type.  Defaults to
     `""'.  (At present, this property is only defined for unit types.)

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

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

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


File: xcdesign.info,  Node: Type Images,  Next: Documentation,  Prev: Type Names,  Up: Types in General

3.9.2 Type Images
-----------------

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

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

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

 -- TypeProperty: `char' str
     This property supplies a single character for this type (all
     characters after the first one in STR are ignored).  Defaults to
     `""'.  (This property is not defined for advance types.)

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


File: xcdesign.info,  Node: Documentation,  Prev: Type Images,  Up: Types in General

3.9.3 Documentation
-------------------

 -- TypeProperty: `help' string
     This property is a brief (preferably one-line) description of the
     type.  Defaults to `""'.

 -- TypeProperty: `notes' strings...
     This property is detailed documentation about the type.  The
     formatting of the strings is up to the interface, but in general
     each string is a separate line, the string `""' indicates a line
     break, and two `""' in a row indicates a paragraph break.
     Defaults to `()'.


File: xcdesign.info,  Node: Unit Types,  Next: Terrain Types,  Prev: Types in General,  Up: Reference Manual

3.10 Unit Types
===============

 -- Form: `unit-type' symbol properties...
     This form defines a new type of unit.  The SYMBOL is required and
     must be previously undefined.  The bindings in PROPERTIES are then
     added to the type one by one.  If no other name properties are
     defined, the SYMBOL may be displayed to players (see above).  You
     can define no more than 126 types of units.

   The SYMBOL here becomes the unit type's "internal type name" which
is guaranteed unique.  To make synonyms for the internal type name, use
`define'.

 -- GlobalVariable: `u*'
     This variable evaluates to a list of all unit types, listed in the
     order that they were defined.  This list always reflects the list
     of types at the moment it is evaluated.

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

 -- UnitTypeProperty: `name-internal' str
     Internally used type name.

* Menu:

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


File: xcdesign.info,  Node: Unit Naming,  Next: Availability,  Up: Unit Types

3.10.1 Unit Naming
------------------

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

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

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


File: xcdesign.info,  Node: Availability,  Next: Class-Restricted Unit Types,  Prev: Unit Naming,  Up: Unit Types

3.10.2 Availability
-------------------

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

 -- UnitTypeProperty: `available' n
     If the value of this property is greater than 0, then this type is
     available in the game on or after turn N.  If the value is less
     than 0, then the type is available, but only until turn -N.  If
     the value is 0, then the type is never available.  Defaults to `1',
     which means that the type is always available.

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


File: xcdesign.info,  Node: Class-Restricted Unit Types,  Next: Self-Unit Capable Units,  Prev: Availability,  Up: Unit Types

3.10.3 Class-Restricted Unit Types
----------------------------------

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

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

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


File: xcdesign.info,  Node: Self-Unit Capable Units,  Next: Limits on Unit Quantities,  Prev: Class-Restricted Unit Types,  Up: Unit Types

3.10.4 Self-Unit Capable Units
------------------------------

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

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

 -- UnitTypeProperty: `can-be-self' t/f
     This property says that the type of unit can represent the side
     directly.  Defaults to `false'.

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

 -- UnitTypeProperty: `self-resurrects' t/f
     This property is true if when the self-unit dies, another unit of
     an allowable type becomes the self-unit automatically.  Defaults to
     `false'.

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

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

 -- TableUU: `unit-control-chance-at' u1 u2 -> n%

 -- TableUU: `unit-control-chance-adjacent' u1 u2 -> n%

 -- TableUU: `unit-control-chance' u1 u2 -> n%

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


File: xcdesign.info,  Node: Limits on Unit Quantities,  Next: Hit Points,  Prev: Self-Unit Capable Units,  Up: Unit Types

3.10.5 Limits on Unit Quantities
--------------------------------

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

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

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

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

 -- UnitTypeProperty: `type-in-game-max' n
     This property is the maximum total of the given type, for all sides
     together.  Defaults to `-1', which means that there is no limit.

 -- UnitTypeProperty: `type-per-side-max' n
     This property is the maximum number of units of the given type
     allowed to each side.  Defaults to `-1', which means that there is
     no limit.


File: xcdesign.info,  Node: Hit Points,  Next: Experience,  Prev: Limits on Unit Quantities,  Up: Unit Types

3.10.6 Hit Points
-----------------

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

 -- UnitTypeProperty: `hp-max' n
     This property is the maximum number of hit points for (each part
     of) a unit.  Completed units start with this many hit points.
     Defaults to `1'.

 -- UnitTypeProperty: `parts-max' n
     This property declares that a unit is really an aggregate of N
     smaller identical units.  Defaults to `1'.

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

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

 -- UnitTypeProperty: `hp-recovery' n
     This property is the number of 1/100 hp recovered per turn.
     Recovery happens automatically at the end of each turn.  The
     amount n / 100 is recovered automatically each turn, while n mod
     100 is the percent chance of recovering an additional 1 hit point.

 -- UnitTypeProperty: `hp-to-recover' hp
     This property is the minimum number of hp that the unit must have
     for hp recovery to work.


File: xcdesign.info,  Node: Experience,  Next: Tech Levels vs Units,  Prev: Hit Points,  Up: Unit Types

3.10.7 Experience
-----------------

 -- UnitTypeProperty: `cxp-max' cxp
     This property is the maximum combat experience this type of unit
     can have.


File: xcdesign.info,  Node: Tech Levels vs Units,  Next: Opinions,  Prev: Experience,  Up: Unit Types

3.10.8 Tech Levels vs Units
---------------------------

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

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

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

 -- UnitTypeProperty: `tech-to-see' tl
     This property is the minimum tech level that a side must have
     before it can see a unit of this type.

 -- UnitTypeProperty: `tech-to-own' tl
     This property is the minimum tech level that a side must have in
     order to have a unit of this type.

 -- UnitTypeProperty: `tech-from-ownership' tl
     This property is the tech level that may be reached by acquiring a
     unit of this type.  Since this is expressed as a minimum, multiple
     acquisitions have no additional effect.

 -- UnitTypeProperty: `tech-to-use' tl
     This property is the minimum tech level that a side must have in
     order to give actions to this type of unit.

 -- UnitTypeProperty: `tech-to-build' tl
     This property is the minimum tech level that a side must have in
     order to build this type of unit.

 -- UnitTypeProperty: `tech-max' tl
     This property is the absolute maximum tech level possible for this
     type.

 -- TableUU: `tech-crossover' u1 u2 -> n%
     This table is the minimum tech level for U2 that is guaranteed by
     a particular tech level for U1, expressed as a percentage of the
     `tech-max' for the types.  For instance, if `tech-crossover' is
     80, and the tech level for U1 is 10 out of a max of 20, and the
     max for U2 is also 20, then the side has a tech for U2 at least 8.

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

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


File: xcdesign.info,  Node: Opinions,  Next: Point Value,  Prev: Tech Levels vs Units,  Up: Unit Types

3.10.9 Opinions
---------------

 -- UnitTypeProperty: `opinion-min' n

 -- UnitTypeProperty: `opinion-max' n
     These properties are the bounds of the strength of a unit's opinion
     about the sides, both other sides and its own.

 -- UnitTypeProperty: `courage-min' n

 -- UnitTypeProperty: `courage-max' n

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

 -- UnitTypeProperty: `morale-max' n
     This property is the maximum morale that the unit may have.

 -- TableUT: `morale-terrain-effect' u t -> n
     This table is the effect of the terrain at a unit's location on its
     morale.

 -- UnitTypeProperty: `morale-recovery' .01n
     This property is the amount of morale increase for a unit each
     turn, in 1/100ths of a point of morale.  Defaults to `0'.


File: xcdesign.info,  Node: Point Value,  Next: Advanced Units,  Prev: Opinions,  Up: Unit Types

3.10.10 Point Value
-------------------

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

 -- UnitTypeProperty: `point-value' n
     This property is the "value" of a unit.  Defaults to `1'.


File: xcdesign.info,  Node: Advanced Units,  Prev: Point Value,  Up: Unit Types

3.10.11 Advanced Units
----------------------

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

 -- UnitTypeProperty: `advanced' t/f
     This property is true if the type is an advanced type.

 -- UnitProperty: `size' n
     This property is the size of the advanced unit.

 -- TableUA: `size-limit-without-advance' u a -> n
     This table indicates the maximum size of a unit of type U if the
     advance A has not been achieved.  Defaults to a large number.

 -- TableUU: `size-limit-without-occupant' u1 u2 -> n
     This table indicates the maximum size of a unit of type U1 if a
     unit of type U2 is not an occupant.  Defaults to a large number.

 -- TableUM: `unit-consumption-per-cp' u m -> n

 -- TableUM: `unit-consumption-per-size' u m -> n

 -- TableUM: `unit-consumption-to-grow' u m -> n

   Advanced units may use cells around them for production.

 -- UnitTypeProperty: `reach' n
     This property is the radius out to which an advanced unit type may
     use the terrain for production.

 -- UnitProperty: `reach' n
     This property is the radius out to which an advanced unit may use
     the terrain for production.  (This is always the same as the type
     property currently.)

 -- UnitProperty: `size' n
     This property is the size of the advanced unit.

 -- UnitTypeProperty: `use-own-cell' t/f
     If true, then the advanced unit type automatically uses the cell
     it is sitting on.

 -- TableUA: `advance-add-maxcells' u a -> n
     This is the number of additional cells that the unit can use for
     production if its side has the advance.

 -- TableUA: `advance-mult-maxcells' u a -> n
     This is the percentage multiplier for the additional cells that
     the unit can use for production if its side has the advance.
     Defaults to `100'.

 -- TableUU: `occ-add-maxcells' u1 u2 -> n
     This is the number of additional cells that each occupant of type
     U2 adds to a unit of type U1.

 -- TableUU: `occ-multiply-maxcells' u1 u2 -> n
     This is the percentage by which each occupant of type U2 multiples
     the production cells of a unit of type U1.  Defaults to `100'.

 -- UnitProperty: `usedcells' n
     This is a cache of the number of cells used by an advanced unit.

 -- UnitProperty: `maxcells' n
     This is a cache of the maximum number of cells available to an
     advanced unit.

 -- TableUA: `advance-add-production' u a -> n
     This is the amount of additional production available to the unit
     if its side has the advance.

 -- TableUA: `advance-multiply-production' u a -> n
     This is the percentage by which an advance multiplies the
     production of the unit.  Defaults to `100'.

 -- TableUU: `occupant-add-production' u1 u2 -> n
     This is the amount of additional production available to the unit
     of type U1 due to each occupant of type U2.

 -- TableUU: `occupant-multiply-production' u1 u2 -> n
     This is the percentage by which each occupant of type U2
     multiplies the production of a unit of type U1.  Defaults to `100'.

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

 -- TableMM: `conversion' m1 m2 -> n
     Values greater than zero in this table indicate that produced
     materials of type M1 can become materials of type M2.

 -- TableMM: `conversion-default' m1 m2 -> n
     This table is the default conversion rate of material of type M1
     into a material of type M2.


File: xcdesign.info,  Node: Terrain Types,  Next: Material Types,  Prev: Unit Types,  Up: Reference Manual

3.11 Terrain Types
==================

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

 -- Form: `terrain-type' name properties...
     This form defines a new type of terrain, named by NAME.  Details
     are similar to those for unit types.

 -- GlobalVariable: `t*'
     This variable evaluates to a list of all terrain types, listed in
     the order that they were defined.

 -- GlobalVariable: `non-terrain'
     This variable has a value that is guaranteed not to be a terrain
     type.

* Menu:

* Terrain Subtypes::
* Terrain Compatibility::
* Other Terrain Properties::


File: xcdesign.info,  Node: Terrain Subtypes,  Next: Terrain Compatibility,  Up: Terrain Types

3.11.1 Terrain Subtypes
-----------------------

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

 -- TerrainTypeProperty: `subtype' subtype
     This property is the role that the terrain type can appear in.
     Defaults to `cell'.

 -- GlobalConstant: `cell'
     This constant indicates that terrain can fill a cell.  All units
     in the open and with an altitude of 0 are assumed to be surrounded
     by the cell terrain.

 -- GlobalConstant: `border'
     This constant indicates that the terrain can be a border between
     two cells.

 -- GlobalConstant: `connection'
     This constant indicates that the terrain can be a connection
     between two cells.

 -- GlobalConstant: `coating'
     This constant indicates that the terrain can be a coating.  A
     "coating" is a temporary terrain modification.  The classic example
     is snow, which effectively changes some kinds of terrain, but not
     completely and usually not permanently.  Cells can have varying
     heaviness of each type of coating.

 -- TableTT: `coating-depth-min' t1 t2 -> n
     In order for a coating T1 to "stick", this table says much must be
     added all at once to terrain T2.  A coating depth that drops below
     this will disappear immediately.

 -- TableTT: `coating-depth-max' t1 t2 -> n
     This table is the upper limit on coating depth.

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

 -- TerrainTypeProperty: `subtype-x' n
     This property is extra subtype information, used in synthesis.
     Defaults to `no-x'.

 -- Symbol: `no-x'

 -- GlobalConstant: `river-x'
     This constant indicates that synthesis methods should treat this
     type as a river.  The terrain type may be either a border or a
     connection.

 -- GlobalConstant: `valley-x'
     This constant indicates that synthesis methods should treat this
     type as a valley.

 -- GlobalConstant: `road-x'
     This constant indicates that synthesis methods should treat this
     type as a road.

 -- TerrainTypeProperty: `liquid' t/f
     This property is true if the terrain type represents a liquid,
     which means that adjacent cells of liquid must have the same
     elevation.  Defaults to `false'.


File: xcdesign.info,  Node: Terrain Compatibility,  Next: Other Terrain Properties,  Prev: Terrain Subtypes,  Up: Terrain Types

3.11.2 Terrain Compatibility
----------------------------

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

 -- TableTT: `adjacent-terrain-effect' t1 t2 -> t3
     This table specifies what will happen to a cell of type T1
     adjacent to a cell of type T2.  If T3 is `non-terrain', nothing
     will happen, otherwise it will become a cell of type T3.

     If T1 is a border type adjacent to a cell of type T2, and if T3 is
     `non-terrain', nothing will happen.  Otherwise, the border of type
     T1 will be removed, and if T3 is a border type, a border of that
     type will be added.  The effect on connection types is analogous.

     Defaults to `non-terrain'.


File: xcdesign.info,  Node: Other Terrain Properties,  Prev: Terrain Compatibility,  Up: Terrain Types

3.11.3 Other Terrain Properties
-------------------------------

 -- TerrainTypeProperty: `elevation-min' elev

 -- TerrainTypeProperty: `elevation-max' elev
     These properties define the minimum and maximum possible values
     for the elevation in a cell of given terrain type.  Both default
     to `0'.

 -- TerrainTypeProperty: `temperature-min' n

 -- TerrainTypeProperty: `temperature-max' n
     These properties define the minimum and maximum possible values
     for the temperature in a cell of given terrain type.  Both default
     to `0'.

 -- TerrainTypeProperty: `wind-force-min' n

 -- TerrainTypeProperty: `wind-force-max' n
     These properties define limits on wind force.  Both default to `0'.

 -- TerrainTypeProperty: `clouds-min' n

 -- TerrainTypeProperty: `clouds-max' n
     These properties define limits on cloud density.  Both default to
     `0'.


File: xcdesign.info,  Node: Material Types,  Next: Advance Types,  Prev: Terrain Types,  Up: Reference Manual

3.12 Material Types
===================

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

   No more than 126 types of material may be defined.

 -- Form: `material-type' symbol properties...
     This form defines a new type of material, named by SYMBOL.
     Details are similar to those for unit types.

 -- GlobalVariable: `m*'
     This variable evaluates to a list of all material types, listed in
     the same order as they were defined.

 -- GlobalVariable: `non-material'
     This variable has a value that is never a material type.

* Menu:

* People::


File: xcdesign.info,  Node: People,  Up: Material Types

3.12.1 People
-------------

A material type can be designated as representing people.

 -- MaterialTypeProperty: `people' n
     This property is the actual number of individuals represented by 1
     of a material.  If 0, then the material type does not have people
     associated with it at all.

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

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

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


File: xcdesign.info,  Node: Advance Types,  Next: Static Relationships Between Types,  Prev: Material Types,  Up: Reference Manual

3.13 Advance Types
==================

Advances are scientific, economic, social, or any other type of general
accomplishment.  They can enable the construction of particular types
of units.

   No more than 126 types of advances may be defined.

 -- Form: `advance-type' symbol properties...
     This form defines a new type of advance, named by SYMBOL.  Details
     are similar to those for unit types.

 -- GlobalVariable: `a*'
     This variable evaluates to a list of all advance types, listed in
     the same order as they were defined.

 -- GlobalVariable: `non-advance'
     This variable has a value that is never an advance type.

 -- AdvanceTypeProperty: `rp' n
     This property is the number of research points necessary to
     achieve the advance.  Defaults to `1'.


File: xcdesign.info,  Node: Static Relationships Between Types,  Next: Vision,  Prev: Advance Types,  Up: Reference Manual

3.14 Static Relationships Between Types
=======================================

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

* Menu:

* Occupants and Transports::
* Units and Terrain::
* Units and Materials::
* Terrain and Materials::
* Units and Advances::


File: xcdesign.info,  Node: Occupants and Transports,  Next: Units and Terrain,  Up: Static Relationships Between Types

3.14.1 Occupants and Transports
-------------------------------

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

 -- UnitTypeProperty: `capacity' n
     This property is the limit on the sum of sizes of units that may
     occupy this type of unit, not counting the exclusive capacities.

 -- TableUU: `unit-size-as-occupant' u1 u2 -> n
     This table is the "size" of a (full-sized) unit U1 when it is in a
     transport U2.  Defaults to `1'.

 -- TableUU: `unit-capacity-x' u1 u2 -> n
     This table is the number of units of type U2 that are guaranteed a
     place in a unit of type U1.

 -- TableUU: `occupant-max' u1 u2 -> n
     This table is the upper limit on the number of occupants of this
     type (not counting `unit-capacity-x').

 -- UnitTypeProperty: `occupant-total-max' n
     This property is the upper limit on occupants of all types
     together.  Defaults to `-1', which allows unlimited occupancy.

 -- UnitTypeProperty: `mobile-total-max' n
     This property is the upper limit on the number of mobile units
     (speed > 0) allowed as occupants.  Defaults to `-1', which allows
     unlimited occupancy.

 -- UnitTypeProperty: `facility-total-max' n
     This property is the upper limit on the number of facility units
     (`facility' is true) allowed as occupants.  Defaults to `-1',
     which allows unlimited occupancy.

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

 -- TableUU: `occupant-vision' u1 u2 -> n%
     This is the effect on U1's vision of being an occupant in a unit
     of type U2.  If the value is 0, then U1 is completely blind while
     an occupant.  Defaults to `100'.

 -- TableUU: `occupant-combat' u1 u2 -> n%
     This table defines the effect on the combat abilities of a unit of
     type U1 when an occupant in a unit of type U2.  If `0', then the
     occupant cannot attack or fire.  Defaults to `100'.

 -- TableUU: `occupant-can-construct' u1 u2 -> t/f
     This table is `true' if U1 can create or complete units while an
     occupant of U2.  Defaults to `false'.

 -- TableUU: `occupant-can-have-occupants' u1 u2 -> t/f
     This table is `true' if U1 can have occupants of its own while an
     occupant of U2.  Defaults to `false'.


File: xcdesign.info,  Node: Units and Terrain,  Next: Units and Materials,  Prev: Occupants and Transports,  Up: Static Relationships Between Types

3.14.2 Units and Terrain
------------------------

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

 -- TableUT: `vanishes-on' u t -> t/f
     This table is `true' if a unit U will disappear instantly if it
     somehow ends up on terrain of type T.  Defaults to `false'.

 -- TableUT: `wrecks-on' u t -> t/f
     This table is `true' if a unit U will wreck instantly if it
     somehow ends up on terrain of type T.  Defaults to `false'.

 -- TerrainTypeProperty: `capacity' n
     This property is the limit on the sum of unit sizes that may share
     this cell.  Defaults to `1'.

 -- TableUT: `unit-size-in-terrain' u t -> n
     This table is the "size" of a (full-sized) unit U when it is in/on
     the terrain T.  Defaults to `1'.  (Note that this is not the same
     as the size property of an advanced unit.)

 -- TableUT: `terrain-capacity-x' u t -> n
     This table is the number of (full-sized) units of type U that are
     guaranteed to have a place in the cell.

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

 -- TableUT: `capacity-negation' u t -> t/f

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

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


File: xcdesign.info,  Node: Units and Materials,  Next: Terrain and Materials,  Prev: Units and Terrain,  Up: Static Relationships Between Types

3.14.3 Units and Materials
--------------------------

Units can carry materials.

 -- TableUM: `unit-storage-x' u m -> n
     This table is the space reserved specifically for each type of
     material.

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

 -- TableUT: `people-surrender-chance' u t -> n%
     This table is the base chance that people in terrain of type T
     will change sides if a unit of type U is in their cell.

 -- TableUM: `people-surrender-effect' u m -> n
     This is a multiplier that takes the people type into account.
     Defaults to `100'.

