weapon_data.csv

weapon_data.csv is a file of .csv format. While possible to edit with a text editor, it is highly advised to use appropriate tools for .csv format to prevent errors. If you plan on editing .csv, please visit Required Tools page and use one of the appropriate tools.

A [.weapon] and a weapon_data.csv entry contain all of the information directly about a weapon. weapon_data.csv is expected in location \Starsector\mods\ExampleMod\data\weapons\weapon_data.csv. The more commonly balance tweaked information is in the weapon_data.csv while the less commonly edited information is in the .weapon file. weapon_data.csv is formatted comma delimited csv format. Projectile information is located separately in a referenced .proj file.

Elements

At the very top of weapon_data.csv, you will see a list of categories. Going from left to right, the function of each are explained in table bellow.

Type Column legend (Not all types used by every csv)

String (ID) - this is unique ID for this separate ship, system, hullmod and so on depending on file. It most important String for most csvs and files. It how game finds things in first place. Changing ID means changing it in all other connected files, usually manually. Do ID right when you first setup entry, and try to keep it same going forward.
String (Any) - freeform text, usually names, descriptions or designations. Usually will not get used anywhere outside UI.
String (Keys) - these text fields accept only predefined values, either ids (of ships, shipsystems and other things) or some special key. Case sensitive. If you want to enter multiple keys in cell they need to be separated by comma (e.g COMBAT, CARRIER) Note that not all key columns can accept multiple values.
Number (int) - accepts whole numbers. Correspond to some int value in API.
Number (float) - accepts decimal numbers. Correspond to some float value in API. For decimals in .csv whole and decimal part separated by dot (e.g. 1.2)
Boolean - TRUE or FALSE, tells what something is true or false, used for major grouping of things which can only be one or another thing in game engine.

Column name	Type	Description
name	String (Any)	The human-readable name of the weapon that is displayed in-game. This isn't the internal name for the weapo
id	String (ID)	This is the internal name that is recognized by the code in the background. When modding, this weapon will be referenced everywhere by this ID. It will be used in .variant files, .wpn files, and campaign scripts. Remember, if you want to reference this weapon somewhere else, it is this designation that you use, not the one above. This must be unique within the mod, vanilla files and also any other mods. For this reason it is highly recommended to add some form of unique prefix such as myuniquemod_weaponid
tier	Number (int)	This partly controls the store availability of the weapon. Normal values range between 0-3 with a special case at 5. Tier 0 weapons are ubiquitous & can be bought on the open market; anything higher requires a progressively higher relationship with the faction for purchase on a military submarket. 3 is the highest tier in vanilla weapons. Tier >=5 weapons cannot appear in markets for purchase at all. Interacts with the rarity value, if any For weapons, higher tier means a lower chance of being available.
rarity	Number (float)	Between 0 and 1 with lower being rarer. For reference the Tachyon Lance is at rarity 0.5. Interacts with the tier. Rarity is just for drops - it doesn't affect fleet composition or weapon/fighter selection at all. com.fs.starfarer.api.impl.campaign.fleets.DefaultFleetInflater.java is a good place to look for the details; if you want specific behavior with regard to rarity etc, writing a custom one is probably the way to go. See also: CampaignPlugin.pickFleetInflater().
base value	Number (float)	How many credits the weapon costs in the campaign.
range	Number (float)	For projectile weapons: - how far a projectile travels before it begins to fade out. For beam weapons: - how far a beam travels, no fade out. For missile weapons: - how far from target an autofire AI can fire weapon (but not necessarily will). does not affect the actual distance the missile will travel, for that see flight time
damage/second	Number (float)	Used only for beam weapons. Determines how much damage is inflicted on the target per second.
damage/shot	Number (float)	Used for non-beam weapons. This determines how much damage is inflicted on a target per shot.
emp	Number (float)	This is the amount of EMP damage the weapon applies to the target per shot.
impact	Number (float)	Affects any combat entity that can be affected by collisions, including asteroids, all ships and missiles. If a target hit by a weapon with sufficiently high impact (around 999999 for some ships), it will be gradually slowed to immobility and rotated in seemingly random direction. Missiles successfully affected by impact will never recover controls and can be considered disabled. Ships can recover as soon as the effect is lifted. Look at the graviton beam for reference. Missiles (and likely other projectiles) also use this as their mass value.
turn rate	Number (float)	The rate at which a turret can turn.
OPs	Number (int)	The ordnance points that the weapon requires for you to install into the weapons slot in your ship.
ammo	Number (int)	The total number of shots that a weapon can fire before a reload or end of combat. Leave null for unlimited ammo.
ammo/sec	Number (float)	The total number of shots that regenerate per second, taking reload size into account. For example say the clip size is 20. If ammo/second is .1, this means it takes 10 seconds for 1 ammo to regenerate. Since the clip size is 20, it would take 20 * 10 = 200 seconds per clip. A more reasonable ammo/second of 1 would mean a 20 second reload time per clip.
reload size	Number (int)	How many shots are added in a single reload event. Used to create clip style reloading. Defaults to 1.
type	String (Keys)	Damage type. Can only be: KINETIC, ENERGY, HIGH_EXPLOSIVE, or FRAGMENTATION (can also be OTHER, but that isn't actually used by any weapon in the game. seems to be the same as ENERGY but with different icon.)
energy/shot	Number (float)	Flux generated per shot.
energy/second	Number (float)	Used for beam weapons. Flux generated per second.
chargeup	Number (float)	The time it takes for a projectile weapon to fire a round. For example, if this were set to 1, then there would be a 1 second delay between clicking the mouse and the weapon being fired. For beam weapons this determines how long it takes for the beam to reach full intensity, where the beam will glow but not fire yet.
chargedown	Number (float)	For non-beam weapons, - this determines how long it takes for the weapon to be ready to fire again--i.e. cooldown. For beam weapons: - this determines how long it takes for the beam to dissipate after the mouse button is released, where the beam is narrowing and doing less damage.
burst size	Number (float)	The number of projectiles that are fired when the weapon opens fire. For beam weapons this is the fire time in seconds.
burst delay	Number (float)	For non-beam weapons, this determines the amount of time between shots fired. Used concurrently with "burst size". For beam weapons with a non-zero value in "burst size", this determines how long it takes for the beam to be ready to fire another burst--i.e. cooldown, after the burst & cooldown periods have completed. min spread
min spread	Number (float)	The minimum angle (in degrees) that projectiles will be constrained to firing within. 0 means that the weapon can be perfectly accurate, but may not be due to other factors such as max spread.
max spread	Number (float)	The maximum angle (in degrees) that projectiles will be constrained to firing within. 0 means that the weapon will fire shots with perfect accuracy. A maximum spread of 30 means that fire will be wildly inaccurate outside of point blank range.
spread/shot	Number (float)	How many degrees of spread, per shot, is added to the minimum spread. When the maximum spread value is reached, there will be no more continued accuracy reduction. Thus, firing a weapon for an extended period of time could make it less accurate. Without a spread/shot value, a weapon will always fire at its minimum spread value.
spread decay/sec	Number (float)	How many degrees of spread are subtracted, per second, from the weapon's current spread. This value is used to control how quickly a weapon will return to true minimum spread after you stop firing.
beam speed	Number (float)	Determines how fast the beam extends from the barrel to max range.
proj speed	Number (float)	For non-beam weapons: - determines how fast projectiles travel. For missile weapons, - determines the missile's desired cruise speed that it will try to reach under it's own power.
launch speed	Number (float)	Deals with missiles. This is the value that governs how fast the missiles are moving before their engines ignite and propel them. Missiles will accelerate to their "proj speed" value defined before this.
flight time	Number (float)	This determines how long a missile's engines will function, in seconds. After this time is up, a missile's engines will cut out, and will no longer be able to accelerate. proj hitpoints
proj hitpoints	Number (float)	This determines the number of hitpoints a missile has.
hints	String (Keys)	These "hints" are small instructions that tell the AI how to use the weapon. These refer to WeaponAPI.AIHints
tags		Additional metadata. Primarily used by the autofit system to locate similar replacement weapons by providing a tiered grouping. The vanilla groupings, where x is replaced with a number, are:
number		Unused. Good place to put notes, as nothing here has to actually be a number.

Hints

These "hints" are small instructions that tell the AI how to use the weapon. These refer to WeaponAPI.AIHints. Possible hints:

Hints	Description
ANTI_FTR	In conjunction with PD_ONLY, allows point defense weapons to target fighters in addition to missiles. On missiles, informs the AI to fire the weapon at fighters as well.
AUTOZOOM	Makes viewpoint automatically snap to target. Strongly not recommended for use.
BOMB	Used on missiles. Force the weapon fire at least once every 3 seconds when target in range.
CONSERVE_1 CONSERVE_2 CONSERVE_3 CONSERVE_4 CONSERVE_5	Informs the AI to be hesitant in firing the last X shots of a limited-ammo weapon. For weapons with a burst size larger than one, it counts full bursts and not individual shots.
CONSERVE_FOR_ANTI_ARMOR	Informs the AI to be hesitant in firing against stripped armor of a target and prefer firing at more armored section of a target like the Breach SRM.
DIRECT_AIM	Informs the missile AI to not weave while approaching target. See Breach SRM.
DO_NOT_AIM	Used primarily for missile weapons, this will make the AI fire the weapon even if the target is not within its firing arc. Note this is more accurately described as "do not aim and fire immediately". Useful for missiles like Pilums that almost always want to fire. Overrides conserve hints.
DO_NOT_CONSERVE	Informs the AI to be liberal in firing a limited-ammo weapon, firing at any opportunity.
EXTRA_RANGE_ON_FIGHTER	Informs the AI to fire the weapon at listed range plus 500 when mounted on fighters.
FIRE_WHEN_INEFFICIENT	Informs AI to fire the weapon even when not flux efficient. Used on weapons with ancillary effects like the Ion Beam.
GUIDED_POOR	Used for missiles. Informs the AI to fire at up to 10 degrees outside of arc. See also DO_NOT_AIM
HEATSEEKER	Used for missiles. Missile targets engines in a manner similar to the Salamander MRM.
MISSILE_SPREAD	Used for missiles. Makes missiles aim randomly off the target's center in a manner similar to the Breach SRM or Squall MLRS.
NO_TURN_RATE_BOOST_WHEN_IDLE	Prevents the weapon from gaining a turn rate bonus when they are not firing (by default, weapons gain a turn rate bonus otherwise).
PD	Allows the weapon to target missiles. Weapon will still target ships but prefer missiles in range.
PD_ALSO	Used concurrently with PD. If used with PD, the weapon will only target missiles if other targets are not available.
PD_ONLY	Allows the weapon to only target missiles, unless paired with ANTI_FTR. See above.
SHOW_IN_CODEX	Makes a SYSTEM weapon appear in the codex.
STRIKE	This means that this weapon will only be used against ships destroyer-size or above. It will also grant any ship carrying this weapon the "strike" ability.
SYSTEM	For things like flares, built-in weapons and decorative weapons. Hides the weapon from the codex and prevents it from being dropped as loot (except by fighters which have the weapon specified in their variant file instead of as a built-in, due to a bug).
USE_VS_FRIGATES	Used concurrently with the STRIKE hint. If a weapon contains the STRIKE hint, this will make it so that weapon can be fired against frigates as well.

Tag	Col 2
kineticX heX energyX pdX beamX	Autofit tags for non missiles weapons, where x is replaced with a number (e. g. `he12`). Autofit will preference higher numbers in the same grouping first.
strikeX missileX rocketX utilityX	Autofit tags for missiles weapons, where x is replaced with a number (e. g. `he12`). Autofit will preference higher numbers in the same grouping first.
SR LR	Autofit tags for short & long range:

Tag	Description
base_bp	Adds weapon to base blueprint package known to all factions, including player at start of game.
lowtech_bp	Adds weapon to Low Tech blueprint package
midline_bp	Adds weapon to Midline blueprint package
hightech_bp	Adds weapon to High Tech blueprint package
rare_bp	Adds weapon as rare blueprint, making it drop as separate singular blueprint
merc	Adds weapon to me

Tag	Description
base_bp	(known to all factions, including player at start of game)
rare_bp	(will appear as a standalone blueprint)
midline_bp
midline_bp

weapon_data.csv

Elements

Hints

Tags