#==== #==== Necessary Code: will cause error if these are not included

name: string Defines the unit raw name, game uses it to identify as a unique
name. (This is not displayed in-game) name: customTank1
mass: int The 'weight' of the unit, defines how it collides with other units, a
greater value means it's tougher to push. mass: 3000
radius: int Circular area around the unit that makes it selectable. (mouse
click/screen touch) radius: 20
price: int / price The unit cost from builders/buildings. Defaults to credits
if no resource type is used price: 500, gold=5, stone=10
class: string Reserved for future use, must be CustomUnitMetadata by
default. class: CustomUnitMetadata
maxHp: int The max health for the unit. (will spawn with this value). maxHp:
200
techLevel: int Defines the Tech Level of the unit, there're 3 levels and each
will appear in a different color in the GUI. techLevel: 1
buildSpeed: float / s Time it takes to build the unit. (may multiply with builder
speed) buildSpeed: 3s
#==== #==== Common Keys
altNames: string(s) Comma separated list of names. Like name but lower
priority, useful for multiple optional mods. altNames: custTank1, customTank1,
cTank1
strictLevel: float "Defaults to 0. 1 = Errors if keys are duplicated. Add to
""all-units.template"" in root to apply to all units." strictLevel: 1
isBio: bool Choose whether the unit is bioligical or not, affects sound and
splat (unless hideScorchMark:true) isBio: true
isBug: bool Changes some death defaults, and sort order in Sandbox. isBug:
false
isBuilder: bool Normally required if this unit places buildings. Defaults to
[ai]useAsBuilder. isBuilder: true
streamingCost: price Like price but paid for overtime while this unit is being
queued or built. Construction or queue is paused if resources run out while
building.
switchPriceWithStreamingCost: bool Shortcut to set streamingCost to price value
and clear price, add to all-units.template to quickly switch a mod over to
streaming resources.
#==== #==== Unit Stats Keys
selfRegenRate: float Passive self repair rate. selfRegenRate: 0.01
maxShield: int The max shield hitpoints of the unit. Can start with 0 hitpoints
if startShieldAtZero:true. maxShield: 500
startShieldAtZero: bool Unit starts with a 0 hitpoints shield on created if
true. startShieldAtZero: true
shieldRegen: float Passive shield regen rate. shieldRegen: 0.15
energyMax: float Defaults to 0. Energy that can be used as ammo for turrets, laser
defense and actions. energyMax: 1
energyRegen: float Passive energy regen rate. energyRegen: 0.001
energyStartingPercentage: float Sets the percentage of charged energy when the
unit is first built. energyStartingPercentage: 0.5
energyNeedsToRechargeToFull: float Disables weapons using energy after reaching
zero till fully recharged if true. energyNeedsToRechargeToFull: true
energyRegenWhenRecharging float Regen rate while recharging.
armour: int Damage taken away from each hit. (not currently used in any
vanilla units) armour: 6
armourMinDamageToKeep: int Min damage to keep from received damage. Defaults to
1. armourMinDamageToKeep: 2
borrowResourcesWhileAlive: price Takes these resources when created and returns
them when removed or destroyed. borrowResourcesWhileAlive: gold=10
borrowResourcesWhileBuilt: price Like borrowResourcesWhileAlive but doesn't take
affect till built. Mostly useful for buildings like houses that have negative
resources to add to the unit cap, etc. borrowResourcesWhileBuilt: supplyCap = -
10
generation_resources: price Income unit creates. (custom resource version)
generation_resources: credits=5, gold=20
generation_active: logicBoolean Disables generation_resources/credits
when false. (logic_boolean) generation_active: if not self.hp(lessThan=100)
generation_credits: int Income unit creates. (credits only)
generation_credits: 2
generation_delay: int How often generation_resources/credits is added. Defaults
to 40. (changing not recommended) generation_delay: 40
#==== #==== UI and Graphics Keys
showInEditor: bool Set to false to hide unit in Sandbox editor. (Defaults to
true) showInEditor: false
displayText: LocaleString The unit name that the game shows to the
player. displayText: Custom Tank
displayText_{LANG}: string LANG = ISO 639-1 Code to show this text instead
when game is in this language. displayText_es: Tanque Personalizado
displayDescription: LocaleString Unit description that the game shows to
the player. displayDescription: -Fast movement\n-Light damage
displayDescription_{LANG}: string LANG = ISO 639-1 Code to show this text
instead when game is in this language. displayDescription_es: -Movimiento
rápido\n-Daño ligero
displayLocaleKey: string Translation file key for unit name and description.
displayLocaleKey: units.mechArtillery
displayRadius: int Defaults to radius value. Set to show a larger or smaller
selection circle UI on units. displayRadius: 20
uiTargetRadius int Defaults to displayRadius value. Radius used when
attacking/reclaiming/etc this unit
shieldRenderRadius: int Defaults is a little bigger than radius. Set to show
a larger or smaller shield circle on units. shieldRenderRadius: 12
shieldDisplayOnlyDeflection: bool Hide shield unless deflecting shot if true.
shieldDisplayOnlyDeflection: true
shieldDeflectionDisplayRate: float Defaults to 4. High value causes shield
deflection to fade disappear faster. shieldDeflectionDisplayRate: 3
showOnMinimap: bool Defaults to true. Hide units on minimap if false.
showOnMinimap: false
showActionsWithMixedSelectionIfOtherUnitsHaveTag: bool Shows a merged action
list if all units selected includes one of these tags. Useful for converted units.
showActionsWithMixedSelectionIfOtherUnitsHaveTag: true
showOnMinimapToEnemies bool Useful for stealth units
#==== #==== Building Only Keys
isBuilding: bool Defines if the unit is a building. isBuilding: true
footprint: ints Left, up, right, down. Tiles taken up which block unit movement.
Defaults to 0,0,0,0 = 1 center tile. footprint: 0,0,1,1
constructionFootprint: ints Tiles taken up for placement of other buildings.
Defaults to 0,0,0,0 = 1 center tile. constructionFootprint: -1,-1,1,3
displayFootprint: ints Left, up, right, down. Only applies to buildings, just used
for GUI. Defaults to footprint. displayFootprint: 0,0,1,1
buildingSelectionOffset: int Defaults to 0. Adds or removes padding on the
drawn selection rect in UI. buildingSelectionOffset: 4
buildingToFootprintOffsetX: float Defaults to 10. Change the building position in
the footprint on the X-axis. buildingToFootprintOffsetX: 4
buildingToFootprintOffsetY: float Defaults to 10. Change the building position in
the footprint on the Y-axis. buildingToFootprintOffsetY: 6
placeOnlyOnResPool: bool Normally used for extractors, forces building
construction in a resource pool. placeOnlyOnResPool: true
selfBuildRate: float Rate unit builds itself when placed without a builder.
selfBuildRate: 0.0008
ignoreInUnitCapCalculation defaults to true for buildings otherwise false.
Set to true to not count this unit in unit cap.
#==== #==== Misc Keys
copyFrom: file(s) (ini) Uses unit data from another ini file as default for
this unit, supports multiple files. copyFrom: ROOT:defaultTanks.template,
tankT1.ini
dont_load: bool Do not load unit, and don't error on missing data. Can be useful
when used with copyFrom. dont_load: true
overrideAndReplace: string(s) Overrides another unit with this unit. Build
links and map positions to target unit will be replaced. overrideAndReplace:
builder, combatEngineer
onNewMapSpawn: string Values: emptyResourcePools_asNeutral,
emptyOrOccupiedResourcePools_asNeutral, mapCenter_asNeutral,
mapCenter_eachActiveTeam, spawnPoint_eachActiveTeam
globalScale: float Defaults to 1. Changing not recommended. globalScale: 2
isLocked: bool Disallow building of this unit. Can be used with
overrideAndReplace to restrict units player can build. isLocked: true
isLockedIfGameModeNoNuke: bool Disallows building of this unit if nukes are
disabled during match setup. isLockedIfGameModeNoNuke: true
experimental: bool Tag unit as experimental. Affects zoomed out icon and end
game stats. experimental: true
stayNeutral: bool Set to false to disable capture when unit is on the neutral
team. stayNeutral: false
createNeutral: bool Set to true to always spawn the unit on the neutral team.
createNeutral: true
createOnAggressiveTeam: bool Set to true to always spawn the unit on aggressive
teams on single player matches. createOnAggressiveTeam: true
tags: string(s) List of comma separated strings. Used to classify units, create
special actions and balances. tags: tank, smallTank, piercingDamage
defineUnitMemory Can define several variables for custom storage, unique for
each unit. Allowed types: boolean, float/number, unit, string. "defineUnitMemory:
boolean nukeActive, boolean laserReady, float experience, unit nextTarget, unit
homeBase, string customText
"
fogOfWarSightRange: int Sets number of tiles this unit can see through the
fog of war. Defaults to 15. fogOfWarSightRange: 18
fogOfWarSightRangeWhileNotBuilt int Fog of War range when unit/building is
incomplete. Defaults to fogOfWarSightRange
softCollisionOnAll: int Creates a soft collision effect when touching other
units. softCollisionOnAll: 3
disableAllUnitCollisions: bool Unit cannot collide with others if true.
disableAllUnitCollisions: true
isUnrepairableUnit: bool No unit can repair this unit if true.
isUnrepairableUnit: true
isUnselectable: bool If true unit cannot be selected. (includes AI players)
isUnselectable: true
isUnselectableAsTarget bool Defaults to isUnselectable. Can be used to create
units that cannot be selected but can be targeted for attack, reclaim, etc
isPickableStartingUnit: bool If true, unit is added to dropdowns for starting unit
in game setup menus. isPickableStartingUnit: true
startFallingWhenStartingUnit: bool Unit will appear falling from skies when
starting unit if true. startFallingWhenStartingUnit: true
soundOnAttackOrder: sound(s) List of sound names. Only one will be played on
each attack order. Only .ogg and .wav formats. soundOnAttackOrder:
tankAttackOrder1.ogg, tankAttackOrder2.ogg
soundOnMoveOrder: sound(s) List of sound names. Only one will be played on each
move order. Only .ogg and .wav formats. soundOnMoveOrder: tankMoveOrder1.ogg,
tankMoveOrder2.ogg
soundOnNewSelection: sound(s) List of sound names. Only one will be played on
each unit selection. Only .ogg and .wav formats. soundOnNewSelection:
tankSelection1.ogg, tankSelection2.ogg
canNotBeDirectlyAttacked: bool No unit can directly target this unit. If true
this will also skip this unit in victory/defeat checks.
canNotBeDirectlyAttacked: true
canNotBeDamaged bool Defaults to value of canNotBeDirectlyAttacked (be careful
setting this without canNotBeDirectlyAttacked, as AI will attack forever)
canNotBeGivenOrdersByPlayer: bool If true unit will not take player or AI orders.
canNotBeGivenOrdersByPlayer: true
canOnlyBeAttackedByUnitsWithTags: strings(s) List of tag strings, only units
with these tags can directly target this unit. canOnlyBeAttackedByUnitsWithTags:
piercingTank, powerfulTank
disableDeathOnZeroHp bool "Setting to true allows unit to continue living even
at 0 HP, useful for custom ""death"" action. Warning: If not used with an
autoTrigger, etc units will attack this unit forever."
#==== #==== Transport Keys
transportSlotsNeeded: int Defaults to 1. Number of slots this unit uses up in a
transport, experimentals are often set to 5. transportSlotsNeeded: 2
maxTransportingUnits int Number of slots this units has for transporting other
units. maxTransportingUnits: 5
transportUnitsRequireTag: string(s) Only allows trasport of units that have
one of these tags. transportUnitsRequireTag: smallTank, soldier
transportUnitsRequireMovementType: movementTypes Only allows trasport of units
that have one of these movement types. transportUnitsRequireMovementType: AIR,
WATER
transportUnitsBlockAirAndWaterUnits: bool Defaults to true. This unit can
only transport LAND units if true. transportUnitsBlockAirAndWaterUnits: false

transportUnitsKeepBuiltUnits: bool Makes built units stay inside transport instead

of exiting it once ready if true. transportUnitsKeepBuiltUnits: true
transportUnitsCanUnloadUnits: LogicBoolean Defaults to: if not
self.isOverLiquid() and not self.isMoving(). This unit cannot unload units if
false. transportUnitsCanUnloadUnits: false
transportUnitsAddUnloadOption: bool Defines if unload button should be added
to the unit menu transportUnitsAddUnloadOption: false
transportUnitsUnloadDelayBetweenEachUnit: float Changes the delay it takes between
each unit getting unloaded. transportUnitsUnloadDelayBetweenEachUnit: 12
transportUnitsKillOnDeath: LogicBoolean Defaults to true. If false
transported units don't die when transport dies. transportUnitsKillOnDeath: if
self.isOverLiquid()
transportUnitsHealBy: float Rate to heal units that are being transported.
transportUnitsHealBy: 0.1
transportUnitsBlockOtherTransports: bool Defaults to true, if false this
transports can hold other transports. transportUnitsBlockOtherTransports: false
whileNeutralTransportAnyTeam: bool This unit can transport units of any team while
neutral if true. whileNeutralTransportAnyTeam: true
whileNeutralConvertToTransportedTeam: bool Converts this unit to transported
team while neutral. Useful with whileNeutralTransportAnyTeam.
whileNeutralConvertToTransportedTeam: true
convertToNeutralIfNotTransporting: bool Reverts back this unit to neutral when
unloaded. Useful with whileNeutralTransportAnyTeam.
convertToNeutralIfNotTransporting: true
transportUnitsOnTeamChangeKeepCurrentTeam: bool Keeps transported units on
their orginal team when this unit is converted if true.
transportUnitsOnTeamChangeKeepCurrentTeam: true

#==== #==== Resource Node Keys

resourceRate: float Used with canReclaimResources. Allows other teams to

reclaim this unit. Normally used with neutral team. Use price to set what resources
are gained.
similarResourcesHaveTag: string(s) When this has been reclaimed harvester
unit moves on to another resource with these tags. similarResourcesHaveTag:
goldResource
resourceMaxConcurrentReclaimingThis: int Defaults to unlimited. Set to
restict how many units can reclaim this resource at the same time.
resourceMaxConcurrentReclaimingThis: 3
reclaimPrice: int Like price but for resources. Useful for buildable
resources. reclaimPrice: gold=1000
#==== #==== Resource Harvester Keys
canReclaimResources: bool If true this unit can gather resources, useful with
resourceRate. canReclaimResources: true
canReclaimResourcesNextSearchRange: int Defines the resource search range of this
unit when its main gathered resource runs out. canReclaimResourcesNextSearchRange:
100
canReclaimResourcesOnlyWithTags: string(s) This unit is only allowed to gather
resources with these tags. canReclaimResourcesOnlyWithTags: foodResource,
goldResource
canReclaimUnitsOnlyWithTags string(s) This is for reclaiming units, not for
resources. See canReclaimResourcesOnlyWithTags
resourceReclaimMultiplier float "Multiplies the builder's reclaim speed.
Different from the related key ""nanoUnbuildSpeed"""
#==== #==== Construction and Factory Keys
canRepairUnitsOnlyWithTags string(s)
canRepairBuildings: bool Can this can heal ally buildings (isBuilder:true is
required) canRepairBuildings: true
canRepairUnits: bool Can this can heal ally units. (isBuilder:true is required),
canRepairBuildings required for buildings. canRepairUnits: true
autoRepair: bool Automatically try and repair damaged units in nano range.
(isBuilder:true is required) autoRepair: true
nanoRange: int Defaults to 85. Defines the unit building/repair/reclaim range.
nanoRange: 110
nanoRepairSpeed: float Defaults to 0.2. Defines the unit nano repair/reclaim
speed. nanoRepairSpeed: 0.01
nanoBuildSpeed: float Defaults to 1. Defines the unit nano building speed. (May
multiply with target's buildSpeed) nanoBuildSpeed: 0.9
nanoUnbuildSpeed: float How fast a builder reclaims an incomplete building
(defaults to 1)
nanoReclaimSpeed: float How fast a builder reclaims a normal unit (not a resource
unit)
nanoRangeForRepairIsMelee: bool Defines if this unit must touch its target to
repair it. nanoRangeForRepairIsMelee: true
nanoRangeForReclaimIsMelee: bool Defines if this unit must touch its target to
reclaim it. nanoRangeForReclaimIsMelee: true
nanoRangeForRepair: int Defines a specific range for the repair action of
this unit. nanoRangeForRepair: 60
nanoRangeForReclaim: int Defines a specific range for the reclaim action of
this unit. nanoRangeForReclaim: 60
nanoFactorySpeed: float Defaults to 1. Multiplies the buildSpeed value of the
created unit if this unit is a factory. nanoFactorySpeed: 1.2
extraBuildRangeWhenBuildingThis: int Temporarily adds extra build range to
builders to build this unit. Useful for water based buildings.
extraBuildRangeWhenBuildingThis: 90
builtFrom_#_name: string(s) Useful if adding this unit to build to existing
buildings. Like canBuild but in opposite direction. builtFrom_1_name:
landFactory, airFactory
builtFrom_#_pos: float Order this build link appears in UI. Using canBuild instead
is more recommended. builtFrom_1_pos: 0.1
builtFrom_#_forceNano: bool Build as if this is a building if true. (even if it's
a unit) builtFrom_1_forceNano: true
builtFrom_#_isLocked: LogicBoolean If true this unit cannot be built in this
build link. (can be conditioned if logicBooleans are used) builtFrom_1_isLocked: if
self.hp(lessThan=100)
builtFrom_#_isLockedMessage: LocaleString Message shown when this build link
is locked. builtFrom_1_isLockedMessage: -Needs more population
exit_x: float Where created or unloaded units appears from the transport or
building. Defaults to 0. exit_x: 0
exit_y: float Where created or unloaded units appears from the transport or
building. Defaults to 5. exit_x: 5
exit_dirOffset: float Defaults to 180 for units and 0 for buildings. Defines the
exit direction of created or unloaded units. exit_dirOffset: 140
exit_heightOffset: float Defaults to 0. Defines the height where created or
unloaded units appears. exit_heightOffset: 16
exit_moveAwayAmount: float Defaults to 70. Defines the distance that created or
unloaded units moves from this unit. exit_moveAwayAmount: 10
exitHeightIgnoreParent bool Ignores parent height for exit height; useful for
separating attachments with their parents for building
#==== #==== Death Keys
dieOnConstruct: bool Deletes this unit when it starts to build if true. (target
building/unit likely will need selfBuildRate set) dieOnConstruct: true
dieOnZeroEnergy: bool Kills this unit if energy level reaches zero when true.
dieOnZeroEnergy: true
numBitsOnDeath: int Defines the number of scattered bit fragments when this
unit dies. numBitsOnDeath: 20
nukeOnDeath: bool Unit will spawn a nuke detonation built-in effect when dies
if true. nukeOnDeath: true
nukeOnDeathRange: float Defines the nuke effect range when using nukeOnDeath.
nukeOnDeathRange: 140
nukeOnDeathDamage: float Defines the nuke effect area damage when using
nukeOnDeath. nukeOnDeathDamage: 2000
nukeOnDeathDisableWhenNoNuke: bool Defaults to false. If true this unit will not
explode with nuke when nukes are disabled in skirmish maps.
nukeOnDeathDisableWhenNoNuke: true
fireTurretXAtSelfOnDeath: turret ref Auto-shoot a specific turret when this
unit dies. fireTurretXAtSelfOnDeath: turret_1
explodeOnDeath: bool Defaults to true. Disables the unit death explode built-in
effect if false. explodeOnDeath: false
explodeOnDeathGroundCollision: boolean Defaults to true. Disables the
explode built-in effect on death when unit touches ground if false.
explodeOnDeathGroundCollision: false
explodeTypeOnDeath: preset effects options: verysmall, small, normal, large,
largeUnit, building, buildingNoShockwaveOrSmoke, verylargeBuilding
effectOnDeath: effect(s) ref Spawns built-in or custom effects when unit
dies. effectOnDeath: shockwave, CUSTOM:pieces*3, CUSTOM:deathSound
effectOnDeathGroundCollision: effect(s) ref Like effectOnDeath but when unit
touches ground. Useful for flying units. effectOnDeathGroundCollision:
CUSTOM:bigExplosion
unitsSpawnedOnDeath: string(s) Spawns these units when dies. Comma separated
unit identifiers. unitsSpawnedOnDeath: tank*5, hoverTank
unitsSpawnedOnDeath_setToTeamOfLastAttacker: bool Units spawned on death will
appear on the last attacker team if true.
unitsSpawnedOnDeath_setToTeamOfLastAttacker: true
hideScorchMark: bool Disables the death scorch mark leaved when unit dies if
true. hideScorchMark: true
soundOnDeath: string(s) Sets a custom sound for this unit death.
soundOnDeath: tankExplosion1.ogg, tankExplosion2.ogg
effectOnDeathIfUnbuilt: effect(s) ref If the unit was not completed, and
is destroyed, play this effect. Defaults to effectOnDeath effectOnDeathIfUnbuilt:
CUSTOM:implode
#==== #==== Action Keys
autoTriggerCooldownTime: time (seconds) Post automatic action cooldown (Not
detection cooldown). Defaults to 1s. Warning: Setting this too low for many units
might effect performance depending on the action effects.
autoTriggerCooldownTime_allowDangerousHighCPU: bool Allows for auto action
cooldown lower than 0.2s. Default to false. Not recommended.
autoTriggerCheckRate enum options: everyFrame (default), every4Frames,
every8Frames. Note: all triggers regardless of check rate are checked when first
created and after an auto trigger cooldown. Note: Adding
[core]autoTriggerCheckRate:every8Frames to all-units.template could have a large
performance boost for mods with complex autoTriggers.
autoTriggerCheckRate:every8Frames
#==== #==== Deprecated Keys (can be used but there are better ways)
action_#_convertTo: string Deprecated in 1.13, use [action_x] sections
instead action_1_convertTo: customTank_2
action_#_pos: float Order action appears in UI action_1_pos: 0.1
action_#_price: int The price of your action for the unit. (All your sub
actions will be linked to the # you use) action_1_price: 1000
action_#_text: string A display text when you select your unit's action,
used to explain it's purpose. action_1_text: Upgrade to Custom Tank 2
action_#_description: string The action description. action_1_description: -
Converts the tank
action_#_addEnergy: float Adds energy to unit. Has no effect unless energyMax
is set action_1_addEnergy: 10
action_#_whenBuilding_cannotMove: bool Stops unit moving while action is being
applied. Useful for deploy like actions. action_1_whenBuilding_cannotMove: true
canBuild_#_name/pos/isLocked: string Use canBuild section instead.
canBuild_1_name: tank
Section [canBuild_NAME]
Code Value Type Description Example
name: string(s) "List of unit identifiers this unit can create. Can be buildings
or units. Add ""setRally"" to create a rally button" name: setRally, tank,
hoverTank, heavyTank
pos: float Order build link appears in this unit UI. pos: 0.1
tech: int Tech level. Mostly just affects build link colour in this unit UI.
Defaults to 1. tech: 2
forceNano: bool Builds target as if it was a building if true. (even if it's a
unit) forceNano: true
isVisible: LogicBoolean Hide this build link if true in this unit UI.
isVisible: if not self.energy(greaterThan=100)
isLocked: LogicBoolean Dynamically locks this build option and shows
isLockedMessage if true. isLocked: if self.hp(lessThan=100)
isLockedMessage: string Set to tell to players why a unit is locked.
isLockedMessage: -Needs 2 Barracks
isLockedMessage_{LANG}: string LANG = ISO 639-1 Code to show this text instead
when game is in this language. isLockedMessage_es: -Necesita 2 Cuarteles
isLockedAlt: LogicBoolean Another reason for this to be locked. Just
allows a different message to be shown. isLockedAlt: if
self.energy(greaterThan=90)
isLockedAltMessage: string Message for isLockedAlt.
isLockedAltMessage: -Needs less energy
isLockedAlt2: LogicBoolean Like isLockedAlt but to show one more message.
isLockedAlt2: if self.isMoving()
isLockedAlt2Message: string Message for isLockedAlt2.
isLockedAlt2Message: -Needs to be quiet
addResources: price(s) Adds these resources to self when placing the
building or producing the unit. addResources: ammo=5, setFlag=1
price: price(s) Overrides builded units/buildings price. Defaults to target
unit prices. price: credits=1000, ammo=5
isGuiBlinking: LogicBoolean Generates a blinking effect in UI if true.
isGuiBlinking: true
Section [graphics]
Code Value Type Description Example
#==== #==== Necessary code
file (image) image:
#==== #==== Common Keys
image: file (image) File path to png image.
image_back: file (image) An optional image drawn behind other units. Useful
for factories that units exit
image_shield file (image) Image to show as a custom shield
image_wreak: file (image) Image to use when unit dies. Can be NONE to
leave no wreak
image_offsetX: int Use this to adjust the graphics of a unit if it is too far
off one side
image_offsetY: int Use this to adjust the graphics of a unit if it is too far
off one side
isVisible logic If false will hide the unit.
isVisibleToEnemies bool Only visible to player and allies when false.
Recommend with showOnMinimapToEnemies. Useful for stealth units.
teamColoringMode How pixels are used for team coloring, options: pureGreen
(default), hueAdd, hueShift, disabled
teamColorsUseHue: bool False: Green pixels on unit gets converted to team color.
True: Whole unit is tinted the team colour. Defaults to false
scaleImagesTo: float Resize image to fit this value in pixels. Effects leg, and
shadow images as well.
imageScale: float Resize image. Defaults to 1. Effects leg, and shadow images as
well.
drawLayer: string Land units normally default to ground or ground2 if
transport. wreaks, underwater, bottom, ground, ground2, experimentals, air, top
whenBeingBuiltMakeTransparentTill float How long the transparent effect is
applied to incomplete units, set to 0 to disable completelyDefault: 1
icon_zoomed_out file (image)
icon_zoomed_out_neverShow bool
icon_build file (image) Displays icon of the unit on Build Panel
#==== #==== Turrets (images can also be set on each turret)
image_turret: file (image) Default image for all turrets, can also be set
per turret
teamColorsOnTurret bool Defaults false. Apply team colours on turret as well.
Also effects pre-turret images
scaleTurretImagesTo: float Will cause crash if image_turret is not specified,
even if image is set per turret
lock_body_rotation_with_main_turret: bool Locks body image locked to first
turret's direction
lock_leg_rotation_with_main_turret bool Locks legs and arms to first turret's
direction
#==== #==== Shadow
image_shadow: file (image) Image file, NONE, or AUTO. (AUTO will use image
and make it transparent black only.)
shadowOffsetX: float
shadowOffsetY: float
image_shadow_frames bool If shadow image should use frame animation of main
image
lock_shadow_rotation_with_main_turret: bool Locks body image shadow locked to
first turret's direction
#==== #==== Effects and animation
total_frames int Defaults to 1. Animations require this.
frame_width: int Calculated for you if total frames is set, but can be
overridden
frame_height: int Defaults to image height
splastEffect: bool True to create a water wave effect when over water. Default
false
dustEffect: bool True to create a dust effect when over land. Default false
splastEffectReverse: bool True to also create effect when unit is reversing
dustEffectReverse: bool True to also create effect when unit is reversing
movementEffect effect Custom movement effect, can be anything eg:
movementEffect: smoke, CUSTOM:fastDust*2, CUSTOM:pop*5
movementEffectReverse effect
movementEffectRate float
movementEffectReverseFlipEffects bool Create effect as if unit has rotated 180
when reversing
repairEffect effect ref Custom movement effect, can be anything. Replaces
default effect from builders
repairEffectAtTarget effect
repairEffectRate int Defaults to 5
reclaimEffect effect
reclaimEffectAtTarget effect
reclaimEffectRate int
rotate_with_direction: bool Defaults to true. Makes unit body image locked to 0
degrees when false. Often used with animation_direction_*
animation_direction_units: float 45 for 8 directions, 90 for 4 direction
animation. Used with rotate_with_direction:false
animation_direction_strideX: int Animation frames to offset on direction change.
animation_direction_strideY: int Animation frames to offset on direction change.
Used with frame_height.
animation_direction_starting: float Direction for first frame
disableLowHpFire bool
disableLowHpSmoke
showTransportBar: bool
showHealthBar bool
showEnergyBar bool
showShieldBar bool
showQueueBar bool
showShotDelayBar bool
#==== #==== Deprecated Keys (can be used but there are better, more adaptable ways)
animation_TYPE_start: int TYPE can be set to: attack, moving, idle. Use
[animation] section instead for more control animation_moving_start: 0
animation_TYPE_end: int End frame, must be larger then start
animation_moving_end: 3
animation_TYPE_scale_start: float Scale unit image. Defaults to 1. Useful for bio
units or breathing effects.
animation_TYPE_scale_end: float Scale unit image. Defaults to 1. Useful for bio
units or breathing effects.
animation_TYPE_speed: float Delay for each frame of animation. Larger values
cause slower animation
animation_TYPE_pingPong: bool Play animation in reverse before repeating.
Useful with scale_start/scale_end
Section [attack] The attack section is for global attack
characteristics, per-turret overrides these
Code Value Type Description Example
canAttack: bool If set to false, can not attack any unit. Regards of other
canAttack options below.
canAttackFlyingUnits: LogicBoolean can also be narrowed per turret. Note:
not required if canAttack is false.
canAttackLandUnits: LogicBoolean can also be narrowed per turret
canAttackUnderwaterUnits: LogicBoolean can also be narrowed per turret
maxAttackRange: float (multiplied by globalScale)
canAttackNotTouchingWaterUnits: LogicBoolean Default true. If false unit
can only attack units in contact with the water. Used for units with torpedos. (can
also be set per turret)
canOnlyAttackUnitsWithTags tags Will only attack units that has the specified
tags.
canOnlyAttackUnitsWithoutTags tags Can only attack units without the specified
tags.
turretMultiTargeting bool Allow each turrets to fire at a different target at
the same time. Very useful if [turret]limitingAngle is used
isMelee: bool Used with a low attack range (like maxAttackRange: 9) makes src
and target radius get added to range, and effects AI.
meleeEngangementDistance int Makes unit move to attack nearby units.
Defaults to 250 for melee, and 0 for non melee (Works even if non-melee, but might
be unexpected to players)
turretRotateWithBody bool Are all turrets rotated when body rotates. Defaults
to true
attackMovement: string normal/bomber. bomber attack movement will retreat
when energy runs out
dieOnAttack: bool Will die when it attacks.
isFixedFiring: bool Must aim body at target to shoot. Will often make the unit
need to stop before it can aim and shoot.
aimOffsetSpread: float Offset each shot multiplied by target radius. Defaults to
0.6 aimOffsetSpread:0 will make unit always attack center
stopTargetingAfterFiring bool Unit stops targeting after firing a shot.
Rarely used or needed.
disablePassiveTargeting: bool Unit only attacks manually ordered target.
Rarely used or needed.
showRangeUIGuide bool Will it show the range indicator. Useful for showing ranges
in radar and related structures.
shootDelayMultiplier float Defaults to 1. Can be dynamically changed with
setUnitStats
shootDamageMultiplier float Defaults to 1. Can be dynamically changed with
setUnitStats
#==== #==== Deprecated Keys - can be used but better to set these per turret
turretSize: float (multiplied by globalScale)
turretTurnSpeed: float
shootDelay: float Global delay, can also use delay on each turret
Section [turret_NAME] Turrets fire projectiles with different traits
Code Value Type Description Example
#==== #==== Necessary Code
float x:
float y:
#==== #==== Positioning/Stats

x: float
y: float
copyFrom: turret ref Copy all values from another turret as defaut values for
this turret copyFrom: 1
projectile projectile ref Projectile fired from this turret. eg: projectile:
torpedo
altProjectile projectile ref Alternative projectile fired from this turret
when altProjectileCondition is true
altProjectileCondition LogicBoolean Used with altProjectile
barrelX float Defaults to 0. Controls horizontal position for projectile spawn.
barrelY float Defaults to size. Note: size and barrelY have the same meaning
barrelHeight float Height of barrel in 3d. Effect projectile and shoot flame
starting height
size: float Controls the distance between the center of the turret and the point
from where projectiles spawn. size: 5
turnSpeed float Max turn speed of the turret
turnSpeedAcceleration float Defaults to disabled, and full turn speed is used.
turnSpeedDeceleration float Defaults to turnSpeedAcceleration. Setting this
higher than turn acceleration might allow faster targets to be hit
idleDir float Defaults to 0
idleDirReversing float Defaults to idleDir+180 unless attached to another turret
(as attached turret will often be rotating when reversing)
shouldResetTurret: bool Defaults true. False to disable the reseting turret
angle when idle
idleSweepAngle int "Disabled by default. Controls how far the turret will
""look"" left and right"
idleSweepDelay float Controls the delay between idleSweep movements
idleSweepSpeed float Controls the speed with which the turret sweeps when idle
idleSweepCondition LogicBoolean Disable idle sweep if false
idleSweepAddRandomDelay float Default 1-20 depends on idleSweepDelay, used to stop
sweep syncing up with other units
idleSweepAddRandomAngle int Default 0
attachedTo: turret ref Id of another turret to attach to, will be positioned
relative to it, and rotate with it.
slave: bool Locks this turret's direction and shot cooldown to attached
turret. Often used with warmup for multiple barrel guns
isMainNanoTurret: bool Defaults to false. Turret to use for creating buildings,
etc. should only be true on one turret, and should have canShoot set to false
energyUsage: float Required energy to fire weapon. Same as resourceUsage:
energy=X
resourceUsage price can be in credits/energy/hp/shield/ammo. Stops firing if
not met resourceUsage: credits=5, energy=5, hp=100, shield=5, ammo=1
#==== #==== Timing
delay: float Override global shootDelay for this turret
linkDelayWithTurret turret ref When this other turret fires the cooldown delay
on this turret will be reset/removed
warmup: float Delay before firing a shot.
warmupCallDownRate float Rate to reduce warmup when turret is not ready to
fire at any targets
warmupNoReset bool Defaults to false. When true warmup is not reset after
firing a shot and turret doesn't wait for warnup. Used with warmupCallDownRate and
warmupShootDelayTransfer.
warmupShootDelayTransfer float Defaults to 0, amount to reduces the next shot
delay depending on warmup. When used with warmupNoReset, can make a each shot
faster.
#==== #==== On Shoot
onShoot_freezeBodyMovementFor Freezes body movement while shooting.
barrelOffsetX_onOddShots: float 0 by default. Sets a barrelX offset only during
odd numbered shots, useful for twin-barreled units. Use with barrelX
#==== #==== Targeting control
aimOffsetSpread
canShoot: bool Defaults to true
canAttackFlyingUnits: LogicBoolean Narrows targeting for this turret, note
targeting for the whole unit in [attack] is applied first. (so you can only use
this to target less not more)
canAttackLandUnits: LogicBoolean
canAttackUnderwaterUnits: LogicBoolean
canAttackNotTouchingWaterUnits: LogicBoolean Default true. If false unit
can only attack units in contact with the water. Used for units with torpedos.
canOnlyAttackUnitsWithTags tags
canOnlyAttackUnitsWithoutTags tags
canAttackCondition: LogicBoolean Normally, used to optionally disable a
turret based on a LogicBoolean. Eg: this unit's height canAttackCondition: if
not self.flying
canAttackMaxAngle float Max angle to target for turret to be allowed for fire.
Defaults to 5, don't set lower. Can be set to 181 for turrets that don't need to
turn to fire missiles.
clearTurretTargetAfterFiring bool Clears the turrets sub-target when using multi-
targeting
limitingRange: float Make this turret have less range than the maxAttackRange.
Do not apply this to all turrets change maxAttackRange instead.
limitingAngle Linked with idleDir. Turret will only be able to fire at
units +/- this angle.
limitingMinRange Sets minimum range for turret. limitingMinRange: 200
interceptProjectiles_withTags Currently used with anti-nuke units.
interceptProjectiles_andTargetingGroundUnderDistance
interceptProjectiles_andUnderDistance Defaults to 2000, distance inflight
before firing
interceptProjectiles_andOverHeight Defaults to 0
interceptProjectile_removeTargetLifeOnly bool Defaults to false. When false
projectiles are just removed. Could be true to make hit projectiles explode or
split when hit
laserDefenceEnergyUse: float Set to enable a projectile laser defence from this
turret. Should also set the energyMax in core.
#==== #==== Graphics and effects
invisible: LogicBoolean Don't render this turret, but still can shoot, etc.
image: file (image) Use custom image. Overrides unit's main turret image
image_applyTeamColors bool
image_drawOffsetX float
image_drawOffsetY float
"chargeEffectImage:
" file (image) Used with warmup. Shows a scaling effect image on turret
barrel when charging.
warmupStartEffect effect ref
shoot_sound: string Can be linked to an .ogg or .wav file, or one of the
default game sounds (list at bottom of reference) shoot_sound: tank_firing |
shoot_sound: missile.wav | shoot_sound: ROOT:audio/shoot.ogg
shoot_sound_vol: float
shoot_flame: effects Current types are: small, large, smoke, shockwave, or
CUSTOM: effectSectionName eg: shoot_flame: smoke, CUSTOM:lightFade,
CUSTOM:pop*5
shoot_light color
idleSpin: float Spin rate when idle, used on missile turrets
onShoot_playAnimation animation ref Play a custom animation from an
[animation] section after firing this turret
onShoot_triggerActions action refs Trigger these actions each time this turret
fires
onShoot_freezeBodyMovementFor time
unloadUpToXUnitsAndGiveAttackOrder int Unloads X units at turret barrel
locations and gives them the attack order of turret target
recoilOffset float Push turret forward or back after firing for a recoil
effect. Value in pixels.
recoilOutTime float Time to get to offset position after firing
recoilReturnTime float Time to return to default position
showRangeUIGuide bool
Section [projectile_NAME] Projectiles are necessary to inflict damage on
an enemy, but can also be used for other purposes
Code Value Type Description Example
#==== #==== Necessary Code
int directDamage: or areaDamage:
life:
#==== #==== Core
life: How long till this projectile gets removed if it hasn't hit a target,
300 might be a good starting point, change depending on speed and range
deflectionPower: float Defaults to 1. Energy needed for laser defence to deflect.
-1 to disable deflection (only disable for special weapons like flames)
explodeOnEndOfLife bool Default to false. True to explode at end of life with
all side effects and area damage instead of disappearing. Good for making area-
denial weapons.
autoTargetingOnDeadTarget: bool Retarget to nearby unit if target dies while in
transit
autoTargetingOnDeadTargetRange int The range which it will select a new
target if old target has died
autoTargetingOnDeadTargetLead float The lead it will try to have on the new target
unloadUpToXUnitsFromSource int Unload X units from source unit, to projectile
explode location
teleportSource bool Move unit that shot this projectile to projectile explode
location
spawnUnit unit types Spawn new units of this type at projectile explode location
eg: spawnUnit: heavyTank, tank*5, hoverTank(offsetX=10)
spawnProjectilesOnEndOfLife projectile ref Spawns new projectiles on end of
life, useful for secondary projectiles spawnProjectilesOnEndOfLife:
torpedo_split(offsetDir=90), torpedo_split(offsetDir=-90)
spawnProjectilesOnExplode projectile ref Projectiles to spawns when this
projectile hits it's target
spawnProjectilesOnCreate Spawns projectiles on creation of this
projectile, useful for making true shotgun-like projectile spread
convertHitToSourceTeam bool Convert units hit to the team that fired this
projectile. Useful to make capturing systems
tags tags Useful for projectile interceptions (e.g. Nuke and Anti-Nuke
Interaction)
flameWeapon: bool Generates small flames on hit (only cosmetic)
#==== #==== Damage
directDamage: int Damage to target unit on hit. Does not work with
targetGround:true as it won't have a clear unit to target
areaDamage: int Damages on arrival of target with an area effect, use areaRadius
to adjust size of damage. targetGround needs this to damage
areaRadius: float How wide areaDamage effects. Note this drops off (unless
areaDamageNoFalloff is used)
areaDamageNoFalloff bool Removes the falloff from areaDamage
areaRadiusFromEdge bool Applies damage from edge of units instead of center.
Mostly effects large units.
areaExpandTime float Applies area damage as an expanding blast wave rather than
instantly. Useful for nuke projectiles
areaHitAirAndLandAtSameTime bool Defaults to false
areaHitUnderwaterAlways bool Defaults to false
areaIgnoreUnitsCloserThan int Units closer than this range aren't effected.
Rarely needed. Not recommended for normal projectiles.
buildingDamageMultiplier float Defaults to 1
shieldDamageMultiplier float Defaults to 1. eg: 0 to do no damage to shields
and 2 to do double damage
shieldDefectionMultiplier float Defaults to 1. The amount of shield to bypass
eg: 0 to ignore shields and directly damage hull
hullDamageMultiplier float Defaults to 1. Can be used to create EMP weapons that
affect shields only eg: 0 to ignore hull and only damage shields
ignoreParentShootDamageMultiplier bool
armourIgnoreAmount int Amount of armour to ignore on target and do damage as
if this armour was not there
friendlyFire bool/string Lets area effect projectiles damage own team units
(can't damage allies). Useful for nuke-like weapons friendlyFire: false /
friendlyFire: true / friendlyFire: only-ignoreEnemy
mutatorX_ifUnitWithTags tags Applies mutators to this projectile if target has
corresponding tags eg: mutator1_ifUnitWithTags: infantry
mutatorX_ifUnitWithoutTags tags Same as ifUnitWithTags, but applies if target
doesn't have the set tags eg: mutator1_ifUnitWithoutTags: strongArmour
mutatorX_directDamageMultiplier float Changes directDamage. Defaults to 1. Be
careful not to confuse players using this as the effect may not be clear. Use amour
instead when possible
mutatorX_areaDamageMultiplier float Same as directDamageMultiplier but for
areaDamage. Defaults to 1.
mutatorX_changedExplodeEffect effect Change explode effect if this mutator is
active. Eg make a bounce off amour effect. Helps to make the damage change more
clear to players (Doesn't work with targetGround.)
mutatorX_addResourcesDirectHit resource Add resource to all hit units.
Warning: Be careful not be break units from other mods by adding random resources
or energy to them that they don't expect.
mutatorX_addResourcesAreaHit resource
#==== #==== Movement
targetGround bool Target ground, and don't home in on target. Note: only
areaDamage is applied if targeting ground.
targetGround_includeTargetHeight bool Default false. for area affect AA weapons
targetGroundHeightOffset float Default 0. for shooting over or under a target.
Useful for projectiles that split and rain down.
speed: float Projectile default travel speed
targetSpeed: float Accelerate to this speed
targetSpeedAcceleration float Controls the speed rampup for targetSpeed
ballistic: bool Makes projectiles fly up into the air and come down, instead of
going in a straight line
ballistic_delaymove_height: float
ballistic_height: float
targetGroundSpread: float Randomly makes the shot inaccurate by this amount.
Also used by weapons like the flamethrower
speedSpread: float Randomly change the starting projectile speed by this
amount
instant bool Hit target instantly
instantReuseLast: bool Recycles last projectile fired, only one projectile ever
exists. Can turn lasers into beam weapons by using lower rate of fire and setting
this to true
instantReuseLast_alsoChangeTurretAim bool Make turret's aim include last
projectile's spread and sweep offsets, useful for beam weapons
instantReuseLast_keepAreaDamageList bool Default false. Keeping the list was the
normal behaviour in 1.13 making area damage not apply a second time but this is not
useful. Use this only if you want the old behaviour.
disableLeadTargeting bool Disable the lead targeting calculations when aiming
at a moving target. Defaults false.
leadTargetingSpeedCalculation float The expected speed of this projectile for
targetGround lead target calculation. Defaults to 'targetSpeed' if set otherwise
'speed'.
initialUnguidedSpeedHeight Sets vertical speed for projectiles with
targetGround. Use gravity to make smooth arching projectiles
gravity: Controls the pull for projectiles that target ground. Use
together with initialUnguidedSpeedHeight
turnSpeed float Limits the turn speed of a projectile, making them inaccurate
even with directDamage
wobbleAmplitude float How wide the projectile will wobble
wobbleFrequency float How often the projectile will wobble
pushForce float Push (or pull with a negative value) the units that get hit.
Divided by target mass
pushVelocity float Push (or pull with a negative value) the units that get
hit. Ignores target mass
moveWithParent bool Move projectile as parent moves. Useful for beam effects
that need to stick to source turret.
sweepOffset float Useful for beam effects.
sweepOffsetFromTargetRadius float Add to sweep offset by factor of target's
radius. 0.4 would be 40% sweepOffsetFromTargetRadius: 0.4
sweepSpeed float Useful for beam effects.
retargetingInFlight bool Can retarget a new target mid-flight, perfect for
flak-style weapons and projectiles that collide
retargetingInFlightSearchDelay float/time How long between searching for new
targets. Default 5
retargetingInFlightSearchRange int Range which targets are reselected.
Default 120
retargetingInFlightSearchLead float The lead of the projectile to try to hit the
target. Default 15
retargetingInFlightSearchOnlyTags tag ref Only retarget units with these tags
#==== #==== Graphics and effects
color color Recolors this projectile using a hex value. color: #bebe50
invisible bool
image: file (image) Use custom image. Overrides drawType and frame
drawType int Built-in image to use. 0:projectiles.png 1:projectiles_large.png
2:projectiles2.png drawType:1
drawSize: float Scale image. Defaults to 1
frame int Built-in image frame to use, starts at zero.
hitSound: bool Default true
explodeEffect effect ref list explodeEffect: smallExplosion,
CUSTOM:myExplodeEffect
explodeEffectOnShield effect ref list Use this effect if shield is active on
target
teamColorRatio float Mix 0-1 of team colour into color field
teamColorRatio_sourceRatio float default is (1-teamColorRatio). Keep more of
color when mixing. Note this might saturate colors.
drawUnderUnits bool
effectOnCreate effect ref list
shouldRevealFog bool Reveal fog to player on explode
alwaysVisibleInFog bool
nukeWeapon bool Shows on mini-map when fired. Some other side effects as well.
trailEffect bool/effect true for built-in defaults, but can also point to any
custom effects
trailEffectRate float Defaults to 3
lightCastOnGround bool
lightSize: float
lightColor color lightColor: #ffe92b
largeHitEffect: bool Creates a large explosion and accompanying sound on hit
(only cosmetic)
lightingEffect: bool Draw as lighting works best with instant:true
laserEffect: bool Draw as laser works best with instant:true
beamImage file (image) Image to use for laserEffect
beamImageOffsetRate float
beamImageStart int Frame start of beam animationeffect
beamImageStartRotated bool Defaults false. True to rotate with turret angle
beamImageEnd int Frame end of beam animation effect
beamImageEndRotated bool Defaults false
Section [movement] These are traits the unit has as far as movement
goes, such as rotation and acceleration speed
Code Value Type Description Example
movementType: string Defines what kind of terrain the unit will be able to
move, along with other properties of unit types. movementType: LAND
slowDeathFall: bool Used with large aircraft. Makes the unit fall slowly while
maintaining its speed at the time of death. slowDeathFall: true
moveSpeed: float Maximum movement speed of the unit. moveSpeed: 1.2
moveAccelerationSpeed: float Defines how fast units accelerate to max speed.
 moveAccelerationSpeed: 0.07
moveDecelerationSpeed: float Don't make this too low or units will have trouble
stopping at waypoints moveDecelerationSpeed: 0.17
reverseSpeedPercentage: float 0.6 default. Over 0.4 will reverse for short
distances (at 40% speed). If set to 1 will drive in reverse same as forwards.
Useful if slow turning reverseSpeedPercentage: 0
landOnGround: bool Should flying unit land when idle. landOnGround: false
targetHeight: float Defaults to 0 but if AIR movementType default is 35
targetHeight: 25
targetHeightDrift: float Smooth animated height change. Defaults to 0 but if
AIR movementType default is 1.5 targetHeightDrift: 1
startingHeightOffset: float
heightChangeRate: float Rate at which the unit changes height, either from
converting or drifting heightChangeRate: 3
fallingAcceleration: float The acceleration in which a unit drops
fallingAccelerationDead: float fallingAcceleration but when destroyed
maxTurnSpeed: float
turnAcceleration: float
moveSlidingMode: bool Makes the unit slide when moveDecelerationSpeed is lower,
making them drift and feel natural
moveIgnoringBody: bool Allows the unit to move without fully turning in the
direction its moving, useful for ships and air units
moveSlidingDir: int
joinsGroupFormations: bool Defaults to true. Changing not recommended
Section [ai] This determines what the AI will use the unit for, does not
effect player
Code Value Type Description Example
useAsBuilder: bool Set to true if unit can build or repair buildings. Defaults
to [core]isBuilder.
useAsTransport bool Defaults to true if unit can transport units
useAsHarvester bool Defaults to true if unit can reclaim resources
disableUse: bool Disallow AI building this unit or building
ai_upgradePriority float Defaults to 0.06. Set between 0-1, higher means AI is
more likely to upgrade this unit before others
#==== #==== Buildings only
buildPriority: float 0-1. AI uses 0.8 for first land factory, 0.48 for air
factory, 0.47 for first turret.
noneInBaseExtraPriority: float Adds to buildPriority, if this unit doesn't
exist in the AIs base
noneGlobalExtraPriority: float Adds to buildPriority, if this unit doesn't
exist in the any where on the map
recommendedInEachBaseNum float Defaults to 0
recommendedInEachBasePriorityIfUnmet float Defaults to 0.5. Overrides
buildPriority
upgradedFrom: string Create link to another unit to preserve max counts
for upgraded and non-upgraded types in same base.
maxGlobal: int
maxEachBase: int
notPassivelyTargetedByOtherUnits bool Useful for walls, etc
lowPriorityTargetForOtherUnits Useful for units that cannot attack back.
Eg walls
whenUsingAsHarvester_recommendedInEachBase
whenUsingAsHarvester_recommendedGlobal
whenUsingAsHarvester_includeOtherHarvesterCounts
onlyUseAsHarvester_ifBaseHasUnitTagged
Section [leg_#] / [arm_#] Legs can move around when unit moves, Arms need
an animation or convert
Code Value Type Description Example
x: float Sets position of the foot on the X axis.
y: float Sets position of the foot on the Y axis.
copyFrom: int Copy from another leg. Useful to only need to set leg values once
copyFrom: 1
attach_x: float Sets the leg's attach point on the X axis.
attach_y: float Sets the leg's attach point on the Y axis.
rotateSpeed: float
endDirOffset Target foot/end rotation relative to body
lockMovement bool Lock to unit body. Useful if walking unit converted to a
flying unit.
heightSpeed: float
moveSpeed
moveWarmUp
holdDisMin: float Defaults to 7. Reposition leg at this distance if neighbor legs
are not already repositioning.
holdDisMax: float Defaults to 16. Force reposition of leg at this distance.
holdDisMin_maxMovingLegs
hold_moveOnlyIfFurthest
holdDisMin_checkNeighbours
hardLimit: float Defaults to 50. Force leg to never go this far. Better to not be
reached.
estimatingPositionMultiplier float defaults to 1. Predicts were unit will be for
leg placement based on unit speed.
#==== #==== Graphics and effects
hidden: logic boolean
image_end file (image)
image_end_shadow file (image)
image_end_teamColors
image_foot file (image) same as image_end
image_foot_shadow file (image)
image_middle file (image)
image_leg file (image) same as image_middle
draw_foot_on_top bool
drawOverBody bool Draw over body
drawUnderAllUnits bool Draw over all units
drawDirOffset float
dust_effect: bool Spawns dust particles on each step.
spinRate float Makes arm/leg spin, like idleSpin for turrets
favourOppositeSideNeighbours calculate neighbours with X 10 times closer
than Y
drawLegWhenZoomedOut For performance, defaults changes based on unit size
drawFootWhenZoomedOut For performance, defaults changes based on unit size
resetAngle: float Unused
Section [attachment_NAME] Attachments are slots where other units can be
positioned or carried
Code Value Type Description Example
x float
y float
height bool
idleDir int
idleDirReversing int
isVisible bool
onCreateSpawnUnitOf unit ref
isUnselectable bool Defaults to false
canAttack bool Defaults to true. Set to false to stop this attachment attacking.
canBeAttackedAndDamaged bool
deattachIfWantingToMove bool If the unit is ordered to move, it will detach. This
includes waypoints from actions.
lockLegMovement bool
keepAliveWhenParentDies bool Defaults to false
setDrawLayerOnTop bool
setDrawLayerOnBottom bool
addTransportedUnits bool
lockRotation bool
rotateWithParent bool
resetRotationWhenNotAttacking bool Similar to shouldResetTurret:for turrets.
prioritizeParentsMainTarget bool It will priotize targeting the main target.
Defaults to true.
alwaysAllowedToAttackParentsMainTarget bool Will always attack the parents main
target.
onParentTeamChangeKeepCurrentTeam bool Defaults false. If true attached units
are not converted when parent changes team. Eg from
[projectile]convertHitToSourceTeam
smoothlyBlendPositionWhenExistingUnitAdded bool
keepWaypointsNeedingMovement bool Defaults to false. When false any queued
waypoints needing movement to complete get removed.
showAllActionsFrom LogicBoolean Show all actions of the units attached in
the parent unit list when selected
createIncompleteIfParentIs: bool If parent hasn't been built, create attachment
with the same built value. Links built values till attachment is complete. Useful
for buildings built with nano.
redirectDamageToParent: bool Redirects damage done to this attachment to the
parent instead of damaging itself directly
redirectDamageToParent_shieldOnly: bool
Section [action_NAME] / [hiddenAction_NAME] Actions that can dynamically
cause changes to units and resources
Code Value Type Description Example
text string
textPostFix: string Text shown as suffix, useful with textAddUnitName to
create text UI "text: [ textPostFix: ] textAddUnitName: unitRef
self.attachment(slot=""${slotId}"")"
text_{LANG} string
description string A display text when you select your unit's action, used to
explain it's purpose.
description_{LANG} string
displayType list none, rally, upgrade, queueUnit, building, action, infoOnly,
infoOnlyNoBox, infoOnlyStockpile
displayRemainingStockpile bool Queue is shown as number of times action can be
triggered based on price
pos float Order action appears in UI
iconImage file (image)
iconExtraImage file (image) Drawn over top of icon image. Useful for
upgrade icons, etc
iconExtraColor colour Defaults to #64FFFFFF
iconExtraIsVisible LogicBoolean
unitShownInUI unitRef/unitType Display this unit. (as if this action built
this unit) eg: unitShownInUI: unitRef self.transporting(slot=0) or
unitShownInUI: heavyTank
guiBuildUnit
setBuilt float Designates how built the unit is from a percentage of 0-100% with
a number between 0 and 1.
#==== #==== Unit Reference - Dynamically parts from already existing units, useful
w/ isAlsoViewableByEnemies self, self.parent(), self.transporting(slot=x),
self.attachment(slot=X)
textAddUnitName unitRef/unitType Add this unit's name to this action's text
" eg: textAddUnitName: unitRef self.attachment(slot=""1"")"
descriptionAddFromUnit unitRef/unitType Add this unit's description to this
action's description
descriptionAddUnitStats: unitRef/unitType Add this unit's stats (eg HP,
energy, resources) to this action's description descriptionAddUnitStats: unitRef
self.parent()
unitShownInUIWithHpBar bool default true, Only used when unitShownInUI is a
unitRef
unitShownInUIWithProgressBar bool default true, Only used when unitShownInUI is a
unitRef. Replaces HP bar if active
#==== #==== Requirements for player/AI to use in UI
alwaysSinglePress bool Defaults false. When true no confirmation needed on mobile,
when used with canPlayerCancel:false and allowMultipleInQueue:false will also hide
the queue interface.
price resources The price of your action for the unit. Disables action if not
available. Defaults to credits if unlabelled price: credits=5, energy=5, hp=100,
shield=5, ammo=1
isActive LogicBoolean Defaults true. If false then action is disabled and
shown in red in UI.
isVisible LogicBoolean Defaults true. If false action is hidden from UI and
disabled.
isLocked LogicBoolean Defaults false. If true action is disabled, and a
lock icon is shown. Mostly used for no nuke game modes
isLockedMessage LocaleString
isLockedAlt LogicBoolean Another reason for this to be locked. Can just use OR
on isLocked, but this allows a different message to be shown
isLockedAltMessage LocaleString
isLockedAlt2 LogicBoolean
isLockedAlt2Message LocaleString
allowMultipleInQueue This makes it so only one action can be queued of
this type (useful for keeping actions with conditions from being spammed)
onlyOneUnitAtATime bool When action is picked in UI, only one unit selected
with get this action. Defaults to false.
isGuiBlinking LogicBoolean Flashes in UI to draw attention to it. Might be
annoying if used often, recommended only for temporarily states/messages
isAlsoViewableByAllies bool Allows ally players to see actions from this unit,
useful for showing stats to other players (eg missile count, items collected)
isAlsoViewableByEnemies bool Allows enemy players to see actions from this unit,
useful for showing stats to other players (eg missile count, items collected)
#==== #==== AI - How the AI uses this action
ai_isHighPriority LogicBoolean Use this for faction selection actions or other
high priority actions such as building high priority units
ai_isDisabled LogicBoolean Defaults false. Stop AI using this action.
ai_considerSameAsBuilding Be careful with

#==== #==== Triggers - These skip the queue and do not use price, ignores isLocked,
buildTime, etc (Use 2 actions and alsoQueueAction to automatically add an action
to the queue)
autoTriggerOnEvent "Parameters: created, completeAndActive, destroyed,
killedAnyUnit, queuedUnitFinished, queueItemAdded, queueItemCancelled, teleported,
touchTargetSuccess, newWaypointGivenByPlayer, teamChanged, transportingNewUnit,
transportUnloadedOrRemovedUnit, tookDamage(withTag=""#""),
newMessage(withTag=""#""), enteredTransport, leftTransport"withTag parameter for
tookDamage uses tag from projectile and it is optional. withTag parameter for
newMessage uses message tags.
autoTrigger LogicBoolean When true triggers the effects of this action
instantly (ignoring price, isActive, isVisible, buildSpeed, etc) autoTrigger: if
self.overWater(), autoTrigger: if self.customTimer(laterThanSeconds=5)
autoTriggerCheckRate enum options: everyFrame (default), every4Frames,
every8Frames. This overrides autoTriggerCheckRate set on [core] Note: all triggers
regardless of check rate are checked when first created and after an auto trigger
cooldown. Note: Adding [core]autoTriggerCheckRate:every8Frames to all-
units.template could have a large performance boost for mods with complex
autoTriggers. autoTriggerCheckRate:every8Frames
#==== #==== While action is queued
buildSpeed time buildSpeed: 5s
highPriorityQueue bool Defaults to false. If true this action skips all other low
priority actions in queue. Useful for fireTurret actions.
canPlayerCancel bool
whenBuilding_cannotMove bool Stops unit moving while action is being applied.
Useful for deploy like actions.
whenBuilding_playAnimation animation ref
whenBuilding_rotateTo float Rotate unit body to this direction when action is in
active queue
whenBuilding_rotateTo_orBackwards bool If true allow rotation in 180 degrees
from whenBuilding_rotateTo when this is a smaller angle
whenBuilding_rotateTo_waitTillRotated bool Pause action queue till rotation is
finished
whenBuilding_temporarilyConvertTo unit ref Convert to another unit while
action is in active queue. Note: actions from the original unit will be kept
whenBuilding_temporarilyConvertTo_keepFields Don't change these fields
when using whenBuilding_temporarilyConvertTo (both to and from), useful with
setUnitStats
whenBuilding_triggerAction action ref
whenBuilding_rotateTo_aimAtActionTarget bool BETA NOTE: is broken in some cases
whenBuilding_rotateTo_rotateTurretX turret ref
spawnEffectsOnQueue effect ref Effects to spawn at unit when action is first
added to queue
playSoundToPlayerOnQueue sound ref Global sound to play to unit's player
only when action is first added to queue
#==== #==== Misc outcomes / Results (What happens) (Note: Must be at least one
outcome for an action to show)
requireConditional Skip all effects of this action if this evaluates to
false
convertTo unit ref Convert your unit into another unit. properties are
preserved.
convertTo_keepCurrentTags Keep current and temporarily tags and ignores default
tags on convertTo target.
convertTo_keepCurrentFields maxHp, maxShield, shieldRegen, maxEnergy, armour, mass,
shootDelayMultiplier, moveSpeed, maxAttackRange.)
"
addEnergy float Adds energy to unit. Has no effect unless energyMax is set. (Same
as addResources: energy=X)
addResources resources Add these resources when action finishes.
addResources: credits=5, energy=-5, hp=-100, shield=5, ammo=1
addResourcesScaledByAIHandicaps resources Same as addResources, but increased
or decreased depending on AI difficulty level
addResourcesWithLogic dynamic resources Like addResources but allows logic to be
used for the resource value addResourcesWithLogic: hp =
select( self.parent.energy>5, 10, 20 )
setResourcesWithLogic dynamic resources Sets target resources to this value
instead of adding. Becareful with global resources. setResourcesWithLogic:
hp=self.parent.hp - 10, energy = self.energy / 2
deleteSelf Remove self with no explosions or sounds
resetCustomTimer LogicBoolean Reset timer used with self.customTimer()
setBodyRotation
setUnitStats fields values Allows changing of a select number of fields
dynamically without converting. Supports =/+=/-=, with dynamic maths/logic.
Changeable fields: maxHp, hp, maxShield, shield, shieldRegen, maxEnergy, energy,
armour, mass, shootDelayMultiplier, shootDamageMultiplier, moveSpeed, maxTurnSpeed,
maxAttackRange, fogOfWarSightRange, nanoRange, selfRegenRate
resetUnitStats boolean Reset changes made by setUnitStats to base values
setUnitMemory key value pairs Change this unit's memory, values can be set
with logic. Memory must first be defined with defineUnitMemory "setUnitMemory:
""""""
customText=memory.customText+'hello',
nukeActive=true,
nextTarget=self.attacking.nearestUnit(withinRange=300, withTag='x',
relation='enemy')
"""""""
sendMessageTo: unitref Sends a message to a targeted unit "sendMessageTo:
unitref nearestUnit(withinRange=100, withTag=""fish"")."
sendMessageWithTags: Message Tag Useful for message detection in an
autoTriggerOnEvent event, eg autoTriggerOnEvent:newMessage(withTag=xyz)
sendMessageWithData key-value The data that will be sent to the targeted
unit. Allows multiple key-value pairs with any dynamic data type, use eventData()
to read this data in the event "sendMessageWithData: fish=""nice!"",
cat=self.activeWaypointTarget, amount=4, xyz=memory.something"

refundAllQueuedItems boolean Refunds the spent price in the queue of a

specific action; Includes set flags in price.
removeAllQueuedItemsWithoutRefund boolean Clears the queue without refunding

#==== #==== Outcome - Chaining Actions

alsoTriggerAction action refs Trigger to results of another action as well. Ignores

action's requirements. alsoTriggerAction: addCredits, playSound
alsoQueueAction action refs Adds another action into the normal unit's queue.
Ignores action's requirements
alsoTriggerOrQueueActionConditional LogicBoolean Defaults true.
alsoTriggerAction and alsoQueueAction are ignored if this works out to be false.
#==== #==== Outcome - Sounds
playSoundAtUnit sound ref Local sound to play when action finishes
playSoundGlobally sound ref Global sound to play to all players in game
playSoundToPlayer sound ref Global sound to play to unit's player only
#==== #==== Outcome - Fire projectile from turret
fireTurretXAtGround turret ref When action finishes fire target turret at
point on ground, bypasses canShoot rules in turret. fireTurretXAtGround: nukeSilo
fireTurretXAtGround_withOffset point If not set player targets the ground with
GUI, if a point is set this step is skipped fireTurretXAtGround_withOffset: 0,0
fireTurretXAtGround_withProjectile projectile ref Used with
fireTurretXAtGround. Defaults to target turret's normal projectile.
fireTurretXAtGround_withTarget unitref Fires a turret aimed at the
location of the indicated unit or marker
fireTurretXAtGround_count Number of projectiles to fire. Defaults to 1
fireTurretXAtGround_onlyOverPassableTileOf Only allow tiles crossable by
this movement type to be selected LAND,BUILDING,WATER,HOVER, etc
#==== #==== Outcome - Spawning
spawnUnits Spawn units at action's target. See 'Spawn units line' section in
this doc for details. eg: spawnUnits: heavyTank, tank*5, hoverTank(offsetX=10)
produceUnits Like spawnUnits but unit exits as if it was produced
normally, and gets a move away waypoint
spawnEffects effect ref Effects to spawn at unit
#==== #==== Outcome - Position
offsetSelfAbsolute: point3d Changes unit position absolutely to its current
position offsetSelfAbsolute: 0, 0, 40 [x,y,height]
#==== #==== Outcome - Transport Changes
addUnitsIntoTransport unitTypes Add units into transport, use
self.transportingCount() to check for space before adding addUnitsIntoTransport:
tank*3, heavyTank(neutralTeam=true)
deleteNumUnitsFromTransport int
deleteNumUnitsFromTransport_onlyWithTags string(s)
startUnloadingTransport bool
forceUnloadTransportNow bool For unload all units, or slot targeted by
forceUnloadTransportNow_onlyOnSlot. Unloads even if no space or overwater, etc
forceUnloadTransportNow_onlyOnSlot int
#==== #==== Outcome - Waypoint Changes
clearAllWaypoints bool Clears all waypoints, be careful not to annoy players by
removing their orders, prepending waypoints is often better
clearActiveWaypoint bool
addWaypoint_type move, attackMove, guard, loadInto, loadUp, attack, reclaim,
repair, touchTarget, build, follow, setPassiveTarget
addWaypoint_unitType Only for use with addWaypoint_type:build
addWaypoint_prepend bool Add to the start of the waypoint queue or the end
addWaypoint_triggerActionIfFailed actions If target_nearestUnit fails to find
a match so waypoint cannot be added then trigger this action
addWaypoint_triggerActionIfMatched actions
addWaypoint_maxTime time Automatically remove this waypoint if it has been
active for longer than this time.
addWaypoint_target_nearestUnit_tagged tags
addWaypoint_target_nearestUnit_team relation own|neutral|allyNotOwn|ally|enemy|
any
addWaypoint_target_nearestUnit_maxRange float
addWaypoint_target_mapMustBeReachable bool
addWaypoint_target_fromReference unit ref
addWaypoint_target_fromReference: self.memory.lastDock
addWaypoint_position_offsetFromSelf point
addWaypoint_position_fromAction bool
addWaypoint_position_randomOffsetFromSelf Same as above, but random.
addWaypoint_position_relativeOffsetFromSelf point
addWaypoint_target_randomUnit_tagged
addWaypoint_target_randomUnit_team
addWaypoint_target_randomUnit_maxRange
#==== #==== Outcome - Cooldown
addAllActionCooldownsTime
addActionCooldownTime Player cannot use action again for this amount of
time
addActionCooldownApplyToActions action ids Sets addActionCooldownTime's
target. Defaults to this action.
clearAllActionCooldowns
#==== #==== Outcome - Animation
playAnimation animation id
playAnimationIfNotPlaying bool Don't restart animation if this animation is
already playing
finishPlayingLastAnimation bool Finish last animation, including blend out
stopLastAnimation bool Stop last animation, skipping blend out

switchToNeutralTeam boolean Change team to neutral. This team is allied to

all other teams. Will be captured by nearby units unless [core]stayNeutral:true is
used
switchToAggressiveTeam boolean Change to a built-in team that is aggressive to
all other teams. Does not get captured.
switchToTeam logicNumber Team id to switch to. Starts at 0. (but -1 for a
neutral team, -2 for aggressive Team)
#==== #==== Outcome - Take Resources from other units
takeResources customPrice Resources to take (required to use take resources).
And at-least 1 include key is needed. takeResources: hp=5, gold=10
takeResources_includeUnitsInTransport bool
takeResources_includeParent bool Include attachment parent or transport parent
takeResources_includeReference unit ref
[action]takeResources_includeReference: self.lastDamagedBy
takeResources_includeUnitsWithinRange float
takeResources_includeUnitsWithinRange_team TeamRelation Used with
includeUnitsWithinRange, defaults to own. Can be: own|ally|allyNotOwn|enemy|
neutral|any
takeResources_excludeUnitsWithoutTags tags
takeResources_excludeUnitsWithTheseResources customPrice
takeResources_excludeUnitsWithoutAllResources bool Defaults to true.
takeResources_triggerActionIfAnyCollected action refs
takeResources_triggerActionIfNoneCollected action refs
takeResources_discardCollected bool Just take resources from targets, don't
add(or remove) to self
takeResources_keepResourcesOnTarget bool Don't add/remove resource from target.
This clones resources. Use with takeResources_discardCollected and
takeResources_triggerActionIfAnyCollected to make a resource detector.
takeResources_maxUnits int Defaults to 1.
takeResources_directTransferStoppingAtZero bool If less resources on target
than transfer amount, only remaining resources will be transfered. Doesn't support
use with some other takeResources_* keys
#==== #==== Outcome - Convert Resources
convertResource_from customResource Name of custom resource to take from
convertResource_to customResource Name of custom resource to give to
convertResource_minAmount float Skip if less than this amount in 'from'.
Defaults to 0. Likely not needed for most use cases
convertResource_maxAmount float Max amount to transfer between 'from' and 'to'
convertResource_multiplyAmountBy float Defaults to 1. Amount to multiply when
adding on 'to' (does not effect amount taken on 'from')
#==== #==== Outcome - Set Resources
resourceAmount customResource Name of custom resource to set with the below 3
keys. All keys are optional, and can be used together. resourceAmount: oil
resourceAmount_setValue float Absolute value to set this resource to, ignores
current value of resource. Skipped by default resourceAmount_setValue: 20
resourceAmount_addOtherResource customResource Name of another custom
resource to add to this on. Can be used without resourceAmount_setValue, to just
add resources. Or with resourceAmount_setValue:0 to copy a resource value.
resourceAmount_multiplyBy float Defaults to 1. Multiple the current or new
value by
#==== #==== Outcome - Attachment changes
attachments_addNewUnits unit types
attachments_deleteNumUnits int
attachments_onlyOnSlots attachment ids Restrict attachments_* actions to these
attachments
disconnectFromParent bool
attachments_unload bool Unload all attachments. Can be used with
attachments_onlyOnSlots. Same as unloading transported units
attachments_disconnect bool Disconnect all attachments in the place they are
right now. Can be used with attachments_onlyOnSlots.
#==== #==== Outcome - Tag changes
temporarilyAddTags tags Add tag to this unit until it is converted or reset
(unless convertTo_keepCurrentTags is used)
temporarilyRemoveTags tags Remove tag from this unit until it is converted or
reset (unless convertTo_keepCurrentTags is used)
resetToDefaultTags bool Reset to standard tags
addGlobalTeamTags tags Add a tag to player's team. Use with self.globalTeamTags()
to create unlocks and upgrades. Unique tags are best to not conflict with other
mods.
removeGlobalTeamTags tags Remove a tag from player's team.
#==== #==== Outcome - Show Message
showMessageToPlayer string Sends a message to the player controlling the
unit
showMessageToPlayer_{LANG} string Note: This format is support on nearly
all strings that show to player even when reference doesn't show it
showMessageToAllPlayers string Sends a message to all players Eg:
showMessageToAllPlayers: %{self.playerName} has captured a point
showMessageToAllEnemyPlayers string showMessageToAllEnemyPlayers: Team
%{self.playerName} has %{self.resource.gold}
showQuickWarLogToPlayer string Sends a Quick War Log message to the player
controlling the unit (in the lower lef)
showQuickWarLogToAllPlayers Sends a Quick War Log message to all players
(in the lower lef)
debugMessage Only shows in Sandbox with Debug mode on.
Section [effect_NAME] Effects are purely visual, but can be important
for a mod
Code Value Type Description Example
life float Defaults 200. Time till effect is removed. Set low as possible to
reduce effect overhead. life: 70
lifeRandom float Random offset life by +/- this value lifeRandom: 12
alsoEmitEffects effect ref Create more effects when created, useful for meta-
effects. Note: other 'alsoEmitEffects' on created effects are ignored.
alsoEmitEffectsOnDeath effect ref Create these effects when life runs out.
ifSpawnFailsEmitEffects effect ref If 'spawnChance' for this effects fails then
emit these effects instead
alsoPlaySound sound ref
createWhenOffscreen bool Defaults false.
createWhenZoomedOut bool Defaults true
createWhenOverLiquid bool Defaults true
createWhenOverLand bool Defaults true
spawnChance float Default 1. If less than 1 effect only has a random chance of
being created
showInFog bool Default false
delayedStartTimer float Hide for x time before showing and updating effect.
liveAfterAttachedDies bool Defaults false when attachedToUnit is being used
priority string Defaults to high. verylow/low/high/veryhigh/critical. Takes
effect when too many effects are being shown at once.
#==== #==== Movement
attachedToUnit bool Attach to unit or projectile that created this effect. Will
move with this object.
alwayStartDirAtZero bool Ignore source/attached unit dir
atmospheric bool Apply drag to slow this effect down and add small wind effects
physics bool Fall to ground and bounces. Needs height to take effect.
physicsGravity float Defaults to 1. height speed acceleration when physics: true
xOffsetRelative float Offset starting effect position. Relative to direction of
attached turret, projectile, unit
yOffsetRelative float Offset starting effect position. Relative to direction of
attached turret, projectile, unit
xOffsetRelativeRandom float Random offset by +/- this value
yOffsetRelativeRandom float Random offset by +/- this value
xOffsetAbsolute float Offset starting effect by position ignoring direction of
attached turret, projectile, unit
yOffsetAbsolute float Offset starting effect by position ignoring direction of
attached turret, projectile, unit
xOffsetAbsoluteRandom float Random offset by +/- this value
yOffsetAbsoluteRandom float Random offset by +/- this value
xSpeedRelative float
ySpeedRelative float
xSpeedRelativeRandom float Randomly change by -value to value
ySpeedRelativeRandom float Randomly change by -value to value
xSpeedAbsolute float
ySpeedAbsolute float
xSpeedAbsoluteRandom float Randomly change by -value to value
ySpeedAbsoluteRandom float Randomly change by -value to value
hOffset float height offset from source
hOffsetRandom float Randomly change by -value to value
hSpeed float height speed
hSpeedRandom float Randomly change by -value to value
dirOffset float rotation
dirOffsetRandom float Randomly change by -value to value
dirSpeed float rotation speed
dirSpeedRandom float Randomly change by -value to value
#==== #==== Graphics
frameIndex int frame of to use
frameIndexRandom
stripIndex int/string A built-in image set to use. Cannot be used with custom
image

effects/explode_big/light_50/flame/effects/effects2/projectiles/projectiles2/
explode_bits
Image image Custom image file to use. Cannot be used with stripIndex.
imageShadow image Custom image file to use for shadows
scaleTo float Defaults to 1
scaleFrom float Defaults to 1
color color Defaults #FFFFFFFF
teamColorRatio 0-1
drawUnderUnits bool
fadeInTime float Fade alpha from 0% to 100% for this time at start
fadeOut bool Fade alpha from 100% to 0% based on life. Set alpha is higher
than 1 to delay fade
alpha Capped between 0-1. Can be set higher than 1 to delay fadeOut effects
shadow True to draw a shadow. Forced true if imageShadow is used
#==== #==== Animation
total_frames int Total frames of 'image', used with animation or frameIndex.
Only needed with custom images
animateFrameStart int
animateFrameEnd int
animateFramePingPong int
animateFrameSpeed time
animateFrameSpeedRandom time
animateFrameLooping bool Defaults false. When false effect is removed when
animation ends
Section [animation_NAME] Use this to make intricate animations based on
different circumstances
Code Value Type Description Example
onActions : Unknown move, attack, idle, underConstruction,
underConstructionWithLinkedBuiltTime, queuedUnits
onActionsQueuedUnitPlayAt : float For onAction: queuedUnits. Amount queue
needs to reach before starting, set between 0-1
blendIn : time Blend with last animation for this time
blendOut : time Blend with next animation for this time
pingPong bool Play animation in reverse after it ends
KeyframeTimeScale : float float Scales all keyframe times, useful to make an
animation faster/slower without changing everything
#==== #==== Keyframes - create as many as needed
arm#_[time] Adds a keyframe at time. Use multiple times to create animation.
eg: arm1_5s: {x: 5, dir: 90 }
leg#_[time] Adds a keyframe at time. Use multiple times to create animation.
body_[time] Adds a keyframe at time for body. Only frame and scale allowed on
body eg: body_4s: {frame: 4, scale: 0.5}
effect_[time] "Spawn effects while playing an animation
" eg: effect_2s: {name:CUSTOM|myExplode, x: 0,y: 5}

direction_units float Overrides [graphics]animation_direction_units while this

animation is playing
direction_strideX: int Overrides [graphics]animation_direction_strideX
direction_strideY: int Overrides [graphics]animation_direction_strideY
direction_starting: float Overrides [graphics]animation_direction_starting
#==== #==== Deprecated Keys (can be used but there are better ways)
start : int Start image frame. deprecated
end : int End image frame. deprecated
scale_start : float Start scale. Deprecated, use body keyframes instead.
scale_end : float End scale. Deprecated, use body keyframes instead.
speed : float Speed, smaller is faster. Only effects start, end,
scale_start, scale_end

Type Spawn units line "Spawn lines specifically for units, used with ""unit
ref"" value types"
Code Description Example
#==== #==== Most units spawning keys support multiple units with parameters
spawnUnits: crates*10(neutralTeam=true), tank(spawnChance=0.5)
neutralTeam Spawn the unit on the neutral team instead of the same team as
source
setToTeamOfLastAttacker Spawn the unit on the last attacker of source (useful
on [core]unitsSpawnedOnDeath)
spawnChance Chance this unit will spawn. Defaults to 1.
spawnSource unit ref Changes spawn location and team of spawned units to this
unit ref. "[action]spawnUnits: tank(spawnSource=memory.lastLocation)
"
maxSpawnLimit Useful with spawnChance, max number of units to spawn in
total spawnUnits: treeA(spawnChance=0.5, maxSpawnLimit=1), treeB(maxSpawnLimit=1)
gridAlign Align spawn location to grid, useful for buildings
skipIfOverlapping bool Don't spawn this unit if spawn in an invalid location. Eg
on units or over water when LAND based
offsetX float
offsetY float
offsetRandomX float
offsetRandomY float
offsetRandomDir float
offsetHeight float
offsetDir float
addResources resource ref Give spawn unit those resources, can be used to
set flags that trigger actions spawnUnits: crates(addResource=gold:30|
stone:10, spawnChance=0.5)
transportedUnitsToTransfer int Puts the designated amount of transported units
into the transport of the spawned unit. spawnUnits:
transporter(transportedUnitsToTransfer=5)
copyWaypointsFrom unit ref Copies all waypoints on target to created units.
spawnUnits: tank(copyWaypointsFrom=self)
alwayStartDirAtZero bool
techLevel int Usually used in BR maps, controls the size of safe zones. 1
techLevel = 10x10 tiles = 200 pixels in diameter
Type Spawn Projectiles line "Spawn lines specifically for projectiles, used
with ""proj ref"" value types"
Code Description Example
#==== #==== Most projectile spawning keys used for projectile ref
spawnProjectilesOnEndOfLife: secondary*3(spawnChance=0.5)
spawnChance float Chance this projectile will spawn. Defaults to 1. spawnChance:
0.5
maxSpawnLimit int Maximum amount to spawn
recursionLimit int Prevents loops, useful with spawning itself so it doesn't
infinitely spawn, good for chain exploding recursionLimit: 5 (Recommended no
more than 4 if spawning more than 3 projectiles)
offsetX float
offsetY float
xOffsetRelative float Similar to offsetX, but the offset is relative to the
position of the projectile
yOffsetRelative float Similar to xOffsetRelative, but for Y axis
offsetRandomX float Random value to offset in the X axis only
offsetRandomY float Random value to offset in the Y axis only
offsetRandomXY float The offset in both directions to randomly spawn, makes
truly random spawning within an area
offsetHeight float
offsetDir degrees
offsetRandomDir degrees
Type LogicBoolean Advanced code to create conditionals and triggers
Code Returns Description Example
true bool
false bool
if Start all logic booleans with if, unless just using true/false
and bool if self.isInWater() and self.energy(greaterThan=1)
or bool if (self.energy(greaterThan=1) or self.ammo(greaterThan=1)) and
self.isFlying()
not bool if not self.isOverLiquid()
< bool Return true if number on left is smaller
> bool Return true if number on right is smaller
<= bool Return true if number on left is smaller or equal
>= bool Return true if number on right is smaller or equal
== bool Return true if number, unit, string, bool on both sides is the same
!= bool Return true if number, unit, string, bool on both sides different
+ same type Add two numbers or join two strings
- same type Subtract two numbers
/ same type Divide two numbers
* same type Multiply two numbers
% same type Divides two numbers and returns the remainder
#==== #==== Unit location and movement
self.isUnderwater() bool
self.isAtGroundHeight() bool
self.isFlying() bool
self.isMoving() bool
self.isReversing() bool
self.isAtTopSpeed() bool
self.isInWater() bool Touching water
self.isOverwater() bool Touching or over a water tile
self.isOverLiquid() bool
self.isOverClift() bool
self.isOverPassableTile() bool (parameters: type) Type Values: NONE, LAND,
BUILDING, HOVER, OVER_CLIFF, OVER_CLIFF_WATER, AIR, WATER
self.isOverOpenLand() bool shortcut for self.isOverPassableTile(type='LAND')
#==== #==== Unit stats
self.hasResources() bool Can check multiple resources (all price parameters)
self.resource() float / bool Checks a single resource (parameters: type,
greaterThan, lessThan) (1.15 returns float with no parameters)
self.resource.RESOURCE_TYPE float Shortcut for:
self.resource(type='RESOURCE_TYPE') addResourcesWithLogic: hp += self.resource.gold
self.isResourceLargerThan bool Compare two resource between each other, note
multiplyTargetBy doesn't make any changes. (parameters: source=x, compareTarget=x,
byMoreThan=x, multiplyTargetBy=x)
self.hp() float / bool (parameters: greaterThan, lessThan, empty, full).
(1.15 returns float with no parameters)
self.maxHp() float / bool (parameters: greaterThan, lessThan, empty,
full). (1.15 returns float with no parameters)
self.height() float / bool (parameters: greaterThan, lessThan, empty,
full) (1.15 returns float with no parameters)
self.ammo() int / bool Returns int if no parameters, boolean with any parameters
(parameters: greaterThan, lessThan, empty, full)
self.isAmmoEmpty() bool shortcut for self.ammo(empty=true)
self.ammoIncludingQueued() int / bool Also includes ammo from actions still in
queue (parameters: greaterThan, lessThan, empty, full) if
self.ammoIncludingQueued(lessThan=12)
self.energy() float / bool (parameters: greaterThan, lessThan, empty,
full) (1.15 returns float with no parameters) if self.energy() > 50
self.energyIncludingQueued() float / bool Also includes energy from actions
still in queue (parameters: greaterThan, lessThan, empty, full)
self.isEnergyFull() bool shortcut for self.energy(full=true)
self.isEnergyEmpty() bool shortcut for self.energy(empty=true)
self.shield() float / bool (parameters: greaterThan, lessThan, empty,
full) (1.15 returns float with no parameters)
self.kills() int / bool (parameters: greaterThan, lessThan) (1.15 returns
int with no parameters)
self.queueSize() int / bool (parameters: greaterThan, lessThan) (1.15 returns
float with no parameters)
self.teamId() int Return team id of unit or marker. Starts at 0. (but -1 for
a neutral team)
self.teamName() string Returns allied group team name
self.playerName() string Returns player's name
self.x(), self.y(), self.z() float Returns the unit's coordinate parts
self.dir() float Returns the unit's direction
self.priceCredits() Returns the price of the unit
#==== #==== Misc

self.hasFlag() bool Boolean flag saved into units for mods to use. (parameters:
id=0-31) Use addResources in action change this vaule
self.tags() bool (parameters: includes)
self.globalTeamTags() bool (parameters: includes)
self.transportingCount() int (parameters: greaterThan, lessThan, empty)
(1.15 returns int with no parameters)
self.numberOfAttachedUnits() int / bool (withTag, greaterThan, lessThan) (1.15
returns int with no parameters)
self.isAttacking() bool
self.hasActiveWaypoint() bool ([type=WAYPOINT_TYPE])
self.transportingUnitWithTags() bool (parameters: includes)
self.transportingUnitWithTags(includes='human')
self.hasParent() bool For both attachments and transports (parameters:
[withTag=x] )
self.hasTakenDamage() float / bool (parameters: withinSeconds=X,
laterThanSeconds=X) (v1.15 returns float in seconds with no parameters)
self.hasTakenDamage(withinSeconds=1)
self.timeAlive() float / bool (parameters: withinSeconds=X,
laterThanSeconds=X) (v1.15 returns float in seconds with no parameters)
self.lastConverted() float / bool (parameters: withinSeconds=X,
laterThanSeconds=X) (v1.15 returns float in seconds with no parameters)
self.customTimer() float / bool (parameters: withinSeconds=X,
laterThanSeconds=X) (v1.15 returns float in seconds with no parameters)
self.isOnNeutralTeam() bool
self.numberOfUnitsInTeam() int / bool (parameters: withTag, greaterThan,
lessThan, withinRange, incompleteBuildings, factoryQueue) (v1.15 returns int with
no parameters) numberOfUnitsInTeam(withTag='techUnlockBuilding', greaterThan=0)
self.numberOfUnitsInAllyNotOwnTeam() int / bool (parameters: withTag,
greaterThan, lessThan, withinRange, incompleteBuildings, factoryQueue) (v1.15
returns int with no parameters)
self.numberOfUnitsInEnemyTeam() int / bool (parameters: withTag, greaterThan,
lessThan, withinRange, incompleteBuildings, factoryQueue) (v1.15 returns int with
no parameters)
numberOfUnitsInNeutralTeam() int / bool (parameters: withTag, greaterThan,
lessThan, withinRange, incompleteBuildings, factoryQueue) (v1.15 returns int with
no parameters)
numberOfUnitsInAggressiveTeam() int / bool The special 'aggressive to all'
team (this is not the same as numberOfUnitsInEnemyTeam) (parameters: withTag,
greaterThan, lessThan, withinRange, incompleteBuildings, factoryQueue)
self.hasUnitInTeam() bool (parameters: withTag, withinRange,
incompleteBuildings, factoryQueue) alias for numberOfUnitsInTeam
self.noUnitInTeam() bool (parameters: withTag, withinRange,
incompleteBuildings, factoryQueue) alias for numberOfUnitsInTeam
self.isControlledByAI() bool
self.readUnitMemory() any type (name:string,
type:string{boolean,unit,float,string}, [default]) if
parent.readUnitMemory('boostTarget', type='unit') == self

#==== #==== Unit references

thisActionTarget unit / marker Current target or location targeted.
"fireTurretXAtGround: mainGun (thisActionTarget==Marker with ground location)
alsoTriggerAction: x (thisActionTarget==Same as original action)
[turret]onShoot_triggerActions: x (thisActionTarget==Target that was shot at)
takeResources_triggerActionIfAnyCollected: x (thisActionTarget==Target with
resources)
addWaypoint_triggerActionIfMatched: x (thisActionTarget == Marker for move/Target
for attack, etc. Note: use addWaypoint_maxTime:0 if you want to search only)"
eventSource unit / marker Current trigger from an autoTriggerOnEvent, otherwise
null "autoTriggerOnEvent: tookDamage (eventSource==Unit that caused damage)
autoTriggerOnEvent: killedAnyUnit (eventSource==Unit that was killed)
autoTriggerOnEvent: transportingNewUnit (eventSource==Unit that was transported)
autoTriggerOnEvent: transportUnloadedOrRemovedUnit (eventSource==Unit unloaded)
autoTriggerOnEvent: queuedUnitFinished (eventSource==New unit made)
autoTriggerOnEvent: touchTargetSuccess (eventSource==Target touched) "
attachment unit (parameters: [slot], [withTag])
self.attachment(withTag='x').lastDamagedBy.getAsMarker()
transporting unit (parameters: [slot]) if
self.transporting(slot=0).hasResources(gold=100)
attacking unit Current target this is attacking, might not be the current
waypoint target. if attacking.tags(includes='bug') and attacking.hp < 20
lastDamagedBy unit Last unit that attacked this.
parent unit The transporter or attachment parent. (Note: units are suspended
state when transported without attachment slot) Eg autoTrigger: if parent.energy >
100
activeWaypointTarget unit Current active waypoint target. Includes attacking,
transporting, repairing, etc. if distanceBetween(self, activeWaypointTarget) < 100
customTarget1 unit Custom memory, defaults to the unit that created this unit.
if parent.customTarget1 == self
customTarget2 unit Custom memory, defaults to null
nearestUnit unit (withinRange=500, withTag='x', relation='any') Search for a unit
(not recommended in autoTrigger check for perfomance)
globalSearchForFirstUnit unit (withTag=x, relation) - Returns first (and
oldest) unit found matching the filter. Slow, avoid using in autoTrigger checks
 self.globalSearchForFirstUnit(withTag='gameController', relation='neutral')
nullUnit unit returns a null unit reference, useful for comparisons if
self.parent == nullUnit
#==== #==== Marker functions
getAsMarker marker creates a temporary marker at the position a unit is right
now. Markers are very fast to create and automatically removed when no longer
needed. Is not linked to any unit and still exists when the unit dies, and stays
the same when source moves. lastDamagedBy.getAsMarker()
getOffsetAbsolute marker ([x],[y],[height]) Returns marker with absolute
offset (-y is north, +x is east)
getOffsetRelative marker ([x],[y],[height],[dirOffset]) Returns marker with
relative offset. (y+ is forwards)
self.getOffsetRelative(y=100).nearestUnit(withinRange=70, withTag='mouse') !=
null
eventSource event Returns the event from autoTriggerOnEvent, null if used outside
of a valid autoTriggerOnEvent

#==== #==== Global functions

memory.NAME any type Shortcut to read the self with current defineUnitMemory
types. Cannot be used on other units, use readUnitMemory for that. Don't call with
self. autoTrigger: if memory.experience > 100
distance(x1, y1, x2, y2) float Returns the difference between two points
distanceSquared(x1, y1, x2, y2) float Returns the squared difference between
two points. Bit faster than distance.
distanceBetween(unit1, unit2) float Returns the distance between two units or
markers
distanceBetweenSquared(unit1, unit2) float Returns the squared distance
between two units. Bit faster than distanceBetween
game.nukesEnabled() bool Returns true if nukes are enabled in this game's
settings.
int(x) int Removes decimal places from a number. int(4.2) == 4
select(bool, textA, textB) returns textA if bool is true otherwise returns
textB
debug(logicBoolean) string Returns a text string helping to explain the
reason for the current result. Can see into nested logic, comparisons, and
operators.
str(x) string Convert a number, unit or boolean into a string
str(self.energy)+'x' == '100x'
substring(text,start,end) string Takes a part of the string from the
indicated start and end parts substring('hello',0,2) == 'he'
length(string) int Returns string length as number
squareRoot(num) float Requires square root of a number
min(num1, num2) float Returns the smallest number damage = min(self.hp,
self.energy)
max(num1, num2) float Returns the biggest number max(5, 10) == 10
createMarker(x, y, [height], [teamId], [dir]) marker

eventData(name, type, [default]) any type Displays the data from a specified
message from some unit. Only use in autoTriggerOnEvent:newMessage events
sin(angle) float Takes the sine value of a specified number sin(10) = 0.173
cos(angle) float Takes the cosine value of a specified number cos(60) = 0.5
rnd(min, max) float Produces a random number between minimum and maximum input.
rnd(666, 888)
lowercase(string) string Sets all letters from a string into lowercase
"lowercase(""Spaghetti Macaroni Lasagna"") -> ""spaghetti macaroni lasagna"""
uppercase(string) string Sets all letters from a string into uppercase
"uppercase(""fish dish wish"") -> ""FISH DISH WISH"""
direction(x1, y1, x2, y2) float Returns the relative angle of x1/y1 and x2/y2
directionBetween(unit1, unit2) float Returns the relative angle of unit/marker
A and unit/marker B directionBetween(self, lastDamagedBy)

self.isInMap() bool Returns true if unit (or marker) is with the game area;
Returns false if outside bounds
game.mapWidth() float Returns the width of the map
game.mapHeight() float Retyrns the height of the map
Type [placementRule_NAME] Allows creation of rules for requiring
buildings
Code Value Type Description Example
anyRuleInGroup: string (Only require 1 of the rules in this group pass,
instead of all. Use the same group name on other placement rules to create a
group.)
searchTags: tag list Search for any unit with at least one of these tags
searchTeam: relation Teams to include in search, can be: own|neutral|allyNotOwn|
ally|enemy|any
searchOffsetX: float defaults to 0
searchOffsetY: float defaults to 0
searchDistance: float Required
excludeIncompleteBuildings: bool defaults to false. Might want to set to true
depending on the requirement reason
excludeNonBuildings: bool defaults to false
minCount: int Set min amount of units that need to be found in search. (eg
needs to be near something). Defaults to 0
maxCount: int Set max amount of units before match fails (eg cannot be close to
something). Defaults to unlimited
blocksPlacement: bool Defaults to true.
cannotPlaceMessage: LocaleString Highly Recommended. Message shown to
player if this rule fails (will be first failing rule if using anyRuleInGroup).
checkEachTile: bool defaults to true (set to false to only test unit center,
true checks each tile under the unit which shows up on the placement grid. Can be
easier to see requirements with true)
Type Prices/Resources lines - used by addResources, price, etc
Code Targets Description Example
credits Global resource
energy
hp
shield price: hp=-100, shield=100
ammo Hidden value on each unit for use by mods
setFlag use with addResources, resourceUsage or price. 0-31. Flags are
stored in each unit setFlag=1
unsetFlag use with addResources, resourceUsage or price. 0-31
hasFlag use with price or resourceUsage
hasMissingFlag use with price or resourceUsage
X Any resource defined in [global_resource_x] or [resource_x] sections
gold=5, stone=20
Section [global_resource_NAME]
Code Value Type Description Example
#==== #==== Define a new resource shared with all units in a team, works just like
the built-in credits resource. Add to 'all-units.template' (at mod root) for easy
use in all of your mods
displayName Name of this resource in UI
displayNameShort Resource name on smaller UI elements like action hovertext
(Defaults to displayName)
hidden bool Hide this resource from the player
priority If 2 or mods/units define a resource with the same NAME, the
displayName/displayColor with the highest priority is used
displayColor color Color, can be hex with optional alpha #FF0000
displayRoundedDown bool Don't show decimal places to the player
displayTextPrefix string Adds a string before the resource value
displayTextPostfix string Adds a string after the resource value
displayTextAppendResource resource "Appends another resource after this
resource. It's recommended to give a ""hidden"" key on the appended resource to
hide duplicate."
displayWhenZero bool Displays the resource even when empty. Set as false by
default
displayPos int Sets the position of the globa resource in the screen
iconImage image Shows a custom icon for the specific resource in the HUD and in
text
iconImageUseInText bool Default as true; Shows resource icon in action
description
displayNameHideWhenIconShownInText bool Default as false
displayNameHideWhenIconShownInHUD bool Hides the icon in menus referring to
resource when true. Default as false
displayColorUseInText bool Shows color in action description
appendResourceInHUD resource stacks another resource specified after this
resource on the HUD.
appendResourceInHUD_whenThisZero: bool Defaults as true. When set as false,
allows appended resource to be hidden with the parent resource.
displayPrefixInHUD string Displays text to show before resource value -
replaces resource name and removes the colon separator
displayPostfixInHUD string Similar to the prefix counterpart, but is
displayed after the resource value

displayTextAppendResourceWithGap: bool Adds a space between this and the

appended resource. Defaults as false.

Section [resource_NAME]
Code Value Type Description Example
#==== #==== Define a new resource local to unit. Works like build-in ammo resource
displayName Name of this resource in UI (eg hovering over unit info)
displayNameShort
hidden Hide this resource from the player
equivalentGlobalResourceForAI Used to hint to the AI that a resource node
with a local resources could be used to get a different global resource. Eg when a
harvester unloads the resource
displayRoundedDown
Section [template_NAME]
Code Value Type Description Example
#==== #==== Template sections can have any keys and have no effect by themselves.
#==== #==== Template can get included from other files with [core]copyFrom. Eg:
[core]copyFrom: ROOT:effects/explodeEffects.template (Note that copyFrom can
include multiple files. )
#==== #==== --All these below features can be used with any section not just
templates--
@copyFromSection Use in any section to include keys from a section or
template. (Comma separated for multiple) @copyFromSection:
template_name/action_name/projectile_name
@copyFrom_skipThisSection Use in any section to make [core]copyFrom not
copy into it. Eg not copy an action when overriding @copyFrom_skipThisSection
@define X Define a local variable within a section (best outside of
template) @define targetEffect: boom
@global X Define a global variable used in all sections. Local variables
have a higher priority @global targetEffect: pop
@memory X Define a memory for this unit, its type must be defined as well.
@memory transportCount: float
${X} can be used to reference variables (can also be done outside of a
template). It is calculated when loading and remains static. Has no impact on
runtime performance. spawnEffects: effect_${targetEffect}
 ${section.key} can be used to reference another key (can also be done
outside of a template) addResources: credits=${ core.price * 2 + 10 }
%{X} can be used to add dynamic logic into some strings. (CAN NOT be
used everywhere). The value will update every frame. [action]text: Missing hp %
{self.maxHp - self.hp}
""""""" text """""" can be used for multiline strings. Newlines with be
removed from final result." "copyFrom:""""""
ROOT:a.ini,
ROOT:b.ini,
ROOT:c.ini
""""""
"
Section [comment_NAME]

Code Value Type Description Example

#==== #==== Comment sections can have any keys and have no effect.

List of default game noises (for turret fire sound or other sound references):
bug_attack, bug_die, building_explode, cannon_firing, click, click_add,
click_remove, firing3, firing4, gun_fire, interface_error, large_gun_fire1,
large_gun_fire2, laser_deflect, laser_deflect2, lighting_burst, message,
missile_fire, missile_hit, move, nuke_explode, nuke_launch, plasma_fire,
plasma_fire2, tank_firing, unit_explode, unit_explode_old, warning