Differences

This shows you the differences between two versions of the page.

--- world_setup:weapons_reference [2020/02/17 17:17] – created mit
+++ world_setup:weapons_reference [2020/02/17 19:11] (current) – [Weapons.txt Field Reference] mit
@@ Line 2: / Line 2: @@
 ===== Weapons.txt Field Reference ======
-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.
+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.
-==== Main Weapon Script Fields ====
+===== Required Weapon Fields =====
+These fields are required on each weapon for it to function:
-- CONTROL=
+==== CONTROL ====
+>>[[world_setup:weapons_reference:control modes|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.
+==== FIRE ====
+>> [[world_setup:weapons_reference:fire modes|Weapon Fire Modes Reference]]\\
-Click here for a list of the options available for the CONTROL= field.
-- FIRE=
 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.
+===== Main Weapon Script Fields =====
+These fields are not always essential for a functional weapon but you'll usually want to set each.
-Click here for a list of the options available for the FIRE= field
-- OBJECT=
+==== OBJECT ====
+>> [[world_setup:weapons_reference:object types|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.
+==== SPEED ====
+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.
+FIXME : Speed is probably in m/s but i need to check that..
-Click here for full details of the object types available
+==== DELAY ====
+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
-- SPEED=
+==== DAMAGE ====
-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. A value of 1000 launches the weapon at (very roughly) 100mph.
+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
-- PITCH=
+===== Other General Weapon Fields =====
+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.
+==== PITCH ====
 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.
+==== EXPIRY ====
-- EXPIRY=
 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
+==== PARAM ====
+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
-- DELAY=
+==== BUILDDAMAGE ====
+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 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
+==== PROX ====
+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.
+==== MINEXPIRY ====
+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.
-- PARAM=
+==== MINSPEED ====
+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 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
+==== VELEFFECT ====
+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
+===== Ammunition & Item restrictions =====
-- DAMAGE=
+==== ITEM ====
+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).
-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
+==== MAXCARRIED ====
+The amount of a weapon item that can be carried. E.g. MaxCarried=50
+==== AMMOPERLIFE ====
+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).
-Weapon Script Fields controlling Graphical Appearance
+==== ENERGY ====
+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.
-- GRAPHIC=
+===== Weapon Graphics & Sounds =====
+==== GRAPHIC ====
 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
+==== SOUND ====
-- SOUND=
 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.
+==== SOUND2 ====
+==== MUZZLE ====
-- MUZZLE=
 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)
+==== GRAPHICSIZE ====
-- GRAPHICSIZE=
 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
+==== TRAIL ====
-- TRAIL=
 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
+==== TRAILWIDTH ====
-- TRAILWIDTH=
 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.
+==== TRAILLENGTH ====
-- TRAILLENGTH=
 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.
+==== ANIM ====
-Weapon Script Fields controlling ammo limits etc
-- ITEM=
-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).
-- MAXCARRIED=
-The amount of a weapon item that can be carried. E.g. MaxCarried=50
-- AMMOPERLIFE=
-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).
-- ENERGY=
-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.
-Misc / Other Weapon Script Fields
-- BUILDDAMAGE=
-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
-- PROX=
-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.
-- MINEXPIRY=
-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.
-- MINSPEED=
-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'.
-- VELEFFECT=
-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
-- ANIM=
 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.
+==== NAME ====
+This is an (optional) name for the weapon - If present it is displayed in the weapon selection window.
-- SUBEXPIRY=
+===== Special Weapon Fields =====
+These fields are generally only used by particular modes as described:
+==== SUBEXPIRY ====
 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
+==== ROTOFFSET ====
-- ROTOFFSET=
 [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.
+==== STEPS ====
-- STEPS=
 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.
+==== POWEREDSPEED ====
-- NAME=
-This is an (optional) name for the weapon - If present it is displayed in the weapon selection window.
-- POWEREDSPEED=
 This is used for 'powered' weapons (such as 'Rockets') and determines the maximum speed they will travel at when the weapon 'engine' is enabled.
+==== POWEREDACC ====
-- POWEREDACC=
 This is used for 'powered' weapons (such as 'Rockets') and determines the acceleration rate of the weapon when its 'engine' is enabled.
+==== SPREAD ====
-- SPREAD=
 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.
+==== SPLASHRADIUS ====
-- SPLASHRADIUS=
 [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..
+==== REQUIRETARGET ====
+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]**
+FIXME : Link to targetingmode page :)
-Editing the script
+==== NOTIFYMODE ====
+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.\\
-Setting up your weapons involves a lot of sitting about on your world with the game running in one window and your script running in Notepad (or similar) in another window. You're not going to break anything seriously by messing about with the script fields, so try something, save the script, and test the results.
+==== RESTRICTIONS ====
+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.
-The script is reloaded each time you join the world. You can also reload it without having to leave and re-join using the command *refreshweap (this also works for other players, not just world owners). So the basic process goes: change something. Save the script. Type *refreshweap. Test the results. Repeat until bored :)
+===== Weapons debugging and comments =====
+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.
-- #' comments
-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.