ODF Commands


About ODF Commands

The commands that can be used in an ODF depend on the classlabel command being used. The classlabels that inherit the base classlabel can have the commands that the Class has and possibly other commands that the specific classlabel has. One file may have only one classlabel.

Any command can be placed only once in an ODF (except when otherwise noted!). If a single-use command is placed multiple times in an ODF, only the first valid command will be read (if the copies have errors they will be ignored).

One row can have only one command and commands cannot have any symbol or space placed before them (the command will not be read). ODF commands are case insensitive.

An equality sign (=) is used to separate the command and value. Empty spaces are ignored when on the same line (except for separating several integers or floats).

All three of the following examples are thus valid:

command = value
command=value
command   =        value

A value of 3 2 1 is not equivalent to 321. If the command cannot handle separated integers or floats, only the first value will be considered valid:

command = 42 1 1 //If this command accepts only one unseperated integer, the value that is read will be "42"

Wrapping

All commands automatically wrap to the next rows provided there is at least one space before the values:

command =
   value     //Note the space before the value in this instance

Arrays

Some commands can take multiple values (such as those that define RGB values, multiple hardpoints, or craft names):

command = value1 value2 value3 ...

Due to the aforementioned wrapping, such values can be entered in multiple rows:

command = value1    //No value needs to be entered here
   value2
   value3
   ...

Pair Arrays

Other commands mix the command type and the command string (such as those that define DamageBase, DamageVariance, or SupplyClasses). This syntax allows the command to define effects to particular GameObjects:

command = default "exception1" value1 "exception2" value2 ...

As a result of wrapping, such values can be entered in multiple paired rows:

command = default
   "exception1" value1
   "exception2" value2
   "exception3" value3
   ...

Negative Values

Integer and float values may be negative, but this is not recommended in all circumstances. Although these values will not cause a crash, they might have unexpected behavior (such as not actually causing a negative value to be generated).

Nonetheless, this can be used to great effect to cause build costs to give resources to the player and other unique conditions that may be described for the appropriate command.

Note that while many commands do have a description for the effects of negative values, not all commands have been explored in this respect.

Types of Commands

The values that an ODF command can have depend on the command itself.

Type   Advanced Notes
Boolean TRUE or FALSE. In the ODFs they appear as a 0 or 1. Values between 0 and <1 behave as 0. Values 1 and greater behave as 1.
Integer Any integer. If multiple integers are specified (command dependent), they must be separated by at least one space. If the integer is included as a float (3.0 for instance), the values after the dot (.) will be ignored.
Float Dot (.) is decimal separator. "Percents" are inputted as fractions. If multiple floats are specified (command dependent), they must be separated by at least one space.

All floats can be input as Scientific Notation. For instance, a value of 1e6 = 1000000.0 and a value of 1e-5 = 0.00001
Strings in quotes after the value are ignored; those before invalidate the command. Unquoted strings before or after the value are ignored.
  RGB Values - Three floats between 0 and 1, with a space between each value. To convert real RGB values to Armada RGB float values, take the desired RGB value and divide by 255 (thus a pure red would be 255/255 = 1.0).  
String One row, a string must be in quotes ("string_here"). If multiple strings are specified they do not need to be separated by a space. File extensions may be required depending on the command. Any values - aside from quotation marks - before or after a string are ignored. Unfilled quotes ("") and unquoted letters are treated as a null entry
  Event - A string that is a relay to the events.dat file.  
  Sprite - A string that is a relay to a sprite reference in sprite files.  

Letters, numbers or punctuation (aside from empty spaces) that are present between the ODF command and its equality sign will invalidate the command.

Note that commas are only used by the few coordinate commands and in all other cases act as other string values. Consequently, simple text added to a blank row (or after a command, even a string) will not cause a crash provided there is nothing valid in that row. This is not recommended however due to the ease of making a mistake (especially due to the wrapping nature of ODF values).

Commenting

Comments can also be added to ODFs at the beginning of a line:

# One row comment. Everything after the # is commented out
// Same as above

Note that if you want a comment to extend for several rows, each new row should have a commenting marker placed.

Important: if a comment is added after a command that is Null in the same line, the comment will be read as if it is part of the command!

Renamed Stock Commands / Variables

Patch 3.1.5 renamed some commands and SODs to match their Armada II counterparts. The following list should help you convert files.

Armada 2 FO 3.0-3.1.4 FO 3.1.5 and later
Latinum Tritan Latinum
latinumCost tritanCost latinumCost
Biomatter Supply Biomatter
biomatterCost supplyCost biomatterCost
xshldx01 shield_hit shield_hit
xshlddie shield_down shield_down
wshldadd shield_add shield_add
wshldsub shield_sub shield_sub
u_ball_obj trigger u_ball_obj
lifeTimer BufferTime lifeTimer
hidden SysTrg hidden
antimine explmine antimine
BorgEnergyEmitter InstantEnergy BorgEnergyEmitter
clairvoyance revealing clairvoyance
particleArt effectSOD particleArt
deathchant modifier deathchant
micro drainer micro
affectedSystem DrainingType affectedSystem
flareSprite lensflare flareSprite
utribeam eventstart utribeam
objectName triggerODF objectName
NebGeneration TargetSelf NebGeneration
xspark xempty xspark

False ODF Commands

The Armada I / II developers were not very careful in how they compiled their game, and therefore it is not uncommon to find totally foreign ODF commands that will not do a thing (even if they may be labeled as functional in other guides). This is because these commands in fact are not referenced by the .exe and so have no effect on the game.

A list will not be compiled here, as there are literally hundreds of such inaccuracies that can be found within the ODFs. Before assuming the functionality of a command, it is always best to check the definitive lists on the guide.

Universal ODF Command

The include instruction can be used with most files in Fleet Operations: .tt, .odf (except for AllCommands.odf and Stars configuration .odfs), .h (except for dynamic_localized_strings.h), .cfg, .aip, .frm, and .spr.

This command allows a child file to include the commands of a valid parent file by pointing to another file of the same type (i.e. ODFs point to ODFs, configuration .h files point to .h files).

Any duplicate commands included in this manner are overwritten by the child file, and any non duplicate commands are inherited by the child file.

Only commands that are valid for the child file will be inherited (included) by the child file (the instruction cannot be used to circumvent command validity).

The include instruction cannot be used to point the file to itself, otherwise Armada II will freeze. Note the special functionality in Modification Modules.

#include "file_name.file_extension" //Note that the file extension is required or Armada will crash

In Fleet Operations the include instruction is not used very often as Armada loads a bit faster if you have one fully assembled file, rather than having a lot of files that all have inheritances.

Fleetcap Configuration Files (removed in FO4.0)

Command (and example)
Description
 
fleetCapClassX = ""
example: fleetcapclassX = "kli_bortasr2"
This indicates that when a ship with this ODF name attempts to use this fleetcap, it should count.
fleetCapClassXcapValue = X
example: fleetcapclassXcapvalue = 4
If present, this indicates that the ship listed takes more than one slot out of the cap. If negative, it increases the cap by the amount indicated by the negative value.
maxCap = 3
This is the maximum number of ships you can have of this cap.
simpleCapMode = 1
This means that any ship that says it uses this cap can only be built the specified number of times.
capTooltip = "( %d / %d )" 
example: capTooltip = "Collective Features ( %d / %d )"
 
This is the text attached to the appropriate ships' tooltips to indicate the max cap and the currently used cap. the first "%d" in the string is replaced with the used amount of cap and the second "%d" is replaced with the maximum cap.
capTooltipReached = "Already Researched"
This is the tooltip used when you hover over a buildbutton of a ship whose cap is full.
capTooltipOver Tooltip used when the cap is exceeded.
affectsAI If 0, the fleetcap does not restrict the AI
countconstructions = 1 If the unit is in the build queue then it would be counted toward the fleet cap if set to 0 then it's not

Upcoming FO4.0 Commands

added:
techtree xml

 

GameObject commands

curSpecialEnergy

Integer, Default: maxSpecialEnergy

Determines how much special weapons energy the GameObject spawns with. This value can be negative or above maxSpecialEnergy.

renderIgnoreCameraDistance

Boolean, Default: FALSE

When set to true (1), the GameObject is always rendered regardless of the distance from the camera. Note however it will always render behind other objects, regardless if other GameObjects are physically behind the GameObject.

hullTooltip

String, Default: Null???

Overwrites the unitName ODF command for the unit display window (the single-select background image) when defined. The Dynamic_Localized_Strings.h file can be used to save space and store longer, more complex tooltips.

Note that tooltip text entered into the ODF directly will appear in a single row on-screen regardless if the text is entered in multiple rows.

 

Producer commands

queueInstantDeduct

Boolean, Default: FALSE.

When set to true (1), Producers deduct resources as soon as they are given a build order (such as immediately upon placing the 'ghost' GameObject). For Producers that can queue up build items, each item will deduct resources as it is queued.

Note that when set to true, if the Producer is destroyed before the buildItem(s) is completed all resources will be returned. This differs from standard Armada II behavior.

 

Craft commands

defaultAlertStatus

Integer, Default: -1 no override, inherit from Producer

Overrides default Craft autonomies set by RTS_cfg.h or the Producer.
ALERT_STATUS_RED = 0
ALERT_STATUS_YELLOW = 1
ALERT_STATUS_GREEN = 2
ALERT_STATUS_NONE = 3 // Treated like Red Alert, but no Alert Status is depressed on the command pallet

defaultSpecialWeaponAutonomy

Integer, Default: -1 no override, inherit from Producer

Overrides default Craft autonomies set by RTS_cfg.h or the Producer.
SPECIAL_WEAPON_AUTONOMY_NONE = 0
SPECIAL_WEAPON_AUTONOMY_MED = 1
SPECIAL_WEAPON_AUTONOMY_HIGH = 2

defaultMovementAutonomy

Integer, Default: -1 no override, inherit from Producer

Overrides default Craft autonomies set by RTS_cfg.h or the Producer.
MOVEMENT_AUTONOMY_LOW = 0
MOVEMENT_AUTONOMY_MED = 1
MOVEMENT_AUTONOMY_HIGH = 2

healthBeamRatio

Float, Default: Null? 100%???

Determines what percent of the hull hitpoints must be remaining before enemy boarding operations may begin (1.0 = 100%). Shields must still be at zero.

logoFileNames

String, Default: Null, Array

Lists the possible unique texture files for the Craft, which will be placed on the Craft's model in-game. Each separate texture name must be in quotes. *any special formating????*

The model needs a mesh group called "stlogo", as this changes the texture for the Craft name.

footprintAligned

Boolean, Default: FALSE

When set to true (1), a station gets "auto aligned" when built through a ConstructionRig. Consequently, when being placed, the station will snap to the grid rather than be placed anywhere (thus allowing the station to always take up a defined number of grid spaces).

explosionChunks

Boolean, Default: TRUE

When set to false (1), the Craft creates no wreckage when it explodes.

beneficialBuildInvert

Boolean, Default: FALSE

When set to true (1), BeneficialBuild commands disallow construction (instead of allowing it). The placement indicator of a craft will turn red. All original restrictions on beneficialBuild commands apply.

 

Faction Configuration commands

usesDilithium

Integer, Default: TRUE

When set to false (0) the faction ignores dilithium costs and the resource does not appear on the tooltips.

usesLatinum

Integer, Default: TRUE

When set to false (0) the faction ignores latinum costs and the resource does not appear on the tooltips.

usesMetal

Integer, Default: TRUE

When set to false (0) the faction ignores metal costs and the resource does not appear on the tooltips.

usesBiomatter

Integer, Default: TRUE

When set to false (0) the faction ignores biomatter costs and the resource does not appear on the tooltips.

usesCrew

Integer, Default: TRUE

When set to false (0) the faction ignores crew costs and the resource does not appear on the tooltips.

trackX

String, Default: singlePlayerMusic / multiPlayerMusic???

Determines what track is played while in-game. Order in which tracks are played is determined by integer values.

track0 = "fed1.ogg"
track1 = "fed2.mp3"
track2 = "fed3.mp3"
track3 = "fed4.ogg"
track4 = "fed5.ogg"
track5 = "fed6.ogg"

Weapon ODF commands

initialShotDelayModifier

Float, Default: -1.0

Sets the initial shot delay modifier after a weapon spawns. This is usually after a GameObject is built or spawned, or the weapon was caste as an extraWeapon.

Pseudo code:
initialShotDelay = shotDelay * initialShotDelayModifier

Negative values mean that the modifier is chosen randomly between 0 and initialShotDelay.

Positive values are to define fixed values.

Zero disables the initial shot delay.

ignoreShotDelayEffects

Boolean, Default: FALSE

When set to true (1), the weapon ignores effects that would normally alter the shotDelay.

These include the PlasmaOverdrive and DeathChant Ordnances. IgnoreShotDelayEffect operates independently of crewAffectsWeaponDelay: unless crewAffectsWeaponDelay = 0, Red and Yellow crew status versus Green will still cause an effect.

 

replaceWeapon ODF commands

ignoreTechtree

Boolean, Default: FALSE

When set to true (1), the ReplaceWeapon ignores the technology tree (and any requirements it might have). Used in Fleet Operations to allow vessels that are part of a capacity list to be replaced by an upgrade into the same capacity list.

Note that this command is not used by the AI: the AI obeys the AIP Buildlist command checkTechnologyAvailable to determine whether technology requirements need to be met.

UniOrdnance ODF commands

extraWeaponTimerReset

Boolean, Default: TRUE

When set to true (1), already existing / deployed extraWeapons get their expire timers reset to extraWeaponTime. This only applies if extraWeaponTime is longer than extraWeaponTime (in case being cast by multiple weapons with different timer delays).

When set to false (0), extraWeaponTime adds additional time to expire timers on already existing/deployed extraWeapons.

 

cloakingDeviceControl ODF commands

initialCloak

Boolean, Default: FALSE

When set to true (1), the cloaking device control is enabled when the vessel is created and as soon as the tech requirements for the cloaking device control are fullfilled.

 

RTS_CFG.h

-SHIELD_EFFECT_RESCALE //use 2x for simulating shield impact effects
-SHIELD_EFFECT_DAMAGE_COLORED
-GAME_OPTIONS_PHYSICS
-PRODUCER_BUILD_INFO_WIREFRAME_SIZE//determines the size of the icon that appears when a Producer is given a build command. 32 for FO, 16 for A2 should be optimal
-TECHTREE_DEFAULT_FILE
GRID_SIZE
CRAFT_DEFAULT_ALERT_STATUS
CRAFT_DEFAULT_MOVEMENT_AUTONOMY
CRAFT_DEFAULT_SPECIALWEAPON_AUTONOMY

Commands Removed in FO4.0

fleetcap files

craft
- requiredAlliedRace
- buildableByOwnerRaceOnly
- fleetCapFile

producer
- buildItemXAvailability
- buildItemXAvailabilityParent

replaceweapon
- ignoreFleetCap
- fleetCapFile

weapon
- showOnlyIfHasTech

Changed Commands in FO4.0

ReplaceWeapon

Note that replaceWeapons will not overwrite the target's race (GameObject ODF command) unless the previous object had no race defined (if an object - like an UtritiumBall - had no race defined and was replaced, the new object would have no race and would cause a crash).

Child vessels do not inherit the fleet group number if the ODF command selectMode=2 (not selected) is defined.

Obeys the technology tree now, including for instant replaceWeapons.

UtritiumBeam

Modified in Fleet Operations

This Ordnance spawns additional GameObjects, which can be used to set up a string of effects. The Ordnance will only fire at the area beneath targets.

In stock Armada II, if targetLocation = 0 for a special weapon (special = 1), then it could not fire at all. Fleet Operations changes this so that a special weapon firing the UtritiumBeam can be set to target discrete GameObjects or locations.

BuildYard

ModuleCfg won't crash when left empty now.

Unknown Stock Armada II Commands

This contains a complete list of all the unknown commands within the guide. If you have any information on these commands, do not hesitate to post on the forums or PM Dominus_Noctis.

Some of these commands may be non-functional, so it is difficult to separate the functional and non-functional ones.

UltritiumBall

radius

damageValue

rotation

scalingStepSize

scalingCount

BackgroundPlanet

rotation

Planet, LatinumNebula, Scrap, AsteroidField

rotationSpeed

TradingStation

percentTradeProfit

Wormhole

disableTimer

transportRadius

animationRadius

Nebula

damageCrewModifier

damageHullModifier

pathing_cost: how does it work - default to RTS_CFG?

MiningStation

checkvalidresourceinterval - something for the AI?

Craft

downBuffer

upBuffer

alwaysUseSpecialWeapons: original notes A1, zentity.odf, psychonic blast - this guy will always try to use special weapons regardless of team timers. could be the timers for the ai that prevents it from spamming some special weapons.

GameObject

avoidanceClass

SELF_DESTRUCT

SPECIES_MINE

directorRadiusScale

weldingAnimSpeed

collisionRadius - original notes A1, zkahless, UNKNOWN ONLY IN FREIGHTER & CONSTRUCTION SHIP FILE

NebulaGenerator

nebulaID

FireballExplosion

shockwaveminimum

ResourceExtractionBeam

extractionInterval

UtritiumBeam

scaleCount

TractorBeam

targetSpeed

Nanites

rollRate

NebulaCreator

fadeFactor

FluxWave

propSpeed

Artillery

explosionSprite

explosionSpriteRadius

ProbeTorpedo

detectCloak

ClairvoyantLink

effectDuration

Weapon

toggle - appears to have no effect

CloakingDevice

unsafeCloakDistance - appears to have no effect; maybe for AI only?

Physics Configuration

For all Physics classes (Borg, Hover, and Smooth)

-combatPhysicsFile

Appears that commands in the physics file it references are not actually used at all

Borg Physics
-tooSlowToTurn

For Smooth Physics
-pitchOmegaFractionAtRest
-pitchAlphaFractionAtRest
-turnOmegaFractionAtRest
-turnAlphaFractionAtRest

All four of the above seem to have no effect as near as I can tell.

-forwardControlDistance
Seems to interplay with tooCloseToTurn (base Physics command), but can't figure out the math behind it (nor the exact effect).

For Hover Physics
-maxReverseSpeed

Several undocumented Physics commands for Hover+Borg
-(a float) frontBackDrag
-(a float) forwardControlScale
-(a float) braccelControlDamping