Designing Games with Xconq - Unit Forms

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

## Unit Forms

The basic `unit` form creates or modifies a unit.

Form: `unit` id [ type ] properties...

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

Form: unit-type-name x y [ side-id ] properties...

This is an abbreviated form, in which the x,y position is required, and an optional side id may be included. The side id will come from `unit-defaults` if not specified. The unit-type-name may be any valid unit type name or defined name. This form always results in a new unit.

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

Form: `unit-defaults` [ modifier ] properties...

This form sets the default values for all subsequent units read in, in this and every other module not yet loaded. The set of defaults is additive, so for instance you can repeatedly change the default side of units. If the symbol `reset` has been supplied for the optional modifier, then all the defaults will be changed to the basic default values, as described in this manual.

Symbol: `reset`

This is the symbol used to reset unit defaults; see above.

GlobalVariable: `create-units-from-specs` t/f

When true, unit forms actually cause units to be created. When false, the unit forms are saved away and can be used later by a unit form to supply values for properties. Defaults to `true`.

- Unit Properties
- Unit Action State
- Unit Plan
- Goal Types
- Task Types

### Unit Properties

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

UnitProperty: `@` x y [ z ]

This property is the position of the unit. Defaults to `-1,-1,0`, which causes the unit to be placed randomly. The optional altitude z can also be set separately with the property `z` below. If z is even and the unit is in the open, then the unit's altitude is z/2; if z is odd, then (z-1)/2 is the type of connection terrain that the unit is on.

UnitProperty: `z` z

This property is identical to the optional z part of the `@` property.

UnitProperty: `s` side

This property is the side of the unit. It can be either a side name, noun, or adjective (string) or an id (number). A value of `0` or `"independent"` means that the unit is independent.

UnitProperty: `os` side

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

UnitProperty: `#` n

This property is the unique numeric id of the unit. Defaults to a game-selected value.

UnitProperty: `n` str

This property is the name of the unit.

UnitProperty: `nb` n

This property is the number of the unit, which starts at `1` and goes up. Defaults to `0`, which means that the unit is unnumbered.

UnitProperty: `cp` n

This property is the current completeness of the unit. If negative, indicates that the unit will appear at a time and place specified by the `appear` x-property. Defaults to the `cp-max` for the type.

UnitProperty: `hp` n

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

UnitProperty: `cxp` cxp

This property is the combat experience of the unit. Experience starts at 0 for new units and goes up with each engagement in combat.

UnitProperty: `mo` n

This property is the morale of the unit. Morale ranges from 0 to a maximum set by `morale-max`.

UnitProperty: `trk` n

This property is a bit vector indicating the sides that are currently tracking the unit's movements. The unit's own side is not included.

UnitProperty: `m` mtype-value-list

This property is the amounts of supplies being carried by the unit. Defaults to `0` for each material type.

UnitProperty: `tp` utype-value-list

This property is the level of tooling to build each type of unit. Defaults to `0` for each unit type.

UnitProperty: `in` x

This property is the id, name, or symbol of the unit's transport. Defaults to `0`, meaning that unit is not in any transport.

UnitProperty: `opinions` side-value-list...

This property is the unit's true feelings towards each side, including its own side. Defaults to `0` for each side.

UnitProperty: `appear` n

This property is the turn on which a unit will appear. The unit's cp must also be negative, and its position must be negatives of its position. Defaults to `-1`.

UnitProperty: `disappear` n

This property is the turn on which a unit will disappear from the game. Occupants will be ejected if possible; otherwise they will disappear also. Defaults to `-1`.

UnitProperty: `autoplan` n

This property is true when the unit should choose its own research topics.

UnitProperty: `autobuild` n

This property is true when the unit should choose its own construction task.

UnitProperty: `autoresearch` n

This property is true when the unit should choose its own research topics.

UnitProperty: `curadv` n

This property is the current advance that the unit is researching.

UnitProperty: `popul` n

This property is the unit's population (currently unused).

UnitProperty: `prod` mtype-value-list

This property is the unit's production for each material type.

UnitProperty: `sym` symbol

This property is a symbol that is unique to this unit. This symbol may appear instead of a unit id, for instance as the value of the property `in`. Defaults to `()`.

UnitProperty: `sides` list

This property is a list of side names that the unit may be given to during setup. (See side property `units`.) Defaults to `()`.

### Unit Action State

UnitProperty: `acp` n

This property is the number of action points left to the unit for this turn.

UnitProperty: `acp0` n

This property is the initial number of action points for this turn, computed at the beginning of the turn.

UnitProperty: `am` n

This property is the actual number of moves (cell entries) executed so far in the current turn.

UnitProperty: `a` action

This property is the next action that the unit will perform.

### Unit Plan

UnitProperty: `plan` type [ creation-turn ] properties...

This property describes the unit's current plan.

PlanType: `none`

A unit with this type of plan does nothing. It is used when a side has no player.

PlanType: `passive`

This plan type is for units on a side that is being run directly by the side. This is the normal plan type for units when a human player is playing.

PlanType: `defensive`

This plan type is for units that defend areas or other units.

PlanType: `offensive`

This plan type is for units that are to be aggressive.

PlanType: `exploratory`

This plan type is for units that explore the world.

PlanType: `colonizing`

This plan type is for units to build more units (like cities) that can themselves build more units.

PlanType: `improving`

This plan type is for units to improve themselves, such as by adding special types of occupants.

PlanType: `random`

A unit with this plan type will act randomly.

PlanProperty: `goal` goal

This property is the main goal of a unit's plan. Defaults to `()`.

PlanProperty: `formation` goal

This property is the formation goal of a unit's plan. If defined, it is a position goal that the unit should try to achieve when it is not trying to achieve the main goal. Defaults to `()`.

PlanProperty: `tasks` tasks...

This property is the complete task agenda for the unit's plan. It is a list of tasks. Defaults to `()`.

PlanProperty: `asleep` t/f

This property is true if the unit is asleep. Defaults to `false`.

PlanProperty: `reserve` t/f

This property is true if the unit is in reserve. Defaults to `false`.

PlanProperty: `delayed` t/f

This property is true if the unit's activity has been delayed until all others have acted. Defaults to `false`.

PlanProperty: `wait` t/f

This property is true if the unit is waiting for orders. Defaults to `false`.

PlanProperty: `ai-control` t/f

This property is true if the unit can be controlled by any AI associated with the side. Defaults to `true`.

PlanProperty: `supply-alarm` t/f

This property is true if the unit should react when supply is low. Defaults to `false`.

PlanProperty: `supply-is-low` t/f

This property is true if the unit considers its supply to be low. Defaults to `false`.

PlanProperty: `wait-transport` t/f

This property is true if the unit is waiting for transport. Defaults to `false`.

PlanProperty: `initial-turn` turn

This property is the turn upon which a plan should go into effect.

PlanProperty: `final-turn` turn

This property is the turn upon which a plan should be removed. If the value is `0`, then the plan is not scheduled to be removed.

### Goal Types

The possible types of goals are these:

GoalType: `no-goal`

GoalType: `won-game`

GoalType: `lost-game`

GoalType: `world-is-known`

GoalType: `vicinity-is-known`

GoalType: `positions-known`

GoalType: `cell-is-occupied`

GoalType: `vicinity-is-held`

GoalType: `has-unit-type`

GoalType: `has-unit-type-near`

GoalType: `has-material-type`

GoalType: `keep-formation`

GoalType: `find-spot-to-build`

### Task Types

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

TaskType: `build` ex re u n n2 unit-id

This type of task directs the unit to build n units of type u. n2 is the number already built in the run and unit-id is the (optional) id of a unit already being built.

TaskType: `capture` ex re unit-id

TaskType: `collect` m x y

This type of task directs the unit to acquire material of type m at or around x,y and to deliver it to the nearest unit that can accept the material.

TaskType: `disband` ex re

This type of task directs the unit to disband itself.

TaskType: `hit-position` ex re x y z

This type of task directs the unit to attack or fire on any unfriendly units at the given location.

TaskType: `hit-unit` ex re unit-id

TaskType: `move-dir` ex re dir n

This type of task directs the unit to move in direction dir for a distance of n cells.

TaskType: `move-to` ex re x y z dist

This type of task directs the unit to move to a distance of no more than dist cells from the given location.

TaskType: `occupy` ex re unit-id

This type of task directs the unit to attempt to enter the given unit-id, moving adjacent to it first if necessary.

TaskType: `pickup` ex re unit-id

This type of task directs the unit to move towards the given unit-id.

TaskType: `repair` ex re unit-id

TaskType: `resupply` ex re

This type of task directs the unit to replenish its supplies, whether by doing more production or by moving to another unit that has supplies available.

TaskType: `sentry` ex re n

This task type directs the unit to stay where it is for the next n turns.

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