The Universal World Owner's Manual

Your server's Data\Weapons.txt sets up the behaviours for each weapon type on your world. The following parameters are supported ; some are only applicable to particular configurations.

These fields are required on each weapon for it to function:

Weapon Control Modes Reference

This affects how the player fires the weapon. You can use it to make weapons that need a quick keypress to fire, or weapons that increase their fire 'strength' the longer the key is held down. All of these modes generate a 'Fire Parameter' value from 0.0 to 1.0 that is passed to the 'FIRE=' function described below. By combining different 'Control=' and 'Fire=' functions you can make weapons where holding the key down controls the fire angle, or range, or type, etc.

Weapon Fire Modes Reference

This field controls how the weapon object is launched once it is fired. It is used to define things like the initial trajectory and speed of the weapon object, and defines how the Fire parameter (described above) is interpreted. In a similar way, each Fire function generates a further parameter that is applied to the Object you specify below.

These fields are not always essential for a functional weapon but you'll usually want to set each.

Weapon Object Types Reference

This field defines the physical properties of the weapon being fired - some bounce, some have gravity applied, some don't, etc. The behaviour of some of these objects is affected by the parameter passed in from the Fire function (see above). In most cases, this comes from the script Param field.

This is the overall speed of the weapon when it is fired - it can be modified by your Fire settings. If the Fire parameter affects the speed, then this value is the maximum speed of the weapon- i.e when the Fire Parameter is 1. : Speed is probably in m/s but i need to check that..

This is the number of milliseconds that must pass before the weapon can be fired again. (i.e. 1000 = player can fire once every second). This value must be above 100 (Lower values are ignored). If omitted, this defaults to 1000. E.g. For a weapon that can be fired twice per second, use Delay=500

This is the damage rating for the weapon - i.e. how much harm it will do to a player or building when it hits em. The value is on a scale such that 6500 would kill a player (with normal armour - 50) in one shot. If omitted, the default damage of 500 is set. E.g. Damage=4000

There are a large number of other fields that can be used for special weapon types or are only used by particular CONTROL or FIRE modes.

The pitch in degrees that the weapon fires at. For instance, Pitch=30 means the weapon fires at an upwards angle of 30 degrees. Pitch=90 would fire straight up; pitch=180 would fire the weapon backwards.) If omitted, 0 is default.

This is the expiry time of the weapon (where appropriate - some Objects do not have an expiry time applied). It is set in 1/100ths of a second, so 500 means the weapon expires after 5 seconds If omitted, this defaults to 1000 (i.e. 10 seconds). E.g. For an object that lasts for 20 seconds, use Expiry=2000

This is a global parameter value that can take on different meanings depending on the Fire and Control type chosen. It is often ignored, but it's essential for MGs and a few other weapon types, for example. E.g. Param=400

This is the damage rating for the weapon when it hits a building. If omitted, the main Damage setting is used instead. E.g. builddamage=20

This is the proximity range for the weapons u fire - i.e. how far away from a player they need to be to be considered a hit. Because of the nature of lag on the internet, adding a proximity range on the collision detection of weapons helps to ensure that lag does not overtly affect the fairness of the game. A typical value for this field is 10. Smaller values mean smaller prox range. Default is 20. E.g. Prox=40 doubles the default proximity range.

This field is only required when using the 'Fire=VariableExpiry' method. In this case, adding this field sets a minimum expiry time (in 1/100ths of a second) for the weapon. So if MinExpiry=200 , and the 'Fire Parameter' for the weapon is 0.0 (for instance, if using 'Control=Javelin' and the player didnt hold the key down for any length of time), the weapon will still have an expiry time of 2 seconds.

This field is only required when using the 'Fire=VariableForce' and 'Fire=VariableForceAim'methods. In this case, adding this field sets a minimum speed for the weapon, applied irrespective of the 'Fire Parameter'.

This controls whether the speed that the player is moving it is included in the speed that the weapon is launched at. 0 means it isn't, 1 means it is (default). E.g. VelEffect=1

This is the item (ammo) required to use the weapon. If set to NONE, no ammo is required. (This is the default if this field is omitted).

The amount of a weapon item that can be carried. E.g. MaxCarried=50

Adding this field provides an alternate method for controlling how many times a player may use a particular weapon item. It overrides the Item/Ammo options. The value you provide here is the number of times the weapon can be fired until the player next dies. e.g. AmmoPerLife=3 means the weapon can be fired 3 times in each 'life'. (The count is reset if their vehicle explodes or their character dies).

This field is only required when using *settings → Subgame → Weapons Control Mode set to 2. In this mode each player has an 'energy bar', which is depleted when they receive damage and when they fire weapons. The amount of energy each weapon takes is set in this field. The total amount of energy for each player is 65000, so (ignoring any energy recharge rate), setting a weapon to Energy=32500 means it could be fired twice before the player ran out of energy.

This is the graphic used for the weapon. Note that the validity of this field depends upon the type of object used. (See below). Some objects, like plasmas, machine guns etc, use a specific model or graphic for their effect, which overrides the graphic setting you enter here. In normal use however, the graphic value should be a number from 1 to 8 - which refers to the Weapon Models 1 - 8 that you can set on the Server Menu → Tools → Model Selector page. E.g. Graphic=4

This is the sound played when this weapon is fired. The value given corresponds to the 'Assignable Sound' number that you choose on the server's Tools → Sound Selector dialog in the following way: sound=500 would play assignable sound 1. sound=501 would play assignable sound 2, etc.

This determines whether muzzle flashes appear from a vehicle model's weapon attach points. E.g. Muzzle=0.5 (must be a float value, eg 0.1 or 1.5, that determines the size of the flash)

This field is only required when using one of the 'plasma' weapon objects. Larger values here mean the plasma graphics are bigger. The default value (used if this field is omitted) is 0.05. e.g To double the size of the default plasma graphics, add GraphicSize=0.1

If present, this field means a nice little 'trail' graphic is attached to the weapon object when it is fired. The value entered here determines the 'type' of the trail.. some are different colours and/or behave differently. e.g. Trail=1

If a trail is attached (see above), then this parameter determines the width of the trail graphic. If omitted, the trail width is set to a default value of 1000.

If a trail is attached (see above), then this parameter determines the length of the trail graphic. If omitted, the trail length is set to a default value of 800.

This is the animation played when this weapon is fired. If omitted, the player will use the normal generic weapon fire animation where applicable.

Options for this field are:

AnimFire
AnimFireMG
AnimFirePlasma
AnimWeap1
AnimWeap2
AnimWeap3
AnimWeap4
AnimWeap5
AnimWeap6
AnimWeap7
AnimWeap8. 

This is an (optional) name for the weapon - If present it is displayed in the weapon selection window.

These fields are generally only used by particular modes as described:

This field is used to control the expiry time of bullets, in 1/100ths of a second, only when the 'Object=MG' type is used (because with MGs the 'Expiry=' field is used to determine the longevity of the burst). E.g. SubExpiry=500

[Not working at the moment]. Adds an offset so weapons fire out at different angles. E.g. rotoffset=90 means weapons fire from the left hand side of a vehicle. Rotoffset=270 means they fire from the right.

This field is only used when the 'Control=HoldBar' method is used. The value here determines the number of divisions in the bar.. e.g. Steps=4 means there are 4 distinct divisions in the power bar.

This is used for 'powered' weapons (such as 'Rockets') and determines the maximum speed they will travel at when the weapon 'engine' is enabled.

This is used for 'powered' weapons (such as 'Rockets') and determines the acceleration rate of the weapon when its 'engine' is enabled.

This field is only used when using the 'Fire=DualAim' method - when used it determines the distance apart the pair of bullets are. If omitted, a default value of 0.1 is used.

[Not working at the moment]. Including this value means that, when a weapon hits a target, any players standing within the region receive some damage. The value is the splash damage radius in metres. e.g. SplashRadius=10 means anyone within 10 metres of the weapon when it hits something will receive damage. The amount of splash damage players receive varies according to how far from the weapon they were..

If set to 1, the weapon can't be fired unless the player has acquired a target through the system activated by server command: *targetingmode [PLAYERNAME] [mode] [dist] : Link to targetingmode page :)

You can use NotifyMode to have the server trigger a script function when something happens to the weapon.
NotifyMode = 1, means the server triggers the “WeaponHitGround” event when the weapon hits the ground (with the weapon number as param).
NotifyMode = 2, means the server triggers the “WeaponHitPlayer” event when the weapon hits a player.
NotifyMode = 3 activates both the above systems.

Currently this just supports mode 1, which means the weapon is not allowed to be fired if the player is within 30m of a crow flag. Further, more configurable options will be added if/as required.

Any text following a # symbol is ignored by the game, so you can use that for commments and annotation to make your weapons file more readable, or temporarily edit out particular settings.

Another useful command is .debugweap 1. This runs through your current script and prints a list of error messages, if it finds any problems.