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.
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 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: creation-id n
The ID of the unit created by this unit. Reset once the building stage starts.
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 ().
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.
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.
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
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.