[TUTORIAL] Beginners guide to weapons modding (2024)

What i have figured out so far is the following:

First "Bullets per second" should actually be called "shots per second" since you can multiply the "bullets per shot" with the barrelamount modifier which directly multiplies the MW per shot.

Reload rate equals shots per second
Ammunition reload is seconds of pause after ammo clip is empty

Means:
Time per burst = AmmoClipReload + AmmoClipAmount / ReloadRate

in this example:

<diff><replace sel="//ammunition/@value">16</replace><replace sel="//ammunition/@reload">2</replace><replace sel="//reload/@rate">4</replace></diff>

2s + 16 / 4/s = 6s
It takes 4 seconds to empty the clip followed by a 2 seconds reload time which results in a total burst time of 6 seconds

We also know that per burst we fire 16 shots which results in 16 / 6s = 2.666 shots per second.

Shots per Second = AmmoClipAmount / (AmmoClipReload + AmmoClipAmount / ReloadRate)

If the attribute "barrelamount" equals 1, we also know that per shot one bullet is fired. If it equals 2 it will double the effective bullets per second.

Lets say we have a damage value of 100 then barrelamount will multiply this value. With 2.666 shots per second and barrelamount of 1 we have an output of 266.66 MJ / s.
With 2 barrels 533.33 MJ / s and so on.

Also important is to know that each barrel has its own ammoclip. Means in this example the two barrels have a 16 shot clip each. So effectively 32 bullets with 100 MJ fired every 6 seconds.

In the game this is displayed wrong. If i increase the barrelamount from 1 to 2, the "bullets per second" (aka shots per second) stays the same but it will double the MW weapon output.

Energy per Second = DamageValue * BarrelAmount * Amount * AmmoClipAmount / (AmmoClipReload + AmmoClipAmount / ReloadRate) ~edited

*edit:
Looks like amount and barrelamount have the same effect and multiply each other.

With:

AmmoClipAmount = 16
AmmoClipReload = 4s
ReloadRate = 4 / s
Amount = 4
BarrelAmount = 4
and Damage = 100 MJ

we have the following caluculation for the energy:

100 * 4 * 4 * 16 / (4 + 16 / 4) = 3200 MJ / s

With Amount = 2 it will be 1600 MJ / s

And even amount doesn't affect the "shots per second" like barrelamount. Although one might think that at least with Amount = 4, per shot 4 bullets are fired at once and removed from the clip. But no... It still fires 16 times. Just the energy output increases.

Maybe both attributes are just an easy way to increase damage from M to L weapon scripts without changing damage and shield values directly.

*end edit

With different combinations of ReloadRate and AmmoClipReload you can create some simple burst patterns.

The following example:
4 shots per clip
4 shots per sec -> 1 clip per sec
2 sec clip reload

<diff><replace sel="//ammunition/@value">4</replace><replace sel="//ammunition/@reload">2</replace><replace sel="//reload/@rate">4</replace></diff>

will result in a pattern like: BAM - BAM - BAM - BAM - pauseonesec - pauseonesec - BAM - BAM - BAM - BAM - pauseonesec - pauseonesec ....

And as far as i can tell, the reload time and rate declared directly in the turret file have no effect.

*Edit:

Just to complete this a bit more. There are other modifier to adjust the weapons/bullets behavior.

1. #####
the damage element can have an shield attribute

<diff><replace sel="//damage/@value">100</replace><add sel="//damage" type="@shield">-25</add></diff>

In this example we have a basedamage of 100 which is basicly the hull damage and if no shield attribut is applied also the shield damage.
If we add the shield attribute with -25 the weopon will do 100 hull damage and 100 + -25 = 75 damage to the shields.

The shield attribute is additive. So if we add +25 to shields the weapon will do more shield damage (125) than hull damage which is the case for ion cannons for example.

2. #####
ricochet is an attribute in the bullet element.

It represents a propability value between 0 and 1, a bullet can be reflected randomly and hits maybe something else.

<diff><replace sel="//bullet/@ricochet">0.1</replace></diff>

With ricochet = 0.1, 1 out of 10 bullets will be reflected and hits twice. But i can't say with which energy. Would make sense if its less.

3. #####
For flak turrets there is also the selfdestruct attribute in the bullet element.
Its simply a boolean 0 or 1.

I'm not sure but i think its working together with the areadamage element.
Regarding this element i can't say how the attributs value, time and lifetime are applied to the environment. Its hard to see the effects by numbers.

<diff><replace sel="//bullet/@selfdestruct ">1</replace><add sel="//properties/"><areadamage value="75" time="1" lifetime="5"/></add></diff>

Could be that the areadamage also works for other bullets if they hit something. That i have to find out still.

4. #####
The attribut angle in the element bullet adds some inaccuracy to the weapon.
I've set it to 45 just to see what will happen. And indeed there was a cone with an angle of 45° where the bullets fly randomly.

5. #####
It looks like the timediff attribute in the bullet element adds a bit of randomness to the time between the shots. May be a nice effect for bolters which spit out lead in a more dirty fashion.

*end edit