Bos Wars Scripting API: UnitType

Intro - Introduction to unit-type functions and variables

Conceptual

Frame numbers and flipping

The engine draws units and missiles using frames that it loads from graphic files. The frames within a file all have the same size and are numbered from zero up. When a unit or a missile moves, the engine tries to automatically choose a frame that faces the correct direction.

DefineAnimations("animations-example", {
    Still = {"frame 0", …},
    Death = {…, "frame 8", …, "frame 16", …}})

To save effort and memory, the frames that face the west can be omitted from the graphic file. The engine will then generate them on demand by flipping the corresponding frames that face the east. To enable this feature, set Flip = true in DefineUnitType or DefineMissileType.

Flipping changes the numbers of frames. Only the frames that are left in the graphic file have contiguous nonnegative numbers. Each flipped frame has a negative number that the engine computes as (-1 - original number).

DefineAnimations("animations-example", {
    Still = {"frame 0", …},
    Death = {…, "frame 5", …, "frame 10", …}})

In missiles, the engine always numbers frames as if Flip were true.

DefineMissileType("missile-example", {
    Flip = false,
    NumDirections = 8,
    Frames = 3*5,       -- Not 3*8, even though all frames are in the file.
    …})

Functions

DefineAnimations("ident-name", {type = {script}, ...})

"ident-name"

Name of the animation to define. The name tells stratagus when to play the animation.

type

Supported types:

• Still
• Move
• Attack
• Repair
• Train
• Build
• Harvest_ followed by the name of the harvested resource
• Death

script

A script is a list of operations. Supported operations:

• "frame X": Display this frame (see Frame numbers and flipping) plus the direction offset
• "exact-frame X": Display this exact frame
• "wait X": Wait this number of cycles
• "random-wait X Y": Wait a random number of cycles between X and Y
• "sound X": Play this sound
• "random-sound X Y Z ...": Randomly play one of the listed sounds
• "attack": Attack
• "rotate X": Rotate unit, positive for clockwise, negative for counterclockwise
• "random-rotate X": Rotate in a random direction
• "move X": Move this number of pixels
• "unbreakable {begin|end}": Start or end an unbreakable section
• "label X": Create a label (used by goto and random-goto)
• "goto X": Goto a label position
• "random-goto X Y": Goto label Y with X percent probability

Example

DefineAnimations("animations-footman", {
  Still = {"frame 0", "wait 4", "frame 0", "wait 1",},
  Move = {"unbreakable begin", "frame 0", "move 3", "wait 2", "frame 5", "move 3", "wait 1",
    "frame 5", "move 3", "wait 2", "frame 10", "move 2", "wait 1",
    "frame 10", "move 3", "wait 1", "frame 0", "move 2", "wait 1",
    "frame 0", "move 3", "wait 2", "frame 15", "move 3", "wait 1",
    "frame 15", "move 3", "wait 2", "frame 20", "move 2", "wait 1",
    "frame 20", "move 3", "wait 1", "frame 0", "move 2", "unbreakable end", "wait 1",},
  Attack = {"unbreakable begin", "frame 25", "wait 3", "frame 30", "wait 3", "frame 35", "wait 3",
    "frame 40", "attack", "sound footman-attack", "wait 5", "frame 0", "wait 10",
    "frame 0", "unbreakable end", "wait 1",},
  Death = {"unbreakable begin", "frame 45", "wait 3", "frame 50", "wait 3", "frame 55", "wait 100",
    "frame 55", "unbreakable end", "wait 1",}

DefineVariables( "varname-1", {tag = value}, "varname-2", {tag = value}, ...)

Value = number

Initial value for the variable

Max = number

Max value for the number, assuming 0 is the min.

Increase = number

Number to add each simulated second if possible, negative value are possible.

Enable = boolean

if the variable is active by default. For example, Mana is active only for caster, but HP is available for every unit. When a variable is disabled, the Increase does not take effect, and the Value usually becomes invisible (but see ShowIfNotEnable in DefineDecorations).

Note

HitPoints

Hp of the unit.

Build

State of the construction in building.

Mana

Mana point of the unit.

Transport

Number of unit inside (for transporter only, no build inside).

Training

Remaining cost to build the unit being training.

GiveResource

Resource that the unit gives ("resource-name" mine for exemple)

Kill

Number of unit killed by the unit.

Armor

Basic armor of the unit.

SightRange

Sight range (in tiles) of the unit. See also Preference.ShowSightRange.

RadarRange

Radar range of the unit.

RadarJammerRange

Radar Jamming range of the unit.

AttackRange

Attack range of the unit. See also Preference.ShowAttackRange.

PiercingDamage

piercing damage of the unit. FIXME calculations?

BasicDamage

Basic damage of the unit. FIXME calculations?

PosX

X position of the unit. Max is the Map size.

PosY

Y position of the unit. Max is the Map size.

AutoRepairRange

Range to check for unit to repair. (for unit which can repair)

Slot

Unique number that identifies the unit (begin at 0). Max is the last valid slot number.

Example

DefineVariable("cooldown", {Value = 0, Increase = -1, Max = 50, Enable = false})

DefineUnitType( "ident", { tag1 = value1, tag2 = value2, ...})

ident

The unit-type unique identifier. It is used to reference unit-types in game. F.E: "unit-knight", "unit-gold-mine". Please use all-lowercase names prefixed with unit-, it is easier to read this way.

Name = "show-name"

The unit-type name shown in the game. F.E: "Knight", "Gold Mine". If the name is too long, it is split at space.

Image = {"file", filename, "size", {x, y}}

Defines the graphics used to display the unit-type in game.

Offset = {x, y}

Defines the offset for the graphics in pixels used to display the unit-type

Shadow = {tag, value, ...}

Defines the Parameters for the shadow the unit is casting in the game

Possible tags:

"file", filename

Defines the graphics used to display the shadow of the unit-type

"size", {width, height}

Defines the size of the graphics in pixels used to display the shadow of the unit-type

"offset", {x, y}

Defines the offset of the graphics in pixels used to display the shadow of the unit-type. Note that this is relative to the unit graphics including its own offset

Flip = boolean

Flip = false (the default) means the unit type has separate frames for all directions. The graphic file defined with the Image tag must thus have NumDirections frames for each animation posture.

Flip = true means the frames facing west are not included in the graphic file because they are mirror images of the frames facing east. The file must then have only NumDirections / 2 + 1 frames for each animation posture. Please see Frame numbers and flipping for details.

DrawLevel = number

This is used when sorting units and missiles for drawing. Units with a higher draw order will always be on top of units with lower draw order. Units are also sorted from top to the bottom of the screen.

Animations = "animation-type"

Identifier to reference the animation sequences (scripts) for the unit-type. F.E. "animations-knight", "animations-gold-mine". See DefineAnimations.

TileSize = {x, y}

Define the unit-type size in tiles. NOTE: currently only buildings could be bigger than one tile.

BoxSize = {width, height}

Define the size of the unit selection box. This is drawn centered around the unit and most of the time it is equal to the tile size of the unit* the size of a terrain tile, for an almost perfect fit.

NumDirections = number

Define the number of directions a unit can face. Default 1 for buildings and 8 for units. Can be adjusted from the default. Useful for cannons or turrets that are considered buildings but must aim towards the enemy.

IsNotSelectable = boolean

set whether the unit is able to be selected or not.

Decoration = boolean

set whether the unit is a decoration (act like a tile) or not.

Indestructible = boolean

set whether the unit is indestructible not.

NeutralMinimapColor = {r, g, b}

sets the color of a unit when belonging to the neutral player. F.E. '(0 0 0) for a black oil patch.

Icon = "Icon-name"

Identifier to reference the icon shown in game for this unit-type. F.E. "icon-knight", "icon-gold-mine".

Sounds = {event, "sound-name", ...}

The following events are supported:

• "selected": Happens when the unit is selected.
• "acknowledge": Happens when the unit received an order.
• "ready": Happens when the unit finished training (and it's ready)
• "help": Happens when the unit is under attack.
• "dead": Happens when the unit is killed.

You can use the same help or ready sound for all units if you want generic "Your unit is under attack", "Some unit was trained" sounds. The actual sound files are not declared here. Please see the documentation on sounds

CanGroundAttack = boolean

Whether the unit can attack a place where there is no known enemy unit.

CanAttack = boolean

Whether the unit can attack at all.

CanTargetLand = boolean

Whether the unit can attack land units (Type = "land"). Actually, it can attack naval units too, if they are explicitly allowed on land (see AllowTerrainLand). It does not matter whether the targeted unit currently is on land.

CanTargetSea = boolean

Whether the unit can attack naval units (Type = "naval"). Actually, it can attack land units too, if they are explicitly allowed in some type of water (see AllowTerrainShallowWater and AllowTerrainDeepWater). It does not matter whether the targeted unit currently is in water.

CanTargetAir = boolean

Whether the unit can attack flying units (Type = "fly").

MaxMana = number

Maximum mana of the unit. When a unit of this type is created, it initially has only 33% of this mana.
MaxMana = number is equivalent to Mana = {Initial = number * 33 / 100, Max = number, Increase = 1, Enable = true}.

MaxAttackRange = number

Attack range (in tiles) of this unit. Use 1 for melee units.
This is the same as the predefined AttackRange variable. You can set it using either name.

MinAttackRange = number

Minimum attack range (in tiles) of this unit. This is useful for siege units you want to make vulnerable to close range attacks.

RegenerationRate = number

Amount of HP a unit gains per simulated second.
RegenerationRate = number is equivalent to HitPoints = {Increase = number}.

EnergyValue = number

The energy cost of building or training a unit of this type. This also affects how much energy can be harvested from the unit.

MagmaValue = number

The magma cost of building or training a unit of this type. This also affects how much magma can be harvested from the unit.

MaxEnergyUtilizationRate = number

How much energy the unit can consume per simulated second, typically when it is training or building something. If you make this number smaller, then training will take longer.

MaxMagmaUtilizationRate = number

How much magma the unit can consume per simulated second.

EnergyProductionRate = number

How much energy the unit produces per simulated second, just by existing. This does not include any energy it can produce by harvesting other units.

MagmaProductionRate = number

How much magma the unit produces per simulated second, just by existing.

EnergyStorageCapacity = number

How much more energy the player can store by having this unit. The engine only keeps track of the total amount of stored energy per player, and not exactly where it has been stored.

MagmaStorageCapacity = number

How much more magma the player can store by having this unit.

RightMouseAction = "none" or "move" or "attack" or "harvest" or "spell-cast"

"none"

Do nothing.

"move"

Right clicking defaults to move. This should be used for unit's that can't attack.

"attack"

Right clicking defaults to attack. This should be used for most combat units.

"harvest"

This should be used for resource gathering units. It will return goods when on a deposit and mine when on a resource.

"spell-cast"

This is an ugly hack for demolishing units. The unit will cast it's first known spell(in order of spell definition) instead of attacking a hostile unit.

Construction = construction-name

How to draw units of this type while they are being built. See DefineConstruction.

ProductionEfficiency = number

Efficiency percentage for energy and magma production of units built on top of this one, using an "ontop" building rule. If the unit type that has a ProductionEfficiency is itself producing energy (EnergyProductionRate) or magma (MagmaProductionRate), the ProductionEfficiency does not affect those.

CanHarvestFrom = boolean

This is a flag for harvestable resource buildings.

Vanishes = boolean

True means the unit is a corpse or a destroyed building. It cannot be selected, targeted, or killed again; it just lies there until its animation ends, and then it vanishes.

Building = boolean

Unit is a building, and immobile. Available as a spell target check.

Type = "land" or "fly" or "naval"

Whether the unit stands/walks/rolls on dry land, flies in the air, or sails/dives in the water. This affects several things:

• Flying units cannot be blocked by land or naval units, and vice versa.
• Flying units ignore the movement costs defined in map patches. They can fly over swamps as fast as over roads.
• By default, land units cannot move in the water, and naval units cannot move on the land, but flying units can move anywhere. However, you can override these defaults with AllowTerrainLand, AllowTerrainCoast, AllowTerrainShallowWater, and AllowTerrainDeepWater.
• Only land units can board transporters. (FIXME: allow different restrictions for different transporter types.)
• Land units may be unable to attack naval units, or vice versa. See CanTargetLand, CanTargetSea, and CanTargetAir.
• When selecting units with a rectangle, the player can press Alt to select only land and naval units, or Control to select only flying units.
• The spell action "demolish" does not hit flying units.

VisibleUnderFog = boolean

Unit remains visible under fog of war. In most games this is true for and only for buildings.

ShoreBuilding = boolean

Unit is a shore building, and immobile. This is used for those unique buildings that have to be built on sea and have at least one point on coast. This restriction is like BuildingRules = {{"terrain", {CountCoast=true, Min=1}}}, but ShoreBuilding also affects other things: see AllowTerrainCoast.

AllowTerrainLand = boolean

Explicitly allow or forbid moving the unit to dry land. By default, only air units and land units are allowed there. This also affects whether the unit can be targeted as a land unit (see CanTargetLand).

AllowTerrainCoast = boolean

Explicitly allow or forbid moving the unit to coasts. By default, only air units, naval transporter units, and shore buildings are allowed there. This does not affect which units can target the unit.

AllowTerrainShallowWater = boolean

Explicitly allow or forbid moving the unit to shallow water. By default, only air units and naval units are allowed there. This also affects whether the unit can be targeted as a naval unit (see CanTargetSea).

AllowTerrainDeepWater = boolean

Explicitly allow or forbid moving the unit to deep water. By default, only air units and naval units are allowed there. This also affects whether the unit can be targeted as a naval unit (see CanTargetSea).

BuildingRules = { { "distance", { Distance = 3, DistanceType = ">", Type = "unit-gold-mine"}}}

BuildingRules allows you to specify a list of restrictions to make when building. The list is in nested tables, the inter list is and'd together, and or'd with the other lists. See the example for details.

"distance"

Specifies a distance constraint.

Distance

The distance in tiles to measure

DistanceType

<, >, <=, >=, ==, !=

Type

The type of the unit that this distance restriction applies to

Except NOT IMPLEMENTED

boolen, #t implies all units, except this type must be

"addon"

Specifies an addon to an existing building.

OffsetX

Offset from the top left of the parent building that this unit must be placed. eg, -2 would left two of the building. (you need to consider the size of the parent building)

OffsetY

As with OffsetX, except in the Y direction

Type

Type of the unit that this unit is an addon too

"ontop"

Building must be built on top of another building type.
NOTE: the engine may not be able to guess the correct parent if the rules are complex enough. For example, if you define that unit-magmapump can be built on top of either unit-hotspot and unit-weakhotspot, and building the pump removes the hot spot but destroying the pump restores it, then the engine does not remember which type of hot spot it was. This matters especially if the possible underlying unit types have different ProductionEfficiency values, but in that case, removing the underlying units during building seems unusual anyway.

Type

The unit-type that we are to build on top of

ReplaceOnDie

boolean, true if you want the original unit to be replaced when this unit dies

ReplaceOnBuild

boolean, true if you want to remove the old unit underneath when you build this one

"terrain"

Implement a tile restriction, unit must be placed on certain types of tiles.

CountLand = boolean

CountCoast = boolean

CountShallowWater = boolean

CountDeepWater = boolean

Which types of terrain tiles are being counted.

Min = number

Smallest permitted number of such terrain tiles under the unit. If omitted, there is no minimum limit.

Max = number

Greatest permitted number of such terrain tiles under the unit. If omitted, there is no maximum limit.

"direction" NOT IMPLEMENTED

Direction

A bitmask in int format for the directions to build. (bits not specified yet)

Coward = boolean

Unit will not attack on sight, and will run away instead of retaliating. Use this for units that can't attack or are next to useless in combat (like resource workers) Available as a spell target check.

Harvester = boolean

Whether this unit can harvest resources from units that have CanHarvestFrom = true.

Neutral = boolean

The unit must always be owned by the neutral player. The map editor displays the neutral unit types in a separate list. Neutral unit types for plants and minerals should have Building = true so that the corpses of such units cannot fuel spells; but unlike other buildings, neutral units can be placed on map fields that do not allow buildings.

CanCastSpell = {spell-name, ...}

This is used to determine what spells can this unit cast. It is followed by a list of spell names. Spells have to be declared already. Since some spells also rely on units being defined this can lead to a chicken and egg problem. It's better to declare an unit type in advance with just DefineUnitType( "unit-whatever", {}). Please see the documentation on spells. F.E. CanCastSpell = {"spell-healing", "spell-exorcism"}

AutoCastActive = {spell-name, ...}

Lists the spells that the unit casts automatically. The exact conditions for autocast must be defined under "autocast" in DefineSpell. The player can switch autocast on and off for individual units during the game but cannot change the default for new units. AI players ignore this setting because they have their own "ai-cast" section in DefineSpell and always enable autocast if possible.

RepairRange = number

Range that a unit can repair from, eg. RepairRange = 1.

RepairHp = number

Defines the amount of hp a unit gain for each repair animation. Units can only be repaired if this value is non-zero. F.E.: RepairHp = 4.

ComputerReactionRange = number

The reaction range for units of AI players. Each unit can automatically attack enemy units that enter its reaction range. See also Preference.ShowReactionRange.

PersonReactionRange = number

The reaction range for units of human players. Each unit can automatically attack enemy units that enter its reaction range. See also Preference.ShowReactionRange.

Priority = number

This is the ai priority level. High damage low-hp units for instancce should have higher priorities than say a peasant. It can be safely ignored.

AnnoyComputerFactor = number

This is another ai priority level. This is not used, but included in wc2 data. Maybe it should be used to attack resource buildings first? You can safely ignore it.

DecayRate = number

This is the unit's decay rate, in 1/6 seconds. It should be really really really changed to cycles. If you set this the unit will die by itself after a while. Don't use it for spells, spells will override this with their own ttl setting.

BurnPercent = number

The unit will start burning when it has less health than this, in percents.

BurnDamageRate = number

The rate at which the unit will get damaged. The period is the same as with regeneration.

Points = number

This is the score value of an unit. Used for the final score.

Missile = missile-name

Some units fire by throwing missiles, this is the missile thrown. You can use it for close range units as well, but I can't really see the point.

Corpse = {unittype-name, number}

This is the corpse of the unit. When the unit dies and passes through it's death animation it turns into this. It's a list of an unittype-name and a a corpse frame number. The unit type to which refers should have Vanishes = true. As you can see in DefineAnimations(), an animation is composed out of several script frames, this is the frame to start the script from. FE: Corpse = {"unit-dead-body", 0}

ExplodeWhenKilled = missile-name

Sets unit to explode when killed, syntax is followed by the missile to use. eg. ExplodeWhenKilled "missile-explosion"

DeathExplosion = explosion-function

Set the lua function that will create the particles of the explosion.

AttackFromTransporter = boolean

Gives units with range the ability to attack from within a transporter such as a building. These can act like amoured personnel carriers or bunkers

CanTransport = boolean

Unit is a transporter, you can place organic land units inside. (FIXME: allow different restrictions for different transporter types.)

MaxOnBoard = number

This is only used for transporters, It's the maximum allowed on board. Curently you can't have more that 6, or you won't get any buttons for the rest.

Organic = boolean

Only organic units can be carried in transporters. Spell conditions in DefineSpell can check the Organic flag, so that you can prevent healing spells from affecting machines.

Revealer = boolean

This is a special flag to use for reveal map spells. A reveal map smell is in fact a summon spell with an infinite range, that summons an unit with the revealer flag. Revealer are summoned and marked removed, but they still keep their sight. This way a revealer unit can't be attacked, won't show on the minimap and can't be interacted with. Please see the documentation on spells.

SelectableByRectangle = boolean

Most units should have this flag. When false the unit will only get selected alone, use this for buildings. Enemy units are never selectable by rectangle.

Mana = number or boolean or {tag = value, ...}

SightRange = number or boolean or {tag = value, ...}

RadarRange = number or boolean or {tag = value, ...}

RadarJammerRange = number or boolean or {tag = value, ...}

Armor = number or boolean or {tag = value, ...}

BasicDamage = number or boolean or {tag = value, ...}

PiercingDamage = number or boolean or {tag = value, ...}

HitPoints = number or boolean or {tag = value, ...}

AutoRepairRange = number or boolean or {tag = value, ...}

custom variable = number or boolean or {tag = value, ...}

Each of these tags makes the unit type override some properties of the identically-named (predefined or custom) variable. Which properties get overridden depends on the type of the value you provide:

variable = {Value = number, Max = number, Increase = number, Enable = boolean}

Overrides individual properties of the variable. The tags and values of the table have the same meanings as in DefineVariables. If you omit some tags from the table, then the corresponding properties set with DefineVariables remain in force.

variable = number

Assigns the number as both the initial value and the maximum value of the variable, and enables the variable.
This is the same as variable = {Value = number, Max = number, Enable = true}.

variable = boolean

Enables or disables the variable.
This is the same as variable = {Enable = boolean}.

If you use custom variables, you must define them with DefineVariables before you define any unit types.

Example

DefineUnitType("unit-footman", { Name = "Footman",
  Image = {"file", "alliance/units/footman.png", "size", {72, 72}},
  Animations = "animations-footman", Icon = "icon-footman",
  EnergyValue = 600,
  MagmaValue = 60,
  HitPoints = 60,
  DrawLevel = 40,
  TileSize = {1, 1}, BoxSize = {31, 31},
  SightRange = 4, ComputerReactionRange = 6, PersonReactionRange = 4,
  Armor = 2, BasicDamage = 6, PiercingDamage = 3, Missile = "missile-none",
  MaxAttackRange = 1,
  Priority = 60,
  Points = 50,
  Corpse = {"unit-dead-body", 6},
  Type = "land",
  RightMouseAction = "attack",
  CanAttack = true,
  CanTargetLand = true,
  Organic = true,
  SelectableByRectangle = true,
  -- distance is >3 from gold, and <2 from a watch tower
  -- or distance is >6 from goldmine
  BuildingRules = { { "distance", { Distance = 3, DistanceType = ">", Type = "unit-gold-mine"},
  					  "distance", { Distance = 2, DistanceType = "<", Type = "unit-gold-mine"}},
					{ "distance", { Distance = 6, DistanceType = ">", Type = "unit-gold-mine"},
					}
				  },
  Sounds = {
    "selected", "footman-selected",
    "acknowledge", "footman-acknowledge",
    "ready", "footman-ready",
    "help", "basic alliance voices help 1",
    "dead", "basic alliance voices dead"} } )