A .weapon file and a weapon_data.csv entry contain all of the information directly about a weapon. The more commonly balance tweaked information is in the weapon_data.csv while the less commonly edited information is in the .weapon file. It is formatted in Starsector's somewhat loose JSON schema. projectile information is located in a referenced .proj file.



At the very top of weapon_data.csv, you will see a list of categories. Going from left to right, the function of each will be described:


The human-readable name of the weapon that is displayed in-game. This isn't the internal name for the weapon.


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. If you want to switch out a weapon for another in ship variants, this is the one you use. 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


This partly controls the store availability of the weapon. Tier 0 weapons can be bought on the open market; anything higher requires a progressively higher relationship with the faction for purchase on a military submarket. Tier >=5 weapons cannot be purchased at all.


base valueEdit

How many credits the weapon costs in the campaign.


How far a beam travels or how far a projectile travels before it begins to fade out.


Used only for beam weapons. Determines how much damage is inflicted on the target per second.


Used for non-beam weapons. This determines how much damage is inflicted on a target per shot.


This is the amount of EMP damage the weapon applies to the target per shot.


Only affects fighters and asteroids. If one of the two is hit by a weapon with a high impact, they will spin out of control. Look at the graviton beam for reference.

turn rateEdit

The rate at which a turret can turn.


The ordnance points that the weapon requires for you to install into the weapons slot in your ship.


The total number of shots that a weapon can fire before a reload or end of combat. Leave null for unlimited ammo.


The total number of shots that regenerate per second.

reload sizeEdit

How many shots are added in a single reload event. Used to create clip style reloading.




Flux generated per shot.


Used for beam weapons. Flux generated per second.


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.


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.

burst sizeEdit

The number of projectiles that are fired when the weapon opens fire. For beam weapons, a value here makes the beam fire in bursts. For example, if this were set to 1 for a beam weapon, then the beam would fire for 1 second after pressing the mouse button, and then fade away.

burst delayEdit

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.

min spreadEdit

The minimum angle (in degrees) that projectiles will be constrained to firing within. 0 means that the weapon fire can be perfectly accurate, but may not be due to other factors such as max spread.

max spreadEdit

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.


How many degrees of spread, per shot, is added to the onto 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/secEdit

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 speedEdit

Determines how fast the beam extends from the barrel to max range.

proj speedEdit

For non-beam weapons, this determines how projectiles/missiles will move.

launch speedEdit

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 timeEdit

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 hitpointsEdit

This determines the number of hitpoints a missile has.


These "hints" are small instructions that tell the AI how to use the weapon. These refer to WeaponAPI.AIHints. Possible hints:
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.
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.
Informs the AI to be hesitant in firing the last shot of a limited-ammo weapon. For weapons with a burst size larger than one, it counts full bursts and not individual shots.
Informs the AI to be hesitant in firing the last two shots/bursts. See CONSERVE_1.
Informs the AI to be hesitant in firing the last three shots/bursts. See CONSERVE_1.
Informs the AI to be hesitant in firing the last four shots/bursts. See CONSERVE_1.
Informs the AI to be hesitant in firing the last five shots/bursts. See CONSERVE_1.
Used primarily for missile weapons, this will make the AI fire the weapon even if the target is not within its firing arc.
Informs the AI to be liberal in firing a limited-ammo weapon, firing at any opportunity.
Informs the AI to fire the weapon at listed range plus 500 when mounted on fighters.
Informs AI to fire the weapon even when not flux efficient. Used on weapons with ancillary effects like the Ion Beam.
Used for missiles. Informs the AI to fire at up to 10 degrees outside of arc. See also DO_NOT_AIM
Used for missiles. Missile targets engines in a manner similar to the Salamander MRM.
  • PD
Allows the weapon to target missiles. Weapon will still target ships but prefer missiles in range.
Used concurrently with PD. If used with PD, the weapon will only target missiles if other targets are not available.
Allows the weapon to only target missiles, unless paired with ANTI_FTR. See above.
Makes a SYSTEM weapon appear in the codex.
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.
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).
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.


These are used by the autofit to locate similar weapons.


Unused. Good place to put notes, as nothing here has to actually be a number.

Return to: Modding