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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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''.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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]

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")

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.

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.

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.

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.

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.

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.

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.

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.

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?]

Setup Miscellany
================

This section describes random things.

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.

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)

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.

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.

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.

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.

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.

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.

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

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

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.

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).

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.

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.

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.

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.

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.

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.

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]

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!

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.

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.

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.

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.

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.

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.

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.

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.

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!

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!

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.

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!

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.

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.]

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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]

Describing Objects
------------------

[fill in]

Describing Events
-----------------

[fill in]

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.

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!

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!

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.

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

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.

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!).

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.

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''.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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!).

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!

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.

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.

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.

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.

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).

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.

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.

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.

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
       )

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.

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 (see 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.

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.

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.

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.

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.

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!

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.

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) &

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.

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.

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.

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.

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.

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.

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.