Here is a fairly comprehensive guide to how weapons work.
Most of this code is in script, in defaultweapons.lua under 'DefaultProjectileWeapon'.
You can mod it till your hearts content, but this will probably answer a lot of questions about what values do what.

WEAPONS

Weapon Mechanics:
A weapon consists of 3 parts
-Turret
-Rack
-Muzzle

-A Weapon holds Racks. A Rack holds Muzzles. Racks are controlled by the rate of fire of a weapon. Muzzles are controlled by the rack and their salvo size and delay.
-A weapon unpacks, charges, fires, reloads and repacks. In that order. Those can be skipped if they are specified as not being part of the weapon.
-Unpacking/Packing happens when a weapon wants to be open during all of the firing the weapon will do in between getting a target and losing a target.
-Charge up happens before the racks fire.
-Reload happens after the racks fire.
-Firing a rack runs through it's muzzles and does the muzzle salvo there.
-Rack salvo size is how many times the racks will fire before going to the reload phase.


Cam shake:
CameraShakeDuration = <time to maintain the camera shake>
CameraShakeMax = <Max size of the camera shake>
CameraShakeMin = <Minimum size of the camera shake>
CameraShakeRadius = <How far from the unit should the camera shake>

Aiming
Aiming is calculated with a combination of rack bones, muzzle bones and can have the option of being turreted in which case yaw, pitch and muzzle need to be defined in order for aiming to be accurate.
Note that one of the most important parts of a weapon is the bone’s axis orientation and alignment with muzzle, racks and turrets. All aiming is done with the assumption that bones are oriented on a right hand orientation where the index finger is the Z axis and the thumb is the Y axis .
We also need to keep close attention to the alignment of all the bones used in the weapon.
A weapon needs for all its aiming bones’ Z axis to be coplanar and pointing along the same + or - direction.

BallisticArc = <Ballistic arcs that should be used on the projectile. RULEUBA_None, RULEUBA_LowArc or RULEUBA_HighArc>
FiringRandomness = <How much random inaccuracy should we be from the target>
FiringTolerance = <How much misalignment can the barrel be before starting to fire. Used when you are trying to target ammo that does not require lots of accuracy due to the size of their damage radius or because the ammo does automatic targetting>
MaxRadius = <How far does the target need to be before we start firing>

FireTargetLayerCapsTable = {
Air = 'Land|Water',
Land = 'Land|Water',
Water = 'Land|Water',
},
FireTargetLayerCapsTable allows you to pick which layers you can target in relation to the layer that you are currently at.
For example, on the previous block, we can target land or water when we are on the air on land or on water.

Damage
CollideFriendly = True/false should the unit collide against friendly meshes
DamageFriendly = True/false should we damage friendly units
Damage = Damage value.
DamageRadius = Radius of the damage
DamageType = String specifying the damage type.
DoTTime = <True/false. Should we distribute damage over time?>
DoTPulses = <The number of times the damage will be dealt.>
DamageType = <The type of damage the unit will do. ‘Normal’ will affect all units. >
DamageRadius = <Blast Radius>

Buffs are going to be changed drastically

Economy
EnergyDrainPerSecond = How much energy this weapon will drain per second
EnergyRequired = How much energy is required to fire this weapon.

Turrets
When a weapon needs to be turreted it means that we are going to use a turret to rotate its rack and muzzle and its aim will be dependant on those bones so the turret needs to define which bones are used for these rotations.

TurretBoneMuzzle = Muzzle bone name
TurretBonePitch = Bone name that will determine the pitch rotation (rotation along the X axis)
TurretBoneYaw = Bone name that will determine the yaw rotation (rotation along the Y axis)
An important note to keep in mind is that if a weapon has both the pitch and yaw as the same bone then we require for the muzzle to be collinear

If they are not the same bones then they only need to be coplanar.

Another important situation that you might encounter is when we get an arm like set of bones like with bots. We need to make sure that all the weapon bones are coplanar and that the Muzzle bone’s z axis is collinear with the point defining the turret pitch
Look at the following image to get a better idea of what is described here.
The bone set up for the units is 100% the responsibility of the artist in charge of the mesh creation of the unit.

Dual muzzle weapons are used with units that have 2 racks working in unison. We find this kind of weapons in bots. UEF light assault bot is a good example of a unit that has this type of weapon.

Blueprint Data:
Turreted = <true/false, Does this have a turret?>
TurretBoneDualPitch = <The second pitch bone for a turret, used for arms on bots as weapons>
TurretBoneDualMuzzle = <The second muzzle bone for a turret, used for arms on bots as weapons>
TurretBoneMuzzle = <The bone used as the muzzle bone for turrets. This is used for aiming as where the projectile would come out.>
TurretBonePitch = <The bone used to pitch the turret.>
TurretBoneYaw = <The bone used as the yaw for the turret>
TurretDualManipulators = <true/false. Do we need two manipulators? Used for bots with arms>
TurretPitch = <The center angle for determining pitch, based off the rest pose of the art>
TurretPitchRange = <The angle +/- off the pitch that is a valid angle to turn to>
TurretPitchSpeed = <The speed at which the turret can pitch>
TurretYaw = <The center angle for determining yaw, based off the rest pose of the art>
TurretYawRange = <The angle +/- off the yaw that is a valid angle to turn to>
TurretYawSpeed = <The speed at which the turret can yaw>

Non-Turreted weapons are mainly set when you have seeking projectiles which do not require the weapon to have a particular direction and the projectile corrects the direction. A good example of such weapon is a torpedo from a sub. In this case the barrel and muzzle would be the same bone and the “Turreted” flag would be set to false. Look at unit URS0203 as an example.

Rack:
Racks hold sets of muzzles with in them. You can have multiple sets of muzzles associated to a rack bone which will allow you manipulate their behavior with common attributes.

Racks can have telescopes which mean their barrels can recoil at the barrel’s telescope bone. In addition it recoils the entire rack by a small distance.

Some weapons like the big guns on Cybran Battleship have multiple sets. This unit fires each muzzle set individually and recoils the entire rack on every fire event. It also does not use a telescope but the result is very similar since we could think of the telescope bone as the rack bone.


Blueprint Data:

RackBone = <Bone Used for Rack Recoil>,
MuzzleBones = {<List of muzzle bones>},
TelescopeBone = <Bone used for telescoping barrel recoil>
TelescopeRecoilDistance = <Distance the telescoping part of the barrel will recoil>
HideMuzzle = <true/false, Indicates that the muzzle bones will be hidden when fired and turned back on before muzzle recharge and during idle. Useful for weapons that show the projectile in the art then fire it off. (Mobile missile launchers)>
RackRecoilDistance = <Distance racks will recoil, Z axis, local coords.>
RackSalvoChargeTime = <Time before the racks start firing>
RackSalvoFiresAfterCharge = <true/false, Does the racks immediately fire when charge is done or wait until next OnFire event?>
RackSlavedToTurret = <true/false, All rack bones are slaved to the turret pitch bone?>
RackFireTogether = <true/false, Do all racks fire simultaneously?>
RateOfFire = <Rack firings per second. You can use decimals for fire rates that are longer than a second>
RackReloadTimeout = <Seconds before the weapon will reload when it didn't go through all its racks>


Muzzle:
The muzzle is the location (bone) of a piece of art that determines where a projectile or a beam comes out of the weapon.
We can have multiple muzzles per rack.

Blueprint Data:
MuzzleSalvoSize = <Number of times the muzzle will fire during a rack firing>
MuzzleSalvoDelay = <Time in between muzzles firing. Setting to 0 = all muzzle fire together>
MuzzleChargeDelay = <The time that the muzzle will wait between playing the FxMuzzleFlash table and the creation of the projectile. Note: This will delay the firing of the projectile. So if you set the rate of fire to fire quickly, this will throttle it.>
MuzzleVelocity = Speed in which the projectile comes out of the muzzle. This speed is used in the ballistics calculations. If you weapon doesn't fire at its max radius, this may be too low.

Salvo:
Salvo is the ammo used by the rack. We need to define how they interact
RackSalvoReloadTime = <Time the racks will reload before starting its next charge/salve cycle>
RackSalvoSize = <Number of times the racks will fire before its reload period>
ProjectileId = <Blueprint of the projectile to fire>,
ProjectileLifetime = <How long the projectile lives>



Targeting
Target Priorities:
TargetPriorities = <Table of category strings that define the targetting order of this weapon>
TargetRestrictDisallow = <The categories that we will not allow to target>
TargetRestrictOnlyAllow = <Exclusive categories that we will allow to target> TargetCheckInterval = <Interval of time between looking for a target>
TrackingRadius = <The radius that the weapon start tracking the target. This does not mean that the weapon will fire. The weapon will only fire when a target enters the maxradius>


Category Strings are string that get converted to unit categories. They work exactly like the strings used for buildable categories. ie: You want TECH1 and MOBILE, the string would be 'TECH1 MOBILE'. If you wanted TECH1 and not MOBILE, it'd be 'TECH1 -MOBILE' and if you want LAND and AIR then you would do ‘LAND, AIR’ where the ‘,’ will be the union token.

Beam weapons
BeamCollisionDelay = <Every X seconds, this beam will collide and do damage>
BeamLifetime = <The amount of time the beam exists.>
WeaponRepackTimeout = <Amount of time after the unit has lost its target that it will pack back up>

Unpacking/Repacking
WeaponUnpackAnimation = <Animation name of the unpack animation>
WeaponUnpackAnimationRate = <How fast the unpack animation runs>
WeaponUnpackLocksMotion = <True/false, Does this unit require it to stop to fire?>
WeaponUnpacks = <Tue/false, Weapon must unpack before ready to fire>
WeaponRepackTimeout = <Time the unit will take to repack the weapon>

Death Weapons
Some units explode and deal damage when they get killed (not destroyed). You can add a death weapon the following way.
Weapon = {
{
Damage = <Damage Amount>,
DamageFriendly = <true/false>,
DamageType = 'Normal',
DamageRadius = <Blast Radius>,
DummyWeapon = <true/false>,
Label = 'DeathWeapon',
},
},


This weapon will fire when the unit dies.
Label has to be 'DeathWeapon' or ‘DeathImpact’ for air units crashing and dealing damage on impact.
Weapon fires at the spot of the unit.
Fires when the unit is killed not destroyed.

What you can't do via only data:
-You can't take a beam weapon and make it a projectile weapon. If you want to do something like that you need to instantiate that type of weapon from the script file and make the necessary adjustments on the blueprint.


Deprecated attributes (Changing these will do nothing to the weapon):
WeaponCategory
MetaImpactAmount
MetaImpactRadius
ProjectilesPerOnFire

Realy nice tutorial!

But some questions are still open.

When looking through the units blueprints there are not all parameters in. So I think not all parameters are necesary which depents on which projectile is used? Do some parameters have standarts when we do not define them? And when it is so, where are the standart definitions?

Another question is how could we find out which bones a unit owns and when they need a definition for pitch and yaw?

Edit: A third question. In the unitname_script.lua files the used weapons are included. How is this affecting the weapons a unit is using?

Very nice.

FatMcK I believe that if a variable isn't shown it is either not needed or considered a default value. (Nil or 0 for things that require number or property values, True/Faule depending on which is considered default)

sweeeeeeeeettttt, just what i was thinking about yesterday while looking over the fatboy.

*bows down to the mind reading devs*

now give us more info on everythingelse till there is nothing else!!!

hehe seriously though thanks again

Kenetor

I forgot two important fields:
HeadingArcCenter = Controls what the weapon is allowed to target in reference to the heading of the unit
HeadingArcRange = Controls what the weapon is allowed to target in reference to the arc center, this is degrees on either side.

For example:
I want a weapon to only target things in the front half of a unit:
HeadingArcCenter = 0, HeadingArcRange = 90

I want a weapon that only targets things on the right side of the unit but have a 45 degree overlap to the left side:
HeadingArcCenter = -90, HeadingArcRange = 135
(Basically, it won't target anything perpendicular to the left side +/- 45 degrees.

Again, the heading arc stuff is based on the unit direction, not the default pose of the weapon.

This is very handy for getting weapons on different sides of the unit to target different things.
The Fatboy uses this extensively.

I still don't quite understand racks, muzzles, and dual manipulators.

What exactly does the 'dualmanipulators' tag do? If the yaw bone is the torso of the bot, the pitch bone is the shoulder joint, and the muzzle is on the lower arm some distance below and forward, what exactly will happen without assigning dual manipulators? (Also, I don't see the 'following image' you mention)

Then, racks. If I want to make a bot that fires bursts with two guns at once, three shots each, do I set Muzzle Salvo to 3, Muzzle salvo delay to 0.1, Rack salvo to 2, rack salvo delay to 0, then reload time? Or what? This system kinda confused me... maybe I need more sleep..

Dual manipulators are when you want one weapon but two aiming mechanisms. Like two aiming arms on one bot that share the same torso.
That's really the only time you want to use it.

Racks hold muzzles. A rack can be anything from a single barrel to a missile tube that has 6 missiles. They are arbitrary.
The main difference is that projectiles come out of muzzles and that's all the muzzles are there for. Racks can recoil and play animations when they fire.
You can change how a weapon works simply by changing the rack/muzzle setup.

Lets say you have a missile weapon with 6 slots.
If you make one rack with 6 muzzles and a salvo of 1, it'll fire all 6 at a time.
If you make two racks with 3 muzzles each, it'll fire 3, then the next 3 next firing cycle.
And so on.
By simply changing what the code thinks is muzzles and racks you can get different firing behaviors.

Can you expand a little on how randomness is calculated? Does it interface with the ballistics calculations directly? It seems as if that must be the case, since the spread for long-ranged weapons is bigger than for shorter-ranged ones with similar randomness.

Unrelated to the actual topic, but shouldn't all Tips be stickied or put somewhere where only admin can make threads?

-1

All of these can be found within the stickies at the top.

Randomness does not affect the ballistics calculation while aiming. It only changes the direction of the shot when the projectile is created.

Sorry, couldn't find any mention of this in the stickies. I can judge the randomness effects through testing, but I don't understand how randomness=x translates into an actual shot spread.

Added.

It's also under 'Weapons'... go figure. :p

Is there such thing as a "MassDrainPerSecond" and a "MassNeededToFire" tag to complement the energy requirement, or do I need to add it in?

I found the command MuzzleVelocityReduceDistance in the Cybran Amphibious Tank blueprint (URL0203) for the Meson Rocket Weapon. Whats that for?

You need to add it.

If the distance to the target is less than the distance specified by MuzzleVelocityReduceDistance, the MuzzleVelocity is scaled back by the difference.

Basically:

MuzzleVelocityReduceDistance was put there so weapons that have a high muzzle velocity because they have a huge range, like an artillery piece, wouldn't point right at something that's close, it'll slow down it's shot and still have a nice arc to it.

Thanks for response. Another five commands that are needed to explain ..

DisplayName - Is this effecting something?
AutoInitiateAttackCommand - Whats that for?
NeedPrep - And this?
Label - And this?
DummyWeapon - Is this only used for death weapons? Any other interesting thing about it?

PS: I copy&pasted most of the original posting into the wiki, hope that is ok!?

FatMck / Label links .bp file's wepon info and .lua's.

.lua code:



.bp code:



If it doesn't match, that weapon will do nothing

Just for debugging. "dbg weapons" on the console shows the weapon names. Also some errors that we detect in script code will print the name of the weapon to help track down the issue.



If the unit has no issued commands and has a weapon that has AutoInitiateAttackCommand set, then if it finds a suitable target it will issue an attack command to go after the target.



If NeedProp is true then whenever the unit aquires a new target and is ready to attack it it will first run the OnGotTarget script on the weapon.



This is used to by the engine to wire the C++ side weapon correctly with the script side.



This instructs the engine not to create a C++ weapon object that is usually linked with the script object. This is for purely script driven weapons (like death weapons).



NP

i need some help with rof, muzzle salvo, charge and reload:

loyalist has RackSalvoChargeTime 0.7, RackSalvoReloadTime 1
Time between firing shoul be 1.7 sec, but here is reload time with charge 2.1 sec, in real is 1.9 sec, how is this calculated?

Other example: transcender has MuzzleSalvoDelay 0.4 and RoF 2, that means it fires 2 projectiles with 0.4 sec pause and then 0.5 sec pause (RoF), but here is 2 projectiles with 0.3 pause and then 0.5 sec pause, in real is it 0.3 pause between projectiles and 0.4 sec pause....

Last example (for me most important): Flayer has RackSalvoChargeTime 0.2 sec, RackSalvoReloadTime 0.5 sec and RoF 3, that's 0.3 sec between projectiles fire and reload with charge (time between all racks firing) is 0.7 sec, here is reload with charge 1 sec and in real is it 0.8 sec...

Can somebody help me?

Can all weapon attributes be changed at runtime? For example a weapon with an adjustable arc or recoil?

Would changing a weapon *instance* in-game affect only the targeted unit or all units with that weapon?

Similarly if the *blueprint* was changed in-game would that affect current units as well as future ones?

Do any values become effectively read-only (ie, crash the game if changed) once the game is initialised or a unit built?

They can be changed at run time. However, some may require a new unit placed down because some values are calculated when the unit is created. Some will change automatically.