Designing Games with Xconq - Side and Player Forms

Go to the first, previous, next, last section, table of contents.

## Side and Player Forms

Form: `side` [ id ] properties...

This form has the effect of declaring a side to exist. If the number or symbol id is supplied and matches that of a side that has already been created, then the properties will modify the pre-existing side. Otherwise a new side object will be created, with a arbitrarily-chosen numeric id ranging between 1 and `sides-max`. If the given id is a symbol, then the side's numeric id will be bound to that symbol.

GlobalVariable: `sides-min` n

GlobalVariable: `sides-max` n

These variables are the minimum and maximum number of sides that may exist in a game. Defaults are to `1` and the internal parameter `MAXSIDES`, which is usually around 7. `MAXSIDES` can only be changed by recompiling Xconq.

Form: `side-defaults` properties...

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

- Side Name Properties
- Side Class
- Status in Game
- Side Relationships
- Numbering Units
- Side-Specific Namers
- Side Tech Levels
- Side Views
- Interaction
- Doctrine
- Other Side Properties
- Independent Side
- Players
- Rules of Side Configuration

### Side Name Properties

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

SideProperty: `name` str

This property is the proper name of a side, as a country or alliance name. Examples include `"Axis"` and `"Hyperborea"`.

SideProperty: `long-name` str

This property is the long form of a side's name, as in `"People's Republic of Hyperborea"`. Defaults to be the same as the side's name.

SideProperty: `short-name` str

This property is an short name or acronym for the side, often just the letters of the long name, as in `"PRH"`.

SideProperty: `noun` str

This property is the name of an individual unit or person belonging to the side. Defaults to `""`, which suppresses any mention of the side when (textually) describing the individual.

SideProperty: `plural-noun` str

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

SideProperty: `adjective` str

This property is an adjective that can be used of individuals on the side, as in `"Spanish"`. Defaults to `""`, which suppresses use of the adjective.

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

SideProperty: `color` str

This property is a comma-separated list of colors that represents the side. Defaults to `"black"`.

SideProperty: `emblem-name` str

This property is the name of a graphical icon that represents the side. An emblem name of `"none"` suppresses any emblem display for the side. Defaults to `""`, which gives the side a randomly-selected emblem.

SideProperty: `names-locked` t/f

If the value of this property is `true`, then the player cannot modify any of the side's names. Defaults to `false`.

### Side Class

SideProperty: `class` str

This property is a side's class, which is a keyword that characterizes the side. Any number of sides may be in the same class.

### Status in Game

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

SideProperty: `active` t/f

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

SideProperty: `status` lose/draw/win

This property tells how this side did in the game. Defaults to `draw`.

GlobalConstant: `win`

GlobalConstant: `draw`

GlobalConstant: `lose`

These constants are the different possible values for a side's status.

SideProperty: `ever-active` t/f

This property records if the side was ever active during the course of a game. Sides that were never active (perhaps because they are used in some scenarios of a game design but not others) will not be recorded in the scorefile.

SideProperty: `advantage` n

SideProperty: `advantage-min` n

SideProperty: `advantage-max` n

Initial and min/max limits on advantage for the side. All default to the values of the corresponding global variables.

### Side Relationships

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

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

SideProperty: `controlled-by` side

This property refers to the side controlling this one. If 0, then the side is not under control.

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

SideProperty: `trusts` side-value-list

This property is true for any side that is trusted by this side. Note that this relationship need not be symmetrical. Defaults to `false` for all sides.

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

SideProperty: `trades` side-value-list

This property defines the trading relationship with other sides.

### Numbering Units

SideProperty: `next-numbers` utype-value-list

This property gives the next serial numbers that will be assigned to units acquired by this side. Defaults to `1` for each unit type (Dijkstra notwithstanding, that's still where people start numbering things).

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

### Side-Specific Namers

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

SideProperty: `unit-namers` utype-value-list

This property specifies which namers will be used with which types that the side starts out with or creates new units. These will not be run automatically on captured units or gifts.

SideProperty: `feature-namers` feature-type-value-list

This property specifies which namers to use with which geographical features in the side's initial country (if if has one). Defaults to `()`.

### Side Tech Levels

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

SideProperty: `tech` utype-value-list

This property assigns a tech level to each unit type named.

SideProperty: `init-tech` utype-value-list

This property is the tech level at the beginning of the current turn.

SideProperty: `advance` atype-value-list

This property is the state of the side's research on each advance. A value of -1 indicates that the advance has been achieved.

### Side Views

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

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

SideProperty: `terrain-view` layer-data...

This property is the side's current knowledge of the world's terrain. Defaults to `()`.

SideProperty: `terrain-view-dates` layer-data...

This property is the dates of the side's current knowledge of the world's terrain. Defaults to `()`.

SideProperty: `aux-terrain-view` ttype layer-data...

This property is the side's current knowledge of the world's aux terrain of type ttype. Defaults to `()`.

SideProperty: `aux-terrain-view-dates` ttype layer-data...

This property is the dates of the side's current knowledge of the world's aux terrain of type ttype. Defaults to `()`.

SideProperty: `unit-views` unit-view...

This property is the side's current knowledge of the positions of units in the world. It is a list of unit-view objects, where each has the forms `(type side id x y)`. Defaults to `()`.

SideProperty: `material-view` mtype layer-data...

This property is the side's current knowledge of the amounts of each type of material at each location in the world. Defaults to `()`.

SideProperty: `material-view-dates` ttype layer-data...

Defaults to `()`.

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

SideProperty: `temperature-view` layer-data...

Defaults to `()`.

SideProperty: `temperature-view-dates` layer-data...

Defaults to `()`.

SideProperty: `cloud-view` layer-data...

Defaults to `()`.

SideProperty: `cloud-bottom-view` layer-data...

Defaults to `()`.

SideProperty: `cloud-height-view` layer-data...

Defaults to `()`.

SideProperty: `cloud-view-dates` layer-data...

Defaults to `()`.

SideProperty: `wind-view` layer-data...

Defaults to `()`.

SideProperty: `wind-view-dates` layer-data...

Defaults to `()`.

### Interaction

SideProperty: `initial-center-at` x y

This property is the preferred location at which to center the first map displayed by an interface.

SideProperty: `turn-time-used` seconds

This property is the number of (real) seconds that this side has been moving units during the present turn.

SideProperty: `total-time-used` seconds

This property is the number of (real) seconds that this side has been moving units during the course of the game.

SideProperty: `timeouts` n

This property is the number of "time outs" a side gets for the game.

SideProperty: `timeouts-used` n

This property is the number of "time outs" a side has already used up.

SideProperty: `finished-turn` t/f

This property is true if the side has declared that it is finished moving things during this turn. Defaults to `false`.

SideProperty: `willing-to-draw` t/f

This property is true if the side will go along with any other side that wants to end the game in a draw. Defaults to `false`.

### Doctrine

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

SideProperty: `doctrines` utype-property-groups...

This property is the side's unit-type-specific doctrine. Each utype-property-group has the form `(unit-types doctrine)`. Defaults to `()`.

SideProperty: `doctrines-locked` t/f

This property says whether the docrine-unit type correspondence for the side may be altered during the game. This property does not control whether or not the properties of the doctrines may be altered. Defaults to `false`.

SideProperty: `default-doctrine` doctrine-id

This property is the base doctrine that applies to all unit types by default.

Form: `doctrine` [ id ] properties...

This form creates a doctrine with the given id and properties.

DoctrineProperty: `resupply-percent` n%

This property indicates that when the level of a operationally-consumed material is at n% of capacity, try to resupply. Defaults to `50`.

DoctrineProperty: `rearm-percent` n%

This property indicates that when the level of a combat-consumed material is at n% of capacity, try to resupply.

DoctrineProperty: `repair-percent` n%

This property indicates that when the unit's hp is at n% of max, make a plan to repair.

DoctrineProperty: `construction-run` type-value-list

This property is the default number of units to build when construction has been requested.

DoctrineProperty: `locked` t/f

This property is true if the properties of the doctrine cannot be modified by the side's player during the game. Defaults to `false`.

### Other Side Properties

SideProperty: `self-unit` unit

This property identifies a unit that represents the side itself. The value may be a unit id, number, string, or symbol. Defaults to `0`, which means that no unit represents the side. See below for more details on self units.

SideProperty: `units` list

This property is a weighted list of units that could be given to the side during setup in order to satisfy the side's `start-with` numbers.

SideProperty: `treasury` mtype-value-list

This property is the quantity of each type of material belonging to the side as a whole, independent of materials in specific units.

SideProperty: `priority` n

The order in which the side will get to act, relative to other sides and to units. Defaults to `-1`. Note that the `sequential` variant will automatically cause side priority to be set to nonnegative values, unless the value is already nonnegative.

SideProperty: `action-priorities` (utype val)...

This property is the acting priority of units belonging to the side.

SideProperty: `scores` (skid val)...

This property is the current values of any numeric scores being kept for the side. It is a list of pairs of scorekeeper id and value. Defaults to `()`.

SideProperty: `attack-stats` n...

SideProperty: `hit-stats` n...

These properties are the raw counts of attacks and hits, by attacking and defending unit types. Default to `()`.

SideProperty: `gain-counts` n...

SideProperty: `loss-counts` n...

These properties are the raw counts of unit gains and losses, organized by unit type and gain/loss reason.

Form: `independent-units` properties...

Like the `side` form, but sets properties for independent units.

SideProperty: `ui-data` data...

This property contains interface-specific data for the side. This is mainly for preservation across game save/restores. The property's value has the form

    ((interface-type data) (interface-type data) ...)

so that each interface can maintain its own data separately.

SideProperty: `ai-data` data...

This property is information about the AIs associated with a side. The property's value has the form

    ((ai-type data) (ai-type data)
    ...)

so that each type of AI can maintain its own data separately. The form and meaning of each AI's data is specific to it alone.

SideProperty: `standing-order` data...

This property contains the list of standing orders for the side.

GlobalConstant: `always`

This symbol indicates a standing order that is always to be executed by a unit. GlobalConstant: `@`

This symbol indicates a standing order that units of the specified types are to execute when at a given location. GlobalConstant: `in`

This symbol indicates a standing order that units of the specified types are to execute when occupying a given unit. GlobalConstant: `near`

This symbol indicates a standing order that units of the specified types are to execute when within a given distance of a given location.

### Independent Side

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

GlobalVariable: `no-indepside-ingame` t/f

This variable is true if the game should not allow the players to make the independent units active. This is appropriate for historical games where all the participating side are predefined, for instance.

GlobalVariable: `indepside-has-ai` t/f

This is true if an AI should be created for the independent side.

GlobalVariable: `indepside-can-build` t/f

This is true if independent units may construct new units.

GlobalVariable: `indepside-can-develop` t/f

This is true if independent units may develop their technology.

### Players

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

SideProperty: `player` id

This property is the unique identifier of a player that is running this side. Defaults to `0`, which means that no player has been assigned to the side.

Form: `player` [ id ] properties...

This form defines a player. If the id is supplied and matches the id of an existing player, then the player object is updated using the properties, otherwise a new player object will be created, using the given id if supplied, otherwise creating a new value.

GlobalVariable: `player-sides-locked` t/f

This variable is `true` if the player/side assignment may not be changed while the game is starting up. Defaults to `false`.

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

PlayerProperty: `name` str

This property identifies the player by name.

PlayerProperty: `config-name` str

This property identifies a particular set of doctrine and other definitions that the player is using.

PlayerProperty: `display-name` str

This property identifies the display being used by the player's interface. The interpretation of this value is dependent on the interface in use.

PlayerProperty: `ai-type-name` str

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

PlayerProperty: `password` str

This property is the encoding of a password that must be entered before this player object can be reused successfully.

PlayerProperty: `initial-advantage` n

This property is an initial relative strength at which the player should start. Some synthesis methods can use this to give more units or some other advantage to each player according to the requested strength. Defaults to `1`.

GlobalVariable: `advantage-min` n

GlobalVariable: `advantage-max` n

GlobalVariable: `advantage-default` n

These variables set the bounds and default values for players' initial advantages. Default to `1`, `9999`, and `1`, respectively.

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

### Rules of Side Configuration

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

- Interface-specific sources (X resources, Mac preferences).
- The `side` form for the side.
- The `side-defaults` form for the game.
- General program defaults.

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

Go to the first, previous, next, last section, table of contents.