Weapon

Weapon is the basic classlabel for weapon ODFs (note however that if you set an ODF's classlabel to Weapon, the ODF will crash the game). The commands available for the Weapon classlabel are inherited by all weapons that are subclasses of a weapon. For instance, CloakingDevice has all the commands that Weapon has, and PhaseCloakDevice has all commands that CloakingDevice has, etc.

Game objects use and carry weapons. Weapons cannot be used except by a game object.

Weapon classlabels are split between those that require specifying an ordnance file to have an effect and those that do not require one. This is noted in the respective classlabel pages, although weapon-ordnance pairing compatibility is not known in many cases. It is untested whether Weapon classlabels that do not require an ordnance file cannot utilize one.

Classlabels

Commands

Stock ODF Commands

ordName

String, Default: Null

Determines the weapon's ordnance file. If ordName references anything other than a valid Ordnance file it will cause a crash. Does not require .odf extension.

ordname = "romW_rhienn1o"

fireSound

String, Default: Null

The sound file played when a weapon is fired. Requires file extension.

firesound = "romulan_pulse_disruptor.wav"

offSound

String, Default: Null

The sound file played when the weapon deactivates after firing. Requires file extension.

fireEventID

Event, Default: Null

The event that is played when the weapon is fired.

wpnName

String, Default: Null

Used for the weapon's in-game tooltip (displayed when special = 1 or when using the Craft weaponXIconPos ODF command). Also used to display the technology requirements string.

wpnname = "Pulse Disruptor Cannon"

buttonBorder

Integer, Default:

In Armada 1 this was the type of border that a weapon button used to appear in-game. Has no effect in Stock Armada II or Fleet Ops.

0 = No border.
1 = Offensive border.
2 = Defensive border.

buttonSlot

Integer, Default: 1

Sets display of special weapon icon and the order of display (smaller buttonSlot special weapon is displayed first). When buttonSlot is set to zero no button is displayed. Negative buttonSlots also display no button, but are valid.

Note that this can be used to create special weapons (special = 1) that can be researched and used by the AI / special weapons autonomy, yet never display a button.

In Fleet Ops, special weapon icons for weapons with different buttons slots are still visible, even if they share the same classlabel. Note that the engine can display a maximum of 31 buttons on-screen at one time (this includes all buttons, including commands).

buttonslot = 176

ButtonSlot sharing:

When multiple weapons (either regular or special) share the same Weapon classlabel (only when the Weapon in question does not require an Ordnance file) or Ordnance classlabel, if they also share the same buttonSlot, the special weapon icon for the one with highest buttonPriority is displayed. ButtonPriority is determined by the order in the Craft's weaponX list: lowest number has highest buttonPriority.

Furthermore, when sharing the same Weapon/Ordnance classlabel, if visibleRange / showRange commands are included and the weapons (either regular or special) share the same buttonSlot, the visibleRange of the weapon with the highest buttonPriority is used for each weapon. Note that this inheritance occurs even if one of the weapons has showRange = 0.

buttonPriority

Integer, Default: ???

In Armada II this can be used to determine which button will appear if two buttons share the same buttonSlot. Only used if buttonSlot is non-zero. Disabled in Fleet Ops.

ButtonPriority in Fleet Ops is determined by the order in the Craft's weaponX list: lowest number has highest buttonPriority.

tooltip

String, Default: Null

The first tooltip displayed (replaces wpnName when hovered). In Fleet Ops this is not used actively (and thus always has the same name as wpnName). 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.

tooltip = "Pulse Disruptor Cannon"

verboseTooltip

String, Default: Null

Longer description of the weapon that pops up when the unit is hovered for longer. Appears below the tooltip. 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.

hotkeyLabel

String, Default: Null

Refers to the unit's hotkey as specified in the input.map file. Cannot have spaces between letters.

hotkeylabel = "GAME-HOTKEY-H"

special

Boolean, Default: FALSE

When set to true (1), the weapon is designated as a special weapon. This allows button and techtree checking. Note that Fleet Operations displays the special weapon buttons of multiple special weapons if they share the same classlabel (in Stock Armada II only one would display).

A single unit may only display 9 special weapon buttons at once.

special = 1

restrictFireArc

Boolean, Default: FALSE

When set to true (1), the firing arc of the weapon can be specified by the fireArc command.

restrictfirearc = 1

fireArc

Float, Default: 0

Determines the firing arc of the weapon as orthogonal to the facing of the hardpoint. This is measured in radians, but rounded to avoid issues at the extremeties. 0 is the same as 2π (or 360 firing arc)

firearc = 1.61 //This is a ~180 degree firing-arc

targetLocation

Boolean, Default: False

When set to true (1), the weapon fires only on an area, not on GameObjects directly. The weapon will try to acquire the target's coordinates, aiming at the location "under" the target.

AItargetLocation

Boolean, Default: FALSE

When set to true (1), the AI will use the weapon to target an area only.

crewAffectsWeaponDelay

Boolean, Default: TRUE

When set to false (0), crew loss of the owner vessel has no affect on the weapon's shotDelay. Overrides weaponYellow and weaponRed ODF command shotDelay multipliers.

targetEnemyCraft

Boolean, Default: TRUE

When set to false (0), the weapon cannot fire on enemy vessels.

targetEnemyBuildings

Boolean, Default: TRUE

When set to false (0), the weapon cannot fire on enemy stations. GameObjects with the Craft ODF command is_starbase = 1 count as stations.

targetEnemyPlanets

Boolean, Default: FALSE

When set to true (1), the special weapon can fire on enemy Planets. Regular weapons are controlled by the Craft canAttackPlanets ODF command.

Note that canAttackPlanets = 1 partially overrides the Weapon targetEnemyPlanets ODF command, such that Craft with targetEnemyPlanets = 0 can still use special weapons automatically on Planets via the AI / Special Weapons Autonomy.

targetEnemyPlanetsOnly

Boolean, Default: FALSE

When set to true (1), the special weapon can only fire on enemy Planets. Regular weapons are controlled by the Craft canOnlyAttackPlanets ODF command.

targetAlliedCraft

Boolean, Default: FALSE

When set to true (1), the weapon can fire on allied vessels.

targetAlliedBuildings

Boolean, Default: FALSE

When set to true (1), the weapon can fire on allied stations. GameObjects with the Craft ODF command is_starbase = 1 count as stations.

shotDelay

Float, Default: 0.0 *see initialShotDelayModifier

Time required for the weapon to reload between shots. Some classlabels are not affected by this command (listed on their respective pages).

shotdelay = 5

range

Float, Default: 0.0 *

Determines the maximum range (in map units) at which point the weapon will fire. * Not all Weapons use range.

Range, when specified, must be greater than zero for self-targeting weapons.

Regular (special = 0) toggle-type weapons will toggle on once reaching the specified range.

Fleet Ops weapon ranges in map units:range = 200 // Fleet Ops standard dogfight range
range = 400 // Fleet Ops standard short range
range = 600 // Fleet Ops standard medium range
range = 800 // Fleet Ops standard long range
range = 1100 // Fleet Ops standard artillery range
range = 1400 // Fleet Ops standard strategic range

Fleet Ops Version 4 weapon ranges in map units:

range = 200 // Fleet Ops standard Dogfight range
range = 400 // Fleet Ops standard Short range
range = 600 // Fleet Ops standard Medium range
range = 800 // Fleet Ops standard Long range
range = 1200 // Fleet Ops standard Artillery range
range = 1600 // Fleet Ops standard Strategic range

hitChance

Float, Default: 1.0, Pair Array

Hit chance for the weapon between 0 and 1. Does not require .odf extension.

Note that some Weapons and Ordnances ignore hitChance. This is documented on the respective pages.

hitchance = 1
    "fed_excelsioriiYr6.odf"    0.65
    "fed_excelsioriiZr6.odf"    0.65
    "fed_excelsiorii_romr6.odf" 0.65
    "fed_mirandaiiMr6.odf"      0.65
    "fed_mirandaiir6.odf"       0.65

Note the following important exceptions:

The weapons of Craft which have no valid physicsFile defined will always hit their targets with 100% accuracy. Note also that combatSpeed must be greater than 0 for the Craft's physicsFile to be considered valid for hitChance.

If a Craft does not have enginesHitpoints and / or a valid physicsFile defined, all weapons will hit it with 100% accuracy. Note also that combatSpeed must be greater than 0 for the Craft's physicsFile to be considered valid for hitChance.

needTarget

Boolean, Default: FALSE

Only used by special weapons (special = 1): regular weapons get their target by the Craft's choosing. When set to true (1), the weapon needs a target (either an area or a specific unit) to be specified after clicking the button, before it can be fired by the Player. The appropriate cursor will then be displayed when hovered over a valid target. Wave-type weapons for instance might not need a target in order to be triggered successfully.

Depending on the classlabel of the ordnance or weapon, when specified, needTarget may not match the actual post-firing target of the weapon (for instance the ChainPulsar may be configured to require the player to click on a target to fire the weapon, but the first Craft that is hit is chosen separately).

Note, when configured as a special weapon (special = 1), some weapon classlabels require needTarget to be true in order not to crash when the AI / Special Weapons Autonomy activates them. See respective Ordnance classlabel pages for more information on which classes are not compatible. The Drones and BioPulse Weapons also require needTarget to be true in order to function as a special weapon.

cloakEnable

Boolean, Default: FALSE

Can only used by special weapons (special = 1). If set to true (1), the special weapon can fire while the owner is cloaked.

Note that switchToAttack should be set to false to prevent the owner Craft from decloaking if the weapon requires a Craft as a target.

warpEnable

Boolean, Default: FALSE

When set to true (1), the weapon can be fired while the owner is at warp velocities.

beneficial

Boolean, Default: FALSE

When set to true (1), indicates that the weapon is not harmful to the allied target and thus prevents the owner from firing upon the allied target with its other weapons (thus no attack order is given).

The hardcoded event label, EnemyEngaged, is not used when beneficial = 1.

toggle

Boolean, Default: ???

???? *appears non functional*

switchToAttack

Boolean, Default: TRUE

When set to true (1), after the unit fires this weapon it will fire upon its target with any weapon (attack order is given) or attempt to do so (by chasing it). Similar to Beneficial.

specialEnergyCost

Float, Default: 0.0

The amount of special weapons energy used when the weapon is triggered.

Note that any Weapon that does not require an Ordnance deducts the energy cost from the Weapon's specialEnergyCost command. Any Weapon that requires an Ordnance deducts the energy cost from the Ordnance's specialEnergyCost command.

regularWeaponDelay

Float, Default: 0.0

Puts the specified delay (in seconds) on firing all other regular (special = 0) weapons after using this weapon. For toggle-type weapons, the delay counter begins after the weapon is toggled on. Toggling off has no effect.

impulseToHitModifier

Float, Default: 0.0

Adds the weapon's hitChance to this value to generate a new hit chance for the weapon when fired when the owner vessel is moving at impulse or warp velocities.

Note that some Weapons and Ordnances ignore these modifiers. This is documented on the respective pages for hitChance.

impulseToHitModifier = -0.25 // If hitChance is 1.00, then the hit chance when the weapon is fired while moving is 0.75, as 1.00 + (-0.25) = 0.75

stopToHitModifier

Float, Default: 0.0

Adds the weapon's hitChance to this value to generate a new hit chance for the weapon when fired when the owner vessel is not moving.

Note that some Weapons and Ordnances ignore these modifiers. This is documented on the respective pages for hitChance.

toHitImpulseModifier

Float, Default: 0.0

Adds the weapon's hitChance to this value to generate a new hit chance when the target is moving at impulse or warp velocities.

Note that some Weapons and Ordnances ignore these modifiers. This is documented on the respective pages for hitChance.

toHitStopModifier

Float, Default: 0.0

Adds hitChance to this value to generate a new hit chance when the target is not moving.

Note that some Weapons and Ordnances ignore these modifiers. This is documented on the respective pages for hitChance.

ignoreValidAsTarget

Boolean, Default: FALSE

When set to true (0), weapons will ignore target invalidation when used by the AI or Special Weapons Autonomy. Target invalidation is caused by beaming or by the Ordnance forceInvalidateTarget ODF command. This causes two effects:

If a GameObject is beaming onto a target, GameObjects controlled by the AI or Special Weapons Autonomy can use weapons with ignoreValidAsTarget = 1 on the target. If false, beaming must stop for the AI to use the weapon.

If a GameObject uses an Ordnance with forceInvalidateTarget = 1 on a target, another GameObject with a weapon that has ignoreValidAsTarget = 1 can use it on the same target. If ignoreValidAsTarget is false, these weapons can only be used by the AI once the Ordnance that invalidates the target, ends.

speakOnAttack

Boolean, Default: TRUE

When set to false (0), no sound is given (indicated in events.dat) when the Craft uses its weapons. Note that clicking a toggleable replaceWeapon counts as using the Craft's weapons (even if a cooldown is in action).

attackSpeech

Boolean, Default: TRUE

When set to false (0), no sound is given (indicated in events.dat) when the Craft is given an attack command.

animateOwner

Boolean, Default: FALSE

When set to true (1), the owner vessel will play its animation when the weapon is fired.

Note that the command does not function with all weapon classes. The command only works with the Cannon (and CannonImp, TargetOnlyNebulae, TransientRiftWeapon), Launcher, MineLayer, TranswarpConduit, and WormholeGenerator classes.

assimilatable

String, Default: Null

When present, the special weapon defined by this GameObject can be assimilated by the TechAssimWeapon or by the TechAssimBeam Ordnance. Weapons are assimilated in order of the owner GameObject's weaponX assignment. No .odf file extension required.

TechAssimWeapon: Only ResearchPods can be specified (if another type of GameObject is specified, no research will occur and the tech-assimilated Craft will decomission). The ResearchPod that researched that special weapon will be attached to the Craft carrying the TechAssimWeapon. Note that the ResearchPod has technology requirements, so if it is unavailable to the player that uses the TechAssimWeapon (either because the special weapon has not been researched, or is restricted to certain factions), the special weapon cannot be assimilated.

TechAssimBeam Ordnance: Any GameObject may be specified. The GameObject that is specified does not affect which special weapon is given to the owner Craft: the TechAssimBeam will choose based on the target's available special weapons.

The definable ODF is limited to 63 characters.

multiReqClassX

String, Default: Null

Indicates the units required for weapons that need multiple units to fire (FusingWeapon or BioPulse). The values X must be entered in order from least to greatest (from 0 to #).

For the BioPulse: If only one Craft entry is specified here (when only multiReqClass0 is used), the multiReqClass0 Craft will fire the BioPulse by itself (no charging occurs).

multireqclass0 =  "bor_assimilatorBTR"
multireqclass1 =  "bor_sphereBBRR"
multireqclass2 =  "bor_assi_matrixZ"
multireqclass3 =  "bor_incubationZ"

multiReqMinX

Integer, Default: 1, see below*

Indicates the minimum number of units of each multireqclassX needed to operate a multi-unit weapon (FusingWeapon or BioPulse). Note that if X is zero, the Craft is not used in the multi-unit weapon ever.

*For the BioPulse: This command and a value must be specified for the class that corresponds to the main firing Craft or the BioPulse weapon will be invalid.

multireqmin0 =  1 // A minimum of 1 bor_assimilatorBTR is needed

multiReqMaxX

Integer, Default: multiReqMinX

Indicates the maximum number of units of each multireqclassX needed to operate a multi-unit weapon (FusingWeapon or BioPulse).

For the BioPulse: Even though the main firing Craft can use this command, only one of these Craft will act as the main firing unit when selected as a group with supporting Craft, while the superfluous main firing Craft will also charge it.

multireqmax0 =  4 // A maximum of 4 bor_assimilatorBTR are needed

Fleet Operations ODF Commands

overrideCeaseFire

Boolean, Default: FALSE

When set to true (1), the weapon can be used during the cease fire.

showInMultiSelect

Boolean, Default: TRUE

When set to false (0), the special weapon button is only shown when a single vessel is selected.

showOnlyIfHasTech

Boolean, Default: FALSE

When set to true (1), the button for the special weapon is hidden (not displayed nor leaving a button gap) instead of being rendered red when its technology requirements are not met.

showRange

Boolean, Default: FALSE

Shows the radius for the weapon when the weapon system icon in the ship's system display or special weapons button is hovered over. See buttonSlot for additional information.

visibleRange

Float, Default: inherits range.

Can be used to override the range which is shown when showRange is set to true. Note that this is purely a visual. See buttonSlot for additional information.

validTargets

Boolean, Default: TRUE, Pair Array

Defines the vessels which the weapon can hit.
IMPORTANT: The vessel will try to attack with that weapon, even if the target is marked invalid in the "validTargets" list. This command is intended for special weapons (like the Negh'var's anti-station torpedo).

Example 1:validTargets = 0   // The weapon cannot hit vessels, except...
  "fed_akira"  1   //..the Akira

Example 2:validTargets = 1   // The weapon can hit all vessels, except...
  "fed_galaxy" 0   //..the Galaxy
  "fed_saber"  0   //..and the Saber

hasNegativeEffectOnOwner

Boolean, Default: FALSE

This command has only cosmetic effects. When set to true (1), the extraWeapon buff icon (in the ship's system background) is displayed in red and when set to false (0) it is shown in green (to indicate the positive effect on the owner).

preserveStatus

Boolean, Default: FALSE

When set to true (1), the weapon's shotDelay (or shotDelayX) is remembered and not reset should the weapon owner (and thus its weapons) be changed or affected.

overrideSubSystem

Boolean, Default: FALSE

When set to true (1), the weapon can be used even if the weapon subsystem is disabled or broken. As of now this command only works with special weapons, but not those which fire on terrain only (example: artillery special weapon).

showEffectIcon

Boolean, Default: TRUE

When set to false (0), the effect icon cast by the weapon is not shown in the target's buff bar (in the ship's system background).

Examples where showEffectIcon is true include the Romulan Spy, Gravity Mine, extraWeapons (UniBeam / UniTorpedo), etc.

showAsEffectIcon

Boolean, Default: FALSE

When set to true (1), the command displays the weapon as an effect in the weapon owner's buff bar (in the ship's system background). If this weapon was cast as an extraWeapon which has showEffectIcon (other command!) disabled, showAsEffectIcon=true may be ineffective.