FreeSpace Wiki - User contributions [en]

Dynamic SEXPs

2021-04-11T12:23:19Z

M!m: Add missing types

{{Tables}}
Since version 3.8.2 FSO supports adding custom SEXPs to a mod which have a user defined effect. Currently there is only one way to add such a SEXP but more may be added in the future.

Dynamic SEXPs are only added in modular table files which end with <tt>-sexp.tbm</tt>

=Table syntax=
This section will describe the syntax and effects of the individual options.

==#Lua SEXPs==

Specifies a list of dynamic SEXPs implemented using a Lua function (see [[#Lua interface|Lua interface]] for how to use the implementation function). This section must end with <tt>#End</tt>

===$Operator:===
*Adds a new SEXP operator with the specified name. The name may not contain the following characters: <tt>()\"'</tt>. Furthermore, any whitespace (tab characters or spaces) are also not permitted. This is the name under which this operator will appear in the SEXP code. While the name is mostly up to you it would be a good idea to keep it in line with how the other SEXPs are named. To avoid conflicts with other custom SEXPs you should also use a unique prefix. For example, if you want to have some SEXP operators that control a cloaking script then you could use <tt>cloak-</tt> as the common prefix for all the operators that are related to this system. A SEXP that disables the cloak system could be named something like <tt>cloak-disable</tt>.
*This name must be unique among all operators that are known to the SEXP system. That includes built-in SEXPs and operators added before. If there is a conflict then the new operator definition will be ignored. Built-in operators always take precedence.
*Syntax: '''''String'''''

===$Category:===
*Specifies in which category this SEXP will appear in the context menu in the FRED event editor. Only one of the existing categories may be used. These are all the currently defined categories:
**Objectives
**Time
**Logical
**Arithmetic
**Status
**Change
**Conditionals
**Ai goals
**Event/Goals
**Training
*Syntax: '''''String'''''

===$Subcategory:===
*Specifies into which subcategory this SEXP should be put. This is the second level in the context menu of the FRED event editor. New subcategories can be added by specifying a new name here but all subcategory names must be globally unique (you can't have the same subcategory name under two different categories).
*Syntax: '''''String'''''

===$Minimum Arguments:===
*Specifies ht minimum number of parameters this SEXP needs to work. If less parameters are specified then the SEXP parser will treat this as an error.
*Must be at least 0.
*Syntax: '''''Integer'''''

===$Maximum Arguments:===
*Specifies the maximum number of parameters this SEXP can process.
*Optional. If this option is not present then the SEXP can process an unlimited number of parameters.
*Must be at least 0 and greater or equal to $Minimum Arguments.

===$Return Type:===
*Specifies what data type this SEXP will return when invoked. Can be one of the following:
**; number: The SEXP will return an integer. The scripting function needs to return a number value.
**; boolean: The SEXP will return a boolean. The scripting function must return a boolean value.
**; nothing: The SEXP will return nothing. The scripting function may not return anything.
*Optional. Defaults to ''nothing''
*Syntax: '''''String'''''

===$Description:===
*Sets the help text displayed in the FRED help box. This should be the generic description of what this SEXP does but should not include the documentation for the individual parameters.
*Syntax: '''''String'''''

===$Repeat===
*This option must be combined with the parameter documentation below to specify a repeating pattern in a SEXP with a variable number of parameters. See the example below for how exactly this will work. All parameters specified after this option will be grouped together. The script will receive these groups of parameters as a single entity (see [[#Lua interface|Lua interface]]) to make it easier to use the values without having to separate them again in the script.

===$Parameter:===
*Adds documentation for the parameters and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by <tt>$Minimum Arguments</tt> and <tt>$Maximum Arguments</tt>.
*This option has no value.

====+Description:====
*Sets the description of this parameter. This will be used for the documentation text.
*Syntax: '''''String'''''

====+Type:====
*Sets the type this parameter requires. The currently supported types are:
**; number: This parameter is a number. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; boolean: This parameter is a boolean. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; ship: This parameter is the name of a ship. The script will receive this value as a <tt>ship</tt> handle. If the name provided by the mission is invalid (if the ship has not arrived yet or if it is not present anymore) then the script will receive an invalid <tt>ship</tt> handle.
**; string: This parameter is a generic string with no special format. In Unicode mode this string may contain Unicode characters.
**; team: This parameter is a handle to a specific team. The script will receive this value as a <tt>team</tt> handle.
**; waypointpath: This parameter is a reference to a specific waypoint path. The script will receive this as a <tt>waypointlist</tt> handle.
**; variable: This is a reference to a SEXP variable. This is a reference to the actual variable and not its contents. The script will receive this as a <tt>sexpvariable</tt> handle.
**; message: This is a reference to a mission message. The script will receive it as a <tt>message</tt> handle.
**; wing: This is a reference to a wing in the mission. The script will receive it as a <tt>wing</tt> handle.
**; shipclass: This is a reference to a table ship class. The script will receive it as a <tt>shipclass</tt> handle.
**; weaponclass: This is a reference to a table weapon class. The script will receive it as a <tt>weaponclass</tt> handle.
**; soundentry: This is a reference to a table defined game sound. The script will receive it as a <tt>soundentry</tt> handle.
*Syntax: '''''String'''''

==Example==
<pre>
#Lua SEXPs

$Operator: dynamic-sexp
$Category: Change
$Subcategory: Scripted
$Minimum Arguments: 3
; No maximum arguments means that it accepts a variable number of arguments
$Return Type: Nothing
$Description: This is a dynamic parameter test SEXP
$Parameter:
+Description: Number parameter
+Type: Number
$Parameter:
+Description: Ship parameter
+Type: Ship
$Parameter:
+Description: Variable name parameter
+Type: variable
$Repeat ; This starts the part of the parameter list where the parameter pattern repeats
$Parameter:
+Description: Variable string parameter
+Type: string
$Parameter:
+Description: Variable number parameter
+Type: Number

#End
</pre>

=Lua interface=
So far, all the SEXP table has done is specify that a new Lua SEXP exists but there is no actual action which will be executed when the SEXP is called. For the Lua language this can be done using the <tt>mn.LuaSEXPs</tt> variable. This is a variable which can be indexed using the SEXP name. The returned value is of type <tt>LuaSEXP</tt> which only has a single field, <tt>Action</tt>. This is the function that will be executed once the SEXP is called in a mission. You can use it to retrieve the function of a LuaSEXP but the more common use case is that it is written in the <tt>$On Game Init</tt> hook to set the action function.

The action function will receive the values as normal parameters. If the SEXP will receive a variable number of parameters then you can use <tt>...</tt> as the last parameter to also capture these values. If a parameter is optional and not specified by the SEXP invocation then it will be <tt>nil</tt> in the script. Parameters in the repeat pattern of the parameter list will be grouped into a array of arrays where each array instance contains the individual values. See below for an example of how this can be handled in the Lua code.

<pre>
#Conditional Hooks

$Application: FS2_Open
$On Game Init: [
mn.LuaSEXPs["dynamic-sexp"].Action = function (arg1, arg2, arg3, ...)
ba.print(tostring(arg1)
ba.print(arg2.Name)
ba.print(tostring(arg3.Value))

for val in {...} do
ba.print(val[1])
ba.print(tostring(val[2]))
done
end
]

#End
</pre>

Action System

2021-02-28T15:16:03Z

M!m:

The dynamic action system is an SCP addition that provides a way for mods to create custom sequences of events that should happen when a certain event occurs. This system is designed to be highly flexible to allow mods complete control over what effects to trigger and where to place them.

This page will describe the basic ideas behind the system and describe how to use it.

==Basic functionality==
The basic functionality of the action system is to take a list of "Actions" and execute them over the span of an arbitrary amount of game-frames. This allows a mod to specify quite complex operations without hard-coding that into the engine. Example:
<pre>
$On Beam Warmdown: ; This defines a "program" to run once a beam weapon has finished firing
; Timing for effects is important so this allows to delay the execution of the remaining actions by 5 (in-mission) seconds
+Wait: 5

; Some actions simply update some internal data which can be used by later actions
; This data will be kept until it is set again and can be used by an unlimited number of actions
+Set Position: (8.0 0.0 0.0)
+Set Direction: (1.0 -1.0 1.0)

; All positions and directions are local to the attached subobject (turret02 in this case) and will respect animations

; These actions actually cause some external "thing" by using the previously set "local" data
+Start Particle Effect: "Beam Warmdown Effect"
+Play 3D Sound: "18"

+Set Position: locals.position + (3.0 0.0 0.0)
+Start Particle Effect: "Beam Warmdown Effect"

+Wait: 3.0

; Programs are attached to the object that triggered them so if the object dies before this can run then the sound will not be played
; The position is still (8, 0, 0) from the previous setting so no need to set it here again
+Play 3D Sound: "19" ; Actions can be used multiple times with different parameters
</pre>

This sequence of actions will be called a "program" in this document. When the corresponding event is triggered, the program is started which creates a "program instance". Every instance of a program is completely separate from each other and will also execute concurrently. This means that a "+Wait:" instruction in one program will not have any effect on another program wanting to trigger a sound effect or something similar.

When a program is started it will have some parameters specified at that point. These parameters are used for attaching an action to a specific object and subobject depending on where it has been triggered. A program attached to an object will only execute for as long as that object is present in the mission and will be stopped once the object is gone. If a program instance is attached to a subobject then all operations will be local to that subobject. Offsets and directions specified in actions will be relative to the selected subobject. However, a program instance will not be stopped if a subobject is destroyed.

In tables, an action option ("$On Beam Warmdown:" in the above example) can also be used several times in sequence. This will collect all those programs and when the event is triggered, every program is started at the same time with the same parameters. This allows to separate different effects into their own programs in order to make management of these actions a bit easier.

The points where these action programs can be used are documented in the relevant tables.

==Action expressions==
The value used for actions ("locals.position + (3.0 0.0 0.0)" for "+Set Position: locals.position + (3.0 0.0 0.0)" above) is a so called "Action expression". This is a simple language for expressing mathematical expressions which is used for every parameter of an action. The language follows the usual mathematical rules with some special parts that will be described here.

*'''~(<left> <right>)''': Will evaluate to a random value uniformly distributed without the range between <left> and <right>.
*'''"<name>"''': Is a string value. This is necessary for actions taking names of other tables as parameters. For example "+Start Particle Effect".
*'''(<x> <y> <z>)''': Will create a 3D vector value. Used for positions and directions. Each of the x, y, and z values can themselves be expressions again.

===Variables===
Every program instance will have some "local" variables assigned to it. This is a set of values that can be changed by the program and used by other actions for altering their behavior. These values are available within expressions:
*'''locals.position''': A vector value specifying an offset from the host of the program instance. Can be changed with "+Set Position".
*'''locals.direction''': A vector value specifying a direction. Can be changed with "+Set Direction".

==Available actions==
All of these listed actions can generally be combined freely with each other.

===+Wait:===
Will delay the execution of subsequent actions by the specified amount of in-game seconds.

'''Parameter type:''' ''Floating point number''

===+Set Position:===
Will alter the value of "locals.position" to the specified value.

'''Parameter type:''' ''3D Vector''

===+Set Direction:===
Will alter the value of "locals.direction" to the specified value.

'''Parameter type:''' ''3D Vector''

===+Move To Subobject:===
Will alter what subobject the program instance is attached to. A value of "<parent>" will move to the parent subobject of the current one. Otherwise the name of any other subobject may be specified.

'''Parameter type:''' ''String'' "<none>" or a valid subobject name.

===+Start Particle Effect:===
Triggers a [[Particle Effects|particle effect]] with the specified name. Will use "locals.position" as an offset and "locals.direction" to orient the effect.

'''Parameter type:''' ''String'' The name of a particle effect to trigger.

===+Play 3D Sound:===
Plays the specified 3D sound. Will use "locals.position" as an offset to compute the global position of the sound.

'''Parameter type:''' ''String'' The name of the sound as specified in [[Sounds.tbl]]

[[Category:Modding]]

Weapons.tbl

2021-02-28T13:51:41Z

M!m: Added $On Create:

{{TableVersionGit|2017-08-25|2039815}}
{{Tables}}
The '''weapons.tbl''' defines all of the weapon classes used in FSO.

This table is one of the [[Modular Tables]] and can be extended with xxx-wep.tbm

==Introduction==
The weapons.tbl is responsible for defining the behavior of the numerous weapon effects used in FSO, including the amount of damage dealt, the firing rate, and graphical effects.

This wiki page goes over all of the entries used exclusively in the weapons.tbl file. Hyperlinks to individual weapon creation/editing tutorials are provided when appropriate.

==Special Case Weapons==
===Beam Cannons===
'''REQUIRES:'''
*'''"beam"''' flag
*'''[[weapons.tbl#$BeamInfo:|$BeamInfo:]]'''

See also: [http://www.hard-light.net/wiki/index.php/Tutorial_-_Beam_Weapons Tutorial - Beam Weapons]

===Flak Guns===
'''REQUIRES:'''
*'''"flak"''' flag
*'''"particle spew"''' flag
*Must have inner and outer radius defined to have any effect.
*A '''.pof''' model must be defined ( usually '''Hornet.pof''' )
**Note: the model is not actually used... Instead, it uses [[Weapons.tbl#$Pspew:|particle spew]]. Trails may also be added.

==General Format==
*The weapons table consist of several sections
*All sections beginning with <nowiki>#</nowiki> need <nowiki>#</nowiki>'''End''' before the next section.
**<nowiki>#</nowiki>'''Primary Weapons'''
***Defines all '''standard primaries weapons''' as well as '''beam cannons''' and '''flak cannons'''.
**<nowiki>#</nowiki>'''Secondary Weapons'''
***Defines all '''secondary weapons'''.
**<nowiki>#</nowiki>'''Beam Weapons'''
***I haven't got any ideas for this one.
**<nowiki>#</nowiki>'''[[Weapons.tbl#Countermeasures|Countermeasures]]'''
***Defines the used countermeasure.
**'''$Player Weapon Precedence'''
***Player Weapon Precedence is used in weapon selection when a default specified by the mission designer is not available to the player. The next weapon on the list is used in its place (assuming that weapon is allowed for the player).

==Core Table==

===$Name:===
*This is the name of the weapon. If it's going to be used by the player, keep it under 12 characters so it doesn't spill over the HUD box. Two special characters can be used in the name: '''#''' and '''@'''. Their usage details are the very same than inside the [[Ships.tbl#.24Name:_2|$Name field from Ships.tbl]].
*Syntax: '''''String'''''

====+nocreate====
{{Table3610|
*In [[Modular Tables]] name can be followed by line '''+nocreate''' that prevent game from creating an incomplete entry by leaving the entry unread unless it already exists (either in Weapons.tbl or in earlier parsed *-wep.tbm files) by the time the *-wep.tbm is read.}}

===$Alt Name:===
{{Table3611|
*An alternative name that can be referenced instead of $Name:
*Syntax: '''''String'''''}}

===$Subtype:===
{{Table3610|
Specifies the weapon 's subtype. Overrides the default subtype as specified by the #-section it is in (#Primary, #Secondary, #Beam Weapon, etc.).

{{Note|
:Since the weapon subtype is already specified by the #-section it is in, this option is not particularly useful when the weapon is inside a #Primary or #Secondary section. However, it may be used to specify the weapon slot it uses on fighters/bombers for weapons that are normally capship only (such as beam cannons).}}

*Syntax: '''''String'''''
*Valid Entries:
:Primary
:Secondary}}

===+Title:===
*This is the title of the weapon in the Weapons loadout screen. Only needed for player allowed weapons. Title may be anything. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Syntax: XSTR('''''"String"''''', -1)

===+Description:===
*This is the description you see in the weapons loadout screen. Again, these aren't based on any hard numbers, just approximations. Only needed for player allowed weapons. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Must be followed by '''$end_multi_text'''

'''Example'''

<pre>
XSTR(
"''Standard Issue
''Level 3 Hull Damage
''Level 2 Shield Damage''", -1)
$end_multi_text
</pre>

===+Tech Title:===
*Title of the weapon in the Tech room. Only needed for player allowed weapons.
*Syntax: XSTR('''''"String"''''', -1)

===+Tech Anim:===
*Animation used for the weapon in the Tech room. Only needed for player allowed weapons.
*Syntax: '''''String''''', animation filename
**Example: ''Tech_Subach_HL-7''

===+Tech Description:===
*Descriptive text you see in the tech room. Only needed for player allowed weapons. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Must be followed by '''$end_multi_text'''

'''Example'''

<pre>
XSTR(
"''The Subach-Innes HL-7...''", 3245)
$end_multi_text
</pre>

===$Tech Model:===
{{Table3610|
*Defines model used in wing loadout screen for the weapon. 3D weapon models in the tech room have not yet been implemented.
*Syntax: '''''String.pof''''', model filename}}

====+Closeup_Pos:====
{{Table3613|
*How the model will show on the Loadout Screen. The position of the camera relative to the model center.
*Syntax: '''''Vector''''', three '''floats''', x, y and z values respectively}}

====+Closeup_Zoom:====
{{Table3613|
*How the model will show on the Loadout Screen. How far the camera's zoomed in, defines camera's FOV.
*Syntax: '''''Float''''', radians}}

===$Selection Effect:===
{{Table3613|
*Defines which selection effect to use when the -weapon_choice_3d commandline flag is enabled or no ani can be found for the selected weapon.
*Syntax: '''''String''''', either "FS1", or "Off". This defaults to the FS2 effect.
}}

===$HUD Image:===
{{Table3610|
*Defines the picture used to represent the weapon in HUD loadout list
*Syntax: '''''String''''', filename}}

===$Model File:===
*Filename of the model file (.pof) at data/models folder. Additional fields beginning from '''''@Laser Bitmap:''''' and ending to '''''@Laser Tail Radius:''''' are not needed if a model has been defined for the weapon.
*Standard primaries and beam cannons do not use specific models so for those the name is 'none'.
*Flak weapons and secondaries use models, though the exact model is not important with the flak weapons.
*Syntax: '''''String.pof''''' or ''none'', model filename
**Example: ''none''

===$POF target LOD:===
{{Table3610|
*Defines the LOD (Level-Of-Detail) of the model used in HUD targeting view
*Syntax: '''''Integer'''''}}

===$Detail Distance:===
{{Table3613|
*Defines the distance where the change between different Levels-Of-Details (LODs) occurs
*Take notice that these are base values. Model detail in Detail options, (within game press F2), applies a multiplier to these values. These multipliers are (from left to right): 1/8, 1/4, 1, 4, 8
*Optional. If not defined the game uses the formula ((radius * 20.0 + 20.0) * LOD)
*Syntax: '''''(Detail Distances)''''' , list of '''integers''' (same amount as LODs), distances from the model in meters
**Example: ''(0, 80, 300, 900)''}}

===$External Model File:===
{{Table3610|
*Defines the models shown on the gunpoint, used with Bobb's external-visible-weapon code.
*Syntax: '''''String.pof''''', model filename}}

===$Submodel Rotation Speed:===
{{Table3610|
*Defines the rotation speed of the subobject, with the $gun_rotation property defined, in the external weapon model.
*Syntax: '''''Float'''''
*Note: weapon fire will be delayed by the time it takes for the weapon to spin up to this speed (using $Submodel Rotation Acceleration or its default value), regardless of whether an external model is used or not.
}}
{{Table38|
*Note: It's no longer required that the ship actually have external models enabled (whether or not this weapon has one defined) for the spin up delay to occur.
}}

===$Submodel Rotation Acceleration:===
{{Table3610|
*Defines the rotation acceleration of the external weapon model.
*Syntax: '''''Float'''''
*Default value: 10}}

===@Laser===
In the event a 3D model is not defined for the weapon, FSO creates an object similar to a glowpoint. Essentially, it is a 2D plane that always faces the player's camera with an additive texture applied to it, and may or may not have an omnilight follow it.

As suggested by its name, this option group is normally used for lasers and similar primaries, but it may also be used for other weapon types as well.

Unless said otherwise, the graphic files used within this group may be of any compatible type (.DDS, .PCX, .TGA, etc.), however a .DDS is recommended.

====@Laser Bitmap:====
Defines the graphic file to be used as the weapon effect.

Blending type: additive

Syntax: '''''String''''', filename

'''Example:'''
<pre>
@Laser Bitmap: my_laser_bitmap
</pre>

====@Laser Glow:====
Defines the graphic file to be used for the glowmap of the weapon effect.

Blending type: additive

*This file is 'multiplied' by a value between Color and Color2.
*The physical dimensions of the glowmap in-game is 2x the size of the bitmap.

Syntax: '''''String''''', filename

'''Example:'''
<pre>
@Laser Glow: my_laser_glowmap
</pre>

====@Laser Color:====
The RGB color of the glow effect.

*The color is applied both to the glowmap and the omnilight that follows the effect.

Syntax: '''''Color''''', red, green, blue respectively, 8-bit value from 0 to 255

'''Example:'''
<pre>
@Laser Color: 255, 0, 0 ; Red glow effect at the start of the effect's lifetime
</pre>

====@Laser Color2:====
The RGB color of the glow effect at the end of the effect's lifetime (at its maximum range).

*The color is applied both to the glowmap and the omnilight that follows the effect.
*The actual color of the glow effect is somewhere in between the values defined by Color and Color2. Essentially, the actual color "fades" from Color to Color2 over its lifetime.
**If Color is not defined, then a default value of 255, 255, 255 is assumed for its initial color.

Syntax: '''''Color''''', red, green, blue respectively, 8-bit value from 0 to 255

'''Example:'''
<pre>
@Laser Color2: 0, 0, 255 ; Blue glow effect at the end of the effect's lifetime.
</pre>

'''Example:'''
<pre>
@Laser Color: 255, 0, 0 ; Start with a Red glow effect, and fade into...
@Laser Color2: 0, 0, 255 ; a Blue glow effect over the lifetime of the effect.
</pre>

====@Laser Length:====
Defines the length of the weapon effect.
*This option stretches the 2D plane "away" from its origin.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Length: 1.0
</pre>

====@Laser Head Radius:====
Defines the width of the leading edge, or "head," of the weapon effect.
*The edge of the 2D plane farthest away from its origin is the leading edge.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Head Radius: 0.75
</pre>

====@Laser Tail Radius:====
Defines the width of the trailing edge, or "tail" of the weapon effect.
*The edge of the 2D plane that is closest to its origin is the trailing edge.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Tail Radius: 0.75
</pre>

===$Collision Radius Override:===
{{Table202|
*Weapon - weapon collisions are treated as two spheres, where a laser's sphere's radius is equal to its Head Radius, and a missile's is the radius of its associated model (possibly doubled). Using this will override either of those values.
*NOTE: If the weapon is interceptable, such as a bomb or has been given hitpoints, this value will ''still'' be doubled, unless the "no radius doubling" flag is used.
*Syntax: '''''Float''''', meters}}

===$Mass:===
*How much of a kinetic effect this weapon has on its target. 3+ gives you the Flail effect. Set it to 10 and you can knock cruisers around.
*This is multiplied by the speed. ie ''$Mass: 3'' and ''$Velocity: 200'' has much weaker kinetic effect than ''$Mass: 3'' and ''$Velocity: 1000''. Also $Mass is used to calculate intensity of "shudder" effect if flagged.
*Syntax: '''''Float''''', blast effect

===$Velocity:===
*How fast the weapon travels. Is also used to define the weapon range, '''''$Velocity x $Lifetime = range'''''.
*Beams travel instantly so this field has effect only on weapon range and AI beam targeting with certain beam types. $Velocity of beam also applies to its kinetic effect along with $Mass.
*Syntax: '''''Float''''', meters per second

===$Fire Wait:===
*Time in seconds between firings
*Note that Fire wait will be reset to 1 if it is set over 5 for non turreted primary weapons (doesn't apply to 3.6.14+)
*Syntax: '''''Float''''', seconds

====+Max Delay:====
{{Table373|
*Defines the maximum amount of time it takes to refire a weapon in a random fire delay range.
**This must be used with +Min Delay: to have any effect.
*Syntax: '''''Float''''', seconds}}

====+Min Delay:====
{{Table373|
*Defines the minimum amount of time it takes to refire a weapon in a random fire delay range.
**This must be used with +Max Delay: to have any effect.
*Syntax: '''''Float''''', seconds}}

===$Damage:===
*Base damage this weapon does. The actual damage is this number multiplied by the factors below.
*Base damage this beam does is continuous damage, damage is approximately 5.88 times the damage value per second. The actual damage is this number multiplied by one of the factors below.
*The exact factor to multiply by is 100/17, or one 'pulse' of damage every 170 seconds. The generally used wisdom of 5.5 times may have been generally accurate before beam damage was made continuous and frame-rate independent, but is now out of date information.
*Syntax: '''''Float''''', damage
*Note: adding an inner and/or outer radius to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x area effect)

===$Damage Time:===
{{Table373|
*This sets a time from the end of the weapons lifetime that damage will start to attenuate at. '''''Example: Weapon lifetime is 2.0 seconds and the desired effect is to attenuate after 0.5 seconds have passed, set this to 1.5 seconds.'''''
*Syntax: '''''Float''''', seconds. Defaults to 0.0.
**Note: If neither +Min Damage: nor +Max Damage: is set, the damage will always attenuate to zero at max range.
***If both +Min Damage: and +Max Damage: are set, both are defaulted to 0.0 and damage will be attenuated to zero.}}

====+Attenuation Damage:====
{{Table373|
*This sets the damage a weapon will attenuate to after reaching $Damage Time:.
*Syntax: '''''Float''''', damage.}}

====+Min Damage:====
{{Table373|
*This sets the lowest amount of damage possible assuming damage attenuation is taking place. '''''This has been deprecated, please use +Attenuation Damage: instead.'''''
*Syntax: '''''Float''''', damage. Defaults to 0.0.}}

====+Max Damage:====
{{Table373|
*This sets the highest amount of damage possible assuming damage attenuation is taking place. '''''This has been deprecated, please use +Attenuation Damage: instead.'''''
*Syntax: '''''Float''''', damage. Defaults to 0.0.}}

===$Angle of Incidence Damage Multiplier:===
{{Table212|
*Causes the weapon's damage to be multiplied by these factors depending on the angle of incidence.
*It is ''not'' linear, it is based on the sine of the angle to the surface. If the factors are 1x for minimum, and 2x for maximum, at an angle of 45° the multiplier is 1.707x, for instance.
====+Min:====
*The damage multiplier at a perfectly glancing hit, parallel to the surface (although not technically possible).
*Syntax: '''''Float'''''
====+Max:====
*The damage multiplier when hit straight on, perpendicular to the surface.
*Syntax: '''''Float'''''}}

===$Damage Type:===
{{Table3610|
Defines the damage type that this weapon uses. All armor effects are applied after shield and have no function against shockwave or subsystem damage.

'''REQUIRES:''' [[armor.tbl]]

*Syntax: '''''String''''', name of the damage type ( as defined by [[armor.tbl#$Damage Type:|$Damage Type]] )}}

===$Arm time:===
{{Table3610|
*Defines the time after the launch that is required before the weapon comes hot
*If the time has not been reached when the weapon detonates the Dinky explosion is used
*Syntax: '''''Float''''', seconds}}

===$Arm distance:===
{{Table3610|
*Defines the distance from the firing ships that is required before the weapon comes hot
*If the distance has not been reached when the weapon detonates the Dinky explosion is used
*Syntax: '''''Float''''', meters}}
{{Table3615|
*This parameter is also applied to flak weapons. Previous behaviour was to arm weapons after 10 meters of travel.}}

===$Arm radius:===
{{Table3610|
*Defines the distance from the target where the weapon will arm itself
*Syntax: '''''Float''''', meters}}

===$Detonation Range:===
{{Table3610|
*Defines the distance from the point in space that the weapon was launched where the weapon will detonate
*Syntax: '''''Float''''', meters}}

===$Detonation Radius:===
{{Table3610|
*Defines the distance between the target center point point and the weapon which detonates the weapon.
*Syntax: '''''Float''''', meters}}

===$Shockwave damage:===
{{Table3610|
*Override for the damage caused by shockwaves (default is [[#$Damage:]])
*Syntax: '''''Float''''', damage
*Note: adding a shockwave to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x shockwave)
}}

===$Shockwave Damage Type:===
{{Table3610|
*'''REQUIRES ADDITIONAL TABLE'''. Defines the damage type used for the weapon explosions
*Syntax: '''''String''''', name as defined in [[armor.tbl]]}}

===$Flak Detonation Accuracy:===
{{Table3615|
*Normally, flak weapons detonate at a range of 65 to 99 meters from their intended target, depending on the firing ships' weapon subsystem health. This parameter can be used to adjust this behaviour, as it defines the base range used to determine this detonation range. Standard value is 65.
*Syntax: '''''Float''''', range in meters}}

===$Flak Targeting Accuracy:===
{{Table3615|
*Turret-fired flak weapons are normally firing in a cone around the target's predicted position. This parameter can be used to adjust the size of this cones' base radius. Standard is 60 meters.
*Syntax: '''''Float''''', radius in meters}}

===$Untargeted Flak Range Penalty:===
{{Table3615|
*If a flak weapon is fired without a target selected, this parameter defines the range penalty applied to that weapon. Standard is 20 meters, meaning an untargeted flak weapon will detonate after travelling its max range - 20 meters.
*Syntax: '''''Float''''', penalty in meters.}}

===$Blast Force:===
*The intensity of the kinetic blast effect when ship is within the outer radius of the explosion. Comes in effect only if inner and outer radius are defined.
*Syntax: '''''Float''''', blast effect

===$Inner Radius:===
*Radius at which the full explosion damage is done. Marks the line where damage attenuation begins. Damage is reduced by the square of the distance between the inner radius and outer radius. i.e. half way between inner and outer results in 1/4 damage
*Note: adding an inner and/or outer radius to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x area effect)
*Syntax: '''''Float''''', meters

===$Outer Radius:===
*Maximum radius at which any damage is done. See $Inner Radius for the attenuation formula.
*Also defines the size of the shockwave (if shockwave speed is > 0)
*Note: adding an inner and/or outer radius to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x area effect)
*Syntax: '''''Float''''', meters

===$Shockwave Speed:===
*Speed shockwave expands at. Zero means no shockwave and that any area-effect damage is applied immediately
*Syntax: '''''Float''''', meters per second

===$Shockwave rotation:===
{{Table3610|
*Defines how the 3D shockwave is rotated. Random, if left undefined.
*Syntax: '''''Angle''''', three values, pitch, bank, heading respectively, in degrees}}

===$Shockwave model:===
{{Table3610|
*Defines the model file (.pof) used as a shockwave for the 3D shockwaves.
*Syntax: '''''String.pof''''', model filename}}

===$Shockwave name:===
{{Table3610|
*Defines the name of the animation used for the 2D shockwave
*Syntax: '''''String''''', filename}}

===$Dinky shockwave:===
{{Table3610|
*Dinky shockwave are used if the weapon is shot down before arming or if the conditions marked at '''Arm time''' and '''Arm distance''' are not reached before impact
*It uses exactly same entries as the standard shockwaves
*'''''+Shockwave damage:'''''
*'''''+Shockwave damage type:'''''
*'''''+Blast Force:'''''
*'''''+Inner Radius:'''''
*'''''+Outer Radius:'''''
*'''''+Shockwave Speed:'''''
*'''''+Shockwave Rotation:'''''
*'''''+Shockwave Model:'''''
*'''''+Shockwave Name:'''''}}

===$Armor Factor:===
*Multiplier for the damage done to armor
*Syntax: '''''Float''''', damage multiplier

===$Shield Factor:===
*Multiplier for the damage done to shields
*Syntax: '''''Float''''', damage multiplier

===$Subsystem Factor:===
*Multiplier for the damage done to subsystems
*Syntax: '''''Float''''', damage multiplier

===$Lifetime Min:===
{{Table3610|
*Defines the minimum lifetime of the weapon
*Syntax: '''''Float''''', seconds}}

===$Lifetime Max:===
{{Table3610|
*Defines the maximum lifetime of the weapon
*Syntax: '''''Float''''', seconds}}

===$Lifetime:===
*Time before the standard primaries fizzle out and secondaries self destruct. Multiply this by the speed to get the range. If values are too low (below framerate) then the collision detection and graphic effects may suffer.
*This field has no effect for the beams apart from weapon range and AI beam targeting with certain beam types
*Syntax: '''''Float''''', seconds

===$Energy Consumed:===
*The amount of energy each bolt drains firing ship. Has no effect on turretted weapons.
*Syntax: '''''Float'''''

===$Cargo Size:===
*Cargo size, is not used with non-ballistic primaries.
*Amount of missiles available = Bank capacity / Cargo Size.
*Syntax: '''''Float'''''

===$Homing:===
'''This option is exclusive to secondaries.'''
{{Table212|'''This option may now be applied to primaries'''. They may only use heat seeking. For optimal results the "no homing speed ramp" flag may be used.}}

Defines if the bolts/missiles in question is homing

If set to NO, then following fields are not required in the table.

*Syntax: '''''Boolean''''', yes or no

===='''+Type:'''====
Defines the homing method
*Syntax: '''''String''''', ''ASPECT'' or ''HEAT''
{{Table3610| An additional option, ''JAVELIN'', has been added. This behaves like an aspect missile but automatically only locks onto the engines of a target, and only if the engines are in sight.}}

===='''+Turn Time:'''====
Determines how quickly the missile can turn. Ostensibly the number of seconds it takes the missile to do a 360 degree circle at full turn speed, but for complicated reasons this is only true if [[Game_settings.tbl#.2BAI_respect_tabled_turn_time_and_rotdamp|AI respect tabled turn time and rotdamp]] is enabled.
**Syntax: '''''Float''''', seconds

===='''+Turning Acceleration Time:'''====
{{Table202|
Determines how quickly the missile reaches its maximum turn speed.
*Note: Requires [[Game_settings.tbl#.24AI_use_framerate_independent_turning:|$AI use framerate independent turning]] in game_settings.tbl
**Syntax: '''''Float''''', seconds}}

===='''+View Cone:'''====
'''Heat-seeking missiles only'''

This is the width of the weapon's viewing cone, given in degrees. Objects outside this cone are effectively invisible to the missile. The value / 2 gives the angle from the missile's centerline to the edge of the viewing cone.
*Syntax: '''''Float''''', degrees
{{Table3610| Has been enabled also to aspect seekers as an option.}}

===='''+Min Lock Time:'''====
'''For aspect/javelin missiles only'''

The minimum number of seconds to gain a target lock.
*Syntax: '''''Float''''', seconds

===='''+Lock Pixels/Sec:'''====
'''For aspect/javelin missiles only'''
The number of pixels the aspect triangle moves per second while attempting lock-on.

*Syntax: '''''Integer''''', pixels per second

===='''+Catch-up Pixels/Sec:'''====
'''For aspect/javelin missiles only'''

The number of pixels moved per second while attempting to catch up to the target.
*Syntax: '''''Integer''''', pixels per second

===='''+Catch-up Penalty:'''====
'''For aspect/javelin missiles only'''

Extra pixels to move after catching up. (Needs verification )
**Syntax: '''''Integer''''', pixels

===='''+Seeker Strength:'''====
{{Table3610|
Defines the seeking ability of the homing system. Default of heat seekers is 3.0 and for aspect seekers 2.0. Spoofing chance is defined as '''[[#$Countermeasure:|cm type effectiveness]]'''/'''seeker strength''' (missile must be within the countermeasures '''[[#$Countermeasure:|+Effective Radius:]]'''
*Syntax: '''''Float''''', seeker strength}}

===='''+Target Lead Scaler:'''====
{{Table3611|
Defines the type of pursuit course the missile tries to obtain.
*Values < 0 give lag pursuit, values ~ 0 give pure pursuit, values > 0 give lead pursuit.
*Syntax: '''''Float''''', default for heat seekers: 0, default for aspect or javelin seekers: 1.}}

===='''+Target Lock Restriction:'''====
{{Table202|
Defines if the missile can lock onto ships besides the current target
*Syntax: '''''String''''', name of the behavior, default is ''current target only'';.
*''Current target only'' As normal, can only acquire locks on the targeted ship
*''Any target'' Missile will lock on any valid target. Missile locking is still disabled in certain cases, such as when a friendly is the player's target
*''Current target, any subsystem'' Targeting is restricted to the current ship, but will pick turrets and subsystems on that ship. }}

===='''+Independent Seekers:'''====
{{Table202|
Defines the ability for a missile to target multiple objects at once.
*Syntax: '''''Boolean''''', yes or no, default is no.}}

===='''+Trigger Hold:'''====
{{Table202|
Defines the ability to hold the trigger to lock and release to fire.
*Syntax: '''''Boolean''''', yes or no, default is no.}}

===='''+Reset On Launch:'''====
{{Table202|
Defines the ability for locks to reset upon missiles being fired.
*Syntax: '''''Boolean''''', yes or no, default is no.}}

===='''+Max Seekers Per Target:'''====
{{Table202|
Defines the maximum number of seekers that can target a single object.
*Syntax: '''''Integer''''', number of seekers.}}

===='''+Max Active Seekers:'''====
{{Table202|
Defines the maximum number of total seekers for the weapon to have.
*Syntax: '''''Integer''''', number of seekers.}}

===='''+Ship Types:'''====
{{Table202|
Defines the ship types that this missile can target. In order for a ship to be targetable it must be able to match one of the listed types, if some of the below lists are also specified, it must match into those as well.
*Syntax: '''("String" "String")''', ship types.}}

===='''+Ship Classes:'''====
{{Table202|
Defines the ship classes that this missile can target. In order for a ship to be targetable it must be able to match one of the listed classes, if some of the above/below lists are also specified, it must match into those as well.
*Syntax: '''("String" "String")''', ship classes.}}

===='''+Species:'''====
{{Table202|
Defines the species whose ships this missile can target. In order for a ship to be targetable it must be able to match one of the listed Species, if some of the above/below lists are also specified, it must match into those as well.
*Syntax: '''("String" "String")''', species.}}

===='''+IFFs:'''====
{{Table202|
Defines the IFF's whose ships this missile can target. In order for a ship to be targetable it must be able to match one of the listed IFFs, if some of the above lists are also specified, it must match into those as well.
*Syntax: '''("String" "String")''', IFFs.}}

===$Swarm:===
*The number of missiles to fire per volley if it's a swarm missile
*Can be issued to Standard primaries also. Causes single part turrets to malfunction but causes multi part turrets to fire only on their barrel line. Can be used for 'burst fire weapons'. Does not work with player weapons.
*Is incompatible with "Corkscrew" option.
*Swarm will negatively affect the missile's ability to hit its target and will not lead its target even with [[Weapons.tbl#.2BTarget_Lead_Scaler:|Target Lead Scaler]] defined unless [[Game_settings.tbl#.24Swarmers_Lead_Targets:|$Swarmers Lead Targets]] is enabled.
*Syntax: '''''Integer''''', number of shots in a swarm
{{Table3610|
*'''+SwarmWait:'''
**Defines the time between weapons fired in a swarm
**Syntax: '''''Float''''', seconds
***Default: 0.150
***Max: 0.5 (Resets to default if set over 0.5)}}

===$Acceleration Time:===
{{Table371|
*Defines how long it takes for a secondary weapon to attain full speed. Takes precedence over $Free Flight Time (see below) in terms of the weapon's velocity, and affects both locked-on and dumbfired secondaries.
*Syntax: '''''Float''''', seconds
**Default: 0.0}}

===$Velocity Inherit:===
{{Table371|
*Defines how much of the parent ship's velocity to inherit, if [[Ai_profiles.tbl#.24use_additive_weapon_velocity:]] is used.
*Syntax: '''''Float''''', percents
**Default: 100.0}}

===$Free Flight Time:===
{{Table3610|
*Defines the free flight time of homing weapons. During this time weapon flies at 1/4 of its velocity + firing ships velocity in a straight line.
*Syntax: '''''Float''''', seconds
**Default: 0.25}}

'''Note:''' due to dumbfires never changing their speed, using this on a dumbfire missile will have it stuck at freeflight speed even after the end of the freeflight time.

===$Free Flight Speed:===
{{Table3613|
*Defines the speed that the weapon will be travelling at during the free flight segment (see above).
*Syntax: '''''Float''''', Multiplier for the actual speed, minimum 0.01.
**Default: 0.25
{{Note| This feature was never implemented correctly and was removed in r8867. FSO parses but doesn't use the value, and prints a warning in the log. This feature has subsequently been reimplemented, see $Free Flight Speed Factor: below}}
}}

===$Free Flight Speed Factor:===
{{Table202|
*Defines the speed that the weapon will be traveling at during the free flight segment (see above).
*Syntax: '''''Float''''', Multiplier for the actual speed, minimum 0.01.
**Default: 0.25
}}

===$PreLaunchSnd:===
{{Table3613|
*Defines the one-shot sound effect to play at the beginning of a firing stream. Currently only has an effect on primary weapons.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
**Default: No Sound}}

===+PreLaunchSnd Min Interval:===
{{Table3613|
*Defines Minimum interval between when the player stops firing and the next time the pre-launch sound can play, as a limiter in case the player is pumping the trigger.
*Syntax: '''''Integer''''', Minimum delay in milliseconds between the end of the previous firing sequence and the next time the pre-launch sound effect will be played.
**Default: 0 (play pre-launch sound at the beginning of every firing sequence, if present)}}

===$LaunchSnd:===
*Corresponding sound effect when the weapon is launched.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$ImpactSnd:===
*Sound the weapon makes when it hits a hull.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$Disarmed ImpactSnd:===
{{Table3610|
*Sound the weapon makes when it hits a hull before being armed.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$FlyBySnd:===
*The sound this weapon makes if it narrowly misses you. -1 is no sound.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]], usually -1

===$TrackingSnd===
{{Table3615|
*The looping sound played when this weapon tracks a target.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$LockedSnd===
{{Table3615|
*The sound played when this weapon has locked onto its target.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$InFlightSnd===
{{Table3615|
*The looping sound played when the missile is currently flying.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+Inflight sound type'''
**Specifies when the in flight sound is played.
**The value can be one of the following values which are matched case-insensitively:
***''''''TARGETED'''''': The sound is played when the missile tracks a target
***''''''UNTARGETED'''''': The sound is played when the missile is currently not tracking a target
***''''''ALWAYS'''''': The sound is played always}}

===$Model:===
{{Table3610|
*Defines used model file. Included for compatibility with countermeasures as they have been merged with weapons in the code.
*Syntax: '''''String.pof''''', model filename}}

===$Rearm Rate:===
*Defines the frequency that weapons are loaded to the ship
*Syntax: '''''Float''''', How many times per second the weapons are loaded.
**Example: 2.0 will reload every half second. 0.1 will load every ten seconds.

===$Rearm Ammo Increment:===
{{Table38|
*Defines how many missiles or how much ballistic ammo is loaded per load sound.
*Syntax: '''''Integer''''', how many bullets or missiles are loaded.}}

===+Weapon Range:===
*Defines the range to the target where the weapons under AI will start firing. This also affects the [[Hud_gauges.tbl#Lead_Indicator|Lead Indicator]]
*Syntax: '''''Float''''', meters

===+Weapon Min Range:===
{{Table3610|
*Defines the minimum range to the target where the weapons under AI will still fire.
*Implemented before FS_Open 3.6.5
*Syntax: '''''Float''''', meters}}

===$Flags:===
*See [[Weapons.tbl#Weapons.tbl_Flags|below]]
*Syntax: '''''( "String" "String" )''''', names of the flags assigned to the weapon
**Example: ( "Player allowed" "in tech database" )

{{Table3610|
*Can be followed by '''+override''' option in order to reset the weapon flags before parsing in the new ones
*Using this option will erase all '''homing'''-related flags as well as '''swarm''', '''variable lead''', '''trail''', '''TAG''', and '''transparent''' settings in addition to the listed flags. All these should be set again - if they are required - when this option is used.

**Syntax: '''''+override'''''}}

===$Trail:===
*This is used if you want your weapon to have a trail. Trail is often used only with secondaries though it works with standard primaries as well.
*'''+Start Width:'''
**How wide the head of the trail is.
**Syntax: '''''Float''''', meters
*'''+End Width:'''
**How wide the tail of the trail is.
**Syntax: '''''Float''''', meters
*'''+Start Alpha:'''
**The opacity of the trail head.
**Syntax: '''''Float''''', value between 0 and 1
*'''+End Alpha:'''
**The opacity of the trail tail.
**Syntax: '''''Float''''', value between 0 and 1
{{Table212|
*'''+Alpha Decay Exponent:'''
**Causes the trail to fade away non-linearly. The 1 -> 0 progress through the trail's life is taken to the power of the provided number when being used for trail alpha purposes
**Smaller numbers below 1 cause the trail to fade away very slowly at first, and then suddenly at the end. Larger numbers above 1 cause it to fade away quickly at first, and then slow down for most of its life.
**Syntax: '''''Float''''', positive}}
*'''+Max Life:'''
**How long the trail lasts.
**Syntax: '''''Float''''', seconds
{{Table202|
*'''+Spread:'''
**Causes the trail points to diffuse and drift apart at this speed over time.
**Syntax: '''''Float''''', meters per second}}
*'''+Bitmap:'''
**The graphic file to use for the trail.
**Syntax: '''''String''''', filename
{{Table212|
*'''+Bitmap Stretch:'''
**Multiplies how far the bitmap is stretched over each trail segment.
**Syntax: '''''Float'''''}}
{{Table3611|
*'''+Faded Out Sections:'''
**Defines the number of the trail sections (counting from the leading edge) which are gradually faded out.
**Syntax: '''''Integer''''', number of trail sections}}

===$Icon:===
*Loadout icon used in the weapons selection screen.
*Syntax: '''''String''''', filename

===$Anim:===
*Green grid animation used on the weapons screen.
*Syntax: '''''String''''', filename

===$Collide Ship:===
{{Table3610|
*Has been replaced with '''#Conditional Hooks''', see [[Scripting.tbl]]}}

===$Collide Weapon:===
{{Table3610|
*Has been replaced with '''#Conditional Hooks''', see [[Scripting.tbl]]}}

===$Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for impacts of this weapon.
*Syntax: '''String''', the particle effect name
*If this option is specified then ''$Impact Explosion'' and ''$Impact Explosion Radius'' are not valid options!
}}

===$Impact Explosion:===
*Impact explosion used. Must be defined in weapon_expl.tbl,
*Syntax: '''''String''''', filename or ''none''

===$Impact Explosion Radius:===
*Radius of the defined impact explosion.
*Syntax: '''''Float''''', meters, default 1.0

===$Shield Impact Explosion Radius:===
{{Table373|
*Radius of the shield impact explosion, see [[Ships.tbl#.24Shield_Impact_Explosion:]].
*Syntax: '''''Float''''', meters, defaults to value of $Impact Explosion Radius}}

===$Dinky Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for Dinky (not armed) explosions of this weapon.
*Syntax: '''String''', the particle effect name
*If this option is specified then ''$Dinky Impact Explosion'' and ''$Dinky Impact Explosion Radius'' are not valid options!
}}

===$Dinky Impact Explosion:===
{{Table3610|
*Same as Impact Explosion but for Dinky (not armed) explosions
*Syntax: '''''String''''', filename or ''none''}}

===$Dinky Impact Explosion Radius:===
{{Table3610|
*Same as Impact Explosion Radius but for Dinky explosions
*Syntax: '''''Float''''', meters}}

===$Piercing Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for piercing impacts.
*Syntax: '''String''', the particle effect name
*If this option is specified then piercing impact options below are not valid!
}}

===$Piercing Impact Explosion:===
{{Table3611|
*Defines the effect used for events when weapon pierces the target
*Syntax: '''''String''''', filename or ''none''}}

===$Piercing Impact Radius:===
{{Table3611|
*Defines the base radius of the effect used for piercing weapon impacts
*Syntax: '''''Float'''''}}

===$Piercing Impact Velocity:===
{{Table3611|
*Defines the base velocity for the particles piercing the target
*Syntax: '''''Float'''''}}

===$Piercing Impact Splash Velocity:===
{{Table3611|
*Defines the base velocity for the particles splashing from the target (secondary piercing effects
*Negative value causes the second batch or particles to splash to opposite direction
*Syntax: '''''Float'''''}}

===$Piercing Impact Variance:===
{{Table3611|
*Defines the variance added to the particles
*Values near 0 cause very little variance and values close to 1 cause extreme dispersal.
*Syntax: '''''Float'''''}}

===$Piercing Impact Life:===
{{Table3611|
*Defines the lifetime of the effect for single frame effects
*For multiple frame effects the lifetime is the lifetime of the animation used
*Syntax: '''''Float'''''}}

===$Piercing Impact Particles:===
{{Table3611|
*Defines the number of particles released per impact
*Syntax: '''''Integer'''''}}

===$Piercing Impact Draw Modifier:===
{{Table3611|
*Defines the multiplier applied to the ships piercing effect limit percentage
*Syntax: '''''Float'''''}}
*Option removed in 3.6.12. Use [[armor.tbl]] to finetune piercing effects.

===$Inflight Effect:===
{{Table38|
*Sets the inflight [[Particle Effects|particle effect]] which is used when the laser is active. This is only used by laser weapons.
*Syntax: '''''String''''', the particle effect name
}}
===$Freeflight Effect:===
{{Table38|
*Sets the [[Particle Effects|particle effect]] which is used when the missile is in the free flight phase. See [[#$Free Flight Time:|$Free Flight Time]] for more information.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Ignition Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is transitioning from free flight to homed or unhomed flight.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Homed Flight Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is in homed flight mode.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Unhomed Flight Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is in unhomed flight mode.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}

===$Muzzleflash:===
*Normally only with flak cannons.
*Defines the muzzle flash the weapon uses
*Syntax: '''''String''''', muzzleflash name, as defined in [[mflash.tbl]]

===$EMP Intensity:===
*If it has an EMP effect, how deeply it scrambles your electronics
*Basically a percentage, a value of 250 results in a 25% chance of something getting scrambled each frame.
*Maximum value of 500
**Syntax: '''''Float'''''

===$EMP Time:===
**Duration of the EMP effect
**Syntax: '''''Float''''', seconds

===$Recoil Modifier:===
{{Table373|
*Multiplies the recoil force of a weapon by this value, use a value greater than 1.0 to increase the force, use a value between 1.0 and 0.0 to decrease.
**Syntax: '''''Float''''' (defaults to 1.0)
{{Note| The "apply recoil" weapon flag must be set for this to be valid. If the flag is not set, FSO will throw a warning and automatically set it at runtime.}}
}}

===$Leech Weapon:===
**The amount of weapon energy to drain with each hit (a flat value, not a percentage)
**Needs the [[#Esuck|Esuck]] flag set to have any effect
**Syntax: '''''Float''''' (defaults to 10.0)

===$Leech Afterburner:===
**The amount of afterburner fuel to drain with each hit (a flat value, not a percentage)
**Needs the [[#Esuck|Esuck]] flag set to have any effect
**Syntax: '''''Float''''' (defaults to 10.0)

===$Corkscrew:===
{{Table3610|
*Allow corkscrew parameters to be defined
*'''+Num Fired:'''
**Defines the number of weapons fired in sequence. Same as the standard swarm entry but for corkscrew missiles
**Syntax: '''''Integer''''', number of missiles
*'''+Radius:'''
**Defines the radius used in the corkscrew motion
**Syntax: '''''Float''''', meters
*'''+Fire Delay:'''
**Defines the delay between missile firings
**Syntax: '''''Integer''''', milliseconds
*'''+Counter rotate:'''
**Defines if every other missile rotates to a different direction (clockwise / anticlockwise)
**Syntax: '''''Boolean''''', ''0'' or ''1'', no or yes
*'''+Twist:'''
**Defines the speed of rotation movement on the radius of corkscrew motion.
**Syntax: '''''Float''''', radians per second}}

===$Electronics:===
{{Table3610|
*Defines the weapons effect against electronics. Requires [[weapons.tbl#"Electronics"|"electronics"]] flag. '''+New Style:''' and '''+Old Style:''' options are mutually exclusive.
*'''+New Style:'''
**Defines that the electronics use the new style which enables more options.
*'''+Old Style:'''
**Defines that the electronics use the old style. The old style was the way the D-Missile worked in Descent: FreeSpace.
}}
{{Table371|
*'''+Area Of Effect'''
**If specified, allows the electronics effect to apply to every ship hit by this weapon's blast or shockwave (the "Electronics" flag isn't necessary with this option).
}}
{{Table3610|
*'''+Intensity:'''
**May only be used with '''+New Style:''' electronics. '''''Has been deprecated'''''.
**Syntax: '''''Float'''''
*'''+Lifetime:'''
**Syntax: '''''Integer''''', milliseconds
*'''+Engine Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for engine subsystems.
**Syntax: '''''Float'''''
*'''+Weapon Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for non-beam turrets.
**Syntax: '''''Float'''''
*'''+Beam Turret Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for beam turrets.
**Syntax: '''''Float'''''
*'''+Sensors Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for sensor subsystems.
**Syntax: '''''Float'''''
*'''+Randomness Time:'''
**Defines the randomness of duration target suffers from the electronics hit. A random number between 0 and this time will be added or subtracted from the disruption time.
**Syntax: '''''Integer''''', milliseconds

* Without any electronics parameters, a weapon with the "electronics" flag will default to the ''Old Style'' mode with a lifetime of 6000 milliseconds and a randomness of 4000 milliseconds. Thus any ship that gets hit can get disrupted for anywhere between 2 to 10 seconds.

}}

===$Spawn Angle:===
{{Table3610|
*Defines the cone (with an angle) where the spawned weapons appear. ''Value'' gives the angle from the missile's centerline. The maximum possible angle between any two child weapons would be ''Value*2''.
*Like all spawn options, Spawn Angle should be defined as many times as the carrier weapon has child weapons defined for it (up to 5), before moving to the next option.
*Syntax: '''''Float''''', degrees, default is 180}}

===$Spawn Minimum Angle:===
{{Table202|
*Defines an inner angle for the cone within which the spawned weapons appear. ''Value'' gives the angle from the missile's centerline.
*Like all spawn options, Spawn Minimum Angle should be defined as many times as the carrier weapon has child weapons defined for it (up to 5), before moving to the next option.
*Syntax: '''''Float''''', degrees, default is 0}}

===$Spawn Interval:===
{{Table202|
*Causes the associated spawn event to happen continuously at this time interval. Enabling this will prevent the spawn event from triggering on detonation.
*NOTE: Having very large numbers of total children (low interval and/or high count) can cause issues for multiplayer, and you will be warned in multiplayer if the ttotal count is greater then 300.
*Like all spawn options, Spawn Interval (and its associated Delay) should be defined as many times as the carrier weapon has child weapons defined for it (up to 5), before moving to the next option.
*Syntax: '''''Float''''', seconds, minimum is 0.1, '''You will not be warned for a negative spawn interval. ''' The value will be ignored and the spawn will be treated as a regular detonate spawn if negative. This is on purpose so that continuous/detonate spawns can be set regardless of the order in which they are defined in the flags.}}

====+Delay:====
{{Table202|
*Continuous spawn will not begin until this has elapsed.
*Syntax: '''''Float''''', seconds, default is 0}}

===$Spawn Effect:===
{{Table202|
*Specifies the [[Particle Effects|particle effect]] which will be used for continuous spawns of this weapon. Will not be used for detonation.
*Like all spawn options, Spawn Effect should be defined as many times as the carrier weapon has child weapons defined for it (up to 5), before moving to the next option.
*Syntax: '''String''', the particle effect name}}

===$Local SSM:===
{{Table3610|
*Defines the local SSM (Subspace Missile). In effect missile moves via subspace to a position close to the target and starts homing.
*Weapon must be '''''aspect seeking missile''''' and must have '''''[[Weapons.tbl#"local ssm"|local ssm]]''''' flag.
*'''+Warpout Delay:'''
**Defines the time between the missile launch and the subspace jump.
**Syntax: '''''Integer''''', milliseconds
*'''+Warpin Delay:'''
**Defines the time missile stays in subspace before exiting.
**Syntax: '''''Integer''''', milliseconds
*'''+Stage 5 Velocity:'''
**Defines the velocity of the missile after the subspace jump.
**Syntax: '''''Float''''', meters per second
*'''+Warpin Radius:'''
**Defines how far from the SSM will appear from the outer radius of the target.
**Syntax: '''''Float''''', meters
*'''+Lock Range:'''
**Defines the maximum range where SSM can achieve target lock
**Syntax: '''''Float''''', meters}}

===$Countermeasure:===

*Defines the countermeasure effectiveness, radius, etc
{{note|
*Spoofing chance is defined as '''cm type effectiveness'''/'''[[#+Seeker Strength:|seeker strength]]''' (missile must be within the countermeasures '''+Effective Radius:''').
*All countermeasures in the mission perform tests to spoof missiles for two frames after '''any countermeasure''' is created in the mission. No, this doesn't seem to make much sense.
{{Table382|The global frame counter can be bypassed by using '''[[#+Pulse Interval:|pulse interval]]'''.}}
*'''Provisional'''; Countermeasures are only given one chance to spoof any individual missile. This makes tuning seeker strength/effectiveness meaningful.
**Previously some record of which countermeasures had been seen by each missile was kept, but it broke when multiple countermeasures were involved. A good chance of breaking with two countermeasures, and a guaranteed chance of breaking with three or more. This reduced the impact of the seeker strength/effectiveness ratio, but was partly cancelled out by the 2 frames thing.
}}

{{Table3610|
===='''+Heat Effectiveness:'''====
*Defines the countermeasures effectiveness against heat seeking missiles
*Syntax: '''''Float''''', cm effectiveness
**Default: 1.0

===='''+Aspect Effectiveness:'''====
*Defines the countermeasures effectiveness against aspect seeking missiles
*Syntax: '''''Float''''', cm effectiveness
*Default: 1.0

===='''+Effective Radius:'''====
*Defines the countermeasures effective radius
*Syntax: '''''Float''''', meters
**Default: 300.0
}}

{{Table373|
====+Missile Detonation Radius:====
*Defines the radius within which a missile homing on this countermeasure will trigger a detonation (see '''+Single Missile Kill:''')
*Syntax: '''''Float''''', meters
**Default: 40.0
{{note| only affects missiles homing on countermeasures, i.e. heat or aspect with "pulls aspect seekers" flag}}

====+Single Missile Kill:====
*Defines if countermeasures will detonate only the missile homing on this countermeasure, or every missile within '''+Missile Detonation Radius:'''
*Syntax: '''''Boolean'''''
**Default: false
{{note| only affects missiles homing on countermeasures, i.e. heat or aspect with "pulls aspect seekers" flag}}
}}

{{Table382|
====+Pulse Interval:====
*Defines how much time passes between each pulse of this countermeasure.
*Syntax: '''''Float''''', milliseconds
**Default: 0
{{note| any value less than or equal to 0 means the countermeasure doesn't pulse, and uses the global 2-frame counter after any countermeasure is fired.}}
}}

{{Table212|
====+Use Fire Wait:====
*Makes the countermeasure fire wait use what is specified in the '''$Fire Wait:''' section of the weapon.
*Default countermeasure fire wait is 333 milliseconds, regardless of that value was set in '''$Fire Wait:'''.

====+Failure Launch Delay Multiplier for AI:====
*After a failed countermeasure launch the game waits a certain time interval before attempting another launch.
*Previously, the amount of time was calculated as ('fire wait' + 2000 * 'countermeasure firing chance').
*If set to a non negative number, this value will be multiplied to the fire wait value to determine the amount of time before another countermeasure can be attempted.
*Syntax: '''''Integer'''''
**Default: -1
{{note| any value less than 0 means the default formula will be used.}}

====+Successful Launch Delay Multiplier for AI:====
*After a successful countermeasure launch the game waits a certain time interval before attempting another launch.
*This value is multiplied to the fire wait value to determine the amount of time before another countermeasure can be attempted.
*Syntax: '''''Integer'''''
**Default: 2
{{note| any value less than 0 means the default value will be used.}}

}}

}}

===$BeamInfo:===
*'''+Type:'''
**Defines the type of beam in question. Beam types: 0 is a standard non-slashing type beam. 1 is a slashing type beam. 2 is a targeting beam that is used to trigger SSMs. 3 is a beam type that fires pulses in anti-fighter role and acts like type 0 beam in other roles. 4 is a beam that is restricted to what is directly in front of it, along turrets firepoints normal.
**Syntax: '''''Integer''''',, only values from 0 to 4 are legal
*'''+Life:'''
**How long it lasts once the beam is actually firing.
**Syntax: '''''Float''''', seconds
*'''+Warmup:'''
**Warmup time
**Syntax: '''''Integer''''', milliseconds
*'''+Warmdown:'''
**Warmdown time
**Syntax: '''''Integer''''', milliseconds
*'''+Radius:'''
**Muzzle glow radius
**Syntax: '''''Float''''', meters
*'''+PCount:'''
**Particles spewed every interval. ??
**Syntax: '''''Integer'''''
*'''+PRadius:'''
**Particle radius
**Syntax: '''''Float''''', meters
*'''+PAngle:'''
**Defines the random "cone" where the particles are generated
**Syntax: '''''Float''''', angle of the cone
*'''+PAni:'''
**Animation used to represent the particles
**Syntax: '''''String''''', filename
*'''+Miss Factor:'''
**The higher the numbers, the more likely that this beam will miss. One value for every difficulty level
**Syntax: '''''Miss Factor''''', five '''floats''', very easy, easy, moderate, hard, insane, respectively.
***Example: 0.5 0.975 1.35 1.875 2.5
{{Table3613|
*'''IFF specific miss factors'''
**Identical to the preceding entry but IFF specific. Replace the <IFF> with the name of the IFF from [[iff_defs.tbl]]
**Syntax: '''''+<IFF> Miss Factor:''''', five '''floats''', very easy, easy, moderate, hard, insane, respectively.
***Example: 0.5 0.975 1.35 1.875 2.5}}
*'''+BeamSound:'''
**Corresponding looping sound effect when the beam is firing.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+WarmupSound:'''
**Corresponding sound effect when the beam is beam warmed up.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+WarmdownSound:'''
**Corresponding sound effect when the beam is warming down.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+Muzzleglow:'''
**Defines the bitmap used to create the muzzle glow
**Syntax: '''''String''''', filename
{{Table372|
*'''+Directional Glow:'''
**Defines the length to stretch the muzzleglow along the beam.
**Syntax: '''''Float''''', length in meters, the muzzleglow is rendered along (in the same plane) as the beam instead of perpendicular to the camera.}}
*'''+Shots:'''
**Defines into how may invidual shots the type 3 (AAA) beams are divided. Note total firing is the same as the +Life:
**ALSO AFFECTS FIGHTER BEAMS. If greater than 0, fires from up to that many fire points at a time before cycling. 1 mimics the behavior of weapons with the "cycle" flag, 0 fires from all available fire points like normal weapons.
**Syntax: '''''Integer''''', Default: 1
*'''+ShrinkFactor:'''
**How much of the beam's life is remaining before it starts to shrink in width. (0.1 means 10% life left)
**Syntax: '''''Float''''', value from 0 to 1
*'''+ShrinkPct:'''
**What factor of beam's width is subtracted per second.
**Syntax: '''''Float''''', value from 0 to 1
{{Table202|
*'''+GrowFactor:'''
**How much of the beam's life is remaining before it starts to grow in width. (1.0 means as soon as the beam fires)
**Syntax: '''''Float''''', value from 0 to 1
*'''+GrowPct:'''
**What factor of beam's width is added per second.
**Syntax: '''''Float''''', value from 0 to 1
*'''+Initial Width Factor:'''
**What factor of the beam's maximum width it starts with.
**Syntax: '''''Float''''', value from 0 to 1}}
{{Table3610|
*'''+Range:'''
**Defines the maximum range where the beam still has any effect.
**Syntax: '''''Float''''', meters
*'''+Attenuation:'''
**Defines the point where the damage caused by the beam starts to attenuate. At maximum range damage is zero.
**Syntax: '''''Float''''', from 0 - firing point to 1 - no effect
***Default: 1}}
{{Table3611|
*'''+BeamWidth:'''
**Defines the width of the beam for collision test purposes instead of using widest beam section.
**Syntax: '''''Float''''
{{Table38|
*'''+Beam Flash Particle Effect:'''
**Specifies the beam flash [[Particle Effects|particle effect]].
**Syntax: '''''String''''', particle effect name
**If this is specified then '''+Beam Flash Effect''' and '''+Beam Flash Radius''' are not valid options!
}}
*'''+Beam Flash Effect:'''
**Defines the additional impact flash effect for the beam.
**Syntax: '''''String''''', filename
*'''+Beam Flash Radius:'''
**Defines the radius for the additional impact flash effect.
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect:'''
**Defines the beam piercing (bursting flames) effect for the beam.
**Syntax: '''''String''''', filename
*'''+Beam Piercing Radius:'''
**Defines the average radius used for the beam piercing effects.
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect Velocity:'''
**Defines the base velocity for the piercing effects
**Syntax: '''''Float'''''
*'''+Beam Piercing Splash Effect Velocity:'''
**Defines the base velocity for the secondary piercing effects
**Negative velocity causes the particles to move to opposite direction
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect Variance:'''
**Defines the variances of the particles from the main path
**Values close to 0 cause minimum variance, higher values cause higher variances
**Syntax: '''''Float'''''}}

*'''$Section:'''
**Beams are made up of up to five sections layered atop one another to create the effect. Each section has its own parameters.
{{Table3610|
:*'''+Index:'''
:**Field used to define with [[Modular Tables]] the beam section which is edited.
:**Only valid when editing beam sections that already exist in other tables. Attempting to index new sections will generate warnings, adding new sections is the default behavior for un-indexed sections.
:**Syntax: '''''Integer''''', index number legal values are from 0 to 5
:*'''+remove'''
:**Removes the set beam section.
:*'''+nocreate'''
:**Does not create new section for the beam}}

:*'''+Width:'''
:**Width of the section
:**Syntax: '''''Float''''', meters
:*'''+Texture:'''
:**Texture for the section
:**Syntax: '''''String''''', filename
:*'''+RGBA Inner:'''
:**Defines the color and transparency of the center of the section
{{Table3613|:**Not used in current builds. Settings entered here will have no effect.}}
:**Syntax: '''''Color''''', red, green, blue, alpha, respectively, value from 0 to 255
:***Example: 255 255 255 255
:*'''+RGBA Outer:'''
:**Defines the color and transparency of the edges of the section
{{Table3613|:**Not used in current builds. Settings entered here will have no effect.}}
:**Syntax: '''''Color''''', red, green, blue, alpha, respectively, value from 0 to 255
:***Example: 150 150 150 10
:*'''+Flicker:'''
:**Defines how much the section flickers
:**Syntax: '''''Float''''', value from 0 to 1
:*'''+Zadd:'''
:**Defines the 'thickness' of the section. The higher the Zadd, the closer the section appears to be. (Zadd can be safely ignored; it actually does nothing.)
:**Syntax: '''''Float'''''
{{Table3610|
:*'''+Tile Factor:'''
:**Defines the beam texture tiling factor. Second number defines the tiling type. Type 0 tiles the graphic in the beam as many times as defined by the 1st number. Type 1 uses the 1st value as the lenght of the tile.
:**Syntax: '''''Float''''', '''''Integer'''''
:*'''+Translation:'''
:**Defines the speed of translation of the beam, a positive value moves from the impact point to the firing point, while a negative value moves away from the firing point towards the impact point. Measured in tiles per second, where the tile count is defined in the "+Tile Factor:" field above.
:**Syntax: '''''Float'''''}}

===$Pspew:===
{{Table3610|
*Defines a particle spew effect for the given weapon
}}{{Table3613|
*'''+Index:'''
**indicates which spewer to add/edit/delete. may be 0-3. used for xmt compatibility.
**Syntax: '''''Integer'''''
*'''+Remove'''
**removes spewer at +Index: (requires +index:)
*'''+Type:'''
**type of particle spew
**Syntax: '''''String'', Default, Helix, Sparkler, Ring, or Plume '''
}}{{Table3610|
*'''+Count:'''
**Defines how many particles are spawn when they are ready to be created (at each +Time: interval)
**Syntax: '''''Integer'''''
*'''+Time:'''
**Defines the time in milliseconds between next particle(s) spewed
**Syntax: '''''Integer''''', milliseconds
*'''+Vel:'''
**Defines the created particles velocity as percentage of the weapons velocity
**Syntax: '''''Float'''''
*'''+Radius:'''
**Defines the size of the created particles
**Syntax: '''''Float''''', meters
*'''+Life:'''
**Defines how long the particles last.
**Syntax: '''''Float''''', seconds
*'''+Scale:'''
**Defines the particle spread. Small value will make particles group together
**typically controls how big the effect is or how fast it moves away from the weapon path on a perpendicular (or sometimes arbitrary) axis.
**helical spews and rings use this value to control how fast the particle helix moves away from the central axis.
**sparklers use this to control how fast particles move away from the spawn point, in any direction
**plumes use this to set the diameter of the disk across which particles are spawned
**Syntax: '''''Float'''''
}}{{Table3613|
*'''+Z Scale:'''
**for sparklers, allows you to elongate the effect to surround other effects, like lasers. essentially a length multiplier
**for plume, it multiplies against +scale to set the plume to spread or converge, zero would be full convergence, 1 would be straight flight, and bigger numbers would cause particles to diverge from the disk.
**Syntax: '''''Float'''''
*'''+Rotation Rate:'''
**used only by helical spews, controls how many rotations per second the helix makes
**Syntax: '''''Float'', may be negative, useful for setting up 2 spews that spin in opposite directions'''
*'''+Offset:'''
**position of effect with regards to the weapon center
**Syntax: '''''Vector'''''
*'''+Initial Velocity:'''
**to indicate both direction and speed of particle effects regards to the weapon velocity and +scale:
**Syntax: '''''Vector'''''
}}{{Table3610|
*'''+Bitmap:
**Defines the animation used to create the particle spew effect
**Syntax: '''''String''''', filename}}

===$Tag:===
*Allowed for secondary weapons
{{Table3610|
*Allowed for primary weapons and secondary weapons}}

*Sets this weapon as a TAG missile, level 1, 2, or 3. The second number is the duration in seconds.
*TAG Level 1 will illuminate hidden targets such as stealth fighters or ships normally obscured by nebula conditions.
*TAG Level 2 illiminates targets much like TAG Level 1, but turrets will prefer to shoot at them over other ships.
*TAG Level 3 has no effect in retail.
{{Table3610|
*TAG Level 3 allows the weapon to trigger [[Weapon.tbl#$SSM:|SSMs]]}}

*Syntax: '''''Integer''''' '''''Float''''', TAG level and seconds respectively
*'''Note''': TAG will not trigger unless the weapon in question has a non-zero damage value.

===$SSM:===
{{Table3610|
*Defines the weapons SSM index number.
*Requires [[Weapons.tbl#$Tag:|TAG level 3]] or a targeting beam.
*Syntax: '''''Integer'''''}}
{{Table373|
*Now also accepts SSM strike names.
*Syntax: '''''String'''''}}

===$FOF:===
{{Table3610|
*Defines the field of fire for the weapon. Causes weapon to fire into a firing cone instead of direct firing line thus causing light inaccuracy
*Syntax: '''''Float''''', degrees}}

====+FOF Spread Rate:====
{{Table37|
*Defines the spread rate of the field of fire. This controls how the FOF increases over time while the weapon is firing.
*Syntax: ''''''Float'''''', rate}}

====+FOF Reset Rate:====
{{Table37|
*Rate at which the spread decreases if the weapon isn't firing.
*Syntax: ''''''Float'''''', rate
*This is required if '''+FOF Spread Rate:''' is present}}

====+Max FOF:====
{{Table37|
*The maximum FOF. After the FOF reaches this value it will not increase any further.
*Syntax: ''''''Float'''''', degrees. Must be greater than or equal to zero.
*This is required if '''+FOF Spread Rate:''' is present}}

===$Shots:===
{{Table3610|
*Defines the number of shots every time the weapon is fired.
*Works only for primary weapons
*Syntax: '''''Integer''''', number of shots}}

===$decal:===
{{Table3610|
*Defines impact decals if they are in use
*'''+texture:'''
**Defines the texture used for impact decals (can use '''''-burn''''' and '''''-glow''''' textures)
**Syntax: '''''String''''', filename
*'''+backface texture:'''
**Defines ???
**Syntax: '''''String''''', filename
*'''+radius:'''
**Defines the size of the impact decals on target
**Syntax: '''''Float''''', meters
*'''+burn time:'''
**Defines the time the '''''-burn''''' texture appears on the target
**Syntax: '''''Integer''''', milliseconds}}
{{Table3613|
*Feature removed - table parsing retained to maintain compatibility}}

===$Impact decal:===
{{Table190|
*Defines an impact decal (think bullet impact/scorch mark) using the new system introduced in FSO 19.0.0.
**Syntax: '''''String''''', this must match to one of the entries in a [[Decals|decal tbm]].
*'''+Radius:'''
**Syntax: '''''Float''''', Radius of the impact decal; default is 1.0
*'''+Lifetime:'''
**Syntax: Either '''''Eternal''''' or '''''Float''''', lifetime in seconds
}}

===$Transparent:===
{{Table3610|
*Defines weapon effect as transparent. Enables optional fields for 'alpha animations'
*'''+Alpha:'''
**Defines the strenght of the alpha (transparency). And also the maximum value for the alpha cycle option
**Syntax: '''''Float''''', from 0 to 1
*'''+Alpha Min:'''
**Defines the minimum alpha value for alpha cycle option
**Syntax: '''''Float''''', from 0 to 1
*'''+Alpha Cycle:'''
**Defines the change in alpha per frame, between '''Alpha''' and '''Alpha Min''' values
**Syntax: '''''Float'''''}}

===$Weapon Hitpoints:===
{{Table3611|
*Defines the amount of hitpoints a weapon has.
*Weapons with '''"bomb"''' flag have 50 hitpoints by default
*Giving weapon hitpoints makes it possible for the weapon to be shot down or be destroyed by EMP.
**Syntax: '''''Integer'''''
}}

===$Armor Type:===
{{Table3613|
*REQUIRES ADDITIONAL TABLE. Defines the armor type for the weapon. This works exactly like ship armor types.
**Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]
}}

===$Burst Shots:===
{{Table3611|
*Defines the number of shots in a burst
*Shots in a burst use shorter ( '''$Burst Delay:''' ) delay than usually
*If this weapon is cycling each individual firing event counts as one burst shot, so bursts end sooner in time for large banks than small.
**Syntax: '''''Integer'''''}}

===$Burst Delay:===
{{Table3611|
*Defines the time in milliseconds between the shots in a burst
**Syntax: '''''Integer'''''}}

===$Burst Flags:===
{{Table3611|
*Defines the flags used to define the burst firing behaviour
**Syntax: ( '''''String''''' '''''String''''' ), list of flags
**Available burst flags:
***'''"fast firing"''', acts as if '''same turret cooldown''' flag would be used between the shots in the burst.
***'''"random length"''', makes AI to fire burst of random length (from 1 to burst shots).}}
{{Table202|'''"resets"''', as long as a full fire wait has passed since last fired, the burst is reset and can be fired in full again.}}

===$Thruster Flame Effect:===
{{Table3611|
*Defines the filename of the effect used on the modeled thruster of the missile
**Syntax: '''''String''''', filename}}

===$Thruster Glow Effect:===
{{Table3611|
*Defines the filename of the effect used on the glow type effect of the missile
**Syntax: '''''String''''', filename}}

===$Thruster Glow Radius Factor:===
{{Table3611|
*Defines the radius multiplier for the thruster's glow type effect
**Syntax: '''''Float'''''}}

===$On Create:===
{{Table212|
*Defines an [[Action System|action system]] program set to be executed when a weapon of this type is created. Only applicable to laser and missile style weapons.
}}

===$Substitute:===
{{Table3613|
Defines a pattern of ammo to substitute for primary or secondary weapons. '''$Substitute:''' can be repeated any number of times (so you could make something like a rainbow laser with several ammo substitutions, for example). If neither ''+period'' or ''+index'' is specified, it is assumed to be equivalent to ''+index: '''0'''''.

*Syntax: '''''Weapon Name'''''
*'''Swarm missiles act in a strange way when used with $Substitute, use at your own risk.'''}}

{{Table3615|
Turrets can use $Substitute as well.
}}
====+period:====
{{Table3613|
FSO will substitute '''Weapon Name''' every ''period'' shots.

*Syntax: '''''Positive Integer'''''
*'''You may not define both +period and +index for the same $Substitute entry'''}}
=====+offset:=====
{{Table3613|
A suboption of +period, offsets the substitute pattern according to the launched ammo. For example, an offset of 3 and a period of 4 will substitute on the 3rd ammo launched, and then every 4th ammo after that.

*Syntax: '''''Positive Integer'''''}}

====+index:====
{{Table3613|
FSO will substitute the '''Weapon Name''' at firepoint ''index'' in the shot pattern. Similar to carefully using both +period and +offset, but is not affected by ships with different firepoint numbers. i.e. Firepoint ''index'' will always have the substitution, while +period and +offset will cycle at different rates dependant on the number of firepoints.'''

*Syntax: '''''Positive Integer'''''

*'''You may not define both +period and +index for the same $Substitute entry'''}}

==Weapons.tbl Flags==

==="Electronics"===
*Will seize up the weapons and engines systems of any ship for a short period of time.

==="Spawn ''Name'',''Value''"===
*Will spawn the specified number of defined missiles upon detonation.
*The flag will parse without a value, using a default of 10.
{{Table3610|
*Multiple spawn types can be defined for a single 'carrier' weapon up to maximum of 5 different weapons}}

==="Remote Detonate"===
*Can be triggered remotely via a second press on the trigger

==="Big Ship"===
*These weapons cannot be mounted on small ships like fighters, bombers, sentry guns etc.

==="Huge"===
*Allows this weapon to do the final 10% damage to a ship with the "Big Damage" flag. Also the AI will not try to hit fighters with it, but only if the weapon is in a turret or is a secondary. If the weapon is a primary in a fighter then there are no targeting restrictions. See [[Weapons.tbl#.22capital.2B.22|capital+]] instead.

==="Supercap"===
*Allows this weapon to do the final 75% damage to a ship with the "supercap" flag.

==="Bomber+"===
*The AI will prefer to use this weapon against bombers

==="child"===
*Cannot be set as a weapon on any ship, but is instead a child of a weapon. Usually defined with "Spawn ''Name'',''Value''"

==="Bomb"===
*Makes this weapon target-able with the B key and interceptable by AIs
** Has been long thought to make the AI prefer this weapon against large ships, but in fact has no effect on AI weapon selection.

==="No Dumbfire"===
*Missile will not fire without a lock

==="in tech database"===
*Has the weapon in the tech database at the start of the campaign

==="Player allowed"===
*Allows this weapon as a player weapon.
{{Table3610|
*'''EXTREMELY IMPORTANT NOTE:'''
**Whenever you plan to use a weapon as a player one in your campaign or missions, '''USE THIS FLAG'''.
**Not using it can cause problems within fs_open and it's a BAD MOD DESIGN.
**In the future, fs_open will maybe be able to avoid these problems but, nevertheless, it's still a BAD DESIGN.
**As another possible example: be careful to update "retail" tables if you plan to use Shivan weapons in player fighters.}}

==="Particle Spew"===
*Makes the weapon projectile spew out particles
{{Table3610|
*Can be defined with [[Weapons.tbl#$Pspew:|Particle Spew parameters]]}}

==="EMP"===
*This weapon will have an EMP effect on any ship within the blast radius
*Can be defined with [[Weapons.tbl#$EMP_Intensity:|EMP Intensity]] and [[Weapons.tbl#$EMP_Time:|EMP Time]]

==="Esuck"===
*Drains the target's energy banks
*Can be defined with [[Weapons.tbl#$Leech_Weapon:|Leech Weapon]] and [[Weapons.tbl#$Leech_Afterburner:|Leech Afterburner]]

==="Flak"===
*Makes this weapon a [[weapons.tbl#Flak_Guns|flak gun]]

==="Corkscrew"===
*Makes this weapon spiral AND swarm 4.
{{Table3610|
*Can be defined with [[Weapons.tbl#$Corkscrew:|Corkscrew parameters]]}}

==="Shudder"===
*Makes your ship shudder while you're firing the weapon

==="lockarm"===
*Requires a target lock in order to arm its warhead. In other words weapon causes less damage if it hits the target without target lock.

==="beam"===
*Makes this weapon a [[weapons.tbl#Beam Cannons|beam cannon]]

==="stream"===
* Does nothing

==="puncture"===
*Reduces hull damage by 75%
The AI will prefer these weapons for anti-subsystem use

==="countermeasure"===
{{Table3610|
*Defines the weapon as a countermeasure}}

==="Ballistic"===
{{Table3610|
*Defines the weapon as a ballistic weapon that needs ammunition.
*Make sure you define the size and reload rate for ballistic weapons}}

==="pierce shields"===
{{Table3610|
*Causes weapons to penetrate shield without causing damage to it.}}

==="no pierce shields"===
{{Table3610|
*Prevents weapons (beams) from piercing shields causing shields to be damaged by weapons first.}}

==="local ssm"===
{{Table3610| }}

==="tagged only"===
{{Table3610|
*Weapon can only be fired at tagged targets}}

==="beam no whack"===
{{Table3610|
*Disables beam whacking (push). Practically same as setting beam mass to zero.}}

==="cycle"===
{{Table3610|
*Causes weapon to alternate between firing points}}

==="small only"===
{{Table3610|
*Causes AI to use the weapon only on small targets (fighters, bombers etc.) Only applies to the target selection of turrets, has no effect on the behavior of fighters picking primary and secondary bank weapons.}}

==="same turret cooldown"===
{{Table3610|
*Forces the turrets to fire on the designated rate of fire on all difficulty levels and all AI levels}}

==="apply no light"===
{{Table3610|
*Prevents light from being applied to the weapon model.}}

==="training"===
{{Table3610|
*Sets weapon to be of training weapon type. ?}}

==="smart spawn"===
{{Table3611|
*Forces turret fired spawn weapon of this type to be fired like normal weapons.}}

==="inherit parent target"===
{{Table3611|
*Sets spawned 'child' weapons to use parent weapon's target.}}

==="no emp kill"===
{{Table3611|
*Defines the weapon (with hitpoints) to be immune to automatic EMP destruction.}}

==="untargeted heat seeker"===
{{Table3611|
*Defines the weapon as a heatseeker type missile which acquires its target by itself.}}

==="no radius doubling"===
{{Table3611|
*Prevents weapon radius from being doubled when doing collision test. Makes bombs harder to intercept.}}

==="no subsystem homing"===
{{Table3611|
*Prevents weapon from acquiring a subsystem as its target. Missile homing points are spread over the target ship.}}

==="no lifeleft penalty"===
{{Table3611|
*Prevents weapon lifetime from being penalized if the angle to the target is too big.}}

==="can be targeted"===
{{Table3611|
*Allows weapon to be targeted by player. Does not influence AI}}

==="show on radar"===
{{Table3611|
*Allows weapon to be visible on the radar}}

==="show friendly on radar"===
{{Table3611|
*Allows friendly, otherwise visible to radar weapon, to be visible on player radar}}

==="capital+"===
{{Table3613|
*Tells AI to use this weapon only on capital ships}}

==="chain external model fps"===
{{Table3613|
*Tells game to keep switching external model firingpoints when firing}}

==="external model launcher"===
{{Table3613|
*Tells game that the external model is a launcher so that it would be kept static without loading motion}}

==="takes blast damage"===
{{Table3613|
*Weapon takes damage from weapon blasts}}

==="takes shockwave damage"===
{{Table3613|
*Weapon takes damage from shockwaves}}

==="ciws"===
{{Table3615|
*Weapon can deal shockwave/blast damage to bombs, regardless of whether the target weapons have the "take blast/shockwave damage" flags.}}

==="render flak"===
{{Table3615|
*Normally, flak shells are not rendered. This flag switches rendering on for those weapons.}}

==="anti-subsystem beam"===
{{Table3615|
*Beam weapons with this flag can target subsystems on enemy ships, just like normal weapons.}}

==="no primary linking"===
{{Table3615|
*Primary weapons with this flag can not be linked with other weapons.}}

==="same emp time for capships"===
{{Table37|
*capships affected by this weapon will use the tabled EMP time rather than the fixed retail value (7.5 secs)}}

==="no primary linked penalty"===
{{Table371|
*Primary weapons with this flag do not incur the retail linked fire penalty}}

==="no homing speed ramp"===
{{Table371|
*Locked homing weapons will not perform the standard 1 second long acceleration when fired. Note that use of $Acceleration Time is '''not''' affected by this flag.}}

==="pulls aspect seekers"===
{{Table371|
*If an aspect seeker is grabbed by this countermeasure the missile will follow the countermeasure instead of going into dumbfire mode.
'''Only valid for countermeasures!'''}}

==="turret interceptable"===
==="fighter interceptable"===
==="interceptable"===
{{Table371|
*Allows turrets/fighters/both (respectively) to shoot at this weapon without requiring it to be a bomb. If this is the first time this weapon has been defined, it also gives it a default of 25 hitpoints so that it can be shot down.
'''If you use a TBM to give this flag to an existing weapon, you'll need to specify hitpoints manually (unless you want it to be unkillable but still draw defensive fire).'''}}

==="apply recoil"===
{{Table373|
*A ship that fires a weapon with this flag will experience a recoil effect, slowing the ship down and, with lighter strikecraft, inducing some rotation if the firing points are offset from the center of mass.}}

==="don't spawn if shot"===
{{Table373|
*Prevents parent weapons from spawning children in the even of the parent weapon being shot down.}}

==="die on lost lock"===
{{Table373|
*Aspect seeking missiles (only, not heat seekers) will detonate upon losing their lock. Currently they only lose lock if decoyed by a countermeasure, AND "pulls aspect seekers" or similar is not set. The detonation will use their "dinky" explosion (i.e. same as if ran out of lifetime).}}

==="no doublefire"===
{{Table202|
*Prevents dual-firing of secondary weapons. If the ship tries to dual-fire a weapon with this flag they are set back to single fire.}}

==="require exact los"===
{{Table202|
*Prevent AI form firing this weapon from a turret or as a secondary weapon if there is no clear line of sight from the weapons firing point to its targeted ship (center). Note that this may keep the weapon trained on a target out of sight while another target may be available to shoot.}}

==Countermeasures==
*Usually not altered. Only one can exist
{{Table3610|
*More than one can exist}}

===$Name:===
*Name of the countermeasure
*Syntax: '''''String''''', name

===$Velocity:===
*Defines the speed of the countermeasure, relative to the ship.
*Syntax: '''''Float''''', meter per second

===$Fire Wait:===
*Definies the minumum time between the countermeasure launches
*Syntax: '''''Float''''', seconds

===Lifetime===
*Countermeasure's life time is defined between with minimum and maximum lifetime
*'''$Lifetime Min:'''
**Syntax: '''''Float''''', seconds
*'''$Lifetime Max:'''
**Syntax: '''''Float''''', seconds

===$LaunchSnd:===
*Defines the sound for the countermeasure launch
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$Model:===
*Defines the used model file (.pof)
*Syntax: '''''String.pof''''', model filename

==Player Weapon Precedence==
*First the primary weapons are defined, from most powerful to least powerful, and then the same for secondaries
*Syntax: ( '''''"String" "String"'''''), names of the weapons
*Example:

<pre>
$Player Weapon Precedence: (
"UD-8 Kayser"
"Prometheus R"
"Subach HL-7"
"Harpoon"
"Tempest"
"Rockeye" )
</pre>

==Sample==

<pre>
#Primary Weapons

$Name: @Subach HL-7
+Title: XSTR("GTW Subach HL-7", 3243)
+Description:
XSTR( "Standard Issue
Level 3 Hull Damage
Level 2 Shield Damage", 3244)
$end_multi_text
+Tech Title: XSTR("Subach HL-7", 146)
+Tech Anim: Tech_Subach_HL-7
+Tech Description:
XSTR(
"Descriptive text...", -1)
$end_multi_text
$Model File: none
@Laser Bitmap: newglo9
@Laser Glow: 2_laserglow03
@Laser Color: 250, 0, 0
@Laser Color2: 0, 0, 250
@Laser Length: 10.0
@Laser Head Radius: 0.90
@Laser Tail Radius: 0.90
$Mass: 0.2
$Velocity: 450.0
$Fire Wait: 0.2
$Damage: 15
$Armor Factor: 0.9
$Shield Factor: 0.7
$Subsystem Factor: 0.3
$Lifetime: 2.0
$Energy Consumed: 0.20
$Cargo Size: 0.0
$Homing: NO
$LaunchSnd: 76
$ImpactSnd: 85
$Flags: ( "in tech database"
"player allowed"
"stream")
$Icon: iconSD4
$Anim: SD4
$Impact Explosion: none

#End

#Secondary Weapons

$Name: EMP Adv.
+Title: XSTR("GTM-14 EMP Adv.", 3396)
+Description:
XSTR( "Advanced Missile
Electromagnetic Pulse Weapon
General Purpose Suppression", 3397)
$end_multi_text
+Tech Title: XSTR("GTM-14 EM Pulse Adv.", 3398)
+Tech Anim: Tech_EMP
+Tech Description:
XSTR(
"Descriptive text...", -1)
$end_multi_text
$Model File: EMPulse2.pof
$Mass: 15.0
$Velocity: 275.0
$Fire Wait: 2.0
$Damage: 45
$Blast Force: 20.0
$Inner Radius: 80.0
$Outer Radius: 300.0
$Shockwave Speed: 120.0
$Armor Factor: 1.0
$Shield Factor: 0.8
$Subsystem Factor: 0.5
$Lifetime: 5.0
$Energy Consumed: 0.0
$Cargo Size: 4.0
$Homing: YES
+Type: ASPECT
+Turn Time: 1.0
+Min Lock Time: 2.0
+Lock Pixels/Sec: 70
+Catch-up Pixels/Sec: 100
+Catch-up Penalty: 30
$LaunchSnd: 118
$ImpactSnd: 88
$FlyBySnd: -1
$Rearm Rate: 2.0
$Flags: ( "player allowed"
"EMP")
$Trail:
+Start Width: 0.25
+End Width: 0.75
+Start Alpha: 1.0
+End Alpha: 0.0
+Max Life: 1.5
+Bitmap: MissileTrail04
$Icon: iconEMPulse
$Anim: ecm
$Impact Explosion: ExpMissileHit1
$Impact Explosion Radius: 10.0
$EMP Intensity: 375.0
$EMP Time: 20.0

#End

$Player Weapon Precedence: (
"Subach HL-7"
"EMP Adv." )
</pre>

[[Category:Tables]]

Subsystem

2021-02-28T13:49:05Z

M!m: Added $On Beam Warmdown:

{{Fileversion|7119}}

*All subsystems ship can have must be defined in ships model file (.pof).

{{Table3610|
*[[Animation_Code|Animation Code]] can be applied to the subsystems that consist of submodels, like multi-part turrets.}}

==$Subsystem:==
*The name of the subsystem as defined in .pof file, % of ship's total hitpoints the subsystem has and rotation time (360 degrees) for multi-part turrets. Note: Assigning zero to the %-hitpoint entry causes the subsystem to be without hitpoints, like fighterbays on some capital ships.
*Syntax: '''''String''''', '''''Float''''', '''''Float''''', name of the subsystem followed by the subsystem hitpoints as % of ships hitpoints and seconds per 360 degree turn. Subsystem name must be the same as described in model file (.pof).
{{Table3610|
*Entries can be left empty in which case game uses default values}}
**Example: communications, 5, 0.0

===$Alt Subsystem Name:===
{{Table3610|
*Defines the alternate name for the subsystem. This name is shown for example in the targeting window when subsystem is targeted.
*Syntax: '''''String'''''}}
{{Table3611|
*Option to use pipe character '<nowiki>|</nowiki>' to force line breaks into the alt subsystem name}}

===$Alt Damage Popup Subsystem Name:===
{{Table3611|
*Defines the alternate name for the subsystem when it is displayed on the '''damaged systems''' popup.
*Syntax: '''''String'''''}}

===$Armor Type:===
{{Table3610|
* '''REQUIRES ADDITIONAL TABLE'''. Defines armor type used for the subsystem. If subsystem armor type is not defined ships armor type is used instead.
* Syntax: '''''String''''', as defined in [[armor.tbl]]}}

===$Default PBanks:===
*Defines default primary weapon for the turret
*Syntax: ( '''''"String"''''' )
**Example: ( ''"Subach HL-7"'' )

===$PBank Capacity:===
{{Table3610|
*Defines ammunition capacity of turrets ballistic primary weapon.
*Syntax: ( '''''Integer''''' )}}

===$Default SBanks:===
*Defines default secondary weapon for the turret
*Syntax: ( '''''"String"''''' )

===$SBank Capacity:===
*Defines ammunition capacity of turrets secondary weapon.
*Syntax: ( '''''Integer''''' )

===$Engine Wash:===
*All engines may use information concerning the engine wash. Engine washes are usually used only with larger vessels.
*Syntax: '''''String''''', name as defined in Engine Wash section in [[ships.tbl]]
**Example: ''Default1000''

===$AliveSnd:===
{{Table3610|
*Specifies a sound to play from the subsystem while it is not destroyed.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$DeadSnd:===
{{Table3610|
*Specifies a sound to play from the subsystem while it is destroyed.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$RotationSnd:===
{{Table3613|
*Can be used to define a sound that is played when this subsystem rotates.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$Turret Base RotationSnd:===
{{Table3611|
*Defines the sound which is played when the turrets base rotates
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$Turret Gun RotationSnd:===
{{Table3611|
*Defines the sound which is played when the turrets guns change their elevation
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$Turret BaseSnd Volume:===
{{Table3611|
*Defines the multiplier for the sound volume for turret base rotations
*Syntax: '''''Float'''''}}

===$Turret GunSnd Volume:===
{{Table3611|
*Defines the multiplier for the sound volume for turret guns change their elevation
*Syntax: '''''Float'''''}}

===$AWACS:===
*Sets this subsystem's effective AWACS range. (AWACS reveals stealthed ships, cuts through nebula fog.)
*Syntax: '''''Float''''', the maximum range of the AWACS

===$Maximum Barrel Elevation:===
{{Table3611|
*Defines the maximum barrel elevation for the turret
*Basically 'inverse FOV'.
*Syntax: '''''Integer''''', from 0 to 90}}

===$Turret Base FOV:===
{{Table3611|
*Defines the FOV of the turret's base.
*Syntax: '''''Integer''''', from 0 to 359}}

===$Turret Reset Delay:===
{{Table3611|
*Defines the time after losing the target before the turret begins to reset itself
*Syntax: '''''Integer''''', in milliseconds}}

===$Turret Optimum Range:===
{{Table3611|
*Defines the optimum range for the turret
*Syntax: '''''Float'''''}}

===$Turret Direction Preference:===
{{Table3611|
*Defines the turrets preference to keep targeting targets based how far the turret should turn instead of nearest target
*The higher the value the higher the preference to keep targeting targets close to previous targets direction
*Syntax: '''''Integer''''', from 0 to 100, 0 disables the preference setup}}

===$Target Priority:===
{{Table3611|
*Defines the target priorities, and their order for the turret
*Syntax: '''''String list'''''}}

===$Max Turrets per Bomb:===
{{Table3613|
*Limits the number of turrets that can be targeting the same bomb.
*When this is set, when this turret tries to target a bomb, it will check to see how many turrets are already targeting it and only choose it as a target if there are less than this number.
*This allows control over the default behavior, where every turret will fire at the leading bomb.
*Syntax: '''''Integer'''''}}

===$Max Turrets per Target:===
{{Table3613|
*Limits the number of turrets that can be targeting the same target.
*'''ONLY AFFECTS SMALL TARGETS''' such as fighters and bombers. This limit does '''NOT''' apply vs large ships.
*When this is set, when this turret tries to target a ship, it will check to see how many turrets are already targeting it and only choose it as a target if there are less than this number.
*This helps turrets spread their efforts out among multiple targets.
*Syntax: '''''Integer'''''}}

===$ROF:===
{{Table3613|
*Defines the modifier applied to the turret rate of fire (ROF).

====+Use firingpoints====
*Modifies (multiplies) the rate of fire by the number of firingpoints the turret has.

====+Multiplier:====
*Checked only if ''+Use firingpoints'' has not been defined
*If set to larger than 0 the value acts as multiplier
*If set to 1.0 the feature is disabled
*If set to equal to or smaller than 0 it as if ''+Use firingpoints'' option would have been enabled
*Syntax: '''''Float'''''}}

===$Flags:===
{{Table3610|
*Can be used to sets additional subsystem related properties
*Syntax: ( '''''"String" "String"''''' )
*List of available flags:

===="untargetable"====
*Subsystem cannot be targeted

===="carry no damage"====
*Damage caused to the subsystem will not carry over to the parent ship

===="use multiple guns"====
*Enables the turret to fire all equipped weapons, picking a not-in-use firing point at each trigger. Not to be confused with 'Salvo mode'.

===="fire down normals"====
*Forces the turret to fire along the turret normals - regardless of the swarm setting.

===="check hull"====
*Forces the firing turret to check against the parent model if valid line of sight exists between the firingpoint and the target.}}

{{Table3611|
===="fixed firingpoints"====
*Forces the firing turret to retain the firingpoints of their weapons: if the turret has multiple banks, the first bank will only fire from the first firepoint, the second bank only from the second firepoint, and so on. Maximum number of weapons is the same as maximum number of weapons in turret (3 primary, 4 secondary)

===="salvo mode"====
*Forces the firing turret to use only the first weapon defined for it but fires it simultaneously from all the firing points. Not to be confused with 'use multiple guns'

===="no subsystem targeting"====
*Prevents the firing turret from targeting targets subsystems - instead forces the turret to fire randomly at the targets hull.

===="fire on target"====
*Prevents the turret from firing unless the turret barrels (firingpoints) and targets are aligned.

===="reset when idle"====
*Forces the turret to reset to its initial position if it has no targets.

===="carry shockwave"====
*Forces the turret to carry damage caused by shockwaves to the hull regardless of other flags.}}

{{Table3613|
===="allow landing"====
*Defines the subsystem as something on which player can attempt to land on

===="target requires fov"====
*Prevents turret from accidentally selecting target out of it field of view (fov) when acquiring targets

===="fov edge checks"====
*If the predicted target point of the turret falls outside of the field of view this flag but according to ship radius and dot product the target should still be partially visible then this flag attempts to turn the turret to the edge of the FOV closest to the targeted position and allow it to fire along that direction.

===="no replace"====
*Tells game not to use the replacement submodel (-destroyed) when the subsystem loses all of it's hitpoints.

===="no live debris"====
*Prevents the subsystem from releasing live debris pieces when destroyed

===="ignore if dead"====
*When subsystem has been destroyed prevents homing weapons from attempting to hit the now destroyed submodel and instead tells them to home on the main hull of the target

===="allow vanishing"====
*Allow subsystem to be destroyed from the ship without sound or graphical effects

===="damage as hull"====
*Treats subsystem as if it were hull when applying damage.

===="starts locked"====
*Turret starts locked and won't shoot until you use a turret-free or turret-free-all SEXP on it.

===="no aggregate"====
*Freespace keeps track of a ships overall functionality (such as if a ship is sensorless, disarmed or disabled) via a total hitpoint count of the associated subsystems. For example if a ship has three engines with 100HP each, the 'engines' count will be at 300HP. Shooting at any of the subsystems with the keyword 'engine' in them will decrement this total, and when it is at 0 then the ship becomes disabled.
*This flag tells FS to ignore the associated subsystem and not count it towards those totals. For example, if a ship had three 100HP engines with one set to 'no aggregate' then the 'engines' count will be 200HP. Shooting the 'no aggregate' engine will not decrement the 'engines' count, and so in other words the status of this engine is irrelevant to whether or not the ship is disabled. In the same way when applied to a turret, the turret's status is irrelevant to whether the ship is disarmed or not.

===="wait for animation"====
*When this flag is active, a turret will only fire after any associated subsystem animations (such as a turret hatch opening) have played out.

===="play fire sound for player"====
*If this turret is on a player ship, play its associated sounds.

===="only target if can fire"====
*Do additional checks to make sure that a turret which cannot fire at its target releases that target.
}}

{{Table3615|
===="no disappear"====
*If this subsystem is a physical subsystem, it won't disappear nor switch to the -destroyed model when destroyed.

===="collide submodel"====
*If this subsystem is a physical subsystem, it will only take damage from hits which impact the submodel. By default damage is taken from all hits within the submodel's radius*2. Does not affect area damage such as shockwaves.

===="allow destroyed rotation"====
*Allows a rotating subobject to continue to rotate even when it has been destroyed
}}

{{Table373|
===="turret use ammo"====
*If the subsystem is a turret, it will use ammo.
**Note: If the turret does not have ammo, it will not fire. Remember that the maximum ammo a turret can hold is the Capacity of the Bank divided by the Cargo Size of the weapon.

===="share fire direction"====
*If this subsystem is a turret, whenever the turret fires it will make all of the firing points shoot their weapon in the same direction instead of at the same point or set of points on a target.
}}

{{Table381|
===="no damage spew"====
*If this subsystem is hit then there will be no damage spew particles emitted.

===="no impact debris"====
*If this subsystem is hit then no impact debris will be generated.
}}

===[[Animation Code]]===
{{Table3610|
*Option for animating the submodels}}

===$On Beam Warmdown:===
{{Table212|
Specifies an [[Action System|action system]] program set to be executed when a beam attached to this subsystem is starting its warmdown sequence.
}}

==Case Specific Entries==

===Turret===
*All turrets require information concerning the weapon mounted to the turret. The entry can be either '''$Default PBanks''' for turret primaries (including beams) or '''$Default SBanks''' for turret secondaries
{{Table3610|
*[[Animation_Code#Setting_Turret_Angle|Animation Code]] can be used with multi-part turrets.
*Multiple defined weapons will all fire but the targeting is handled by the first weapon in the list. '''Multiple beams are not possible'''. All weapons alternate between the firingpoints of the turret so turrets do not need to have more than one weapon defined no matter how many barrels or firingpoints they have.}}

====Example====

<pre>
$Subsystem: turret01, 1.0, 1.0
$Default PBanks: ( "Terran Turret" )
</pre>

===Engine===

====Example====

<pre>
$Subsystem: engine01, 5.0, 0.0
$Engine Wash: Default1000
</pre>

[[Category:Tables]]

List of modding-related articles

2021-02-28T13:43:37Z

M!m: /* Tabling */

This is a '''list of articles related to modding''', including modeling, texturing, and conversion.

For information about mission design, see the [[Portal:FRED|FRED portal]].

For coding, see [[:Category:Source Code Project|the Source Code Project]] category.

==Modeling==
*[[Detail box]]
*[[Hierarchy]]
*[[Rampage's Post Modding Guide]]
*[[Subobject and subsystem properties]]
*[[Turret setup]]
*[[User-made Ships|List of user-made ships]]

===Applications===
*[[3D Studio Max]]
*[[Blender]]
*[[Lithium Unwrap]]
*[[Maja]]
*[[ModelView]]
*[[POF Constructor Suite]]
*[[POF Constructor Suite 2]]
*[[trueSpace]]

===Texturing===
*:''[[Texturing|Index]]''
*''[[Goober5000's Orion nameplate tutorial]]''

===Conversion===
*[[Blender to POF Conversions|Blender to POF conversion]]
*[[Collada Importer]]
*[[Styxx's POF Conversion plugin for 3D Studio Max]]

==[[Tables|Tabling]]==
:''[[:Category:Tables|List of table files]]''
*[[Animation Code|Animation code]]
*[[Tutorial - Beam Weapons|Beam weapon tutorial]]
*[[Modular Tables|Modular table]]
*[[Ship Templates|Ship template]]
*[[Subsystem]]
*[[Technical Terms and Definitions|Terminology]]
*[[Action System]]

==Miscellaneous==
*[[Custom HUD elements (basics)]]
*[[FS2 Data Structure|FreeSpace 2 data structure]]
*[[:Category:File Types|File types]]
*[[Five things you'll forget to do before you release]]
*[[Installing Mods for FS2 Open|Installing mods for FreeSpace 2 Open]]
*[[Karajorma's FreeSpace FAQ: General Questions]]
*[[mod.ini]]
*[[Squadron insignia]]
*[[User-made effects]]
**[[Lightspeed's Nebula Pack]]
*[[User-made music]]

===VP files===
*[[QuickVP]]
*[[VPMage]]
**[[Using VPMage]]
*[[VPmake]]

[[Category:Lists]]
[[Category:Modding|*]]

Action System

2021-02-28T13:43:32Z

M!m: Created page with "The dynamic action system is an SCP addition that provides a way for mods to create custom sequences of events that should happen when a certain event occurs. This system is d..."

The dynamic action system is an SCP addition that provides a way for mods to create custom sequences of events that should happen when a certain event occurs. This system is designed to be highly flexible to allow mods complete control over what effects to trigger and where to place them.

This page will describe the basic ideas behind the system and describe how to use it.

==Basic functionality==
The basic functionality of the action system is to take a list of "Actions" and execute them over the span of an arbitrary amount of game-frames. This allows a mod to specify quite complex operations without hard-coding that into the engine. Example:
<pre>
$On Beam Warmdown: ; This defines a "program" to run once a beam weapon has finished firing
; Timing for effects is important so this allows to delay the execution of the remaining actions by 5 (in-mission) seconds
+Wait: 5

; Some actions simply update some internal data which can be used by later actions
; This data will be kept until it is set again and can be used by an unlimited number of actions
+Set Position: (8.0 0.0 0.0)
+Set Direction: (1.0 -1.0 1.0)

; All positions and directions are local to the attached subobject (turret02 in this case) and will respect animations

; These actions actually cause some external "thing" by using the previously set "local" data
+Start Particle Effect: "Beam Warmdown Effect"
+Play 3D Sound: "18"

+Set Position: locals.position + (3.0 0.0 0.0)
+Start Particle Effect: "Beam Warmdown Effect"

+Wait: 3.0

; Programs are attached to the object that triggered them so if the object dies before this can run then the sound will not be played
; The position is still (8, 0, 0) from the previous setting so no need to set it here again
+Play 3D Sound: "19" ; Actions can be used multiple times with different parameters
</pre>

This sequence of actions will be called a "program" in this document. When the corresponding event is triggered, the program is started which creates a "program instance". Every instance of a program is completely separate from each other and will also execute concurrently. This means that a "+Wait:" instruction in one program will not have any effect on another program wanting to trigger a sound effect or something similar.

When a program is started it will have some parameters specified at that point. These parameters are used for attaching an action to a specific object and subobject depending on where it has been triggered. A program attached to an object will only execute for as long as that object is present in the mission and will be stopped once the object is gone. If a program instance is attached to a subobject then all operations will be local to that subobject. Offsets and directions specified in actions will be relative to the selected subobject. However, a program instance will not be stopped if a subobject is destroyed.

In tables, an action option ("$On Beam Warmdown:" in the above example) can also be used several times in sequence. This will collect all those programs and when the event is triggered, every program is started at the same time with the same parameters. This allows to separate different effects into their own programs in order to make management of these actions a bit easier.

==Action expressions==
The value used for actions ("locals.position + (3.0 0.0 0.0)" for "+Set Position: locals.position + (3.0 0.0 0.0)" above) is a so called "Action expression". This is a simple language for expressing mathematical expressions which is used for every parameter of an action. The language follows the usual mathematical rules with some special parts that will be described here.

*'''~(<left> <right>)''': Will evaluate to a random value uniformly distributed without the range between <left> and <right>.
*'''"<name>"''': Is a string value. This is necessary for actions taking names of other tables as parameters. For example "+Start Particle Effect".
*'''(<x> <y> <z>)''': Will create a 3D vector value. Used for positions and directions. Each of the x, y, and z values can themselves be expressions again.

===Variables===
Every program instance will have some "local" variables assigned to it. This is a set of values that can be changed by the program and used by other actions for altering their behavior. These values are available within expressions:
*'''locals.position''': A vector value specifying an offset from the host of the program instance. Can be changed with "+Set Position".
*'''locals.direction''': A vector value specifying a direction. Can be changed with "+Set Direction".

==Available actions==
All of these listed actions can generally be combined freely with each other.

===+Wait:===
Will delay the execution of subsequent actions by the specified amount of in-game seconds.

'''Parameter type:''' ''Floating point number''

===+Set Position:===
Will alter the value of "locals.position" to the specified value.

'''Parameter type:''' ''3D Vector''

===+Set Direction:===
Will alter the value of "locals.direction" to the specified value.

'''Parameter type:''' ''3D Vector''

===+Move To Subobject:===
Will alter what subobject the program instance is attached to. A value of "<parent>" will move to the parent subobject of the current one. Otherwise the name of any other subobject may be specified.

'''Parameter type:''' ''String'' "<none>" or a valid subobject name.

===+Start Particle Effect:===
Triggers a [[Particle Effects|particle effect]] with the specified name. Will use "locals.position" as an offset and "locals.direction" to orient the effect.

'''Parameter type:''' ''String'' The name of a particle effect to trigger.

===+Play 3D Sound:===
Plays the specified 3D sound. Will use "locals.position" as an offset to compute the global position of the sound.

'''Parameter type:''' ''String'' The name of the sound as specified in [[Sounds.tbl]]

Scripting

2020-08-08T09:18:16Z

M!m: Added link to debugging guide

{{SCP_table}}

Scripting allows a modder to run custom code in the engine that can read and modify the game state to produce new features.

Scripts are either specified via [[Scripting.tbl]] or as standalone lua files.

==General Info==
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Useful references==
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[[Debugging Lua scripts]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.1/ Reference manual for Lua 5.1]'''

==Standalone Lua scripts==
Since writing Lua scripts using the table can lead to some issues while developing scripts (such as wrong syntax highlighting or wrong line numbers in error messages) the engine also supports loading Lua scripts directly and executing them when the initial game data has been loaded. Since that alone does not allow to register hooks, there is a scripting API that allows to do that from Lua code. See engine.addHook in scripting.html.

This allows to write a non-trivial script without using the global namespace which always risks contamination by other other scripts writing to the same global variables. Since the hook functions are defined in the same file as the other hook functions they can use the ''local'' variables declared in the top level scope without having to expose them to the global namespace.

==Basics==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

==Asynchronous operations==
{{Table382| This feature is currently only available in nightly builds.}}
As already laid out in the previous sections, Lua code is executed ''synchronously'' when the engine invokes a hook. That means that the engine will stop doing what it does, execute some Lua code and then continue on. However, if you want to have some behaviour happen over multiple frames (e.g. you want to smoothly move text from one side of the screen to the other) you have to break up that operation into multiple "On Frame" hooks calls and somehow restore the operation state in each hook call. This is bothersome and gets increasingly more complicated when scripts get more complex. For this reason, the scripting API supports the concept of "Promises" and ''asynchronous coroutines''. Let's look at Promises first since they are important for the coroutines.

===Promise===
''Promise'' is a JavaScript concept that exists in various other languages with various names but the basic idea is that it is a handle to a value that will be available in the future. For example, you could have a function that returns when a specific ship arrives in a mission and gives you a handle to that ship. Such a function could not be run synchronously since it would block the engine making it impossible for it to actually warp in that ship.

However, a function could return a promise that will ''resolve'' to the ship handle once that ship has arrived. Then a script could just register itself to be called when the promise has been resolved and not worry about keeping track of new arrivals via different hooks or something like that.

For this reason, promises has one important operation: "continueWith" (in JavaScript it would be "then" but that is a keywork in Lua). That function gets called with a function as its first parameter. This function will be called when the promise resolves with the resolve values as its parameters.

In addition to resolving, promises can also go into an "error" state. This means that whatever operation the promise represents has failed for some reason. In our example, ending the mission would also cause an error for the promise since it is impossible for a new ship to arrive in the mission we were in. This case can be handled with the "catch" function. Similar to "continueWith", you pass it a function but this will only be called when the promise ends in an error. The function returns another promise that will (successfully) resolve with the return value of the "catch" function so you can handle an error in a promise and still continue.

===Asynchronous Coroutines===
A normal function has a very strict life cycle. It gets called, does some stuff, and then returns a value. A coroutine expands that concept by allowing the function to "suspend" at certain points in its runtime. Then the calling function can "resume" the coroutine at a later point until the function is actually finished and reaches a "return" statement. This is a very common concept in several programming languages but Lua has built-in support for that. That covers the "Coroutine" part. Now let's look at the asynchronous part.

Consider again our promise from above where we want to wait for a ship to arrive. What we want to do is to apply some battle damage to the ship once it arrives. However, this ship isn't here yet. We could use the "continueWith" function from the returned promise but that is a bit bothersome expecially if you have some more complicated control flow. Instead, we can use our coroutines to start a function, maybe do some setup, and then "suspend" until the promise resolves:
<pre>
async.run(function()
mn.sendPlainMessage("Waiting for GTVA Collosus")

local ship = async.await(mn.waitForShipAsync("GTVA Collosus"))

applyBattleDamage(ship)
end)
</pre>
There are two interesting functions here. ''async.run'' and ''async.await''. ''async.run'' will execute the specified function as a Lua coroutine and return a promise that will resolve with the return value of the function or error out if one of the awaited promises returns an error.

''async.await'' takes a promise as its parameter and uses the coroutine character of the function and suspends the function until the promise resolves or causes an error. It will then resume the function an return the resolve value of the promise. This way, we can write code that looks just like normal synchronous code but still do stuff across several frames.

===Advanced promise features===
These coroutines are a very powerful feature but without anything to produce promises it is not very helpful. The engine can maybe provide you with some functions that return coroutines but the point of Lua is to allow modders to do their own thing. For this reason, there is the basic building block ''async.promise''. This function can create a promise for which the Lua code can determine when it resolves or errors. To do this, you pass ''async.promise'' a function that takes up to two parameters. Both parameters will be functions. Calling the first parameter ''resolve'' will resolve the original promise with the passed parameters. ''reject'' will similarly cause the promise to transition into the error state with the passed parameters as the error values.

This feature is very useful to "promisify" code that uses the "old" way of doing asynchronous operations since it allows to create the promise at one point and then store the resolve and reject functions so that they can be called at a later point.

For a more detailed and step by step guide on how this feature can be used, please see [[Tutorial:Custom Promises]].

[[Category:Modding]]

Debugging Lua scripts

2020-08-08T09:17:45Z

M!m: Created page with "When a script reaches a certain complexity it becomes more and more difficult to determine what exactly that script does. Finding errors can be done by using "ba.print" statem..."

When a script reaches a certain complexity it becomes more and more difficult to determine what exactly that script does. Finding errors can be done by using "ba.print" statements to log the values of certain variables at runtime but that is a crude way of figuring things out.

Fortunately, Lua provides some basic building blocks for implementing an interactive debugger where you can tell it to stop the program at a certain point, take a look at variable values, and stepping to the next execution line.

This page will explain how to set that up for debugging Lua script in FSO.

== EmmyLua ==
This is a useful suite of plugins that allows both to do interactive debugging and having enhanced code assistance if configured correctly. There are two variants, one for the IntelliJ family of IDEs and one for VisualStudio Code.

=== IntelliJ plugin ===
Installing the plugin is as easy as going to the plugin page in the settings and searching for "EmmyLua". Restart the IDE and you are good to go.

==== Project setup ====
Select the "EmmyLua" type under the "Other" section and enter the path to your mod folder:

[[File:EmmyLua_NewProject.png]]

That is enough and you should now see your mod project including your scripts. Since EmmyLua has no idea about our special scripting tables, this would be a good point to either use a standalone script file or to separate your script into a Lua module so that you can work with pure .lua files.
EmmyLua can also use the API definitions generated by FSO to give you more assistance with the FSO scripting API. Simply use the tool from [https://www.hard-light.net/forums/index.php?topic=96658.0 this thread] to generate the API definition for the plugin to use.

==== Debugging setup ====
Now that you have your project, you can click "Add configurations..." in the top left corner. Click the small "+" and select "Emmy Debugger(NEW)" (name might have changed by the time you read this but it should still be similar):

[[File:EmmyLua DebuggerSetup.png]]

The two relevant items here are the "Connection" value and the script the IDE shows you. Since the debugger works by doing some (local) network communication you need to specify in which order the debugger and FSO will be launched. If you select "Tcp (IDE connect debugger)" then you need to launch FSO first and then launch the debugging session. "Tcp (Debugger connect IDE)" is the reverse, there you first need to launch the debugger configuration and then launch FSO. Choose whichever works better for you. For advanced users, you can also create a combined launch configuration that automatically launches FSO as well but that will not be covered here.

Now that you have chosen, simply copy the script the IDE displays to you and place it as "zzzdebugger-sct.lua" in your data/tables folder. The weird name ensures that the script will be executed first before any other script and will allow you to debug all Lua code that you have in your mod. Please not that this script is specific to your machine and will also break your mod if there is no debugger on the system so it should neither be checked into Git/SVN (if you have that) or included in the final mod release.

And now you are done. Set breakpoints where you would like the debugger to halt. Breakpoints can be placed by clicking to the right of the line numbers and a visual indicator will show that a breakpoint now exists there and if your script reaches that point execution will suspend and you can look at both local and global variables.

File:EmmyLua DebuggerSetup.png

2020-08-08T09:08:28Z

M!m:

File:EmmyLua NewProject.png

2020-08-08T08:01:39Z

M!m:

Scripting

2020-05-29T20:54:59Z

M!m:

{{SCP_table}}

Scripting allows a modder to run custom code in the engine that can read and modify the game state to produce new features.

Scripts are either specified via [[Scripting.tbl]] or as standalone lua files.

==General Info==
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Useful references==
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.1/ Reference manual for Lua 5.1]'''

==Standalone Lua scripts==
Since writing Lua scripts using the table can lead to some issues while developing scripts (such as wrong syntax highlighting or wrong line numbers in error messages) the engine also supports loading Lua scripts directly and executing them when the initial game data has been loaded. Since that alone does not allow to register hooks, there is a scripting API that allows to do that from Lua code. See engine.addHook in scripting.html.

This allows to write a non-trivial script without using the global namespace which always risks contamination by other other scripts writing to the same global variables. Since the hook functions are defined in the same file as the other hook functions they can use the ''local'' variables declared in the top level scope without having to expose them to the global namespace.

==Basics==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

==Asynchronous operations==
{{Table382| This feature is not yet available in FSO builds and is still in code review.}}
As already laid out in the previous sections, Lua code is executed ''synchronously'' when the engine invokes a hook. That means that the engine will stop doing what it does, execute some Lua code and then continue on. However, if you want to have some behaviour happen over multiple frames (e.g. you want to smoothly move text from one side of the screen to the other) you have to break up that operation into multiple "On Frame" hooks calls and somehow restore the operation state in each hook call. This is bothersome and gets increasingly more complicated when scripts get more complex. For this reason, the scripting API supports the concept of "Promises" and ''asynchronous coroutines''. Let's look at Promises first since they are important for the coroutines.

===Promise===
''Promise'' is a JavaScript concept that exists in various other languages with various names but the basic idea is that it is a handle to a value that will be available in the future. For example, you could have a function that returns when a specific ship arrives in a mission and gives you a handle to that ship. Such a function could not be run synchronously since it would block the engine making it impossible for it to actually warp in that ship.

However, a function could return a promise that will ''resolve'' to the ship handle once that ship has arrived. Then a script could just register itself to be called when the promise has been resolved and not worry about keeping track of new arrivals via different hooks or something like that.

For this reason, promises has one important operation: "continueWith" (in JavaScript it would be "then" but that is a keywork in Lua). That function gets called with a function as its first parameter. This function will be called when the promise resolves with the resolve values as its parameters.

In addition to resolving, promises can also go into an "error" state. This means that whatever operation the promise represents has failed for some reason. In our example, ending the mission would also cause an error for the promise since it is impossible for a new ship to arrive in the mission we were in. This case can be handled with the "catch" function. Similar to "continueWith", you pass it a function but this will only be called when the promise ends in an error. The function returns another promise that will (successfully) resolve with the return value of the "catch" function so you can handle an error in a promise and still continue.

===Asynchronous Coroutines===
A normal function has a very strict life cycle. It gets called, does some stuff, and then returns a value. A coroutine expands that concept by allowing the function to "suspend" at certain points in its runtime. Then the calling function can "resume" the coroutine at a later point until the function is actually finished and reaches a "return" statement. This is a very common concept in several programming languages but Lua has built-in support for that. That covers the "Coroutine" part. Now let's look at the asynchronous part.

Consider again our promise from above where we want to wait for a ship to arrive. What we want to do is to apply some battle damage to the ship once it arrives. However, this ship isn't here yet. We could use the "continueWith" function from the returned promise but that is a bit bothersome expecially if you have some more complicated control flow. Instead, we can use our coroutines to start a function, maybe do some setup, and then "suspend" until the promise resolves:
<pre>
async.run(function()
mn.sendPlainMessage("Waiting for GTVA Collosus")

local ship = async.await(mn.waitForShipAsync("GTVA Collosus"))

applyBattleDamage(ship)
end)
</pre>
There are two interesting functions here. ''async.run'' and ''async.await''. ''async.run'' will execute the specified function as a Lua coroutine and return a promise that will resolve with the return value of the function or error out if one of the awaited promises returns an error.

''async.await'' takes a promise as its parameter and uses the coroutine character of the function and suspends the function until the promise resolves or causes an error. It will then resume the function an return the resolve value of the promise. This way, we can write code that looks just like normal synchronous code but still do stuff across several frames.

===Advanced promise features===
These coroutines are a very powerful feature but without anything to produce promises it is not very helpful. The engine can maybe provide you with some functions that return coroutines but the point of Lua is to allow modders to do their own thing. For this reason, there is the basic building block ''async.promise''. This function can create a promise for which the Lua code can determine when it resolves or errors. To do this, you pass ''async.promise'' a function that takes up to two parameters. Both parameters will be functions. Calling the first parameter ''resolve'' will resolve the original promise with the passed parameters. ''reject'' will similarly cause the promise to transition into the error state with the passed parameters as the error values.

This feature is very useful to "promisify" code that uses the "old" way of doing asynchronous operations since it allows to create the promise at one point and then store the resolve and reject functions so that they can be called at a later point.

For a more detailed and step by step guide on how this feature can be used, please see [[Tutorial:Custom Promises]].

[[Category:Modding]]

Tutorial:Custom Promises

2020-05-29T20:54:54Z

M!m: Created page with "This tutorial will walk you through using ''async.promise'' for creating promises from Lua code so that you can await custom conditions in ''async.run''. A relatively common..."

This tutorial will walk you through using ''async.promise'' for creating promises from Lua code so that you can await custom conditions in ''async.run''.

A relatively common operation in missions is to have an event happen when a ship has arrived in mission. This could be done via very complicated usages of the "On Warp In" hook that involve a lot of global variables. However, here we will create a [https://www.tutorialspoint.com/lua/lua_modules.htm Lua Module] that exposes the function "waitForShipAsync(ship_name)" that returns a promise which resolves to the ship handle when the specified ship has arrived in the mission or errors when the mission has ended. So, let's start with a simple template that exposes exactly that function:
<pre>
local module = {}

function module.waitForShipAsync(ship_name)
end

return module
</pre>
Not very useful but a good start nonetheless. If you save this as "missionPromise.lua" in your "scripts" folder it will be available for use with ''require''.
For the rest of the tutorial we will be using the same main script so you can save this as ''tutorial-sct.lua'' in your "tables" folder.
<pre>
local mnProm = require("missionPromise")

engine.addHook("On Gameplay Start", function()
async.run(function()
mn.sendPlainMessage("Start of the coroutine!")

local ship = async.await(mnProm.waitForShipAsync("TestShip"))

mn.sendPlainMessage("Ship has arrived! Name: " .. ship.Name)
end)
end)
</pre>
Since you will also need a mission to test this in you can use this [https://gist.github.com/asarium/3678172e71a522b5e07e26ee347cd81e#file-async_test-fs2 simple test mission] that has a few ships set up that will arrive when either "1" or "2" is pressed.

If you run this now it will immediately cause a Lua error since ''waitForShipAsync'' does not return a value yet which is not accepted by async.await. Since this is about ''async.promise'' let's call it and see what happens:
<pre>
function module.waitForShipAsync(ship_name)
return async.promise(function(resolve, reject) end)
end
</pre>
This will now no longer cause an error upon starting a mission. However, you will also never see the "Ship has arrived!" message since the promise that is waited on will never resolve. To see something happen let's make a small change to the module function:
<pre>
function module.waitForShipAsync(ship_name)
return async.promise(function(resolve, reject)
resolve(hv.Player)
end)
end
</pre>
When you start the mission now you will immediately see the message "Ship has arrived! Name: Alpha 1".
So, we now have a function that returns a promise which will immediately resolve to the player ship handle. However, that is not the handle to the correct ship since we expect to get a handle to "TestShip".

Next, we need to add an engine hook for when a ship has arrived in the mission since that is exactly the event we want to wait for. This can be done with ''engine.addHook''. You pass as the first parameter the name of the hook and a function that will be executed on that hook as the second parameter:
<pre>
engine.addHook("On Warp In", function()
end)

function module.waitForShipAsync(ship_name)
return async.promise(function(resolve, reject)
resolve(hv.Player)
end)
end
</pre>
In this hook we can check ''hv.Self'' to get a handle of the ship that is arriving. What we want to happen in that function is that if we have created a promise before this point with the ''ship_name'' set to the same value as the name of the arriving ship, we want to resolve that promise. The actual way we want to do that is to actually save the ''resolve'' callback we got in the promise constructor:
<pre>
local arrivalListeners = {}
engine.addHook("On Warp In", function()
end)

function module.waitForShipAsync(ship_name)
return async.promise(function(resolve, reject)
arrivalListeners[ship_name] = resolve -- <--
end)
end
</pre>
We now have ''arrivalListeners'' as a table which maps ship name to the desired resolve function. In the warp in hook we can now simply check if we have a pending promise for that ship name and if so, resolve it:
<pre>
engine.addHook("On Warp In", function()
local resolver = arrivalListeners[hv.Self.Name]

if resolver then
resolver(hv.Self)
end
end)
</pre>
Try it out now. If you press "1" in the mission you will see "Ship has arrived! Name: TestShip".

That is it. You just created your first promise!

That code will work reasonably well but will break in subtle ways when used a bit more extensively. For example, if two coroutines want to wait for the same ship, only one will be notified since the previous resolve function will be overwritten. Also, if a ship has already arrived then the function will never resolve since we will never see the "On Warp In" event. Here is a [https://gist.github.com/asarium/3678172e71a522b5e07e26ee347cd81e#file-missionpromiseextended-lua "production ready"] version of this script that will handle these edge cases properly. It will also cause the promises to reject when the mission ends so that promises waiting for ships that will never arrive do not stick around forever.

Thank you for joining this tutorial! If you have any questions, don't hesitate to ask them either on discord in the #scp channel or in the scripting subforum.

Scripting

2020-05-24T19:57:21Z

M!m:

{{SCP_table}}

Scripting allows a modder to run custom code in the engine that can read and modify the game state to produce new features.

Scripts are either specified via [[Scripting.tbl]] or as standalone lua files.

==General Info==
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Useful references==
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.1/ Reference manual for Lua 5.1]'''

==Standalone Lua scripts==
Since writing Lua scripts using the table can lead to some issues while developing scripts (such as wrong syntax highlighting or wrong line numbers in error messages) the engine also supports loading Lua scripts directly and executing them when the initial game data has been loaded. Since that alone does not allow to register hooks, there is a scripting API that allows to do that from Lua code. See engine.addHook in scripting.html.

This allows to write a non-trivial script without using the global namespace which always risks contamination by other other scripts writing to the same global variables. Since the hook functions are defined in the same file as the other hook functions they can use the ''local'' variables declared in the top level scope without having to expose them to the global namespace.

==Basics==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

==Asynchronous operations==
{{Table382| This feature is not yet available in FSO builds and is still in code review.}}
As already laid out in the previous sections, Lua code is executed ''synchronously'' when the engine invokes a hook. That means that the engine will stop doing what it does, execute some Lua code and then continue on. However, if you want to have some behaviour happen over multiple frames (e.g. you want to smoothly move text from one side of the screen to the other) you have to break up that operation into multiple "On Frame" hooks calls and somehow restore the operation state in each hook call. This is bothersome and gets increasingly more complicated when scripts get more complex. For this reason, the scripting API supports the concept of "Promises" and ''asynchronous coroutines''. Let's look at Promises first since they are important for the coroutines.

===Promise===
''Promise'' is a JavaScript concept that exists in various other languages with various names but the basic idea is that it is a handle to a value that will be available in the future. For example, you could have a function that returns when a specific ship arrives in a mission and gives you a handle to that ship. Such a function could not be run synchronously since it would block the engine making it impossible for it to actually warp in that ship.

However, a function could return a promise that will ''resolve'' to the ship handle once that ship has arrived. Then a script could just register itself to be called when the promise has been resolved and not worry about keeping track of new arrivals via different hooks or something like that.

For this reason, promises has one important operation: "continueWith" (in JavaScript it would be "then" but that is a keywork in Lua). That function gets called with a function as its first parameter. This function will be called when the promise resolves with the resolve values as its parameters.

In addition to resolving, promises can also go into an "error" state. This means that whatever operation the promise represents has failed for some reason. In our example, ending the mission would also cause an error for the promise since it is impossible for a new ship to arrive in the mission we were in. This case can be handled with the "catch" function. Similar to "continueWith", you pass it a function but this will only be called when the promise ends in an error. The function returns another promise that will (successfully) resolve with the return value of the "catch" function so you can handle an error in a promise and still continue.

===Asynchronous Coroutines===
A normal function has a very strict life cycle. It gets called, does some stuff, and then returns a value. A coroutine expands that concept by allowing the function to "suspend" at certain points in its runtime. Then the calling function can "resume" the coroutine at a later point until the function is actually finished and reaches a "return" statement. This is a very common concept in several programming languages but Lua has built-in support for that. That covers the "Coroutine" part. Now let's look at the asynchronous part.

Consider again our promise from above where we want to wait for a ship to arrive. What we want to do is to apply some battle damage to the ship once it arrives. However, this ship isn't here yet. We could use the "continueWith" function from the returned promise but that is a bit bothersome expecially if you have some more complicated control flow. Instead, we can use our coroutines to start a function, maybe do some setup, and then "suspend" until the promise resolves:
<pre>
async.run(function()
mn.sendPlainMessage("Waiting for GTVA Collosus")

local ship = async.await(mn.waitForShipAsync("GTVA Collosus"))

applyBattleDamage(ship)
end)
</pre>
There are two interesting functions here. ''async.run'' and ''async.await''. ''async.run'' will execute the specified function as a Lua coroutine and return a promise that will resolve with the return value of the function or error out if one of the awaited promises returns an error.

''async.await'' takes a promise as its parameter and uses the coroutine character of the function and suspends the function until the promise resolves or causes an error. It will then resume the function an return the resolve value of the promise. This way, we can write code that looks just like normal synchronous code but still do stuff across several frames.

===Advanced promise features===
These coroutines are a very powerful feature but without anything to produce promises it is not very helpful. The engine can maybe provide you with some functions that return coroutines but the point of Lua is to allow modders to do their own thing. For this reason, there is the basic building block ''async.promise''. This function can create a promise for which the Lua code can determine when it resolves or errors. To do this, you pass ''async.promise'' a function that takes up to two parameters. Both parameters will be functions. Calling the first parameter ''resolve'' will resolve the original promise with the passed parameters. ''reject'' will similarly cause the promise to transition into the error state with the passed parameters as the error values.

This feature is very useful to "promisify" code that uses the "old" way of doing asynchronous operations since it allows to create the promise at one point and then store the resolve and reject functions so that they can be called at a later point.

[[Category:Modding]]

Scripting

2020-05-24T19:56:34Z

M!m: Add initial documentation for asynchronous coroutines

{{SCP_table}}

Scripting allows a modder to run custom code in the engine that can read and modify the game state to produce new features.

Scripts are either specified via [[Scripting.tbl]] or as standalone lua files.

==General Info==
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Useful references==
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.1/ Reference manual for Lua 5.1]'''

==Standalone Lua scripts==
Since writing Lua scripts using the table can lead to some issues while developing scripts (such as wrong syntax highlighting or wrong line numbers in error messages) the engine also supports loading Lua scripts directly and executing them when the initial game data has been loaded. Since that alone does not allow to register hooks, there is a scripting API that allows to do that from Lua code. See engine.addHook in scripting.html.

This allows to write a non-trivial script without using the global namespace which always risks contamination by other other scripts writing to the same global variables. Since the hook functions are defined in the same file as the other hook functions they can use the ''local'' variables declared in the top level scope without having to expose them to the global namespace.

==Basics==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

==Asynchronous operations==
{{Table3614| This feature is not yet available in FSO builds and is still in code review.}}
As already laid out in the previous sections, Lua code is executed ''synchronously'' when the engine invokes a hook. That means that the engine will stop doing what it does, execute some Lua code and then continue on. However, if you want to have some behaviour happen over multiple frames (e.g. you want to smoothly move text from one side of the screen to the other) you have to break up that operation into multiple "On Frame" hooks calls and somehow restore the operation state in each hook call. This is bothersome and gets increasingly more complicated when scripts get more complex. For this reason, the scripting API supports the concept of "Promises" and ''asynchronous coroutines''. Let's look at Promises first since they are important for the coroutines.

===Promise===
''Promise'' is a JavaScript concept that exists in various other languages with various names but the basic idea is that it is a handle to a value that will be available in the future. For example, you could have a function that returns when a specific ship arrives in a mission and gives you a handle to that ship. Such a function could not be run synchronously since it would block the engine making it impossible for it to actually warp in that ship.

However, a function could return a promise that will ''resolve'' to the ship handle once that ship has arrived. Then a script could just register itself to be called when the promise has been resolved and not worry about keeping track of new arrivals via different hooks or something like that.

For this reason, promises has one important operation: "continueWith" (in JavaScript it would be "then" but that is a keywork in Lua). That function gets called with a function as its first parameter. This function will be called when the promise resolves with the resolve values as its parameters.

In addition to resolving, promises can also go into an "error" state. This means that whatever operation the promise represents has failed for some reason. In our example, ending the mission would also cause an error for the promise since it is impossible for a new ship to arrive in the mission we were in. This case can be handled with the "catch" function. Similar to "continueWith", you pass it a function but this will only be called when the promise ends in an error. The function returns another promise that will (successfully) resolve with the return value of the "catch" function so you can handle an error in a promise and still continue.

===Asynchronous Coroutines===
A normal function has a very strict life cycle. It gets called, does some stuff, and then returns a value. A coroutine expands that concept by allowing the function to "suspend" at certain points in its runtime. Then the calling function can "resume" the coroutine at a later point until the function is actually finished and reaches a "return" statement. This is a very common concept in several programming languages but Lua has built-in support for that. That covers the "Coroutine" part. Now let's look at the asynchronous part.

Consider again our promise from above where we want to wait for a ship to arrive. What we want to do is to apply some battle damage to the ship once it arrives. However, this ship isn't here yet. We could use the "continueWith" function from the returned promise but that is a bit bothersome expecially if you have some more complicated control flow. Instead, we can use our coroutines to start a function, maybe do some setup, and then "suspend" until the promise resolves:
<pre>
async.run(function()
mn.sendPlainMessage("Waiting for GTVA Collosus")

local ship = async.await(mn.waitForShipAsync("GTVA Collosus"))

applyBattleDamage(ship)
end)
</pre>
There are two interesting functions here. ''async.run'' and ''async.await''. ''async.run'' will execute the specified function as a Lua coroutine and return a promise that will resolve with the return value of the function or error out if one of the awaited promises returns an error.

''async.await'' takes a promise as its parameter and uses the coroutine character of the function and suspends the function until the promise resolves or causes an error. It will then resume the function an return the resolve value of the promise. This way, we can write code that looks just like normal synchronous code but still do stuff across several frames.

===Advanced promise features===
These coroutines are a very powerful feature but without anything to produce promises it is not very helpful. The engine can maybe provide you with some functions that return coroutines but the point of Lua is to allow modders to do their own thing. For this reason, there is the basic building block ''async.promise''. This function can create a promise for which the Lua code can determine when it resolves or errors. To do this, you pass ''async.promise'' a function that takes up to two parameters. Both parameters will be functions. Calling the first parameter ''resolve'' will resolve the original promise with the passed parameters. ''reject'' will similarly cause the promise to transition into the error state with the passed parameters as the error values.

This feature is very useful to "promisify" code that uses the "old" way of doing asynchronous operations since it allows to create the promise at one point and then store the resolve and reject functions so that they can be called at a later point.

[[Category:Modding]]

Portal:Modding

2020-05-24T16:40:27Z

M!m: Add scripting link

{| border=0 align=center cellpadding=4 cellspacing=0 width=95% style="margin: 0 0 1em 1em; background: #202020; border: 1px #AA2020 solid; border-collapse: collapse; font-size: 95%;"
! style="color: white; height: 30px; background: #512020; 70%;"|'''The Freespace Modding Portal'''
|}

{| border=0 align=right cellpadding=4 cellspacing=1 width=30% style="margin: 0 0 1em 1em; background: #202020; border: 1px #AA2020 solid; border-collapse: collapse; font-size: 95%;"
! style="color: white; height: 30px; background: #512020; 70%;"|'''''General'''''
|-
! style="color: white; height: 30px; 70%;"|[[FS2 Data Structure|Data Structure]]
|-
! style="color: white; height: 30px; 70%;"|[[File Types]]
|-
! style="color: white; height: 30px; 70%;"|[[List of FRED-related topics|Mission design]]
|-
! style="color: white; height: 30px; 70%;"|[[Modelling]]
|-
! style="color: white; height: 30px; 70%;"|[[Tables]]
|-
! style="color: white; height: 30px; 70%;"|[[Texturing]]
|-
! style="color: white; height: 30px; 70%;"|[[PBR Reference Guide]]
|-
! style="color: white; height: 30px; 70%;"|[[Scripting]]
|-
! style="color: white; height: 30px; background: #512020; 70%;"|'''''Tutorials and Downloads'''''
|-
! style="color: white; height: 30px; 70%;"|[[:Category:Tools|Modding Tools]]
|-
! style="color: white; height: 30px; 70%;"|[[Tutorial - Beam Weapons|Beam Weapons reference]]
|-
! style="color: white; height: 30px; 70%;"|[[Styxx's POF Conversion plugin for 3D Studio Max|3DS Max Exporter]]
|-
! style="color: white; height: 30px; 70%;"|[[:Category:Tutorials|Tutorials Category]]
|-
! style="color: white; height: 30px; 70%;"|[[:Category:Scripting Examples|Scripting Examples]]
|-
! style="color: white; height: 30px; 70%;"|[[Video Tutorials]]
|-
! style="color: white; height: 30px; background: #512020; 70%;"|'''''Released Content'''''
|-
! style="color: white; height: 30px; 70%;"|[[User-made Campaigns]]
|-
! style="color: white; height: 30px; 70%;"|[[User-made standalone missions]]
|-
! style="color: white; height: 30px; 70%;"|[[User-made Ships]]
|-
|}

Welcome to the FreeSpace Modding portal. Though presently unfinished, the FS Modding portal will come to be the central hub of all modding-related information on the FS Wiki. It will, of course, have strong links to the SCP-related areas of the Wiki, but for now is reasonably isolated. Please help expand this portal by editing and adding to pages linked from it.

For a complete list of modding-related articles, click [[List of modding-related articles|here]].

[[Category:Modding|*]]

Scripting.tbl

2020-05-24T16:39:45Z

M!m:

{{SCP_table}}

{{TableVersion|11242}}

The '''scripting.tbl''' is used for scripting special features like alternate HUDs or ship viewer into the game.

This table is one of the [[Modular Tables]] and can be extended with xxx-sct.tbm

[[Tables|List of Tables]]

==General Info==
*Scripting table consist of several sections identified by a hash mark preceding the section name (i.g. #Global Hooks)
*All sections ''must'' end with #'''End'''
*All sections are optional
*Most entries are optional
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Sections==

===#Global Hooks===
'''DEPRECATED:''' Global hooks have been deprecated in favour of state hooks since they are more flexible and can be specified multiple times.

Global hooks are the simplest form of scripting hooks available. They are at preset locations in the code, and are generally executed every time that point is reached. Exceptions to this rule (such as the HUD hook) only depend on one or two variables to determine execution. All other scripting execution is determined by the modder.
Note that, as with other tables, the game expects these entries in precisely the order given here; if this is not followed, the parser will throw an error.
 

====$Global:====
Script in this section is executed almost immediately before each frame is drawn. This means that any scripting elements will be drawn, or take effect, after everything else, except for the "On Frame" conditional hook. It is not used with the standalone server. In addition, note that use of this hook should generally be avoided, since all scripting will have to be processed every frame.
 

====$Splash:====
This hook is executed once, when the splash images (PreLoad and PreLoadLogo) would be drawn. This hook should generally be used only for drawing the splash screen; any initialization could should be placed in GameInit. This hook is executed before virtually any other subsystem has been loaded, aside from the graphics and filesystem subsystems, so scripting elements such as the table and mission libraries will be nonfunctional.
 

=====+Override:=====
Executed just before default splash images are loaded and displayed. Note that the frame is still drawn regardless; it is not necessary to flip the backbuffer manually.
 

====$GameInit:====
This hook is executed once, after all of the Freespace2 subsystems have been initialized. It is executed before the game switches to the main hall or, in the case of standalone server mode, begins the game.
 

====$Simulation:====
This hook is executed only during missions. It is executed after all damage, movement, physics, SEXPs, and other "physical" in-game changes have been applied. It is executed before anything has been rendered. This hook should be used only for damage, movement, and physics related scripting, as if the game needs to be rendered without any in-game time having been passed, this function will not be called.
 

====$HUD:====
The HUD hook is executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on.
 

=====+Override:=====
Executed immediately before anything on the HUD is drawn, and controls whether the default FS2_Open is drawn.
 

===#State Hooks===
In Freespace2, a "state" more or less refers to a room. It may also refer to a separate mode - playing a mission is the GS_STATE_GAME_PLAY state. The main menu is the GS_STATE_MAIN_MENU state. This section should only exist in 3.6.9. It is included here for the sake of documentation; it has since been removed (Dec 2006) and superseded by the conditional hook system.
 

=====$State:=====
Specifies the state name. A full list of states is located here: ''[[List of Game States]]''

=====$Hook:=====
Executed after all of the state code has been executed, but before the game frame is actually drawn.

======+Override:======
Determines whether the specified state is handled at all by Freespace. If true, then none of the loading or exit code for the state will be specified as well.

===#Conditional Hooks===
Scripting hooks have been available since Sep 2006. They consist of any number of conditions, followed by any number of actions. All available conditions and actions are located in the file generated by -output_scripting.

One way to think of conditional scripting is like this: The condition specifies the object that the action will apply to, or the place that the action will occur in. All conditions must be met for their associated actions to execute. Actions are associated with a set of conditions by simply adding them after that set of conditions. (Obviously, you may want to space out each pair of action/condition sets in the TBL to make it easier to read.)

The flexibility of conditional scripting comes in due to its inherent scalability. If you specify a mission and ship condition with a warpin action, that script will only be executed when the ship warps in on that particular mission. Removing the mission field will make that warpin scripting apply to the ship for all missions; or removing the ship field will make the warpin scripting apply to all ships in that mission.

This prompts the question: if this is all conditional scripting does, why not just use the global hook?
#Organization - conditional scripting is generally easier to read and modify because it is grouped in a standardized manner.
#Speed - All conditions can be evaluated by FS2_Open itself, without invoking the Lua interpreter at all.
#Scalability - As of the time of this writing, you can only have one global hook. Modular tables will simply replace it. With conditional scripting, if you want to specify additional actions for a set of conditions in a modular table file, you may do so.

;Format

;'''$Condition:''': Where "$Condition:" is one of several conditions specified in scripting.html, such as $State: or $Ship:. Takes a value representing the object the condition should be checked against (such as a state, ship, or mission name)
;'''$Condition:''': ...
;'''...''':
;'''$Action:''': Where "$Action:" is one of several actions specified in scripting.html, such as $On Frame or $On Warp In. Takes a scripting hook, using the bracket configuration outlined at the top of this article.
;'''$Condition:''': ...
;'''...''':

A brief description of all Conditions and Actions at the time of this writing:

====Conditions====

=====$Application:=====
Specifies which application the execution will apply to. Can be '''FS2_Open''' or '''FRED2_Open'''.

=====$State:=====
Controls execution based on what state FS2_Open is in, such as the main hall, options screen, or in a mission.
*The full list of states can be found here: ''[[List of Game States]]''

=====$Campaign:=====
Controls execution based on the current campaign's filename. (It is under consideration to change this to the campaign's name, instead).

=====$Mission:=====
Controls execution based on the filename of the last mission to have started. This condition will remain true even after the mission has been exited until another mission is started.

=====$Object Type:=====
Defines a specific object type that the action will apply for, such as a "Ship", "Asteroid", or "Jump Node".

=====$Ship:=====
Defines a specific ship (name) that the action will apply for.

=====$Ship class:=====
Defines a specific ship class (name) that the action will apply for.

=====$Ship type:=====
Defines a specific ship type (name) that the action will apply for.

=====$Weapon class:=====
Defines a specific weapon class (name) that the action will apply for.

=====$KeyPress:=====
Defines a specific key that the action will apply for.
*Experimental.

=====$Action:=====
{{Table371|
Defines a specific control that the action will apply for. For example "Fire Primary Weapon" or "Match Target Speed".
}}

====Actions====

=====$On Game Init:=====
Executes immediately after game has been started.
::* No associated hook variables.

=====$On Splash Screen:=====
Executes when initial game splash screen is shown
::* No associated hook variables.

=====$On State Start:=====
Executed when specified game state starts
::* No associated hook variables.

=====$On Frame:=====
Executes immediately after the global scripting hook, which is right before the frame is drawn.
::* No associated hook variables.

=====$On Key Pressed:=====
Executed when specified key is pressed
::* '''Key''', The pressed key

=====$On Key Released:=====
Executed when specified key is released
::* '''Key''', The released key

=====$On Mouse Moved:=====
Executed when mouse is moved
::* No associated hook variables.

=====$On Mouse Pressed:=====
Executed when mouse button is pressed
::* No associated hook variables.

=====$On Mouse Released:=====
Executed when mouse button is released
::* No associated hook variables.

=====$On State End:=====
Executed when specified game state ends
::* No associated hook variables.

=====$On Mission Start:=====
Executed when mission starts
::* No associated hook variables.

=====$On Gameplay Start:=====
{{Table3615|
Executed when the gameplay part of a mission starts
::* No associated hook variables.}}

=====$On HUD Draw:=====
Executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on
::* '''Self''', the viewer (object)

=====$On Ship Collision:=====
Executes when the specified object collides with a ship. Sets a handle in the HookVariables library with the name of the object type ("Weapon", "Debris", and so on) with the type of the object. If both objects are ships, the other object gains the name "ShipB". (If both ship objects define a collision hook, the variables will be swapped for the other ship, so the ship that the script is executing for will always be called "Script".) The override will disable FS2_Open code, as well as the other object's collision code. If both objects have an override set, only one of the objects' hooks will be used (Chosen arbitrarily). Note that the override receives the same variables.
::* When colliding something other than other ship:
::** '''Ship''', the ship (object)
::** '''Debris''', '''Asteroid''', '''Weapon''', depending what it collided with (object)
::** '''Self''', the object referred by the condition (object)
::** '''Object''', the ship (object)
::* When colliding with other ship:
::** '''Ship''', the ship (object) referred by the condition (object)
::** '''ShipB''', the other ship (object)
::** '''Self''', the ship (object) referred by the condition (object)
::** '''Object''', the other ship (object)

=====$On Weapon Collision:=====
Like the ship collision hook, but for weapons.
::* When colliding something other than other weapon:
::** '''Weapon''', the weapon (object)
::** '''Debris''', '''Asteroid''', '''Ship''', depending what it collided with (object)
::** '''Self''', the object the weapon collided with (object)
::** '''Object''', the weapon (object)
::* When colliding with other weapon:
::** '''Weapon''', the weapon (object) referred by the condition
::** '''WeaponB''', the other weapon (object)
::** '''Self''', the weapon (object) referred by the condition
::** '''Object''', the other weapon (object)

=====$On Debris Collision:=====
Like the ship collision hook, except for debris.
::* '''Debris''', the debris (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the debris collided with (object)
::* '''Object''', the debris (object)

=====$On Asteroid Collision:=====
Like the ship collision hook, only for asteroids.
::* '''Asteroid''', the asteroid (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the asteroid collided with (object)
::* '''Object''', the asteroid (object)

=====$On Object Render:=====
Executes when the specified object is rendered. The override is run before the object is rendered, and both the hook and its override receive an "Object" variable of the object to be rendered.
::* '''Self''', the object rendered (object)

=====$On Warp In:=====
Run when a ship has begun warping in, immediately after everything has been set up for per-frame processing. This hook is only executed once, when the ship begins warping in. An override will disable _all_ behavior related to warpin. Both the hook and an override receive an "Object" handle in the HookVariables library, with the type of the object that is warping in.
::* '''Self''', the object warping in (object)

=====$On Warp Out:=====
Same as warping in, except for warping out.
::* '''Self''', the object warping out (object)

=====$On Death:=====
*Currently only valid for ships.
Receives "Self" and "Killer" variables of the object and killer, respectively. Overriding it will override all default death behavior.
::* For asteroids:
::** '''Self''', the asteroid (object)
::* For ships:
::** '''Self''', the ship (object)
::** '''Killer''', the other object (object) - NOTE, not guaranteed to exists

=====$On Mission End:=====
Run on mission end.
::* No associated hook variables.
=====$On Weapon Equipped:=====
{{Table3613|
Runs once each frame, for every ship that has the weapon defined in the $Weapon class condition equipped.
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Fired:=====
{{Table3613|
Runs once when a ship fires a weapon defined in the $Weapon class condition
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Selected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is selected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Deselected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is deselected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Turret Fired:=====
{{Table3615|
Executed when a turret fires.
::* '''Ship''', the parent ship
::* '''Weapon''', the weapon which was fired
::* '''Target''', the intended target
}}

=====$On Ship Arrive:=====
{{Table371|
Executed when a ship arrives.
::* '''Ship''', the arriving ship
::* '''Parent''', the ship acting as the anchor when arrival location is "in front of ship", "near ship" or "docking bay"; nil or invalid handle otherwise
}}

=====$On Action:=====
{{Table371|
Executed when an action is triggered, regardless of which key or button it is bound to. Does currently not trigger on mouse or joystick movements.
::* '''Action''', the textual description of the action (for example "Fire Primary Weapon" or "Match Target Speed")
}}

=====$On Action Stopped:=====
{{Table371|
Executed when a continuous action is released (for example "Fire Primary Weapon", "Turn Left" or "Afterburner").
::* '''Action''', the textual description of the action
}}

=====$On Message Received:=====
{{Table371|
Executed when the player receives a message.
::* '''Name''', the message name that was received. The message handle can be accessed with mn.Messages[hv.Name]
::* '''Message''', the message text that would be displayed on the message gauge. Takes in account scrambled messages and variable replacements.
::* '''SenderString''', the displayed string that shows the origin of the message.
::* '''Builtin''', boolean, true if the message was a builtin message (eg: automatic messages from Command or wingmen)
::* '''Sender''', object handle of the ship that sent the message. This might not always be valid, so check is :isValid() if you need to use it
}}

=====$On HUD Message Received:=====
{{Table371|
Executed when the HUD should display a message. This is similar to $On Message Received but it will also receive messages that were not generated by a message (e.g "Firing artillery" for SSM strikes).
::* '''Text''', the plain text of the message
::* '''SourceType''', a number representing the type of the sender. The number can be one of the following:
:::* ''0'' A message sent by the computer
:::* ''1'' A training message
:::* ''2'' A message from a hidden source
:::* ''3'' An important message (this type is currently unused)
:::* ''4'' An failed message (this type is currently unused)
:::* ''5'' An satisfied message (this type is currently unused)
:::* ''6'' An message sent by (Terran) command
:::* ''7'' A multiplayer message
:::* ''≥8'' When the type is greater or equal to 8 then the source is one of the teams in the mission. You can get a team handle using mn.Team[hv.SourceType - 7] (as lua uses 1 based indexes)
}}

=====$On Afterburner Engage:=====
{{Table373|
Executed when a ship engages its afterburner.
::* '''Ship''', the ship object of the ship engaging its afterburner
}}

=====$On Afterburner End:=====
{{Table373|
Executed when a ship stops its afterburner.
::* '''Ship''', the ship object of the ship stopping its afterburner
}}

=====$On Beam Collision:=====
{{Table373|
Executed when a beam hits something.

----

'''If the beam hit a ship:'''
::* '''Self''', the target ship that the beam hit
::* '''Object''', the beam object that was fired

----

'''If the beam hit an asteroid:'''
::* '''Object''', the beam object that was fired
::* '''Self''', the asteroid that was hit by the beam

----

'''If the beam hit a weapon, such as a torpedo:'''
::* '''Object''', the beam object that was fired
::* '''Self''', the weapon object that was hit by the beam

----

'''If the beam hit a piece of debris:'''
::* '''Object''', the beam object that was fired
::* '''Self''', the debris object that was hit by the beam

}}

=====$On Beam Fire:=====
{{Table373|
Executed when a beam is fired. This will occur after warm up is complete, as the beam starts to render and give damage.
::* '''Beam''', the beam object being fired
::* '''User''', the parent ship object firing the beam
::* '''Target''', the target object that the beam is trying to hit. Not guaranteed to exist!
}}

=====$On Campaign Mission Accept:=====
{{Table381|
Executed when the outcome of a campaign mission is accepted.
}}

=====$On Ship Depart:=====
{{Table381|
Executed when a ship departs the mission. This hook accounts for all departure types and it is not limited to only warping.
::* '''Ship''', the ship departing
}}

=====$On Waypoints Done:=====
{{Table382|
Executed when a ship or wing completes a waypoint path.
::* '''Ship''', the ship that completed the waypoint path
::* '''Wing''', the wing that completed the waypoint path; nil or invalid handle otherwise
::* '''Waypointlist''', the waypointlist that was completed
}}

=====$On Subsystem Destroyed:=====
{{Table382|
Executed when a subsystem is destroyed.
::* '''Ship''', the parent ship of the destroyed subsystem
::* '''Subsystem''', the name of the subsystem that was destroyed (string)
}}

=====$On Goals Cleared:=====
{{Table382|
Executed when a ship's goals are cleared via the clear-goals sexp or scripting function.
::* '''Ship''', the ship that had it's goals cleared
}}

==Misc. Hook Variables:==

===Viewer===
*Active if (non-player) viewing object is valid

===Player===
*Active if player obj is valid
 

==Examples==

See [[:Category:Scripting Examples|Scripting Examples category]]

[[Category:Tables]]

Scripting

2020-05-24T16:39:15Z

M!m:

Scripting

2020-05-24T16:38:22Z

M!m: Created page with "{{SCP_table}} Scripting allows a modder to run custom code in the engine that can read and modify the game state to produce new features. Scripts are either specified via ..."

{{SCP_table}}

Scripting allows a modder to run custom code in the engine that can read and modify the game state to produce new features.

Scripts are either specified via [[Scripting.tbl]] or as standalone lua files.

==General Info==
*Scripting table consist of several sections identified by a hash mark preceeding the section name (i.g. #Global Hooks)
*All sections ''must'' end with #'''End'''
*All sections are optional
*Most entries are optional
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Useful references==
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.1/ Reference manual for Lua 5.1]'''

==Standalone Lua scripts==
Since writing Lua scripts using the table can lead to some issues while developing scripts (such as wrong syntax highlighting or wrong line numbers in error messages) the engine also supports loading Lua scripts directly and executing them when the initial game data has been loaded. Since that alone does not allow to register hooks, there is a scripting API that allows to do that from Lua code. See engine.addHook in scripting.html.

==Prerequisites==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

[[Category:Modding]]

Particle Effects

2019-02-09T11:08:51Z

M!m: Added documentation for "effects per second feature"

{{SCP_table}}

{{TableVersionGit|2016-09-02|417eb20}}

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the [[Modular Tables]] and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual ''+nocreate'' ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with ''+nocreate'' in mind for when that is implemented.

[[Tables|List of Tables]]

=General Info=
*Begins with #Particle Effects
*Contains zero or more particle effect definitions
*Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

==$Effect:==
*Creates a new effect and specifies its name. The name must be at least one character long.
*Syntax: '''String'''

===$Type:===
*Sets the type of this effect. See [[#Effect Types|Effect Types]] for possible values.
*Syntax: '''String'''

=Effect Types=
There are multiple different types of effects. They are specified by passing the given name to ''$Type''.

==Single==
This effect type creates exactly one particle per processing step.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Effects per second:===
*Specifies how many times per second this effect is triggered. If this is not specified then the effect is triggered every frame. "Triggering" an effect means that one instance of the effect with the properties from above is created. If this is specified then the amount of triggers per second is always the same regardless of the FPS the game is running at. Values higher than the FPS (e.g. 120 if the game is running at 60 FPS) are handled correctly and will trigger the effect multiple times per frame if necessary.
*This is optional
*Syntax: ''number''. Must be greater than 0.

==Composite==
A composite effects contains multiple other effects which are all displayed at the same time. This is useful if you want to create complex effects that require more than one individual particle effect. The amount of child effects is not limited. This type currently does not support ''+nocreate''.

===+Child effect:===
*This specifies a child effect that should be added to the composite effect. The effect is specified using [[#Inline effect creation]].

==Cone==
This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution] around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Deviation:===
*Sets the standard deviation from the direction vector.
*Required if ''+nocreate'' is not present
*Syntax: '''float''', in degrees

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Effects per second:===
*Specifies how many times per second this effect is triggered. If this is not specified then the effect is triggered every frame. "Triggering" an effect means that one instance of the effect with the properties from above is created. If this is specified then the amount of triggers per second is always the same regardless of the FPS the game is running at. Values higher than the FPS (e.g. 120 if the game is running at 60 FPS) are handled correctly and will trigger the effect multiple times per frame if necessary.
*This is optional
*Syntax: ''number''. Must be greater than 0.

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Sphere==
This effect creates particles in a sphere shape around the center.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Effects per second:===
*Specifies how many times per second this effect is triggered. If this is not specified then the effect is triggered every frame. "Triggering" an effect means that one instance of the effect with the properties from above is created. If this is specified then the amount of triggers per second is always the same regardless of the FPS the game is running at. Values higher than the FPS (e.g. 120 if the game is running at 60 FPS) are handled correctly and will trigger the effect multiple times per frame if necessary.
*This is optional
*Syntax: ''number''. Must be greater than 0.

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Inline effect creation==
At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use '''$New Effect''' which will create a new, unnamed effect. If a name is specified then that effect must be already defined. In order to ensure that the effect is always defined no matter in which order the effect tables are parsed the effect should be defined in the same table. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If '''$New Effect''' is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. ''+nocreate'' is not valid within this element.

==Random range==
The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

===Uniform random range===
*This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values. If only one value is specified then the parentheses are optional.
**Example: ''(4 20)''
**Example: ''4''

===Normal distribution random range===
*This accepts 1 or 2 values. This random range generates values according to a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution]. The first value specified the mean value of the distribution. The second value specifies the standard deviation of the distribution, this defaults to 1.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

=Example=
<pre>
#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
+Filename: exp05
+Size: (5 7)
+Lifetime: (0.6)
+Deviation: 5
+Velocity: (500 700)
+Number: (20 30)
+Direction: Reflected
+Trail effect: $New Effect
$Type: Single
+Filename: exp20
+Size: (10)
+Lifetime: (1)
+Duration: Always

$Effect: ApocalypseIgnition
$Type: Single
+Filename: exp20
+Size: (10 20)

$Effect: ApocalypseHomed
$Type: Composite
+Child effect: $New Effect
$Type: Single
+Filename: exp05
+Size: (5 7)
+Duration: (2 10)
+Child effect: $New Effect
$Type: Single
+Filename: exp06b
+Size: (5 7)
+Duration: (2 10)
+Delay: (8 15)
+Effects per second: 20

#End
</pre>

Particle Effects

2019-02-09T11:02:54Z

M!m: Add documentation for optional parentheses.

{{SCP_table}}

{{TableVersionGit|2016-09-02|417eb20}}

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the [[Modular Tables]] and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual ''+nocreate'' ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with ''+nocreate'' in mind for when that is implemented.

[[Tables|List of Tables]]

=General Info=
*Begins with #Particle Effects
*Contains zero or more particle effect definitions
*Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

==$Effect:==
*Creates a new effect and specifies its name. The name must be at least one character long.
*Syntax: '''String'''

===$Type:===
*Sets the type of this effect. See [[#Effect Types|Effect Types]] for possible values.
*Syntax: '''String'''

=Effect Types=
There are multiple different types of effects. They are specified by passing the given name to ''$Type''.

==Single==
This effect type creates exactly one particle per processing step.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Composite==
A composite effects contains multiple other effects which are all displayed at the same time. This is useful if you want to create complex effects that require more than one individual particle effect. The amount of child effects is not limited. This type currently does not support ''+nocreate''.

===+Child effect:===
*This specifies a child effect that should be added to the composite effect. The effect is specified using [[#Inline effect creation]].

==Cone==
This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution] around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Deviation:===
*Sets the standard deviation from the direction vector.
*Required if ''+nocreate'' is not present
*Syntax: '''float''', in degrees

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Sphere==
This effect creates particles in a sphere shape around the center.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Inline effect creation==
At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use '''$New Effect''' which will create a new, unnamed effect. If a name is specified then that effect must be already defined. In order to ensure that the effect is always defined no matter in which order the effect tables are parsed the effect should be defined in the same table. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If '''$New Effect''' is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. ''+nocreate'' is not valid within this element.

==Random range==
The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

===Uniform random range===
*This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values. If only one value is specified then the parentheses are optional.
**Example: ''(4 20)''
**Example: ''4''

===Normal distribution random range===
*This accepts 1 or 2 values. This random range generates values according to a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution]. The first value specified the mean value of the distribution. The second value specifies the standard deviation of the distribution, this defaults to 1.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

=Example=
<pre>
#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
+Filename: exp05
+Size: (5 7)
+Lifetime: (0.6)
+Deviation: 5
+Velocity: (500 700)
+Number: (20 30)
+Direction: Reflected
+Trail effect: $New Effect
$Type: Single
+Filename: exp20
+Size: (10)
+Lifetime: (1)
+Duration: Always

$Effect: ApocalypseIgnition
$Type: Single
+Filename: exp20
+Size: (10 20)

$Effect: ApocalypseHomed
$Type: Composite
+Child effect: $New Effect
$Type: Single
+Filename: exp05
+Size: (5 7)
+Duration: (2 10)
+Child effect: $New Effect
$Type: Single
+Filename: exp06b
+Size: (5 7)
+Duration: (2 10)
+Delay: (8 15)

#End
</pre>

Particle Effects

2018-12-23T12:40:44Z

M!m: Updated location of trail effect option location

{{SCP_table}}

{{TableVersionGit|2016-09-02|417eb20}}

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the [[Modular Tables]] and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual ''+nocreate'' ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with ''+nocreate'' in mind for when that is implemented.

[[Tables|List of Tables]]

=General Info=
*Begins with #Particle Effects
*Contains zero or more particle effect definitions
*Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

==$Effect:==
*Creates a new effect and specifies its name. The name must be at least one character long.
*Syntax: '''String'''

===$Type:===
*Sets the type of this effect. See [[#Effect Types|Effect Types]] for possible values.
*Syntax: '''String'''

=Effect Types=
There are multiple different types of effects. They are specified by passing the given name to ''$Type''.

==Single==
This effect type creates exactly one particle per processing step.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Composite==
A composite effects contains multiple other effects which are all displayed at the same time. This is useful if you want to create complex effects that require more than one individual particle effect. The amount of child effects is not limited. This type currently does not support ''+nocreate''.

===+Child effect:===
*This specifies a child effect that should be added to the composite effect. The effect is specified using [[#Inline effect creation]].

==Cone==
This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution] around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Deviation:===
*Sets the standard deviation from the direction vector.
*Required if ''+nocreate'' is not present
*Syntax: '''float''', in degrees

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Sphere==
This effect creates particles in a sphere shape around the center.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Inline effect creation==
At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use '''$New Effect''' which will create a new, unnamed effect. If a name is specified then that effect must be already defined. In order to ensure that the effect is always defined no matter in which order the effect tables are parsed the effect should be defined in the same table. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If '''$New Effect''' is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. ''+nocreate'' is not valid within this element.

==Random range==
The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

===Uniform random range===
*This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

===Normal distribution random range===
*This accepts 1 or 2 values. This random range generates values according to a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution]. The first value specified the mean value of the distribution. The second value specifies the standard deviation of the distribution, this defaults to 1.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

=Example=
<pre>
#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
+Filename: exp05
+Size: (5 7)
+Lifetime: (0.6)
+Deviation: 5
+Velocity: (500 700)
+Number: (20 30)
+Direction: Reflected
+Trail effect: $New Effect
$Type: Single
+Filename: exp20
+Size: (10)
+Lifetime: (1)
+Duration: Always

$Effect: ApocalypseIgnition
$Type: Single
+Filename: exp20
+Size: (10 20)

$Effect: ApocalypseHomed
$Type: Composite
+Child effect: $New Effect
$Type: Single
+Filename: exp05
+Size: (5 7)
+Duration: (2 10)
+Child effect: $New Effect
$Type: Single
+Filename: exp06b
+Size: (5 7)
+Duration: (2 10)
+Delay: (8 15)

#End
</pre>

Particle Effects

2018-12-16T19:20:57Z

M!m: Clarify how +Number works

{{SCP_table}}

{{TableVersionGit|2016-09-02|417eb20}}

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the [[Modular Tables]] and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual ''+nocreate'' ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with ''+nocreate'' in mind for when that is implemented.

[[Tables|List of Tables]]

=General Info=
*Begins with #Particle Effects
*Contains zero or more particle effect definitions
*Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

==$Effect:==
*Creates a new effect and specifies its name. The name must be at least one character long.
*Syntax: '''String'''

===$Type:===
*Sets the type of this effect. See [[#Effect Types|Effect Types]] for possible values.
*Syntax: '''String'''

=Effect Types=
There are multiple different types of effects. They are specified by passing the given name to ''$Type''.

==Single==
This effect type creates exactly one particle per processing step.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Composite==
A composite effects contains multiple other effects which are all displayed at the same time. This is useful if you want to create complex effects that require more than one individual particle effect. The amount of child effects is not limited. This type currently does not support ''+nocreate''.

===+Child effect:===
*This specifies a child effect that should be added to the composite effect. The effect is specified using [[#Inline effect creation]].

==Cone==
This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution] around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Deviation:===
*Sets the standard deviation from the direction vector.
*Required if ''+nocreate'' is not present
*Syntax: '''float''', in degrees

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Sphere==
This effect creates particles in a sphere shape around the center.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of particles created for every frame the effect is active. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Inline effect creation==
At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use '''$New Effect''' which will create a new, unnamed effect. If a name is specified then that effect must be already defined. In order to ensure that the effect is always defined no matter in which order the effect tables are parsed the effect should be defined in the same table. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If '''$New Effect''' is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. ''+nocreate'' is not valid within this element.

==Random range==
The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

===Uniform random range===
*This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

===Normal distribution random range===
*This accepts 1 or 2 values. This random range generates values according to a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution]. The first value specified the mean value of the distribution. The second value specifies the standard deviation of the distribution, this defaults to 1.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

=Example=
<pre>
#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
+Filename: exp05
+Size: (5 7)
+Lifetime: (0.6)
+Deviation: 5
+Velocity: (500 700)
+Number: (20 30)
+Direction: Reflected
+Trail effect: $New Effect
$Type: Single
+Filename: exp20
+Size: (10)
+Lifetime: (1)
+Duration: Always

$Effect: ApocalypseIgnition
$Type: Single
+Filename: exp20
+Size: (10 20)

$Effect: ApocalypseHomed
$Type: Composite
+Child effect: $New Effect
$Type: Single
+Filename: exp05
+Size: (5 7)
+Duration: (2 10)
+Child effect: $New Effect
$Type: Single
+Filename: exp06b
+Size: (5 7)
+Duration: (2 10)
+Delay: (8 15)

#End
</pre>

Subsystem

2018-10-27T17:03:12Z

M!m: Add documentation for "no damage spew" and "no impact debris" flags.

{{Fileversion|7119}}

*All subsystems ship can have must be defined in ships model file (.pof).

{{Table3610|
*[[Animation_Code|Animation Code]] can be applied to the subsystems that consist of submodels, like multi-part turrets.}}

==$Subsystem:==
*The name of the subsystem as defined in .pof file, % of ship's total hitpoints the subsystem has and rotation time (360 degrees) for multi-part turrets. Note: Assigning zero to the %-hitpoint entry causes the subsystem to be without hitpoints, like fighterbays on some capital ships.
*Syntax: '''''String''''', '''''Float''''', '''''Float''''', name of the subsystem followed by the subsystem hitpoints as % of ships hitpoints and seconds per 360 degree turn. Subsystem name must be the same as described in model file (.pof).
{{Table3610|
*Entries can be left empty in which case game uses default values}}
**Example: communications, 5, 0.0

===$Alt Subsystem Name:===
{{Table3610|
*Defines the alternate name for the subsystem. This name is shown for example in the targeting window when subsystem is targeted.
*Syntax: '''''String'''''}}
{{Table3611|
*Option to use pipe character '<nowiki>|</nowiki>' to force line breaks into the alt subsystem name}}

===$Alt Damage Popup Subsystem Name:===
{{Table3611|
*Defines the alternate name for the subsystem when it is displayed on the '''damaged systems''' popup.
*Syntax: '''''String'''''}}

===$Armor Type:===
{{Table3610|
* '''REQUIRES ADDITIONAL TABLE'''. Defines armor type used for the subsystem. If subsystem armor type is not defined ships armor type is used instead.
* Syntax: '''''String''''', as defined in [[armor.tbl]]}}

===$Default PBanks:===
*Defines default primary weapon for the turret
*Syntax: ( '''''"String"''''' )
**Example: ( ''"Subach HL-7"'' )

===$PBank Capacity:===
{{Table3610|
*Defines ammunition capacity of turrets ballistic primary weapon.
*Syntax: ( '''''Integer''''' )}}

===$Default SBanks:===
*Defines default secondary weapon for the turret
*Syntax: ( '''''"String"''''' )

===$SBank Capacity:===
*Defines ammunition capacity of turrets secondary weapon.
*Syntax: ( '''''Integer''''' )

===$Engine Wash:===
*All engines may use information concerning the engine wash. Engine washes are usually used only with larger vessels.
*Syntax: '''''String''''', name as defined in Engine Wash section in [[ships.tbl]]
**Example: ''Default1000''

===$AliveSnd:===
{{Table3610|
*Specifies a sound to play from the subsystem while it is not destroyed.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$DeadSnd:===
{{Table3610|
*Specifies a sound to play from the subsystem while it is destroyed.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$RotationSnd:===
{{Table3613|
*Can be used to define a sound that is played when this subsystem rotates.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$Turret Base RotationSnd:===
{{Table3611|
*Defines the sound which is played when the turrets base rotates
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$Turret Gun RotationSnd:===
{{Table3611|
*Defines the sound which is played when the turrets guns change their elevation
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$Turret BaseSnd Volume:===
{{Table3611|
*Defines the multiplier for the sound volume for turret base rotations
*Syntax: '''''Float'''''}}

===$Turret GunSnd Volume:===
{{Table3611|
*Defines the multiplier for the sound volume for turret guns change their elevation
*Syntax: '''''Float'''''}}

===$AWACS:===
*Sets this subsystem's effective AWACS range. (AWACS reveals stealthed ships, cuts through nebula fog.)
*Syntax: '''''Float''''', the maximum range of the AWACS

===$Maximum Barrel Elevation:===
{{Table3611|
*Defines the maximum barrel elevation for the turret
*Basically 'inverse FOV'.
*Syntax: '''''Integer''''', from 0 to 90}}

===$Turret Base FOV:===
{{Table3611|
*Defines the FOV of the turret's base.
*Syntax: '''''Integer''''', from 0 to 359}}

===$Turret Reset Delay:===
{{Table3611|
*Defines the time after losing the target before the turret begins to reset itself
*Syntax: '''''Integer''''', in milliseconds}}

===$Turret Optimum Range:===
{{Table3611|
*Defines the optimum range for the turret
*Syntax: '''''Float'''''}}

===$Turret Direction Preference:===
{{Table3611|
*Defines the turrets preference to keep targeting targets based how far the turret should turn instead of nearest target
*The higher the value the higher the preference to keep targeting targets close to previous targets direction
*Syntax: '''''Integer''''', from 0 to 100, 0 disables the preference setup}}

===$Target Priority:===
{{Table3611|
*Defines the target priorities, and their order for the turret
*Syntax: '''''String list'''''}}

===$Max Turrets per Bomb:===
{{Table3613|
*Limits the number of turrets that can be targeting the same bomb.
*When this is set, when this turret tries to target a bomb, it will check to see how many turrets are already targeting it and only choose it as a target if there are less than this number.
*This allows control over the default behavior, where every turret will fire at the leading bomb.
*Syntax: '''''Integer'''''}}

===$Max Turrets per Target:===
{{Table3613|
*Limits the number of turrets that can be targeting the same target.
*'''ONLY AFFECTS SMALL TARGETS''' such as fighters and bombers. This limit does '''NOT''' apply vs large ships.
*When this is set, when this turret tries to target a ship, it will check to see how many turrets are already targeting it and only choose it as a target if there are less than this number.
*This helps turrets spread their efforts out among multiple targets.
*Syntax: '''''Integer'''''}}

===$ROF:===
{{Table3613|
*Defines the modifier applied to the turret rate of fire (ROF).

====+Use firingpoints====
*Modifies (multiplies) the rate of fire by the number of firingpoints the turret has.

====+Multiplier:====
*Checked only if ''+Use firingpoints'' has not been defined
*If set to larger than 0 the value acts as multiplier
*If set to 1.0 the feature is disabled
*If set to equal to or smaller than 0 it as if ''+Use firingpoints'' option would have been enabled
*Syntax: '''''Float'''''}}

===$Flags:===
{{Table3610|
*Can be used to sets additional subsystem related properties
*Syntax: ( '''''"String" "String"''''' )
*List of available flags:

===="untargetable"====
*Subsystem cannot be targeted

===="carry no damage"====
*Damage caused to the subsystem will not carry over to the parent ship

===="use multiple guns"====
*Enables the turret to fire all equipped weapons, picking a not-in-use firing point at each trigger. Not to be confused with 'Salvo mode'.

===="fire down normals"====
*Forces the turret to fire along the turret normals - regardless of the swarm setting.

===="check hull"====
*Forces the firing turret to check against the parent model if valid line of sight exists between the firingpoint and the target.}}

{{Table3611|
===="fixed firingpoints"====
*Forces the firing turret to retain the firingpoints of their weapons: if the turret has multiple banks, the first bank will only fire from the first firepoint, the second bank only from the second firepoint, and so on. Maximum number of weapons is the same as maximum number of weapons in turret (3 primary, 4 secondary)

===="salvo mode"====
*Forces the firing turret to use only the first weapon defined for it but fires it simultaneously from all the firing points. Not to be confused with 'use multiple guns'

===="no subsystem targeting"====
*Prevents the firing turret from targeting targets subsystems - instead forces the turret to fire randomly at the targets hull.

===="fire on target"====
*Prevents the turret from firing unless the turret barrels (firingpoints) and targets are aligned.

===="reset when idle"====
*Forces the turret to reset to its initial position if it has no targets.

===="carry shockwave"====
*Forces the turret to carry damage caused by shockwaves to the hull regardless of other flags.}}

{{Table3613|
===="allow landing"====
*Defines the subsystem as something on which player can attempt to land on

===="target requires fov"====
*Prevents turret from accidentally selecting target out of it field of view (fov) when acquiring targets

===="fov edge checks"====
*If the predicted target point of the turret falls outside of the field of view this flag but according to ship radius and dot product the target should still be partially visible then this flag attempts to turn the turret to the edge of the FOV closest to the targeted position and allow it to fire along that direction.

===="no replace"====
*Tells game not to use the replacement submodel (-destroyed) when the subsystem loses all of it's hitpoints.

===="no live debris"====
*Prevents the subsystem from releasing live debris pieces when destroyed

===="ignore if dead"====
*When subsystem has been destroyed prevents homing weapons from attempting to hit the now destroyed submodel and instead tells them to home on the main hull of the target

===="allow vanishing"====
*Allow subsystem to be destroyed from the ship without sound or graphical effects

===="damage as hull"====
*Treats subsystem as if it were hull when applying damage.

===="starts locked"====
*Turret starts locked and won't shoot until you use a turret-free or turret-free-all SEXP on it.

===="no aggregate"====
*Freespace keeps track of a ships overall functionality (such as if a ship is sensorless, disarmed or disabled) via a total hitpoint count of the associated subsystems. For example if a ship has three engines with 100HP each, the 'engines' count will be at 300HP. Shooting at any of the subsystems with the keyword 'engine' in them will decrement this total, and when it is at 0 then the ship becomes disabled.
*This flag tells FS to ignore the associated subsystem and not count it towards those totals. For example, if a ship had three 100HP engines with one set to 'no aggregate' then the 'engines' count will be 200HP. Shooting the 'no aggregate' engine will not decrement the 'engines' count, and so in other words the status of this engine is irrelevant to whether or not the ship is disabled. In the same way when applied to a turret, the turret's status is irrelevant to whether the ship is disarmed or not.

===="wait for animation"====
*When this flag is active, a turret will only fire after any associated subsystem animations (such as a turret hatch opening) have played out.

===="play fire sound for player"====
*If this turret is on a player ship, play its associated sounds.

===="only target if can fire"====
*Do additional checks to make sure that a turret which cannot fire at its target releases that target.
}}

{{Table3615|
===="no disappear"====
*If this subsystem is a physical subsystem, it won't disappear nor switch to the -destroyed model when destroyed.

===="collide submodel"====
*If this subsystem is a physical subsystem, it will only take damage from hits which impact the submodel. By default damage is taken from all hits within the submodel's radius*2. Does not affect area damage such as shockwaves.

===="allow destroyed rotation"====
*Allows a rotating subobject to continue to rotate even when it has been destroyed
}}

{{Table373|
===="turret use ammo"====
*If the subsystem is a turret, it will use ammo.
**Note: If the turret does not have ammo, it will not fire. Remember that the maximum ammo a turret can hold is the Capacity of the Bank divided by the Cargo Size of the weapon.

===="share fire direction"====
*If this subsystem is a turret, whenever the turret fires it will make all of the firing points shoot their weapon in the same direction instead of at the same point or set of points on a target.
}}

{{Table381|
===="no damage spew"====
*If this subsystem is hit then there will be no damage spew particles emitted.

===="no impact debris"====
*If this subsystem is hit then no impact debris will be generated.
}}

===[[Animation Code]]===
{{Table3610|
*Option for animating the submodels}}

==Case Specific Entries==

===Turret===
*All turrets require information concerning the weapon mounted to the turret. The entry can be either '''$Default PBanks''' for turret primaries (including beams) or '''$Default SBanks''' for turret secondaries
{{Table3610|
*[[Animation_Code#Setting_Turret_Angle|Animation Code]] can be used with multi-part turrets.
*Multiple defined weapons will all fire but the targeting is handled by the first weapon in the list. '''Multiple beams are not possible'''. All weapons alternate between the firingpoints of the turret so turrets do not need to have more than one weapon defined no matter how many barrels or firingpoints they have.}}

====Example====

<pre>
$Subsystem: turret01, 1.0, 1.0
$Default PBanks: ( "Terran Turret" )
</pre>

===Engine===

====Example====

<pre>
$Subsystem: engine01, 5.0, 0.0
$Engine Wash: Default1000
</pre>

[[Category:Tables]]

Particle Effects

2018-07-24T03:14:24Z

M!m: Add missing documentation for specifying effect timing information

{{SCP_table}}

{{TableVersionGit|2016-09-02|417eb20}}

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the [[Modular Tables]] and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual ''+nocreate'' ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with ''+nocreate'' in mind for when that is implemented.

[[Tables|List of Tables]]

=General Info=
*Begins with #Particle Effects
*Contains zero or more particle effect definitions
*Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

==$Effect:==
*Creates a new effect and specifies its name. The name must be at least one character long.
*Syntax: '''String'''

===$Type:===
*Sets the type of this effect. See [[#Effect Types|Effect Types]] for possible values.
*Syntax: '''String'''

=Effect Types=
There are multiple different types of effects. They are specified by passing the given name to ''$Type''.

==Single==
This effect type creates exactly one particle per processing step.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Composite==
A composite effects contains multiple other effects which are all displayed at the same time. This is useful if you want to create complex effects that require more than one individual particle effect. The amount of child effects is not limited. This type currently does not support ''+nocreate''.

===+Child effect:===
*This specifies a child effect that should be added to the composite effect. The effect is specified using [[#Inline effect creation]].

==Cone==
This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution] around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Deviation:===
*Sets the standard deviation from the direction vector.
*Required if ''+nocreate'' is not present
*Syntax: '''float''', in degrees

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Sphere==
This effect creates particles in a sphere shape around the center.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Inline effect creation==
At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use '''$New Effect''' which will create a new, unnamed effect. If a name is specified then that effect must be already defined. In order to ensure that the effect is always defined no matter in which order the effect tables are parsed the effect should be defined in the same table. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If '''$New Effect''' is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. ''+nocreate'' is not valid within this element.

==Random range==
The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

===Uniform random range===
*This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

===Normal distribution random range===
*This accepts 1 or 2 values. This random range generates values according to a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution]. The first value specified the mean value of the distribution. The second value specifies the standard deviation of the distribution, this defaults to 1.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

=Example=
<pre>
#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
+Filename: exp05
+Size: (5 7)
+Lifetime: (0.6)
+Deviation: 5
+Velocity: (500 700)
+Number: (20 30)
+Direction: Reflected
+Trail effect: $New Effect
$Type: Single
+Filename: exp20
+Size: (10)
+Lifetime: (1)
+Duration: Always

$Effect: ApocalypseIgnition
$Type: Single
+Filename: exp20
+Size: (10 20)

$Effect: ApocalypseHomed
$Type: Composite
+Child effect: $New Effect
$Type: Single
+Filename: exp05
+Size: (5 7)
+Duration: (2 10)
+Child effect: $New Effect
$Type: Single
+Filename: exp06b
+Size: (5 7)
+Duration: (2 10)
+Delay: (8 15)

#End
</pre>

Tables

2018-01-15T13:26:30Z

M!m: Add link to the dynamic SEXPs page

'''Tables''' are the major data files in [[Portal:FreeSpace 1|FreeSpace]] and [[Portal:FreeSpace 2|FreeSpace 2]]. Compared with many other games, they are highly intuitive and easy to edit, requiring no special tools other than Notepad. For more detail on specific tables, see the links below.

'''''Full list of active tables can be found below. In-depth modular tables info can be found in [[Modular Tables]] page.

Information on how FreeSpace uses tables can be found on the [[FreeSpace 2 directory structure|FreeSpace 2 directory structure]] page.'''''

{| border=0 align=right cellpadding=2 cellspacing=1 style="margin: 0 0 1em 1em; background: #202020; border: 1px #AA2020 solid; border-collapse: collapse; font-size: 95%;"
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''''Active tables files and related code files'''''
|-
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''* Notes [[Modular Tables]]'''
|-
! colspan="2" style="color: white; height: 30px; background: #512020; 70%;"|'''** Notes tables which only use modular tables'''
|-
| align="center"| [[Ai.tbl]]
| '''/ai/'''aicode.cpp
|-
| align="center"| [[Ai_profiles.tbl]]*
| '''/ai/'''ai_profiles.cpp
|-
| align="center"| [[Armor.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Asteroid.tbl]]
| '''/asteroid/'''asteroid.cpp
|-
| align="center"| [[Autopilot.tbl]]
| '''/autopilot/'''autopilot.cpp
|-
| align="center"| [[Colors.tbl]]*
| '''/globalincs/'''alphacolors.cpp
|-
| align="center"| [[Controlconfigdefaults.tbl]]
| '''/controlconfig/'''controlsconfigcommon.cpp
|-
| align="center"| [[Credits.tbl]]*
| '''/menuui/'''credits.cpp
|-
| align="center"| [[Cutscenes.tbl]]
| '''/cutscene/'''cutscenes.cpp
|-
| align="center"| [[Fireball.tbl]]*
| '''/fireball/'''fireballs.cpp
|-
| align="center"| [[Fonts.tbl]]
| '''/graphics/'''font.cpp
|-
| align="center"| [[Game_settings.tbl]]*
| '''/mod_table/'''mod_table.cpp
|-
| align="center"| [[Glowpoints.tbl]]*
| '''/model/'''modelread.cpp
|-
| align="center"| [[Help.tbl]]*
| '''/gamehelp/'''contexthelp.cpp
|-
| align="center"| [[Hud_gauges.tbl]]*
| '''/hud/'''hudparse.cpp
|-
| align="center"| [[Icons.tbl]]
| '''/mission/'''missionbriefcommon.cpp
|-
| align="center"| [[Iff_defs.tbl]]
| '''/iff_defs/'''iff_defs.cpp
|-
| align="center"| [[Lightning.tbl]]
| '''/nebula/'''neblightning.cpp
|-
| align="center"| [[Mainhall.tbl]]*
| '''/menuui/'''mainhallmenu.cpp
|-
| align="center"| [[Medals.tbl]]
| '''/stats/'''medals.cpp
|-
| align="center"| [[Messages.tbl]]
| '''/mission/'''missionmessage.cpp
|-
| align="center"| [[Mflash.tbl]]*
| '''/weapon/'''muzzleflash.cpp
|-
| align="center"| [[Music.tbl]]*
| '''/gamesnd/'''eventmusic.cpp
|-
| align="center"| [[Nebula.tbl]]
| '''/nebula/'''neb.cpp
|-
| align="center"| [[Objecttypes.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Pixels.tbl]]
| '''/palman/'''palman.cpp
|-
| align="center"| [[Post_processing.tbl]]
| '''/graphics/'''gropenglpostprocessing.cpp
|-
| align="center"| [[Rank.tbl]]
| '''/stats/'''scoring.cpp
|-
| align="center"| [[Scripting.tbl]]*
| '''/parse/'''scripting.cpp
|-
| align="center"| [[Ships.tbl]]*
| '''/ship/'''ship.cpp
|-
| align="center"| [[Dynamic SEXPs|Sexps.tbl]]**
| '''/parse/sexp/'''sexp_lookup.cpp
|-
| align="center"| [[Sounds.tbl]]*
| '''/gamesnd/'''gamesnd.cpp
|-
| align="center"| [[Species_defs.tbl]]*
| '''/species_defs/'''species_defs.cpp
|-
| align="center"| [[Species.tbl]]
| '''/menuui/'''techmenu.cpp
|-
| align="center"| [[Ssm.tbl]]*
| '''/hud/'''hudartillery.cpp
|-
| align="center"| [[Stars.tbl]]*
| '''/starfield/'''starfield.cpp
|-
| align="center"| [[Strings.tbl]]*
| '''/localization/'''localize.cpp
|-
| align="center"| [[Tips.tbl]]
| '''/menuui/'''playermenu.cpp
|-
| align="center"| [[Traitor.tbl]]
| '''/missionui/'''missiondebrief.cpp
|-
| align="center"| [[Tstrings.tbl]]*
| '''/localization/'''localize.cpp
|-
| align="center"| [[Weapon_expl.tbl]]*
| '''/weapon/'''weapons.cpp
|-
| align="center"| [[Weapons.tbl]]*
| '''/weapon/'''weapons.cpp
|-
|}

==Accessing table files==
Volition used a special kind of packaging method called .vp (Volition Pack) for the FreeSpace games. Table files are stored in Root_fs2.vp. To open and extract files from a VP, you must use a VP editing program such as [[VPView32]]. For more details about VP files and how to work with them, consult [[*.VP|this article]].

For some further information about where to put modified files, consult [[FreeSpace 2 directory structure]].

==Table files==
Table files are customarily edited using Notepad, but any text editor that can save in a pure text format will do.

===.tbl files===

These files are the basic FreeSpace table used for defining various aspects of the game. Game reads only single .tbl choosing the one it encounters first while parsing the game directories.

===.tbm files===
These files are modular table files. They can be used for adding content to the 'base' tables or to modify the data from those files. For usage info and important notes, see [[Modular Tables]].

==Notes of certain table files==

===Hardcoded table files===

Some of the table files are not actually required as the basic version has been written directly to the code. However these can be overridden by table files present in game directories.

'''These files are not present in standard FreeSpace 2 .vp files'''

*[[Ai_profiles.tbl]]
*[[Autopilot.tbl]]
*[[Colors.tbl]]
*[[Iff_defs.tbl]]
*[[Objecttypes.tbl]]
*[[Species_defs.tbl]]

===Optional table files===

Certain tables are not found from the code nor do they belong to the basic table set. These tables are parsed if game detects them

'''These files are not present in standard FreeSpace 2 .vp files'''

*[[Armor.tbl]]
*[[Controlconfigdefaults.tbl]]
*[[Scripting.tbl]]

===Obsolete table files===

Some table files have since been 'retired' and they are no longer needed with FreeSpace Open

*[[Hud.tbl]]
*[[Launchhelp.tbl]]
*[[Menu.tbl]]
*[[Tooltips.tbl]]

===Theoretical table files===

These tables are documentations of possible future tables for use with FreeSpace Open

*[[Interface.tbl]]

==Important notes==

===Table entries must be ordered===

*As a general rule, '''''all the table entries must be ordered'''''.
*Keep the order shown in the following help sections for each table in both normal tables (tbl files) and [[Modular Tables]] (tbm files). If you don't do it, you can get parser errors on FS2 or FRED2 loading when they are reading them.
** In other words, you don't have to have all of these details/attributes for a given weapon/ship/etc (or a modification of a weapon/etc)--few, if any, have them all, and many have a mere fraction of these--but the ones you do have must be kept in the same relative order. If, for example, your weapon doesn't have/need any of the 30-or-so attributes between 'Lifetime' and 'ImpactSnd', you can probably leave them out altogether, but be sure to place your entry for 'ImpactSnd' after your entry for 'Lifetime' on the weapon in question.

==Brief descriptions of table files==

*In all the table help pages, SCP added entries are usually marked with infoboxes that mark the branch there the particular feature has added to.
:*'''<nowiki>{{Table3610| text}}</nowiki>''' gives 3.6.10 box
{{Table3610| text}}
:*'''<nowiki>{{Table3612| text}}</nowiki>''' gives 3.6.12 box
{{Table3612| text}}
:*'''<nowiki>{{Table3614| text}}</nowiki>''' gives 3.6.14 box
{{Table3614| text}}
:*'''<nowiki>{{Table3616| text}}</nowiki>''' gives 3.6.16 box
{{Table3616| text}}
:*'''<nowiki>{{Table37| text}}</nowiki>''' gives 3.7.0 box
{{Table37| text}}
:*'''<nowiki>{{Table372| text}}</nowiki>''' gives 3.7.2 box
{{Table372| text}}
*For full list of table related pages and links see [[:Category:Tables]]

[[Category:Tables|*]]

[[Category:Modding]]

[[Category:File Types]]

Multimedia Files

2018-01-03T11:26:54Z

M!m: Add some documentation on the new cutscene player

The FreeSpace 2 Open engine is able to use several different '''multimedia file formats''' for audio, animation and video playback. Retail FreeSpace 2 used the [[Wikipedia:Wav|WAV]] and '''ANI''' file formats, but the currently the FreeSpace 2 Open supports several [[Wikipedia:Ogg|Ogg]] container files as well. Support for the [[Wikipedia:Mp3|MP3]] file format was removed in favor of Ogg. The game engine also supports the custom '''.EFF''' animation format, as well as [[Wikipedia:APNG|APNG]] (as of commit 76ffc2668 / 3.8.0).

==Ogg==
'''Ogg''' is a file format for compressed multimedia files. Unlike MP3, Ogg is an open-source, open-standard container format with a permissive license, both of which allow it to be incorporated into the FS2_Open source code. Also unlike MP3, Ogg is a [[Wikipedia:Container_format|container format]], meaning that it can contain video data (via the [[Wikipedia:Theora|Theora codec ]]) in addition to audio data (via the [[Wikipedia:Vorbis|Vorbis codec]]).

Since Ogg delivers significantly smaller file sizes than [[Wikipedia:Wav|WAV]], while retaining substantially the same level of audio quality, it is becoming more and more frequently used in FSO-targeted mods. Ogg Vorbis is not, however, a lossless format -- i.e., it is not possible to exactly reconstruct the original data from an Ogg Vorbis file because some is "lost" in the conversion process. This is not usually a problem, however, because a high-quality Ogg Vorbis file is usually indistinguishable from the source. The lossless counterpart to Ogg Vorbis is [[Wikipedia:Free_Lossless_Audio_Codec|FLAC]], which can be contained in Ogg also.

Vorbis uses a quality parameter between -1 and 10 as a measure of quality. 5 is the default, giving around 160kbps. The higher the number, the higher the quality, but anything over 5 is probably pointless.

Audacity and Goldwave are two popular programs that allow WAV files to be converted to Ogg Vorbis audio. Audacity is Free Software, while Goldwave is shareware that ceases to function after a period of time.

Please note that this is a fso feature and is not supported by the original retail FreeSpace 2.

==WAV==
The most common sound file format. WAVs are uncompressed and take up a larger amount of space than almost any other sound file type, so consider converting them to the [[*.OGG|Ogg]] Vorbis format (supported only by SCP) before including them in your campaign. Audacity and Goldwave are two examples of programs that can make this conversion. [http://www.rarewares.org/ogg-oggdropxpd.php oggdropXPd] is an useful drag-and-drop encoder.

==ANI==
FreeSpace uses the ANI format for animation effects. It can be used either for an effect (explosions, etc.), an interface animation, or as a ship texture.

===Creating an ANI file===

Using [http://www.descent-network.com/cgi-bin/descman.cgi?module=anibuilder AniBuilder], one can create new ANI files from AVI movies or rendered frames.

To create your own ANI:

#Create your scene in a 3D animation program or in FreeSpace. You can capture game footage using free recording software such as [http://www.planetgamecam.com GameCam], a preexisting movie, or you can render your own. Volition used the expensive [[Wikipedia:3ds_Max|3ds Max]] for their animations, but the free [[Wikipedia:Blender_(software)|Blender]] is just as good, and there are plenty of tutorials available for both. Alternately, ANIs can simply have one or two static frames.
#Output your movie to individual 24- or 32-bit BMP frames, numbered in sequence (starting with aniname0000.) You can check your desired resolution by looking at the type of ANI you want to replace, with the exception of up to 660x300 acceptable for high-resolution command briefing animations in FreeSpace Open. If you have a movie, use a program such as [[Wikipedia:Virtual_Dub|Virtual DUB]] to convert the AVI into a series of BMP files and crop or resize them as necessary.
#Convert your BMP frames to PCX files with a common palette. Certain interface art (for example, briefing icons and HUD head animations) requires an exact palette, which you can import from an existing ANI using a paint program such as [[Wikipedia:GIMP|GIMP]]. But in most cases, you will want to convert them to an optimized common palette. Best results are achieved with [http://freespacemods.net/download.php?view.520 BRIGHT]. AniBuilder can attempt to do this by itself but the results are almost always very poor.
#Use AniBuilder to convert the PCX files to an ANI. Some animations, such as ship/weapon loadouts and main hall animations, require keyframes; refer to the existing animations for how to insert these.

A more technical definition of ani files can be found [[ANI_Formal_Definition|here]].

==EFF==
FreeSpace 2 uses the EFF ASCII format text files to store information about animated effects. These animated effects can be used for various effects such as in game animations and animated textures. Please note that this is a fso feature and is not supported by the original retail FreeSpace 2.

===Creation of EFF animation===
*For EFF animation all the individual frames of the animation have to be present in one of the [[Graphic Files|graphic file formats]] supported by the game engine.
*All files related to the EFF animation have to named so that the name of actual .EFF animation forms the basic structure of the filename.
**'''Graphic files''' add the 4 digit number - that identifies the frame where the file is used - after the animation name, starting from 0 (example_0000.dds, example_0001.dds etc.)
**'''ASCII file''' contains the information of the animation (example.eff)

===Contents of a EFF file===

====$Type:====
*Defines the file format of the graphics file used for the EFF animation
*Syntax: '''''String''''', for example ''DDS''

====$Frames:====
*Defines the length of the number of the frames in the animation
*Syntax; '''''Integer'''''

====$FPS:====
*Used ''optionally'' to define the '''frames per second''' value for the animation
*Syntax: '''''Integer'''''

====$Keyframe:====
*Used ''optionally'' to define a keyframe for EFF used as part of the interface.
*Syntax: '''''Integer''''' (The frame number, starting at index 0. Do not specify numbers greater than the number of frames)

====Example====

Let's say you have three dds (TGA and pcx are also acceptable) files (named 1_000, 1_0001, and 1_0002) you want to make into an animation, but you don't want to use anibuild and therefore compromise quality.

Your EFF file would be like this:

Filename (the filename, not information to be entered. This must match up with characters before _xxxx in frames): 1.eff

$Type: DDS
$Frames: 3
$FPS: 5

This EFF effect file would display one frame after another at 5 frames a second, skipping back to the beginning at the end.

'''Please note''' that in FSO 3.6.10 and earlier, EFF cannot be used for streaming files (head animations, icons, mainhall, cbanis, ect.) and is meant ONLY for weapon/explosion effects and animated textures.

==APNG==

The places in FSO where APNGs make most sense are

* Command Brief Anims
* Intel Anims (techroom)
* Loading Screen Anim
* HUD Anims (e.g. headz, lock, etc)
* Mainhall animations

You CAN use APNGs for any other animation if you wish, e.g. animated glows, weapon impact effects, explosions, shield anims, etc. However, EFF with DDS would generally be a better choice because they're compressed in a format your video card can use directly, and thus they use much less video RAM.

Having said that, in many cases the apng files on disk (only) will be smaller than other animation formats which can mean reduced modpack sizes. e.g. the 2_intel_earth.png file is 7.5MB, compared with 15MB for the mediavps_2014 ANI file. Likewise an example EFF+PNG headani was 3.8MB as png frames, the APNG was 2.1MB. Note that this reduction heavily depends on the content of the APNG. From some rough tests done by Axem & niffiwan it seems that APNGs with a transparent background and an object moving through the background will probably fair poorly. One such example only reduced from 11MB to 9.9MB. This is because the best APNG compression method is diff/delta frames composed over the previous frame, and it can't draw a transparent pixel over the top of a non-transparent one. Therefore with a transparent background the frame needs to get completely redrawn, making the filesize larger.

Lastly, FSO uses the .png extension for apngs, not .apng (see [https://github.com/scp-fs2open/fs2open.github.com/pull/537#discussion_r53765499 here] for more info on why if you're curious)

====Simple APNG creation====

Here's steps on how to create simple APNGs.

1) Create your animation in your favourite animation application and save it as a PNG file stream. It'll be easiest if the frames are named in ascending order; e.g. anim_0000.png, anim_0001.png, etc (not strictly needed, just easier). Remember you have 24 bit colour & 8 bit alpha available, there's no need for a custom palette or special transparency colours.

2) Get an apng assembler. There's a bunch available on the internet, online only versions, local installs, command line and GUI. I've personally used the apngasm command line version so that's what I'll use in my example.

* [https://github.com/apngasm/apngasm/archive/3.1.6.zip Latest apngasm source (3.1.6)]
* [https://github.com/apngasm/apngasm/releases/download/3.1.3/apngasm_3.1-3_AMD64.exe Latest Windows 64bit executable (3.1.3)]
* For OSX they say use homebrew; I have no idea how to do this, sorry!

Note that the [http://www.reto-hoehener.ch/japng/ Japng Editor] allows you to open up apngs and see exactly what each frame is doing, e.g. when the assembler has chosen to use delta frames vs complete frames, etc.

3) Use the assembler to create your apng

You need to know what frame delay you want between all frames... and that's it for a simple animation.

Here's an example using frames exported from the mediavps_2014 intelligence ANI file for "Earth" (I used aniview32 to export the frames to BMPs, then imagemagick to convert them to 24bit PNGs). The FPS for the ani is 15.

<pre>
apngasm -d 67 -o 2_intel_earth.png 2_intel_earth_0*.png

-d specifies the default frame delay for each frame (67 msec in the example)
-o specifies the output name, for FSO we'll use the .png extension
The last set of arguments is all the frames in animation order
</pre>

4) Configure the apng within FSO

In my example, copy 2_intel_earth.png to FSO/mod/data/intelanims

And that's it!

====Advanced APNG creation====

There are some more advanced options for creating apngs which may be of use in certain circumstances.

1) Per Frame Delays

You can give each frame in the animation it's own delay, different to every other frame in the animation. To do this, just put the individual frame delay after the frames source image.

i.e.
<pre>
apngasm -d 67 -s -o 2_intel_earth.png 2_intel_earth_renamed_0000.png 500 2_intel_earth_0*.png
</pre>

This makes the 1st frame play for 500 ms, and all the other frames have a 67ms delay.

Note that the most recent versions of apngasm will do this for you if you include duplicated frames in your sequence. i.e. if you have 50 frames and two sequential frames are the same, then apngasm will create an apng with 49 frames, where one frame has double the frame delay of the rest.

2) Loading APNGs as PNGs

FSO will happily load an apng as a static image if you load it as an image rather than an animation. This is a bit hard to control for stuff internal to FSO, but you've got full control over this in LUA. Anyway, this could save you putting extra files in your mod, by default the 1st frame of the animation will be loaded as the static image. Or you can put any frame you like as the "1st frame" and tell apngasm to skip than frame when playing back as an animation.

i.e.
<pre>
apngasm -d 67 -s -o 2_intel_earth.png special_1st_frame.png 2_intel_earth_0*.png

-s is the option to skip the 1st frame
special_1st_frame.png is the 1st argument without a preceding option and thus is the 1st frame processed by apngasm
</pre>

Maybe this could be of use if you wanted to (e.g.) have a selectable pilot image that's also the 1st frame in that pilots head ani (I dunno, I'm not sure if there's any real use cases for this or not, but as long as everyone knows about the option then people could think up tricky uses for it).

3) Looping

APNG's can set the number of times that they will loop. However, FSO ignores this in favour of the code controlling how any given animation will loop (e.g. cbanims always loop, headanis never loop, etc). So don't worry about the loop value as FSO will ignore it.

==Movie files==
{{Table38|
In the 3.8.0 release of FreeSpace Open a new cutscene system was added which uses [https://www.ffmpeg.org/ FFmpeg] for decoding video files. This added support for multiple video codecs and container formats. The following video codecs have been tested and are known to work:
* Theora (in Ogg container files)
* H.264 (in MP4 container files)
* VP8/VP9 (typically in WebM files)

The movie player always selects the "best" video channel and the corresponding audio channel which may cause problems if a movie file contains multiple video or audio streams. To make the behavior predictable a movie file should only contain one video stream and one audio stream.
}}

===Subtitles===
{{Table382|
For localization purposes the movie player also supports language specific subtitles encoded in the movie file. This code has not been tested with a lot of movie files so if you encounter issues with this part of the cutscene player please post the movie file in the forums so that the SCP can improve the cutscene player.
}}

[[Category:File Types]]

Game settings.tbl

2018-01-03T11:22:38Z

M!m: Add documentation for the $Movie subtitle font option.

{{SCP_table}}

{{TableVersionGit|2017-12-16| a583764}}

The '''game_settings.tbl''', also known as mod.tbl, defines options that can be changed globally.

This table is one of the [[Modular Tables]] and can be extended with xxx-mod.tbm

[[Tables|List of Tables]]

==#GAME SETTINGS==
Optional. Contains settings that affect how the engine works. 

===$Target Version:===
{{Table373|
Specifies the minimum version of FreeSpace Open that this mod supports. If the version specified here is greater than the version of the current build, an error message is displayed.
}}
{{Table381|
The $Minimum version option has been renamed to $Target Version. The old name is kept with the same functionality for backwards-compatibility.

The target version specifies what version of the FSO engine this mod was created for. It will be used by the engine to enable or disable backwards-incompatible changes by default. The default value is 2.0 which specifies that the mod targets the retail engine version.
}}

====+Major:====
{{Table373|
Required. Sets the major component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Minor:====
{{Table373|
Required. Sets the minor component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''7''''' (for a minimum version of 3.7.3.20151121)
}}

====+Build:====
{{Table373|
Required. Sets the build component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Revision:====
{{Table373|
Optional. Sets the revision component of the target version. If no revision is given then all builds of that release are supported (even nightly builds if there are any).
For nightly builds this is the date in YYYYMMDD format.
*Syntax: '''''Integer''''' 
*Example: '''''20151121''''' (for a minimum version of 3.7.3.20151121)
}}

===$Window title:===
{{Table382|
Specifies the name of the FSO window when this mod is running. If blank or unspecified, the window will have the default title of "FreeSpace 2".
*Syntax: '''''String'''''
}}

===$Unicode mode:===
{{Table382|
Enabled the Unicode text mode for this mod. In Unicode mode all text is assumed to be UTF-8 encoded Unicode and certain features are disabled if they do not have full Unicode support. Most notably, if this is enabled then the engine will no longer support the old bitmap fonts that were used by Retail FreeSpace. Only the newer TrueType fonts will be supported.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

==#CAMPAIGN SETTINGS==
Optional. This group contains various Campaign related settings and overrides. 

===$Default Campaign File Name:===
Defines which campaign will be selected by default for new pilots. A file extension is not needed and, if present, is removed by the code.
*Syntax: '''''String''''' 

===#Ignored Campaign File Names===
Optional. Defines which campaigns, if present, will not appear in the Campaign Room. Only single-player campaigns can be ignored. ''File extensions are required.''
{{Table371|As of 3.7.1, file extensions are not required and, if present, are removed by the code.}}
====$Campaign File Name:====
File name of the campaign to ignore. Multiple entries may exist.
*Syntax: '''''String''''' 

===$Red-alert applies to delayed ships:===
Controls whether red-alert saved statistics (hitpoints, weapons, subsystem strengths) will be restored for ships that are not present at mission start.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#HUD SETTINGS==
Optional. This group contains various HUD behavior settings and overrides 

===$Directive Wait Time:===
*Defines how long the game will wait before displaying a directive.
*Syntax: '''''Integer''''' 
*Values: '''''Greater than or equal to 0 ms'''''

===$Cutscene camera displays HUD:===
Show the HUD when the cutscene camera is enabled.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Cutscene camera disables HUD: and had a default of YES.

===$Full color head animations:===
Enables full-color head ANIs. Normal head ANIs will appear in gray.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Color head animations with hud colors: and had a default of YES.

==#SEXP SETTINGS==
Optional. This group contains SEXP settings and overrides. 

===$Loop SEXPs Then Arguments:===
Flips how when-argument settings loop. See: [http://www.hard-light.net/forums/index.php?topic=79602.0 SEXP Argument changes via mod.tbl]
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

===$Use Alternate Chaining Behavior:===
When set, this makes the event chaining behavior act as people expected it to be in [http://scp.indiegames.us/mantis/view.php?id=82 Mantis #82].
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#GRAPHICS SETTINGS==
Optional. This group contains settings related to graphics. 

===$Enable External Shaders:===
Enables the use of external shader files. By default, the engine will use the built-in shaders.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default Detail Level:===
{{Table3615|
Determines which graphics detail level preset (low, medium, high, very high) acts as the default for new pilots.
*Syntax: '''''Integer''''' (0-3)
*Default Value: '''''3''''' (very high) }}

===$Briefing Window FOV:===
{{Table371|
Determines the FOV in the briefing Icon window. Retail default for this is 0.29375, previous versions of FSO used a value of 0.5.
*Syntax: '''''Float''''' (0.0 to 1.0)
*Default Value: '''''0.29375''''' }}

===$Generic Pain Flash Factor:===
{{Table373|
Determines the intensity of the pain red flash when the player is hit.
*Syntax: '''''Float'''''
*Default Value: '''''1.0''''' }}

===$Shield Pain Flash Factor:===
{{Table373|
Determines the intensity of a pain flash when the player's shields are hit. Color will match the current ships shield color defined in ships.tbl. A value of 0 will give retail behavior (no shield effect). Positive values will cause the effect to start at full intensity at full shields and go to next to no intensity at zero shields. Negative values will cause no effect at full shields and full effect at no shields. Values should be kept between -1.0 and 1.0 for good pilot visibility.
*Syntax: '''''Float'''''
*Default Value: '''''0.0''''' }}

===$BMPMAN Slot Limit:===
{{Table382|
Determines the maximum number of textures that can be loaded simultaneously. This includes every frame of an animation, unless that animation is streaming (e.g. command briefing animations, message talking heads, etc). Also includes dynamically-created textures (used internally for various functions).
*Syntax: '''''Int'''''
*Values: '''''Greater than or equal to 3500'''''
*Default Value: '''''4750''''' }}

==#SOUND SETTINGS==
Optional. This group contains sound-related settings 

===$Default Sound Volume:===
{{Table371|
*Defines the default sound fx volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''1.0'''''}}

===$Default Music Volume:===
{{Table371|
*Defines the default music volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.5'''''}}

===$Default Voice Volume:===
{{Table371|
*Defines the default voice volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.7'''''}}

==#FRED SETTINGS==
Optional. This group contains settings for FRED. 

===$Disable Hard Coded Message Head Ani Files:===
{{table371|
If set, FRED will not fill the head ani selection in the Event Editor with the retail head ani filenames.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' }}

===$Enable scripting in FRED:===
{{table382|
If set, scripting will be enabled in FRED. Use with extreme caution. The effects of scripts on FRED have not been fully tested. You can check if a script is running in FRED by using ba.inMissionEditor().
*Default Value: '''''NO''''' }}

==#OTHER SETTINGS==
Optional. This group contains miscellaneous settings. 

===$Fixed Turret Collisions:===
Makes all hits to a turret's barrels count as hits to the turret subsystem. By default, this does not happen unless the point of impact falls inside the model radius of the turret's base.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Damage Impacted Subsystem First:===
If set, a hit to a physical subsystem will always deal damage to that subsystem first, even if another subsystem is closer to the point of impact. By default, the closest subsystem will always receive damage first.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default ship select effect:===
{{Table3615|
*This specifies which effect to use for ship select animations when no .ani can be found, or the -ship_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Default weapon select effect:===
{{Table3615|
*This specifies which effect to use for weapon select animations when no .ani can be found, or the -weapon_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Weapons inherit parent collision group:===
{{Table3615|
*When set to true, Weapons fired by a ship will inherit their parents' collision group setting. Default is false.}}

===$Flight controls follow eyepoint orientation:===
{{Table371|
*Specifies that if the player ship's eyepoint happens to rotate into a non-standard orientation, pitch and yaw axes should stay relative to the eyepoint orientation, not the ship. Note that this does not affect the pitch/yaw turning speed, which always remains relative to the ship. Default is false.}}

===$Beams Use Damage Factors:===
{{Table371|
*Specifies that beam weapons will use the tabled damage factors for Armour, Shields and Subsystems. Default is false (i.e. all factors are treated as 1.0)}}

===$Default fiction viewer UI:===
{{Table373|
*Specifies which fiction viewer layout to use in missions that don't specify one. Possible values are as follows:
**"FS2": Standard layout. Requires (2_)fictionviewer and (2_)fictionviewer-m to be present in data\interface.
**"WCS": Moves the "Accept" button to the lower-left corner of the screen. Requires (2_)fictionviewerb and (2_)fictionviewer-mb to be present in data\interface.
**"auto": Selects "WCS" if the appropriate files are present; otherwise, selects "FS2". This is the default setting.}}

===$Movie subtitle font:===
{{Table382|
*Specifies which font should be used for displaying subtitles in the cutscene player. This should be the name given to this font in the fonts table. Since movie subtitles can contain Unicode text it is a good idea to enable Unicode mode when movie subtitles are used but this is not enforced by this option.}}

==#END==
Required. The last line of the table must be #END

==Sample Entry==

#CAMPAIGN SETTINGS
$Default Campaign File Name: NewCampaignFile

#Ignored Campaign File Names
$Campaign File Name: FreeSpace2.fc2

#HUD SETTINGS
$Directive Wait Time: 5000

#SEXP SETTINGS
$Loop SEXPs Then Arguments: True

#OTHER SETTINGS
$Fix Turret Collisions: True

#END

[[Category:Tables]]

Dynamic SEXPs

2018-01-03T10:54:03Z

M!m: Add documentation for the message parameter type.

Since version 3.8.2 FSO supports adding custom SEXPs to a mod which have a user defined effect. Currently there is only one way to add such a SEXP but more may be added in the future.

Dynamic SEXPs are only added in modular table files which end with <tt>-sexp.tbm</tt>

=Table syntax=
This section will describe the syntax and effects of the individual options.

==#Lua SEXPs==

Specifies a list of dynamic SEXPs implemented using a Lua function (see [[#Lua interface|Lua interface]] for how to use the implementation function). This section must end with <tt>#End</tt>

===$Operator:===
*Adds a new SEXP operator with the specified name. The name may not contain the following characters: <tt>()\"'</tt>. Furthermore, any whitespace (tab characters or spaces) are also not permitted. This is the name under which this operator will appear in the SEXP code. While the name is mostly up to you it would be a good idea to keep it in line with how the other SEXPs are named. To avoid conflicts with other custom SEXPs you should also use a unique prefix. For example, if you want to have some SEXP operators that control a cloaking script then you could use <tt>cloak-</tt> as the common prefix for all the operators that are related to this system. A SEXP that disables the cloak system could be named something like <tt>cloak-disable</tt>.
*This name must be unique among all operators that are known to the SEXP system. That includes built-in SEXPs and operators added before. If there is a conflict then the new operator definition will be ignored. Built-in operators always take precedence.
*Syntax: '''''String'''''

===$Category:===
*Specifies in which category this SEXP will appear in the context menu in the FRED event editor. Only one of the existing categories may be used. These are all the currently defined categories:
**Objectives
**Time
**Logical
**Arithmetic
**Status
**Change
**Conditionals
**Ai goals
**Event/Goals
**Training
*Syntax: '''''String'''''

===$Subcategory:===
*Specifies into which subcategory this SEXP should be put. This is the second level in the context menu of the FRED event editor. New subcategories can be added by specifying a new name here but all subcategory names must be globally unique (you can't have the same subcategory name under two different categories).
*Syntax: '''''String'''''

===$Minimum Arguments:===
*Specifies ht minimum number of parameters this SEXP needs to work. If less parameters are specified then the SEXP parser will treat this as an error.
*Must be at least 0.
*Syntax: '''''Integer'''''

===$Maximum Arguments:===
*Specifies the maximum number of parameters this SEXP can process.
*Optional. If this option is not present then the SEXP can process an unlimited number of parameters.
*Must be at least 0 and greater or equal to $Minimum Arguments.

===$Return Type:===
*Specifies what data type this SEXP will return when invoked. Can be one of the following:
**; number: The SEXP will return an integer. The scripting function needs to return a number value.
**; boolean: The SEXP will return a boolean. The scripting function must return a boolean value.
**; nothing: The SEXP will return nothing. The scripting function may not return anything.
*Optional. Defaults to ''nothing''
*Syntax: '''''String'''''

===$Description:===
*Sets the help text displayed in the FRED help box. This should be the generic description of what this SEXP does but should not include the documentation for the individual parameters.
*Syntax: '''''String'''''

===$Repeat===
*This option must be combined with the parameter documentation below to specify a repeating pattern in a SEXP with a variable number of parameters. See the example below for how exactly this will work. All parameters specified after this option will be grouped together. The script will receive these groups of parameters as a single entity (see [[#Lua interface|Lua interface]]) to make it easier to use the values without having to separate them again in the script.

===$Parameter:===
*Adds documentation for the parameters and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by <tt>$Minimum Arguments</tt> and <tt>$Maximum Arguments</tt>.
*This option has no value.

====+Description:====
*Sets the description of this parameter. This will be used for the documentation text.
*Syntax: '''''String'''''

====+Type:====
*Sets the type this parameter requires. The currently supported types are:
**; number: This parameter is a number. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; boolean: This parameter is a boolean. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; ship: This parameter is the name of a ship. The script will receive this value as a <tt>ship</tt> handle. If the name provided by the mission is invalid (if the ship has not arrived yet or if it is not present anymore) then the script will receive an invalid <tt>ship</tt> handle.
**; string: This parameter is a generic string with no special format. In Unicode mode this string may contain Unicode characters.
**; team: This parameter is a handle to a specific team. The script will receive this value as a <tt>team</tt> handle.
**; waypointpath: This parameter is a reference to a specific waypoint path. The script will receive this as a <tt>waypointlist</tt> handle.
**; variable: This is a reference to a SEXP variable. This is a reference to the actual variable and not its contents. The script will receive this as a <tt>sexpvariable</tt> handle.
**; message: This is a reference to a mission message. The script will receive it as a <tt>message</tt> handle.
*Syntax: '''''String'''''

==Example==
<pre>
#Lua SEXPs

$Operator: dynamic-sexp
$Category: Change
$Subcategory: Scripted
$Minimum Arguments: 3
; No maximum arguments means that it accepts a variable number of arguments
$Return Type: Nothing
$Description: This is a dynamic parameter test SEXP
$Parameter:
+Description: Number parameter
+Type: Number
$Parameter:
+Description: Ship parameter
+Type: Ship
$Parameter:
+Description: Variable name parameter
+Type: variable
$Repeat ; This starts the part of the parameter list where the parameter pattern repeats
$Parameter:
+Description: Variable string parameter
+Type: string
$Parameter:
+Description: Variable number parameter
+Type: Number

#End
</pre>

=Lua interface=
So far, all the SEXP table has done is specify that a new Lua SEXP exists but there is no actual action which will be executed when the SEXP is called. For the Lua language this can be done using the <tt>mn.LuaSEXPs</tt> variable. This is a variable which can be indexed using the SEXP name. The returned value is of type <tt>LuaSEXP</tt> which only has a single field, <tt>Action</tt>. This is the function that will be executed once the SEXP is called in a mission. You can use it to retrieve the function of a LuaSEXP but the more common use case is that it is written in the <tt>$On Game Init</tt> hook to set the action function.

The action function will receive the values as normal parameters. If the SEXP will receive a variable number of parameters then you can use <tt>...</tt> as the last parameter to also capture these values. If a parameter is optional and not specified by the SEXP invocation then it will be <tt>nil</tt> in the script. Parameters in the repeat pattern of the parameter list will be grouped into a array of arrays where each array instance contains the individual values. See below for an example of how this can be handled in the Lua code.

<pre>
#Conditional Hooks

$Application: FS2_Open
$On Game Init: [
mn.LuaSEXPs["dynamic-sexp"].Action = function (arg1, arg2, arg3, ...)
ba.print(tostring(arg1)
ba.print(arg2.Name)
ba.print(tostring(arg3.Value))

for val in {...} do
ba.print(val[1])
ba.print(tostring(val[2]))
done
end
]

#End
</pre>

Dynamic SEXPs

2018-01-02T18:30:20Z

M!m: Also fix SEXP variable usage

Since version 3.8.2 FSO supports adding custom SEXPs to a mod which have a user defined effect. Currently there is only one way to add such a SEXP but more may be added in the future.

Dynamic SEXPs are only added in modular table files which end with <tt>-sexp.tbm</tt>

=Table syntax=
This section will describe the syntax and effects of the individual options.

==#Lua SEXPs==

Specifies a list of dynamic SEXPs implemented using a Lua function (see [[#Lua interface|Lua interface]] for how to use the implementation function). This section must end with <tt>#End</tt>

===$Operator:===
*Adds a new SEXP operator with the specified name. The name may not contain the following characters: <tt>()\"'</tt>. Furthermore, any whitespace (tab characters or spaces) are also not permitted. This is the name under which this operator will appear in the SEXP code. While the name is mostly up to you it would be a good idea to keep it in line with how the other SEXPs are named. To avoid conflicts with other custom SEXPs you should also use a unique prefix. For example, if you want to have some SEXP operators that control a cloaking script then you could use <tt>cloak-</tt> as the common prefix for all the operators that are related to this system. A SEXP that disables the cloak system could be named something like <tt>cloak-disable</tt>.
*This name must be unique among all operators that are known to the SEXP system. That includes built-in SEXPs and operators added before. If there is a conflict then the new operator definition will be ignored. Built-in operators always take precedence.
*Syntax: '''''String'''''

===$Category:===
*Specifies in which category this SEXP will appear in the context menu in the FRED event editor. Only one of the existing categories may be used. These are all the currently defined categories:
**Objectives
**Time
**Logical
**Arithmetic
**Status
**Change
**Conditionals
**Ai goals
**Event/Goals
**Training
*Syntax: '''''String'''''

===$Subcategory:===
*Specifies into which subcategory this SEXP should be put. This is the second level in the context menu of the FRED event editor. New subcategories can be added by specifying a new name here but all subcategory names must be globally unique (you can't have the same subcategory name under two different categories).
*Syntax: '''''String'''''

===$Minimum Arguments:===
*Specifies ht minimum number of parameters this SEXP needs to work. If less parameters are specified then the SEXP parser will treat this as an error.
*Must be at least 0.
*Syntax: '''''Integer'''''

===$Maximum Arguments:===
*Specifies the maximum number of parameters this SEXP can process.
*Optional. If this option is not present then the SEXP can process an unlimited number of parameters.
*Must be at least 0 and greater or equal to $Minimum Arguments.

===$Return Type:===
*Specifies what data type this SEXP will return when invoked. Can be one of the following:
**; number: The SEXP will return an integer. The scripting function needs to return a number value.
**; boolean: The SEXP will return a boolean. The scripting function must return a boolean value.
**; nothing: The SEXP will return nothing. The scripting function may not return anything.
*Optional. Defaults to ''nothing''
*Syntax: '''''String'''''

===$Description:===
*Sets the help text displayed in the FRED help box. This should be the generic description of what this SEXP does but should not include the documentation for the individual parameters.
*Syntax: '''''String'''''

===$Repeat===
*This option must be combined with the parameter documentation below to specify a repeating pattern in a SEXP with a variable number of parameters. See the example below for how exactly this will work. All parameters specified after this option will be grouped together. The script will receive these groups of parameters as a single entity (see [[#Lua interface|Lua interface]]) to make it easier to use the values without having to separate them again in the script.

===$Parameter:===
*Adds documentation for the parameters and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by <tt>$Minimum Arguments</tt> and <tt>$Maximum Arguments</tt>.
*This option has no value.

====+Description:====
*Sets the description of this parameter. This will be used for the documentation text.
*Syntax: '''''String'''''

====+Type:====
*Sets the type this parameter requires. The currently supported types are:
**; number: This parameter is a number. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; boolean: This parameter is a boolean. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; ship: This parameter is the name of a ship. The script will receive this value as a <tt>ship</tt> handle. If the name provided by the mission is invalid (if the ship has not arrived yet or if it is not present anymore) then the script will receive an invalid <tt>ship</tt> handle.
**; string: This parameter is a generic string with no special format. In Unicode mode this string may contain Unicode characters.
**; team: This parameter is a handle to a specific team. The script will receive this value as a <tt>team</tt> handle.
**; waypointpath: This parameter is a reference to a specific waypoint path. The script will receive this as a <tt>waypointlist</tt> handle.
**; variable: This is a reference to a SEXP variable. This is a reference to the actual variable and not its contents. The script will receive this as a <tt>sexpvariable</tt> handle.
*Syntax: '''''String'''''

==Example==
<pre>
#Lua SEXPs

$Operator: dynamic-sexp
$Category: Change
$Subcategory: Scripted
$Minimum Arguments: 3
; No maximum arguments means that it accepts a variable number of arguments
$Return Type: Nothing
$Description: This is a dynamic parameter test SEXP
$Parameter:
+Description: Number parameter
+Type: Number
$Parameter:
+Description: Ship parameter
+Type: Ship
$Parameter:
+Description: Variable name parameter
+Type: variable
$Repeat ; This starts the part of the parameter list where the parameter pattern repeats
$Parameter:
+Description: Variable string parameter
+Type: string
$Parameter:
+Description: Variable number parameter
+Type: Number

#End
</pre>

=Lua interface=
So far, all the SEXP table has done is specify that a new Lua SEXP exists but there is no actual action which will be executed when the SEXP is called. For the Lua language this can be done using the <tt>mn.LuaSEXPs</tt> variable. This is a variable which can be indexed using the SEXP name. The returned value is of type <tt>LuaSEXP</tt> which only has a single field, <tt>Action</tt>. This is the function that will be executed once the SEXP is called in a mission. You can use it to retrieve the function of a LuaSEXP but the more common use case is that it is written in the <tt>$On Game Init</tt> hook to set the action function.

The action function will receive the values as normal parameters. If the SEXP will receive a variable number of parameters then you can use <tt>...</tt> as the last parameter to also capture these values. If a parameter is optional and not specified by the SEXP invocation then it will be <tt>nil</tt> in the script. Parameters in the repeat pattern of the parameter list will be grouped into a array of arrays where each array instance contains the individual values. See below for an example of how this can be handled in the Lua code.

<pre>
#Conditional Hooks

$Application: FS2_Open
$On Game Init: [
mn.LuaSEXPs["dynamic-sexp"].Action = function (arg1, arg2, arg3, ...)
ba.print(tostring(arg1)
ba.print(arg2.Name)
ba.print(tostring(arg3.Value))

for val in {...} do
ba.print(val[1])
ba.print(tostring(val[2]))
done
end
]

#End
</pre>

Dynamic SEXPs

2018-01-02T18:29:15Z

M!m: Fix outdated example script

Since version 3.8.2 FSO supports adding custom SEXPs to a mod which have a user defined effect. Currently there is only one way to add such a SEXP but more may be added in the future.

Dynamic SEXPs are only added in modular table files which end with <tt>-sexp.tbm</tt>

=Table syntax=
This section will describe the syntax and effects of the individual options.

==#Lua SEXPs==

Specifies a list of dynamic SEXPs implemented using a Lua function (see [[#Lua interface|Lua interface]] for how to use the implementation function). This section must end with <tt>#End</tt>

===$Operator:===
*Adds a new SEXP operator with the specified name. The name may not contain the following characters: <tt>()\"'</tt>. Furthermore, any whitespace (tab characters or spaces) are also not permitted. This is the name under which this operator will appear in the SEXP code. While the name is mostly up to you it would be a good idea to keep it in line with how the other SEXPs are named. To avoid conflicts with other custom SEXPs you should also use a unique prefix. For example, if you want to have some SEXP operators that control a cloaking script then you could use <tt>cloak-</tt> as the common prefix for all the operators that are related to this system. A SEXP that disables the cloak system could be named something like <tt>cloak-disable</tt>.
*This name must be unique among all operators that are known to the SEXP system. That includes built-in SEXPs and operators added before. If there is a conflict then the new operator definition will be ignored. Built-in operators always take precedence.
*Syntax: '''''String'''''

===$Category:===
*Specifies in which category this SEXP will appear in the context menu in the FRED event editor. Only one of the existing categories may be used. These are all the currently defined categories:
**Objectives
**Time
**Logical
**Arithmetic
**Status
**Change
**Conditionals
**Ai goals
**Event/Goals
**Training
*Syntax: '''''String'''''

===$Subcategory:===
*Specifies into which subcategory this SEXP should be put. This is the second level in the context menu of the FRED event editor. New subcategories can be added by specifying a new name here but all subcategory names must be globally unique (you can't have the same subcategory name under two different categories).
*Syntax: '''''String'''''

===$Minimum Arguments:===
*Specifies ht minimum number of parameters this SEXP needs to work. If less parameters are specified then the SEXP parser will treat this as an error.
*Must be at least 0.
*Syntax: '''''Integer'''''

===$Maximum Arguments:===
*Specifies the maximum number of parameters this SEXP can process.
*Optional. If this option is not present then the SEXP can process an unlimited number of parameters.
*Must be at least 0 and greater or equal to $Minimum Arguments.

===$Return Type:===
*Specifies what data type this SEXP will return when invoked. Can be one of the following:
**; number: The SEXP will return an integer. The scripting function needs to return a number value.
**; boolean: The SEXP will return a boolean. The scripting function must return a boolean value.
**; nothing: The SEXP will return nothing. The scripting function may not return anything.
*Optional. Defaults to ''nothing''
*Syntax: '''''String'''''

===$Description:===
*Sets the help text displayed in the FRED help box. This should be the generic description of what this SEXP does but should not include the documentation for the individual parameters.
*Syntax: '''''String'''''

===$Repeat===
*This option must be combined with the parameter documentation below to specify a repeating pattern in a SEXP with a variable number of parameters. See the example below for how exactly this will work. All parameters specified after this option will be grouped together. The script will receive these groups of parameters as a single entity (see [[#Lua interface|Lua interface]]) to make it easier to use the values without having to separate them again in the script.

===$Parameter:===
*Adds documentation for the parameters and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by <tt>$Minimum Arguments</tt> and <tt>$Maximum Arguments</tt>.
*This option has no value.

====+Description:====
*Sets the description of this parameter. This will be used for the documentation text.
*Syntax: '''''String'''''

====+Type:====
*Sets the type this parameter requires. The currently supported types are:
**; number: This parameter is a number. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; boolean: This parameter is a boolean. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; ship: This parameter is the name of a ship. The script will receive this value as a <tt>ship</tt> handle. If the name provided by the mission is invalid (if the ship has not arrived yet or if it is not present anymore) then the script will receive an invalid <tt>ship</tt> handle.
**; string: This parameter is a generic string with no special format. In Unicode mode this string may contain Unicode characters.
**; team: This parameter is a handle to a specific team. The script will receive this value as a <tt>team</tt> handle.
**; waypointpath: This parameter is a reference to a specific waypoint path. The script will receive this as a <tt>waypointlist</tt> handle.
**; variable: This is a reference to a SEXP variable. This is a reference to the actual variable and not its contents. The script will receive this as a <tt>sexpvariable</tt> handle.
*Syntax: '''''String'''''

==Example==
<pre>
#Lua SEXPs

$Operator: dynamic-sexp
$Category: Change
$Subcategory: Scripted
$Minimum Arguments: 3
; No maximum arguments means that it accepts a variable number of arguments
$Return Type: Nothing
$Description: This is a dynamic parameter test SEXP
$Parameter:
+Description: Number parameter
+Type: Number
$Parameter:
+Description: Ship parameter
+Type: Ship
$Parameter:
+Description: Variable name parameter
+Type: variable
$Repeat ; This starts the part of the parameter list where the parameter pattern repeats
$Parameter:
+Description: Variable string parameter
+Type: string
$Parameter:
+Description: Variable number parameter
+Type: Number

#End
</pre>

=Lua interface=
So far, all the SEXP table has done is specify that a new Lua SEXP exists but there is no actual action which will be executed when the SEXP is called. For the Lua language this can be done using the <tt>mn.LuaSEXPs</tt> variable. This is a variable which can be indexed using the SEXP name. The returned value is of type <tt>LuaSEXP</tt> which only has a single field, <tt>Action</tt>. This is the function that will be executed once the SEXP is called in a mission. You can use it to retrieve the function of a LuaSEXP but the more common use case is that it is written in the <tt>$On Game Init</tt> hook to set the action function.

The action function will receive the values as normal parameters. If the SEXP will receive a variable number of parameters then you can use <tt>...</tt> as the last parameter to also capture these values. If a parameter is optional and not specified by the SEXP invocation then it will be <tt>nil</tt> in the script. Parameters in the repeat pattern of the parameter list will be grouped into a array of arrays where each array instance contains the individual values. See below for an example of how this can be handled in the Lua code.

<pre>
#Conditional Hooks

$Application: FS2_Open
$On Game Init: [
mn.LuaSEXPs["dynamic-sexp"].Action = function (arg1, arg2, arg3, ...)
ba.print(tostring(arg1)
ba.print(arg2.Name)
ba.print(tostring(mn.SEXPVariables[arg3].Value))

for val in {...} do
ba.print(val[1])
ba.print(tostring(val[2]))
done
end
]

#End
</pre>

SEXP

2017-12-27T11:25:36Z

M!m: Add link to the dynamic SEXPs page

'''Symbolic expressions''' (more commonly '''SEXPs''') are used by FreeSpace missions.

==See also==
*[[Retail SEXPs]] for SEXPs that are used by FreeSpace 2 v1.2.
*[[SCP SEXPs]] for SEXPs that were implemented by the [[Source Code Project]].
*[[Dynamic SEXPs]] for documentation on how to add custom SEXPs to a mod. These will appear as usual in the mission editor but the mod can define what the SEXP does.

{{stub}}

Dynamic SEXPs

2017-12-27T11:24:08Z

M!m: Update documentation of ship parameter type

Since version 3.8.2 FSO supports adding custom SEXPs to a mod which have a user defined effect. Currently there is only one way to add such a SEXP but more may be added in the future.

Dynamic SEXPs are only added in modular table files which end with <tt>-sexp.tbm</tt>

=Table syntax=
This section will describe the syntax and effects of the individual options.

==#Lua SEXPs==

Specifies a list of dynamic SEXPs implemented using a Lua function (see [[#Lua interface|Lua interface]] for how to use the implementation function). This section must end with <tt>#End</tt>

===$Operator:===
*Adds a new SEXP operator with the specified name. The name may not contain the following characters: <tt>()\"'</tt>. Furthermore, any whitespace (tab characters or spaces) are also not permitted. This is the name under which this operator will appear in the SEXP code. While the name is mostly up to you it would be a good idea to keep it in line with how the other SEXPs are named. To avoid conflicts with other custom SEXPs you should also use a unique prefix. For example, if you want to have some SEXP operators that control a cloaking script then you could use <tt>cloak-</tt> as the common prefix for all the operators that are related to this system. A SEXP that disables the cloak system could be named something like <tt>cloak-disable</tt>.
*This name must be unique among all operators that are known to the SEXP system. That includes built-in SEXPs and operators added before. If there is a conflict then the new operator definition will be ignored. Built-in operators always take precedence.
*Syntax: '''''String'''''

===$Category:===
*Specifies in which category this SEXP will appear in the context menu in the FRED event editor. Only one of the existing categories may be used. These are all the currently defined categories:
**Objectives
**Time
**Logical
**Arithmetic
**Status
**Change
**Conditionals
**Ai goals
**Event/Goals
**Training
*Syntax: '''''String'''''

===$Subcategory:===
*Specifies into which subcategory this SEXP should be put. This is the second level in the context menu of the FRED event editor. New subcategories can be added by specifying a new name here but all subcategory names must be globally unique (you can't have the same subcategory name under two different categories).
*Syntax: '''''String'''''

===$Minimum Arguments:===
*Specifies ht minimum number of parameters this SEXP needs to work. If less parameters are specified then the SEXP parser will treat this as an error.
*Must be at least 0.
*Syntax: '''''Integer'''''

===$Maximum Arguments:===
*Specifies the maximum number of parameters this SEXP can process.
*Optional. If this option is not present then the SEXP can process an unlimited number of parameters.
*Must be at least 0 and greater or equal to $Minimum Arguments.

===$Return Type:===
*Specifies what data type this SEXP will return when invoked. Can be one of the following:
**; number: The SEXP will return an integer. The scripting function needs to return a number value.
**; boolean: The SEXP will return a boolean. The scripting function must return a boolean value.
**; nothing: The SEXP will return nothing. The scripting function may not return anything.
*Optional. Defaults to ''nothing''
*Syntax: '''''String'''''

===$Description:===
*Sets the help text displayed in the FRED help box. This should be the generic description of what this SEXP does but should not include the documentation for the individual parameters.
*Syntax: '''''String'''''

===$Repeat===
*This option must be combined with the parameter documentation below to specify a repeating pattern in a SEXP with a variable number of parameters. See the example below for how exactly this will work. All parameters specified after this option will be grouped together. The script will receive these groups of parameters as a single entity (see [[#Lua interface|Lua interface]]) to make it easier to use the values without having to separate them again in the script.

===$Parameter:===
*Adds documentation for the parameters and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by <tt>$Minimum Arguments</tt> and <tt>$Maximum Arguments</tt>.
*This option has no value.

====+Description:====
*Sets the description of this parameter. This will be used for the documentation text.
*Syntax: '''''String'''''

====+Type:====
*Sets the type this parameter requires. The currently supported types are:
**; number: This parameter is a number. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; boolean: This parameter is a boolean. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; ship: This parameter is the name of a ship. The script will receive this value as a <tt>ship</tt> handle. If the name provided by the mission is invalid (if the ship has not arrived yet or if it is not present anymore) then the script will receive an invalid <tt>ship</tt> handle.
**; string: This parameter is a generic string with no special format. In Unicode mode this string may contain Unicode characters.
**; team: This parameter is a handle to a specific team. The script will receive this value as a <tt>team</tt> handle.
**; waypointpath: This parameter is a reference to a specific waypoint path. The script will receive this as a <tt>waypointlist</tt> handle.
**; variable: This is a reference to a SEXP variable. This is a reference to the actual variable and not its contents. The script will receive this as a <tt>sexpvariable</tt> handle.
*Syntax: '''''String'''''

==Example==
<pre>
#Lua SEXPs

$Operator: dynamic-sexp
$Category: Change
$Subcategory: Scripted
$Minimum Arguments: 3
; No maximum arguments means that it accepts a variable number of arguments
$Return Type: Nothing
$Description: This is a dynamic parameter test SEXP
$Parameter:
+Description: Number parameter
+Type: Number
$Parameter:
+Description: Ship parameter
+Type: Ship
$Parameter:
+Description: Variable name parameter
+Type: variable
$Repeat ; This starts the part of the parameter list where the parameter pattern repeats
$Parameter:
+Description: Variable string parameter
+Type: string
$Parameter:
+Description: Variable number parameter
+Type: Number

#End
</pre>

=Lua interface=
So far, all the SEXP table has done is specify that a new Lua SEXP exists but there is no actual action which will be executed when the SEXP is called. For the Lua language this can be done using the <tt>mn.LuaSEXPs</tt> variable. This is a variable which can be indexed using the SEXP name. The returned value is of type <tt>LuaSEXP</tt> which only has a single field, <tt>Action</tt>. This is the function that will be executed once the SEXP is called in a mission. You can use it to retrieve the function of a LuaSEXP but the more common use case is that it is written in the <tt>$On Game Init</tt> hook to set the action function.

The action function will receive the values as normal parameters. If the SEXP will receive a variable number of parameters then you can use <tt>...</tt> as the last parameter to also capture these values. If a parameter is optional and not specified by the SEXP invocation then it will be <tt>nil</tt> in the script. Parameters in the repeat pattern of the parameter list will be grouped into a array of arrays where each array instance contains the individual values. See below for an example of how this can be handled in the Lua code.

<pre>
#Conditional Hooks

$Application: FS2_Open
$On Game Init: [
mn.LuaSEXPs["dynamic-sexp"].Action = function (arg1, arg2, arg3, ...)
ba.print(tostring(arg1)
ba.print(mn.Ships[arg2].Name)
ba.print(tostring(mn.SEXPVariables[arg3].Value))

for val in {...} do
ba.print(val[1])
ba.print(tostring(val[2]))
done
end
]

#End
</pre>

Dynamic SEXPs

2017-12-21T14:16:27Z

M!m: Add clarification for why ships are passed as strings

Since version 3.8.2 FSO supports adding custom SEXPs to a mod which have a user defined effect. Currently there is only one way to add such a SEXP but more may be added in the future.

Dynamic SEXPs are only added in modular table files which end with <tt>-sexp.tbm</tt>

=Table syntax=
This section will describe the syntax and effects of the individual options.

==#Lua SEXPs==

Specifies a list of dynamic SEXPs implemented using a Lua function (see [[#Lua interface|Lua interface]] for how to use the implementation function). This section must end with <tt>#End</tt>

===$Operator:===
*Adds a new SEXP operator with the specified name. The name may not contain the following characters: <tt>()\"'</tt>. Furthermore, any whitespace (tab characters or spaces) are also not permitted. This is the name under which this operator will appear in the SEXP code. While the name is mostly up to you it would be a good idea to keep it in line with how the other SEXPs are named. To avoid conflicts with other custom SEXPs you should also use a unique prefix. For example, if you want to have some SEXP operators that control a cloaking script then you could use <tt>cloak-</tt> as the common prefix for all the operators that are related to this system. A SEXP that disables the cloak system could be named something like <tt>cloak-disable</tt>.
*This name must be unique among all operators that are known to the SEXP system. That includes built-in SEXPs and operators added before. If there is a conflict then the new operator definition will be ignored. Built-in operators always take precedence.
*Syntax: '''''String'''''

===$Category:===
*Specifies in which category this SEXP will appear in the context menu in the FRED event editor. Only one of the existing categories may be used. These are all the currently defined categories:
**Objectives
**Time
**Logical
**Arithmetic
**Status
**Change
**Conditionals
**Ai goals
**Event/Goals
**Training
*Syntax: '''''String'''''

===$Subcategory:===
*Specifies into which subcategory this SEXP should be put. This is the second level in the context menu of the FRED event editor. New subcategories can be added by specifying a new name here but all subcategory names must be globally unique (you can't have the same subcategory name under two different categories).
*Syntax: '''''String'''''

===$Minimum Arguments:===
*Specifies ht minimum number of parameters this SEXP needs to work. If less parameters are specified then the SEXP parser will treat this as an error.
*Must be at least 0.
*Syntax: '''''Integer'''''

===$Maximum Arguments:===
*Specifies the maximum number of parameters this SEXP can process.
*Optional. If this option is not present then the SEXP can process an unlimited number of parameters.
*Must be at least 0 and greater or equal to $Minimum Arguments.

===$Return Type:===
*Specifies what data type this SEXP will return when invoked. Can be one of the following:
**; number: The SEXP will return an integer. The scripting function needs to return a number value.
**; boolean: The SEXP will return a boolean. The scripting function must return a boolean value.
**; nothing: The SEXP will return nothing. The scripting function may not return anything.
*Optional. Defaults to ''nothing''
*Syntax: '''''String'''''

===$Description:===
*Sets the help text displayed in the FRED help box. This should be the generic description of what this SEXP does but should not include the documentation for the individual parameters.
*Syntax: '''''String'''''

===$Repeat===
*This option must be combined with the parameter documentation below to specify a repeating pattern in a SEXP with a variable number of parameters. See the example below for how exactly this will work. All parameters specified after this option will be grouped together. The script will receive these groups of parameters as a single entity (see [[#Lua interface|Lua interface]]) to make it easier to use the values without having to separate them again in the script.

===$Parameter:===
*Adds documentation for the parameters and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by <tt>$Minimum Arguments</tt> and <tt>$Maximum Arguments</tt>.
*This option has no value.

====+Description:====
*Sets the description of this parameter. This will be used for the documentation text.
*Syntax: '''''String'''''

====+Type:====
*Sets the type this parameter requires. The currently supported types are:
**; number: This parameter is a number. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; boolean: This parameter is a boolean. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; ship: This parameter is the name of a ship. The script will receive this value as a string which is the ship name. <tt>mn.Ships</tt> can be used for getting a ship handle from the name. The name may produce an invalid handle if the ship does not exist or is no longer present in the mission. This is done to pass as much information about the ship to the script as possible since the invalid name can still be used by the script while an invalid <tt>ship</tt> handle is not very useful after determining that it is invalid.
**; string: This parameter is a generic string with no special format. In Unicode mode this string may contain Unicode characters.
**; team: This parameter is a handle to a specific team. The script will receive this value as a <tt>team</tt> handle.
**; waypointpath: This parameter is a reference to a specific waypoint path. The script will receive this as a <tt>waypointlist</tt> handle.
**; variable: This is a reference to a SEXP variable. This is a reference to the actual variable and not its contents. The script will receive this as a <tt>sexpvariable</tt> handle.
*Syntax: '''''String'''''

==Example==
<pre>
#Lua SEXPs

$Operator: dynamic-sexp
$Category: Change
$Subcategory: Scripted
$Minimum Arguments: 3
; No maximum arguments means that it accepts a variable number of arguments
$Return Type: Nothing
$Description: This is a dynamic parameter test SEXP
$Parameter:
+Description: Number parameter
+Type: Number
$Parameter:
+Description: Ship parameter
+Type: Ship
$Parameter:
+Description: Variable name parameter
+Type: variable
$Repeat ; This starts the part of the parameter list where the parameter pattern repeats
$Parameter:
+Description: Variable string parameter
+Type: string
$Parameter:
+Description: Variable number parameter
+Type: Number

#End
</pre>

=Lua interface=
So far, all the SEXP table has done is specify that a new Lua SEXP exists but there is no actual action which will be executed when the SEXP is called. For the Lua language this can be done using the <tt>mn.LuaSEXPs</tt> variable. This is a variable which can be indexed using the SEXP name. The returned value is of type <tt>LuaSEXP</tt> which only has a single field, <tt>Action</tt>. This is the function that will be executed once the SEXP is called in a mission. You can use it to retrieve the function of a LuaSEXP but the more common use case is that it is written in the <tt>$On Game Init</tt> hook to set the action function.

The action function will receive the values as normal parameters. If the SEXP will receive a variable number of parameters then you can use <tt>...</tt> as the last parameter to also capture these values. If a parameter is optional and not specified by the SEXP invocation then it will be <tt>nil</tt> in the script. Parameters in the repeat pattern of the parameter list will be grouped into a array of arrays where each array instance contains the individual values. See below for an example of how this can be handled in the Lua code.

<pre>
#Conditional Hooks

$Application: FS2_Open
$On Game Init: [
mn.LuaSEXPs["dynamic-sexp"].Action = function (arg1, arg2, arg3, ...)
ba.print(tostring(arg1)
ba.print(mn.Ships[arg2].Name)
ba.print(tostring(mn.SEXPVariables[arg3].Value))

for val in {...} do
ba.print(val[1])
ba.print(tostring(val[2]))
done
end
]

#End
</pre>

Dynamic SEXPs

2017-12-21T11:12:35Z

M!m: Add initial Dynamic SEXPs documentation

Since version 3.8.2 FSO supports adding custom SEXPs to a mod which have a user defined effect. Currently there is only one way to add such a SEXP but more may be added in the future.

Dynamic SEXPs are only added in modular table files which end with <tt>-sexp.tbm</tt>

=Table syntax=
This section will describe the syntax and effects of the individual options.

==#Lua SEXPs==

Specifies a list of dynamic SEXPs implemented using a Lua function (see [[#Lua interface|Lua interface]] for how to use the implementation function). This section must end with <tt>#End</tt>

===$Operator:===
*Adds a new SEXP operator with the specified name. The name may not contain the following characters: <tt>()\"'</tt>. Furthermore, any whitespace (tab characters or spaces) are also not permitted. This is the name under which this operator will appear in the SEXP code. While the name is mostly up to you it would be a good idea to keep it in line with how the other SEXPs are named. To avoid conflicts with other custom SEXPs you should also use a unique prefix. For example, if you want to have some SEXP operators that control a cloaking script then you could use <tt>cloak-</tt> as the common prefix for all the operators that are related to this system. A SEXP that disables the cloak system could be named something like <tt>cloak-disable</tt>.
*This name must be unique among all operators that are known to the SEXP system. That includes built-in SEXPs and operators added before. If there is a conflict then the new operator definition will be ignored. Built-in operators always take precedence.
*Syntax: '''''String'''''

===$Category:===
*Specifies in which category this SEXP will appear in the context menu in the FRED event editor. Only one of the existing categories may be used. These are all the currently defined categories:
**Objectives
**Time
**Logical
**Arithmetic
**Status
**Change
**Conditionals
**Ai goals
**Event/Goals
**Training
*Syntax: '''''String'''''

===$Subcategory:===
*Specifies into which subcategory this SEXP should be put. This is the second level in the context menu of the FRED event editor. New subcategories can be added by specifying a new name here but all subcategory names must be globally unique (you can't have the same subcategory name under two different categories).
*Syntax: '''''String'''''

===$Minimum Arguments:===
*Specifies ht minimum number of parameters this SEXP needs to work. If less parameters are specified then the SEXP parser will treat this as an error.
*Must be at least 0.
*Syntax: '''''Integer'''''

===$Maximum Arguments:===
*Specifies the maximum number of parameters this SEXP can process.
*Optional. If this option is not present then the SEXP can process an unlimited number of parameters.
*Must be at least 0 and greater or equal to $Minimum Arguments.

===$Return Type:===
*Specifies what data type this SEXP will return when invoked. Can be one of the following:
**; number: The SEXP will return an integer. The scripting function needs to return a number value.
**; boolean: The SEXP will return a boolean. The scripting function must return a boolean value.
**; nothing: The SEXP will return nothing. The scripting function may not return anything.
*Optional. Defaults to ''nothing''
*Syntax: '''''String'''''

===$Description:===
*Sets the help text displayed in the FRED help box. This should be the generic description of what this SEXP does but should not include the documentation for the individual parameters.
*Syntax: '''''String'''''

===$Repeat===
*This option must be combined with the parameter documentation below to specify a repeating pattern in a SEXP with a variable number of parameters. See the example below for how exactly this will work. All parameters specified after this option will be grouped together. The script will receive these groups of parameters as a single entity (see [[#Lua interface|Lua interface]]) to make it easier to use the values without having to separate them again in the script.

===$Parameter:===
*Adds documentation for the parameters and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by <tt>$Minimum Arguments</tt> and <tt>$Maximum Arguments</tt>.
*This option has no value.

====+Description:====
*Sets the description of this parameter. This will be used for the documentation text.
*Syntax: '''''String'''''

====+Type:====
*Sets the type this parameter requires. The currently supported types are:
**; number: This parameter is a number. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; boolean: This parameter is a boolean. The SEXP system will evaluate the expression for this parameter (which may be another SEXP operator) and pass the result to the script.
**; ship: This parameter is the name of a ship. The script will receive this value as a string which is the ship name. <tt>mn.Ships</tt> can be used for getting a ship handle from the name. The name may be invalid if the ship does not exist or is no longer present in the mission.
**; string: This parameter is a generic string with no special format. In Unicode mode this string may contain Unicode characters.
**; team: This parameter is a handle to a specific team. The script will receive this value as a <tt>team</tt> handle.
**; waypointpath: This parameter is a reference to a specific waypoint path. The script will receive this as a <tt>waypointlist</tt> handle.
**; variable: This is a reference to a SEXP variable. This is a reference to the actual variable and not its contents. The script will receive this as a <tt>sexpvariable</tt> handle.
*Syntax: '''''String'''''

==Example==
<pre>
#Lua SEXPs

$Operator: dynamic-sexp
$Category: Change
$Subcategory: Scripted
$Minimum Arguments: 3
; No maximum arguments means that it accepts a variable number of arguments
$Return Type: Nothing
$Description: This is a dynamic parameter test SEXP
$Parameter:
+Description: Number parameter
+Type: Number
$Parameter:
+Description: Ship parameter
+Type: Ship
$Parameter:
+Description: Variable name parameter
+Type: variable
$Repeat ; This starts the part of the parameter list where the parameter pattern repeats
$Parameter:
+Description: Variable string parameter
+Type: string
$Parameter:
+Description: Variable number parameter
+Type: Number

#End
</pre>

=Lua interface=
So far, all the SEXP table has done is specify that a new Lua SEXP exists but there is no actual action which will be executed when the SEXP is called. For the Lua language this can be done using the <tt>mn.LuaSEXPs</tt> variable. This is a variable which can be indexed using the SEXP name. The returned value is of type <tt>LuaSEXP</tt> which only has a single field, <tt>Action</tt>. This is the function that will be executed once the SEXP is called in a mission. You can use it to retrieve the function of a LuaSEXP but the more common use case is that it is written in the <tt>$On Game Init</tt> hook to set the action function.

The action function will receive the values as normal parameters. If the SEXP will receive a variable number of parameters then you can use <tt>...</tt> as the last parameter to also capture these values. If a parameter is optional and not specified by the SEXP invocation then it will be <tt>nil</tt> in the script. Parameters in the repeat pattern of the parameter list will be grouped into a array of arrays where each array instance contains the individual values. See below for an example of how this can be handled in the Lua code.

<pre>
#Conditional Hooks

$Application: FS2_Open
$On Game Init: [
mn.LuaSEXPs["dynamic-sexp"].Action = function (arg1, arg2, arg3, ...)
ba.print(tostring(arg1)
ba.print(mn.Ships[arg2].Name)
ba.print(tostring(mn.SEXPVariables[arg3].Value))

for val in {...} do
ba.print(val[1])
ba.print(tostring(val[2]))
done
end
]

#End
</pre>

Game settings.tbl

2017-12-20T11:44:53Z

M!m: Add documentation for $Enable scripting in FRED

{{SCP_table}}

{{TableVersionGit|2015-12-03|5d8f779}}

The '''game_settings.tbl''', also known as mod.tbl, defines options that can be changed globally.

This table is one of the [[Modular Tables]] and can be extended with xxx-mod.tbm

[[Tables|List of Tables]]

==#GAME SETTINGS==
Optional. Contains settings that affect how the engine works. 

===$Target Version:===
{{Table373|
Specifies the minimum version of FreeSpace Open that this mod supports. If the version specified here is greater than the version of the current build, an error message is displayed.
}}
{{Table381|
The $Minimum version option has been renamed to $Target Version. The old name is kept with the same functionality for backwards-compatibility.

The target version specifies what version of the FSO engine this mod was created for. It will be used by the engine to enable or disable backwards-incompatible changes by default. The default value is 2.0 which specifies that the mod targets the retail engine version.
}}

====+Major:====
{{Table373|
Required. Sets the major component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Minor:====
{{Table373|
Required. Sets the minor component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''7''''' (for a minimum version of 3.7.3.20151121)
}}

====+Build:====
{{Table373|
Required. Sets the build component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Revision:====
{{Table373|
Optional. Sets the revision component of the target version. If no revision is given then all builds of that release are supported (even nightly builds if there are any).
For nightly builds this is the date in YYYYMMDD format.
*Syntax: '''''Integer''''' 
*Example: '''''20151121''''' (for a minimum version of 3.7.3.20151121)
}}

===$Window title:===
{{Table382|
Specifies the name of the FSO window when this mod is running. If blank or unspecified, the window will have the default title of "FreeSpace 2".
*Syntax: '''''String'''''
}}

===$Unicode mode:===
{{Table382|
Enabled the Unicode text mode for this mod. In Unicode mode all text is assumed to be UTF-8 encoded Unicode and certain features are disabled if they do not have full Unicode support. Most notably, if this is enabled then the engine will no longer support the old bitmap fonts that were used by Retail FreeSpace. Only the newer TrueType fonts will be supported.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

==#CAMPAIGN SETTINGS==
Optional. This group contains various Campaign related settings and overrides. 

===$Default Campaign File Name:===
Defines which campaign will be selected by default for new pilots. A file extension is not needed and, if present, is removed by the code.
*Syntax: '''''String''''' 

===#Ignored Campaign File Names===
Optional. Defines which campaigns, if present, will not appear in the Campaign Room. Only single-player campaigns can be ignored. ''File extensions are required.''
{{Table371|As of 3.7.1, file extensions are not required and, if present, are removed by the code.}}
====$Campaign File Name:====
File name of the campaign to ignore. Multiple entries may exist.
*Syntax: '''''String''''' 

===$Red-alert applies to delayed ships:===
Controls whether red-alert saved statistics (hitpoints, weapons, subsystem strengths) will be restored for ships that are not present at mission start.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#HUD SETTINGS==
Optional. This group contains various HUD behavior settings and overrides 

===$Directive Wait Time:===
*Defines how long the game will wait before displaying a directive.
*Syntax: '''''Integer''''' 
*Values: '''''Greater than or equal to 0 ms'''''

===$Cutscene camera displays HUD:===
Show the HUD when the cutscene camera is enabled.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Cutscene camera disables HUD: and had a default of YES.

===$Full color head animations:===
Enables full-color head ANIs. Normal head ANIs will appear in gray.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Color head animations with hud colors: and had a default of YES.

==#SEXP SETTINGS==
Optional. This group contains SEXP settings and overrides. 

===$Loop SEXPs Then Arguments:===
Flips how when-argument settings loop. See: [http://www.hard-light.net/forums/index.php?topic=79602.0 SEXP Argument changes via mod.tbl]
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

===$Use Alternate Chaining Behavior:===
When set, this makes the event chaining behavior act as people expected it to be in [http://scp.indiegames.us/mantis/view.php?id=82 Mantis #82].
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#GRAPHICS SETTINGS==
Optional. This group contains settings related to graphics. 

===$Enable External Shaders:===
Enables the use of external shader files. By default, the engine will use the built-in shaders.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default Detail Level:===
{{Table3615|
Determines which graphics detail level preset (low, medium, high, very high) acts as the default for new pilots.
*Syntax: '''''Integer''''' (0-3)
*Default Value: '''''3''''' (very high) }}

===$Briefing Window FOV:===
{{Table371|
Determines the FOV in the briefing Icon window. Retail default for this is 0.29375, previous versions of FSO used a value of 0.5.
*Syntax: '''''Float''''' (0.0 to 1.0)
*Default Value: '''''0.29375''''' }}

===$Generic Pain Flash Factor:===
{{Table373|
Determines the intensity of the pain red flash when the player is hit.
*Syntax: '''''Float'''''
*Default Value: '''''1.0''''' }}

===$Shield Pain Flash Factor:===
{{Table373|
Determines the intensity of a pain flash when the player's shields are hit. Color will match the current ships shield color defined in ships.tbl. A value of 0 will give retail behavior (no shield effect). Positive values will cause the effect to start at full intensity at full shields and go to next to no intensity at zero shields. Negative values will cause no effect at full shields and full effect at no shields. Values should be kept between -1.0 and 1.0 for good pilot visibility.
*Syntax: '''''Float'''''
*Default Value: '''''0.0''''' }}

===$BMPMAN Slot Limit:===
{{Table382|
Determines the maximum number of textures that can be loaded simultaneously. This includes every frame of an animation, unless that animation is streaming (e.g. command briefing animations, message talking heads, etc). Also includes dynamically-created textures (used internally for various functions).
*Syntax: '''''Int'''''
*Values: '''''Greater than or equal to 3500'''''
*Default Value: '''''4750''''' }}

==#SOUND SETTINGS==
Optional. This group contains sound-related settings 

===$Default Sound Volume:===
{{Table371|
*Defines the default sound fx volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''1.0'''''}}

===$Default Music Volume:===
{{Table371|
*Defines the default music volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.5'''''}}

===$Default Voice Volume:===
{{Table371|
*Defines the default voice volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.7'''''}}

==#FRED SETTINGS==
Optional. This group contains settings for FRED. 

===$Disable Hard Coded Message Head Ani Files:===
{{table371|
If set, FRED will not fill the head ani selection in the Event Editor with the retail head ani filenames.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' }}

===$Enable scripting in FRED:===
{{table382|
If set, scripting will be enabled in FRED. Use with extreme caution. The effects of scripts on FRED have not been fully tested. You can check if a script is running in FRED by using ba.inMissionEditor().
*Default Value: '''''NO''''' }}

==#OTHER SETTINGS==
Optional. This group contains miscellaneous settings. 

===$Fixed Turret Collisions:===
Makes all hits to a turret's barrels count as hits to the turret subsystem. By default, this does not happen unless the point of impact falls inside the model radius of the turret's base.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Damage Impacted Subsystem First:===
If set, a hit to a physical subsystem will always deal damage to that subsystem first, even if another subsystem is closer to the point of impact. By default, the closest subsystem will always receive damage first.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default ship select effect:===
{{Table3615|
*This specifies which effect to use for ship select animations when no .ani can be found, or the -ship_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Default weapon select effect:===
{{Table3615|
*This specifies which effect to use for weapon select animations when no .ani can be found, or the -weapon_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Weapons inherit parent collision group:===
{{Table3615|
*When set to true, Weapons fired by a ship will inherit their parents' collision group setting. Default is false.}}

===$Flight controls follow eyepoint orientation:===
{{Table371|
*Specifies that if the player ship's eyepoint happens to rotate into a non-standard orientation, pitch and yaw axes should stay relative to the eyepoint orientation, not the ship. Note that this does not affect the pitch/yaw turning speed, which always remains relative to the ship. Default is false.}}

===$Beams Use Damage Factors:===
{{Table371|
*Specifies that beam weapons will use the tabled damage factors for Armour, Shields and Subsystems. Default is false (i.e. all factors are treated as 1.0)}}

===$Default fiction viewer UI:===
{{Table373|
*Specifies which fiction viewer layout to use in missions that don't specify one. Possible values are as follows:
**"FS2": Standard layout. Requires (2_)fictionviewer and (2_)fictionviewer-m to be present in data\interface.
**"WCS": Moves the "Accept" button to the lower-left corner of the screen. Requires (2_)fictionviewerb and (2_)fictionviewer-mb to be present in data\interface.
**"auto": Selects "WCS" if the appropriate files are present; otherwise, selects "FS2". This is the default setting.}}

==#END==
Required. The last line of the table must be #END

==Sample Entry==

#CAMPAIGN SETTINGS
$Default Campaign File Name: NewCampaignFile

#Ignored Campaign File Names
$Campaign File Name: FreeSpace2.fc2

#HUD SETTINGS
$Directive Wait Time: 5000

#SEXP SETTINGS
$Loop SEXPs Then Arguments: True

#OTHER SETTINGS
$Fix Turret Collisions: True

#END

[[Category:Tables]]

Fonts.tbl

2017-12-03T17:43:13Z

M!m: Add documentation for changes introduced by the Unicode mode.

{{SCP_table}}

{{TableVersionGit|2016-08-02|b4db345}}

The '''fonts.tbl''' is a recent addition to the SCP allowing the definition of non-standard fonts. The number of possible fonts is unlimited. The HUD gauges, show-subtitle-text sexp and the [[Fiction Viewer|fiction viewer]] can be manually set to any font in fonts.tbl. The rest of the fonts used in FSO (e.g. techroom text) are hardcoded to one of the first three fonts that are parsed.

This table is one of the [[Modular Tables]] and can be extended with xxx-fnt.tbm

[[Tables|List of Tables]]

==General Info==
*Begins with #Fonts
*Consists of at least 3 entries
*Ends with #End

Currently, there are two different types of supported fonts. The old "VFNT" type (which probably means '''V'''olition '''F'''o'''nt''') and the new TrueType Fonts. The old font use the usual ''$Font:'' option while the new fonts use ''$TrueType:''.

===$Font:===
*Lists a font file to use.
*This font type is not supported if the engine is in [[Game_settings.tbl#$Unicode mode:|Unicode text mode]]!
*Syntax: '''String'''

====+Name:====
{{Table38|
*Sets the name of this font. Defaults to the specified filename if not provided.
*Syntax: '''String'''
}}

====+Default Special Character Index:====
{{Table372|
*Specifies the index of the first special character (e.g., infinity symbol, "match speed" icon) in the font. Must be within the range of 0-249. Does not apply to language entries below that use [[Fonts.tbl#+Special Character Index:|+Special Character Index:]].
*Syntax: '''Integer'''
{{Note|If this parameter is used with the first font, it will override all uses of +Special Character Index: in [[strings.tbl]].}}
}}

====+Language:====
{{Table372|
*Specifies the name of a language.
*Currently used for overriding the value of [[Fonts.tbl#+Default Special Character Index:|+Default Special Character Index:]].
*Syntax: '''String'''

=====+Special Character Index:=====
*Overrides the value of [[Fonts.tbl#+Default Special Character Index:|+Default Special Character Index:]] for this language.
*Syntax: '''Integer'''
}}

====+Top offset:====
{{Table38|
*Specifies the top offset for this font. See [[Fonts.tbl|Top and Bottom offsets]] for more information.
*Syntax: '''float'''
}}

====+Bottom offset:====
{{Table38|
*Specifies the bottom offset for this font. See [[Fonts.tbl|Top and Bottom offsets]] for more information.
*Syntax: '''float'''
}}

===$TrueType:===
{{Table38|
*Lists a font file to use.
*Syntax: '''String'''
}}

====+Name:====
{{Table38|
*Specifies the name of this font, defaults to '''<fontFilename>-<fontSize>'''
*Syntax: '''String'''
}}

====+Size:====
{{Table38|
*Specifies the size of the font, defaults to 8.
*Syntax: '''float''', must be greater than 0
}}

====+Top offset:====
{{Table38|
*Specifies the top offset for this font. See [[Fonts.tbl|Top and Bottom offsets]] for more information.
*Syntax: '''float'''
}}

====+Bottom offset:====
{{Table38|
*Specifies the bottom offset for this font. See [[Fonts.tbl|Top and Bottom offsets]] for more information.
*Syntax: '''float'''
}}

====+Letter spacing:====
{{Table38|
*Specifies the letter spacing. Defaults to 0.
*Syntax: '''float''', must be greater or equal to 0.
}}

====+Special Character Font:====
{{Table38|
*Specifies the VFNT file to use for the special characters. FSO uses a few special characters for a few things that are not present in standard TrueType fonts. To fix this you can specify a VFNT file from which these characters are loaded. This defaults to '''font01.vf''' which is a default font file from FS2 retail.
*This option not needed and not supported if the engine is in [[Game_settings.tbl#$Unicode mode:|Unicode text mode]]!
*Syntax: '''String'''
}}

==Top and Bottom offsets==
The top and bottom offsets can be used to influence the line spacing for a specific font. Before rendering '''top offset''' vertical pixels are skipped. Then the text is rendered and then another '''bottom offset''' pixels are skipped.

==Sample Entry==
<pre>
#Fonts

$Font: font01.vf
$Font: font02.vf
$Font: font03.vf

$TrueType: arial.ttf
+Name: Arial
+Size: 12

#End
</pre>
==Sample Entry (Fiction Viewer)==
<pre>
#Fiction Viewer

$File: [text file]
$Font: [font file]
</pre>

== References ==
# "[http://www.hard-light.net/forums/index.php?topic=66942.msg1327152#msg1327152 Re: Feature Request: 4th font (especially for fiction viewer)]", ''Hard Light Productions Forums'', Hard Light Productions, 24-12-2009. Retrieved on January 28, 2011.

[[Category:Tables]]

Game settings.tbl

2017-12-03T17:39:44Z

M!m: Add documentation for $Unicode mode

{{SCP_table}}

{{TableVersionGit|2015-12-03|5d8f779}}

The '''game_settings.tbl''', also known as mod.tbl, defines options that can be changed globally.

This table is one of the [[Modular Tables]] and can be extended with xxx-mod.tbm

[[Tables|List of Tables]]

==#GAME SETTINGS==
Optional. Contains settings that affect how the engine works. 

===$Target Version:===
{{Table373|
Specifies the minimum version of FreeSpace Open that this mod supports. If the version specified here is greater than the version of the current build, an error message is displayed.
}}
{{Table381|
The $Minimum version option has been renamed to $Target Version. The old name is kept with the same functionality for backwards-compatibility.

The target version specifies what version of the FSO engine this mod was created for. It will be used by the engine to enable or disable backwards-incompatible changes by default. The default value is 2.0 which specifies that the mod targets the retail engine version.
}}

====+Major:====
{{Table373|
Required. Sets the major component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Minor:====
{{Table373|
Required. Sets the minor component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''7''''' (for a minimum version of 3.7.3.20151121)
}}

====+Build:====
{{Table373|
Required. Sets the build component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Revision:====
{{Table373|
Optional. Sets the revision component of the target version. If no revision is given then all builds of that release are supported (even nightly builds if there are any).
For nightly builds this is the date in YYYYMMDD format.
*Syntax: '''''Integer''''' 
*Example: '''''20151121''''' (for a minimum version of 3.7.3.20151121)
}}

===$Window title:===
{{Table382|
Specifies the name of the FSO window when this mod is running. If blank or unspecified, the window will have the default title of "FreeSpace 2".
*Syntax: '''''String'''''
}}

===$Unicode mode:===
{{Table382|
Enabled the Unicode text mode for this mod. In Unicode mode all text is assumed to be UTF-8 encoded Unicode and certain features are disabled if they do not have full Unicode support. Most notably, if this is enabled then the engine will no longer support the old bitmap fonts that were used by Retail FreeSpace. Only the newer TrueType fonts will be supported.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO'''''
}}

==#CAMPAIGN SETTINGS==
Optional. This group contains various Campaign related settings and overrides. 

===$Default Campaign File Name:===
Defines which campaign will be selected by default for new pilots. A file extension is not needed and, if present, is removed by the code.
*Syntax: '''''String''''' 

===#Ignored Campaign File Names===
Optional. Defines which campaigns, if present, will not appear in the Campaign Room. Only single-player campaigns can be ignored. ''File extensions are required.''
{{Table371|As of 3.7.1, file extensions are not required and, if present, are removed by the code.}}
====$Campaign File Name:====
File name of the campaign to ignore. Multiple entries may exist.
*Syntax: '''''String''''' 

===$Red-alert applies to delayed ships:===
Controls whether red-alert saved statistics (hitpoints, weapons, subsystem strengths) will be restored for ships that are not present at mission start.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#HUD SETTINGS==
Optional. This group contains various HUD behavior settings and overrides 

===$Directive Wait Time:===
*Defines how long the game will wait before displaying a directive.
*Syntax: '''''Integer''''' 
*Values: '''''Greater than or equal to 0 ms'''''

===$Cutscene camera displays HUD:===
Show the HUD when the cutscene camera is enabled.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Cutscene camera disables HUD: and had a default of YES.

===$Full color head animations:===
Enables full-color head ANIs. Normal head ANIs will appear in gray.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Color head animations with hud colors: and had a default of YES.

==#SEXP SETTINGS==
Optional. This group contains SEXP settings and overrides. 

===$Loop SEXPs Then Arguments:===
Flips how when-argument settings loop. See: [http://www.hard-light.net/forums/index.php?topic=79602.0 SEXP Argument changes via mod.tbl]
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

===$Use Alternate Chaining Behavior:===
When set, this makes the event chaining behavior act as people expected it to be in [http://scp.indiegames.us/mantis/view.php?id=82 Mantis #82].
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#GRAPHICS SETTINGS==
Optional. This group contains settings related to graphics. 

===$Enable External Shaders:===
Enables the use of external shader files. By default, the engine will use the built-in shaders.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default Detail Level:===
{{Table3615|
Determines which graphics detail level preset (low, medium, high, very high) acts as the default for new pilots.
*Syntax: '''''Integer''''' (0-3)
*Default Value: '''''3''''' (very high) }}

===$Briefing Window FOV:===
{{Table371|
Determines the FOV in the briefing Icon window. Retail default for this is 0.29375, previous versions of FSO used a value of 0.5.
*Syntax: '''''Float''''' (0.0 to 1.0)
*Default Value: '''''0.29375''''' }}

===$Generic Pain Flash Factor:===
{{Table373|
Determines the intensity of the pain red flash when the player is hit.
*Syntax: '''''Float'''''
*Default Value: '''''1.0''''' }}

===$Shield Pain Flash Factor:===
{{Table373|
Determines the intensity of a pain flash when the player's shields are hit. Color will match the current ships shield color defined in ships.tbl. A value of 0 will give retail behavior (no shield effect). Positive values will cause the effect to start at full intensity at full shields and go to next to no intensity at zero shields. Negative values will cause no effect at full shields and full effect at no shields. Values should be kept between -1.0 and 1.0 for good pilot visibility.
*Syntax: '''''Float'''''
*Default Value: '''''0.0''''' }}

===$BMPMAN Slot Limit:===
{{Table382|
Determines the maximum number of textures that can be loaded simultaneously. This includes every frame of an animation, unless that animation is streaming (e.g. command briefing animations, message talking heads, etc). Also includes dynamically-created textures (used internally for various functions).
*Syntax: '''''Int'''''
*Values: '''''Greater than or equal to 3500'''''
*Default Value: '''''4750''''' }}

==#SOUND SETTINGS==
Optional. This group contains sound-related settings 

===$Default Sound Volume:===
{{Table371|
*Defines the default sound fx volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''1.0'''''}}

===$Default Music Volume:===
{{Table371|
*Defines the default music volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.5'''''}}

===$Default Voice Volume:===
{{Table371|
*Defines the default voice volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.7'''''}}

==#FRED SETTINGS==
Optional. This group contains settings for FRED. 

===$Disable Hard Coded Message Head Ani Files:===
{{table371|
If set, FRED will not fill the head ani selection in the Event Editor with the retail head ani filenames.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' }}

==#OTHER SETTINGS==
Optional. This group contains miscellaneous settings. 

===$Fixed Turret Collisions:===
Makes all hits to a turret's barrels count as hits to the turret subsystem. By default, this does not happen unless the point of impact falls inside the model radius of the turret's base.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Damage Impacted Subsystem First:===
If set, a hit to a physical subsystem will always deal damage to that subsystem first, even if another subsystem is closer to the point of impact. By default, the closest subsystem will always receive damage first.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default ship select effect:===
{{Table3615|
*This specifies which effect to use for ship select animations when no .ani can be found, or the -ship_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Default weapon select effect:===
{{Table3615|
*This specifies which effect to use for weapon select animations when no .ani can be found, or the -weapon_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Weapons inherit parent collision group:===
{{Table3615|
*When set to true, Weapons fired by a ship will inherit their parents' collision group setting. Default is false.}}

===$Flight controls follow eyepoint orientation:===
{{Table371|
*Specifies that if the player ship's eyepoint happens to rotate into a non-standard orientation, pitch and yaw axes should stay relative to the eyepoint orientation, not the ship. Note that this does not affect the pitch/yaw turning speed, which always remains relative to the ship. Default is false.}}

===$Beams Use Damage Factors:===
{{Table371|
*Specifies that beam weapons will use the tabled damage factors for Armour, Shields and Subsystems. Default is false (i.e. all factors are treated as 1.0)}}

===$Default fiction viewer UI:===
{{Table373|
*Specifies which fiction viewer layout to use in missions that don't specify one. Possible values are as follows:
**"FS2": Standard layout. Requires (2_)fictionviewer and (2_)fictionviewer-m to be present in data\interface.
**"WCS": Moves the "Accept" button to the lower-left corner of the screen. Requires (2_)fictionviewerb and (2_)fictionviewer-mb to be present in data\interface.
**"auto": Selects "WCS" if the appropriate files are present; otherwise, selects "FS2". This is the default setting.}}

==#END==
Required. The last line of the table must be #END

==Sample Entry==

#CAMPAIGN SETTINGS
$Default Campaign File Name: NewCampaignFile

#Ignored Campaign File Names
$Campaign File Name: FreeSpace2.fc2

#HUD SETTINGS
$Directive Wait Time: 5000

#SEXP SETTINGS
$Loop SEXPs Then Arguments: True

#OTHER SETTINGS
$Fix Turret Collisions: True

#END

[[Category:Tables]]

Launcher engine interaction

2017-11-23T11:10:28Z

M!m: Fix -get_flags link

A launcher for the FreeSpace Open engine is responsible for letting the user configure what mod data FSO should use and also how it should use the available hardware (e.g. joysticks or sound devices). It is also important with what flags FSO is started to allow how the game behaves and looks like. In order for this to work, the launcher needs to follow certain conventions which allow FSO to interpret the data the launcher sets for the engine.

This article describes the situation as of FSO version 3.8.0. Previous versions used different configuration mechanisms but those will not be listed here.

=Writing data for the engine to read=
The engine will look for the files described below in the "preferences" path. This path is determined by using the SDL2 function <tt>SDL_GetPrefPath("HardLightProductions", "FreeSpaceOpen")</tt>. Newer engine versions have a way of getting this information without having to link against SDL2, see [[#JSON output|JSON output]] for an alternative way of determining this path.

There are two major configuration mechanisms FSO uses for reading data which was set by the launcher:

==data/cmdline_fso.cfg==
This file should contain all the command line options FSO should use. They should be on a single line and parameters which contain spaces (e.g. mods line "Vassago's Dirge") must be enclosed in quotes:

<pre>
-mod "Vassago's Dirge,MediaVPs_2014" -nomotiondebris -missile_lighting -3dshockwave -post_process -soft_particles -fxaa -fb_explosions -fb_thrusters -enable_shadows -cache_bitmaps -dualscanlines -targetinfo -orbradar -rearm_timer -ballistic_gauge -3dwarp -snd_preload -nosound -nomovies -fps -window -no_unfocused_pause -benchmark_mode -fxaa_preset 6 -ambient_factor 100 -spec_exp 15 -spec_point 1.2 -spec_static 1.5 -spec_tube 1.5 -ogl_spec 20 -bloom_intensity 45
</pre>

The available flags should not be hardcoded by the launcher. Instead, it should use [[#Getting a list of supported flags and devices|-get_flags]] for determining which flags are supported by the launcher.

==fs2_open.ini==
This file contains more "permanent" options and is saved in a standard ini format. The file is separated into multiple "sections" which each contain options specific to that part of the engine:

; Default : This is the default section used by FSO if no specific section is selected.
:; VideocardFs2open
:: This value determines what display mode FSO will use. It has the following format: <tt>[API]-([width]x[height])x[bits] bit</tt>. <tt>[API]</tt> must be exactly 4 characters long. The only valid option here is "OGL " for using the OpenGL API. The other options are pretty obvious. The width and height should match one of the video modes supported by the display (see [[#JSON output|JSON output]] for a way of getting this information without linking against SDL2). The <tt>bits</tt> parameter should either be 16 or 32 but in almost all cases this should be hard-coded to 32.
:; OGL_AntiAliasSamples
:: This should be the level of anti-aliasing desired for OpenGL rendering. This should be the multiple of 2 for how many samples should be taken (e.g. a value of 3 means 8x MSAA). If set to 0 anti-aliasing will be disabled. '''Note:''' As of FSO 3.8.0 this option has no effect!
:; TextureFilter
:: Sets how textures should be filtered. Valid values are 0 for bilinear filtering and 1 for trilinear filtering.
:; OGL_AnisotropicFilter
:: Specifies the level of anisotropic texture filtering if supported by the OpenGL implementation.
:; CurrentJoystickGUID
:: Specifies the GUID of the primary joystick. The case of alphabetic characters will be normalized so it doesn't matter if this string is upper or lower case. This GUID can be determined by using SDL2 or with the [[#JSON output|JSON output]] if supported by the current build).
:; CurrentJoystick
:: Specified the index of the primary joystick. This will only be used if there are multiple joysticks with the same GUID. This is the index used to open the joystick in SDL2 or the index into the joysticks array in the [[#JSON output|JSON output]].
:; EnableJoystickFF
:: Used to determine if force feedback should be enabled if the joystick supports it. If using the [[#JSON output|JSON output]] then it's possible to determine if a joystick supports this by looking at the '''is_haptic''' field of the joystick object.
:; EnableHitEffect
:: This can be used to enable or disable a directional hit effect if Force Feedback is enabled.
:; Language
:: Sets the language of the game. Possible values are "English", "German", "French", and "Polish".
:; ForcePort : Used to force a specific port for multiplayer connections
:; ConnectionSpeed
:: Used for setting how fast the internet connection is. Possible values are "Slow", "56K", "ISDN", "Cable", and "Fast".
:; SpeechTechroom : Enables or disables text-to-speech in the techroom. Valid values are 1 and 0. Defaults to 0.
:; SpeechBriefings : Enables or disables text-to-speech in the briefings. Valid values are 1 and 0. Defaults to 0.
:; SpeechIngame : Enables or disables text-to-speech in game. Valid values are 1 and 0. Defaults to 0.
:; SpeechMulti : Enables or disables text-to-speech in the multiplayer. Valid values are 1 and 0. Defaults to 0.
:; SpeechVolume : The volume scale of the text-to-speech sound. Should be in the range of 0 to 100.
:; SpeechVoice : Sets which voice to use. See [[#JSON output|JSON output]] for a cross-platform way of determining which voices are available.

; Video : Contains options specific to the video display of FSO.
:; Display
:: Used to choose on which display FSO should be displayed on. The [[#JSON output|JSON output]] contains a list of display detected on the system and their index. Alternatively, SDL2 can be used to enumerate this information.

; ForceFeedback : Contains options for configuring the force feedback subsystem of FSO.
:; Strength : A percentage scale of how strong the effect should be. 0 means completely disabled, 100 means full strength.

; Sound : Contains options specific to how sound should be handled in FSO.
:; Quality : Specifies the quality of the sound output. The value should be in [1, 3] where 3 is the highest quality and 1 is the lowest.
:; SampleRate : Explicitly specifies the sample rate the OpenAL context should use.
:; EnableEFX : Enables or disables usage of OpenAL EFX.
:; PlaybackDevice : Sets the playback device OpenAL should use. The [[#JSON output|JSON output]] contains a list of available playback devices.
:; CaptureDevice : Sets the capture device OpenAL should use. The [[#JSON output|JSON output]] contains a list of available capture devices.

=Getting a list of supported flags and devices=
As of 3.8.1, FSO has two ways of determining what flags are supported by the engine. The JSON output has more information and should be easier to parse but is only supported by newer builds.

The flags can be queries by passing the <tt>-get_flags</tt> option to FSO (this should be done directly instead of overwriting <tt>cmdline_fso.cfg</tt>). When doing this, the command line should also contain the <tt>-parse_cmdline_only</tt> to make sure that FSO only reads the actual command line and not <tt>cmdline_fso.cfg</tt>. This avoids issues when <tt>cmdline_fso.cfg</tt> contains options not supported by the selected FSO binary. Since 3.8.1, <tt>-get_flags</tt> optionally accepts one string parameter for selecting how the flags data is formatted and where it is written.

If FSO does not support the parameter for <tt>-get_flags</tt> then it will be ignored silently and the legacy binary format will be used. Every version before 3.8.1 will behave this way. This allows to gracefully degrade to the old legacy behavior if support for older builds is desired. Also, if the build does not support the given <tt>-get_flags</tt> mode then it will print the string "OUTPUT TYPE NOT SUPPORTED!" to <tt>stdout</tt> and default to the version 1 of the JSON output. This is designed so that it is easy for a launcher to be notified if the selected format is not supported.

==JSON output==
This mode for <tt>-get_flags</tt> was introduced in 3.8.1 and can be enabled by using "json_v1" as the mode parameter <tt>-get_flags</tt> (e.g. <tt>-get_flags json_v1</tt>). In this mode FSO will output a JSON formatted data structure to stdout which will contain information about the supported flags and available devices that FSO detected. The object structure of this output is described in the following by using hierarchical lists for symbolizing if an object key is a child of another element. The root of the output will be a JSON object.

; "version" : Contains information about the version of this executable.
:; "full" : The full version string as is displayed in the main menu.
:; "major" : The major part of the version as an integer number.
:; "minor" : The minor part of the version as an integer number.
:; "build" : The build part of the version as an integer number.
:; "has_revision" : A boolean to indicate if this version has a valid revision part.
:; "revision" : An integer indicating the revision part of the build version.
:; "revision_str" : A string indicating the full revision part of the build version. This may contain the Git hash of the commit in the case of nightly builds or something like "RC2" for release candidates.

; "easy_flags" : This is an array of the available "Easy flags" configuration names. The flags array will contain two bitfields where a bit at position n (starting from the last significant bit) will reference the entry of this array which is at position n.

; "flags" : This is an array of all the flags supported by this binary.
:; "name" : A string which specifies the name of the flag (e.g. <tt>-soft_particles</tt>).
:; "description" : A short description of what this flag does. This should be displayed in the launcher overview.
:; "fso_only" : A boolean indicating whether this flag is only available in FSO builds or not.
:; "on_flags" : An integer which represents a bitfield for which easy flags enable this flag. If the bit n is set in this integer then selecting the easy flag at index n will enable this flag. No action should be taken for the bits that are not set in this bitfield.
:; "off_flags" : An integer which represents a bitfield for which easy flags disable this flag. If the bit n is set in this integer then selecting the easy flag at index n will disable this flag. No action should be taken for the bits that are not set in this bitfield.
:; "type" : Specifies the category of this flag. Typically all flags with the same category will be grouped together.
:; "web_url" : Specifies an URL where more information about this flag can be found.

; "caps"
: A string array of what capabilities this build has. The following strings may be present in the array:
:; OpenAL : This build uses OpenAL for sound.
:; No D3D : This build has no support for Direct3D rendering, only OpenGL.
:; New Sound : This build has support for the new, enhanced sound code.
:; SDL : This build uses SDL on all platforms.

; "voices" : An array of all the possible voice names detected by FSO. If a specific voice should be used then to set the <tt>SpeechVoice</tt> key to the index of that voice in this array.

; "displays" : Contains information about all the displays currently connected to the system.
:; "index" : The index in the array of this display. This should be used for the value of <tt>Video.Display</tt>
:; "name" : A more or less human-readable name of this display.
:; "x" : The x offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the x-offset relative to the other displays.
:; "y" : The y offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the y-offset relative to the other displays.
:; "width" : The x-resolution of this display.
:; "height" : The y-resolution of this display.
:; "modes" : Possible video modes of this display.
::; "x": The x-resolution of this video mode.
::; "y": The y-resolution of this video mode.
::; "bits": The bit depth of this video mode (this is typically 32).

; "openal" : Contains information about detected OpenAL properties and devices.
:; "version_major" : The major version of OpenAL as detected by FSO.
:; "version_minor" : The minor version of OpenAL as detected by FSO.
:; "default_playback" : The default playback device as reported by OpenAL. It is possible that this device does not appear in the playback device list.
:; "default_capture" : The default capture device as reported by OpenAL. It is possible that this device does not appear in the capture device list.
:; "playback_devices" : A string array of all the playback devices detected by OpenAL.
:; "capture_devices" : A string array of all the capture devices detected by OpenAL.

; "joysticks" : An array of all the joysticks that FSO detected.
:; "name" : A string which specifies a human-readable name of this joystick.
:; "guid" : The GUID ('''G'''lobally '''U'''nique '''Id'''entifier) of this joystick. This should be used for setting <tt>CurrentJoystickGUID</tt> in <tt>fs2_open.ini</tt>
:; "num_axes" : The number of axes detected on this joystick.
:; "num_balls" : The number of balls detected in this joystick.
:; "num_buttons" : The number of buttons detected on this joystick.
:; "num_hats" : The number of hats detected on this joystick.
:; "is_haptic" : A boolean indicating if this device supports haptic (Force Feedback) effects.

; "pref_path" : A string indicating where the preferences path is located.

==Binary output==
The binary output is basically a dump of the internal data structure used by FSO for representing the supported flags. If <tt>-get_flags</tt> is called without a parameter or with the parameter <tt>binary</tt> then this output mode will be chosen. In this mode FSO will create a file called "<tt>flags.lcg</tt>" in the working directory of the executable and write the binary representation of the flags in that file. The exact format will not be documented here but there are multiple examples of how to parse this (e.g. wxLauncher or Knossos). Please note that the binary format depends on the current architecture and is not normalized to little- or big-endian. Since FSO currently only support x86 based machines this file will always be little endian encoded.

Launcher engine interaction

2017-11-23T11:09:43Z

M!m: Fix JSON output links

A launcher for the FreeSpace Open engine is responsible for letting the user configure what mod data FSO should use and also how it should use the available hardware (e.g. joysticks or sound devices). It is also important with what flags FSO is started to allow how the game behaves and looks like. In order for this to work, the launcher needs to follow certain conventions which allow FSO to interpret the data the launcher sets for the engine.

This article describes the situation as of FSO version 3.8.0. Previous versions used different configuration mechanisms but those will not be listed here.

=Writing data for the engine to read=
The engine will look for the files described below in the "preferences" path. This path is determined by using the SDL2 function <tt>SDL_GetPrefPath("HardLightProductions", "FreeSpaceOpen")</tt>. Newer engine versions have a way of getting this information without having to link against SDL2, see [[#JSON output|JSON output]] for an alternative way of determining this path.

There are two major configuration mechanisms FSO uses for reading data which was set by the launcher:

==data/cmdline_fso.cfg==
This file should contain all the command line options FSO should use. They should be on a single line and parameters which contain spaces (e.g. mods line "Vassago's Dirge") must be enclosed in quotes:

<pre>
-mod "Vassago's Dirge,MediaVPs_2014" -nomotiondebris -missile_lighting -3dshockwave -post_process -soft_particles -fxaa -fb_explosions -fb_thrusters -enable_shadows -cache_bitmaps -dualscanlines -targetinfo -orbradar -rearm_timer -ballistic_gauge -3dwarp -snd_preload -nosound -nomovies -fps -window -no_unfocused_pause -benchmark_mode -fxaa_preset 6 -ambient_factor 100 -spec_exp 15 -spec_point 1.2 -spec_static 1.5 -spec_tube 1.5 -ogl_spec 20 -bloom_intensity 45
</pre>

The available flags should not be hardcoded by the launcher. Instead, it should use [[Launcher engine interaction#Getting engine flags|-get_flags]] for determining which flags are supported by the launcher.

==fs2_open.ini==
This file contains more "permanent" options and is saved in a standard ini format. The file is separated into multiple "sections" which each contain options specific to that part of the engine:

; Default : This is the default section used by FSO if no specific section is selected.
:; VideocardFs2open
:: This value determines what display mode FSO will use. It has the following format: <tt>[API]-([width]x[height])x[bits] bit</tt>. <tt>[API]</tt> must be exactly 4 characters long. The only valid option here is "OGL " for using the OpenGL API. The other options are pretty obvious. The width and height should match one of the video modes supported by the display (see [[#JSON output|JSON output]] for a way of getting this information without linking against SDL2). The <tt>bits</tt> parameter should either be 16 or 32 but in almost all cases this should be hard-coded to 32.
:; OGL_AntiAliasSamples
:: This should be the level of anti-aliasing desired for OpenGL rendering. This should be the multiple of 2 for how many samples should be taken (e.g. a value of 3 means 8x MSAA). If set to 0 anti-aliasing will be disabled. '''Note:''' As of FSO 3.8.0 this option has no effect!
:; TextureFilter
:: Sets how textures should be filtered. Valid values are 0 for bilinear filtering and 1 for trilinear filtering.
:; OGL_AnisotropicFilter
:: Specifies the level of anisotropic texture filtering if supported by the OpenGL implementation.
:; CurrentJoystickGUID
:: Specifies the GUID of the primary joystick. The case of alphabetic characters will be normalized so it doesn't matter if this string is upper or lower case. This GUID can be determined by using SDL2 or with the [[#JSON output|JSON output]] if supported by the current build).
:; CurrentJoystick
:: Specified the index of the primary joystick. This will only be used if there are multiple joysticks with the same GUID. This is the index used to open the joystick in SDL2 or the index into the joysticks array in the [[#JSON output|JSON output]].
:; EnableJoystickFF
:: Used to determine if force feedback should be enabled if the joystick supports it. If using the [[#JSON output|JSON output]] then it's possible to determine if a joystick supports this by looking at the '''is_haptic''' field of the joystick object.
:; EnableHitEffect
:: This can be used to enable or disable a directional hit effect if Force Feedback is enabled.
:; Language
:: Sets the language of the game. Possible values are "English", "German", "French", and "Polish".
:; ForcePort : Used to force a specific port for multiplayer connections
:; ConnectionSpeed
:: Used for setting how fast the internet connection is. Possible values are "Slow", "56K", "ISDN", "Cable", and "Fast".
:; SpeechTechroom : Enables or disables text-to-speech in the techroom. Valid values are 1 and 0. Defaults to 0.
:; SpeechBriefings : Enables or disables text-to-speech in the briefings. Valid values are 1 and 0. Defaults to 0.
:; SpeechIngame : Enables or disables text-to-speech in game. Valid values are 1 and 0. Defaults to 0.
:; SpeechMulti : Enables or disables text-to-speech in the multiplayer. Valid values are 1 and 0. Defaults to 0.
:; SpeechVolume : The volume scale of the text-to-speech sound. Should be in the range of 0 to 100.
:; SpeechVoice : Sets which voice to use. See [[#JSON output|JSON output]] for a cross-platform way of determining which voices are available.

; Video : Contains options specific to the video display of FSO.
:; Display
:: Used to choose on which display FSO should be displayed on. The [[#JSON output|JSON output]] contains a list of display detected on the system and their index. Alternatively, SDL2 can be used to enumerate this information.

; ForceFeedback : Contains options for configuring the force feedback subsystem of FSO.
:; Strength : A percentage scale of how strong the effect should be. 0 means completely disabled, 100 means full strength.

; Sound : Contains options specific to how sound should be handled in FSO.
:; Quality : Specifies the quality of the sound output. The value should be in [1, 3] where 3 is the highest quality and 1 is the lowest.
:; SampleRate : Explicitly specifies the sample rate the OpenAL context should use.
:; EnableEFX : Enables or disables usage of OpenAL EFX.
:; PlaybackDevice : Sets the playback device OpenAL should use. The [[#JSON output|JSON output]] contains a list of available playback devices.
:; CaptureDevice : Sets the capture device OpenAL should use. The [[#JSON output|JSON output]] contains a list of available capture devices.

=Getting a list of supported flags and devices=
As of 3.8.1, FSO has two ways of determining what flags are supported by the engine. The JSON output has more information and should be easier to parse but is only supported by newer builds.

The flags can be queries by passing the <tt>-get_flags</tt> option to FSO (this should be done directly instead of overwriting <tt>cmdline_fso.cfg</tt>). When doing this, the command line should also contain the <tt>-parse_cmdline_only</tt> to make sure that FSO only reads the actual command line and not <tt>cmdline_fso.cfg</tt>. This avoids issues when <tt>cmdline_fso.cfg</tt> contains options not supported by the selected FSO binary. Since 3.8.1, <tt>-get_flags</tt> optionally accepts one string parameter for selecting how the flags data is formatted and where it is written.

If FSO does not support the parameter for <tt>-get_flags</tt> then it will be ignored silently and the legacy binary format will be used. Every version before 3.8.1 will behave this way. This allows to gracefully degrade to the old legacy behavior if support for older builds is desired. Also, if the build does not support the given <tt>-get_flags</tt> mode then it will print the string "OUTPUT TYPE NOT SUPPORTED!" to <tt>stdout</tt> and default to the version 1 of the JSON output. This is designed so that it is easy for a launcher to be notified if the selected format is not supported.

==JSON output==
This mode for <tt>-get_flags</tt> was introduced in 3.8.1 and can be enabled by using "json_v1" as the mode parameter <tt>-get_flags</tt> (e.g. <tt>-get_flags json_v1</tt>). In this mode FSO will output a JSON formatted data structure to stdout which will contain information about the supported flags and available devices that FSO detected. The object structure of this output is described in the following by using hierarchical lists for symbolizing if an object key is a child of another element. The root of the output will be a JSON object.

; "version" : Contains information about the version of this executable.
:; "full" : The full version string as is displayed in the main menu.
:; "major" : The major part of the version as an integer number.
:; "minor" : The minor part of the version as an integer number.
:; "build" : The build part of the version as an integer number.
:; "has_revision" : A boolean to indicate if this version has a valid revision part.
:; "revision" : An integer indicating the revision part of the build version.
:; "revision_str" : A string indicating the full revision part of the build version. This may contain the Git hash of the commit in the case of nightly builds or something like "RC2" for release candidates.

; "easy_flags" : This is an array of the available "Easy flags" configuration names. The flags array will contain two bitfields where a bit at position n (starting from the last significant bit) will reference the entry of this array which is at position n.

; "flags" : This is an array of all the flags supported by this binary.
:; "name" : A string which specifies the name of the flag (e.g. <tt>-soft_particles</tt>).
:; "description" : A short description of what this flag does. This should be displayed in the launcher overview.
:; "fso_only" : A boolean indicating whether this flag is only available in FSO builds or not.
:; "on_flags" : An integer which represents a bitfield for which easy flags enable this flag. If the bit n is set in this integer then selecting the easy flag at index n will enable this flag. No action should be taken for the bits that are not set in this bitfield.
:; "off_flags" : An integer which represents a bitfield for which easy flags disable this flag. If the bit n is set in this integer then selecting the easy flag at index n will disable this flag. No action should be taken for the bits that are not set in this bitfield.
:; "type" : Specifies the category of this flag. Typically all flags with the same category will be grouped together.
:; "web_url" : Specifies an URL where more information about this flag can be found.

; "caps"
: A string array of what capabilities this build has. The following strings may be present in the array:
:; OpenAL : This build uses OpenAL for sound.
:; No D3D : This build has no support for Direct3D rendering, only OpenGL.
:; New Sound : This build has support for the new, enhanced sound code.
:; SDL : This build uses SDL on all platforms.

; "voices" : An array of all the possible voice names detected by FSO. If a specific voice should be used then to set the <tt>SpeechVoice</tt> key to the index of that voice in this array.

; "displays" : Contains information about all the displays currently connected to the system.
:; "index" : The index in the array of this display. This should be used for the value of <tt>Video.Display</tt>
:; "name" : A more or less human-readable name of this display.
:; "x" : The x offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the x-offset relative to the other displays.
:; "y" : The y offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the y-offset relative to the other displays.
:; "width" : The x-resolution of this display.
:; "height" : The y-resolution of this display.
:; "modes" : Possible video modes of this display.
::; "x": The x-resolution of this video mode.
::; "y": The y-resolution of this video mode.
::; "bits": The bit depth of this video mode (this is typically 32).

; "openal" : Contains information about detected OpenAL properties and devices.
:; "version_major" : The major version of OpenAL as detected by FSO.
:; "version_minor" : The minor version of OpenAL as detected by FSO.
:; "default_playback" : The default playback device as reported by OpenAL. It is possible that this device does not appear in the playback device list.
:; "default_capture" : The default capture device as reported by OpenAL. It is possible that this device does not appear in the capture device list.
:; "playback_devices" : A string array of all the playback devices detected by OpenAL.
:; "capture_devices" : A string array of all the capture devices detected by OpenAL.

; "joysticks" : An array of all the joysticks that FSO detected.
:; "name" : A string which specifies a human-readable name of this joystick.
:; "guid" : The GUID ('''G'''lobally '''U'''nique '''Id'''entifier) of this joystick. This should be used for setting <tt>CurrentJoystickGUID</tt> in <tt>fs2_open.ini</tt>
:; "num_axes" : The number of axes detected on this joystick.
:; "num_balls" : The number of balls detected in this joystick.
:; "num_buttons" : The number of buttons detected on this joystick.
:; "num_hats" : The number of hats detected on this joystick.
:; "is_haptic" : A boolean indicating if this device supports haptic (Force Feedback) effects.

; "pref_path" : A string indicating where the preferences path is located.

==Binary output==
The binary output is basically a dump of the internal data structure used by FSO for representing the supported flags. If <tt>-get_flags</tt> is called without a parameter or with the parameter <tt>binary</tt> then this output mode will be chosen. In this mode FSO will create a file called "<tt>flags.lcg</tt>" in the working directory of the executable and write the binary representation of the flags in that file. The exact format will not be documented here but there are multiple examples of how to parse this (e.g. wxLauncher or Knossos). Please note that the binary format depends on the current architecture and is not normalized to little- or big-endian. Since FSO currently only support x86 based machines this file will always be little endian encoded.

Launcher engine interaction

2017-11-23T11:06:45Z

M!m: Add page for launcher <-> engine interaction including documentation for the new JSON flag format

A launcher for the FreeSpace Open engine is responsible for letting the user configure what mod data FSO should use and also how it should use the available hardware (e.g. joysticks or sound devices). It is also important with what flags FSO is started to allow how the game behaves and looks like. In order for this to work, the launcher needs to follow certain conventions which allow FSO to interpret the data the launcher sets for the engine.

This article describes the situation as of FSO version 3.8.0. Previous versions used different configuration mechanisms but those will not be listed here.

=Writing data for the engine to read=
The engine will look for the files described below in the "preferences" path. This path is determined by using the SDL2 function <tt>SDL_GetPrefPath("HardLightProductions", "FreeSpaceOpen")</tt>. Newer engine versions have a way of getting this information without having to link against SDL2, see [[Launcher engine interaction#JSON output|JSON output]] for an alternative way of determining this path.

There are two major configuration mechanisms FSO uses for reading data which was set by the launcher:

==data/cmdline_fso.cfg==
This file should contain all the command line options FSO should use. They should be on a single line and parameters which contain spaces (e.g. mods line "Vassago's Dirge") must be enclosed in quotes:

<pre>
-mod "Vassago's Dirge,MediaVPs_2014" -nomotiondebris -missile_lighting -3dshockwave -post_process -soft_particles -fxaa -fb_explosions -fb_thrusters -enable_shadows -cache_bitmaps -dualscanlines -targetinfo -orbradar -rearm_timer -ballistic_gauge -3dwarp -snd_preload -nosound -nomovies -fps -window -no_unfocused_pause -benchmark_mode -fxaa_preset 6 -ambient_factor 100 -spec_exp 15 -spec_point 1.2 -spec_static 1.5 -spec_tube 1.5 -ogl_spec 20 -bloom_intensity 45
</pre>

The available flags should not be hardcoded by the launcher. Instead, it should use [[Launcher engine interaction#Getting engine flags|-get_flags]] for determining which flags are supported by the launcher.

==fs2_open.ini==
This file contains more "permanent" options and is saved in a standard ini format. The file is separated into multiple "sections" which each contain options specific to that part of the engine:

; Default : This is the default section used by FSO if no specific section is selected.
:; VideocardFs2open
:: This value determines what display mode FSO will use. It has the following format: <tt>[API]-([width]x[height])x[bits] bit</tt>. <tt>[API]</tt> must be exactly 4 characters long. The only valid option here is "OGL " for using the OpenGL API. The other options are pretty obvious. The width and height should match one of the video modes supported by the display (see [[Launcher engine interaction#JSON output|JSON output]] for a way of getting this information without linking against SDL2). The <tt>bits</tt> parameter should either be 16 or 32 but in almost all cases this should be hard-coded to 32.
:; OGL_AntiAliasSamples
:: This should be the level of anti-aliasing desired for OpenGL rendering. This should be the multiple of 2 for how many samples should be taken (e.g. a value of 3 means 8x MSAA). If set to 0 anti-aliasing will be disabled. '''Note:''' As of FSO 3.8.0 this option has no effect!
:; TextureFilter
:: Sets how textures should be filtered. Valid values are 0 for bilinear filtering and 1 for trilinear filtering.
:; OGL_AnisotropicFilter
:: Specifies the level of anisotropic texture filtering if supported by the OpenGL implementation.
:; CurrentJoystickGUID
:: Specifies the GUID of the primary joystick. The case of alphabetic characters will be normalized so it doesn't matter if this string is upper or lower case. This GUID can be determined by using SDL2 or with the [[Launcher engine interaction#JSON output|JSON output]] if supported by the current build).
:; CurrentJoystick
:: Specified the index of the primary joystick. This will only be used if there are multiple joysticks with the same GUID. This is the index used to open the joystick in SDL2 or the index into the joysticks array in the [[Launcher engine interaction#JSON output|JSON output]].
:; EnableJoystickFF
:: Used to determine if force feedback should be enabled if the joystick supports it. If using the [[Launcher engine interaction#JSON output|JSON output]] then it's possible to determine if a joystick supports this by looking at the '''is_haptic''' field of the joystick object.
:; EnableHitEffect
:: This can be used to enable or disable a directional hit effect if Force Feedback is enabled.
:; Language
:: Sets the language of the game. Possible values are "English", "German", "French", and "Polish".
:; ForcePort : Used to force a specific port for multiplayer connections
:; ConnectionSpeed
:: Used for setting how fast the internet connection is. Possible values are "Slow", "56K", "ISDN", "Cable", and "Fast".
:; SpeechTechroom : Enables or disables text-to-speech in the techroom. Valid values are 1 and 0. Defaults to 0.
:; SpeechBriefings : Enables or disables text-to-speech in the briefings. Valid values are 1 and 0. Defaults to 0.
:; SpeechIngame : Enables or disables text-to-speech in game. Valid values are 1 and 0. Defaults to 0.
:; SpeechMulti : Enables or disables text-to-speech in the multiplayer. Valid values are 1 and 0. Defaults to 0.
:; SpeechVolume : The volume scale of the text-to-speech sound. Should be in the range of 0 to 100.
:; SpeechVoice : Sets which voice to use. See [[Launcher engine interaction#JSON output|JSON output]] for a cross-platform way of determining which voices are available.

; Video : Contains options specific to the video display of FSO.
:; Display
:: Used to choose on which display FSO should be displayed on. The [[Launcher engine interaction#JSON output|JSON output]] contains a list of display detected on the system and their index. Alternatively, SDL2 can be used to enumerate this information.

; ForceFeedback : Contains options for configuring the force feedback subsystem of FSO.
:; Strength : A percentage scale of how strong the effect should be. 0 means completely disabled, 100 means full strength.

; Sound : Contains options specific to how sound should be handled in FSO.
:; Quality : Specifies the quality of the sound output. The value should be in [1, 3] where 3 is the highest quality and 1 is the lowest.
:; SampleRate : Explicitly specifies the sample rate the OpenAL context should use.
:; EnableEFX : Enables or disables usage of OpenAL EFX.
:; PlaybackDevice : Sets the playback device OpenAL should use. The [[Launcher engine interaction#JSON output|JSON output]] contains a list of available playback devices.
:; CaptureDevice : Sets the capture device OpenAL should use. The [[Launcher engine interaction#JSON output|JSON output]] contains a list of available capture devices.

=Getting a list of supported flags and devices=
As of 3.8.1, FSO has two ways of determining what flags are supported by the engine. The JSON output has more information and should be easier to parse but is only supported by newer builds.

The flags can be queries by passing the <tt>-get_flags</tt> option to FSO (this should be done directly instead of overwriting <tt>cmdline_fso.cfg</tt>). When doing this, the command line should also contain the <tt>-parse_cmdline_only</tt> to make sure that FSO only reads the actual command line and not <tt>cmdline_fso.cfg</tt>. This avoids issues when <tt>cmdline_fso.cfg</tt> contains options not supported by the selected FSO binary. Since 3.8.1, <tt>-get_flags</tt> optionally accepts one string parameter for selecting how the flags data is formatted and where it is written.

If FSO does not support the parameter for <tt>-get_flags</tt> then it will be ignored silently and the legacy binary format will be used. Every version before 3.8.1 will behave this way. This allows to gracefully degrade to the old legacy behavior if support for older builds is desired. Also, if the build does not support the given <tt>-get_flags</tt> mode then it will print the string "OUTPUT TYPE NOT SUPPORTED!" to <tt>stdout</tt> and default to the version 1 of the JSON output. This is designed so that it is easy for a launcher to be notified if the selected format is not supported.

==JSON output==
This mode for <tt>-get_flags</tt> was introduced in 3.8.1 and can be enabled by using "json_v1" as the mode parameter <tt>-get_flags</tt> (e.g. <tt>-get_flags json_v1</tt>). In this mode FSO will output a JSON formatted data structure to stdout which will contain information about the supported flags and available devices that FSO detected. The object structure of this output is described in the following by using hierarchical lists for symbolizing if an object key is a child of another element. The root of the output will be a JSON object.

; "version" : Contains information about the version of this executable.
:; "full" : The full version string as is displayed in the main menu.
:; "major" : The major part of the version as an integer number.
:; "minor" : The minor part of the version as an integer number.
:; "build" : The build part of the version as an integer number.
:; "has_revision" : A boolean to indicate if this version has a valid revision part.
:; "revision" : An integer indicating the revision part of the build version.
:; "revision_str" : A string indicating the full revision part of the build version. This may contain the Git hash of the commit in the case of nightly builds or something like "RC2" for release candidates.

; "easy_flags" : This is an array of the available "Easy flags" configuration names. The flags array will contain two bitfields where a bit at position n (starting from the last significant bit) will reference the entry of this array which is at position n.

; "flags" : This is an array of all the flags supported by this binary.
:; "name" : A string which specifies the name of the flag (e.g. <tt>-soft_particles</tt>).
:; "description" : A short description of what this flag does. This should be displayed in the launcher overview.
:; "fso_only" : A boolean indicating whether this flag is only available in FSO builds or not.
:; "on_flags" : An integer which represents a bitfield for which easy flags enable this flag. If the bit n is set in this integer then selecting the easy flag at index n will enable this flag. No action should be taken for the bits that are not set in this bitfield.
:; "off_flags" : An integer which represents a bitfield for which easy flags disable this flag. If the bit n is set in this integer then selecting the easy flag at index n will disable this flag. No action should be taken for the bits that are not set in this bitfield.
:; "type" : Specifies the category of this flag. Typically all flags with the same category will be grouped together.
:; "web_url" : Specifies an URL where more information about this flag can be found.

; "caps"
: A string array of what capabilities this build has. The following strings may be present in the array:
:; OpenAL : This build uses OpenAL for sound.
:; No D3D : This build has no support for Direct3D rendering, only OpenGL.
:; New Sound : This build has support for the new, enhanced sound code.
:; SDL : This build uses SDL on all platforms.

; "voices" : An array of all the possible voice names detected by FSO. If a specific voice should be used then to set the <tt>SpeechVoice</tt> key to the index of that voice in this array.

; "displays" : Contains information about all the displays currently connected to the system.
:; "index" : The index in the array of this display. This should be used for the value of <tt>Video.Display</tt>
:; "name" : A more or less human-readable name of this display.
:; "x" : The x offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the x-offset relative to the other displays.
:; "y" : The y offset of where this display is located. This is only relevant for multi-monitor systems where this value specifies the y-offset relative to the other displays.
:; "width" : The x-resolution of this display.
:; "height" : The y-resolution of this display.
:; "modes" : Possible video modes of this display.
::; "x": The x-resolution of this video mode.
::; "y": The y-resolution of this video mode.
::; "bits": The bit depth of this video mode (this is typically 32).

; "openal" : Contains information about detected OpenAL properties and devices.
:; "version_major" : The major version of OpenAL as detected by FSO.
:; "version_minor" : The minor version of OpenAL as detected by FSO.
:; "default_playback" : The default playback device as reported by OpenAL. It is possible that this device does not appear in the playback device list.
:; "default_capture" : The default capture device as reported by OpenAL. It is possible that this device does not appear in the capture device list.
:; "playback_devices" : A string array of all the playback devices detected by OpenAL.
:; "capture_devices" : A string array of all the capture devices detected by OpenAL.

; "joysticks" : An array of all the joysticks that FSO detected.
:; "name" : A string which specifies a human-readable name of this joystick.
:; "guid" : The GUID ('''G'''lobally '''U'''nique '''Id'''entifier) of this joystick. This should be used for setting <tt>CurrentJoystickGUID</tt> in <tt>fs2_open.ini</tt>
:; "num_axes" : The number of axes detected on this joystick.
:; "num_balls" : The number of balls detected in this joystick.
:; "num_buttons" : The number of buttons detected on this joystick.
:; "num_hats" : The number of hats detected on this joystick.
:; "is_haptic" : A boolean indicating if this device supports haptic (Force Feedback) effects.

; "pref_path" : A string indicating where the preferences path is located.

==Binary output==
The binary output is basically a dump of the internal data structure used by FSO for representing the supported flags. If <tt>-get_flags</tt> is called without a parameter or with the parameter <tt>binary</tt> then this output mode will be chosen. In this mode FSO will create a file called "<tt>flags.lcg</tt>" in the working directory of the executable and write the binary representation of the flags in that file. The exact format will not be documented here but there are multiple examples of how to parse this (e.g. wxLauncher or Knossos). Please note that the binary format depends on the current architecture and is not normalized to little- or big-endian. Since FSO currently only support x86 based machines this file will always be little endian encoded.

Sounds.tbl

2017-11-06T13:12:35Z

M!m: Add documentation of sound set feature

{{TableVersion| 344502c (Git commit)}}

The '''sounds.tbl''' is a file for defining the various sounds played ingame.

This table is one of the [[Modular Tables]] and can be extended with xxx-snd.tbm

[[Tables|List of Tables]]

==Format==
*Table file consists of several sections
*First section defines the sound for the actual game play. It begins at '''#Game Sounds Start''' and ends at'''#Game Sounds End'''
*Second section defines the interface sounds. It starts at '''#Interface Sounds Start''' and ends at '''#Interface Sounds End'''
*Third section defines the flyby sounds for different species. It begins at '''#Flyby Sounds Start''' and ends at '''#Flyby Sounds End'''
*This table has three possible syntaxes. The "Sound set" syntax allows to use multiple sounds. The "SCP Syntax" was introduced as a general improvement over the retail Syntax and is very similar to the sound set syntax.
**The Sound set syntax allows to specify multiple sound files for one sound entry and also has a wider variety of options for specifying how the sound should be played. This syntax is based on the SCP syntax and it should be easy to adapt sound entries that use the SCP syntax to the new sound set syntax. This is only required if the new features of the sound set changes are to be used. Otherwise the SCP syntax can be used.
**The SCP Syntax is an improvement of the retail syntax whis is easier to read, and likely preferred for modular tables and extendability.
**The Retail Syntax is the syntax used by the retail tables which was kept in place to keep retail compatibility
*Most of the sounds are hardcoded in the engine (that is, the engine expects sound 33 to be the missile rearm sound, as an example). Modders should follow the retail table layout, and not assign sound numbers smaller than 250 to their custom sounds. This avoids index collisions.

==Sound set syntax==
{{Note|Many retail sound names are hardcoded to a specific type of sound, so removing entries is not recommended. However adding new ones or altering existing ones is possible. See the [[Hardcoded sounds|hardcoded sounds]] for a list of which sounds have hardcoded names.}}

{{Table381|
}}

If this syntax is in use then the new sound set features can be used. These include the ability to use multiple sound files for one entry and with this feature it is possible to randomize the volume and pitch values when a sound is played. Compared to the SCP syntax there are only a few changes: Instead of ''+Filename'' this now uses ''+Entry'' and allows using that option as often as needed. The ''+Volume'' option accepts a random range for possible values and the ''+Pitch'' option is new.

In most entries, the name of the file ('''Second''' value) can be replaced with 'empty' if the particular sound index is not in use.

===#Game Sounds Start===
Notes
*Cockpit sounds are in general non-3D sounds
*All the other in-flight sounds are, in general, 3D sounds
*Non-3D sounds do not require the '''+3D Sound''' entries

Example Line
<pre>
$Name: 6
+Entry: breakup
+Cycle type: sequential
+Preload: no
+Volume: (0.60)
+3D Sound:
+Attenuation start: 100
+Attenuation end: 800
+Priority: High
+Limit: 3
+Pitch: (1.0)
</pre>

====$Name:====
*Specifies the sound handle which FSO will use to identify the sound from other tables
*If +nocreate is to be used, it must come after '''$Name:''' and before the '''String'''
*Syntax: '''String'''
{{Warning|
The name may not contain any whitespace (space or tab characters) or the old parsing code will be used.}}

====+nocreate====
*Allows editing of the sound without creating a new sound handle
*Must be placed after '''$Name:''' and before the '''String'''
*Example
**<pre>$Name: +nocreate SoundName</pre>

====+Entry:====
*The name of the actual sound file. This option may appear more than once if multiple sound files should be used for this sound entry.
*Always required once, even if +nocreate is used.
*To specify no sound file, use "empty" (without the quotes)
*If +nocreate is used then sound files can only be added to the sound but no other modification is available.
*Syntax: '''String'''

====+Cycle type:====
*Specifies how the next sound entry should be chosen from the ''+Entry'' list
*Required, optional if +nocreate is used
*May use one of the following modes:
**'''sequential''': The entry will be chosen sequentially from the list. '''Note:''' The sequence of played sounds is determined globally so if there are two sound sources using the same entry then the sounds may appear as missing parts for either source since the other source used that entry before.
**'''random''': An entry is chosen uniformly at random from the entries list
*Syntax: '''sequential''' or '''random'''

====+Preload:====
*Specifies whether FSO should always preload the sound before the mission or not
*Optional if +nocreate is used, required otherwise
*Syntax: '''Boolean'''

====+Volume:====
*Specifies the volume the sound should be played at as a random range between 0 and 1. The actual volume will be picked within that range whenever a sound is played
*Optional if +nocreate is used, required otherwise
*Syntax: '''(Float)''' or '''(Float Float)''', example: ''(0.5 1.0)''. It is also valid to only specify one value if there should be no randomization.

====+3D Sound:====
*Sets up table syntax for specifying 3D sound options
*If present the sound will be loaded as a 3D sound
*No argument should be specified
*Must be accompanied by '''+Attenuation Start:''' and '''+Attenuation End:'''

====+Attenuation Start:====
*Defines the distance from the origin of the 3D sound where it begins to attenuate
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

====+Attenuation End:====
*Defines the distance from the origin of the 3D sound where it is inaudible
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

====+Priority:====
*Optional, for use with [[Enhanced sound|enhanced sound]]
*Can be used with or without an accompanying +Limit:
*Specifies the priority of this sound when enhanced sound is used
*Should be based on how important this sound is and also how likely the player will notice if the sound drops out
*overrides the engine default value
*For valid values, see the table below. Values are not case-sensitive.
*See the [[Enhanced sound]] page for more information.
*Syntax: '''String'''

<pre>
Value Meaning
----- -------
Must Play Absolutely must play
High Very important
Medium-High Important
Medium Somewhat important
Medium-Low Only a little important
Low Not important
</pre>

====+Limit:====
*Optional, for use with [[Enhanced sound|enhanced sound]]
*Can be used with or without an accompanying +Priority:
*Specifies how many instances of the sound can play at the same time
*overrides the engine default value
*Must be in the range 1 - 15
*See the [[Enhanced sound]] page for more information,
*Syntax: '''Integer'''

====+Pitch:====
*Specifies which pitch values the sound may be assigned
*Optional, defaults to 1.0
*This is a random range which specifies the possible pitch values the sound may be assigned
*The actual effect of these values is very complicated to describe so you should simply test to check which values sound well. A value of 1.0 plays the sound without any changes.
*Syntax: '''(Float)''' or '''(Float Float)''', example: ''(0.9 1.1)''. It is also valid to only specify one value if there should be no randomization.

'''Section ends with #Game Sounds End'''

===#Interface Sounds Start===
Notes
*Interface sounds are not 3D sounds. You may specify '''+3D Sound:''' properties, but they will be ignored.

Example Line
<pre>
$Name: CraneSound1
+Entry: Crane_1
+Cycle type: sequential
+Preload: no
+Volume: 0.50
</pre>

====$Name:====
*Specifies the sound handle which FSO will use to identify the sound from other tables
*If +nocreate is to be used, it must come after '''$Name:''' and before the '''String'''
*Syntax: '''String'''
{{Warning|
The name may not contain any whitespace (space or tab characters) or the old parsing code will be used.}}

====+nocreate====
*Allows editing of the sound without creating a new sound handle
*Must be placed after '''$Name:''' and before the '''String'''
*Example
**<pre>$Name: +nocreate SoundName</pre>

====+Entry:====
*The name of the actual sound file. This option may appear more than once if multiple sound files should be used for this sound entry.
*Always required once, even if +nocreate is used.
*To specify no sound file, use "empty" (without the quotes)
*If +nocreate is used then sound files can only be added to the sound but no other modification is available.
*Syntax: '''String'''

====+Cycle type:====
*Specifies how the next sound entry should be chosen from the ''+Entry'' list
*Required, optional if +nocreate is used
*May use one of the following modes:
**'''sequential''': The entry will be chosen sequentially from the list. '''Note:''' The sequence of played sounds is determined globally so if there are two sound sources using the same entry then the sounds may appear as missing parts for either source since the other source used that entry before.
**'''random''': An entry is chosen uniformly at random from the entries list
*Syntax: '''sequential''' or '''random'''

====+Preload:====
*Specifies whether FSO should always preload the sound before the mission or not
*Syntax: '''Boolean'''

====+Volume:====
*Specifies the volume the sound should be played at as a random range between 0 and 1. The actual volume will be picked within that range whenever a sound is played
*Optional if +nocreate is used, required otherwise
*Syntax: '''(Float)''' or '''(Float Float)''', example: ''(0.5 1.0)''. It is also valid to only specify one value if there should be no randomization.

====+Pitch:====
*Specifies which pitch values the sound may be assigned
*Optional, defaults to 1.0
*This is a random range which specifies the possible pitch values the sound may be assigned
*The actual effect of these values is very complicated to describe so you should simply test to check which values sound well. A value of 1.0 plays the sound without any changes.
*Syntax: '''(Float)''' or '''(Float Float)''', example: ''(0.9 1.1)''. It is also valid to only specify one value if there should be no randomization.

'''Section ends with #Interface Sounds End'''

===#Flyby Sounds Start===
Notes
*Each species has two flyby sounds. One for the fighters and one for the bombers.
*Flyby sounds are all 3D sounds.
*Each flyby sound is defined on a line that begins with the species name ('''String''', species name, eg. '''$Terran:''').
*'''THE FLYBY SECTION CANNOT USE +nocreate'''
If you want to modify a flyby sound entry of a species in a modular table then you will need to have entries for both types.

Line starts with '''$SPECIES:''' in the place of '''$Name:'''

Example Terran Section
<pre>
$Terran: 0
+Entry: T_flyby1
+Cycle type: sequential
+Preload: no
+Volume: (0.75)
+3D Sound:
+Attenuation start: 200
+Attenuation end: 400

$Terran: 1
+Entry: T_flyby2
+Cycle type: sequential
+Preload: no
+Volume: (0.75)
+3D Sound:
+Attenuation start: 200
+Attenuation end: 400
</pre>

====$Name:====
*'''$Name''' must be replaced with '''$SPECIES''' as from the [[Species_defs.tbl]]
*Specifies the sound handle which FSO will use to identify the sound from other tables
*In this case it will usually be a '''1''' or a '''0'''
*Syntax: '''String'''
{{Warning|
The name may not contain any whitespace (space or tab characters) or the old parsing code will be used.}}

====+Entry:====
*The name of the actual sound file. This option may appear more than once if multiple sound files should be used for this sound entry.
*Always required once, even if +nocreate is used.
*To specify no sound file, use "empty" (without the quotes)
*If +nocreate is used then sound files can only be added to the sound but no other modification is available.
*Syntax: '''String'''

====+Cycle type:====
*Specifies how the next sound entry should be chosen from the ''+Entry'' list
*Required, optional if +nocreate is used
*May use one of the following modes:
**'''sequential''': The entry will be chosen sequentially from the list. '''Note:''' The sequence of played sounds is determined globally so if there are two sound sources using the same entry then the sounds may appear as missing parts for either source since the other source used that entry before.
**'''random''': An entry is chosen uniformly at random from the entries list
*Syntax: '''sequential''' or '''random'''

====+Preload:====
*Specifies whether FSO should always preload the sound before the mission or not
*Syntax: '''Boolean'''

====+Volume:====
*Specifies the volume the sound should be played at as a random range between 0 and 1. The actual volume will be picked within that range whenever a sound is played
*Optional if +nocreate is used, required otherwise
*Syntax: '''(Float)''' or '''(Float Float)''', example: ''(0.5 1.0)''. It is also valid to only specify one value if there should be no randomization.

====+3D Sound:====
*Sets up table syntax for specifying 3D sound options
*If present the sound will be loaded as a 3D sound
*No argument should be specified
*Must be accompanied by '''+Attenuation Start:''' and '''+Attenuation End:'''

====+Attenuation Start:====
*Defines the distance from the origin of the 3D sound where it begins to attenuate
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

====+Attenuation End:====
*Defines the distance from the origin of the 3D sound where it is inaudible
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

====+Pitch:====
*Specifies which pitch values the sound may be assigned
*Optional, defaults to 1.0
*This is a random range which specifies the possible pitch values the sound may be assigned
*The actual effect of these values is very complicated to describe so you should simply test to check which values sound well. A value of 1.0 plays the sound without any changes.
*Syntax: '''(Float)''' or '''(Float Float)''', example: ''(0.9 1.1)''. It is also valid to only specify one value if there should be no randomization.

'''Section ends with #Flyby Sounds End'''

==SCP Syntax==
{{Note|Many retail sound names are hardcoded to a specific type of sound, so removing entries is not recommended. However adding new ones or altering existing ones is possible. See the [[Hardcoded sounds|hardcoded sounds]] for a list of which sounds have hardcoded names.}}

In most entries, the name of the file ('''Second''' value) can be replaced with 'empty' if the particular sound index is not in use.

===#Game Sounds Start===
Notes
*Cockpit sounds are in general non-3D sounds
*All the other in-flight sounds are, in general, 3D sounds
*Non-3D sounds do not require the '''+3D Sound''' entries

Example Line
<pre>
$Name: 6
+Filename: breakup
+Preload: no
+Volume: 0.60
+3D Sound:
+Attenuation start: 100
+Attenuation end: 800
+Priority: High
+Limit: 3
</pre>

====$Name:====
*Specifies the sound handle which FSO will use to identify the sound from other tables
*If +nocreate is to be used, it must come after '''$Name:''' and before the '''String'''
*Syntax: '''String'''
{{Warning|
The name may not contain any whitespace (space or tab characters) or the old parsing code will be used.}}

====+nocreate====
*Allows editing of the sound without creating a new sound handle
*Must be placed after '''$Name:''' and before the '''String'''
*Example
**<pre>$Name: +nocreate SoundName</pre>

====+Filename:====
*The name of the actual sound file to play
*Always required, even if +nocreate is used.
*To specify no sound file, use "empty" (without the quotes)
*If +nocreate is used and you don't want to change the original filename, then use <same> (including the <>)
*Syntax: '''String'''

====+Preload:====
*Specifies whether FSO should always preload the sound before the mission or not
*Optional if +nocreate is used, required otherwise
*Syntax: '''Boolean'''

====+Volume:====
*Specifies the volume the sound should be played at as a percentage
*Optional if +nocreate is used, required otherwise
*Syntax: '''Float'''

====+3D Sound:====
*Sets up table syntax for specifying 3D sound options
*If present the sound will be loaded as a 3D sound
*No argument should be specified
*Must be accompanied by '''+Attenuation Start:''' and '''+Attenuation End:'''

====+Attenuation Start:====
*Defines the distance from the origin of the 3D sound where it begins to attenuate
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

====+Attenuation End:====
*Defines the distance from the origin of the 3D sound where it is inaudible
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

====+Priority:====
*Optional, for use with [[Enhanced sound|enhanced sound]]
*Can be used with or without an accompanying +Limit:
*Specifies the priority of this sound when enhanced sound is used
*Should be based on how important this sound is and also how likely the player will notice if the sound drops out
*overrides the engine default value
*For valid values, see the table below. Values are not case-sensitive.
*See the [[Enhanced sound]] page for more information.
*Syntax: '''String'''

<pre>
Value Meaning
----- -------
Must Play Absolutely must play
High Very important
Medium-High Important
Medium Somewhat important
Medium-Low Only a little important
Low Not important
</pre>

====+Limit:====
*Optional, for use with [[Enhanced sound|enhanced sound]]
*Can be used with or without an accompanying +Priority:
*Specifies how many instances of the sound can play at the same time
*overrides the engine default value
*Must be in the range 1 - 15
*See the [[Enhanced sound]] page for more information,
*Syntax: '''Integer'''

'''Section ends with #Game Sounds End'''

===#Interface Sounds Start===
Notes
*Interface sounds are not 3D sounds. You may specify '''+3D Sound:''' properties, but they will be ignored.

Example Line
<pre>
$Name: CraneSound1
+Filename: Crane_1
+Preload: no
+Volume: 0.50
</pre>

====$Name:====
*Specifies the sound handle which FSO will use to identify the sound from other tables
*If +nocreate is to be used, it must come after '''$Name:''' and before the '''String'''
*Syntax: '''String'''
{{Warning|
The name may not contain any whitespace (space or tab characters) or the old parsing code will be used.}}

====+nocreate====
*Allows editing of the sound without creating a new sound handle
*Must be placed after '''$Name:''' and before the '''String'''
*Example
**<pre>$Name: +nocreate SoundName</pre>

====+Filename:====
*The name of the actual sound file to play
*Syntax: '''String'''

====+Preload:====
*Specifies whether FSO should always preload the sound before the mission or not
*Syntax: '''Boolean'''

====+Volume:====
*Specifies the volume the sound should be played at as a percentage
*Syntax: '''Float'''

'''Section ends with #Interface Sounds End'''

===#Flyby Sounds Start===
Notes
*Each species has two flyby sounds. One for the fighters and one for the bombers.
*Flyby sounds are all 3D sounds.
*Each flyby sound is defined on a line that begins with the species name ('''String''', species name, eg. '''$Terran:''').
*'''THE FLYBY SECTION CANNOT USE +nocreate'''
If you want to modify a flyby sound entry of a species in a modular table then you will need to have entries for both types.

Line starts with '''$SPECIES:''' in the place of '''$Name:'''

Example Terran Section
<pre>
$Terran: 0
+Filename: T_flyby1
+Preload: no
+Volume: 0.75
+3D Sound:
+Attenuation start: 200
+Attenuation end: 400

$Terran: 1
+Filename: T_flyby2
+Preload: no
+Volume: 0.75
+3D Sound:
+Attenuation start: 200
+Attenuation end: 400
</pre>

====$Name:====
*'''$Name''' must be replaced with '''$SPECIES''' as from the [[Species_defs.tbl]]
*Specifies the sound handle which FSO will use to identify the sound from other tables
*In this case it will usually be a '''1''' or a '''0'''
*Syntax: '''String'''
{{Warning|
The name may not contain any whitespace (space or tab characters) or the old parsing code will be used.}}

====+Filename:====
*The name of the actual sound file to play
*Syntax: '''String'''

====+Preload:====
*Specifies whether FSO should always preload the sound before the mission or not
*Syntax: '''Boolean'''

====+Volume:====
*Specifies the volume the sound should be played at as a percentage
*Syntax: '''Float'''

====+3D Sound:====
*Sets up table syntax for specifying 3D sound options
*If present the sound will be loaded as a 3D sound
*No argument should be specified
*Must be accompanied by '''+Attenuation Start:''' and '''+Attenuation End:'''

====+Attenuation Start:====
*Defines the distance from the origin of the 3D sound where it begins to attenuate
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

====+Attenuation End:====
*Defines the distance from the origin of the 3D sound where it is inaudible
*Must be preceded by '''+3D Sound:'''
*Syntax: '''Integer'''

'''Section ends with #Flyby Sounds End'''

==Retail Syntax==
{{Note|Many retail sound names are hardcoded to a specific type of sound, so removing entries is not recommended. However adding new ones or altering existing ones is possible. See the [[Hardcoded sounds|hardcoded sounds]] for a list of which sounds have hardcoded names.}}

In most entries, the name of the file ('''Second''' value) can be replaced with 'empty' if the particular sound index is not in use.

===#Game Sounds Start===
Notes
*Cockpit sounds are in general non-3D sounds that ought to be of type '0', however all the other in-flight sounds are in general 3D sounds and ought to of type '1' (or type '2').
*Type 0 sounds do not require the '''Sixth''' and '''Seventh''' entries.

Example Line
<pre>$Name: 6 breakup.wav, 0, 0.60, 1, 100, 800</pre>

Line starts with ''$Name:'' and has seven entries separated by commas except for the first and second entries.

**'''First''' value is the index number of the sound ('''Integer''')
**'''Second''' value is the name of actual sound file ('''String''', filename).
**'''Third''' value sets the file to always preloaded before the mission ('''Integer''', 0 or 1)
**'''Fourth''' value defines the playing volume of the sound in percentages ('''Float''', from 0 to 1)
**'''Fifth''' value sets the sound type to either standard sound (type '0'), 3D stereo sound (type '1'), or Aureal A3D (type '2'). This defaults to 3D stereo if it is not available ('''Integer''', 0, 1 or 2)
***'''Sixth''' value defines the distance from the origin of 3D sound where it begins to attenuate and is not used with normal non-3D sounds (type 0)('''Integer''')
***'''Seventh''' value sets the distance from the origin of the 3D sound where it is inaudible and is not used with normal non-3D sounds (type 0)('''Integer''')

'''Section ends with #Game Sounds End'''

===#Interface Sounds Start===
Notes
*Interface sounds are not 3D sounds. Use type '0' sounds. The '''Sixth''' and '''Seventh''' entries can be left out of sounds in this section.

Example Line
<pre>$Name: 26 Crane_1.wav, 0, 0.50, 0</pre>

Line starts with ''$Name:'' and has five entries separated by commas except for the first and second entries.

**'''First''' value is the index number of the sound ('''Integer''')
**'''Second''' value is the name of actual sound file ('''String''', filename or '''Empty''').
**'''Third''' value sets the file to always preloaded before the mission ('''Integer''', 0 or 1)
**'''Fourth''' value defines the playing volume of the sound in percentages ('''Float''', from 0 to 1)
**'''Fifth''' value sets the sound type to either standard sound (type '0'), 3D stereo sound (type '1'), or Aureal A3D (type '2'). This defaults to 3D stereo if it is not available ('''Integer''', 0, 1 or 2)

'''Section ends with #Interface Sounds End'''

===#Flyby Sounds Start===
Notes
*Each species has two flyby sounds. One for the fighters and one for the bombers.
*Flyby sounds are all 3D sounds of type '1' for the '''Fifth''' value.
*Each flyby sound is defined on a single line that begins with the species name ('''String''', species name, eg. '''$Terran:''').

Retail flyby section
<pre>
#Flyby Sounds Start

$Terran: 0 T_flyby1.wav, 0, 0.75, 1, 200, 400 ; * Terran ship1 flyby player sound (3d sound)
$Terran: 1 T_flyby2.wav, 0, 0.75, 1, 200, 400 ; * Terran ship1 flyby player sound (3d sound)

$Vasudan: 0 V_flyby1.wav, 0, 0.85, 1, 200, 400 ; * Vasudan ship1 flyby player sound (3d sound)
$Vasudan: 1 V_flyby2.wav, 0, 0.85, 1, 200, 400 ; * Vasudan ship1 flyby player sound (3d sound)

$Shivan: 0 S_flyby1.wav, 0, 0.75, 1, 200, 400 ; * Shivan ship1 flyby player sound (3d sound)
$Shivan: 1 S_flyby2.wav, 0, 0.75, 1, 200, 400 ; * Shivan ship1 flyby player sound (3d sound)

#Flyby Sounds End
</pre>

Line starts with ''$SPECIES:'' and has seven entries separated by commas except for the first and second entries.

**'''First''' value is the label of the flyby sound, usually 0 for the first (small-ship) entry and 1 for the second (large-ship)entry. ('''Integer''')
**'''Second''' value is the name of actual sound file ('''String''', filename).
**'''Third''' value sets the file to always preloaded before the mission ('''Integer''', 0 or 1)
**'''Fourth''' value defines the playing volume of the sound in percentages ('''Float''', from 0 to 1)
**'''Fifth''' value sets the sound type and should be set to 3D stereo sound (type '1') ('''Integer''', 0, 1 or 2)
***'''Sixth''' value defines the distance from the origin of 3D sound where it begins to attenuate (type 0)('''Integer''')
***'''Seventh''' value sets the distance from the origin of the 3D sound where it is inaudible (type 0)('''Integer''')

'''Section ends with #Flyby Sounds End'''

==Sample==
*Retail FreeSpace 2 table

<pre>
;
; sounds.tbl *
;
; file to specify general game sounds
;
; I M P O R T A N T
; **********************************************************
; * *
; ====> DO NOT MODIFY THE ORDER OF THE LISTED SOUNDS <====*
; * *
; **********************************************************
; I M P O R T A N T
;
; If a sound entry appears in this file, there is a hook into the game to
; play the sound. This file can only be modified to change *existing* sounds.
; Talk to a programmer if you want to add brand new sounds. Adding a line to
; this file will not make your sound appear in the game, it will more than
; likely break something.
;
; If you don't want the sound to play, put none.wav as the sound to play.
;
; The fields for a sound entry are:
; 1) unqiue sound signature
; 2) filename of the sound
; 3) flag to indicate sound should always be pre-loaded before a mission
; 4) the default volume (from 0.0 -> 1.0)
; 5) 0 - not 3d 1 - stereo 3D 2 - Aureal A3D (if available), otherwise use stereo 3D
; 6) distance at which sound starts to attenuate (for 3d sounds only)
; 7) distance at which sound is inaudible (for 3d sounds only)
;
#Game Sounds Start
; Misc sounds section ** = Aureal 3d support | * = FS = 3D support
$Name: 0 trk-loop.wav, 0, 0.40, 0 ; Missle tracking to acquire a lock (looped)
$Name: 1 lock.wav, 0, 0.40, 0 ; Missle lock (non-looping)
$Name: 2 cycle.wav, 0, 0.60, 0 ; cycle primary weapon
$Name: 3 cycle.wav, 0, 0.60, 0 ; cycle secondary weapon
$Name: 4 ship_p.wav, 0, 0.30, 0 ; engine sound (as heard in cockpit)
$Name: 5 reveal.wav, 0, 0.40, 0 ; cargo revealed
$Name: 6 breakup.wav, 0, 0.60, 1, 100, 800 ; ship death roll (3d sound)
$Name: 7 boom_3.wav, 0, 0.90, 2, 600, 1200 ; * ship explosion 1 (3d sound)
$Name: 8 beep_2.wav, 0, 0.40, 0 ; target acquried
$Name: 9 switch_1.wav, 0, 0.50, 0 ; energy level change success
$Name: 10 beep_5.wav, 0, 0.50, 0 ; energy level change fail
$Name: 11 switch_2.wav, 0, 0.50, 0 ; energy transfer success
$Name: 12 beep_5.wav, 0, 0.50, 0 ; energy transfer faile
$Name: 13 thr_full.wav, 0, 0.40, 0 ; set full throttle
$Name: 14 thr_off.wav, 0, 0.40, 0 ; set zero throttle
$Name: 15 thr_up.wav, 0, 0.40, 0 ; set 1/3 or 2/3 throttle (up)
$Name: 16 thr_dwn.wav, 0, 0.40, 0 ; set 1/3 or 2/3 throttle (down)
$Name: 17 approach.wav, 0, 0.60, 1, 10, 800 ; dock approach retros (3d sound)
$Name: 18 attach.wav, 0, 0.60, 1, 10, 800 ; dock attach (3d sound)
$Name: 19 detach.wav, 0, 0.60, 1, 10, 800 ; dock detach (3d sound)
$Name: 20 depart.wav, 0, 0.60, 1, 10, 800 ; dock depart retros (3d sound)
$Name: 21 aburn_1.wav, 0, 0.70, 0 ; afterburner engage (3d sound)
$Name: 22 aburn_2.wav, 0, 0.90, 0 ; afterburner burn sound (looped)
$Name: 23 vaporize2.wav, 0, 0.90, 0 ; Destroyed by a beam (vaporized)
$Name: 24 aburn_1f.wav, 0, 0.50, 0 ; afterburner fail (no fuel when aburn pressed)
$Name: 25 alert_2.wav, 0, 0.40, 0 ; heat-seeker launch warning
$Name: 26 m_fail.wav, 0, 0.60, 0 ; tried to fire a missle when none are left
$Name: 27 l_fail.wav, 0, 0.60, 0 ; tried to fire lasers when not enough energy left
$Name: 28 fail.wav, 0, 0.50, 0 ; target fail sound (i.e. press targeting key, but nothing happens)
$Name: 29 beep_1.wav, 0, 0.50, 0 ; squadmate message menu appears
$Name: 30 beep_1.wav, 0, 0.50, 0 ; squadmate message menu disappears
$Name: 31 debris.wav, 0, 0.40, 2, 100, 300 ; ** debris sound (persistant, looping) (3d sound)
$Name: 32 subhit.wav, 0, 0.60, 0 ; subsystem gets destroyed on player ship
$Name: 33 m_load.wav, 0, 0.60, 1, 10, 50 ; missle start load (during rearm/repair) (3d sound)
$Name: 34 m_lock.wav, 0, 0.50, 1, 10, 50 ; missle load (during rearm/repair) (3d sound)
$Name: 35 repair.wav, 0, 0.50, 0 ; ship is being repaired (during rearm/repair) (looped)
$Name: 36 l_hit.wav, 0, 0.90, 0, 30, 100 ; * player ship is hit by laser fire (3d sound)
$Name: 37 m_hit.wav, 0, 0.90, 0, 30, 100 ; * player ship is hit by missile (3d sound)
$Name: 38 cycle.wav, 0, 0.80, 0 ; countermeasure cycle
$Name: 39 s_hit_4.wav, 0, 0.60, 1, 200, 600 ; * shield hit (3d sound)
$Name: 40 s_hit_2.wav, 0, 0.80, 1, 10, 100 ; * player shield is hit (3d sound)
$Name: 41 select.wav, 0, 0.60, 0 ; mouse click
$Name: 42 alert_3.wav, 0, 0.60, 0 ; aspect launch warning
$Name: 43 beep_4.wav, 0, 0.60, 0 ; shield quadrant transfer successful
$Name: 44 wash.wav, 0, 0.80, 1, 200, 400 ; Engine wash looping sound
$Name: 45 warp_1.wav, 0, 0.60, 2, 750, 1500 ; ** warp hole opening up for arriving (3d sound)
$Name: 46 warp_1.wav, 0, 0.60, 2, 750, 1500 ; ** warp hole opening up for departing (3d sound)
$Name: 47 aburn_1f.wav, 0, 0.50, 0 ; player warp has failed
$Name: 48 static.wav, 0, 0.60, 0 ; hud gauge static
$Name: 49 boom_1.wav, 0, 0.90, 1, 600, 1200 ; * ship explosion 2 (3d sound)
$Name: 50 rev1.wav, 0, 0.70, 0 ; ship is warping out in 3rd person
$Name: 51 s_hit_0.wav, 0, 0.70, 1, 100, 200 ; * heavy ship-ship collide sound (3d sound)
$Name: 52 collide.wav, 0, 0.70, 1, 100, 200 ; * light ship-ship collide sound (3d sound)
$Name: 53 s_hit_1.wav, 0, 0.70, 1, 100, 200 ; * shield ship-ship collide overlay sound (3d sound)
$Name: 54 alert_1.wav, 0, 0.50, 0 ; missile threat indicator flashes
$Name: 55 proximity1.wav, 0, 0.70, 0 ; proximity warning (heat seeker)
$Name: 56 proximity2.wav, 0, 0.70, 0 ; proximity warning (aspect)
$Name: 57 directive.wav, 0, 0.70, 0 ; directive complete
$Name: 58 subhit2.wav, 0, 0.90, 1, 250, 800 ; * other ship subsystem destroyed (3d sound)
$Name: 59 atomic.wav, 0, 0.90, 1, 2000, 4000 ; * captial ship explosion (3d sound)
$Name: 60 subhit2.wav, 0, 0.90, 1, 250, 1500 ; * captial ship subsystem destroyed (3d sound)
$Name: 61 warp2.wav, 0, 1.00, 1, 1500, 2000 ; [obsolete] large ship warps out (looping 3d sound)
$Name: 62 ast_lghit.wav, 0, 0.80, 1, 750, 1500 ; ** large asteroid blows up (3d sound)
$Name: 63 ast_smhit.wav, 0, 0.80, 1, 500, 1000 ; ** small asteroid blows up (3d sound)
$Name: 64 cue_voice.wav, 0, 0.90, 0 ; sound to indicate voice is about to start
$Name: 65 end_voice.wav, 0, 0.90, 0 ; sound to indicate voice has ended
$Name: 66 scan.wav, 0, 0.50, 0 ; cargo scanning (looping)
$Name: 67 l_flyby.wav, 0, 0.80, 1, 50, 250 ; * weapon flyby sound
$Name: 68 asteroid.wav, 0, 0.50, 1, 200, 700 ; [obsolete] asteroid sound (persistant, looping) (3d sound)
$Name: 69 warp_open.wav, 0, 1.00, 2, 2000, 4000 ; capital warp hole opening (3d sound)
$Name: 70 warp_close.wav, 0, 1.00, 2, 2000, 4000 ; capital warp hole closing (3d sound)
$Name: 71 rumble.wav, 0, 0.70, 1, 600, 1000 ; LARGE engine ambient
$Name: 72 subspace_left.wav, 0, 0.30, 0 ; subspace ambient sound (left channel) (looping)
$Name: 73 subspace_right.wav, 0, 0.30, 0 ; subspace ambient sound (right channel) (looping)
$Name: 74 Evaded.wav, 0, 0.70, 0 ; "evaded" HUD popup
$Name: 75 rumble.wav, 0, 0.70, 1, 600, 1000 ; HUGE engine ambient
;
; Weapons section
;
$Name: 76 L_Sidearm.wav, 0, 0.50, 1, 50, 400 ; SD-4 Sidearm laser fired
$Name: 77 L_Scalpel.wav, 0, 0.50, 1, 50, 400 ; DR-2 Scalpel fired
$Name: 78 L_Flail2.wav, 0, 0.50, 1, 50, 400 ; Flail II fired
$Name: 79 L_Prom_R.wav, 0, 0.50, 1, 50, 400 ; Prometheus R laser fired
$Name: 80 L_Prom_S.wav, 0, 0.50, 1, 50, 400 ; Prometheus S laser fired
$Name: 81 L_Newton.wav, 0, 0.50, 1, 50, 400 ; GTW-66 Newton Cannon fired
$Name: 82 L_Kayser.wav, 0, 0.55, 1, 50, 400 ; UD-8 Kayser Laser fired
$Name: 83 L_Circle.wav, 0, 0.50, 1, 50, 400 ; GTW-19 Circe laser fired
$Name: 84 L_Lich.wav, 0, 0.50, 1, 50, 400 ; GTW-83 Lich laser fired
$Name: 85 hit_1.wav, 0, 0.90, 1, 200, 800 ; Laser impact
$Name: 86 L_Vasmid.wav, 0, 0.50, 1, 50, 400 ; Subach-HLV Vasudan laser
$Name: 87 m_wasp.wav, 0, 0.80, 1, 50, 400 ; rockeye missile launch
$Name: 88 boom_2.wav, 0, 0.80, 1, 500, 1000 ; missile impact 1
$Name: 89 m_mag.wav, 0, 0.80, 1, 50, 400 ; mag pulse missile launch
$Name: 90 m_fury.wav, 0, 0.80, 1, 50, 400 ; fury missile launch
$Name: 91 m_shrike.wav, 0, 0.80, 1, 50, 400 ; shrike missile launch
$Name: 92 m_angel.wav, 0, 0.80, 1, 50, 400 ; angel fire missile launch
$Name: 93 m_cluster.wav, 0, 0.80, 1, 50, 400 ; cluster bomb launch
$Name: 94 m_clusterb.wav, 0, 0.80, 1, 50, 400 ; cluster baby bomb launch
$Name: 95 m_stiletto.wav, 0, 0.80, 1, 50, 400 ; stiletto bomb launch
$Name: 96 m_tsunami.wav, 0, 0.80, 1, 50, 400 ; tsunami bomb launch
$Name: 97 m_harbinger.wav, 0, 0.80, 1, 50, 400 ; harbinger bomb launch
$Name: 98 m_mega.wav, 0, 0.80, 1, 50, 400 ; mega wokka launch
$Name: 99 counter_1.wav, 0, 0.70, 1, 50, 200 ; countermeasure 1 launch
$Name: 100 l_alien1.wav, 0, 0.60, 1, 50, 400 ; Shivan light laser (3d sound)
$Name: 101 clusterboom.wav, 0, 0.80, 1, 750, 2000 ; shockwave ignition (3d sound)
$Name: 102 m_swarm.wav, 0, 0.70, 1, 50, 400 ; swarm missile sound (3d sound)
$Name: 103 l_alien2.wav, 0, 0.60, 1, 100, 400 ; Shivan heavy laser (3d sound)
$Name: 104 capital4.wav, 0, 0.70, 1, 500, 1500 ; Vasudan SuperCap engine (3d sound)
$Name: 105 capital5.wav, 0, 0.70, 1, 500, 1500 ; Shivan SuperCap engine (3d sound)
$Name: 106 capital6.wav, 0, 0.70, 1, 500, 1500 ; Terran SuperCap engine (3d sound)
$Name: 107 l_vaslight.wav, 0, 0.60, 1, 50, 400 ; Vasudan light laser fired (3d sound)
$Name: 108 l_alien3.wav, 0, 0.60, 1, 50, 400 ; Shivan heavy laser (3d sound)
$Name: 109 shockwave.wav, 0, 1.00, 1, 50, 800 ; ** shockwave impact (3d sound)
$Name: 110 Turret_T1.wav, 0, 0.50, 2, 200, 1000 ; TERRAN TURRET 1
$Name: 111 Turret_T2.wav, 0, 0.50, 2, 200, 1000 ; TERRAN TURRET 2
$Name: 112 Turret_V1.wav, 0, 0.50, 2, 200, 1000 ; VASUDAN TURRET 1
$Name: 113 Turret_V2.wav, 0, 0.50, 2, 200, 1000 ; VASUDAN TURRET 2
$Name: 114 Turret_S1.wav, 0, 0.50, 2, 200, 1000 ; SHIVAN TURRET 1
$Name: 115 paintloop.wav, 0, 0.60, 1, 50, 200 ; targeting laser loop sound
$Name: 116 FlakLaunch.wav, 0, 0.60, 1, 250, 1000 ; Flak Gun Launch
$Name: 117 boom_4.wav, 0, 0.80, 1, 400, 800 ; Flak Gun Impact
$Name: 118 m_emp.wav, 0, 0.60, 1, 50, 400 ; EMP Missle
$Name: 119 Escape.wav, 0, 0.60, 1, 200, 600 ; Escape Pod Drone
$Name: 120 Vaporize1.wav, 0, 0.70, 0 ; Beam Hit 1
$Name: 121 beam_loop.wav, 0, 0.70, 2, 1500, 3000 ; beam loop
$Name: 122 beam_up.wav, 0, 0.70, 2, 1500, 3000 ; beam power up
$Name: 123 beam_down.wav, 0, 0.70, 2, 1500, 3000 ; beam power down
$Name: 124 beam_shot1.wav, 0, 0.70, 2, 1500, 2500 ; Beam shot 1
$Name: 125 beam_shot2.wav, 0, 0.70, 2, 1500, 2500 ; Beam shot 2
;Ship Engine Sounds section
$Name: 126 ship_a1.wav, 0, 0.60, 1, 200, 400 ; Terran fighter engine (3d sound)
$Name: 127 ship_a2.wav, 0, 0.70, 1, 300, 600 ; Terran bomber engine (3d sound)
$Name: 128 ship_a3.wav, 0, 0.80, 1, 400, 800 ; Terran cruiser engine (3d sound)
$Name: 129 ship_b1.wav, 0, 0.70, 1, 200, 400 ; Vasudan fighter engine (3d sound)
$Name: 130 ship_b2.wav, 0, 0.80, 1, 300, 600 ; Vasudan bomber engine (3d sound)
$Name: 131 ship_b3.wav, 0, 0.80, 1, 400, 800 ; Vasudan cruiser engine (3d sound)
$Name: 132 ship_c1.wav, 0, 0.60, 1, 200, 400 ; Shivan fighter engine (3d sound)
$Name: 133 ship_c2.wav, 0, 0.70, 1, 300, 600 ; Shivan bomber engine (3d sound)
$Name: 134 ship_c3.wav, 0, 0.80, 1, 400, 800 ; Shivan cruiser engine (3d sound)
$Name: 135 beacon.wav, 0, 0.60, 1, 300, 600 ; Repair ship beacon/engine sound (3d sound)
$Name: 136 capital1.wav, 0, 0.70, 1, 500, 1500 ; Terran capital engine (3d sound)
$Name: 137 capital2.wav, 0, 0.70, 1, 500, 1500 ; Vasudan capital engine (3d sound)
$Name: 138 capital3.wav, 0, 0.70, 1, 500, 1500 ; Shivan capital engine (3d sound)
; Electrical arc sound fx on the debris pieces
$Name: 139 Arc_01.wav, 0, 0.30, 2, 200, 500 ; ** 0.10 second spark sound effect (3d sound)
$Name: 140 Arc_02.wav, 0, 0.30, 2, 200, 500 ; ** 0.25 second spark sound effect (3d sound)
$Name: 141 Arc_03.wav, 0, 0.30, 2, 200, 500 ; ** 0.50 second spark sound effect (3d sound)
$Name: 142 Arc_04.wav, 0, 0.30, 2, 200, 500 ; ** 0.75 second spark sound effect (3d sound)
$Name: 143 Arc_05.wav, 0, 0.30, 2, 200, 500 ; ** 1.00 second spark sound effect (3d sound)
; Beam Sounds
$Name: 144 BT_LTerSlash.wav, 0, 0.70, 2, 1500, 3000 ; LTerSlash beam loop
$Name: 145 BT_TerSlash.wav, 0, 0.70, 2, 1500, 3000 ; TerSlash beam loop
$Name: 146 BT_SGreen.wav, 0, 0.70, 2, 1500, 3000 ; SGreen beam loop
$Name: 147 BT_BGreen.wav, 0, 0.70, 2, 1500, 3000 ; BGreen beem loop
$Name: 148 BT_BFGreen.wav, 0, 0.70, 2, 1500, 3000 ; BFGreen been loop
$Name: 149 BT_AntiFtr.wav, 0, 0.70, 2, 1500, 3000 ; Antifighter beam loop
$Name: 150 BT_up_1.wav, 0, 0.60, 2, 1500, 3000 ; 1 sec warm up
$Name: 151 BT_up_1.5.wav, 0, 0.60, 2, 1500, 3000 ; 1.5 sec warm up
$Name: 152 BT_up_2.5.wav, 0, 0.60, 2, 1500, 3000 ; 2.5 sec warm up
$Name: 153 BT_up_3.wav, 0, 0.60, 2, 1500, 3000 ; 3 sec warm up
$Name: 154 BT_up_3.5.wav, 0, 0.60, 2, 1500, 3000 ; 3.5 sec warm up
$Name: 155 BT_up_5.wav, 0, 0.60, 2, 1500, 3000 ; 5 sec warm up
$Name: 156 BT_dwn_1.wav, 0, 0.70, 2, 2000, 3000 ; LTerSlash warm down
$Name: 157 BT_dwn_2.wav, 0, 0.70, 2, 2000, 3000 ; TerSlash warm down
$Name: 158 BT_dwn_3.wav, 0, 0.70, 2, 2000, 3000 ; SGreen warm down
$Name: 159 BT_dwn_4.wav, 0, 0.70, 2, 2000, 3000 ; BGreen warm down
$Name: 160 BT_dwn_5.wav, 0, 0.70, 2, 2000, 3000 ; BFGreen warm down
$Name: 161 BT_dwn_6.wav, 0, 0.70, 2, 2000, 3000 ; T_AntiFtr warm down
$Name: 162 Empty, 0, 0.50, 0
$Name: 163 Empty, 0, 0.50, 0
$Name: 164 Empty, 0, 0.50, 0
$Name: 165 Empty, 0, 0.50, 0
$Name: 166 Empty, 0, 0.50, 0
$Name: 167 Empty, 0, 0.50, 0
$Name: 168 Empty, 0, 0.50, 0
$Name: 169 Empty, 0, 0.50, 0
$Name: 170 Empty, 0, 0.50, 0
$Name: 171 Empty, 0, 0.50, 0
$Name: 172 Empty, 0, 0.50, 0
$Name: 173 SupNova1.wav, 0, 1.00, 0 ; SuperNova (distant)
$Name: 174 SupNova2.wav, 0, 1.00, 0 ; SuperNova (shockwave)
$Name: 175 ship_c4.wav, 0, 0.80, 1, 400, 800 ; Shivan large engine (3d sound)
$Name: 176 ship_c5.wav, 0, 0.80, 1, 400, 1000 ; Shivan large engine (3d sound)
$Name: 177 BS_SRed.wav, 0, 0.70, 2, 1500, 3000 ; SRed beam loop
$Name: 178 BS_LRed.wav, 0, 0.70, 2, 1500, 3000 ; LRed beam loop
$Name: 179 BS_AntiFtr.wav, 0, 0.70, 2, 1500, 3000 ; Antifighter beam loop
$Name: 180 Thunder_01.wav, 0, 0.70, 0 ; Thunder 1 sound in neblua
$Name: 181 Thunder_02.wav, 0, 0.70, 0 ; Thunder 2 sound in neblua
$Name: 182 BS_up_1.wav, 0, 0.60, 2, 1500, 3000 ; 1 sec warm up
$Name: 183 BS_up_1.5.wav, 0, 0.60, 2, 1500, 3000 ; 1.5 sec warm up
$Name: 184 BS_up_3.wav, 0, 0.60, 2, 1500, 3000 ; 3 sec warm up
$Name: 185 Commnode.wav, 0, 0.60, 1, 200, 500 ; Shivan Commnode
$Name: 186 Pirate.wav, 0, 0.60, 1, 400, 1000 ; Volition PirateShip
$Name: 187 BS_dwn_1.wav, 0, 0.70, 2, 2000, 3000 ; SRed warm down
$Name: 188 BS_dwn_2.wav, 0, 0.70, 2, 2000, 3000 ; LRed warm down
$Name: 189 BS_dwn_3.wav, 0, 0.70, 2, 2000, 3000 ; AntiFtr warm down
$Name: 190 Inst1.wav, 0, 0.80, 1, 500, 2000 ; Instellation 1
$Name: 191 Inst2.wav, 0, 0.80, 1, 500, 2000 ; Instellation 2

;SCP ADDED SOUNDS START HERE
$Name: 200 m_load.wav, 0, 0.60, 1, 10, 50 ; Ballistic Weapon Rearm Start
$Name: 201 m_lock.wav, 0, 0.50, 1, 10, 50 ; Ballistic Weapon Rearm
;
#Game Sounds End
;
#Interface Sounds Start
$Name: 0 user_c.wav, 0, 0.70, 0 ; mouse click
$Name: 1 empty, 0, 0.70, 0 ; pick up a ship icon (not used)
$Name: 2 load01.wav, 0, 0.60, 0 ; drop a ship icon on a wing slot
$Name: 3 unload01.wav, 0, 0.60, 0 ; drop a ship icon back to the list
$Name: 4 beep_4.wav, 0, 0.70, 0 ; press briefing, ship selection or weapons bar (top-left)
$Name: 5 user_c.wav, 0, 0.70, 0 ; Switching to a new screen, but not commit
$Name: 6 beep_4.wav, 0, 0.70, 0 ; help pressed
$Name: 7 commit.wav, 0, 0.60, 0 ; commit pressed
$Name: 8 user_c.wav, 0, 0.70, 0 ; prev/next pressed
$Name: 9 user_c.wav, 0, 0.70, 0 ; scroll pressed (and scroll)
$Name: 10 fail.wav, 0, 0.70, 0 ; general failure sound for any event
$Name: 11 shipview.wav, 0, 0.50, 0 ; ship animation starts (ie text and ship first appear)
$Name: 12 main_amb.wav, 0, 0.60, 0 ; ambient sound for the Terran main hall (looping)
$Name: 13 vas_amb.wav, 0, 0.60, 0 ; ambient sound for the Vasudan main hall (looping)
$Name: 14 user_a.wav, 0, 0.70, 0 ; brief stage change
$Name: 15 user_i.wav, 0, 0.70, 0 ; brief stage change fail
$Name: 16 beep_3.wav, 0, 0.70, 0 ; selet brief icon
$Name: 17 user_o.wav, 0, 0.50, 0 ; user_over (mouse over a control)
$Name: 18 user_c.wav, 0, 0.70, 0 ; user_click (mouse selects a control)
$Name: 19 reset.wav, 0, 0.70, 0 ; reset (or similar button) pressed
$Name: 20 textdraw.wav, 0, 0.60, 0 ; briefing text wipe
$Name: 21 Lift_Mix.wav, 0, 0.50, 0 ; main hall - elevator
$Name: 22 weapview.wav, 0, 0.60, 0 ; weapon animation starts
$Name: 23 dooropen.wav, 0, 0.50, 0 ; door in main hall opens
$Name: 24 doorclose.wav, 0, 0.50, 0 ; door in main hall closes
$Name: 25 itemdraw.wav, 0, 0.50, 0 ; glow in main hall opens
$Name: 26 Crane_1.wav, 0, 0.50, 0 ; main hall - crane 1
$Name: 27 sub_amb.wav, 0, 0.60, 0 ; ambient sound for menus off the main hall (looping)
$Name: 28 user_c.wav, 0, 0.70, 0 ; popup dialog box appeared
$Name: 29 user_c.wav, 0, 0.70, 0 ; popup dialog box goes away
$Name: 30 1_yes.wav, 0, 1.00, 0 ; voice clip played when volume slider changes
$Name: 31 Crane_2.wav, 0, 0.50, 0 ; main hall - crane 2
$Name: 32 Option1.wav, 0, 0.70, 0 ; main hall options - mouse on
$Name: 33 Option2.wav, 0, 0.70, 0 ; main hall options - mouse off
$Name: 34 Techroom1.wav, 0, 0.70, 0 ; main hall tech room - mouse on
$Name: 35 Techroom2.wav, 0, 0.70, 0 ; main hall tech room - mouse off
$Name: 36 Exitopen.wav, 0, 0.60, 0 ; main hall exit open
$Name: 37 Exitclose.wav, 0, 0.60, 0 ; main hall exit close
$Name: 38 pa_1.wav, 0, 0.50, 0 ; main hall random intercom 1
$Name: 39 pa_2.wav, 0, 0.50, 0 ; main hall random intercom 2
$Name: 40 pa_3.wav, 0, 0.50, 0 ; main hall random intercom 3
$Name: 41 highlight.wav, 0, 0.40, 0 ; spinning highlight in briefing
$Name: 42 noiz.wav, 0, 0.40, 0 ; static in a briefing stage cut
$Name: 43 Camp_on.wav, 0, 0.70, 0 ; main hall campaign - mouse on
$Name: 44 Camp_off.wav, 0, 0.70, 0 ; main hall campaign - mouse off
$Name: 45 V_Hatch_Open.wav, 0, 0.70, 0 ; vasudan hall - exit open
$Name: 46 V_Hatch_Close.wav, 0, 0.70, 0 ; vasudan hall - exit close
$Name: 47 V_Roll_Open.wav, 0, 0.80, 0 ; vasudan hall - hatch open
$Name: 48 V_Roll_Close.wav, 0, 0.80, 0 ; vasudan hall - hatch close
$Name: 49 V_Lift_Up.wav, 0, 0.70, 0 ; vasudan hall - lift up
$Name: 50 V_Lift_Down.wav, 0, 0.70, 0 ; vasudan hall - lift down
$Name: 51 V_Lite_On.wav, 0, 0.70, 0 ; vasudan hall - glow on
$Name: 52 V_Lite_Off.wav, 0, 0.70, 0 ; vasudan hall - glow off
$Name: 53 Skiff.wav, 0, 0.70, 0 ; vasudan hall - skiff loop
$Name: 54 V_Map_On.wav, 0, 0.70, 0 ; vasudan hall - screen on
$Name: 55 V_Map_Off.wav, 0, 0.70, 0 ; vasudan hall - screen off
$Name: 56 V_Head_1.wav, 0, 0.70, 0 ; vasudan hall - vasudan greeting
$Name: 57 V_Head_2.wav, 0, 0.70, 0 ; vasudan hall - vasudan bye
$Name: 58 V_Pa_01.wav, 0, 0.70, 0 ; vasudan hall - vasudan pa 1
$Name: 59 V_Pa_02.wav, 0, 0.70, 0 ; vasudan hall - vasudan pa 2
$Name: 60 V_Pa_03.wav, 0, 0.70, 0 ; vasudan hall - vasudan pa 3
$Name: 61 bup.wav, 0, 0.90, 0 ; bup bup bup-bup bup bup
$Name: 62 thankyou.wav, 0, 0.90, 0 ; thankyou
$Name: 63 V_Exit_Open.wav, 0, 0.70, 0 ; vasudan hall - exit open
$Name: 64 V_Exit_Close.wav, 0, 0.70, 0 ; vasudan hall - exit close
;
#Interface Sounds End
;
; Each species can have up to 4 different flyby sounds
; NOTE : the parse code expects to see exactly 2 sounds for terran, then 2 for vasudan, then 2 for shivan
; the first sound for each species is the fighter/small flyby sound. the second is the bomber/big flyby sound
#Flyby Sounds Start

$Terran: 0 T_flyby1.wav, 0, 0.75, 1, 200, 400 ; * Terran ship1 flyby player sound (3d sound)
$Terran: 1 T_flyby2.wav, 0, 0.75, 1, 200, 400 ; * Terran ship1 flyby player sound (3d sound)

$Vasudan: 0 V_flyby1.wav, 0, 0.85, 1, 200, 400 ; * Vasudan ship1 flyby player sound (3d sound)
$Vasudan: 1 V_flyby2.wav, 0, 0.85, 1, 200, 400 ; * Vasudan ship1 flyby player sound (3d sound)

$Shivan: 0 S_flyby1.wav, 0, 0.75, 1, 200, 400 ; * SHIVAN ship1 flyby player sound (3d sound)
$Shivan: 1 S_flyby2.wav, 0, 0.75, 1, 200, 400 ; * SHIVAN ship1 flyby player sound (3d sound)

#Flyby Sounds End
</pre>

[[Category:Tables]]

Particle Effects

2017-10-05T08:22:57Z

M!m: Overhaul particle effect documentation based on comments provided by Spoon

{{SCP_table}}

{{TableVersionGit|2016-09-02|417eb20}}

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the [[Modular Tables]] and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual ''+nocreate'' ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with ''+nocreate'' in mind for when that is implemented.

[[Tables|List of Tables]]

=General Info=
*Begins with #Particle Effects
*Contains zero or more particle effect definitions
*Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

==$Effect:==
*Creates a new effect and specifies its name. The name must be at least one character long.
*Syntax: '''String'''

===$Type:===
*Sets the type of this effect. See [[#Effect Types|Effect Types]] for possible values.
*Syntax: '''String'''

=Effect Types=
There are multiple different types of effects. They are specified by passing the given name to ''$Type''.

==Single==
This effect type creates exactly one particle per processing step.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Duration:===
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

===+Delay:===
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

==Composite==
A composite effects contains multiple other effects which are all displayed at the same time. This is useful if you want to create complex effects that require more than one individual particle effect. The amount of child effects is not limited. This type currently does not support ''+nocreate''.

===+Child effect:===
*This specifies a child effect that should be added to the composite effect. The effect is specified using [[#Inline effect creation]].

==Cone==
This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution] around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Deviation:===
*Sets the standard deviation from the direction vector.
*Required if ''+nocreate'' is not present
*Syntax: '''float''', in degrees

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Sphere==
This effect creates particles in a sphere shape around the center.

===+Filename:===
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

===+Size:===
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

===+Lifetime:===
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===+Velocity===
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Number===
*Sets the amount of created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

===+Direction===
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it is currently facing.
**''Normal'': The normal vector of the particle source. This data may not exist for all sources. The debug log file will contain the warning message "<tt>Effect '<EffectName>' tried to use normal direction for source without a normal!</tt>" if an effect tries to use the normal vector without it existing.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot. This direction requires the normal for work properly so the same warning message as above may appear in your log if the source has no normal vector assigned to it.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

===+Trail effect:===
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Inline effect creation==
At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use '''$New Effect''' which will create a new, unnamed effect. If a name is specified then that effect must be already defined. In order to ensure that the effect is always defined no matter in which order the effect tables are parsed the effect should be defined in the same table. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If '''$New Effect''' is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. ''+nocreate'' is not valid within this element.

==Random range==
The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

===Uniform random range===
*This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

===Normal distribution random range===
*This accepts 1 or 2 values. This random range generates values according to a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution]. The first value specified the mean value of the distribution. The second value specifies the standard deviation of the distribution, this defaults to 1.
*Syntax: '''(Random values)''', a list of floating point values. Either one or two values.
**Example: ''(4 20)''

=Example=
<pre>
#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
+Filename: exp05
+Size: (5 7)
+Lifetime: (0.6)
+Deviation: 5
+Velocity: (500 700)
+Number: (20 30)
+Direction: Reflected
+Trail effect: $New Effect
$Type: Single
+Filename: exp20
+Size: (10)
+Lifetime: (1)
+Duration: Always

$Effect: ApocalypseIgnition
$Type: Single
+Filename: exp20
+Size: (10 20)

$Effect: ApocalypseHomed
$Type: Composite
+Child effect: $New Effect
$Type: Single
+Filename: exp05
+Size: (5 7)
+Duration: (2 10)
+Child effect: $New Effect
$Type: Single
+Filename: exp06b
+Size: (5 7)
+Duration: (2 10)
+Delay: (8 15)

#End
</pre>

Game settings.tbl

2017-10-05T07:59:28Z

M!m: Add documentation for $Target Version

{{SCP_table}}

{{TableVersionGit|2015-11-21|71cf169}}

The '''game_settings.tbl''', also known as mod.tbl, defines options that can be changed globally.

This table is one of the [[Modular Tables]] and can be extended with xxx-mod.tbm

[[Tables|List of Tables]]

==#GAME SETTINGS==
Optional. Contains settings that affect how the engine works. 

===$Target Version:===
{{Table373|
Specifies the minimum version of FreeSpace Open that this mod supports. If the version specified here is greater than the version of the current build, an error message is displayed.
}}
{{Table381|
The $Minimum version option has been renamed to $Target Version. The old name is kept with the same functionality for backwards-compatibility.

The target version specifies what version of the FSO engine this mod was created for. It will be used by the engine to enable or disable backwards-incompatible changes by default. The default value is 2.0 which specifies that the mod targets the retail engine version.
}}

====+Major:====
{{Table373|
Required. Sets the major component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Minor:====
{{Table373|
Required. Sets the minor component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''7''''' (for a minimum version of 3.7.3.20151121)
}}

====+Build:====
{{Table373|
Required. Sets the build component of the target version.
*Syntax: '''''Integer''''' 
*Example: '''''3''''' (for a minimum version of 3.7.3.20151121)
}}

====+Revision:====
{{Table373|
Optional. Sets the revision component of the target version. If no revision is given then all builds of that release are supported (even nightly builds if there are any).
For nightly builds this is the date in YYYYMMDD format.
*Syntax: '''''Integer''''' 
*Example: '''''20151121''''' (for a minimum version of 3.7.3.20151121)
}}

==#CAMPAIGN SETTINGS==
Optional. This group contains various Campaign related settings and overrides. 

===$Default Campaign File Name:===
Defines which campaign will be selected by default for new pilots. A file extension is not needed and, if present, is removed by the code.
*Syntax: '''''String''''' 

===#Ignored Campaign File Names===
Optional. Defines which campaigns, if present, will not appear in the Campaign Room. Only single-player campaigns can be ignored. ''File extensions are required.''
{{Table371|As of 3.7.1, file extensions are not required and, if present, are removed by the code.}}
====$Campaign File Name:====
File name of the campaign to ignore. Multiple entries may exist.
*Syntax: '''''String''''' 

===$Red-alert applies to delayed ships:===
Controls whether red-alert saved statistics (hitpoints, weapons, subsystem strengths) will be restored for ships that are not present at mission start.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#HUD SETTINGS==
Optional. This group contains various HUD behavior settings and overrides 

===$Directive Wait Time:===
*Defines how long the game will wait before displaying a directive.
*Syntax: '''''Integer''''' 
*Values: '''''Greater than or equal to 0 ms'''''

===$Cutscene camera displays HUD:===
Show the HUD when the cutscene camera is enabled.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Cutscene camera disables HUD: and had a default of YES.

===$Full color head animations:===
Enables full-color head ANIs. Normal head ANIs will appear in gray.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Color head animations with hud colors: and had a default of YES.

==#SEXP SETTINGS==
Optional. This group contains SEXP settings and overrides. 

===$Loop SEXPs Then Arguments:===
Flips how when-argument settings loop. See: [http://www.hard-light.net/forums/index.php?topic=79602.0 SEXP Argument changes via mod.tbl]
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

===$Use Alternate Chaining Behavior:===
When set, this makes the event chaining behavior act as people expected it to be in [http://scp.indiegames.us/mantis/view.php?id=82 Mantis #82].
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#GRAPHICS SETTINGS==
Optional. This group contains settings related to graphics. 

===$Enable External Shaders:===
Enables the use of external shader files. By default, the engine will use the built-in shaders.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default Detail Level:===
{{Table3615|
Determines which graphics detail level preset (low, medium, high, very high) acts as the default for new pilots.
*Syntax: '''''Integer''''' (0-3)
*Default Value: '''''3''''' (very high) }}

===$Briefing Window FOV:===
{{Table371|
Determines the FOV in the briefing Icon window. Retail default for this is 0.29375, previous versions of FSO used a value of 0.5.
*Syntax: '''''Float''''' (0.0 to 1.0)
*Default Value: '''''0.29375''''' }}

===$Generic Pain Flash Factor:===
{{Table373|
Determines the intensity of the pain red flash when the player is hit.
*Syntax: '''''Float'''''
*Default Value: '''''1.0''''' }}

===$Shield Pain Flash Factor:===
{{Table373|
Determines the intensity of a pain flash when the player's shields are hit. Color will match the current ships shield color defined in ships.tbl. A value of 0 will give retail behavior (no shield effect). Positive values will cause the effect to start at full intensity at full shields and go to next to no intensity at zero shields. Negative values will cause no effect at full shields and full effect at no shields. Values should be kept between -1.0 and 1.0 for good pilot visibility.
*Syntax: '''''Float'''''
*Default Value: '''''0.0''''' }}

==#SOUND SETTINGS==
Optional. This group contains sound-related settings 

===$Default Sound Volume:===
{{Table371|
*Defines the default sound fx volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''1.0'''''}}

===$Default Music Volume:===
{{Table371|
*Defines the default music volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.5'''''}}

===$Default Voice Volume:===
{{Table371|
*Defines the default voice volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.7'''''}}

==#FRED SETTINGS==
Optional. This group contains settings for FRED. 

===$Disable Hard Coded Message Head Ani Files:===
{{table371|
If set, FRED will not fill the head ani selection in the Event Editor with the retail head ani filenames.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' }}

==#OTHER SETTINGS==
Optional. This group contains miscellaneous settings. 

===$Fixed Turret Collisions:===
Makes all hits to a turret's barrels count as hits to the turret subsystem. By default, this does not happen unless the point of impact falls inside the model radius of the turret's base.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Damage Impacted Subsystem First:===
If set, a hit to a physical subsystem will always deal damage to that subsystem first, even if another subsystem is closer to the point of impact. By default, the closest subsystem will always receive damage first.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default ship select effect:===
{{Table3615|
*This specifies which effect to use for ship select animations when no .ani can be found, or the -ship_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Default weapon select effect:===
{{Table3615|
*This specifies which effect to use for weapon select animations when no .ani can be found, or the -weapon_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Weapons inherit parent collision group:===
{{Table3615|
*When set to true, Weapons fired by a ship will inherit their parents' collision group setting. Default is false.}}

===$Flight controls follow eyepoint orientation:===
{{Table371|
*Specifies that if the player ship's eyepoint happens to rotate into a non-standard orientation, pitch and yaw axes should stay relative to the eyepoint orientation, not the ship. Note that this does not affect the pitch/yaw turning speed, which always remains relative to the ship. Default is false.}}

===$Beams Use Damage Factors:===
{{Table371|
*Specifies that beam weapons will use the tabled damage factors for Armour, Shields and Subsystems. Default is false (i.e. all factors are treated as 1.0)}}

===$Default fiction viewer UI:===
{{Table373|
*Specifies which fiction viewer layout to use in missions that don't specify one. Possible values are as follows:
**"FS2": Standard layout. Requires (2_)fictionviewer and (2_)fictionviewer-m to be present in data\interface.
**"WCS": Moves the "Accept" button to the lower-left corner of the screen. Requires (2_)fictionviewerb and (2_)fictionviewer-mb to be present in data\interface.
**"auto": Selects "WCS" if the appropriate files are present; otherwise, selects "FS2". This is the default setting.}}

==#END==
Required. The last line of the table must be #END

==Sample Entry==

#CAMPAIGN SETTINGS
$Default Campaign File Name: NewCampaignFile

#Ignored Campaign File Names
$Campaign File Name: FreeSpace2.fc2

#HUD SETTINGS
$Directive Wait Time: 5000

#SEXP SETTINGS
$Loop SEXPs Then Arguments: True

#OTHER SETTINGS
$Fix Turret Collisions: True

#END

[[Category:Tables]]

Weapons.tbl

2016-09-27T10:59:19Z

M!m: Add previously undocumented FOF spread options

{{TableVersionGit|2016-06-05|cb9c669}}

The '''weapons.tbl''' defines all of the weapon classes used in FSO.

This table is one of the [[Modular Tables]] and can be extended with xxx-wep.tbm

[[Tables|List of Tables]]

==Introduction==
The weapons.tbl is responsible for defining the behavior of the numerous weapon effects used in FSO, including the amount of damage dealt, the firing rate, and graphical effects.

This wiki page goes over all of the entries used exclusively in the weapons.tbl file. Hyperlinks to individual weapon creation/editing tutorials are provided when appropriate.

==Special Case Weapons==
===Beam Cannons===
'''REQUIRES:'''
*'''"beam"''' flag
*'''[[weapons.tbl#$BeamInfo:|$BeamInfo:]]'''

See also: [http://www.hard-light.net/wiki/index.php/Tutorial_-_Beam_Weapons Tutorial - Beam Weapons]

===Flak Guns===
'''REQUIRES:'''
*'''"flak"''' flag
*'''"particle spew"''' flag
*Must have inner and outer radius defined to have any effect.
*A '''.pof''' model must be defined ( usually '''Hornet.pof''' )
**Note: the model is not actually used... Instead, it uses [[Weapons.tbl#$Pspew:|particle spew]]. Trails may also be added.

==General Format==
*The weapons table consist of several sections
*All sections beginning with <nowiki>#</nowiki> need <nowiki>#</nowiki>'''End''' before the next section.
**<nowiki>#</nowiki>'''Primary Weapons'''
***Defines all '''standard primaries weapons''' as well as '''beam cannons''' and '''flak cannons'''.
**<nowiki>#</nowiki>'''Secondary Weapons'''
***Defines all '''secondary weapons'''.
**<nowiki>#</nowiki>'''Beam Weapons'''
***I haven't got any ideas for this one.
**<nowiki>#</nowiki>'''[[Weapons.tbl#Countermeasures|Countermeasures]]'''
***Defines the used countermeasure.
**'''$Player Weapon Precedence'''
***Player Weapon Precedence is used in weapon selection when a default specified by the mission designer is not available to the player. The next weapon on the list is used in its place (assuming that weapon is allowed for the player).

==Core Table==

===$Name:===
*This is the name of the weapon. If it's going to be used by the player, keep it under 12 characters so it doesn't spill over the HUD box. Two special characters can be used in the name: '''#''' and '''@'''. Their usage details are the very same than inside the [[Ships.tbl#.24Name:_2|$Name field from Ships.tbl]].
*Syntax: '''''String'''''

====+nocreate====
{{Table3610|
*In [[Modular Tables]] name can be followed by line '''+nocreate''' that prevent game from creating an incomplete entry by leaving the entry unread unless it already exists (either in Weapons.tbl or in earlier parsed *-wep.tbm files) by the time the *-wep.tbm is read.}}

===$Alt Name:===
{{Table3611|
*An alternative name that can be referenced instead of $Name:
*Syntax: '''''String'''''}}

===$Subtype:===
{{Table3610|
Specifies the weapon 's subtype. Overrides the default subtype as specified by the #-section it is in (#Primary, #Secondary, #Beam Weapon, etc.).

{{Note|
:Since the weapon subtype is already specified by the #-section it is in, this option is not particularly useful when the weapon is inside a #Primary or #Secondary section. However, it may be used to specify the weapon slot it uses on fighters/bombers for weapons that are normally capship only (such as beam cannons).}}

*Syntax: '''''String'''''
*Valid Entries:
:Primary
:Secondary}}

===+Title:===
*This is the title of the weapon in the Weapons loadout screen. Only needed for player allowed weapons. Title may be anything. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Syntax: XSTR('''''"String"''''', -1)

===+Description:===
*This is the description you see in the weapons loadout screen. Again, these aren't based on any hard numbers, just approximations. Only needed for player allowed weapons. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Must be followed by '''$end_multi_text'''

'''Example'''

<pre>
XSTR(
"''Standard Issue
''Level 3 Hull Damage
''Level 2 Shield Damage''", -1)
$end_multi_text
</pre>

===+Tech Title:===
*Title of the weapon in the Tech room. Only needed for player allowed weapons.
*Syntax: XSTR('''''"String"''''', -1)

===+Tech Anim:===
*Animation used for the weapon in the Tech room. Only needed for player allowed weapons.
*Syntax: '''''String''''', animation filename
**Example: ''Tech_Subach_HL-7''

===+Tech Description:===
*Descriptive text you see in the tech room. Only needed for player allowed weapons. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Must be followed by '''$end_multi_text'''

'''Example'''

<pre>
XSTR(
"''The Subach-Innes HL-7...''", 3245)
$end_multi_text
</pre>

===$Tech Model:===
{{Table3610|
*Defines model used in wing loadout screen for the weapon. 3D weapon models in the tech room have not yet been implemented.
*Syntax: '''''String.pof''''', model filename}}

====+Closeup_Pos:====
{{Table3613|
*How the model will show on the Loadout Screen. The position of the camera relative to the model center.
*Syntax: '''''Vector''''', three '''floats''', x, y and z values respectively}}

====+Closeup_Zoom:====
{{Table3613|
*How the model will show on the Loadout Screen. How far the camera's zoomed in, defines camera's FOV.
*Syntax: '''''Float''''', radians}}

===$Selection Effect:===
{{Table3613|
*Defines which selection effect to use when the -weapon_choice_3d commandline flag is enabled or no ani can be found for the selected weapon.
*Syntax: '''''String''''', either "FS1", or "Off". This defaults to the FS2 effect.
}}

===$HUD Image:===
{{Table3610|
*Defines the picture used to represent the weapon in HUD loadout list
*Syntax: '''''String''''', filename}}

===$Model File:===
*Filename of the model file (.pof) at data/models folder. Additional fields beginning from '''''@Laser Bitmap:''''' and ending to '''''@Laser Tail Radius:''''' are not needed if a model has been defined for the weapon.
*Standard primaries and beam cannons do not use specific models so for those the name is 'none'.
*Flak weapons and secondaries use models, though the exact model is not important with the flak weapons.
*Syntax: '''''String.pof''''' or ''none'', model filename
**Example: ''none''

===$POF target LOD:===
{{Table3610|
*Defines the LOD (Level-Of-Detail) of the model used in HUD targeting view
*Syntax: '''''Integer'''''}}

===$Detail Distance:===
{{Table3613|
*Defines the distance where the change between different Levels-Of-Details (LODs) occurs
*Take notice that these are base values. Model detail in Detail options, (within game press F2), applies a multiplier to these values. These multipliers are (from left to right): 1/8, 1/4, 1, 4, 8
*Optional. If not defined the game uses the formula ((radius * 20.0 + 20.0) * LOD)
*Syntax: '''''(Detail Distances)''''' , list of '''integers''' (same amount as LODs), distances from the model in meters
**Example: ''(0, 80, 300, 900)''}}

===$External Model File:===
{{Table3610|
*Defines the models shown on the gunpoint, used with Bobb's external-visible-weapon code.
*Syntax: '''''String.pof''''', model filename}}

===$Submodel Rotation Speed:===
{{Table3610|
*Defines the rotation speed of the subobject, with the $gun_rotation property defined, in the external weapon model.
*Syntax: '''''Float'''''
*Note: weapon fire will be delayed by the time it takes for the weapon to spin up to this speed (using $Submodel Rotation Acceleration or its default value), regardless of whether an external model is used or not.
}}
{{Table38|
*Note: It's no longer required that the ship actually have external models enabled (whether or not this weapon has one defined) for the spin up delay to occur.
}}

===$Submodel Rotation Acceleration:===
{{Table3610|
*Defines the rotation acceleration of the external weapon model.
*Syntax: '''''Float'''''
*Default value: 10}}

===@Laser===
In the event a 3D model is not defined for the weapon, FSO creates an object similar to a glowpoint. Essentially, it is a 2D plane that always faces the player's camera with an additive texture applied to it, and may or may not have an omnilight follow it.

As suggested by its name, this option group is normally used for lasers and similar primaries, but it may also be used for other weapon types as well.

Unless said otherwise, the graphic files used within this group may be of any compatible type (.DDS, .PCX, .TGA, etc.), however a .DDS is recommended.

====@Laser Bitmap:====
Defines the graphic file to be used as the weapon effect.

Blending type: additive

Syntax: '''''String''''', filename

'''Example:'''
<pre>
@Laser Bitmap: my_laser_bitmap
</pre>

====@Laser Glow:====
Defines the graphic file to be used for the glowmap of the weapon effect.

Blending type: additive

*This file is 'multiplied' by a value between Color and Color2.
*The physical dimensions of the glowmap in-game is 2x the size of the bitmap.

Syntax: '''''String''''', filename

'''Example:'''
<pre>
@Laser Glow: my_laser_glowmap
</pre>

====@Laser Color:====
The RGB color of the glow effect.

*The color is applied both to the glowmap and the omnilight that follows the effect.

Syntax: '''''Color''''', red, green, blue respectively, 8-bit value from 0 to 255

'''Example:'''
<pre>
@Laser Color: 255, 0, 0 ; Red glow effect at the start of the effect's lifetime
</pre>

====@Laser Color2:====
The RGB color of the glow effect at the end of the effect's lifetime (at its maximum range).

*The color is applied both to the glowmap and the omnilight that follows the effect.
*The actual color of the glow effect is somewhere in between the values defined by Color and Color2. Essentially, the actual color "fades" from Color to Color2 over its lifetime.
**If Color is not defined, then a default value of 255, 255, 255 is assumed for its initial color.

Syntax: '''''Color''''', red, green, blue respectively, 8-bit value from 0 to 255

'''Example:'''
<pre>
@Laser Color2: 0, 0, 255 ; Blue glow effect at the end of the effect's lifetime.
</pre>

'''Example:'''
<pre>
@Laser Color: 255, 0, 0 ; Start with a Red glow effect, and fade into...
@Laser Color2: 0, 0, 255 ; a Blue glow effect over the lifetime of the effect.
</pre>

====@Laser Length:====
Defines the length of the weapon effect.
*This option stretches the 2D plane "away" from its origin.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Length: 1.0
</pre>

====@Laser Head Radius:====
Defines the width of the leading edge, or "head," of the weapon effect.
*The edge of the 2D plane farthest away from its origin is the leading edge.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Head Radius: 0.75
</pre>

====@Laser Tail Radius:====
Defines the width of the trailing edge, or "tail" of the weapon effect.
*The edge of the 2D plane that is closest to its origin is the trailing edge.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Tail Radius: 0.75
</pre>

===$Mass:===
*How much of a kinetic effect this weapon has on its target. 3+ gives you the Flail effect. Set it to 10 and you can knock cruisers around.
*This is somehow multiplied by the speed. ie ''$Mass: 3'' and ''$Velocity: 200'' has much weaker kinetic effect than ''$Mass: 3'' and ''$Velocity: 1000''. Also $Mass is used to calculate intensity of "shudder" effect if flagged.
*Syntax: '''''Float''''', blast effect

===$Velocity:===
*How fast the weapon travels. Is also used to define the weapon range, '''''$Velocity x $Lifetime = range'''''.
*Beams travel instantly so this field has effect only on weapon range and AI beam targeting with certain beam types. $Velocity of beam also applies to its kinetic effect along with $Mass.
*Syntax: '''''Float''''', meters per second

===$Fire Wait:===
*Time in seconds between firings
*Note that Fire wait will be reset to 1 if it is set over 5 for non turreted primary weapons (doesn't apply to 3.6.14+)
*Syntax: '''''Float''''', seconds

====+Max Delay:====
{{Table373|
*Defines the maximum amount of time it takes to refire a weapon in a random fire delay range.
**This must be used with +Min Delay: to have any effect.
*Syntax: '''''Float''''', seconds}}

====+Min Delay:====
{{Table373|
*Defines the minimum amount of time it takes to refire a weapon in a random fire delay range.
**This must be used with +Max Delay: to have any effect.
*Syntax: '''''Float''''', seconds}}

===$Damage:===
*Base damage this weapon does. The actual damage is this number multiplied by the factors below.
*Base damage this beam does is continuous damage, damage is 5.5 times the damage value per second. The actual damage is this number multiplied by one of the factors below.
*Syntax: '''''Float''''', damage
*Note: adding a shockwave to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x shockwave)

===$Damage Time:===
{{Table373|
*This sets a time from the end of the weapons lifetime that damage will start to attenuate at. '''''Example: Weapon lifetime is 2.0 seconds and the desired effect is to attenuate after 0.5 seconds have passed, set this to 1.5 seconds.'''''
*Syntax: '''''Float''''', seconds. Defaults to 0.0.
**Note: If neither +Min Damage: nor +Max Damage: is set, the damage will always attenuate to zero at max range.
***If both +Min Damage: and +Max Damage: are set, both are defaulted to 0.0 and damage will be attenuated to zero.}}

====+Attenuation Damage:====
{{Table373|
*This sets the damage a weapon will attenuate to after reaching $Damage Time:.
*Syntax: '''''Float''''', damage.}}

====+Min Damage:====
{{Table373|
*This sets the lowest amount of damage possible assuming damage attenuation is taking place. '''''This has been deprecated, please use +Attenuation Damage: instead.'''''
*Syntax: '''''Float''''', damage. Defaults to 0.0.}}

====+Max Damage:====
{{Table373|
*This sets the highest amount of damage possible assuming damage attenuation is taking place. '''''This has been deprecated, please use +Attenuation Damage: instead.'''''
*Syntax: '''''Float''''', damage. Defaults to 0.0.}}

===$Damage Type:===
{{Table3610|
Defines the damage type that this weapon uses. All armor effects are applied after shield and have no function against shockwave or subsystem damage.

'''REQUIRES:''' [[armor.tbl]]

*Syntax: '''''String''''', name of the damage type ( as defined by [[armor.tbl#$Damage Type:|$Damage Type]] )}}

===$Arm time:===
{{Table3610|
*Defines the time after the launch that is required before the weapon comes hot
*If the time has not been reached when the weapon detonates the Dinky explosion is used
*Syntax: '''''Float''''', seconds}}

===$Arm distance:===
{{Table3610|
*Defines the distance from the firing ships that is required before the weapon comes hot
*If the distance has not been reached when the weapon detonates the Dinky explosion is used
*Syntax: '''''Float''''', meters}}
{{Table3615|
*This parameter is also applied to flak weapons. Previous behaviour was to arm weapons after 10 meters of travel.}}

===$Arm radius:===
{{Table3610|
*Defines the distance from the target where the weapon will arm itself
*Syntax: '''''Float''''', meters}}

===$Detonation Range:===
{{Table3610|
*Defines the distance from the point in space that the weapon was launched where the weapon will detonate
*Syntax: '''''Float''''', meters}}

===$Detonation Radius:===
{{Table3610|
*Defines the distance between the target center point point and the weapon which detonates the weapon.
*Syntax: '''''Float''''', meters}}

===$Shockwave damage:===
{{Table3610|
*Override for the damage caused by shockwaves (default is [[#$Damage:]])
*Syntax: '''''Float''''', damage
*Note: adding a shockwave to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x shockwave)
}}

===$Shockwave Damage Type:===
{{Table3610|
*'''REQUIRES ADDITIONAL TABLE'''. Defines the damage type used for the weapon explosions
*Syntax: '''''String''''', name as defined in [[armor.tbl]]}}

===$Flak Detonation Accuracy:===
{{Table3615|
*Normally, flak weapons detonate at a range of 65 to 99 meters from their intended target, depending on the firing ships' weapon subsystem health. This parameter can be used to adjust this behaviour, as it defines the base range used to determine this detonation range. Standard value is 65.
*Syntax: '''''Float''''', range in meters}}

===$Flak Targeting Accuracy:===
{{Table3615|
*Turret-fired flak weapons are normally firing in a cone around the target's predicted position. This parameter can be used to adjust the size of this cones' base radius. Standard is 60 meters.
*Syntax: '''''Float''''', radius in meters}}

===$Untargeted Flak Range Penalty:===
{{Table3615|
*If a flak weapon is fired without a target selected, this parameter defines the range penalty applied to that weapon. Standard is 20 meters, meaning an untargeted flak weapon will detonate after travelling its max range - 20 meters.
*Syntax: '''''Float''''', penalty in meters.}}

===$Blast Force:===
*The intensity of the kinetic blast effect when ship is within the outer radius of the explosion. Comes in effect only if inner and outer radius are defined.
*Syntax: '''''Float''''', blast effect

===$Inner Radius:===
*Radius at which the full explosion damage is done. Marks the line where damage attenuation begins. Damage is reduced by the square of the distance between the inner radius and outer radius. i.e. half way between inner and outer results in 1/4 damage
*Syntax: '''''Float''''', meters

===$Outer Radius:===
*Maximum radius at which any damage is done. See $Inner Radius for the attenuation formula.
*Also defines the size of the shockwave (if shockwave speed is > 0)
*Syntax: '''''Float''''', meters

===$Shockwave Speed:===
*Speed shockwave expands at. Zero means no shockwave and that damage is applied immediately
*Syntax: '''''Float''''', meters per second

===$Shockwave rotation:===
{{Table3610|
*Defines how the 3D shockwave is rotated.
*Syntax: '''''Angle''''', three values, pitch, bank, heading respectively, in degrees}}

===$Shockwave model:===
{{Table3610|
*Defines the model file (.pof) used as a shockwave for the 3D shockwaves.
*Syntax: '''''String.pof''''', model filename}}

===$Shockwave name:===
{{Table3610|
*Defines the name of the animation used for the 2D shockwave
*Syntax: '''''String''''', filename}}

===$Dinky shockwave:===
{{Table3610|
*Dinky shockwave are used if the weapon is shot down before arming or if the conditions marked at '''Arm time''' and '''Arm distance''' are not reached before impact
*It uses exactly same entries as the standard shockwaves
*'''''+Shockwave damage:'''''
*'''''+Shockwave damage type:'''''
*'''''+Blast Force:'''''
*'''''+Inner Radius:'''''
*'''''+Outer Radius:'''''
*'''''+Shockwave Speed:'''''
*'''''+Shockwave Rotation:'''''
*'''''+Shockwave Model:'''''
*'''''+Shockwave Name:'''''}}

===$Armor Factor:===
*Multiplier for the damage done to armor
*Syntax: '''''Float''''', damage multiplier

===$Shield Factor:===
*Multiplier for the damage done to shields
*Syntax: '''''Float''''', damage multiplier

===$Subsystem Factor:===
*Multiplier for the damage done to subsystems
*Syntax: '''''Float''''', damage multiplier

===$Lifetime Min:===
{{Table3610|
*Defines the minimum lifetime of the weapon
*Syntax: '''''Float''''', seconds}}

===$Lifetime Max:===
{{Table3610|
*Defines the maximum lifetime of the weapon
*Syntax: '''''Float''''', seconds}}

===$Lifetime:===
*Time before the standard primaries fizzle out and secondaries self destruct. Multiply this by the speed to get the range. If values are too low (below framerate) then the collision detection and graphic effects may suffer.
*This field has no effect for the beams apart from weapon range and AI beam targeting with certain beam types
*Syntax: '''''Float''''', seconds

===$Energy Consumed:===
*The amount of energy each bolt drains firing ship. Has no effect on turretted weapons.
*Syntax: '''''Float'''''

===$Cargo Size:===
*Cargo size, is not used with non-ballistic primaries.
*Amount of missiles available = Bank capacity / Cargo Size.
*Syntax: '''''Float'''''

===$Homing:===
'''This option is exclusive to secondaries.'''

Defines if the bolts/missiles in question is homing
*The bolts of primaries will turn to face their target if this option is set to YES... but is otherwise the same as a normal bolt ( when the option is set to NO ).

If set to NO, then following fields are not required in the table.

*Syntax: '''''Boolean''''', yes or no

===='''+Type:'''====
Defines the homing method
*Syntax: '''''String''''', ''ASPECT'' or ''HEAT''
{{Table3610| An additional option, ''JAVELIN'', has been added. This behaves like an aspect missile but automatically only locks onto the engines of a target, and only if the engines are in sight.}}

===='''+Turn Time:'''====
Determines how well the missile maneuvers. Is defined as the number of seconds it takes the missile to do a 360 degree circle
**Syntax: '''''Float''''', seconds

===='''+View Cone:'''====
'''Heat-seeking missiles only'''

This is the width of the weapon's viewing cone, given in degrees. Objects outside this cone are effectively invisible to the missile. The value / 2 gives the angle from the missile's centerline to the edge of the viewing cone.
*Syntax: '''''Float''''', degrees
{{Table3610| Has been enabled also to aspect seekers as an option.}}

===='''+Min Lock Time:'''====
'''For aspect/javelin missiles only'''

The minimum number of seconds to gain a target lock.
*Syntax: '''''Float''''', seconds

===='''+Lock Pixels/Sec:'''====
'''For aspect/javelin missiles only'''
The number of pixels the aspect triangle moves per second while attempting lock-on.

*Syntax: '''''Integer''''', pixels per second

===='''+Catch-up Pixels/Sec:'''====
'''For aspect/javelin missiles only'''

The number of pixels moved per second while attempting to catch up to the target.
*Syntax: '''''Integer''''', pixels per second

===='''+Catch-up Penalty:'''====
'''For aspect/javelin missiles only'''

Extra pixels to move after catching up. (Needs verification )
**Syntax: '''''Integer''''', pixels

===='''+Seeker Strength:'''====
{{Table3610|
Defines the seeking ability of the homing system. Default of heat seekers is 3.0 and for aspect seekers 2.0. Spoofing chance is defined as '''[[#$Countermeasure:|cm type effectiveness]]'''/'''seeker strength''' (missile must be within the countermeasures '''[[#$Countermeasure:|+Effective Radius:]]'''
*Syntax: '''''Float''''', seeker strength}}

===='''+Target Lead Scaler:'''====
{{Table3611|
Defines the type of pursuit course the missile tries to obtain.
*Values < 0 give lag pursuit, values ~ 0 give pure pursuit, values > 0 give lead pursuit.
*Syntax: '''''Float''''', default for heat seekers: 0, default for aspect or javelin seekers: 1.}}

===$Swarm:===
*The number of missiles to fire per volley if it's a swarm missile
*Can be issued to Standard primaries also. Causes single part turrets to malfunction but causes multi part turrets to fire only on their barrel line. Can be used for 'burst fire weapons'. Does not work with player weapons.
*Is incompatible with "Corkscrew" option.
*Syntax: '''''Integer''''', number of shots in a swarm
{{Table3610|
*'''+SwarmWait:'''
**Defines the time between weapons fired in a swarm
**Syntax: '''''Float''''', seconds
***Default: 0.150
***Max: 0.5 (Resets to default if set over 0.5)}}

===$Acceleration Time::===
{{Table371|
*Defines how long it takes for a secondary weapon to attain full speed. Takes precedence over $Free Flight Time (see below) in terms of the weapon's velocity, and affects both locked-on and dumbfired secondaries.
*Syntax: '''''Float''''', seconds
**Default: 0.0}}

===$Velocity Inherit::===
{{Table371|
*Defines how much of the parent ship's velocity to inherit, if [[Ai_profiles.tbl#.24use_additive_weapon_velocity:]] is used.
*Syntax: '''''Float''''', percents
**Default: 100.0}}

===$Free Flight Time:===
{{Table3610|
*Defines the free flight time of homing weapons. During this time weapon flies at 1/4 of its velocity + firing ships velocity in a straight line.
*Syntax: '''''Float''''', seconds
**Default: 0.25}}

'''Note:''' due to dumbfires never changing their speed, using this on a dumbfire missile will have it stuck at freeflight speed even after the end of the freeflight time.

===$Free Flight Speed:===
{{Table3613|
*Defines the speed that the weapon will be travelling at during the free flight segment (see above).
*Syntax: '''''Float''''', Multiplier for the actual speed, minimum 0.01.
**Default: 0.25
{{Note| This feature was never implemented correctly and was removed in r8867. FSO currently parses but doesn't use the value, and prints a warning in the log saying that the value will not be used.}}
}}

===$PreLaunchSnd:===
{{Table3613|
*Defines the one-shot sound effect to play at the beginning of a firing stream. Currently only has an effect on primary weapons.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
**Default: No Sound}}

===+PreLaunchSnd Min Interval:===
{{Table3613|
*Defines Minimum interval between when the player stops firing and the next time the pre-launch sound can play, as a limiter in case the player is pumping the trigger.
*Syntax: '''''Integer''''', Minimum delay in milliseconds between the end of the previous firing sequence and the next time the pre-launch sound effect will be played.
**Default: 0 (play pre-launch sound at the beginning of every firing sequence, if present)}}

===$LaunchSnd:===
*Corresponding sound effect when the weapon is launched.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$ImpactSnd:===
*Sound the weapon makes when it hits a hull.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$Disarmed ImpactSnd:===
{{Table3610|
*Sound the weapon makes when it hits a hull before being armed.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$FlyBySnd:===
*The sound this weapon makes if it narrowly misses you. -1 is no sound.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]], usually -1

===$TrackingSnd===
{{Table3615|
*The looping sound played when this weapon tracks a target.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$LockedSnd===
{{Table3615|
*The sound played when this weapon has locked onto its target.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$InFlightSnd===
{{Table3615|
*The looping sound played when the missile is currently flying.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+Inflight sound type'''
**Specifies when the in flight sound is played.
**The value can be one of the following values which are matched case-insensitively:
***''''''TARGETED'''''': The sound is played when the missile tracks a target
***''''''UNTARGETED'''''': The sound is played when the missile is currently not tracking a target
***''''''ALWAYS'''''': The sound is played always}}

===$Model:===
{{Table3610|
*Defines used model file. Included for compatibility with countermeasures as they have been merged with weapons in the code.
*Syntax: '''''String.pof''''', model filename}}

===$Rearm Rate:===
*Defines the rate the weapons are loaded to the ship
*Syntax: '''''Float''''', missiles loaded per second

===+Weapon Range:===
*Defines the range to the target where the weapons under AI will start firing.
*Syntax: '''''Float''''', meters

===+Weapon Min Range:===
{{Table3610|
*Defines the minimum range to the target where the weapons under AI will still fire.
*Implemented before FS_Open 3.6.5
*Syntax: '''''Float''''', meters}}

===$Flags:===
*See [[Weapons.tbl#Weapons.tbl_Flags|below]]
*Syntax: '''''( "String" "String" )''''', names of the flags assigned to the weapon
**Example: ( "Player allowed" "in tech database" )

{{Table3610|
*Can be followed by '''+override''' option in order to reset the weapon flags before parsing in the new ones
*Using this option will erase all '''homing'''-related flags as well as '''swarm''', '''variable lead''', '''trail''', '''TAG''', and '''transparent''' settings in addition to the listed flags. All these should be set again - if they are required - when this option is used.

**Syntax: '''''+override'''''}}

===$Trail:===
*This is used if you want your weapon to have a trail. Trail is often used only with secondaries though it works with standard primaries as well.
*'''+Start Width:'''
**How wide the head of the trail is.
**Syntax: '''''Float''''', meters
*'''+End Width:'''
**How wide the tail of the trail is.
**Syntax: '''''Float''''', meters
*'''+Start Alpha:'''
**The opacity of the trail head.
**Syntax: '''''Float''''', value between 0 and 1
*'''+End Alpha:'''
**The opacity of the trail tail.
**Syntax: '''''Float''''', value between 0 and 1
*'''+Max Life:'''
**How long the trail lasts.
**Syntax: '''''Float''''', seconds
*'''+Bitmap:'''
**The graphic file to use for the trail.
**Syntax: '''''String''''', filename
{{Table3611|
*'''+Faded Out Sections:'''
**Defines the number of the trail sections (counting from the leading edge) which are gradually faded out.
**Syntax: '''''Integer''''', number of trail sections}}

===$Icon:===
*Loadout icon used in the weapons selection screen.
*Syntax: '''''String''''', filename

===$Anim:===
*Green grid animation used on the weapons screen.
*Syntax: '''''String''''', filename

===$Collide Ship:===
{{Table3610|
*Has been replaced with '''#Conditional Hooks''', see [[Scripting.tbl]]}}

===$Collide Weapon:===
{{Table3610|
*Has been replaced with '''#Conditional Hooks''', see [[Scripting.tbl]]}}

===$Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for impacts of this weapon.
*Syntax: '''String''', the particle effect name
*If this option is specified then ''$Impact Explosion'' and ''$Impact Explosion Radius'' are not valid options!
}}

===$Impact Explosion:===
*Impact explosion used. Must be defined in weapon_expl.tbl,
*Syntax: '''''String''''', filename or ''none''

===$Impact Explosion Radius:===
*Radius of the defined impact explosion.
*Syntax: '''''Float''''', meters, default 1.0

===$Shield Impact Explosion Radius:===
{{Table373|
*Radius of the shield impact explosion, see [[Ships.tbl#.24Shield_Impact_Explosion:]].
*Syntax: '''''Float''''', meters, defaults to value of $Impact Explosion Radius}}

===$Dinky Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for Dinky (not armed) explosions of this weapon.
*Syntax: '''String''', the particle effect name
*If this option is specified then ''$Dinky Impact Explosion'' and ''$Dinky Impact Explosion Radius'' are not valid options!
}}

===$Dinky Impact Explosion:===
{{Table3610|
*Same as Impact Explosion but for Dinky (not armed) explosions
*Syntax: '''''String''''', filename or ''none''}}

===$Dinky Impact Explosion Radius:===
{{Table3610|
*Same as Impact Explosion Radius but for Dinky explosions
*Syntax: '''''Float''''', meters}}

===$Piercing Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for piercing impacts.
*Syntax: '''String''', the particle effect name
*If this option is specified then piercing impact options below are not valid!
}}

===$Piercing Impact Explosion:===
{{Table3611|
*Defines the effect used for events when weapon pierces the target
*Syntax: '''''String''''', filename or ''none''}}

===$Piercing Impact Radius:===
{{Table3611|
*Defines the base radius of the effect used for piercing weapon impacts
*Syntax: '''''Float'''''}}

===$Piercing Impact Velocity:===
{{Table3611|
*Defines the base velocity for the particles piercing the target
*Syntax: '''''Float'''''}}

===$Piercing Impact Splash Velocity:===
{{Table3611|
*Defines the base velocity for the particles splashing from the target (secondary piercing effects
*Negative value causes the second batch or particles to splash to opposite direction
*Syntax: '''''Float'''''}}

===$Piercing Impact Variance:===
{{Table3611|
*Defines the variance added to the particles
*Values near 0 cause very little variance and values close to 1 cause extreme dispersal.
*Syntax: '''''Float'''''}}

===$Piercing Impact Life:===
{{Table3611|
*Defines the lifetime of the effect for single frame effects
*For multiple frame effects the lifetime is the lifetime of the animation used
*Syntax: '''''Float'''''}}

===$Piercing Impact Particles:===
{{Table3611|
*Defines the number of particles released per impact
*Syntax: '''''Integer'''''}}

===$Piercing Impact Draw Modifier:===
{{Table3611|
*Defines the multiplier applied to the ships piercing effect limit percentage
*Syntax: '''''Float'''''}}
*Option removed in 3.6.12. Use [[armor.tbl]] to finetune piercing effects.

===$Inflight Effect:===
{{Table38|
*Sets the inflight [[Particle Effects|particle effect]] which is used when the laser is active. This is only used by laser weapons.
*Syntax: '''''String''''', the particle effect name
}}
===$Freeflight Effect:===
{{Table38|
*Sets the [[Particle Effects|particle effect]] which is used when the missile is in the free flight phase. See [[#$Free Flight Time:|$Free Flight Time]] for more information.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Ignition Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is transitioning from free flight to homed or unhomed flight.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Homed Flight Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is in homed flight mode.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Unhomed Flight Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is in unhomed flight mode.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}

===$Muzzleflash:===
*Normally only with flak cannons.
*Defines the muzzle flash the weapon uses
*Syntax: '''''String''''', muzzleflash name, as defined in [[mflash.tbl]]

===$EMP Intensity:===
*If it has an EMP effect, how deeply it scrambles your electronics
*Basically a percentage, a value of 250 results in a 25% chance of something getting scrambled each frame.
*Maximum value of 500
**Syntax: '''''Float'''''

===$EMP Time:===
**Duration of the EMP effect
**Syntax: '''''Float''''', seconds

===$Recoil Modifier:===
{{Table373|
*Multiplies the recoil force of a weapon by this value, use a value greater than 1.0 to increase the force, use a value between 1.0 and 0.0 to decrease.
**Syntax: '''''Float''''' (defaults to 1.0)
{{Note| The "apply recoil" weapon flag must be set for this to be valid. If the flag is not set, FSO will throw a warning and automatically set it at runtime.}}
}}

===$Leech Weapon:===
**The amount of weapon energy to drain with each hit (a flat value, not a percentage)
**Needs the [[#Esuck|Esuck]] flag set to have any effect
**Syntax: '''''Float''''' (defaults to 10.0)

===$Leech Afterburner:===
**The amount of afterburner fuel to drain with each hit (a flat value, not a percentage)
**Needs the [[#Esuck|Esuck]] flag set to have any effect
**Syntax: '''''Float''''' (defaults to 10.0)

===$Corkscrew:===
{{Table3610|
*Allow corkscrew parameters to be defined
*'''+Num Fired:'''
**Defines the number of weapons fired in sequence. Same as the standard swarm entry but for corkscrew missiles
**Syntax: '''''Integer''''', number of missiles
*'''+Radius:'''
**Defines the radius used in the corkscrew motion
**Syntax: '''''Float''''', meters
*'''+Fire Delay:'''
**Defines the delay between missile firings
**Syntax: '''''Integer''''', milliseconds
*'''+Counter rotate:'''
**Defines if every other missile rotates to a different direction (clockwise / anticlockwise)
**Syntax: '''''Boolean''''', ''0'' or ''1'', no or yes
*'''+Twist:'''
**Defines the speed of rotation movement on the radius of corkscrew motion.
**Syntax: '''''Float''''', radians per second}}

===$Electronics:===
{{Table3610|
*Defines the weapons effect against electronics. Requires [[weapons.tbl#"Electronics"|"electronics"]] flag. '''+New Style:''' and '''+Old Style:''' options are mutually exclusive.
*'''+New Style:'''
**Defines that the electronics use the new style which enables more options.
*'''+Old Style:'''
**Defines that the electronics use the old style. The old style was the way the D-Missile worked in Descent: FreeSpace.
}}
{{Table371|
*'''+Area Of Effect'''
**If specified, allows the electronics effect to apply to every ship hit by this weapon's blast or shockwave (the "Electronics" flag isn't necessary with this option).
}}
{{Table3610|
*'''+Intensity:'''
**May only be used with '''+New Style:''' electronics. '''''Has been deprecated'''''.
**Syntax: '''''Float'''''
*'''+Lifetime:'''
**Syntax: '''''Integer''''', milliseconds
*'''+Engine Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for engine subsystems.
**Syntax: '''''Float'''''
*'''+Weapon Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for non-beam turrets.
**Syntax: '''''Float'''''
*'''+Beam Turret Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for beam turrets.
**Syntax: '''''Float'''''
*'''+Sensors Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for sensor subsystems.
**Syntax: '''''Float'''''
*'''+Randomness Time:'''
**Defines the randomness of duration target suffers from the electronics hit. A random number between 0 and this time will be added or subtracted from the disruption time.
**Syntax: '''''Integer''''', milliseconds

* Without any electronics parameters, a weapon with the "electronics" flag will default to the ''Old Style'' mode with a lifetime of 6000 milliseconds and a randomness of 4000 milliseconds. Thus any ship that gets hit can get disrupted for anywhere between 2 to 10 seconds.

}}

===$Spawn Angle:===
{{Table3610|
*Defines the cone (with an angle) where the spawned weapons appear. ''Value'' gives the angle from the missiles centerline. The maximum possible angle between any two child weapons would be ''Value*2''.
*Spawn angle can be defined as many times as the carrier missile has child weapons defined for it (up to 5).
*Syntax: '''''Float''''', degrees}}

===$Local SSM:===
{{Table3610|
*Defines the local SSM (Subspace Missile). In effect missile moves via subspace to a position close to the target and starts homing.
*Weapon must be '''''aspect seeking missile''''' and must have '''''[[Weapons.tbl#"local ssm"|local ssm]]''''' flag.
*'''+Warpout Delay:'''
**Defines the time between the missile launch and the subspace jump.
**Syntax: '''''Integer''''', milliseconds
*'''+Warpin Delay:'''
**Defines the time missile stays in subspace before exiting.
**Syntax: '''''Integer''''', milliseconds
*'''+Stage 5 Velocity:'''
**Defines the velocity of the missile after the subspace jump.
**Syntax: '''''Float''''', meters per second
*'''+Warpin Radius:'''
**Defines how far from the SSM will appear from the outer radius of the target.
**Syntax: '''''Float''''', meters
*'''+Lock Range:'''
**Defines the maximum range where SSM can achieve target lock
**Syntax: '''''Float''''', meters}}

===$Countermeasure:===

*Defines the countermeasure effectiveness, radius, etc
{{note|
*Spoofing chance is defined as '''cm type effectiveness'''/'''[[#+Seeker Strength:|seeker strength]]''' (missile must be within the countermeasures '''+Effective Radius:''').
*All countermeasures in the mission perform tests to spoof missiles for two frames after '''any countermeasure''' is created in the mission. No, this doesn't seem to make much sense.
*'''Provisional'''; Countermeasures are only given one chance to spoof any individual missile. This makes tuning seeker strength/effectiveness meaningful.
**Previously some record of which countermeasures had been seen by each missile was kept, but it broke when multiple countermeasures were involved. A good chance of breaking with two countermeasures, and a guaranteed chance of breaking with three or more. This reduced the impact of the seeker strength/effectiveness ratio, but was partly cancelled out by the 2 frames thing.
}}

{{Table3610|
===='''+Heat Effectiveness:'''====
*Defines the countermeasures effectiveness against heat seeking missiles
*Syntax: '''''Float''''', cm effectiveness
**Default: 1.0

===='''+Aspect Effectiveness:'''====
*Defines the countermeasures effectiveness against aspect seeking missiles
*Syntax: '''''Float''''', cm effectiveness
*Default: 1.0

===='''+Effective Radius:'''====
*Defines the countermeasures effective radius
*Syntax: '''''Float''''', meters
**Default: 300.0
}}

{{Table373|
====+Missile Detonation Radius:====
*Defines the radius within which a missile homing on this countermeasure will trigger a detonation (see '''+Single Missile Kill:''')
*Syntax: '''''Float''''', meters
**Default: 40.0
{{note| only affects missiles homing on countermeasures, i.e. heat or aspect with "pulls aspect seekers" flag}}
====+Single Missile Kill:====
*Defines if countermeasures will detonate only the missile homing on this countermeasure, or every missile within '''+Missile Detonation Radius:'''
*Syntax: '''''Boolean'''''
**Default: false
{{note| only affects missiles homing on countermeasures, i.e. heat or aspect with "pulls aspect seekers" flag}}
}}

===$BeamInfo:===
*'''+Type:'''
**Defines the type of beam in question. Beam types: 0 is a standard non-slashing type beam. 1 is a slashing type beam. 2 is a targeting beam that is used to trigger SSMs. 3 is a beam type that fires pulses in anti-fighter role and acts like type 0 beam in other roles. 4 is a beam that is restricted to what is directly in front of it, along turrets firepoints normal.
**Syntax: '''''Integer''''',, only values from 0 to 4 are legal
*'''+Life:'''
**How long it lasts once the beam is actually firing.
**Syntax: '''''Float''''', seconds
*'''+Warmup:'''
**Warmup time
**Syntax: '''''Integer''''', milliseconds
*'''+Warmdown:'''
**Warmdown time
**Syntax: '''''Integer''''', milliseconds
*'''+Radius:'''
**Muzzle glow radius
**Syntax: '''''Float''''', meters
*'''+PCount:'''
**Particles spewed every interval. ??
**Syntax: '''''Integer'''''
*'''+PRadius:'''
**Particle radius
**Syntax: '''''Float''''', meters
*'''+PAngle:'''
**Defines the random "cone" where the particles are generated
**Syntax: '''''Float''''', angle of the cone
*'''+PAni:'''
**Animation used to represent the particles
**Syntax: '''''String''''', filename
*'''+Miss Factor:'''
**The higher the numbers, the more likely that this beam will miss. One value for every difficulty level
**Syntax: '''''Miss Factor''''', five '''floats''', very easy, easy, moderate, hard, insane, respectively.
***Example: 0.5 0.975 1.35 1.875 2.5
{{Table3613|
*'''IFF specific miss factors'''
**Identical to the preceding entry but IFF specific. Replace the <IFF> with the name of the IFF from [[iff_defs.tbl]]
**Syntax: '''''+<IFF> Miss Factor:''''', five '''floats''', very easy, easy, moderate, hard, insane, respectively.
***Example: 0.5 0.975 1.35 1.875 2.5}}
*'''+BeamSound:'''
**Corresponding looping sound effect when the beam is firing.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+WarmupSound:'''
**Corresponding sound effect when the beam is beam warmed up.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+WarmdownSound:'''
**Corresponding sound effect when the beam is warming down.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+Muzzleglow:'''
**Defines the bitmap used to create the muzzle glow
**Syntax: '''''String''''', filename
{{Table372|
*'''+Directional Glow:'''
**Defines the length to stretch the muzzleglow along the beam.
**Syntax: '''''Float''''', length in meters, the muzzleglow is rendered along (in the same plane) as the beam instead of perpendicular to the camera.}}
*'''+Shots:'''
**Defines into how may invidual shots the type 3 (AAA) beams are divided. Note total firing is the same as the +Life:
**Syntax: '''''Integer'''''
*'''+ShrinkFactor:'''
**What percentage of lifetime where beam starts shrinking (0.1 == 10% life left)
**Syntax: '''''Float'''''
*'''+ShrinkPct:'''
**What percentage of max width we subtract per second
**Syntax: '''''Float'''''
{{Table3610|
*'''+Range:'''
**Defines the maximum range where the beam still has any effect.
**Syntax: '''''Float''''', meters
*'''+Attenuation:'''
**Defines the point where the damage caused by the beam starts to attenuate. At maximum range damage is zero.
**Syntax: '''''Float''''', from 0 - firing point to 1 - no effect
***Default: 1}}
{{Table3611|
*'''+BeamWidth:'''
**Defines the width of the beam for collision test purposes instead of using widest beam section.
**Syntax: '''''Float''''
{{Table38|
*'''+Beam Flash Particle Effect:'''
**Specifies the beam flash [[Particle Effects|particle effect]].
**Syntax: '''''String''''', particle effect name
**If this is specified then '''+Beam Flash Effect''' and '''+Beam Flash Radius''' are not valid options!
}}
*'''+Beam Flash Effect:'''
**Defines the additional impact flash effect for the beam.
**Syntax: '''''String''''', filename
*'''+Beam Flash Radius:'''
**Defines the radius for the additional impact flash effect.
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect:'''
**Defines the beam piercing (bursting flames) effect for the beam.
**Syntax: '''''String''''', filename
*'''+Beam Piercing Radius:'''
**Defines the average radius used for the beam piercing effects.
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect Velocity:'''
**Defines the base velocity for the piercing effects
**Syntax: '''''Float'''''
*'''+Beam Piercing Splash Effect Velocity:'''
**Defines the base velocity for the secondary piercing effects
**Negative velocity causes the particles to move to opposite direction
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect Variance:'''
**Defines the variances of the particles from the main path
**Values close to 0 cause minimum variance, higher values cause higher variances
**Syntax: '''''Float'''''}}

*'''$Section:'''
**Beams are made up of up to five sections layered atop one another to create the effect. Each section has its own parameters.
{{Table3610|
:*'''+Index:'''
:**Field used to define with [[Modular Tables]] the beam section which is edited.
:**Only needed when editing beams that already exist in other tables.
:**Syntax: '''''Integer''''', index number legal values are from 0 to 5
:*'''+remove'''
:**Removes the set beam section.
:*'''+nocreate'''
:**Does not create new section for the beam}}

:*'''+Width:'''
:**Width of the section
:**Syntax: '''''Float''''', meters
:*'''+Texture:'''
:**Texture for the section
:**Syntax: '''''String''''', filename
:*'''+RGBA Inner:'''
:**Defines the color and transparency of the center of the section
{{Table3613|:**Not used in current builds. Settings entered here will have no effect.}}
:**Syntax: '''''Color''''', red, green, blue, alpha, respectively, value from 0 to 255
:***Example: 255 255 255 255
:*'''+RGBA Outer:'''
:**Defines the color and transparency of the edges of the section
{{Table3613|:**Not used in current builds. Settings entered here will have no effect.}}
:**Syntax: '''''Color''''', red, green, blue, alpha, respectively, value from 0 to 255
:***Example: 150 150 150 10
:*'''+Flicker:'''
:**Defines how much the section flickers
:**Syntax: '''''Float''''', value from 0 to 1
:*'''+Zadd:'''
:**Defines the 'thickness' of the section. The higher the Zadd, the closer the section appears to be.
:**Syntax: '''''Float'''''
{{Table3610|
:*'''+Tile Factor:'''
:**Defines the beam texture tiling factor. Second number defines the tiling type. Type 0 tiles the graphic in the beam as many times as defined by the 1st number. Type 1 uses the 1st value as the lenght of the tile.
:**Syntax: '''''Float''''', '''''Integer'''''
:*'''+Translation:'''
:**Defines the speed of translation of the beam, a positive value moves from the impact point to the firing point, while a negative value moves away from the firing point towards the impact point. Measured in tiles per second, where the tile count is defined in the "+Tile Factor:" field above.
:**Syntax: '''''Float'''''}}

===$Pspew:===
{{Table3610|
*Defines a particle spew effect for the given weapon
}}{{Table3613|
*'''+Index:'''
**indicates which spewer to add/edit/delete. may be 0-3. used for xmt compatibility.
**Syntax: '''''Integer'''''
*'''+Remove'''
**removes spewer at +Index: (requires +index:)
*'''+Type:'''
**type of particle spew
**Syntax: '''''String'', Default, Helix, Sparkler, Ring, or Plume '''
}}{{Table3610|
*'''+Count:'''
**Defines how many particles are spawn when they are ready to be created (at each +Time: interval)
**Syntax: '''''Integer'''''
*'''+Time:'''
**Defines the time in milliseconds between next particle(s) spewed
**Syntax: '''''Integer''''', milliseconds
*'''+Vel:'''
**Defines the created particles velocity as percentage of the weapons velocity
**Syntax: '''''Float'''''
*'''+Radius:'''
**Defines the size of the created particles
**Syntax: '''''Float''''', meters
*'''+Life:'''
**Defines how long the particles last.
**Syntax: '''''Float''''', seconds
*'''+Scale:'''
**Defines the particle spread. Small value will make particles group together
**typically controls how big the effect is or how fast it moves away from the weapon path on a perpendicular (or sometimes arbitrary) axis.
**helical spews and rings use this value to control how fast the particle helix moves away from the central axis.
**sparklers use this to control how fast particles move away from the spawn point, in any direction
**plumes use this to set the diameter of the disk across which particles are spawned
**Syntax: '''''Float'''''
}}{{Table3613|
*'''+Z Scale:'''
**for sparklers, allows you to elongate the effect to surround other effects, like lasers. essentially a length multiplier
**for plume, it multiplies against +scale to set the plume to spread or converge, zero would be full convergence, 1 would be straight flight, and bigger numbers would cause particles to diverge from the disk.
**Syntax: '''''Float'''''
*'''+Rotation Rate:'''
**used only by helical spews, controls how many rotations per second the helix makes
**Syntax: '''''Float'', may be negative, useful for setting up 2 spews that spin in opposite directions'''
*'''+Offset:'''
**position of effect with regards to the weapon center
**Syntax: '''''Vector'''''
*'''+Initial Velocity:'''
**to indicate both direction and speed of particle effects regards to the weapon velocity and +scale:
**Syntax: '''''Vector'''''
}}{{Table3610|
*'''+Bitmap:
**Defines the animation used to create the particle spew effect
**Syntax: '''''String''''', filename}}

===$Tag:===
*Allowed for secondary weapons
{{Table3610|
*Allowed for primary weapons and secondary weapons}}

*Sets this weapon as a TAG missile, level 1, 2, or 3. The second number is the duration in seconds.
*TAG Level 1 will illuminate hidden targets such as stealth fighters or ships normally obscured by nebula conditions.
*TAG Level 2 illiminates targets much like TAG Level 1, but turrets will prefer to shoot at them over other ships.
*TAG Level 3 has no effect in retail.
{{Table3610|
*TAG Level 3 allows the weapon to trigger [[Weapon.tbl#$SSM:|SSMs]]}}

*Syntax: '''''Integer''''' '''''Float''''', TAG level and seconds respectively
*'''Note''': TAG will not trigger unless the weapon in question has a non-zero damage value.

===$SSM:===
{{Table3610|
*Defines the weapons SSM index number.
*Requires [[Weapons.tbl#$Tag:|TAG level 3]] or a targeting beam.
*Syntax: '''''Integer'''''}}
{{Table373|
*Now also accepts SSM strike names.
*Syntax: '''''String'''''}}

===$FOF:===
{{Table3610|
*Defines the field of fire for the weapon. Causes weapon to fire into a firing cone instead of direct firing line thus causing light inaccuracy
*Syntax: '''''Float''''', degrees}}

====+FOF Spread Rate:====
{{Table37|
*Defines the spread rate of the field of fire. This controls how the FOF increases over time while the weapon is firing.
*Syntax: ''''''Float'''''', rate}}

====+FOF Reset Rate:====
{{Table37|
*Rate at which the spread decreases if the weapon isn't firing.
*Syntax: ''''''Float'''''', rate
*This is required if '''+FOF Spread Rate:''' is present}}

====+Max FOF:====
{{Table37|
*The maximum FOF. After the FOF reaches this value it will not increase any further.
*Syntax: ''''''Float'''''', degrees. Must be greater than or equal to zero.
*This is required if '''+FOF Spread Rate:''' is present}}

===$Shots:===
{{Table3610|
*Defines the number of shots every time the weapon is fired.
*Works only for primary weapons
*Syntax: '''''Integer''''', number of shots}}

===$decal:===
{{Table3610|
*Defines impact decals if they are in use
*'''+texture:'''
**Defines the texture used for impact decals (can use '''''-burn''''' and '''''-glow''''' textures)
**Syntax: '''''String''''', filename
*'''+backface texture:'''
**Defines ???
**Syntax: '''''String''''', filename
*'''+radius:'''
**Defines the size of the impact decals on target
**Syntax: '''''Float''''', meters
*'''+burn time:'''
**Defines the time the '''''-burn''''' texture appears on the target
**Syntax: '''''Integer''''', milliseconds}}
{{Table3613|
*Feature removed - table parsing retained to maintain compatibility}}

===$Transparent:===
{{Table3610|
*Defines weapon effect as transparent. Enables optional fields for 'alpha animations'
*'''+Alpha:'''
**Defines the strenght of the alpha (transparency). And also the maximum value for the alpha cycle option
**Syntax: '''''Float''''', from 0 to 1
*'''+Alpha Min:'''
**Defines the minimum alpha value for alpha cycle option
**Syntax: '''''Float''''', from 0 to 1
*'''+Alpha Cycle:'''
**Defines the change in alpha per frame, between '''Alpha''' and '''Alpha Min''' values
**Syntax: '''''Float'''''}}

===$Weapon Hitpoints:===
{{Table3611|
*Defines the amount of hitpoints a weapon has.
*Weapons with '''"bomb"''' flag have 50 hitpoints by default
*Giving weapon hitpoints makes it possible for the weapon to be shot down or be destroyed by EMP.
**Syntax: '''''Integer'''''
}}

===$Armor Type:===
{{Table3613|
*REQUIRES ADDITIONAL TABLE. Defines the armor type for the weapon. This works exactly like ship armor types.
**Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]
}}

===$Burst Shots:===
{{Table3611|
*Defines the number of shots in a burst
*Shots in a burst use shorter ( '''$Burst Delay:''' ) delay than usually
**Syntax: '''''Integer'''''}}

===$Burst Delay:===
{{Table3611|
*Defines the time in milliseconds between the shots in a burst
**Syntax: '''''Integer'''''}}

===$Burst Flags:===
{{Table3611|
*Defines the flags used to define the burst firing behaviour
**Syntax: ( '''''String''''' '''''String''''' ), list of flags
**Available burst flags:
***'''"fast firing"''', acts as if '''same turret cooldown''' flag would be used between the shots in the burst.
***'''"random length"''', makes AI to fire burst of random length (from 1 to burst shots).}}

===$Thruster Flame Effect:===
{{Table3611|
*Defines the filename of the effect used on the modeled thruster of the missile
**Syntax: '''''String''''', filename}}

===$Thruster Glow Effect:===
{{Table3611|
*Defines the filename of the effect used on the glow type effect of the missile
**Syntax: '''''String''''', filename}}

===$Thruster Glow Radius Factor:===
{{Table3611|
*Defines the radius multiplier for the thruster's glow type effect
**Syntax: '''''Float'''''}}

===$Substitute:===
{{Table3613|
Defines a pattern of ammo to substitute for primary or secondary weapons. '''$Substitute:''' can be repeated any number of times (so you could make something like a rainbow laser with several ammo substitutions, for example). If neither ''+period'' or ''+index'' is specified, it is assumed to be equivalent to ''+index: '''0'''''.

*Syntax: '''''Weapon Name'''''
*'''Swarm missiles act in a strange way when used with $Substitute, use at your own risk.'''}}

{{Table3615|
Turrets can use $Substitute as well.
}}
====+period:====
{{Table3613|
FSO will substitute '''Weapon Name''' every ''period'' shots.

*Syntax: '''''Positive Integer'''''
*'''You may not define both +period and +index for the same $Substitute entry'''}}
=====+offset:=====
{{Table3613|
A suboption of +period, offsets the substitute pattern according to the launched ammo. For example, an offset of 3 and a period of 4 will substitute on the 3rd ammo launched, and then every 4th ammo after that.

*Syntax: '''''Positive Integer'''''}}

====+index:====
{{Table3613|
FSO will substitute the '''Weapon Name''' at firepoint ''index'' in the shot pattern. Similar to carefully using both +period and +offset, but is not affected by ships with different firepoint numbers. i.e. Firepoint ''index'' will always have the substitution, while +period and +offset will cycle at different rates dependant on the number of firepoints.'''

*Syntax: '''''Positive Integer'''''

*'''You may not define both +period and +index for the same $Substitute entry'''}}

==Weapons.tbl Flags==

==="Electronics"===
*Will seize up the weapons and engines systems of any ship for a short period of time.

==="Spawn ''Name'',''Value''"===
*Will spawn the specified number of defined missiles upon detonation.
{{Table3610|
*Multiple spawn types can be defined for a single 'carrier' weapon up to maximum of 5 different weapons}}

==="Remote Detonate"===
*Can be triggered remotely via a second press on the trigger

==="Big Ship"===
*These weapons cannot be mounted on small ships like fighters, bombers, sentry guns etc.

==="Huge"===
*Allows this weapon to do the final 10% damage to a ship with the "Big Damage" flag. Also the AI will not try to hit fighters with it.

==="Supercap"===
*Allows this weapon to do the final 75% damage to a ship with the "supercap" flag.

==="Bomber+"===
*The AI will prefer to use this weapon against bombers

==="child"===
*Cannot be set as a weapon on any ship, but is instead a child of a weapon. Usually defined with "Spawn ''Name'',''Value''"

==="Bomb"===
*Makes this weapon targetable with the B key, and the AI prefers to use it against large ships

==="No Dumbfire"===
*Missile will not fire without a lock

==="in tech database"===
*Has the weapon in the tech database at the start of the campaign

==="Player allowed"===
*Allows this weapon as a player weapon.
{{Table3610|
*'''EXTREMELY IMPORTANT NOTE:'''
**Whenever you plan to use a weapon as a player one in your campaign or missions, '''USE THIS FLAG'''.
**Not using it can cause problems within fs_open and it's a BAD MOD DESIGN.
**In the future, fs_open will maybe be able to avoid these problems but, nevertheless, it's still a BAD DESIGN.
**As another possible example: be careful to update "retail" tables if you plan to use Shivan weapons in player fighters.}}

==="Particle Spew"===
*Makes the weapon projectile spew out particles
{{Table3610|
*Can be defined with [[Weapons.tbl#$Pspew:|Particle Spew parameters]]}}

==="EMP"===
*This weapon will have an EMP effect on any ship within the blast radius
*Can be defined with [[Weapons.tbl#$EMP_Intensity:|EMP Intensity]] and [[Weapons.tbl#$EMP_Time:|EMP Time]]

==="Esuck"===
*Drains the target's energy banks
*Can be defined with [[Weapons.tbl#$Leech_Weapon:|Leech Weapon]] and [[Weapons.tbl#$Leech_Afterburner:|Leech Afterburner]]

==="Flak"===
*Makes this weapon a [[weapons.tbl#Flak_Guns|flak gun]]

==="Corkscrew"===
*Makes this weapon spiral AND swarm 4.
{{Table3610|
*Can be defined with [[Weapons.tbl#$Corkscrew:|Corkscrew parameters]]}}

==="Shudder"===
*Makes your ship shudder while you're firing the weapon

==="lockarm"===
*Requires a target lock in order to arm its warhead. In other words weapon causes less damage if it hits the target without target lock.

==="beam"===
*Makes this weapon a [[weapons.tbl#Beam Cannons|beam cannon]]

==="stream"===
* Does nothing

==="puncture"===
*Reduces hull damage by 75%
The AI will prefer these weapons for anti-subsystem use

==="countermeasure"===
{{Table3610|
*Defines the weapon as a countermeasure}}

==="Ballistic"===
{{Table3610|
*Defines the weapon as a ballistic weapon that needs ammunition.
*Make sure you define the size and reload rate for ballistic weapons}}

==="pierce shields"===
{{Table3610|
*Causes weapons to penetrate shield without causing damage to it.}}

==="no pierce shields"===
{{Table3610|
*Prevents weapons (beams) from piercing shields causing shields to be damaged by weapons first.}}

==="local ssm"===
{{Table3610| }}

==="tagged only"===
{{Table3610|
*Weapon can only be fired at tagged targets}}

==="beam no whack"===
{{Table3610|
*Disables beam whacking (push). Practically same as setting beam mass to zero.}}

==="cycle"===
{{Table3610|
*Causes weapon to alternate between firing points}}

==="small only"===
{{Table3610|
*Causes AI to use the weapon only on small targets (fighters, bombers etc.)}}

==="same turret cooldown"===
{{Table3610|
*Forces the turrets to fire on the designated rate of fire on all difficulty levels and all AI levels}}

==="apply no light"===
{{Table3610|
*Prevents light from being applied to the weapon model.}}

==="training"===
{{Table3610|
*Sets weapon to be of training weapon type. ?}}

==="smart spawn"===
{{Table3611|
*Forces turret fired spawn weapon of this type to be fired like normal weapons.}}

==="inherit parent target"===
{{Table3611|
*Sets spawned 'child' weapons to use parent weapon's target.}}

==="no emp kill"===
{{Table3611|
*Defines the weapon (with hitpoints) to be immune to automatic EMP destruction.}}

==="untargeted heat seeker"===
{{Table3611|
*Defines the weapon as a heatseeker type missile which acquires its target by itself.}}

==="no radius doubling"===
{{Table3611|
*Prevents weapon radius from being doubled when doing collision test. Makes bombs harder to intercept.}}

==="no subsystem homing"===
{{Table3611|
*Prevents weapon from acquiring a subsystem as its target. Missile homing points are spread over the target ship.}}

==="no lifeleft penalty"===
{{Table3611|
*Prevents weapon lifetime from being penalized if the angle to the target is too big.}}

==="can be targeted"===
{{Table3611|
*Allows weapon to be targeted by player. Does not influence AI}}

==="show on radar"===
{{Table3611|
*Allows weapon to be visible on the radar}}

==="show friendly on radar"===
{{Table3611|
*Allows friendly, otherwise visible to radar weapon, to be visible on player radar}}

==="capital+"===
{{Table3613|
*Tells AI to use this weapon only on capital ships}}

==="chain external model fps"===
{{Table3613|
*Tells game to keep switching external model firingpoints when firing}}

==="external model launcher"===
{{Table3613|
*Tells game that the external model is a launcher so that it would be kept static without loading motion}}

==="takes blast damage"===
{{Table3613|
*Weapon takes damage from weapon blasts}}

==="takes shockwave damage"===
{{Table3613|
*Weapon takes damage from shockwaves}}

==="ciws"===
{{Table3615|
*Weapon can deal shockwave/blast damage to bombs, regardless of whether the target weapons have the "take blast/shockwave damage" flags.}}

==="render flak"===
{{Table3615|
*Normally, flak shells are not rendered. This flag switches rendering on for those weapons.}}

==="anti-subsystem beam"===
{{Table3615|
*Beam weapons with this flag can target subsystems on enemy ships, just like normal weapons.}}

==="no primary linking"===
{{Table3615|
*Primary weapons with this flag can not be linked with other weapons.}}

==="same emp time for capships"===
{{Table37|
*capships affected by this weapon will use the tabled EMP time rather than the fixed retail value (7.5 secs)}}

==="no primary linked penalty"===
{{Table371|
*Primary weapons with this flag do not incur the retail linked fire penalty}}

==="no homing speed ramp"===
{{Table371|
*Locked homing weapons will not perform the standard 1 second long acceleration when fired. Note that use of $Acceleration Time is '''not''' affected by this flag.}}

==="pulls aspect seekers"===
{{Table371|
*If an aspect seeker is grabbed by this countermeasure the missile will follow the countermeasure instead of going into dumbfire mode.
'''Only valid for countermeasures!'''}}

==="turret interceptable"===
==="fighter interceptable"===
==="interceptable"===
{{Table371|
*Allows turrets/fighters/both (respectively) to shoot at this weapon without requiring it to be a bomb. If this is the first time this weapon has been defined, it also gives it a default of 25 hitpoints so that it can be shot down.
'''If you use a TBM to give this flag to an existing weapon, you'll need to specify hitpoints manually (unless you want it to be unkillable but still draw defensive fire).'''}}

==="apply recoil"===
{{Table373|
*A ship that fires a weapon with this flag will experience a recoil effect, slowing the ship down and, with lighter strikecraft, inducing some rotation if the firing points are offset from the center of mass.
'''Do not use this with MVPs or retail ships unless you increase their density to 10 or use either $Recoil Modifier: in weapons.tbl or $Ship Recoil Modifier in ships.tbl. This is to avoid exaggerated effects due to retail models having manually defined masses.'''}}

==="don't spawn if shot"===
{{Table373|
*Prevents parent weapons from spawning children in the even of the parent weapon being shot down.}}

==="die on lost lock"===
{{Table373|
*Aspect seeking missiles (only, not heat seekers) will detonate upon losing their lock. Currently they only lose lock if decoyed by a countermeasure, AND "pulls aspect seekers" or similar is not set. The detonation will use their "dinky" explosion (i.e. same as if ran out of lifetime).}}

==Countermeasures==
*Usually not altered. Only one can exist
{{Table3610|
*More than one can exist}}

===$Name:===
*Name of the countermeasure
*Syntax: '''''String''''', name

===$Velocity:===
*Defines the speed of the countermeasure, relative to the ship.
*Syntax: '''''Float''''', meter per second

===$Fire Wait:===
*Definies the minumum time between the countermeasure launches
*Syntax: '''''Float''''', seconds

===Lifetime===
*Countermeasure's life time is defined between with minimum and maximum lifetime
*'''$Lifetime Min:'''
**Syntax: '''''Float''''', seconds
*'''$Lifetime Max:'''
**Syntax: '''''Float''''', seconds

===$LaunchSnd:===
*Defines the sound for the countermeasure launch
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$Model:===
*Defines the used model file (.pof)
*Syntax: '''''String.pof''''', model filename

==Player Weapon Precedence==
*First the primary weapons are defined, from most powerful to least powerful, and then the same for secondaries
*Syntax: ( '''''"String" "String"'''''), names of the weapons
*Example:

<pre>
$Player Weapon Precedence: (
"UD-8 Kayser"
"Prometheus R"
"Subach HL-7"
"Harpoon"
"Tempest"
"Rockeye" )
</pre>

==Sample==

<pre>
#Primary Weapons

$Name: @Subach HL-7
+Title: XSTR("GTW Subach HL-7", 3243)
+Description:
XSTR( "Standard Issue
Level 3 Hull Damage
Level 2 Shield Damage", 3244)
$end_multi_text
+Tech Title: XSTR("Subach HL-7", 146)
+Tech Anim: Tech_Subach_HL-7
+Tech Description:
XSTR(
"Descriptive text...", -1)
$end_multi_text
$Model File: none
@Laser Bitmap: newglo9
@Laser Glow: 2_laserglow03
@Laser Color: 250, 0, 0
@Laser Color2: 0, 0, 250
@Laser Length: 10.0
@Laser Head Radius: 0.90
@Laser Tail Radius: 0.90
$Mass: 0.2
$Velocity: 450.0
$Fire Wait: 0.2
$Damage: 15
$Armor Factor: 0.9
$Shield Factor: 0.7
$Subsystem Factor: 0.3
$Lifetime: 2.0
$Energy Consumed: 0.20
$Cargo Size: 0.0
$Homing: NO
$LaunchSnd: 76
$ImpactSnd: 85
$Flags: ( "in tech database"
"player allowed"
"stream")
$Icon: iconSD4
$Anim: SD4
$Impact Explosion: none

#End

#Secondary Weapons

$Name: EMP Adv.
+Title: XSTR("GTM-14 EMP Adv.", 3396)
+Description:
XSTR( "Advanced Missile
Electromagnetic Pulse Weapon
General Purpose Suppression", 3397)
$end_multi_text
+Tech Title: XSTR("GTM-14 EM Pulse Adv.", 3398)
+Tech Anim: Tech_EMP
+Tech Description:
XSTR(
"Descriptive text...", -1)
$end_multi_text
$Model File: EMPulse2.pof
$Mass: 15.0
$Velocity: 275.0
$Fire Wait: 2.0
$Damage: 45
$Blast Force: 20.0
$Inner Radius: 80.0
$Outer Radius: 300.0
$Shockwave Speed: 120.0
$Armor Factor: 1.0
$Shield Factor: 0.8
$Subsystem Factor: 0.5
$Lifetime: 5.0
$Energy Consumed: 0.0
$Cargo Size: 4.0
$Homing: YES
+Type: ASPECT
+Turn Time: 1.0
+Min Lock Time: 2.0
+Lock Pixels/Sec: 70
+Catch-up Pixels/Sec: 100
+Catch-up Penalty: 30
$LaunchSnd: 118
$ImpactSnd: 88
$FlyBySnd: -1
$Rearm Rate: 2.0
$Flags: ( "player allowed"
"EMP")
$Trail:
+Start Width: 0.25
+End Width: 0.75
+Start Alpha: 1.0
+End Alpha: 0.0
+Max Life: 1.5
+Bitmap: MissileTrail04
$Icon: iconEMPulse
$Anim: ecm
$Impact Explosion: ExpMissileHit1
$Impact Explosion Radius: 10.0
$EMP Intensity: 375.0
$EMP Time: 20.0

#End

$Player Weapon Precedence: (
"Subach HL-7"
"EMP Adv." )
</pre>

[[Category:Tables]]

Ships.tbl

2016-09-04T09:06:39Z

M!m: Add documentation for "$Ship Death Effect".

{{TableVersionGit|2016-05-27|d60c8d5}}

The '''ships.tbl''' defines all the ship classes used in FSO.

This table is one of the [[Modular Tables]] and can be extended with xxx-shp.tbm

[[Tables|List of Tables]]

==General Format==
*Ship.tbl is formed of several different sections.
*All sections beginning with <nowiki>#</nowiki> need <nowiki>#</nowiki>End before the next section.
**<nowiki>#</nowiki>'''Default Player Ship'''
***Defines the default player ship in the game and also in the FRED. If in a mission appears a ship that has not been properly included to tables then game replaces the ship with the Default Player Ship.
**<nowiki>#</nowiki>'''Engine Wash Info'''
***Includes all the definitions of all engine washes used in the game.
{{Table3610|
:*<nowiki>#</nowiki>'''Ship Templates'''
:**Includes entries for ship templates}}

:*<nowiki>#</nowiki>'''Ship Classes'''
:**Includes entries for every ship and also defines their attributes that are used in the game
:**Is discussed in detail at [[Ships.tbl#Table_Options|Table Options]] section.
:*'''$Player Ship Precedence'''
:**Player Ship Precedence is used in ship selection when a ship specified by the mission designer is not available to the player. The next ship on the list is used in its place (assuming that ship is allowed for the player)

==Default Player Ship==
*Defines the default ship in the game.
*Syntax: ''Name'', name of ship model as defined in [[Ships.tbl#Table_Options|Table Options]].

==Engine Wash==
*Defines the engines washes
*First entry must be named 'default'

===$Name:===
*Defines the name of the engine wash.
*Syntax: '''''String'''''

===+nocreate===
{{Table3610|
*In [[Modular Tables]] name can be followed by line '''+nocreate''' that prevent game from creating an incomplete entry by leaving the entry unread unless it already exists (either in ship.tbl or in earlier parsed *-shp.tbm files) by the time the *-shp.tbm is read.}}

===$Angle:===
*Defines the angle from the engine where the engine wash exists
*Syntax: '''''Float''''', degrees

===$Radius Mult:===
*Defines engine wash multiplier
*Syntax: '''''Float'''''

===$Length:===
*Defines the length of the engine wash
*Syntax: '''''Float''''', meters

===$Intensity:===
*Defines the strength of the engine wash
*Syntax: '''''Float''''', blast effect

'''Example'''

$Name: Default
$Angle: 10.0
$Radius Mult: 1.2
$Length: 400
$Intensity: 1.0

==Ship Template Options==
{{Warning|
The ship templates feature has always caused crashes and memory issues. As of 2014/07/24, it has been removed from the codebase.}}
{{Table3610|
*Example of template usage [[Ship_Templates]] in which both [[GTB Artemis]] variants have been defined using a single template}}

===$Template:===
{{Table3610|
*Defines the name of template
*Syntax: '''''String''''', name}}

===+Use Template:===
{{Table3610|
*Another template can be used as template for the current template
*Syntax: '''''String''''', name}}

==Ships Table Options==

===$Name:===
*Model name that is used also in game. It is also used as name for the whole ship entry. There are two special characters can be used in the name: '''#''' and '''@'''
**'''#'''. It's used in the middle of the name and cannot be the first character in the $Name: string. It makes the right part of the name not being shown in the ship class info of the target window, (or beside the target brackets in FS_Open builds). It allows making different versions of a base ship while showing the same class name inside the game. An example from FSPort FreeSpace 1: The '''SF Dragon#weakened''' ship, used in [[Enter the Dragon]], appears to the player just as any other '''SF Dragon'''.
**'''@'''. It's used before the proper ship name. It is fully ignored by the game. Moreover, '''@WhateverShip''' and '''WhateverShip''' are exactly the same name and therefore they both appear as '''WhateverShip''' inside the game. It just allows the user marking ships in the table because of any modding reason. In the retail FS2 ships there are several ships starting by '''@'''.
*Syntax: '''''String''''', name

===+nocreate===
{{Table3610|
*In [[Modular Tables]] name can be followed by line '''+nocreate''' that prevent game from creating an incomplete entry by leaving the entry unread unless it already exists (either in ship.tbl or in earlier parsed *-shp.tbm files) by the time the *-shp.tbm is read.}}

===+Use Template:===
{{Table3610|
*Sets the table entry to use template based on an existing table entry instead of creating totally new one
*Syntax: '''''String''''', name of the template}}

===$Alt Name:===
{{Table3613|
*Alternative $Name: for the ship.
*Syntax: '''''String''''', Alternate $Name:}}

===$Short name:===
*Shortened model name, for FRED, Usually more descriptive than the real name.
*Syntax: '''''String''''''

===$Species:===
*Defines species (Terran, Vasudan or Shivan). Determines many things, including the color of the engine glow, the flyby sound effects, the briefing icon and the support ship.
{{Table3610|
*More species have been enabled, and all of these have to be defined in [[species_defs.tbl]].}}

*Syntax: '''''String''''', name of the species
**Example: ''Terran''

===Technical Description===
List of descriptive terms for techroom and ship selection screens. Number after the quotes refers to [[tstrings.tbl]]

====+Type:====
*Syntax: XSTR("'''''String'''''", integer)
*Example: XSTR("", -1)

====+Maneuverability:====
*Syntax: XSTR("'''''String'''''", integer)
*Example: XSTR("", -1)

====+Armor:====
*Syntax: XSTR("'''''String'''''", integer)
*Example: XSTR("", -1)

====+Manufacturer:====
*Syntax: XSTR("'''''String'''''", integer)
*Example: XSTR("", -1)

====+Description:====
*Syntax: XSTR("'''''String'''''", integer)
*Requires '''$end_multi_text''' after the entry
*Example:
::XSTR("", -1)
::$end_multi_text

====+Tech Title:====
{{Table3613|
*Defines name of the ship as displayed in the tech room
*Syntax: '''''String'''''}}

====+Tech Description:====
*Syntax: XSTR("'''''String'''''", integer)
*Requires '''$end_multi_text''' after the entry
*Example:
::XSTR("", -1)
::$end_multi_text

====+Length:====
*Syntax: XSTR("'''''String'''''", integer)
*Example: XSTR("", -1)

====+Gun Mounts:====
*Syntax: XSTR("'''''String'''''", integer)
*Example: XSTR("", -1)

====+Missile Banks:====
*Syntax: XSTR("'''''String'''''", integer)
*Example: XSTR("", -1)

===$Selection Effect:===
{{Table3613|
*Defines which selection effect to use when the -ship_choice_3d commandline flag is enabled or no ani can be found for the selected ship.
*Syntax: String, either "FS1", or "Off". This defaults to the FS2 effect.}}

===$Cockpit POF file:===
{{Table3610|*Filename of the cockpit model file
*Syntax: '''''String.pof''''', model filename}}

===+Cockpit Offset:===
{{Table3610|*Defines the offset of the cockpit model
*Syntax: '''''Vector''''', three '''floats''', x-axis, y-axis, z-axis, respectively}}

===$Cockpit Display:===
{{Table3615|
*Defines a rectangle surface on a cockpit texture that can be updated dynamically. Multiple displays can be defined, but only one needs to be defined for each texture on the cockpit model.
*'''+Texture:'''
*The filename of the cockpit texture to be replaced.
*Syntax: '''''String''''', texture filename
*'''+Offsets:'''
* (Optional) The offsets of the rectangle surface into the texture that will be drawn into.
*Syntax: '''''Vector''''', two '''integers'''
*'''+Size:'''
* The size of the rectangle surface that will be drawn into.
*Syntax: '''''Vector''''', two '''integers'''
*'''+Background:'''
* (Optional) Filename of the bitmap to be used as the background of this display.
*Syntax: '''''String''''', texture filename
*'''+Foreground:'''
* (Optional) Filename of the bitmap to be used as the foreground of this display.
*Syntax: '''''String''''', texture filename
*'''+Display Name:'''
* A name to be used as a reference handle.
*Syntax: '''''String'''''}}

===$POF File:===
*Filename of the model file (.pof) at data/models folder
*Syntax: '''''String.pof''''', model filename

===$Texture Replace:===
{{Table3610|
*'''+old:'''
*Defines the texture to be replaced
**Syntax: '''''String''''', filename
*'''+new:'''
*Defines the new texture
**Syntax: '''''String''''', filename}}

===$POF Target File:===
*Optional hud targeting model
*Syntax: '''''String.pof''''', model filename

===$POF Target LOD:===
{{Table3610|
*Defines the LOD (Level-Of-Detail) of target model used in the HUD targetbox
*Syntax: '''''Integer'''''}}

===$Detail Distance:===
*Defines the distance where the change between different Levels-Of-Details (LODs) occurs
*Take notice that these are base values. Model detail in Detail options, (within game press F2), applies a multiplier to these values. These multipliers default to (from left to right): 1/8, 1/4, 1, 4, and 8, and may be overridden by the [[Ai_profiles.tbl#$Detail Distance Multiplier:|$Detail Distance Multiplier]]
*Syntax: '''''(Detail Distances)''''' , list of '''integers''' (same amount as LODs), distances from the model in meters
**Example: ''(0, 80, 300, 900)''

===$Collision LOD:===
{{Table373|
*Defines an alternative LOD (Level-Of-Detail) to use for collision detection. Using this can increase performance without visible drawbacks if the LOD chosen has much simpler geometry but the shape still closely matches the base model.
*This works as follows: collision detection proceeds normally through the various model/submodel radius and bounding box checks based on LOD0, but when the game decides to perform a mesh-based collision check of a given submodel, it will use the submodel's LOD mesh instead. However, all submodels do not need to have a counterpart in the given LOD; if one is not found, the closest alternative will automatically be used instead.
*For example, if ''$Collision LOD: 3'' is used and the submodel engine01a is checked for a hit, the game will attempt to use the mesh of engine01d instead. However, if there is no engine01d submodel, the game will find the closest alternative: it'll look for engine01c, then engine01b, and finally fall back to engine01a. Note the implications of for example the root LOD submodel (detaild, detail3, etc) including the geometry of subsystem submodels; if detail0 is checked for a collision before engine01a, and detail3 includes the engine geometry (as opposed to having it in engine01d), then the subsystem engine01a cannot be hit.
**Syntax: '''''Integer'''''}}

===$ND:===
*No Dim field field was used in FreeSpace for ship lights. Use of glowmaps is preferred to the $ND entry. Only noticeable in Glide or Software mode.
*Syntax: '''''Color''''', red, green, blue respectively, value from 0 to 255
**Example: ''42, 42, 224''

===$Enable Team Colors:===
{{Table3615|
*Enables Team Colors for a ship without setting a default color setting.
*Syntax: '''''Boolean'''''}}

===$Default Team:===
{{Table3615|
*Specifies the default team name to be used for coloring a ship.
*None is will set the default to 'no coloring'.
*Syntax: '''''String''''', name of the teams as defined in [[colors.tbl]]}}

===$Show Damage:===
*No function at all. The engine will read values, but discard them. In 3.6.10 or later, this can be left out without adverse consequences.
*Syntax: '''''Boolean''''', yes or no, usually yes

===$Damage Lightning Type:===
{{Table3613|
*Changes the damage lightning effect shown on highly damaged ships.
*Can be defined as:
**''None''
**''Default''}}

===$Impact:===
{{Table3610|
*'''+Damage Type:'''
**Defines the damage type of the collision
**Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]}}

===$Impact Spew:===
{{Table3610|
*Used to define the impact particle spew
*Note: You CANNOT define a different type of particle spew here; the only option possible is listed below
*'''+Max particles:'''
**Defines the maximum number of particles spewed
**Setting to zero causes model to generate no particles at all
**Syntax: '''''Integer'''''
**Default Value: 30}}{{Table3613|
*'''+Min particles:'''
**Defines the minimum number of particles spewed
**Syntax: '''''Integer'''''
**Default Value: 25
*'''+Max Radius:'''
**Defines the maximum radius of particles
**Syntax: '''''Float'''''
**Default Value: 0.5f
*'''+Min Radius:'''
**Defines the minimum radius of particles
**Syntax: '''''Float'''''
**Default Value: 0.2f
*'''+Max Lifetime:'''
**Defines the maximum lifetime of particles
**Syntax: '''''Float'''''
**Default Value: 0.55f
*'''+Min Lifetime:'''
**Defines the minimum lifetime of particles
**Syntax: '''''Float'''''
**Default Value: 0.05f
*'''+Max Velocity:'''
**Defines the maximum velocity of particles
**Syntax: '''''Float'''''
**Default Value: 12.0f
*'''+Min Velocity:'''
**Defines the minimum velocity of particles
**Syntax: '''''Float'''''
**Default Value: 2.0f
*'''+Normal Variance:'''
**Defines the variance of particle direction from the normal
**Syntax: '''''Float'''''
**Default Value: 1.0f}}

===$Damage Spew:===
See [[Ship.tbl#$Impact Spew:|Impact Spew entry]]
*Controls the 'smoke' released on weapon impact point
*Certain default values (marked with '''X''') gain a specific multiplier based on ship radius
::If the radius is less than 20 the multiplier is 1
::If the radius is larger than 40 the multipler is 1.2
::Otherwise it is between 1 and 1.2
{{Table3610|
*'''+Max Particles:'''
**Default Value: 50 * '''X'''}}{{Table3613|
*'''+Min Particles:'''
**Default Value: 20 * '''X'''
*'''+Max Radius:'''
**Default Value: 1.3
*'''+Min Radius:'''
**Default Value: 0.7
*'''+Max Lifetime:'''
**Default Value: 1.5 * '''X'''
*'''+Min Lifetime:'''
**Default Value: 0.7 * '''X'''
*'''+Max Velocity:'''
**Default Value: 12.0
*'''+Min Velocity:'''
**Default Value: 3.0
*'''+Normal Variance:'''
**Default Value: 0.2 * '''X'''}}

===$Collision Physics:===
{{Table3613|
*Parameters affecting collision physics, including landings.
*"Landing" means the ship will not take damage or shake when it touches down. Instead, the ship will reorient towards a neutral resting orientation. "Reorient" thresholds below mean that the ship will still take damage (counts as a crash) but will move towards the correct landing orientation.

====+Bounce:====
When this ship collides with a large ship, how many meters to instantly move it away. Default is 5.0.
====+Both Small Bounce:====
When this ship collides with a small ship, how many meters to instantly move it away. Default is 5.0.
====+Friction:====
During collisions, how much friction to apply (slowing lateral movement). Default is 0.0.
====+Rotation Factor:====
Affects the rotational energy of collisions. Default is 0.2.
====+Landing Max Forward Vel:====
Maximum velocity for which landing physics are used.
====+Landing Min Forward Vel:====
Minimum velocity for which landing physics are used.
====+Landing Max Descent Vel:====
Maximum velocity at which the ship can "hit the deck" and still be considered a landing.
====+Landing Max Horizontal Vel:====
Maximum sideways velocity the ship can land at.
====+Landing Max Angle:====
Maximum angle of attack the ship can land at (in degrees).
====+Landing Min Angle:====
Minimum angle of attack the ship can land at (in degrees).
====+Landing Max Rotate Angle:====
How many degrees the ship can be rotated relative to the landing surface in order to count as a landing.
====+Reorient Max Forward Vel:====
Maximum velocity for which the ship will be adjusted to the correct landing orientation.
====+Reorient Min Forward Vel:====
Minimum velocity for which the ship will be adjusted to the correct landing orientation.
====+Reorient Max Descent Vel:====
Maximum velocity at which the ship can "hit the deck" and still reorient.
====+Reorient Max Horizontal Vel:====
Maximum sideways velocity for reorienting.
====+Reorient Max Angle:====
Maximum angle of attack for reorienting to kick in (in degrees).
====+Reorient Min Angle:====
Minimum angle of attack for reorienting to kick in (in degrees).
====+Reorient Max Rotate Angle:====
How many degrees the ship can be rotated relative to the landing surface in order to be reoriented on impact.
====+Reorient Speed Mult:====
How quickly the reorientation takes place (when applicable)
====+Landing Rest Angle:====
Angle of the ship's nose relative to the plane of the landing surface when the ship is at rest. Reorient will move the ship towards this angle.
====+Landing Sound:====
Sound to play when landing (if it's not a landing, normal collision sound is used).
}}

===$Debris:===
{{Table3610|
*'''+Min Lifetime:'''
**Defines the minimum lifetime of the debris (Default value is a random number)
**Syntax: '''''Float,''' Seconds
*'''+Max Lifetime:
**Defines the maximum lifetime of the debris
**Syntax: '''''Float,''' Seconds
*'''+Min Speed:
**Defines the minimum speed of the debris
**Syntax: '''''Float,''' Meters/second
*'''+Max Speed:
**Defines the maximum speed of the debris
**Syntax: '''''Float,''' Meters/second
*'''+Min Rotation speed:
**Defines the minimum rotational speed of the debris (Default is (6 to 10)/Ship-radius)
**Syntax: '''''Float,''' Radians/second
*'''+Max Rotation speed:
**Defines the maximum rotational speed of the debris
**Syntax: '''''Float,''' Radians/second
*'''+Damage Type:'''
**Defines the damage type of the debris
**Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]}}
{{Table3611|
*'''+Min Hitpoints:'''
**Defines the minimum hitpoints assigned for the generated debris pieces
**Syntax: '''''Float'''''
*'''+Max Hitpoints:'''
**Defines the maximum hitpoints assigned for the generated debris pieces
**Syntax: '''''Float'''''
*'''+Damage Multiplier:'''
**Defines the collision damage multiplier for collisions against the generated debris pieces
**Syntax: '''''Float'''''
*'''+Lightning Arc Percent:'''
**Controls what percent of debris pieces will have the damage lightning effect applied to them.
**Defaults to 50%.
**Syntax: '''''Float,''' 0-100}}

===$Density:===
*This defines how hard you hit something. If you set it very high, a collision will the lower density ship and not yours; the higher the numbers are, the harder they will hit and the farther they will be pushed. However, this doesn't apply to asteroids. When a high density fighter collides with an asteroid, the high-density fighter will receive damage, but it will also destroy the asteroid. Setting a density of 1000 on a fighter with 180 hitpoints will cause the fighter to immediately explode if it collides with, say, an asteroid. A low-density fighter will not have any effect on an asteroid, but if the fighter destroys the asteroid, the fighter will fly far away.
*Syntax: '''''Float''''', usually 1

===$Damp:===
*Sets the natural period (1 / omega) of the dampening effects on top of the acceleration model. (See [[Ships.tbl#$Forward Accel:|$Forward Accel:]])
*In essence, affects how quickly you will accel/decel to your target velocity. Higher damp means slower acceleration and deceleration, while lower values (down to 0.0001) means faster acceleration/deceleration.
**Specifying a value of 0.0 means there is no damping placed on top of the acceleration model, which is the most responsiveness you'll get.

*Syntax: '''''Float'''''

===$Rotdamp:===
*Shares the same principles of [[Ships.tbl#$Damp:|$Damp]], but is applied to rotations directly. (there isn't a engine/thrust acceleration model for rotations)
*Syntax: '''''Float'''''

===$Banking Constant:===
{{Table3610|
*Defines a factor for how much roll is added during a yaw. Set as 1 for full roll and 0 is no roll. Default is 0.5.
*Syntax: '''''Float'''''}}

===$Max Velocity:===
*Defines maximum velocities with standard energy settings on x (left/right), y (up/down), and z (forward) -axis (respectively). z -axis velocity defines the maximum forward velocity.
*The x and y velocities are considered slide veocities
*Syntax: '''''Vector''''', three '''floats''', x-axis, y-axis, z-axis, respectively, meters per second
**Example: ''0.0, 0.0, 80.0''

===$Player Minimum Velocity:===
{{Table38|
*Defines minimum velocities on x (left/right), y (up/down), and z (forward) -axis (respectively). This affects the player only, the AI ignores the value.
*The x and y velocities are considered slide velocities, the minimums for them are '''not currently implemented'''.
*When gliding, if the absolute speed vector of the players ship falls below the minimum then the ships engines will re-engage and cannot be switched off again until the ships absolute vector exceeds the z-minimum.
*Syntax: '''''Vector''''', three '''floats''', x-axis, y-axis, z-axis, respectively, meters per second
**Example: ''0.0, 0.0, 40.0''
}}

===$Rotation Time:===
*Defines rotation times around the x, y, and z-axis. Number is seconds it takes to complete rotate a ship (360 degrees) around the given axis. X-axis is "pitch," y-axis is "yaw," and z-axis is "roll."
*Syntax: '''''Vector''''', three '''floats''', seconds per 360 degree turn around x-axis, y-axis, z-axis, respectively
**Example: ''3.0, 2.6, 5.0''
**Note: Setting to Zero will cause the model to disappear in mission.

===$Rear Velocity:===
*Defines rear velocity
*Syntax: '''''Float''''', meters per second
**Note: This value must be set for [[Ships.tbl#.2BAburn_Max_Reverse_Vel:|+Aburn_Max_Reverse_Vel:]] to work

===$Forward Accel:===
*Number of seconds needed from full stop to 63.21% of the maximum forward (z) velocity
** We use 63.21% instead of 100% because FSO's acceleration/velocity model is based on a simplistic exponential function, rather than the more complex models seen for prop-driven, jet-driven, or rocket-driven craft.
** The equation is a derivative of v = 1 - e^(-t / T), where T is what we define in the ship.tbl
*Syntax: '''''Float''''', seconds

===$Forward Decel:===
*Number of seconds needed from maximum forward (z) velocity to full stop
*Syntax: '''''Float''''', seconds

===$Slide Accel:===
*Number of seconds needed from full stop to 63.21% maximum slide velocity
*Note: this is applied to both slide (x and y) axes
**See [[Ships.tbl#$Forward Accel:|$Forward Accel]] for an explanation of the 63.21%
*Syntax: '''''Float''''', seconds

===$Slide Decel:===
*Number of seconds needed from 63.21% maximum slide velocity to full stop
*Note: this is applied to both slide (x and y) axes
**See [[Ships.tbl#$Forward Accel:|$Forward Accel]] for an explanation of the 63.21%
*Syntax: '''''Float''''', seconds

===$Glide:===
{{Table3610|
*Allows gliding in game, i.e. turning the ship's attitude/facing without changing its current movement direction and speed.
*Syntax: '''''Boolean''''', yes or no}}

====+Dynamic Glide Cap:====
{{Table3611|
*If set, game uses dynamic glide cap. The dynamic glide cap means that the maximum glide speed will follow the same rules as normal flight, including the effects of afterburner and power to engines. If set to YES, the value in +Max Glide Speed is ignored.
*Syntax: '''''Boolean'''''}}

====+Max Glide Speed:====
{{Table3610|
*Defines the maximum glide speed if glide has been enabled. If 0, this is set to the fastest speed the ship can go. If negative, there is no glide cap (allowing practically infinite maximum gliding speed). Defaults to 0.
*Syntax: '''''Float'''''}}

====+Glide Accel Mult:====
{{Table3611|
*Defines the acceleration multiplier for the gliding mode. If > 0, sets a fixed acceleration rate in glide mode depending on value. If set to 0, impossible to accelerate while in glide mode. If negative, enables glide speed ramping (acceleration in glide mode ramps in the same way as in normal flight). Defaults to 0.
*Syntax: '''''Float'''''}}
{{Table3610|
*Entry exists as a dummy entry which doesnt do anything to prevent compatibility issues}}

===$Use Newtonian Dampening:===
{{Table3611|
*If set, forces the ship to use (or not use) newtonian dampening. Basically, allows overriding the AI Profiles flag on a per-ship basis.
*Syntax: '''''Boolean'''''}}

===$Autoaim FOV:===
{{Table3610|
*Defines the field of view for autoaim
*Syntax: '''''Integer'''''}}

====+Converging Autoaim====
{{Table3611|
*Defines that the autoaim uses convergence}}

====+Minimum Distance:====
{{Table3611|
*Defines the minimum distance for the convergence}}

===$Convergence:===
{{Table3611|
*Defines the weapons use convergence
{{Note|If none of the following optional strings are added, the weapon will not converge. Don't forget to use them.}}
}}

====+Automatic====
{{Table3611|
*Defines that the ship uses automatic convergence - converging distance calculated from estimated hit position (lead) of the current target.
*'''+Minimum Distance:'''
**Defines the minimum distance for the convergence. Overrides the setting for $Autoaim FOV's minimum distance.}}

====+Standard====
{{Table3611|
*Defines that ship uses fixed convergence.
*'''+Distance:'''
**Defines the converging distance from the ship}}

====+Offset:====
{{Table3611|
*Defines the offset from the ship centerpoint for the convergence
*Syntax: '''''Vector''''', three '''floats''', x-axis, y-axis, z-axis, respectively}}

===$Warpin Type:===
{{Table3610|
*Allow an animation to be defined as a warpin effect.
*Can be defined as:
:*''Default''
:*''BTRL'' or ''Galactica''
:*''Homeworld''
:*''Hyperspace''}}
{{Table3613|
:*''Knossos''
:*''Babylon5''}}
{{Table3611|
::*''BTRL'' was replaced with ''Galactica'' after 3.6.10}}
{{Table3610|
*Syntax: '''''String'''''}}

===$Warpin Start Sound:===
{{Table3610|
*File for playing at start of warp in effect
*Syntax: '''''String''''', filename}}

===$Warpin End Sound:===
{{Table3610|
*File for playing at end of warp in effect
*Syntax: '''''String''''', filename}}

===$Warpin Speed:===
{{Table3610|
*Sets the speed at which the ship warps in for '''default''' warpin effect
*Sets the time that the ships warp in (not the animation itself) takes for '''BTRL''' type warpin effects
*Syntax: '''''Float''''', meters per second or miiliseconds}}

===$Warpin Time:===
{{Table3610|
*Defines the effect duration
*Syntax: '''''Float''''', seconds}}

===$Warpin Decel Exp:===
{{Table3613|
*Only for the '''hyperspace''' warpin effect.
*Defines an exponent for the deceleration curve at the end of the warpin. Must be higher than 0; a value of 1 produces a constant velocity throughout the effect and higher values produce gradual deceleration.
*Syntax: '''''Float'''''
**Default: 1.0}}

===$Warpin Radius:===
{{Table3610|
*Defines the effect radius
*Syntax: '''''Float''''', meters}}

===$Warpin Animation:===
{{Table3610|
*Defines the animation used for the Homeworld warpin effect. Has no effect for other warpin types.
*Syntax: '''''String''''', filename}}

===$Warpout Type:===
{{Table3610|
*Allow an animation to be defined as a warpout effect.
*Can be defined as:
:*''Default''
:*''BTRL'' or ''Galactica''
:*''Homeworld''
:*''Hyperspace''}}
{{Table3613|
:*''Knossos''
:*''Babylon5''}}
{{Table3611|
::*''BTRL'' was replaced with ''Galactica'' after 3.6.10}}
{{Table3610|
*Syntax: '''''String'''''}}

===$Warpout Start Sound:===
{{Table3610|
*File for playing at start of warp out effect
*Syntax: '''''String''''', filename}}

===$Warpout End Sound:===
{{Table3610|
*File for playing at end of warp out effect
*Syntax: '''''String''''', filename}}

===$Warpout Engage Time:===
{{Table3615|
*Defines the delay the it takes for the warp drive of the ship to engage, during which the player may still abort the warpout. Affects both the player as well as AI ships. If not defined, defaults to 3 seconds for the player and none for the AI.
*Syntax: '''''Float''''', seconds}}

===$Warpout Speed:===
{{Table3610|
*Sets the speed at which the ship warps out for '''default''' warpout effect
*Sets the time that the ships warp out (not the animation itself) takes for '''BTRL''' type warpout effects}}
{{Table3613|
*Sets the minimum speed required for the ship to warp out for '''hyperspace''' type warpout effects}}
{{Table3610|
*Syntax: '''''Float''''', meters per second or milliseconds}}

===$Warpout Time:===
{{Table3610|
*Defines the effect duration
*Syntax: '''''Float''''', seconds}}

===$Warpout Accel Exp:===
{{Table3613|
*Only for the '''hyperspace''' warpin effect.
*Defines an exponent for the acceleration curve at the start of the warpout. Must be higher than 0; a value of 1 produces a constant velocity throughout the effect and higher values produce gradual acceleration.
*Syntax: '''''Float'''''
**Default: 1.0}}

===$Warpout Radius:===
{{Table3610|
*Defines the effect radius
*Syntax: '''''Float''''', meters}}

===$Warpout Animation:===
{{Table3610|
*Defines the animation used as the warpout effect.
*Syntax: '''''String''''', filename}}

===$Player Warpout Speed:===
{{Table3610|
*Sets the speed at which the player warps out from the game
*Syntax: '''''Float'''''}}

===$Expl Inner Rad:===
*Radius at which the full explosion damage is done
*Syntax: '''''Float''''', meters

===$Expl Outer Rad:===
*Maximum radius at which any damage is done
*Syntax: '''''Float''''', meters

===$Expl Damage:===
*Amount of damage done inside the inner radius
*Syntax: '''''Float''''', damage

===$Expl Blast:===
*The intensity of the blast effect when you're within the outer radius
*Syntax: '''''Float''''', blast effect

===$Expl Propagates:===
*This decides whether the ship explodes into debris immediately, or whether it has the many small explosions before breaking apart slowly
*Syntax: '''''Boolean''''', yes or no

===$Propagating Expl Radius Multiplier:===
{{Table3613|
*This sets the multiplier for the ship splitting propagating explosions
*Syntax: '''''Float''''', defaults to 1}}

===$Expl Visual Rad:===
{{Table3611|
*This determines the visual size of the main fireball for an exploding ship. Does not affect ships with propagating explosions.
*Syntax: '''''Float''''', meters}}

===$Base Death-Roll Time:===
{{Table3613|
*Defines the base death-roll time
*Values is modified depending on conditions when the ship died
*Syntax: '''''Integer''''', milliseconds
**Default: 3000}}

===$Death-Roll Explosion Radius Mult:===
{{Table3613|
*Defines the multiplier for the radius of the ship surface explosions during death roll
*Syntax: '''''Float'''''
**Default: 1}}

===$Death-Roll Explosion Intensity Mult:===
{{Table3613|
*Defines the multiplier for the amount of the ship surface explosions during death roll
*Syntax: '''''Float'''''
**Default: 1}}

===$Death FX Explosion Radius Mult:===
{{Table3613|
*Defines the multiplier applied to the ship death explosions
*Syntax: '''''Float'''''
**Default: 1}}

===$Death FX Explosion Count:===
{{Table3613|
*Defines the number of explosion effect game uses when a large ship dies
*Syntax: '''''Integer'''''
**Default: 6}}

===$Ship Splitting Particles:===
See [[Ship.tbl#$Impact Spew:|Impact Spew entry]]
*Controls the particles released on every explosion event which happens when ship is splitting apart
*The old 'popcorn' effect
{{Table3613|
*'''+Max Particles:'''
**Default Value: 80
*'''+Min Particles:'''
**Default Value: 40
*'''+Max Radius:'''
**Default Value: Ship radius * 0.015
*'''+Min Radius:'''
**Default Value: Ship radius * 0.005
*'''+Max Lifetime:'''
**Default Value: 6.0 * (1 + 0.002 * Ship radius)
*'''+Min Lifetime:'''
**Default Value: 0.5 * (1 + 0.002 * Ship radius)
*'''+Max Velocity:'''
**Default Value: Speed of the propagating explosion
*'''+Min Velocity:'''
**Default Value: 0.0
*'''+Normal Variance:'''
**Default Value: 2.0}}

===$Ship Death Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used the final explosion of this ship type,
*Syntax: '''String''', the particle effect name
*If this option is specified then ''$Ship Death Particles'' is not a valid option!
}}

===$Ship Death Particles:===
See [[Ship.tbl#$Impact Spew:|Impact Spew entry]]
*Controls the particles released on the moment 'non-knossos' type object dies
{{Table3613|
*'''+Max Particles:'''
**Default Value: 100
*'''+Min Particles:'''
**Default Value: 50
*'''+Max Radius:'''
**Default Value: 1.5
*'''+Min Radius:'''
**Default Value: 0.1
*'''+Max Lifetime:'''
**Default Value: 4.0
*'''+Min Lifetime:'''
**Default Value: 0.5
*'''+Max Velocity:'''
**Default Value: 20.0
*'''+Min Velocity:'''
**Default Value: 0.0
*'''+Normal Variance:'''
**Default Value: 2.0}}

===$Alternate Death Particles:===
See [[Ship.tbl#$Impact Spew:|Impact Spew entry]]
*Controls the particles released when 'knossos' type object is dying
{{Table3613|
*'''+Max Particles:'''
**Default Value: 30
*'''+Min Particles:'''
**Default Value: 15
*'''+Max Radius:'''
**Default Value: 100.0
*'''+Min Radius:'''
**Default Value: 30.0
*'''+Max Lifetime:'''
**Default Value: 12.0
*'''+Min Lifetime:'''
**Default Value: 2.0
*'''+Max Velocity:'''
**Default Value: 350.0
*'''+Min Velocity:'''
**Default Value: 50.0
*'''+Normal Variance:'''
**Default Value: 2.0}}

===$Vaporize Percent Chance:===
{{Table3611|
*Allows ships to sometimes explode instantly (vaporize) instead of going through a death roll first. Overrides the same flag in [[objecttypes.tbl]].
*Syntax: '''''Float''''', percent chance of vaporization, 0 to 100}}

===$Shockwave Damage Type:===
{{Table3610|
*'''REQUIRES ADDITIONAL TABLE'''. Defines the damage type used for the ship explosions
*Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]}}

===$Shockwave Speed:===
*Speed shockwave expands at, 0 means no shockwave
*Syntax: '''''Float''''', meters per second

===$Shockwave Count:===
*Defines the number of shockwaves to spawned
*Syntax: '''''Integer'''''

===$Shockwave Model:===
{{Table3610|
*Defines the textured model used as the ship's 3D shockwave
*Syntax: '''''String.pof''''', model filename}}

===$Shockwave Name:===
{{Table3610|
*Defines the name of the animation to used for the 2D shockwave
*Syntax: '''''String''''', filename}}

===$Explosion Animations:===
{{Table3610|
*Defines the explosion animations used for the ship
*Syntax: '''''Integer list'''''}}

===$Weapon Model Draw Distance:===
{{Table3610|
*Distance that external weapons are shown, ie. missiles and such.
*Syntax: '''''Float''''', meters
**Default: ''200''}}

===Primary Weapons===
====$Allowed PBanks:====
*List of allowed primary weapons in brackets (weapon name marked with quotes).
*Syntax: '''''( "String" "String" )''''', names of the weapons
{{Table3610|
*Each of the primary weapon banks '''can optionally''' be given their own list of allowed weapons, in which case each bank has its own bracketed entry.
*Syntax: '''''( "String" "String" ) ( "String" "String" )'''''}}

====$Allowed Dogfight PBanks:====
*Primary weapons for multiplayer dogfights.
*Syntax: '''''( "String" "String" )''''', names of the weapons
{{Table3610|
*Each of the primary weapon dogfight banks '''can optionally''' be given their own list of allowed weapons, in which case each bank has it's own bracketed entry.
*Syntax: '''''( "String" "String" ) ( "String" "String" )'''''}}

====$Default PBanks:====
*Defines default primary weapons for each of the primary weapon banks
*Syntax: '''''( "String" "String" )''''', names of the weapons

====$PBank Capacity:====
{{Table3610|
*Defines ammunition capacity of primary weapon banks. In brackets, different weapon banks separated by commas.
*NOTE: In order for this to work, at least one of the primary weapons in the list of default primaries must be a ballistic weapon.
*Syntax: '''''( Integer, Integer )'''''}}

====$Show Primary Models:====
{{Table3610|
*Defines the use of weapon models for primary weapons. In brackets, different weapon banks may have different definitions
*Syntax: '''''( Boolean Boolean )''''', yes or no
**Example: ''( YES YES )'' - Note the spaces on the insides of the brackets.}}

===Secondary Weapons===
====$Allowed SBanks:====
*Same for secondary weapons.
*Syntax: '''''( "String" "String" )''''', names of the weapons
{{Table3610|
*Each of the secondary weapon banks can be given their own list of allowed weapons, in which case each bank has it's own bracketed entry.
*Syntax: '''''( "String" "String" ) ( "String" "String" )'''''}}

====$Allowed Dogfight SBanks:====
*Same for secondary weapons.
*Syntax: '''''( "String" "String" )''''', names of the weapons
{{Table3610|
*Each of the secondary weapon dogfight banks can be given their own list of allowed weapons, in which case each bank has it's own bracketed entry.
*Syntax: '''''( "String" "String" ) ( "String" "String" )'''''}}

====$Default SBanks:====
*Defines default primary weapons for each of the primary weapon banks
*Syntax: '''''( "String" "String" )''''', names of the weapons

====$SBank Capacity:====
*Defines ammunition capacity of secondary weapon banks. In brackets, different weapon banks separated by commas.
*Syntax: '''''( Integer, Integer )'''''

====$Show Secondary Models:====
{{Table3610|
*Defines the use of weapon models for secondary weapons. In brackets, different weapon banks may have different definitions
*Syntax: '''''( Boolean Boolean )'''''
**Example: ''(YES YES)''}}

===$Ship Recoil Modifier:===
{{Table373|
*Multiplies the recoil force of a weapon by this value, use a value greater than 1.0 to increase the force, use a value between 1.0 and 0.0 to decrease.
**Syntax: '''''Float''''' (defaults to 1.0)
{{Note|It is not required to have any weapons with the "apply recoil" flag set for this to be enabled.}}
}}

===$Shields:===
*Determines the shield strength
*Syntax: '''''Float''''', total shield strength

====+Auto Spread:====
{{Table371|
*Defines the thickness of auto spread shields. Note that the [[#.22auto_spread_shields.22|"auto spread shields"]] ship flag is also needed.
*Syntax: '''''Float''''', shield thickness in meters.}}

====+Minimum Weapon Span:====
{{Table373|
*Determines the minimum distance weapons must have traveled before impacting the shield (for example if fired close to or inside the shield). Does not affect whether the weapon bypasses shields, unless +Allow Bypass (see below) is set to ''YES''. Only valid with auto spread shields.
*Syntax: '''''Float''''', defaults to the shield thickness.}}

====+Allow Bypass:====
{{Table371|
*Determines whether weapons which impact on the ship's hull (see +Minimum Weapon Span above) will bypass shields. Only valid with auto spread shields.
*Syntax: '''''Boolean'''''
**Default: ''NO''}}

====+Spread From LOD:====
{{Table371|
*Causes the auto spread shields calculations to be done based off a LOD level other than LOD0. Using a lower-poly LOD will considerably speed up the shield collision detection, while being visually indistinguishable in most cases.
*Syntax: '''''Integer''''', defaults to 0}}

===$Model Point Shield Controls:===
{{Table371|
*Allows remapping of the 4 shield augmentation keys when [[Model Point Shields]] are used. You should usually supply as many values as you have shield segments. The first value determines which augmentation key to use for the first shield segment, the second value determines which key to use for the second shield segment, and so on (the order being defined by the order of the shield points in the model file). If less than 4 values are given, "none" is assumed for the missing ones. Note that as there are only 4 augmentation keys, player ships with more than 4 shield segments would generally not be a good idea.
*Syntax: '''''( String list )''''', possible values "front", "left", "right", "rear" and "none"
**Example: ''( "front" "rear" )'' for a ship with only two shield sections, front and rear; the left and right augmentation keys would be disabled.
**Example: ''( "left" "rear" "right" )'' for a ship with only three shield sections, left, right and rear; the front augmentation key would be disabled.
**Example: ''( "front" "right" "rear" "left" )'' for a ship with four shield sections but perhaps positioned in a non-standard way.}}

===$Shield Color:===
*RGB value for shield color
*Syntax: '''''Color''''', red, green, blue respectively, value from 0 to 255
**Example: ''100, 100, 255''

===$Shield Impact Explosion:===
{{Table373|
*Impact explosion animation to trigger when this ship's shields are hit. Works identically for all shield types.
*Note: The size of the explosion is defined by the weapon, see [[Weapons.tbl#.24Shield_Impact_Explosion_Radius:]].
*Syntax: '''''String''''', filename or ''none''
}}

===$Max Shield Recharge:===
{{Table373|
*Determines a maximum recharge limit of shields. When used, the combined maximum shield energy is lowered, meaning that shield energy can be moved between quadrants even with shields fully charged.
*Syntax: '''''Float''''', multiplier ranging from 0.0 to 1.0, defaults to 1.0
**Example: ''$Max Shield Recharge: 0.5'' caps the combined shield energy to 50%, meaning that a ship with 4 shield quadrants will by default have 12.5% strength on all quadrants (instead of normal 25%), allowing it to for example augment one quadrant to 50% while dropping other quadrants to 0%.
}}

===$Power Output:===
*Actually does *NOTHING* unless set to zero; in which case weapon/shield/burner energy regeneration is disabled. Checked via code inspection 2014/12/29
*Syntax: '''''Float'''''

===$Shield Regeneration Rate:===
{{Table3610|
*Repair rates for shields at percent per second
*Syntax: '''''Float''''', multiplier of total shield hitpoints recharged each second. ('''NOT A PERCENTAGE''', 0.02 equals 2% recharged per second)
**Default: ''0.02''
*Affected by ETS Shields value (1/3rd value recharged per sec at default ETS setting of '4')
*Affected by AI Profile Setting: $Player Shield Recharge Scale:}}

===$Support Shield Repair Rate:===
{{Table3611|
*Shield repair rate when docked to a support ship
*Syntax: '''''Float'''''}}

===$Weapon Regeneration Rate:===
{{Table3610|
*Regeneration rates for primary guns at percent per second
*Syntax: '''''Float''''', multiplier of total gun energy recharged each second ('''NOT A PERCENTAGE''', 0.04 equals 4% recharged per second)
**Default: ''0.04''
*Affected by ETS Guns value (1/3rd value recharged per sec at default ETS setting of '4')
*Affected by AI Profile Setting: $Player Weapon Recharge Scale:}}

===$Max Oclk Speed:===
*Can also be '''$Max Overclock Speed:'''
*Maximum velocity with all energy diverted to engines
*Syntax: '''''Float''''', meters per second

===$Max Weapon Eng:===
*Can also be '''$Max Weapon Energy:'''
*The maximum amount of energy you can store in your primary weapons bank.
*Syntax: '''''Float'''''

===$Hitpoints:===
*How much damage the ship can take
*Syntax: '''''Float''''', hitpoints
**Default: ''100''

===$Hull Repair Rate:===
{{Table3610|
*Repair rates for hull at percent per second
*Syntax: '''''Float''''', multiplier of hitpoints repaired per second, '''NOT A PERCENTAGE''', 0.01 equals 1% recharged per second}}

===$Support Hull Repair Rate:===
{{Table3611|
*Repair rate for hull when docked to a support ship
*Syntax: '''''Float'''''}}

===$Subsystem Repair Rate:===
{{Table3610|
*Repair rates for sybsystems percent per second
*Syntax: ''Value'', percentage of total subsystem hitpoints repaired per second}}

===$Support Subsystem Repair Rate:===
{{Table3611|
*Repair rate for subsystems when docked to a support ship
*Syntax: '''''Float'''''}}

===$Armor Type:===
{{Table3610|
*'''REQUIRES ADDITIONAL TABLE'''. Defines armor type used for the ship
*Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]}}

===$Shield Armor Type:===
{{Table3611|
*'''REQUIRES ADDITIONAL TABLE'''. Defines the armor type used for shield of the ship
*Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]}}

===$Flags:===
*See [[Ships.tbl#Ships.tbl_flags|below]]
*Syntax: '''''( "String" "String" )''''', names of the flags assigned to the ship
**Example: ( "fighter" "in tech database" )
{{Table3610|
*'''+noreplace'''
**Can be used to force game to retain existing flags instead of reseting the ship flags before parsing in the new flags.}}

===$AI Class:===
*Default AI class
*Syntax: '''''String''''', name of the AI class as defined in [[ai.tbl]]

===$Afterburner:===
*Defines if the ships has afterburner
*Syntax: '''''Boolean''''', yes or no
====+Aburn Max Vel:====
*Syntax: '''''Vector''''', three '''floats''', x-axis, y-axis, z-axis, respectively, meters per second
====+Aburn For accel:====
*Defined only for the forward acceleration. In same format as [[Ships.tbl#$Forward Accel:|$Forward Accel]]
*Syntax: '''''Float''''', seconds

====+Aburn Max Reverse Vel:====
{{Table3611|
*Defined only for the reverse acceleration, Sets the top speed for Reverse Afterburner.
*Syntax: '''''Float''''', seconds
**NOTE: Requires [[Ships.tbl#.24Rear_Velocity:|$Rear Velocity:]] to be set in order to work.
}}
====+Aburn Rev accel:====
{{Table3611|
*Defined only for the reverse acceleration. In same format as [[Ships.tbl#$Forward Accel:|$Forward Accel]]

*Syntax: '''''Float''''', seconds'''''}}

====+Aburn Fuel:====
*Amount of afterburner fuel the ship has
*Syntax: '''''Float''''', fuel
====+Aburn Burn Rate:====
*Rate the fuel is consumed when afterburner is engaged (in units per seconds)
*Syntax: '''''Float''''', fuel units per second
====+Aburn Rec Rate:====
*Rate the fuel is restored.
*Syntax: '''''Float''''', fuel units per second
{{Table3610|
====$Trails:====
*Allows afterburner trails to be used
=====+Bitmap:=====
*Texture used to draw the afterburner trail
*Syntax: '''''String''''', filename
=====+Width:=====
*Width of afterburner trail at the beginning of it (ie. the thruster end)
*Syntax: '''''Float''''', meters
=====+Alpha:=====
*Transparancy of the trail, value from 1 (non-transparent) to 0 (totally transparent)
*Syntax: '''''Float'''''
=====+Life:=====
*How long the trail will last
*Syntax: '''''Float''''', seconds}}
{{Table3611|
=====+Faded Out Sections:=====
*Defines the number of the trail sections from the leading edge that are gradually faded away.
*Syntax: '''''Integer'''''}}

===$Countermeasure Type:===
{{Table3610|
*Defines the weapon used as a countermeasure. Weapon does not have to be included in the countermeasure section of the weapons.tbl, but it has to have "countermeasure" flag in that case.
*Syntax: '''''String''''', name of the weapon as defined in [[weapons.tbl]]}}

===$Countermeasures:===
*Number of countermeasures that can be loaded to the ship
*Syntax: '''''Integer'''''

===$Scan Time:===
*Time it takes to scan the ship
*Syntax: '''''Integer''''', milliseconds

===$EngineSnd:===
*Engine sound used for the ship with number referring to sounds.tbl
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$Minimum Engine Volume:===
{{Table373|
*Specifies how to multiply the volume of the engine sound based on ship speed. When the ship is stationary, the engine volume will be multiplied by the given value, with the value approaching 1.0 as the ship speed approaches maximum.
*Note: Default behavior is to ramp the multiplier from 0.5 (when ship is stationary) to 1.0 (when ship is at half speed or more).
*Syntax: '''''Float''''', volume multiplier, usually you'll want a value between 0.0 and 1.0
}}

===$GlideStartSnd:===
{{Table3613|
*Optional sound to be used when entering glide mode, instead of the default throttle down sound.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$GlideEndSnd:===
{{Table3613|
*Optional sound to be used when exiting glide mode, instead of the default throttle up sound.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$CockpitEngineSnd===
{{Table3613|
*Optional sound to be used for looping engine sound heard in the cockpit.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$FullThrottleSnd===
{{Table3613|
*Optional sound to be used for the sound heard when setting throttle to full power.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$ZeroThrottleSnd===
{{Table3613|
*Optional sound to be used for the sound heard when setting throttle to zero power
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$ThrottleUpSnd===
{{Table3613|
*Optional sound to be used for the sound heard when increasing throttle power by 1/3
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$ThrottleDownSnd===
{{Table3613|
*Optional sound to be used for the sound heard when decreasing throttle power by 1/3
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$AfterburnerSnd===
{{Table3613|
*Optional optional sound to be used for the looping sound heard when the afterburner is active
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$AfterburnerEngageSnd===
{{Table3613|
*Optional optional sound to be used for the sound heard when the afterburner is engaged
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$AfterburnerFailedSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the activation of the afterburner failed
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$MissileTrackingSnd===
{{Table3613|
*Optional sound to be used for the sound heard when a aspect seeking missile of the player tries to acquire a lock
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$MissileLockedSnd===
{{Table3613|
*Optional sound to be used for the sound heard when a aspect seeking missile of the player has acquired a lock
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$PrimaryCycleSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the player cycles his primary weapon
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$SecondaryCycleSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the player cycles his secondary weapon
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$TargetAcquiredSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the player acquires a new target
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$PrimaryFireFailedSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the primary weapon fails to fire
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$SecondaryFireFailedSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the secondary weapon fails to fire
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$HeatSeekerLaunchWarningSnd===
{{Table3613|
*Optional sound to be used for the sound heard when a heat-seeker is fired at the player
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$AspectSeekerLaunchWarningSnd===
{{Table3613|
*Optional sound to be used for the sound heard when an aspect-seeker is fired at the player
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$MissileLockWarningSnd===
{{Table3613|
*Optional sound to be used for the sound heard when an aspect-seeker is locked onto the player
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$HeatSeekerProximityWarningSnd===
{{Table3613|
*Optional sound to be used for the sound heard when a heat-seeker is in close proximity to the player
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$AspectSeekerProximityWarningSnd===
{{Table3613|
*Optional sound to be used for the sound heard when an aspect-seeker is in close proximity to the player
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$MissileEvadedSnd===
{{Table3613|
*Optional sound to be used for the sound heard when a missile has been evaded
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$CargoScanningSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the cargo of an object is being scanned
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$ExplosionSnd===
{{Table3613|
*Optional sound to be used for the sound heard when the ship explodes
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
}}

===$Closeup_Pos:===
*How the model will show at techroom and briefing screen animations (assuming a pre-rendered animation is not specified). The position of the camera relative to the model in the tech room and the target box view. If 3D ship selection is used, also affects the drawing of the ship icon in the weapon & ship selection briefing screens.
*Syntax: '''''Vector''''', three '''floats''', x, y and z values respectively

===$Closeup_Zoom:===
*How the model will show at techroom and briefing screen animations (assuming a pre-rendered animation is not specified). How far the camera's zoomed in, defines camera's FOV. If 3D ship selection is used, also affects the drawing of the ship icon in the weapon & ship selection briefing screens.
*Syntax: '''''Float''''', radians

===$Topdown Offset:===
{{Table3610|
*Specifies how high the camera is above the center point of a ship in topdown camera views, or 2D missions.
*Syntax: '''''Float''''', meters}}

===$Shield_Icon:===
*This .ani file must be at data/hud and included to the hud.tbl.
{{Table3610|
*Reference to the hud.tbl is no longer needed.}}
**Syntax: ''Filename''

===$Model Icon Direction:===
{{Table373|
*The direction from which the ship should be drawn from, if $Ship_Icon is not used and the ship icon is generated from the model.
** By default, the direction is based on whether the game thinks the ship is a small ship, a capship or an installation.
**Syntax: ''String'', one of "top", "bottom", "front", "back", "left" or "right"}}

===$Ship_Icon:===
*The icon used in ship selection.
{{Table3610|
*Ship model is used by default to generate the image.}}
**Syntax: ''Filename''

===$Ship_Anim:===
*The glowing green grid animation used in ship selection.
{{Table3610|
*Ship model is used by default to generate the image.}}
**Syntax: '''''String''''', filename

===$Ship_Overhead:===
*The overhead view used in the weapons loadout.
{{Table3610|
*Ship model is used by default to generate the image.}}
**Syntax: '''''String''''', filename

{{Table371|
===$Briefing icon:===
*Defines if the ship has its own briefing icon information which overrides the standard briefing icon image
====+Regular:====
*Syntax: '''''<regular anim filename>'''''
====+Fade:====
*Syntax: '''''<fade anim filename>'''''
====+Highlight:====
*Syntax: '''''<highlight anim filename>'''''}}

{{Table371|
===$Briefing icon with cargo:===
*Defines if the ship has its own cargo briefing icon (which will only be an option if a ship icon is also specified)
====+Regular:====
*Syntax: '''''<regular anim filename>'''''
====+Fade:====
*Syntax: '''''<fade anim filename>'''''
====+Highlight:====
*Syntax: '''''<highlight anim filename>'''''}}

{{Table371|
===$Briefing wing icon:===
*Defines if the ship has its own wing briefing icon (which will only be an option if a ship icon is also specified)
====+Regular:====
*Syntax: '''''<regular anim filename>'''''
====+Fade:====
*Syntax: '''''<fade anim filename>'''''
====+Highlight:====
*Syntax: '''''<highlight anim filename>'''''}}

{{Table371|
===$Briefing wing icon with cargo:===
*Defines if the ship has its own wing-with-cargo briefing icon (which will only be an option if a ship icon is also specified)
====+Regular:====
*Syntax: '''''<regular anim filename>'''''
====+Fade:====
*Syntax: '''''<fade anim filename>'''''
====+Highlight:====
*Syntax: '''''<highlight anim filename>'''''}}

===$Score:===
*Points awarded for destroying the ship
*Syntax: '''''Float'''''

===Customized Thruster Effects===
{{Table3611|
*Defines the texture of the modeled thruster effect cone
*'''$Thruster Normal Flame:'''
**Syntax: '''''String''''', filename
*Defines the texture of the modeled thruster effect cone with afterburners lit
*'''$Thruster Afterburner Flame:'''
**Syntax: '''''String''''', filename}}
{{Table3610|
*'''Defines the primary thruster glow - the one visible only from behind'''
**'''$Thruster Bitmap 1:'''
***Defines the effect for the standard drives. Overrides [[Species_defs.tbl]] line '''+Normal:''' under the '''$Thrustglows:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster Bitmap 1a:'''
***Defines the effect for the afterburner. Overrides [[Species_defs.tbl]] line '''+Afterburner:''' under the '''$Thrustglows:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster01 Radius factor:'''
***Defines the radius multiplier
***Syntax: '''''Float'''''
*'''Defines the secondary glow type-effect for thrusters - the feathery trail like haze behind the main glow'''
**'''$Thruster Bitmap 2:'''
***Defines the effect for the standard drives. Overrides [[Species_defs.tbl]] line '''+Sec_Normal:''' under the '''$ThrustAnims:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster Bitmap 2a:'''
***Defines the effect for the afterburner. Overrides [[Species_defs.tbl]] line '''+Sec_Afterburn:''' under the '''$ThrustAnims:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster02 Radius factor:'''
***Defines the radius multiplier
***Syntax: '''''Float'''''
**'''$Thruster02 Length factor:'''
***Defines the length multiplier for the trail type (secondary) glowpoint thrusters
***Replaces the older '''$Thruster01 Length factor:'''
***Syntax: '''''Float'''''
*'''Defines the tertiary glow type-effect for thrusters - the one visible from all directions'''
**NOTE: The rotation of this effect is jittered, which can look quite bad with certain types of effects.
**'''$Thruster Bitmap 3:'''
***Defines the effect for the standard drives. Overrides [[Species_defs.tbl]] line '''+Ter_Normal:''' under the '''$ThrustAnims:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster Bitmap 3a:'''
***Defines the effect for the afterburner. Overrides [[Species_defs.tbl]] line '''+Ter_Afterburn:''' under the '''$ThrustAnims:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster03 Radius factor:'''
***Defines the radius multiplier
***Syntax: '''''Float'''''}}
{{Table3613|
*'''Defines the distortion effect for thrusters'''
**'''$Thruster Bitmap Distortion:'''
***Defines name of normal thruster distortion envelope animation. Overrides [[Species_defs.tbl]] line '''+Dist_Normal:''' under the '''$ThrustAnims:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster Bitmap Distortion a:'''
***Defines name of afterburner thruster distortion envelope animation. Overrides [[Species_defs.tbl]] line '''+Dist_Afterburn:''' under the '''$ThrustAnims:''' entry.
***Syntax: '''''String''''', filename
**'''$Thruster Distortion Radius factor:'''
***Defines the radius multiplier
***Syntax: '''''Float'''''
**'''$Thruster Distortion Length factor:'''
***Defines the length multiplier for the thruster distortion
***Syntax: '''''Float'''''
**'''$Thruster Distortion:'''
***Defines whether the distortion effect is rendered for this ship.
***Syntax: '''''Bool'''''}}
{{Table373|
*'''$Thruster Glow Noise Mult:'''
**A multiplier for how much noise is applied to the thruster glow radius. A value of 0 causes the radius to remain perfectly steady and values higher than 1 cause the radius to fluctuate more than the default.
** Defaults to 1.0.
**Syntax: '''''Float'''''
}}

===$Thruster Particles:===
{{Table3610|
*Defines the alternative particle thruster
*'''$Thruster Particle Bitmap:''' OR '''$Afterburner Particle Bitmap:'''
**Name of the animation used for particle thrusters, up to '''three''' can be defined for both '''standard''' thrusters and '''afterburners''' (6 in total). Afterburner particles require at least 1 existing particle thruster entry.
**Syntax: '''''String''''', filename
*'''$Min Radius:'''
**Defines the minimum radius of new particles
**Syntax: '''''Float''''', meters
*'''$Max Radius:'''
**Defines the maximum radius of new particles
**Syntax: '''''Float''''', meters
*'''$Min Created:'''
**Defines the minimum amount of particles created
**Syntax: '''''Float'''''
*'''$Max Created:'''
**Defines the maximum amount of particles created
**Syntax: '''''Float'''''
*'''$Variance:'''
**Value that describes the randomness of particle generation, values close to 0 will cause particles to spew very close to the thrusters normal while values close 1 will cause some particles to be spewed even to opposite direction
**Syntax: '''''Float'''''}}

===$Stealth:===
*Defines: Ship behaves as a stealth-ship: non-targettable, and not on radar.
{{Table3610|
This field is [[deprecated]], and mods using 3.6.8 and above should use the "stealth" flag.}}

===$Max Decals:===
{{Table3610|
*Defines: Maximum number of weapon decals on a ship
*Syntax: '''''Integer''''', maximum number of decals on ship
**Default: 50 for anything below cruiser size, 100 for anything below superdestroyer/installation size, 300 for anything above destroyer size, 10 for everything else.}}
{{Table3613|
*Feature disabled. Parsing retained to maintain compatibility}}

===$Trail:===
*These are the origins of the white contrails that appear in the nebula missions. Ship may have multiple trails.
{{Table3611|
*'''+ClearAll'''
**Clears all existing trail data from the ship}}
====+Offset:====
*The position of the contrail's head
*Syntax: '''''Vector''''', three '''floats''', x, y and z values respectively, relative to the center point of the model
====+Start Width:====
*The width of the contrail's head
*Syntax: '''''Float''''', meters
====+End Width:====
*The width of the contrail's tail
*Syntax: '''''Float''''', meters
====+Start Alpha:====
*The opacity of the contrail's head
*Syntax: '''''Float''''', value between 0 and 1
====+End Alpha:====
*The opacity of the contrail's tail
*Syntax: '''''Float''''', value between 0 and 1
====+Max Life:====
*How long the contrail remains
*Syntax: '''''Float'''''', seconds
====+Spew Time:====
*Syntax: '''''Integer'''''
====+Bitmap:====
*The image to use for the contrail.
*Syntax: '''''String''''', filename
{{Table3611|
====+Faded Out Sections:====
*Defines the number of the trail sections from the leading edge that are gradually faded away.}}

===$Thruster:===
{{Table3610|
*Defines maneuvering thrusters. Ship may have multiple $Thrusters defined.
*'''+Index:'''
**Defines the index number of the manoeuvring thruster defined in this entry
**Syntax: '''''Integer'''''
*'''+Used For:'''
**Defines the maneuver that triggers the maneuvering thruster
**List of maneuvers: Bank right, Bank left, Pitch up, Pitch down, Roll right, Roll left, Slide right, Slide left, Slide up, Slide down, Forward, Reverse
**Syntax: '''''String, String'''''
*'''+Position:'''
**Defines thruster location
**Syntax: ( '''''Float''''' '''''Float''''' '''''Float''''' ), position from the ships center point, x, y, z axis respectively
*'''+Normal:'''
**Defines the direction where the thruster points to
**Syntax: ( '''''Float''''' '''''Float''''' '''''Float''''' ), direction of the thrusters normal, x, y, z axis respectively
*'''+Texture:'''
**Defines the graphic that will be used for trail, rendered like beams
**Syntax: '''''String''''', filename
*'''+Radius:'''
**Defines the radius of cylinder
**Syntax: '''''Float''''', meters
*'''+Length:'''
**Defines the length of thruster trail
**Syntax: '''''Float''''', meters
*'''+StartSnd:'''
**Defines the sound played when the thruster is started
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+LoopSnd:'''
**Defines the sound played when the thruster is continuously used
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+StopSnd:'''
**Defines the sound played when the thruster is shutting down
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$Radar Image 2D:===
{{Table3611|
*Defines the bitmap used to represent the ship on the radar screen.
*Syntax: '''''Filename'''''}}
{{Table3615|
*'''$Radar Color Image 2D:'''
**Defines the color bitmap used to represent the ship on the radar screen.
**Syntax: '''''Filename'''''}}
{{Table3611|
*'''$Radar Image Size:'''
**Defines the size of the bitmap on the radar screen (length of the longer dimension)
**Syntax: '''''Integer'''''
*'''$3D Radar Blip Size Multiplier:'''
**Defines the multiplier used for blip size on the 3D radar.
**Syntax: '''''Float'''''}}

===$Glowpoint overrides:===
{{Table373|
*Creates a point that casts light onto ships and objects with the source being a glowpoint defined in the model file.
*Syntax: '''''( "String:Integer" )'''''
*String refers to name in [[glowpoints.tbl]]
*Essentially, [Name_of_glowpoint_override_in_glowpoints.tbl]:[Bank_in_POF]. If there is no override entry then the game will not generate a light. If you have multiple banks that use the same override, use a comma if they are not in order (2,4,7) and use a dash if they are in order (3-5 yields 3, 4, and 5).
**Example: '''$Glowpoint overrides: ( "teal_glow_10:1" "red_glow:2,3" "white_glow_10:4" "red_glow_10:5" "green_glow_10:6")'''
}}

===$Ship IFF Colors:===
{{Table3611|
*Defines the alternate color for the ship. Affects both the targeting brackets as well as the radar screen.
*'''+Seen By:'''
**Defines the IFF actually viewing the object (most often 'Friendly')
**Syntax: '''''String''''', name of an IFF class.
*'''+When IFF Is:'''
**Defines the IFF which the ship has to have for its color to be altered.
**Syntax: '''''String''''', name of an IFF class.
*'''+As Color:'''
**Defines the new color of the ship's targeting brackets and radar blip
**Syntax: '''''Integer list''''', red, blue and green respectively}}

===$Target Priority Groups:===
{{Table3611|
*Defines into which target priority groups the ship belongs to
*Syntax: '''''String list''''', names of the targeting groups
*'''+Override'''
**Overrides the ships existing groupings}}

===$EMP Resistance Modifier:===
{{Table3611|
*Defines the ships EMP resistance modifier:
*Syntax: '''''Float'''''}}

===$Piercing Damage Draw Limit:===
{{Table3611|
*Defines the maximum percentage of hitpoints ship has before piercing effects are enabled
*Syntax: '''''Float'''''
**Example: '''10''', sets the limit to 10%}}

===$Path Metadata:===
{{Table3613|
*Allows definition of extra metadata
*Syntax: '''''String''''', name of the path as defined in the ship POF file.
**Example: '''$Path Metadata: $Bay01'''
====+departure rvec:====
When using this path to depart via fighterbay, the departing ship will rotate to align itself with this rvec (so the right side of the ship is pointing in this direction). Only affects paths used to depart via fighterbay.
====+arrive speed multiplier:====
{{Table373|
*Modifies the speed of ships arriving from a fighterbay using this path. See [[Ai_profiles.tbl#.24bay_arrive_speed_multiplier:]] for details.
**Syntax: '''''Float'''''
}}
====+depart speed multiplier:====
{{Table373|
*Modifies the speed of ships departing to a fighterbay using this path. See [[Ai_profiles.tbl#.24bay_depart_speed_multiplier:]] for details.
**Syntax: '''''Float'''''
}}
}}

===[[Subsystem]]<nowiki>:</nowiki>===
:''Main article: [[Subsystem]]''

==Ships.tbl flags==

==="no_collide"===
*Defines ship as non-collideable, ie. everything will go through it

==="player_ship"===
*Makes it possible for the player to fly the ship

==="default_player_ship"===
*Makes this ship as a default part of the loadout options in FRED

----

===Ship Type===
*Flags in this section are used to define the type of the ship
*Use only one '''ship type''' flag per table entry
{{Table3610|
*New ship types can be defined in [[objecttypes.tbl]]}}

===="repair_rearm"====
*Alternate name for "support"

===="support"====
*Defines the ship as repair and rearm vessel and sets AI behaviour accordingly
*Only one such vessel can be defined per species

===="cargo"====
*Defines ship as a cargo crate and also sets the AI behaviour
*In FS1/FS2 ships that are marked with this flag cannot accept any player orders

===="fighter"====
*Defines ship as a fighter and also sets the AI behaviour
*In FS1/FS2 only ships flagged as fighters or bombers can accept the full set of player orders

===="bomber"====
*Defines ship as a bomber and also sets the AI behaviour
*In FS1/FS2 only ships flagged as fighters or bombers can accept the full set of player orders

===="transport"====
*Defines ship as a transport and also sets the AI behaviour

===="freighter"====
*Defines ship as a freighter and also sets the AI behaviour

===="capital"====
*Defines ship as a capital ship and also sets the AI behaviour

===="supercap"====
*Alternate name for "super cap"

===="super cap"====
*Defines ship as a super capital ship and also sets the AI behaviour

===="drydock"====
*Defines ship as a drydock and also sets the AI behaviour

===="cruiser"====
*Defines ship as a cruiser and also sets the AI behaviour

===="navbuoy"====
*Defines ship as a navbuoy and also sets the AI behaviour
*In FS1/FS2 ships that are marked with this flag cannot accept any player orders

===="sentrygun"====
*Alternate name for "sentry gun"

===="sentry gun"====
*Defines ship as a sentrygun and also sets the AI behaviour
*In FS1/FS2 ships that are marked with this flag cannot accept any player orders

===="escapepod"====
*Alternate name for "escape pod"

===="escape pod"====
*Defines ship as a escapepod and also sets the AI behaviour
*In FS1/FS2 ships that are marked with this flag cannot accept any player orders

===="corvette"====
*Defines ship as a corvette and also sets the AI behaviour

===="gas miner"====
*Defines ship as a gas miner and also sets the AI behaviour

===="awacs"====
*Defines ship as a AWACS and also sets the AI behaviour

===="knossos"====
*Alternate name for the "Knossos device"

===="knossos device"====
*Defines ship as a Knossos and also sets the AI behaviour
*In FS1/FS2 ships that are marked with this flag cannot accept any player orders

===="stealth"====
{{Table3610|
*Defines ship as a stealth-ship: non-targettable, and not on radar.}}

===="no type"====
*Does ???

----

==="ship copy"===
*Defines the ship as a copy of another model

==="in tech database"===
*Includes ships description to the tech database from the beginning of the campaign

==="in tech database multi"===
*Includes the ship to multiplayer tech database

==="dont collide invisible"===
*Defines invisible textures as non-collideable (For example, a hangar entrace)

==="big damage"===
*Limits the damage made to the ship by non-huge weapons.

==="no_fred"===
*Ship will not appear in FRED.

==="ballistic primaries"===
{{Table3610|
*Enables the ship to use ballistic primaries
*No longer needed, game handles it automatically}}

==="flash"===
{{Table3610|
*Makes a flash when a ship dies}}

==="surface shields"===
{{Table3610|
*Shots that impact the hull are applied to shields, regardless of if the ship has a shield mesh.}}

==="show ship"===
{{Table3610|
*Enable rendering the ship even when the ship is a player ship
*Will result in the player's ship model being rendered, when in cockpit mode}}

==="generate icon"===
{{Table3610|
*Creates a HUD icon from the model itself}}

==="gun convergence"===
{{Table3610|
*Enables ship to use the firing points' normals in defining the direction where the weapon fire}}

==="no thruster geometry noise"===
{{Table3611|
*Prevents noise from being added to the thruster effects geometry}}

==="intrinsic no shields"===
{{Table3611|
*Defines that ship has no shields by default, to allow mixing and matching shielded and unshielded craft in loadout}}

==="no primary linking"===
{{Table3611|
*Bypasses linked primaries while cycling. Does not block SEXPs/scripts that might be able to lock them, only the act of cycling for players and determing whether to link or not for AI.}}

==="no pain flash"===
{{Table3613|
*Prevents pain flash from being shown when ship is hit}}

==="dynamic primary linking"===
{{Table37|
*Allows this ship use the primary firepoint cycling code. With a key bind added in 3.6.13, you can toggle between various factorizations of primary firepoint groupings on a per-primary bank basis. So a 4-firepoint bank could cycle through all four firepoints firing together (1x4), each firepoint firing individually (4x1, all 4 firing over the timespan of the bank cooldown, so no change in damage over time, or DPS, occurs from retail behavior), or firing in pairs (2x2).}}

==="no ets"===
{{Table37|
Sets ship class to have no ETS}}

==="no lighting"===
{{Table3613|
Ship will not receive lighting calculations}}

==="auto spread shields"===
{{Table371|
Causes the ship's shield mesh (if any) to be ignored and a shield of a given thickness to be automatically projected around the ship's hull. Weapons will impact the ship's shields at a distance equal to the shield thickness defined in [[Ships.tbl#.2BAuto_Spread:|#.2BAuto_Spread:]], but not before the weapon itself has travelled at least a distance equal to that. Note that impact effects normally projected onto the shield mesh will not work.}}

==="model point shields"===
{{Table371|
Instead of the standard 4 shield quadrants, the ship uses an arbitrary number of shield sections which must have been defined in the model file, see [[Model Point Shields]]. If used on a player ship, you must also define [[Ships.tbl#.24Model_Point_Shield_Controls:|#.24Model_Point_Shield_Controls:]] to allow the shield augmentation controls to be used.}}

==Player Ship Precedence==
*Syntax: ( '''''"String" "String"''''')
===Example===

<pre>
$Player Ship Precedence: (
"GTF Ulysses"
"GTF Hercules"
"GTB Medusa"
"GTB Ursa" )
</pre>

==Sample==

<pre>
#Default Player Ship

$Name: GTF Ulysses

#End

#Engine Wash Info

$Name: Default
$Angle: 10.0
$Radius Mult: 1.2
$Length: 400
$Intensity: 1.0

#End

#Ship Classes
$Name: GTF Ulysses
$Short name: TFight
$Species: Terran
+Type: XSTR("Space Superiority", -1)
+Maneuverability: XSTR("Excellent", -1)
+Armor: XSTR("Light", -1
+Manufacturer: XSTR("Triton / Mekhu", -1)
+Description: XSTR( " ", -1)
$end_multi_text
+Tech Description: XSTR("Descriptive text", -1)
$end_multi_text
+Length: 16 m
+Gun Mounts: 4
+Missile Banks: 1
$POF File: fighter01.pof
$Detail Distance: (0, 80, 300, 900)
$ND: 42 42 244
$Show Damage: YES
$Density: 1
$Damp: 0.1
$Rotdamp: 0.35
$Max Velocity: 0.0, 0.0, 70.0
$Rotation Time: 3.0, 2.6, 5.0
$Rear Velocity: 0.0
$Forward Accel: 2.0
$Forward Decel: 1.5
$Slide Accel: 0.0
$Slide Decel: 0.0
$Expl Inner Rad: 25.0
$Expl Outer Rad: 55.0
$Expl Damage: 15.0
$Expl Blast: 1000.0
$Expl Propagates: NO
$Shockwave Speed: 0.0
$Allowed PBanks: ( "Subach HL-7" "Prometheus R")
$Allowed Dogfight PBanks: ( "Subach HL-D" "Prometheus D" )
$Default PBanks: ( "Subach HL-7" "Prometheus R" )
$Allowed SBanks: ( "Rockeye" "Tempest" )
$Allowed Dogfight SBanks: ( "Tempest D" "Hornet D" )
$Default SBanks: ( "Harpoon" )
$SBank Capacity: ( 40 )
$Shields: 380
$Shield Color: 100 100 255
$Power Output: 2.0
$Max Oclk Speed: 94.0
$Max Weapon Eng: 80.0
$Hitpoints: 180
$Flags: ( "player_ship"
"default_player_ship"
"fighter"
"in tech database")
$AI Class: Captain
$Afterburner: YES
+Aburn Max Vel: 0.0, 0.0, 150.0
+Aburn For accel: 0.7
+Aburn Fuel: 300.0
+Aburn Burn Rate: 50.0
+Aburn Rec Rate: 25.0
$Countermeasures: 25
$Scan Time: 2000
$EngineSnd: 128
$Closeup_Pos: 0.0, 0.0, -22
$Closeup_Zoom: 0.5
$Shield_Icon: shield-f01
$Ship_Icon: iconfighter01
$Ship_Anim: ssfighter01
$Ship_Overhead: loadfighter01
$Score: 8
$Trail:
+Offset: -7.75 -2.8 0.75
+Start Width: 0.25
+End Width: 0.05
+Start Alpha: 1.0
+End Alpha: 0.0
+Max Life: 1.0
+Spew Time: 60
+Bitmap: Contrail01
$Trail:
+Offset: 7.75 -2.8 0.75
+Start Width: 0.25
+End Width: 0.05
+Start Alpha: 1.0
+End Alpha: 0.0
+Max Life: 1.0
+Spew Time: 60
+Bitmap: Contrail01
$Subsystem: communication, 10, 0
$Subsystem: navigation, 10, 0
$Subsystem: weapons, 20, 0
$Subsystem: sensors, 10, 0
$Subsystem: engines, 35, 0

#End

$Player Ship Precedence: (
"GTF Ulysses")
</pre>

[[Category:Tables]]

Particle Effects

2016-09-04T09:03:03Z

M!m: Add sphere type

Benchmarking

2016-08-09T13:54:37Z

M!m: Add -noninteractive to other options section

FSO has support for running automated performance benchmarks using the '''-benchmark_mode''' command line. This option currently has the following effects:

* The pilot selection is automatically accepted (make sure there is a pilot to accept)
* FSO will quit after running one mission

This feature can be combined with '''-profile_frame_time''' to gather detailed performance data without requiring any interaction while running the test.

==-profile_frame_time==
When FSO is started with this option then it will write information about the frame times to a file called ''profiling.csv''. Each line contains the system time and the frametime of each rendered frame in the format ''<system time>;<frametime>''. Both time values are measured in microseconds. ''system time'' is measured from an arbitrary point in the past. To get consistent results the first time value should be substracted from all time values. The first two frames are usually very long because the timer is set at engine startup so you might want to exclude those from your data. [https://gist.github.com/asarium/2ce04d7d2ac01b40e66a This script] uses python and numpy to generate two graphs from two sets of data which can be used to compare two different versions of the engine.

==Missions==
To actually run a mission you could use the commandline option '''-start_mission <mission>''' which will start the specified mission after entering the main hall. To keep the tests non interactive the started mission should be a cutscene which automatically ends when the end is reached. Here is a list of mods that contain such missions:
* Blue Planet Complete
** '''bp2-17.fs2''': Icarus cutscene of War in Heaven. A very demanding mission which is great for testing performance.
** '''bp2-00.fs2''': Intro cutscene of War in Heaven. Also great for performance testing.

==Other options==
* '''-nomovies''': Can be used to disable playback of movies which speeds up game startup.
* '''-no_unfocused_pause''': Disables automatic pausing when the FSO window isn't focused. Can be used to use another application while the benchmark is running.
* '''-noninteractive''': Disables all dialogs or other things that may require interaction. This makes sure that FSO exits in a finite time. If it doesn't please create an issue on the GitHub bug tracker.

Command-Line Reference

2016-08-08T16:06:04Z

M!m: Add documentation for -noninteractive

{{TableVersionGit|2016-28-07|b40631e}}

Command-Line Flags (also called Command-Line Parameters) are optional flags passed to the FSO executable, and generally enables one or more features added to the FS2 Open engine. These flags are accessed conveniently through an [[FSO Launcher]]. To have FSO list all available flags, use any one of the following: [[Command-Line_Reference#-help|-help]], [[Command-Line_Reference#-help|--help]], [[Command-Line_Reference#-help|-h]], or [[Command-Line_Reference#-help|-?]].



===Graphics===
====-spec====
'''"Enable Specular"'''

Only polygons mapped with textures for which a shinemap exists will receive specular mapping; no attempt is made to generate spec maps where they do not exist. Specular maps are specified with the base map name plus "-shine" (i.e. TCov3A-shine.pcx).
{{Table3615|
*This feature is on by default, use launcher option Disable Specular or if necessary to manually disable enter the flag -nospec}}

====-env====
'''"Enable Environment maps"'''

It only works if [[Command-Line_Reference#-spec|-spec]] is also set. Environment mapping intensity will be determined from the shine map too (see [[Texturing]] for more info). [[Installing FreeSpace 2 Open#Video setup|See Video setup.]]
{{Table3615|
*This feature is on by default, use launcher option Disable Environment Maps or if necessary to manually disable enter the flag -noenv }}

====-glow====
'''"Enable Glowmaps"'''

Only polygons mapped with textures for which a glowmap exists will be glowmapped. Glow maps are specified with the base map name plus "-glow" (i.e. TCov4A-glow.pcx)
{{Table3615|
*This feature is on by default, use launcher option Disable Glow Maps or if necessary to manually disable enter the flag -noglow }}

====-nomotiondebris====
'''"Disable motion debris"'''

====-noscalevid====
"Disable scale-to-window for Movies"

Disables fullscreen scaling of video clips.

====-missile_lighting====
'''"Apply Lighting to Missiles"'''

====-normal====
'''"Enable Normal Maps"'''

Normal maps require GLSL rendering, (see [[OpenGL_Shaders_(GLSL)|OpenGL Shaders (GLSL)]] for further info). It needs auxiliary normal maps (the same name of the base map plus "-normal"). DXT5_NM DDS format is needed. (Technical note: DXT5 will work, since only the GREEN and ALPHA channels are read by the current shader system. One direction of lines goes into the GREEN channel, the other direction goes into the ALPHA channel. RED and BLUE can be either base gray (#808080) or black. Usual practice is after creating the DXT5_NM, copy the RED channel to the ALPHA channel, black out the RED and BLUE an then save as either a DXT5 or u8888 (uncompressed) DDS file.)
{{Table3615|
*This feature is on by default, use launcher option Disable Normal Maps or if necessary to manually disable enter the flag -nonormal }}

====-height====
Enables height maps (parallax mapping). It only works if [[Command-Line_Reference#-normal|-normal]] is also set. It also needs GLSL rendering, (see [[OpenGL_Shaders_(GLSL)|OpenGL Shaders (GLSL)]] for further info). It needs auxiliary height maps (with the same name than base map plus "-height").
{{Table3615|
*This feature is on by default. To manually disable, enter the flag -noheight}}

====-post_process====
'''"Enable Post Processing"'''

enables the use (if present) of post-processing effects as defined by the post_process.tbl. Bloom usage has an additional cmdline option for setting it's value, most post processing effects are achieved in mission per the mission designer or can be enabled globally in the table.

====-soft_particles====
'''"Enable soft particles"'''

====-3dshockwave====
'''"Enable 3D Shockwaves"'''

This only has any effect when both a 2d and 3d shockwave effect are present, otherwise the only available effect is used (2d shockwave is defined by effects/shockwave01.eff or .ani, and 3d shockwave by models/shockwave.pof)

Note that 3d shockwaves are usually flat discs, that FSO scales up. The animated 2d billboards used by 2d shockwaves with the addition of [[Command-Line Reference#-soft_particles|soft particles]], may look better when intersecting with models (which shockwaves often do). Use at your discretion.

====-fxaa====
'''"Enable FXAA antialiasing"'''

Enables the FXAA postprocessing stage. Further information can be found here: http://www.hard-light.net/forums/index.php?topic=76145.0

====-nolightshafts====
'''"Disable lightshafts"'''

Disables Lightshafts even if a mission designer enables them via SEXP in a mission. This was previously documented as -flightshaftsoff but appears to have been changed to -nolightshafts for consistency before -flightshaftsoff was ever used in a released build.

====-enable_shadows====
{{table373|
'''"Enable shadows"'''

Enables shadows where supported by the OpenGL version provided by the user's GPU. -shadow_quality can be used to control the quality level.
{{note|Currently doesn't support shadows for cockpits and show ship.}}
}}

====-shadow_quality====
{{table373|
'''"Set shadows quality"'''

Valid ranges are 0 to 2 with 2 being the default.

* 0 disables shadows (so there's no point in setting it!)
* 1 uses 512x512 shadow maps (lower quality)
* 2 uses 1024x1024 shadow maps (higher quality)

Currently this requires -enable_shadows to be set, or it has no effect.
}}

===Game Speed===
====-img2dds====
'''"Compress non-compressed images"'''

Converts all images to DDS (compressed) format. Decreases memory usage but potentially reduces image quality.

====-no_vsync====
'''"Disable vertical sync"'''

====-no_fps_capping====
'''"Don't limit frames-per-second"'''

====-cache_bitmaps====
'''"Cache bitmaps between missions"'''

Will ideally reduce the load-time from one mission to another.

===HUD===
====-dualscanlines====
'''"Another Pair of Scanning Lines"'''

Adds a second pair of scanning lines to the target window when scanning an object.

====-targetinfo====
'''"Enable Info next to Target"'''

Displays target info, such as name and class, beside the targeted object.

====-orbradar====
'''"Enables 3D radar"'''

An Orb style 3D radar will replace the standard 2D version.

====-rearm_timer====
'''"Enable Rearm/Repair Completion Timer"'''

Displays time remaining until rearm and repair from a support ship is complete.

====-ballistic_gauge====
'''"Enable the analog Ballistic Ammo gauge"'''

Adds an ammo gauge to the HUD when armed with a ballistic weapon.

===Gameplay===
====-ship_choice_3d====
'''"Use Models for Ship Selection"'''

Uses ship models in ship selection window. It completely disables the standard ANI interface in this screen. 
Some mods need a compulsory use of this flag because they don't have available animations for their ships. In this situation, and if it is not used, the game will probably crash to desktop in the ship selection window.

====-weapon_choice_3d====
'''"Use Models for Weapon Selection"'''

Uses weapon models in weapon loadout window for secondary weapons (missiles and bombs). It completely disables the standard ANI interface in this screen. 
Some mods need a compulsory use of this flag because they don't have available animations for their secondary weapons. In this situation, and if it is not used, the game will probably crash to desktop in the weapon loadout window.

====-3dwarp====
'''"Enable 3D Warp"'''

Use full geometry for the subspace warp effect.

====-warp_flash====
'''"Enable Flash upon Warp"'''

Enable a flash at warp in and warp out.

====-no_ap_interrupt====
'''"Disable Interrupting of AutoPilot"'''

Tells the game to not allow players to interrupt an autopilot already-in-progress.

====-stretch_menu====
'''"Stretch interface to fill screen"'''

Scales the interface to fill the screen without preserving the aspect ratio. Omit this to keep the aspect ratio, adding black bars where appropriate.

===Audio===
====-snd_preload====
'''"Preload mission game sounds"'''

Useful in preventing game stuttering when sounds are played for the first time.

====-nosound====
'''"Disable Sound and Music"'''

====-nomusic====
'''"Disables Music"'''

===Launcher===
====-portable_mode====
'''"Store config in portable location"'''

Uses the root directory of FSO for storing pilot and config files. The current launcher does not have proper support for this yet so you need to manually copy the fs2_open.ini from the original config directory to your FreeSpace Root directory.

===Multiplayer===
====-standalone====
'''"Run as Stand Alone Server"'''

Creates a standalone multi-player server.

====-startgame====
'''"Skip Mainhall and Start Hosting"'''

Once you launch and choose a pilot within the game, you will immediately have begun to host a game. This can be used in conjunction with several options to customize the game you create: -closed, -restricted, -password, -gamename, -allowabove, and -allowbelow. -startgame has no effect when -standalone is used.

See related: [[Command-Line_Reference#-closed|-closed]] [[Command-Line_Reference#-restricted|-restricted]] [[Command-Line_Reference#-password|-password]] [[Command-Line_Reference#-gamename|-gamename]] [[Command-Line_Reference#-allowabove|-allowabove]] [[Command-Line_Reference#-allowbelow|-allowbelow]]

====-closed====
'''"Start Hosted Server as Closed"'''

Hosts a new game in a closed state, where no one can join until the in-game "Close" button is cleared. This only works when used in conjunction with -startgame. Cannot be used in conjunction with -restricted or -password.

See related: [[Command-Line_Reference#-startgame|-startgame]] [[Command-Line_Reference#-restricted|-restricted]] [[Command-Line_Reference#-password|-password]]

====-restricted====
'''"Host Confirms Join requests"'''

Hosts a new game in a restricted state. The host is presented with option to accept or deny each client's request to join the game. This only works when used in conjunction with -startgame. Cannot be used in conjunction with -closed or -password.

See related: [[Command-Line_Reference#-startgame|-startgame]] [[Command-Line_Reference#-closed|-closed]] [[Command-Line_Reference#-password|-password]]

====-multilog====
Creates a log file with a summary of packets sent and received in multiplayer games. The file is saved as \data\multi.log within the active mod folder—or with main data folder if no mod is active.

====-clientdamage====
{{Note| This feature is not available in current builds.}}

====-mpnoreturn====
'''"Disables Flight Deck option"'''

Disables return to the flight deck screen after a mission completes.

===Troubleshooting===
====-nohtl====
'''"Software Mode (very slow)"'''
{{Warning| Enabling this will significantly reduce performance.}}
Reverts to software rendering mode.

====-no_set_gamma====
'''"Disable Setting of Gamma"'''

Disables the gamma settings in the options screen.

====-nomovies====
'''"Disable Video Playback"'''

Disables all video playback.

====-noparseerrors====
'''"Disable Parsing Errors"'''

Disables some parsing warnings and makes other parse errors non-fatal. Do not rely on this when creating new tables. The errors are there for a reason.

====-parse_cmdline_only====
'''"Parse Command Line Only"'''

Parse only the application command line settings, and ignore any that may have been set in the on-disk data/cmdline_fso.cfg or per-user cmdline_fso.cfg (on Linux/Mac)

====-safeloading====
Loads missions the old way. Typically safer, but slower.
{{Note| This parameter was removed as of the July 5, 2011 nightly build.}}

====-query_speech====
'''"Does this build have Speech?"'''

Determines if the current build includes text-to-speech.

====-novbo====
'''"Disable OpenGL VBO"'''

====-noibx====
'''"Don't use cached index buffers (IBX)"'''

Disables IBX caching of model geometry data. This will dramatically increase load times, but will help troubleshoot a model if one is working incorrectly.

====-loadallweps====
'''"Load all weapons, even those not used"'''

====-disable_fbo====
'''"Disable OpenGL RenderTargets"'''

====-disable_pbo====
'''"Disable OpenGL Pixel Buffer Objects"'''

Disables the use of Pixel Buffer Objects (PBO) which may cause certain OpenGL operations to perform slower. Note PBO's were only used at three places in FSO anyway so it's *probably* not going to have a noticeable effect.

May be required to workaround issues in certain versions of Linux's Mesa drivers for Intel integrated graphics cards where crashes occur in the mainhall (i.e. whenever a popup occurs). Distros that seem to have this problem presently include Ubuntu 13.10 and openSUSE 13.1.
{{Table371|
*This feature is present to work around a bug in Linux's Mesa drivers for Intel integrated graphics cards}}

====-no_glsl====
'''"Disable GLSL (shader) Support"'''

Disables the use of GLSL rendering (OpenGL shaders). The game will revert to legacy fixed render pipeline. Please note that Normal and Height map effects will be unavailable.

====-disable_glsl_model====
'''"Don't use shaders for model rendering"'''

====-ati_swap====
'''"Fix Color issues on some ATI cards"'''

[http://scp.indiegames.us/mantis/view.php?id=1669 Mantis #1669] is what led to this flag's creation.

====-no_3d_sound====
'''"Use only 2D/stereo for sound effects"'''

====-disable_di_mouse====
'''"Disables the DirectInput mouse code for FSO on windows."'''

'''Windows Only''' Can make mouse movement smoother on certain machines.

====-mipmap====
'''"Enable mipmapping"'''

Causes for non-mipmapped textures to have mipmaps generated within the GPU on certain kind of texture formats, (IIRC, DDS formatted textures with a power of 2 size in both width and height). 
Since the use of already mipmapped DDS textures has become common, it has become deprecated.
The quality of the generated mipmaps depends on each GPU and used driver. It is normally used with [[Command-Line_Reference#-img2dds|-img2dds]] flag.

====-use_gldrawelements====
'''"Use glDrawElements instead of glDrawRangeElements"'''

Introduced as a means of switching to the slower OpenGL call glDrawElements, instead of glDrawRangeElements.
{{Table3614|
*This feature may resolve certain rendering problems where parts of models are not drawn on Linux drivers}}

====-keyboard_layout====
'''"Manually sets a keyboard layout"'''

A commandline parameter to set the keyboard layout as a string parameter.
{{Table3614|
*Currently the only valid string is "qwertz" (German) but French azerty may be added in future.}}

====-old_collision====
'''"Use old collision detection system"'''

Uses the old collision code instead of Swifty's new collision code introduced in the 'go_even_faster' project.

====-gl_finish====
'''"Fix input lag on AMD+Linux"'''
{{Table371|
This option adds a "glFinish()" call just prior to swapping buffers. It works around an issue with "recent" (HD 6000 & newer?) AMD cards using proprietary drivers on Linux. Be warned that enabling this may reduce framerate.
}}

Refer to [http://www.hard-light.net/forums/index.php?topic=88102.0 this thread] and [https://github.com/ValveSoftware/Source-1-Games/issues/765 Valve's bugtracker] for more details).

===Experimental===
====-ingame_join====
'''"Allows Ingame Joining"'''

Enables ingame joining in multiplayer. FIXME: Host option?

====-voicer====
'''"Voice Recognition"'''

Windows-only. Enables voice-recognition for wingmen commands. Must be specifically compiled into a build in order for it to be available; 3.6.10 final includes the feature. See [[Voice Recognition]] for more details.

====-fb_explosions====
'''"Enable Framebuffer Shockwaves"'''

===Development Tools===
====-fps====
'''"Show frames per second on HUD"'''

Displays current frames per second.

====-pos====
'''"Show Position of Camera"'''

Displays current position coordinates of camera.

====-window====
'''"Run in Window"'''

Runs the game in a window. No check to make sure that resolution is no higher than your desktop resolution, so be careful.

====-fullscreen_window====
'''"Run in Fullscreen Window"'''
{{Note| This feature is only available on Windows.}}

====-timerbar====
Displays a timing bar across the top of the screen. Timerbar format varies by build. This is a relic from the Volition development days, and is unmaintained.
{{Note| This parameter was removed as of the July 5, 2011 nightly build.}}

====-stats====
'''"Show Statistics"'''

Shows total and free physical memory, virtual memory and system pagefile.

====-coords====
'''"Show Coordinates"'''

Shows coordinates of the mouse cursor.

====-show_mem_usage====
'''"Show Memory Usage"'''

Shows detailed RAM usage based on file, handler and process usage and display on the left-center side of the screen during mission load and while in mission.

The meaning of the info displayed in the upper right corner of the HUD is:

'''DYN''' = dynamic memory, basically anything that's been allocated by the vm_* memory functions. This does NOT indicate total memory usage but does account for most of it.

'''POF''' = model memory, how much memory is being used by models (does not include textures)

'''C-BMP, BMP''' = bmpman memory, how much is used by the textures/images that are loaded. C-BMP means that you are using -cache_bitmaps and it will try to keep textures in memory between level loads and as the new level is loading it will keep what it needs and unload what it doesn't. Can greatly increase level loading speed, but does so at the cost of memory between level loads. This does not increase overall memory usage though, only during the loading screen. BMP means that it is not cached and all textures are unloaded from memory at the start of level load and all needed textures are then loaded from the disk again.

'''S-RAM''' = sound memory, how much is used by the sounds loaded in memory at the time. This counts static sounds only (from sounds.tbl, etc.) and not streaming sounds (music, voices, briefing stuff, etc).

'''V-RAM''' = approximate memory usage of video textures. This does not mean that your card has this much memory, and can report higher numbers that your card actually has memory. For OpenGL it also includes some of the geometry data, but this number does not reflect the total memory that your video card is using. It only reports how much data the game has purposefully loaded into API memory (meaning it could be in system memory, video card memory, or AGP memory).

''(It only works with debug builds, not with release builds).''

====-pofspew====
Reads all objects in the pof file of the selected mod, and creates an ibx cache file for each object in the data/cache folder for that mod. 
Details for each object are output to a pofspew.txt file created in the data folder. 
Otherwise, ibx files are created in game before each mission.

====-tablecrcs====
Is actually now (or should be) a typed reference rather than as a selection item. Takes 1 argument, usually a descriptive name.
Example usage: "-table_crcs MediaVPs" will create a table_crcs.csv file in the running mod (name can be separate of the mod selected) that allows for the validation of the tables used by that mod while on-line. The descriptive parameter given helps "allocate" that .csv file to the mod in question, and as such should closely or exactly match that mods name if possible.

====-missioncrcs====
Is actually now (or should be) a typed reference rather than as a selection item. Takes 1 argument, usually a descriptive name.
Example usage: "-mission_crcs MediaVPs" will create a mission_crcs.csv file in the running mod (name can be separate of the mod selected) that allows for the validation of the missions used by that mod while on-line. The descriptive parameter given helps "allocate" that .csv file to the mod in question, and as such should closely or exactly match that mods name if possible.

====-dis_collisions====
'''"Disable Collisions"'''

Disables all collisions.

====-dis_weapons====
'''"Disable Weapon Rendering"'''

Disables weapons rendering.

====-output_sexps====
This will make the FSO build spit out an html file that documents the supported SEXP's.

Just double click on sexps.html and it should open in your default web browser.

====-output_scripting====
This will make the FSO build spit out an html file that documents the supported scripting hooks and LUA libraries.

Just double click on scripting.html and it should open in your default web browser.

====-nograb====
Disables focus grabbing in a window.
{{Note| This feature is not available on Windows.}}

====-save_render_target====
'''"Save Render Targets to file"'''

====-debug_window====
'''"Display Debug Window"'''

Lists the fs2_open.log in (nearly)real-time generation.

====-verify_vps====
'''"Spew VP crcs to vp_crcs.txt"'''

Exports the CRC values of the VP files being loaded into a vp_crcs.txt file.

====-reparse_mainhall====
'''"Reparse mainhall.tbl when loading halls"'''

Mainhall.tbl will be reparsed every time a mainhall is loaded, as opposed to just once at game startup.

====-profile_frame_time====
'''"Profile engine subsystems"'''

Activates the frame profiling code. This presents a readout showing the current, minimum, maximum and average percentages of frametime a given section of code has taken up; this can be used to identify particular bottlenecks or measure the effectiveness of certain optimizations.

====-profile_write_file====
'''"Write profiling information to file"'''

This will write the frame times of each gameplay frame to the file 'profiling.csv' where each line is ''<time>;<frametime>''. Both times are measured in microseconds. ''time'' is measured from an arbitrary time in the past. To get consistent results the first ''time'' value should be substracted from all ''time'' values. The first two frames are usually very long because the timer is set at engine startup so you might want to exclude those from your data.

====-no_unfocused_pause====
'''"Don't pause if the window isn't focused"'''

When the FSO window looses focus it will not pause the game, useful for doing non-interactive test runs.

====-benchmark_mode====
'''"Puts the game into benchmark mode"'''
See [[Benchmarking]] for more information.

====-noninteractive====
'''"Disables interactive dialogs"'''
Disables all dialogs and chooses the default option when one would be displayed. Very useful for a standalone server on a headless system.

==Other==
The following options are not available as checkboxes in the launcher. Many require parameters, which follow the flag separated by a space. The prototype for use in this case is "-option argument"

===Lighting===
These factors can dramatically alter the atmosphere of the game. [[Sample Lighting Settings|This page]] has some sample lighting settings with screenshots.

====-ambient_factor====
This must be entered into the "Custom flags" field. This is a multiplier applied to the intensity of ambient lighting. Ambient light is lighting applied to all parts of a ship. FS2's standard value is 120. Try 75 for a good and realistic looking value. However, that is relative.

====-no_emissive_light====
By default, all ships in FS2 have a light generated on their own, it is more or less similar to a minimal amount of -ambient_factor. This feature was implemented to help the player seeing the ships over a black background. This flag disables this feature. Use it with a low -ambient_factor value to obtain an ultra-realistic dark looking.

====-spec_exp====
This must be used with the -spec command line parameter and must be entered into the "Custom flags" field. Adjusts the size of the shiny spot on ships. Higher number mean smaller spots. Default is 16. However, 11 is recommended. This is a relative value.

====-spec_point====
This must be used with the -spec command line parameter and must be entered into the
"Custom flags" field. Adjusts how much laser weapons contribute to specular highlights. Higher number mean greater contributions. Default is 1.0. However, 0.6 is recommended. This is a relative value.

====-spec_static====
This must be used with the -spec command line parameter and must be entered into the "Custom flags" field. Adjusts how much suns contribute to specular highlights. Higher numbers mean a greater contribution. Default is 1.0. However, is 0.8 recommended. This is a relative value.

====-spec_tube====
This must be used with the -spec command line parameter and must be entered into the "Custom flags" field. Adjusts how much Beam Weapons contribute to specular highlights. Higher numbers mean a greater contribution. Default is 1.0. However, 0.4 is recommended. This is a relative value.

====-ogl_spec====
Takes a numerical argument. This value changes the basic shininess of the specular light in OpenGL. A lower value reduces the overall intensity of the light making it broader and less powerful. A higher value makes it more focused and brighter. The default value is 80, and the usable range is 0 to 128 (clamped). The original default value was 60, but it was raised to behave more D3D like.

===Graphics===
====-bloom_intensity====
Requires -post_processing ("Enable Post Processing") command.
Default value is 75. Range is 0-200.

====-clipdist====
Changes the distance from the viewpoint for the near-clipping plane.

Takes one argument decimal specifying the distance to the near-clipping plane.

====-res====
Allows you to specify a resolution if the desired one cannot be set in the Launcher.
For example, -res 1920x1080 would run the game in 1920 x 1080 resolution. Since it requires an argument, it needs to be entered as a custom flag when using the Launcher. The "Run at specified resolution" option the Launcher gives is essentially this, but without being able to actually specify a resolution, it doesn't work.

====-center_res====
Specifies how much of the screen area should be utilized by menus, movies, the HUD, and various other 2D graphics. Intended for use with configurations with an extremely wide field of view, such as triple-monitor setups.

By default, if the screen resolution's aspect ratio is wider than 7:2, most 2D elements utilize only the center 3/10 of the screen area. This setting allows users to override this behavior to make better use of the center monitor. (The reason for using 3/10 rather than 1/3 is that many triple-monitor setups use bezel correction, which reduces the fraction of the screen area that the center monitor displays.)

For example, if the screen resolution is 6000x1080, then -center_res 1920x1080 will keep most 2D graphics in the center 1920x1080 area. This setting is automatically scaled to fit the screen resolution, so (assuming the resolution is still 6000x1080) -center_res 1280x720 is given, then that resolution is enlarged to 1920x1080.

====-fxaa_preset====
Requires both -post_processing and -fxaa. Can be used to adjust the FXAA quality and speed, 0 is fastest, 9 is highest quality. Default setting is 6.

===Gameplay===
====-start_mission====
'''"Skip the mainhall in jump right into the specified mission"'''

Jump into the mission specified by the filename. Only in effect on the first run. This will skip load of the mainhall and its other related things altogether.

====-mod====
Specifies in which folders inside FreeSpace 2 directory, the game looks for all the game data (models, missions, textures, tables, ...). Retail version only looks inside ''Freespace2/data/'' structure and ''Freespace2/vp archives''.

This flag allows installing several different mods that modify retail behavior, and switching between them without needing to erase files or having undesired cross effects. Each mod should be installed in its own folder.

It takes one argument string: the chain of names of the used directories. Comma (''',''') must be used as separator. In this way, '''-mod dir1,dir2,dir3,...,dirx''' causes the game to use the following directory precedence:

#Freespace2/dir1/
#Freespace2/dir2/
#Freespace2/dir3/
# ... (the rest of the typed directories) ...
#Freespace2/dirx/
#Freespace2/

This flag can be indirectly set, (and it is normally set), through Launcher MOD tab and [[mod.ini]] file.

Within the Launcher's MOD tab you can select one directory, (let's call it ''moddir''), so the flag is at least set to '''-mod moddir'''.
If ''Freespace2/moddir/[[mod.ini]]'' exists it will be used to modify the -mod flag, too.

For further details, see '''[[mod.ini]]'''

'''Data precedence'''

As already said, within the different directories, the data precedence is set by the specified order in the -mod flag. The lowest priority goes to the Freespace2 installation directory.

Inside each directory, data precedence is the following:

#Individual files located in ''Current_dir/data/'' subdir structure. See [[FS2_Data_Structure|FS2 Data Structure topic]] for deeper info about the different folders and contents this structure has.
#Files located inside vp archives. (These vp archives are "similar" to zip archives. They just contain other files and folders. Moreover, files have to be stored using the same ''data/'' structure used outside it). Vp archives are read in alphabetical order, so aaa.vp files have higher priority than aab.vp files and so on.

The highest priority file overrides the rest of them. In this way, if you have a ''Mission.fs2'' inside ''Freespace2/Pri1/data/missions/'' it doesn't matter that this ''Mission.fs2'' is also inside ''Freespace2/Pri1/aaa.vp'', ''Freespace2/Pri1/aab.vp'', ... or ''Freespace2/data/missions/''. This data precedence allows the user to quickly replace old files by corrected or enhanced ones adding them in a higher priority place.

'''Additional notes'''
# As derived from the explanation, the exact names for directories or vp archives are actually irrelevant. It only matters the directory order inside -mod flag argument and the alphabetical order for vp archives inside each used directory.
# This flag is also used by [[Portal:FRED|FRED]]. So if there is special mod info, (like backgrounds maps, ship models or whatever), it must be typed, (''Fred2_Open_r.exe -MOD whatever''), or FRED won't be able to use it. A special build of wxLauncher is able to configure FRED so that the -mod doesn't have to be done manually see [http://www.hard-light.net/forums/index.php?topic=67950.msg1387911#msg1387911 the forum post] for more details.
{{Table3612|As of 3.6.12 FRED now loads cmdline_fso.cfg just like FS does so FRED will use the same settings as FS including the -mod settings}}
# Be careful while typing the directory names in the flag argument or inside mod.ini files. The program doesn't check if the typed directories exist. If they do not exist, they are just ignored. No warnings, no errors, no messages at all.

{{Warning| '''Priority and Texture Formats'''

''Obsolete behavior - Until FS2_open v3.6.9.:''

FS2_Open can use several file formats in textures: [http://en.wikipedia.org/wiki/PCX PCX], [http://en.wikipedia.org/wiki/DirectDraw_Surface DDS], [http://en.wikipedia.org/wiki/JPG JPG] and [http://en.wikipedia.org/wiki/TGA TGA]. Make sure you keep the format when you update your texture. For example if you update the old ''TextureOfMyFighter.tga'', do not save it as ''TextureOfMyFighter.dds'' in a higher priority place, because there is a chance of the game loading the old one despite of all.

The reason to do this is that, loading process (including priorities) is applied firstly for a kind of textures (TGAs), then for another kind (JPGs), and so on. This behavior can lead to situation where your new, updated and higher priority placed texture is not read because the format of the older one.

''New behavior - From FS2_open v3.6.10. (including previous beta testing releases):''

The former issue has been fixed. Now texture format priority is only applied within the same location. In this ''strange'' situation it goes DDS -> TGA -> JPG -> PCX. Examples:
* ''/Freespace2/MyVp.vp>>>data/maps/MyTexture.dds'' is loaded instead of ''/Freespace2/MyVp.vp>>>data/maps/MyTexture.tga''.
* But your improved ''/Freespace2/data/maps/MyTexture.xxx'' will override them both despite of its format.
In this way, when you update any texture, you don't have to pay attention to its original format. Just place it in a higher priority place.

Nevertheless, global priority is kept between animated and static textures. Because of their management, animated textures (ANIs and EFFs) are looked for BEFORE static ones. In this way there's no way to update an animated texture with a static one (an obsolete ANI is always going to be loaded before the newer DDS version). The solution: use an updated EFF with just one frame.

}}

====-fov====
This flag allows the player to specify the ''vertical'' Field of View (FoV) angle, in radians, for the player eyepoint. The angle is measured across the full height of the viewing cone. The FoV angle is technically known as the Angle of View (AoV)

*Syntax: '''''float''''' Angle
*Valid Values: 0 to 2*Pi radians
*Default Value: 0.75 radians

{{Note|For peculiar reasons, the actual FoV/AoV used by the game will be the supplied value multiplied by 1.39626348.}}

The the FoV angle/AoV is what determines the relative zoom level of the main game camera. Smaller angles generally equal to higher zoom levels, while larger angles equal to lower zoom levels (down to the theoretical x0 magnification).

However, too small of an angle will have a squashed look on the edges of your screen, and too high of an angle will greatly stretch edges. It is recommended to change the AoV, as FS2's default AoV has some perspective distortion at the screen edges (the default AoV is too high).

A natural looking (as if you where physically in the cockpit) AoV depends on the distance the player's actual eyes are away from the screen: the further away from the screen, the smaller the AoV should be, and vice versa. "Ergonomic" distances generally yield a '''''diagonal''''' AoV of 0.523 radians (30 degrees), but you can easily find the natural AoV by the following formula:

AoV (radians) = 2 * atan( H / ( 2*D ))

where:

Height of screen = H

Distance between head/eye and the screen = D

Generally, gamers like to increase the AoV in order to increase their peripheral vision on the screen, so as to gain a better situational awareness around their craft. An AoV of 0.39 radians seems to be a good start, but feel free to experiment and use whatever AoV you are most comfortable with.

===Multiplayer===
====-gamename====
Specifies the name of the game to be created by the host. This only works when used in conjunction with -startgame.

Takes one argument string, the name to be assigned to the game being created.

This argument does nothing when used with -standalone. To set the name for a standalone server, see [[Multiplayer(Main)#Standalone Servers|Standalone Servers]].

See related:   [[Command-Line_Reference#-startgame|-startgame]]   [[Multiplayer(Main)#Standalone Servers|Standalone Servers]]

====-password====
Specifies the password for a standalone server. This only works when used in conjunction with -startgame. Cannot be used in conjunction with -closed or -restricted.

Takes one argument string, the required password for the game being created.

See related: [[Command-Line_Reference#-startgame|-startgame]] [[Command-Line_Reference#-closed|-closed]] [[Command-Line_Reference#-restricted|-restricted]]

====-allowabove====
Specifies a player's minimum rank for joining a game. This only works when used in conjunction with -startgame.

Takes one argument integer, the points ranking above which a player must be to enter the game.

See related: [[Command-Line_Reference#-startgame|-startgame]]

====-allowbelow====
Specifies a player's maximum rank for joining a game on a standalone server. This only works when used in conjunction with -startgame.

Takes one argument integer, the points ranking below which a player must be to enter the game.

See related: [[Command-Line_Reference#-startgame|-startgame]]

====-port====
Specifies the port on which to host a game or serve a standalone game.

Takes one argument integer, the port on which the host will listen for clients.

====-connect====
Automatically connect to multiplayer IP:PORT.

Takes one string value, such as 192.168.0.1:

====-timeout====
Multiplayer network timeout (secs).

Takes one integer argument, the timeout value in seconds. Default is 30.

====-cap_object_update====
Caps the maximum object update the server will respond to regardless of what the client has set. If the client is set to request high object updates but the server is capped to low, then that's all the client will get.

Takes one argument integer (0 to 3) which corresponds to the object update cap (With 0 being low and 3 being LAN).

===Help===
====-help====
Instructs FSO to print out all supported parameters. Some launchers can use these options to automatically populate the available command line options, even if the version of FSO is far newer than the launcher itself. NOTE: This option only works in Linux builds...

====--help====
See [[Command-Line_Reference#-help|-help]]

====-h====
See [[Command-Line_Reference#-help|-help]]

====-?====
See [[Command-Line_Reference#-help|-help]]

[[Category:Lists]]
[[Category:Source Code Project]]

Weapons.tbl

2016-08-05T09:24:20Z

M!m: Add documentation for particle effects options

{{TableVersionGit|2016-06-05|cb9c669}}

The '''weapons.tbl''' defines all of the weapon classes used in FSO.

This table is one of the [[Modular Tables]] and can be extended with xxx-wep.tbm

[[Tables|List of Tables]]

==Introduction==
The weapons.tbl is responsible for defining the behavior of the numerous weapon effects used in FSO, including the amount of damage dealt, the firing rate, and graphical effects.

This wiki page goes over all of the entries used exclusively in the weapons.tbl file. Hyperlinks to individual weapon creation/editing tutorials are provided when appropriate.

==Special Case Weapons==
===Beam Cannons===
'''REQUIRES:'''
*'''"beam"''' flag
*'''[[weapons.tbl#$BeamInfo:|$BeamInfo:]]'''

See also: [http://www.hard-light.net/wiki/index.php/Tutorial_-_Beam_Weapons Tutorial - Beam Weapons]

===Flak Guns===
'''REQUIRES:'''
*'''"flak"''' flag
*'''"particle spew"''' flag
*Must have inner and outer radius defined to have any effect.
*A '''.pof''' model must be defined ( usually '''Hornet.pof''' )
**Note: the model is not actually used... Instead, it uses [[Weapons.tbl#$Pspew:|particle spew]]. Trails may also be added.

==General Format==
*The weapons table consist of several sections
*All sections beginning with <nowiki>#</nowiki> need <nowiki>#</nowiki>'''End''' before the next section.
**<nowiki>#</nowiki>'''Primary Weapons'''
***Defines all '''standard primaries weapons''' as well as '''beam cannons''' and '''flak cannons'''.
**<nowiki>#</nowiki>'''Secondary Weapons'''
***Defines all '''secondary weapons'''.
**<nowiki>#</nowiki>'''Beam Weapons'''
***I haven't got any ideas for this one.
**<nowiki>#</nowiki>'''[[Weapons.tbl#Countermeasures|Countermeasures]]'''
***Defines the used countermeasure.
**'''$Player Weapon Precedence'''
***Player Weapon Precedence is used in weapon selection when a default specified by the mission designer is not available to the player. The next weapon on the list is used in its place (assuming that weapon is allowed for the player).

==Core Table==

===$Name:===
*This is the name of the weapon. If it's going to be used by the player, keep it under 12 characters so it doesn't spill over the HUD box. Two special characters can be used in the name: '''#''' and '''@'''. Their usage details are the very same than inside the [[Ships.tbl#.24Name:_2|$Name field from Ships.tbl]].
*Syntax: '''''String'''''

====+nocreate====
{{Table3610|
*In [[Modular Tables]] name can be followed by line '''+nocreate''' that prevent game from creating an incomplete entry by leaving the entry unread unless it already exists (either in Weapons.tbl or in earlier parsed *-wep.tbm files) by the time the *-wep.tbm is read.}}

===$Alt Name:===
{{Table3611|
*An alternative name that can be referenced instead of $Name:
*Syntax: '''''String'''''}}

===$Subtype:===
{{Table3610|
Specifies the weapon 's subtype. Overrides the default subtype as specified by the #-section it is in (#Primary, #Secondary, #Beam Weapon, etc.).

{{Note|
:Since the weapon subtype is already specified by the #-section it is in, this option is not particularly useful when the weapon is inside a #Primary or #Secondary section. However, it may be used to specify the weapon slot it uses on fighters/bombers for weapons that are normally capship only (such as beam cannons).}}

*Syntax: '''''String'''''
*Valid Entries:
:Primary
:Secondary}}

===+Title:===
*This is the title of the weapon in the Weapons loadout screen. Only needed for player allowed weapons. Title may be anything. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Syntax: XSTR('''''"String"''''', -1)

===+Description:===
*This is the description you see in the weapons loadout screen. Again, these aren't based on any hard numbers, just approximations. Only needed for player allowed weapons. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Must be followed by '''$end_multi_text'''

'''Example'''

<pre>
XSTR(
"''Standard Issue
''Level 3 Hull Damage
''Level 2 Shield Damage''", -1)
$end_multi_text
</pre>

===+Tech Title:===
*Title of the weapon in the Tech room. Only needed for player allowed weapons.
*Syntax: XSTR('''''"String"''''', -1)

===+Tech Anim:===
*Animation used for the weapon in the Tech room. Only needed for player allowed weapons.
*Syntax: '''''String''''', animation filename
**Example: ''Tech_Subach_HL-7''

===+Tech Description:===
*Descriptive text you see in the tech room. Only needed for player allowed weapons. Numerical value is a reference to translations in [[Tstrings.tbl]]
*Must be followed by '''$end_multi_text'''

'''Example'''

<pre>
XSTR(
"''The Subach-Innes HL-7...''", 3245)
$end_multi_text
</pre>

===$Tech Model:===
{{Table3610|
*Defines model used in wing loadout screen for the weapon. 3D weapon models in the tech room have not yet been implemented.
*Syntax: '''''String.pof''''', model filename}}

====+Closeup_Pos:====
{{Table3613|
*How the model will show on the Loadout Screen. The position of the camera relative to the model center.
*Syntax: '''''Vector''''', three '''floats''', x, y and z values respectively}}

====+Closeup_Zoom:====
{{Table3613|
*How the model will show on the Loadout Screen. How far the camera's zoomed in, defines camera's FOV.
*Syntax: '''''Float''''', radians}}

===$Selection Effect:===
{{Table3613|
*Defines which selection effect to use when the -weapon_choice_3d commandline flag is enabled or no ani can be found for the selected weapon.
*Syntax: '''''String''''', either "FS1", or "Off". This defaults to the FS2 effect.
}}

===$HUD Image:===
{{Table3610|
*Defines the picture used to represent the weapon in HUD loadout list
*Syntax: '''''String''''', filename}}

===$Model File:===
*Filename of the model file (.pof) at data/models folder. Additional fields beginning from '''''@Laser Bitmap:''''' and ending to '''''@Laser Tail Radius:''''' are not needed if a model has been defined for the weapon.
*Standard primaries and beam cannons do not use specific models so for those the name is 'none'.
*Flak weapons and secondaries use models, though the exact model is not important with the flak weapons.
*Syntax: '''''String.pof''''' or ''none'', model filename
**Example: ''none''

===$POF target LOD:===
{{Table3610|
*Defines the LOD (Level-Of-Detail) of the model used in HUD targeting view
*Syntax: '''''Integer'''''}}

===$Detail Distance:===
{{Table3613|
*Defines the distance where the change between different Levels-Of-Details (LODs) occurs
*Take notice that these are base values. Model detail in Detail options, (within game press F2), applies a multiplier to these values. These multipliers are (from left to right): 1/8, 1/4, 1, 4, 8
*Optional. If not defined the game uses the formula ((radius * 20.0 + 20.0) * LOD)
*Syntax: '''''(Detail Distances)''''' , list of '''integers''' (same amount as LODs), distances from the model in meters
**Example: ''(0, 80, 300, 900)''}}

===$External Model File:===
{{Table3610|
*Defines the models shown on the gunpoint, used with Bobb's external-visible-weapon code.
*Syntax: '''''String.pof''''', model filename}}

===$Submodel Rotation Speed:===
{{Table3610|
*Defines the rotation speed of the subobject, with the $gun_rotation property defined, in the external weapon model.
*Syntax: '''''Float'''''
*Note: weapon fire will be delayed by the time it takes for the weapon to spin up to this speed (using $Submodel Rotation Acceleration or its default value), regardless of whether an external model is used or not.
}}
{{Table38|
*Note: It's no longer required that the ship actually have external models enabled (whether or not this weapon has one defined) for the spin up delay to occur.
}}

===$Submodel Rotation Acceleration:===
{{Table3610|
*Defines the rotation acceleration of the external weapon model.
*Syntax: '''''Float'''''
*Default value: 10}}

===@Laser===
In the event a 3D model is not defined for the weapon, FSO creates an object similar to a glowpoint. Essentially, it is a 2D plane that always faces the player's camera with an additive texture applied to it, and may or may not have an omnilight follow it.

As suggested by its name, this option group is normally used for lasers and similar primaries, but it may also be used for other weapon types as well.

Unless said otherwise, the graphic files used within this group may be of any compatible type (.DDS, .PCX, .TGA, etc.), however a .DDS is recommended.

====@Laser Bitmap:====
Defines the graphic file to be used as the weapon effect.

Blending type: additive

Syntax: '''''String''''', filename

'''Example:'''
<pre>
@Laser Bitmap: my_laser_bitmap
</pre>

====@Laser Glow:====
Defines the graphic file to be used for the glowmap of the weapon effect.

Blending type: additive

*This file is 'multiplied' by a value between Color and Color2.
*The physical dimensions of the glowmap in-game is 2x the size of the bitmap.

Syntax: '''''String''''', filename

'''Example:'''
<pre>
@Laser Glow: my_laser_glowmap
</pre>

====@Laser Color:====
The RGB color of the glow effect.

*The color is applied both to the glowmap and the omnilight that follows the effect.

Syntax: '''''Color''''', red, green, blue respectively, 8-bit value from 0 to 255

'''Example:'''
<pre>
@Laser Color: 255, 0, 0 ; Red glow effect at the start of the effect's lifetime
</pre>

====@Laser Color2:====
The RGB color of the glow effect at the end of the effect's lifetime (at its maximum range).

*The color is applied both to the glowmap and the omnilight that follows the effect.
*The actual color of the glow effect is somewhere in between the values defined by Color and Color2. Essentially, the actual color "fades" from Color to Color2 over its lifetime.
**If Color is not defined, then a default value of 255, 255, 255 is assumed for its initial color.

Syntax: '''''Color''''', red, green, blue respectively, 8-bit value from 0 to 255

'''Example:'''
<pre>
@Laser Color2: 0, 0, 255 ; Blue glow effect at the end of the effect's lifetime.
</pre>

'''Example:'''
<pre>
@Laser Color: 255, 0, 0 ; Start with a Red glow effect, and fade into...
@Laser Color2: 0, 0, 255 ; a Blue glow effect over the lifetime of the effect.
</pre>

====@Laser Length:====
Defines the length of the weapon effect.
*This option stretches the 2D plane "away" from its origin.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Length: 1.0
</pre>

====@Laser Head Radius:====
Defines the width of the leading edge, or "head," of the weapon effect.
*The edge of the 2D plane farthest away from its origin is the leading edge.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Head Radius: 0.75
</pre>

====@Laser Tail Radius:====
Defines the width of the trailing edge, or "tail" of the weapon effect.
*The edge of the 2D plane that is closest to its origin is the trailing edge.
Syntax: '''''Float''''', meters

'''Example:'''
<pre>
@Laser Tail Radius: 0.75
</pre>

===$Mass:===
*How much of a kinetic effect this weapon has on its target. 3+ gives you the Flail effect. Set it to 10 and you can knock cruisers around.
*This is somehow multiplied by the speed. ie ''$Mass: 3'' and ''$Velocity: 200'' has much weaker kinetic effect than ''$Mass: 3'' and ''$Velocity: 1000''. Also $Mass is used to calculate intensity of "shudder" effect if flagged.
*Syntax: '''''Float''''', blast effect

===$Velocity:===
*How fast the weapon travels. Is also used to define the weapon range, '''''$Velocity x $Lifetime = range'''''.
*Beams travel instantly so this field has effect only on weapon range and AI beam targeting with certain beam types. $Velocity of beam also applies to its kinetic effect along with $Mass.
*Syntax: '''''Float''''', meters per second

===$Fire Wait:===
*Time in seconds between firings
*Note that Fire wait will be reset to 1 if it is set over 5 for non turreted primary weapons (doesn't apply to 3.6.14+)
*Syntax: '''''Float''''', seconds

====+Max Delay:====
{{Table373|
*Defines the maximum amount of time it takes to refire a weapon in a random fire delay range.
**This must be used with +Min Delay: to have any effect.
*Syntax: '''''Float''''', seconds}}

====+Min Delay:====
{{Table373|
*Defines the minimum amount of time it takes to refire a weapon in a random fire delay range.
**This must be used with +Max Delay: to have any effect.
*Syntax: '''''Float''''', seconds}}

===$Damage:===
*Base damage this weapon does. The actual damage is this number multiplied by the factors below.
*Base damage this beam does is continuous damage, damage is 5.5 times the damage value per second. The actual damage is this number multiplied by one of the factors below.
*Syntax: '''''Float''''', damage
*Note: adding a shockwave to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x shockwave)

===$Damage Time:===
{{Table373|
*This sets a time from the end of the weapons lifetime that damage will start to attenuate at. '''''Example: Weapon lifetime is 2.0 seconds and the desired effect is to attenuate after 0.5 seconds have passed, set this to 1.5 seconds.'''''
*Syntax: '''''Float''''', seconds. Defaults to 0.0.
**Note: If neither +Min Damage: nor +Max Damage: is set, the damage will always attenuate to zero at max range.
***If both +Min Damage: and +Max Damage: are set, both are defaulted to 0.0 and damage will be attenuated to zero.}}

====+Attenuation Damage:====
{{Table373|
*This sets the damage a weapon will attenuate to after reaching $Damage Time:.
*Syntax: '''''Float''''', damage.}}

====+Min Damage:====
{{Table373|
*This sets the lowest amount of damage possible assuming damage attenuation is taking place. '''''This has been deprecated, please use +Attenuation Damage: instead.'''''
*Syntax: '''''Float''''', damage. Defaults to 0.0.}}

====+Max Damage:====
{{Table373|
*This sets the highest amount of damage possible assuming damage attenuation is taking place. '''''This has been deprecated, please use +Attenuation Damage: instead.'''''
*Syntax: '''''Float''''', damage. Defaults to 0.0.}}

===$Damage Type:===
{{Table3610|
Defines the damage type that this weapon uses. All armor effects are applied after shield and have no function against shockwave or subsystem damage.

'''REQUIRES:''' [[armor.tbl]]

*Syntax: '''''String''''', name of the damage type ( as defined by [[armor.tbl#$Damage Type:|$Damage Type]] )}}

===$Arm time:===
{{Table3610|
*Defines the time after the launch that is required before the weapon comes hot
*If the time has not been reached when the weapon detonates the Dinky explosion is used
*Syntax: '''''Float''''', seconds}}

===$Arm distance:===
{{Table3610|
*Defines the distance from the firing ships that is required before the weapon comes hot
*If the distance has not been reached when the weapon detonates the Dinky explosion is used
*Syntax: '''''Float''''', meters}}
{{Table3615|
*This parameter is also applied to flak weapons. Previous behaviour was to arm weapons after 10 meters of travel.}}

===$Arm radius:===
{{Table3610|
*Defines the distance from the target where the weapon will arm itself
*Syntax: '''''Float''''', meters}}

===$Detonation Range:===
{{Table3610|
*Defines the distance from the point in space that the weapon was launched where the weapon will detonate
*Syntax: '''''Float''''', meters}}

===$Detonation Radius:===
{{Table3610|
*Defines the distance between the target center point point and the weapon which detonates the weapon.
*Syntax: '''''Float''''', meters}}

===$Shockwave damage:===
{{Table3610|
*Override for the damage caused by shockwaves (default is [[#$Damage:]])
*Syntax: '''''Float''''', damage
*Note: adding a shockwave to a weapon doubles its effective damage to the target (i.e. 1x impact, 1x shockwave)
}}

===$Shockwave Damage Type:===
{{Table3610|
*'''REQUIRES ADDITIONAL TABLE'''. Defines the damage type used for the weapon explosions
*Syntax: '''''String''''', name as defined in [[armor.tbl]]}}

===$Flak Detonation Accuracy:===
{{Table3615|
*Normally, flak weapons detonate at a range of 65 to 99 meters from their intended target, depending on the firing ships' weapon subsystem health. This parameter can be used to adjust this behaviour, as it defines the base range used to determine this detonation range. Standard value is 65.
*Syntax: '''''Float''''', range in meters}}

===$Flak Targeting Accuracy:===
{{Table3615|
*Turret-fired flak weapons are normally firing in a cone around the target's predicted position. This parameter can be used to adjust the size of this cones' base radius. Standard is 60 meters.
*Syntax: '''''Float''''', radius in meters}}

===$Untargeted Flak Range Penalty:===
{{Table3615|
*If a flak weapon is fired without a target selected, this parameter defines the range penalty applied to that weapon. Standard is 20 meters, meaning an untargeted flak weapon will detonate after travelling its max range - 20 meters.
*Syntax: '''''Float''''', penalty in meters.}}

===$Blast Force:===
*The intensity of the kinetic blast effect when ship is within the outer radius of the explosion. Comes in effect only if inner and outer radius are defined.
*Syntax: '''''Float''''', blast effect

===$Inner Radius:===
*Radius at which the full explosion damage is done. Marks the line where damage attenuation begins. Damage is reduced by the square of the distance between the inner radius and outer radius. i.e. half way between inner and outer results in 1/4 damage
*Syntax: '''''Float''''', meters

===$Outer Radius:===
*Maximum radius at which any damage is done. See $Inner Radius for the attenuation formula.
*Also defines the size of the shockwave (if shockwave speed is > 0)
*Syntax: '''''Float''''', meters

===$Shockwave Speed:===
*Speed shockwave expands at. Zero means no shockwave and that damage is applied immediately
*Syntax: '''''Float''''', meters per second

===$Shockwave rotation:===
{{Table3610|
*Defines how the 3D shockwave is rotated.
*Syntax: '''''Angle''''', three values, pitch, bank, heading respectively, in degrees}}

===$Shockwave model:===
{{Table3610|
*Defines the model file (.pof) used as a shockwave for the 3D shockwaves.
*Syntax: '''''String.pof''''', model filename}}

===$Shockwave name:===
{{Table3610|
*Defines the name of the animation used for the 2D shockwave
*Syntax: '''''String''''', filename}}

===$Dinky shockwave:===
{{Table3610|
*Dinky shockwave are used if the weapon is shot down before arming or if the conditions marked at '''Arm time''' and '''Arm distance''' are not reached before impact
*It uses exactly same entries as the standard shockwaves
*'''''+Shockwave damage:'''''
*'''''+Shockwave damage type:'''''
*'''''+Blast Force:'''''
*'''''+Inner Radius:'''''
*'''''+Outer Radius:'''''
*'''''+Shockwave Speed:'''''
*'''''+Shockwave Rotation:'''''
*'''''+Shockwave Model:'''''
*'''''+Shockwave Name:'''''}}

===$Armor Factor:===
*Multiplier for the damage done to armor
*Syntax: '''''Float''''', damage multiplier

===$Shield Factor:===
*Multiplier for the damage done to shields
*Syntax: '''''Float''''', damage multiplier

===$Subsystem Factor:===
*Multiplier for the damage done to subsystems
*Syntax: '''''Float''''', damage multiplier

===$Lifetime Min:===
{{Table3610|
*Defines the minimum lifetime of the weapon
*Syntax: '''''Float''''', seconds}}

===$Lifetime Max:===
{{Table3610|
*Defines the maximum lifetime of the weapon
*Syntax: '''''Float''''', seconds}}

===$Lifetime:===
*Time before the standard primaries fizzle out and secondaries self destruct. Multiply this by the speed to get the range. If values are too low (below framerate) then the collision detection and graphic effects may suffer.
*This field has no effect for the beams apart from weapon range and AI beam targeting with certain beam types
*Syntax: '''''Float''''', seconds

===$Energy Consumed:===
*The amount of energy each bolt drains firing ship. Has no effect on turretted weapons.
*Syntax: '''''Float'''''

===$Cargo Size:===
*Cargo size, is not used with non-ballistic primaries.
*Amount of missiles available = Bank capacity / Cargo Size.
*Syntax: '''''Float'''''

===$Homing:===
'''This option is exclusive to secondaries.'''

Defines if the bolts/missiles in question is homing
*The bolts of primaries will turn to face their target if this option is set to YES... but is otherwise the same as a normal bolt ( when the option is set to NO ).

If set to NO, then following fields are not required in the table.

*Syntax: '''''Boolean''''', yes or no

===='''+Type:'''====
Defines the homing method
*Syntax: '''''String''''', ''ASPECT'' or ''HEAT''
{{Table3610| An additional option, ''JAVELIN'', has been added. This behaves like an aspect missile but automatically only locks onto the engines of a target, and only if the engines are in sight.}}

===='''+Turn Time:'''====
Determines how well the missile maneuvers. Is defined as the number of seconds it takes the missile to do a 360 degree circle
**Syntax: '''''Float''''', seconds

===='''+View Cone:'''====
'''Heat-seeking missiles only'''

This is the width of the weapon's viewing cone, given in degrees. Objects outside this cone are effectively invisible to the missile. The value / 2 gives the angle from the missile's centerline to the edge of the viewing cone.
*Syntax: '''''Float''''', degrees
{{Table3610| Has been enabled also to aspect seekers as an option.}}

===='''+Min Lock Time:'''====
'''For aspect/javelin missiles only'''

The minimum number of seconds to gain a target lock.
*Syntax: '''''Float''''', seconds

===='''+Lock Pixels/Sec:'''====
'''For aspect/javelin missiles only'''
The number of pixels the aspect triangle moves per second while attempting lock-on.

*Syntax: '''''Integer''''', pixels per second

===='''+Catch-up Pixels/Sec:'''====
'''For aspect/javelin missiles only'''

The number of pixels moved per second while attempting to catch up to the target.
*Syntax: '''''Integer''''', pixels per second

===='''+Catch-up Penalty:'''====
'''For aspect/javelin missiles only'''

Extra pixels to move after catching up. (Needs verification )
**Syntax: '''''Integer''''', pixels

===='''+Seeker Strength:'''====
{{Table3610|
Defines the seeking ability of the homing system. Default of heat seekers is 3.0 and for aspect seekers 2.0. Spoofing chance is defined as '''[[#$Countermeasure:|cm type effectiveness]]'''/'''seeker strength''' (missile must be within the countermeasures '''[[#$Countermeasure:|+Effective Radius:]]'''
*Syntax: '''''Float''''', seeker strength}}

===='''+Target Lead Scaler:'''====
{{Table3611|
Defines the type of pursuit course the missile tries to obtain.
*Values < 0 give lag pursuit, values ~ 0 give pure pursuit, values > 0 give lead pursuit.
*Syntax: '''''Float''''', default for heat seekers: 0, default for aspect or javelin seekers: 1.}}

===$Swarm:===
*The number of missiles to fire per volley if it's a swarm missile
*Can be issued to Standard primaries also. Causes single part turrets to malfunction but causes multi part turrets to fire only on their barrel line. Can be used for 'burst fire weapons'. Does not work with player weapons.
*Is incompatible with "Corkscrew" option.
*Syntax: '''''Integer''''', number of shots in a swarm
{{Table3610|
*'''+SwarmWait:'''
**Defines the time between weapons fired in a swarm
**Syntax: '''''Float''''', seconds
***Default: 0.150
***Max: 0.5 (Resets to default if set over 0.5)}}

===$Acceleration Time::===
{{Table371|
*Defines how long it takes for a secondary weapon to attain full speed. Takes precedence over $Free Flight Time (see below) in terms of the weapon's velocity, and affects both locked-on and dumbfired secondaries.
*Syntax: '''''Float''''', seconds
**Default: 0.0}}

===$Velocity Inherit::===
{{Table371|
*Defines how much of the parent ship's velocity to inherit, if [[Ai_profiles.tbl#.24use_additive_weapon_velocity:]] is used.
*Syntax: '''''Float''''', percents
**Default: 100.0}}

===$Free Flight Time:===
{{Table3610|
*Defines the free flight time of homing weapons. During this time weapon flies at 1/4 of its velocity + firing ships velocity in a straight line.
*Syntax: '''''Float''''', seconds
**Default: 0.25}}

'''Note:''' due to dumbfires never changing their speed, using this on a dumbfire missile will have it stuck at freeflight speed even after the end of the freeflight time.

===$Free Flight Speed:===
{{Table3613|
*Defines the speed that the weapon will be travelling at during the free flight segment (see above).
*Syntax: '''''Float''''', Multiplier for the actual speed, minimum 0.01.
**Default: 0.25
{{Note| This feature was never implemented correctly and was removed in r8867. FSO currently parses but doesn't use the value, and prints a warning in the log saying that the value will not be used.}}
}}

===$PreLaunchSnd:===
{{Table3613|
*Defines the one-shot sound effect to play at the beginning of a firing stream. Currently only has an effect on primary weapons.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
**Default: No Sound}}

===+PreLaunchSnd Min Interval:===
{{Table3613|
*Defines Minimum interval between when the player stops firing and the next time the pre-launch sound can play, as a limiter in case the player is pumping the trigger.
*Syntax: '''''Integer''''', Minimum delay in milliseconds between the end of the previous firing sequence and the next time the pre-launch sound effect will be played.
**Default: 0 (play pre-launch sound at the beginning of every firing sequence, if present)}}

===$LaunchSnd:===
*Corresponding sound effect when the weapon is launched.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$ImpactSnd:===
*Sound the weapon makes when it hits a hull.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$Disarmed ImpactSnd:===
{{Table3610|
*Sound the weapon makes when it hits a hull before being armed.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$FlyBySnd:===
*The sound this weapon makes if it narrowly misses you. -1 is no sound.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]], usually -1

===$TrackingSnd===
{{Table3615|
*The looping sound played when this weapon tracks a target.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$LockedSnd===
{{Table3615|
*The sound played when this weapon has locked onto its target.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]}}

===$InFlightSnd===
{{Table3615|
*The looping sound played when the missile is currently flying.
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+Inflight sound type'''
**Specifies when the in flight sound is played.
**The value can be one of the following values which are matched case-insensitively:
***''''''TARGETED'''''': The sound is played when the missile tracks a target
***''''''UNTARGETED'''''': The sound is played when the missile is currently not tracking a target
***''''''ALWAYS'''''': The sound is played always}}

===$Model:===
{{Table3610|
*Defines used model file. Included for compatibility with countermeasures as they have been merged with weapons in the code.
*Syntax: '''''String.pof''''', model filename}}

===$Rearm Rate:===
*Defines the rate the weapons are loaded to the ship
*Syntax: '''''Float''''', missiles loaded per second

===+Weapon Range:===
*Defines the range to the target where the weapons under AI will start firing.
*Syntax: '''''Float''''', meters

===+Weapon Min Range:===
{{Table3610|
*Defines the minimum range to the target where the weapons under AI will still fire.
*Implemented before FS_Open 3.6.5
*Syntax: '''''Float''''', meters}}

===$Flags:===
*See [[Weapons.tbl#Weapons.tbl_Flags|below]]
*Syntax: '''''( "String" "String" )''''', names of the flags assigned to the weapon
**Example: ( "Player allowed" "in tech database" )

{{Table3610|
*Can be followed by '''+override''' option in order to reset the weapon flags before parsing in the new ones
*Using this option will erase all '''homing'''-related flags as well as '''swarm''', '''variable lead''', '''trail''', '''TAG''', and '''transparent''' settings in addition to the listed flags. All these should be set again - if they are required - when this option is used.

**Syntax: '''''+override'''''}}

===$Trail:===
*This is used if you want your weapon to have a trail. Trail is often used only with secondaries though it works with standard primaries as well.
*'''+Start Width:'''
**How wide the head of the trail is.
**Syntax: '''''Float''''', meters
*'''+End Width:'''
**How wide the tail of the trail is.
**Syntax: '''''Float''''', meters
*'''+Start Alpha:'''
**The opacity of the trail head.
**Syntax: '''''Float''''', value between 0 and 1
*'''+End Alpha:'''
**The opacity of the trail tail.
**Syntax: '''''Float''''', value between 0 and 1
*'''+Max Life:'''
**How long the trail lasts.
**Syntax: '''''Float''''', seconds
*'''+Bitmap:'''
**The graphic file to use for the trail.
**Syntax: '''''String''''', filename
{{Table3611|
*'''+Faded Out Sections:'''
**Defines the number of the trail sections (counting from the leading edge) which are gradually faded out.
**Syntax: '''''Integer''''', number of trail sections}}

===$Icon:===
*Loadout icon used in the weapons selection screen.
*Syntax: '''''String''''', filename

===$Anim:===
*Green grid animation used on the weapons screen.
*Syntax: '''''String''''', filename

===$Collide Ship:===
{{Table3610|
*Has been replaced with '''#Conditional Hooks''', see [[Scripting.tbl]]}}

===$Collide Weapon:===
{{Table3610|
*Has been replaced with '''#Conditional Hooks''', see [[Scripting.tbl]]}}

===$Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for impacts of this weapon.
*Syntax: '''String''', the particle effect name
*If this option is specified then ''$Impact Explosion'' and ''$Impact Explosion Radius'' are not valid options!
}}

===$Impact Explosion:===
*Impact explosion used. Must be defined in weapon_expl.tbl,
*Syntax: '''''String''''', filename or ''none''

===$Impact Explosion Radius:===
*Radius of the defined impact explosion.
*Syntax: '''''Float''''', meters, default 1.0

===$Shield Impact Explosion Radius:===
{{Table373|
*Radius of the shield impact explosion, see [[Ships.tbl#.24Shield_Impact_Explosion:]].
*Syntax: '''''Float''''', meters, defaults to value of $Impact Explosion Radius}}

===$Dinky Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for Dinky (not armed) explosions of this weapon.
*Syntax: '''String''', the particle effect name
*If this option is specified then ''$Dinky Impact Explosion'' and ''$Dinky Impact Explosion Radius'' are not valid options!
}}

===$Dinky Impact Explosion:===
{{Table3610|
*Same as Impact Explosion but for Dinky (not armed) explosions
*Syntax: '''''String''''', filename or ''none''}}

===$Dinky Impact Explosion Radius:===
{{Table3610|
*Same as Impact Explosion Radius but for Dinky explosions
*Syntax: '''''Float''''', meters}}

===$Piercing Impact Effect:===
{{Table38|
*Specifies the [[Particle Effects|particle effect]] which will be used for piercing impacts.
*Syntax: '''String''', the particle effect name
*If this option is specified then piercing impact options below are not valid!
}}

===$Piercing Impact Explosion:===
{{Table3611|
*Defines the effect used for events when weapon pierces the target
*Syntax: '''''String''''', filename or ''none''}}

===$Piercing Impact Radius:===
{{Table3611|
*Defines the base radius of the effect used for piercing weapon impacts
*Syntax: '''''Float'''''}}

===$Piercing Impact Velocity:===
{{Table3611|
*Defines the base velocity for the particles piercing the target
*Syntax: '''''Float'''''}}

===$Piercing Impact Splash Velocity:===
{{Table3611|
*Defines the base velocity for the particles splashing from the target (secondary piercing effects
*Negative value causes the second batch or particles to splash to opposite direction
*Syntax: '''''Float'''''}}

===$Piercing Impact Variance:===
{{Table3611|
*Defines the variance added to the particles
*Values near 0 cause very little variance and values close to 1 cause extreme dispersal.
*Syntax: '''''Float'''''}}

===$Piercing Impact Life:===
{{Table3611|
*Defines the lifetime of the effect for single frame effects
*For multiple frame effects the lifetime is the lifetime of the animation used
*Syntax: '''''Float'''''}}

===$Piercing Impact Particles:===
{{Table3611|
*Defines the number of particles released per impact
*Syntax: '''''Integer'''''}}

===$Piercing Impact Draw Modifier:===
{{Table3611|
*Defines the multiplier applied to the ships piercing effect limit percentage
*Syntax: '''''Float'''''}}
*Option removed in 3.6.12. Use [[armor.tbl]] to finetune piercing effects.

===$Inflight Effect:===
{{Table38|
*Sets the inflight [[Particle Effects|particle effect]] which is used when the laser is active. This is only used by laser weapons.
*Syntax: '''''String''''', the particle effect name
}}
===$Freeflight Effect:===
{{Table38|
*Sets the [[Particle Effects|particle effect]] which is used when the missile is in the free flight phase. See [[#$Free Flight Time:|$Free Flight Time]] for more information.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Ignition Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is transitioning from free flight to homed or unhomed flight.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Homed Flight Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is in homed flight mode.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}
===$Unhomed Flight Effect:===
{{Table38|
*Sets the ignition [[Particle Effects|particle effect]] which is used when the missile is in unhomed flight mode.
*Syntax: '''''String''''', the particle effect name
*This option is only valid for missile weapons
}}

===$Muzzleflash:===
*Normally only with flak cannons.
*Defines the muzzle flash the weapon uses
*Syntax: '''''String''''', muzzleflash name, as defined in [[mflash.tbl]]

===$EMP Intensity:===
*If it has an EMP effect, how deeply it scrambles your electronics
*Basically a percentage, a value of 250 results in a 25% chance of something getting scrambled each frame.
*Maximum value of 500
**Syntax: '''''Float'''''

===$EMP Time:===
**Duration of the EMP effect
**Syntax: '''''Float''''', seconds

===$Recoil Modifier:===
{{Table373|
*Multiplies the recoil force of a weapon by this value, use a value greater than 1.0 to increase the force, use a value between 1.0 and 0.0 to decrease.
**Syntax: '''''Float''''' (defaults to 1.0)
{{Note| The "apply recoil" weapon flag must be set for this to be valid. If the flag is not set, FSO will throw a warning and automatically set it at runtime.}}
}}

===$Leech Weapon:===
**The amount of weapon energy to drain with each hit (a flat value, not a percentage)
**Needs the [[#Esuck|Esuck]] flag set to have any effect
**Syntax: '''''Float''''' (defaults to 10.0)

===$Leech Afterburner:===
**The amount of afterburner fuel to drain with each hit (a flat value, not a percentage)
**Needs the [[#Esuck|Esuck]] flag set to have any effect
**Syntax: '''''Float''''' (defaults to 10.0)

===$Corkscrew:===
{{Table3610|
*Allow corkscrew parameters to be defined
*'''+Num Fired:'''
**Defines the number of weapons fired in sequence. Same as the standard swarm entry but for corkscrew missiles
**Syntax: '''''Integer''''', number of missiles
*'''+Radius:'''
**Defines the radius used in the corkscrew motion
**Syntax: '''''Float''''', meters
*'''+Fire Delay:'''
**Defines the delay between missile firings
**Syntax: '''''Integer''''', milliseconds
*'''+Counter rotate:'''
**Defines if every other missile rotates to a different direction (clockwise / anticlockwise)
**Syntax: '''''Boolean''''', ''0'' or ''1'', no or yes
*'''+Twist:'''
**Defines the speed of rotation movement on the radius of corkscrew motion.
**Syntax: '''''Float''''', radians per second}}

===$Electronics:===
{{Table3610|
*Defines the weapons effect against electronics. Requires [[weapons.tbl#"Electronics"|"electronics"]] flag. '''+New Style:''' and '''+Old Style:''' options are mutually exclusive.
*'''+New Style:'''
**Defines that the electronics use the new style which enables more options.
*'''+Old Style:'''
**Defines that the electronics use the old style. The old style was the way the D-Missile worked in Descent: FreeSpace.
}}
{{Table371|
*'''+Area Of Effect'''
**If specified, allows the electronics effect to apply to every ship hit by this weapon's blast or shockwave (the "Electronics" flag isn't necessary with this option).
}}
{{Table3610|
*'''+Intensity:'''
**May only be used with '''+New Style:''' electronics. '''''Has been deprecated'''''.
**Syntax: '''''Float'''''
*'''+Lifetime:'''
**Syntax: '''''Integer''''', milliseconds
*'''+Engine Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for engine subsystems.
**Syntax: '''''Float'''''
*'''+Weapon Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for non-beam turrets.
**Syntax: '''''Float'''''
*'''+Beam Turret Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for beam turrets.
**Syntax: '''''Float'''''
*'''+Sensors Multiplier:'''
**May only be used with '''+New Style:''' electronics. Defines how much longer the disruption effect lasts for sensor subsystems.
**Syntax: '''''Float'''''
*'''+Randomness Time:'''
**Defines the randomness of duration target suffers from the electronics hit. A random number between 0 and this time will be added or subtracted from the disruption time.
**Syntax: '''''Integer''''', milliseconds

* Without any electronics parameters, a weapon with the "electronics" flag will default to the ''Old Style'' mode with a lifetime of 6000 milliseconds and a randomness of 4000 milliseconds. Thus any ship that gets hit can get disrupted for anywhere between 2 to 10 seconds.

}}

===$Spawn Angle:===
{{Table3610|
*Defines the cone (with an angle) where the spawned weapons appear. ''Value'' gives the angle from the missiles centerline. The maximum possible angle between any two child weapons would be ''Value*2''.
*Spawn angle can be defined as many times as the carrier missile has child weapons defined for it (up to 5).
*Syntax: '''''Float''''', degrees}}

===$Local SSM:===
{{Table3610|
*Defines the local SSM (Subspace Missile). In effect missile moves via subspace to a position close to the target and starts homing.
*Weapon must be '''''aspect seeking missile''''' and must have '''''[[Weapons.tbl#"local ssm"|local ssm]]''''' flag.
*'''+Warpout Delay:'''
**Defines the time between the missile launch and the subspace jump.
**Syntax: '''''Integer''''', milliseconds
*'''+Warpin Delay:'''
**Defines the time missile stays in subspace before exiting.
**Syntax: '''''Integer''''', milliseconds
*'''+Stage 5 Velocity:'''
**Defines the velocity of the missile after the subspace jump.
**Syntax: '''''Float''''', meters per second
*'''+Warpin Radius:'''
**Defines how far from the SSM will appear from the outer radius of the target.
**Syntax: '''''Float''''', meters
*'''+Lock Range:'''
**Defines the maximum range where SSM can achieve target lock
**Syntax: '''''Float''''', meters}}

===$Countermeasure:===

*Defines the countermeasure effectiveness, radius, etc
{{note|
*Spoofing chance is defined as '''cm type effectiveness'''/'''[[#+Seeker Strength:|seeker strength]]''' (missile must be within the countermeasures '''+Effective Radius:''').
*All countermeasures in the mission perform tests to spoof missiles for two frames after '''any countermeasure''' is created in the mission. No, this doesn't seem to make much sense.
*'''Provisional'''; Countermeasures are only given one chance to spoof any individual missile. This makes tuning seeker strength/effectiveness meaningful.
**Previously some record of which countermeasures had been seen by each missile was kept, but it broke when multiple countermeasures were involved. A good chance of breaking with two countermeasures, and a guaranteed chance of breaking with three or more. This reduced the impact of the seeker strength/effectiveness ratio, but was partly cancelled out by the 2 frames thing.
}}

{{Table3610|
===='''+Heat Effectiveness:'''====
*Defines the countermeasures effectiveness against heat seeking missiles
*Syntax: '''''Float''''', cm effectiveness
**Default: 1.0

===='''+Aspect Effectiveness:'''====
*Defines the countermeasures effectiveness against aspect seeking missiles
*Syntax: '''''Float''''', cm effectiveness
*Default: 1.0

===='''+Effective Radius:'''====
*Defines the countermeasures effective radius
*Syntax: '''''Float''''', meters
**Default: 300.0
}}

{{Table373|
====+Missile Detonation Radius:====
*Defines the radius within which a missile homing on this countermeasure will trigger a detonation (see '''+Single Missile Kill:''')
*Syntax: '''''Float''''', meters
**Default: 40.0
{{note| only affects missiles homing on countermeasures, i.e. heat or aspect with "pulls aspect seekers" flag}}
====+Single Missile Kill:====
*Defines if countermeasures will detonate only the missile homing on this countermeasure, or every missile within '''+Missile Detonation Radius:'''
*Syntax: '''''Boolean'''''
**Default: false
{{note| only affects missiles homing on countermeasures, i.e. heat or aspect with "pulls aspect seekers" flag}}
}}

===$BeamInfo:===
*'''+Type:'''
**Defines the type of beam in question. Beam types: 0 is a standard non-slashing type beam. 1 is a slashing type beam. 2 is a targeting beam that is used to trigger SSMs. 3 is a beam type that fires pulses in anti-fighter role and acts like type 0 beam in other roles. 4 is a beam that is restricted to what is directly in front of it, along turrets firepoints normal.
**Syntax: '''''Integer''''',, only values from 0 to 4 are legal
*'''+Life:'''
**How long it lasts once the beam is actually firing.
**Syntax: '''''Float''''', seconds
*'''+Warmup:'''
**Warmup time
**Syntax: '''''Integer''''', milliseconds
*'''+Warmdown:'''
**Warmdown time
**Syntax: '''''Integer''''', milliseconds
*'''+Radius:'''
**Muzzle glow radius
**Syntax: '''''Float''''', meters
*'''+PCount:'''
**Particles spewed every interval. ??
**Syntax: '''''Integer'''''
*'''+PRadius:'''
**Particle radius
**Syntax: '''''Float''''', meters
*'''+PAngle:'''
**Defines the random "cone" where the particles are generated
**Syntax: '''''Float''''', angle of the cone
*'''+PAni:'''
**Animation used to represent the particles
**Syntax: '''''String''''', filename
*'''+Miss Factor:'''
**The higher the numbers, the more likely that this beam will miss. One value for every difficulty level
**Syntax: '''''Miss Factor''''', five '''floats''', very easy, easy, moderate, hard, insane, respectively.
***Example: 0.5 0.975 1.35 1.875 2.5
{{Table3613|
*'''IFF specific miss factors'''
**Identical to the preceding entry but IFF specific. Replace the <IFF> with the name of the IFF from [[iff_defs.tbl]]
**Syntax: '''''+<IFF> Miss Factor:''''', five '''floats''', very easy, easy, moderate, hard, insane, respectively.
***Example: 0.5 0.975 1.35 1.875 2.5}}
*'''+BeamSound:'''
**Corresponding looping sound effect when the beam is firing.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+WarmupSound:'''
**Corresponding sound effect when the beam is beam warmed up.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+WarmdownSound:'''
**Corresponding sound effect when the beam is warming down.
**Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]
*'''+Muzzleglow:'''
**Defines the bitmap used to create the muzzle glow
**Syntax: '''''String''''', filename
*'''+Shots:'''
**Defines into how may invidual shots the type 3 (AAA) beams are divided. Note total firing is the same as the +Life:
**Syntax: '''''Integer'''''
*'''+ShrinkFactor:'''
**What percentage of lifetime where beam starts shrinking (0.1 == 10% life left)
**Syntax: '''''Float'''''
*'''+ShrinkPct:'''
**What percentage of max width we subtract per second
**Syntax: '''''Float'''''
{{Table3610|
*'''+Range:'''
**Defines the maximum range where the beam still has any effect.
**Syntax: '''''Float''''', meters
*'''+Attenuation:'''
**Defines the point where the damage caused by the beam starts to attenuate. At maximum range damage is zero.
**Syntax: '''''Float''''', from 0 - firing point to 1 - no effect
***Default: 1}}
{{Table3611|
*'''+BeamWidth:'''
**Defines the width of the beam for collision test purposes instead of using widest beam section.
**Syntax: '''''Float''''
{{Table38|
*'''+Beam Flash Particle Effect:'''
**Specifies the beam flash [[Particle Effects|particle effect]].
**Syntax: '''''String''''', particle effect name
**If this is specified then '''+Beam Flash Effect''' and '''+Beam Flash Radius''' are not valid options!
}}
*'''+Beam Flash Effect:'''
**Defines the additional impact flash effect for the beam.
**Syntax: '''''String''''', filename
*'''+Beam Flash Radius:'''
**Defines the radius for the additional impact flash effect.
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect:'''
**Defines the beam piercing (bursting flames) effect for the beam.
**Syntax: '''''String''''', filename
*'''+Beam Piercing Radius:'''
**Defines the average radius used for the beam piercing effects.
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect Velocity:'''
**Defines the base velocity for the piercing effects
**Syntax: '''''Float'''''
*'''+Beam Piercing Splash Effect Velocity:'''
**Defines the base velocity for the secondary piercing effects
**Negative velocity causes the particles to move to opposite direction
**Syntax: '''''Float'''''
*'''+Beam Piercing Effect Variance:'''
**Defines the variances of the particles from the main path
**Values close to 0 cause minimum variance, higher values cause higher variances
**Syntax: '''''Float'''''}}

*'''$Section:'''
**Beams are made up of up to five sections layered atop one another to create the effect. Each section has its own parameters.
{{Table3610|
:*'''+Index:'''
:**Field used to define with [[Modular Tables]] the beam section which is edited.
:**Only needed when editing beams that already exist in other tables.
:**Syntax: '''''Integer''''', index number legal values are from 0 to 5
:*'''+remove'''
:**Removes the set beam section.
:*'''+nocreate'''
:**Does not create new section for the beam}}

:*'''+Width:'''
:**Width of the section
:**Syntax: '''''Float''''', meters
:*'''+Texture:'''
:**Texture for the section
:**Syntax: '''''String''''', filename
:*'''+RGBA Inner:'''
:**Defines the color and transparency of the center of the section
{{Table3613|:**Not used in current builds. Settings entered here will have no effect.}}
:**Syntax: '''''Color''''', red, green, blue, alpha, respectively, value from 0 to 255
:***Example: 255 255 255 255
:*'''+RGBA Outer:'''
:**Defines the color and transparency of the edges of the section
{{Table3613|:**Not used in current builds. Settings entered here will have no effect.}}
:**Syntax: '''''Color''''', red, green, blue, alpha, respectively, value from 0 to 255
:***Example: 150 150 150 10
:*'''+Flicker:'''
:**Defines how much the section flickers
:**Syntax: '''''Float''''', value from 0 to 1
:*'''+Zadd:'''
:**Defines the 'thickness' of the section. The higher the Zadd, the closer the section appears to be.
:**Syntax: '''''Float'''''
{{Table3610|
:*'''+Tile Factor:'''
:**Defines the beam texture tiling factor. Second number defines the tiling type. Type 0 tiles the graphic in the beam as many times as defined by the 1st number. Type 1 uses the 1st value as the lenght of the tile.
:**Syntax: '''''Float''''', '''''Integer'''''
:*'''+Translation:'''
:**Defines the speed of translation of the beam, a positive value moves from the impact point to the firing point, while a negative value moves away from the firing point towards the impact point. Measured in tiles per second, where the tile count is defined in the "+Tile Factor:" field above.
:**Syntax: '''''Float'''''}}

===$Pspew:===
{{Table3610|
*Defines a particle spew effect for the given weapon
}}{{Table3613|
*'''+Index:'''
**indicates which spewer to add/edit/delete. may be 0-3. used for xmt compatibility.
**Syntax: '''''Integer'''''
*'''+Remove'''
**removes spewer at +Index: (requires +index:)
*'''+Type:'''
**type of particle spew
**Syntax: '''''String'', Default, Helix, Sparkler, Ring, or Plume '''
}}{{Table3610|
*'''+Count:'''
**Defines how many particles are spawn when they are ready to be created (at each +Time: interval)
**Syntax: '''''Integer'''''
*'''+Time:'''
**Defines the time in milliseconds between next particle(s) spewed
**Syntax: '''''Integer''''', milliseconds
*'''+Vel:'''
**Defines the created particles velocity as percentage of the weapons velocity
**Syntax: '''''Float'''''
*'''+Radius:'''
**Defines the size of the created particles
**Syntax: '''''Float''''', meters
*'''+Life:'''
**Defines how long the particles last.
**Syntax: '''''Float''''', seconds
*'''+Scale:'''
**Defines the particle spread. Small value will make particles group together
**typically controls how big the effect is or how fast it moves away from the weapon path on a perpendicular (or sometimes arbitrary) axis.
**helical spews and rings use this value to control how fast the particle helix moves away from the central axis.
**sparklers use this to control how fast particles move away from the spawn point, in any direction
**plumes use this to set the diameter of the disk across which particles are spawned
**Syntax: '''''Float'''''
}}{{Table3613|
*'''+Z Scale:'''
**for sparklers, allows you to elongate the effect to surround other effects, like lasers. essentially a length multiplier
**for plume, it multiplies against +scale to set the plume to spread or converge, zero would be full convergence, 1 would be straight flight, and bigger numbers would cause particles to diverge from the disk.
**Syntax: '''''Float'''''
*'''+Rotation Rate:'''
**used only by helical spews, controls how many rotations per second the helix makes
**Syntax: '''''Float'', may be negative, useful for setting up 2 spews that spin in opposite directions'''
*'''+Offset:'''
**position of effect with regards to the weapon center
**Syntax: '''''Vector'''''
*'''+Initial Velocity:'''
**to indicate both direction and speed of particle effects regards to the weapon velocity and +scale:
**Syntax: '''''Vector'''''
}}{{Table3610|
*'''+Bitmap:
**Defines the animation used to create the particle spew effect
**Syntax: '''''String''''', filename}}

===$Tag:===
*Allowed for secondary weapons
{{Table3610|
*Allowed for primary weapons and secondary weapons}}

*Sets this weapon as a TAG missile, level 1, 2, or 3. The second number is the duration in seconds.
*TAG Level 1 will illuminate hidden targets such as stealth fighters or ships normally obscured by nebula conditions.
*TAG Level 2 illiminates targets much like TAG Level 1, but turrets will prefer to shoot at them over other ships.
*TAG Level 3 has no effect in retail.
{{Table3610|
*TAG Level 3 allows the weapon to trigger [[Weapon.tbl#$SSM:|SSMs]]}}

*Syntax: '''''Integer''''' '''''Float''''', TAG level and seconds respectively
*'''Note''': TAG will not trigger unless the weapon in question has a non-zero damage value.

===$SSM:===
{{Table3610|
*Defines the weapons SSM index number.
*Requires [[Weapons.tbl#$Tag:|TAG level 3]] or a targeting beam.
*Syntax: '''''Integer'''''}}
{{Table373|
*Now also accepts SSM strike names.
*Syntax: '''''String'''''}}

===$FOF:===
{{Table3610|
*Defines the field of fire for the weapon. Causes weapon to fire into a firing cone instead of direct firing line thus causing light inaccuracy
*Syntax: '''''Float''''', degrees}}

===$Shots:===
{{Table3610|
*Defines the number of shots every time the weapon is fired.
*Works only for primary weapons
*Syntax: '''''Integer''''', number of shots}}

===$decal:===
{{Table3610|
*Defines impact decals if they are in use
*'''+texture:'''
**Defines the texture used for impact decals (can use '''''-burn''''' and '''''-glow''''' textures)
**Syntax: '''''String''''', filename
*'''+backface texture:'''
**Defines ???
**Syntax: '''''String''''', filename
*'''+radius:'''
**Defines the size of the impact decals on target
**Syntax: '''''Float''''', meters
*'''+burn time:'''
**Defines the time the '''''-burn''''' texture appears on the target
**Syntax: '''''Integer''''', milliseconds}}
{{Table3613|
*Feature removed - table parsing retained to maintain compatibility}}

===$Transparent:===
{{Table3610|
*Defines weapon effect as transparent. Enables optional fields for 'alpha animations'
*'''+Alpha:'''
**Defines the strenght of the alpha (transparency). And also the maximum value for the alpha cycle option
**Syntax: '''''Float''''', from 0 to 1
*'''+Alpha Min:'''
**Defines the minimum alpha value for alpha cycle option
**Syntax: '''''Float''''', from 0 to 1
*'''+Alpha Cycle:'''
**Defines the change in alpha per frame, between '''Alpha''' and '''Alpha Min''' values
**Syntax: '''''Float'''''}}

===$Weapon Hitpoints:===
{{Table3611|
*Defines the amount of hitpoints a weapon has.
*Weapons with '''"bomb"''' flag have 50 hitpoints by default
*Giving weapon hitpoints makes it possible for the weapon to be shot down or be destroyed by EMP.
**Syntax: '''''Integer'''''
}}

===$Armor Type:===
{{Table3613|
*REQUIRES ADDITIONAL TABLE. Defines the armor type for the weapon. This works exactly like ship armor types.
**Syntax: '''''String''''', name of the armor as defined in [[armor.tbl]]
}}

===$Burst Shots:===
{{Table3611|
*Defines the number of shots in a burst
*Shots in a burst use shorter ( '''$Burst Delay:''' ) delay than usually
**Syntax: '''''Integer'''''}}

===$Burst Delay:===
{{Table3611|
*Defines the time in milliseconds between the shots in a burst
**Syntax: '''''Integer'''''}}

===$Burst Flags:===
{{Table3611|
*Defines the flags used to define the burst firing behaviour
**Syntax: ( '''''String''''' '''''String''''' ), list of flags
**Available burst flags:
***'''"fast firing"''', acts as if '''same turret cooldown''' flag would be used between the shots in the burst.
***'''"random length"''', makes AI to fire burst of random length (from 1 to burst shots).}}

===$Thruster Flame Effect:===
{{Table3611|
*Defines the filename of the effect used on the modeled thruster of the missile
**Syntax: '''''String''''', filename}}

===$Thruster Glow Effect:===
{{Table3611|
*Defines the filename of the effect used on the glow type effect of the missile
**Syntax: '''''String''''', filename}}

===$Thruster Glow Radius Factor:===
{{Table3611|
*Defines the radius multiplier for the thruster's glow type effect
**Syntax: '''''Float'''''}}

===$Substitute:===
{{Table3613|
Defines a pattern of ammo to substitute for primary or secondary weapons. '''$Substitute:''' can be repeated any number of times (so you could make something like a rainbow laser with several ammo substitutions, for example). If neither ''+period'' or ''+index'' is specified, it is assumed to be equivalent to ''+index: '''0'''''.

*Syntax: '''''Weapon Name'''''
*'''Swarm missiles act in a strange way when used with $Substitute, use at your own risk.'''}}

{{Table3615|
Turrets can use $Substitute as well.
}}
====+period:====
{{Table3613|
FSO will substitute '''Weapon Name''' every ''period'' shots.

*Syntax: '''''Positive Integer'''''
*'''You may not define both +period and +index for the same $Substitute entry'''}}
=====+offset:=====
{{Table3613|
A suboption of +period, offsets the substitute pattern according to the launched ammo. For example, an offset of 3 and a period of 4 will substitute on the 3rd ammo launched, and then every 4th ammo after that.

*Syntax: '''''Positive Integer'''''}}

====+index:====
{{Table3613|
FSO will substitute the '''Weapon Name''' at firepoint ''index'' in the shot pattern. Similar to carefully using both +period and +offset, but is not affected by ships with different firepoint numbers. i.e. Firepoint ''index'' will always have the substitution, while +period and +offset will cycle at different rates dependant on the number of firepoints.'''

*Syntax: '''''Positive Integer'''''

*'''You may not define both +period and +index for the same $Substitute entry'''}}

==Weapons.tbl Flags==

==="Electronics"===
*Will seize up the weapons and engines systems of any ship for a short period of time.

==="Spawn ''Name'',''Value''"===
*Will spawn the specified number of defined missiles upon detonation.
{{Table3610|
*Multiple spawn types can be defined for a single 'carrier' weapon up to maximum of 5 different weapons}}

==="Remote Detonate"===
*Can be triggered remotely via a second press on the trigger

==="Big Ship"===
*These weapons cannot be mounted on small ships like fighters, bombers, sentry guns etc.

==="Huge"===
*Allows this weapon to do the final 10% damage to a ship with the "Big Damage" flag. Also the AI will not try to hit fighters with it.

==="Supercap"===
*Allows this weapon to do the final 75% damage to a ship with the "supercap" flag.

==="Bomber+"===
*The AI will prefer to use this weapon against bombers

==="child"===
*Cannot be set as a weapon on any ship, but is instead a child of a weapon. Usually defined with "Spawn ''Name'',''Value''"

==="Bomb"===
*Makes this weapon targetable with the B key, and the AI prefers to use it against large ships

==="No Dumbfire"===
*Missile will not fire without a lock

==="in tech database"===
*Has the weapon in the tech database at the start of the campaign

==="Player allowed"===
*Allows this weapon as a player weapon.
{{Table3610|
*'''EXTREMELY IMPORTANT NOTE:'''
**Whenever you plan to use a weapon as a player one in your campaign or missions, '''USE THIS FLAG'''.
**Not using it can cause problems within fs_open and it's a BAD MOD DESIGN.
**In the future, fs_open will maybe be able to avoid these problems but, nevertheless, it's still a BAD DESIGN.
**As another possible example: be careful to update "retail" tables if you plan to use Shivan weapons in player fighters.}}

==="Particle Spew"===
*Makes the weapon projectile spew out particles
{{Table3610|
*Can be defined with [[Weapons.tbl#$Pspew:|Particle Spew parameters]]}}

==="EMP"===
*This weapon will have an EMP effect on any ship within the blast radius
*Can be defined with [[Weapons.tbl#$EMP_Intensity:|EMP Intensity]] and [[Weapons.tbl#$EMP_Time:|EMP Time]]

==="Esuck"===
*Drains the target's energy banks
*Can be defined with [[Weapons.tbl#$Leech_Weapon:|Leech Weapon]] and [[Weapons.tbl#$Leech_Afterburner:|Leech Afterburner]]

==="Flak"===
*Makes this weapon a [[weapons.tbl#Flak_Guns|flak gun]]

==="Corkscrew"===
*Makes this weapon spiral AND swarm 4.
{{Table3610|
*Can be defined with [[Weapons.tbl#$Corkscrew:|Corkscrew parameters]]}}

==="Shudder"===
*Makes your ship shudder while you're firing the weapon

==="lockarm"===
*Requires a target lock in order to arm its warhead. In other words weapon causes less damage if it hits the target without target lock.

==="beam"===
*Makes this weapon a [[weapons.tbl#Beam Cannons|beam cannon]]

==="stream"===
* Does nothing

==="puncture"===
*Reduces hull damage by 75%
The AI will prefer these weapons for anti-subsystem use

==="countermeasure"===
{{Table3610|
*Defines the weapon as a countermeasure}}

==="Ballistic"===
{{Table3610|
*Defines the weapon as a ballistic weapon that needs ammunition.
*Make sure you define the size and reload rate for ballistic weapons}}

==="pierce shields"===
{{Table3610|
*Causes weapons to penetrate shield without causing damage to it.}}

==="no pierce shields"===
{{Table3610|
*Prevents weapons (beams) from piercing shields causing shields to be damaged by weapons first.}}

==="local ssm"===
{{Table3610| }}

==="tagged only"===
{{Table3610|
*Weapon can only be fired at tagged targets}}

==="beam no whack"===
{{Table3610|
*Disables beam whacking (push). Practically same as setting beam mass to zero.}}

==="cycle"===
{{Table3610|
*Causes weapon to alternate between firing points}}

==="small only"===
{{Table3610|
*Causes AI to use the weapon only on small targets (fighters, bombers etc.)}}

==="same turret cooldown"===
{{Table3610|
*Forces the turrets to fire on the designated rate of fire on all difficulty levels and all AI levels}}

==="apply no light"===
{{Table3610|
*Prevents light from being applied to the weapon model.}}

==="training"===
{{Table3610|
*Sets weapon to be of training weapon type. ?}}

==="smart spawn"===
{{Table3611|
*Forces turret fired spawn weapon of this type to be fired like normal weapons.}}

==="inherit parent target"===
{{Table3611|
*Sets spawned 'child' weapons to use parent weapon's target.}}

==="no emp kill"===
{{Table3611|
*Defines the weapon (with hitpoints) to be immune to automatic EMP destruction.}}

==="untargeted heat seeker"===
{{Table3611|
*Defines the weapon as a heatseeker type missile which acquires its target by itself.}}

==="no radius doubling"===
{{Table3611|
*Prevents weapon radius from being doubled when doing collision test. Makes bombs harder to intercept.}}

==="no subsystem homing"===
{{Table3611|
*Prevents weapon from acquiring a subsystem as its target. Missile homing points are spread over the target ship.}}

==="no lifeleft penalty"===
{{Table3611|
*Prevents weapon lifetime from being penalized if the angle to the target is too big.}}

==="can be targeted"===
{{Table3611|
*Allows weapon to be targeted by player. Does not influence AI}}

==="show on radar"===
{{Table3611|
*Allows weapon to be visible on the radar}}

==="show friendly on radar"===
{{Table3611|
*Allows friendly, otherwise visible to radar weapon, to be visible on player radar}}

==="capital+"===
{{Table3613|
*Tells AI to use this weapon only on capital ships}}

==="chain external model fps"===
{{Table3613|
*Tells game to keep switching external model firingpoints when firing}}

==="external model launcher"===
{{Table3613|
*Tells game that the external model is a launcher so that it would be kept static without loading motion}}

==="takes blast damage"===
{{Table3613|
*Weapon takes damage from weapon blasts}}

==="takes shockwave damage"===
{{Table3613|
*Weapon takes damage from shockwaves}}

==="ciws"===
{{Table3615|
*Weapon can deal shockwave/blast damage to bombs, regardless of whether the target weapons have the "take blast/shockwave damage" flags.}}

==="render flak"===
{{Table3615|
*Normally, flak shells are not rendered. This flag switches rendering on for those weapons.}}

==="anti-subsystem beam"===
{{Table3615|
*Beam weapons with this flag can target subsystems on enemy ships, just like normal weapons.}}

==="no primary linking"===
{{Table3615|
*Primary weapons with this flag can not be linked with other weapons.}}

==="same emp time for capships"===
{{Table37|
*capships affected by this weapon will use the tabled EMP time rather than the fixed retail value (7.5 secs)}}

==="no primary linked penalty"===
{{Table371|
*Primary weapons with this flag do not incur the retail linked fire penalty}}

==="no homing speed ramp"===
{{Table371|
*Locked homing weapons will not perform the standard 1 second long acceleration when fired. Note that use of $Acceleration Time is '''not''' affected by this flag.}}

==="pulls aspect seekers"===
{{Table371|
*If an aspect seeker is grabbed by this countermeasure the missile will follow the countermeasure instead of going into dumbfire mode.
'''Only valid for countermeasures!'''}}

==="turret interceptable"===
==="fighter interceptable"===
==="interceptable"===
{{Table371|
*Allows turrets/fighters/both (respectively) to shoot at this weapon without requiring it to be a bomb. If this is the first time this weapon has been defined, it also gives it a default of 25 hitpoints so that it can be shot down.
'''If you use a TBM to give this flag to an existing weapon, you'll need to specify hitpoints manually (unless you want it to be unkillable but still draw defensive fire).'''}}

==="apply recoil"===
{{Table373|
*A ship that fires a weapon with this flag will experience a recoil effect, slowing the ship down and, with lighter strikecraft, inducing some rotation if the firing points are offset from the center of mass.
'''Do not use this with MVPs or retail ships unless you increase their density to 10 or use either $Recoil Modifier: in weapons.tbl or $Ship Recoil Modifier in ships.tbl. This is to avoid exaggerated effects due to retail models having manually defined masses.'''}}

==="don't spawn if shot"===
{{Table373|
*Prevents parent weapons from spawning children in the even of the parent weapon being shot down.}}

==="die on lost lock"===
{{Table373|
*Aspect seeking missiles (only, not heat seekers) will detonate upon losing their lock. Currently they only lose lock if decoyed by a countermeasure, AND "pulls aspect seekers" or similar is not set. The detonation will use their "dinky" explosion (i.e. same as if ran out of lifetime).}}

==Countermeasures==
*Usually not altered. Only one can exist
{{Table3610|
*More than one can exist}}

===$Name:===
*Name of the countermeasure
*Syntax: '''''String''''', name

===$Velocity:===
*Defines the speed of the countermeasure, relative to the ship.
*Syntax: '''''Float''''', meter per second

===$Fire Wait:===
*Definies the minumum time between the countermeasure launches
*Syntax: '''''Float''''', seconds

===Lifetime===
*Countermeasure's life time is defined between with minimum and maximum lifetime
*'''$Lifetime Min:'''
**Syntax: '''''Float''''', seconds
*'''$Lifetime Max:'''
**Syntax: '''''Float''''', seconds

===$LaunchSnd:===
*Defines the sound for the countermeasure launch
*Syntax: '''''Integer''''' or '''''String''''', name or identification number of the sound as defined in [[sounds.tbl]]

===$Model:===
*Defines the used model file (.pof)
*Syntax: '''''String.pof''''', model filename

==Player Weapon Precedence==
*First the primary weapons are defined, from most powerful to least powerful, and then the same for secondaries
*Syntax: ( '''''"String" "String"'''''), names of the weapons
*Example:

<pre>
$Player Weapon Precedence: (
"UD-8 Kayser"
"Prometheus R"
"Subach HL-7"
"Harpoon"
"Tempest"
"Rockeye" )
</pre>

==Sample==

<pre>
#Primary Weapons

$Name: @Subach HL-7
+Title: XSTR("GTW Subach HL-7", 3243)
+Description:
XSTR( "Standard Issue
Level 3 Hull Damage
Level 2 Shield Damage", 3244)
$end_multi_text
+Tech Title: XSTR("Subach HL-7", 146)
+Tech Anim: Tech_Subach_HL-7
+Tech Description:
XSTR(
"Descriptive text...", -1)
$end_multi_text
$Model File: none
@Laser Bitmap: newglo9
@Laser Glow: 2_laserglow03
@Laser Color: 250, 0, 0
@Laser Color2: 0, 0, 250
@Laser Length: 10.0
@Laser Head Radius: 0.90
@Laser Tail Radius: 0.90
$Mass: 0.2
$Velocity: 450.0
$Fire Wait: 0.2
$Damage: 15
$Armor Factor: 0.9
$Shield Factor: 0.7
$Subsystem Factor: 0.3
$Lifetime: 2.0
$Energy Consumed: 0.20
$Cargo Size: 0.0
$Homing: NO
$LaunchSnd: 76
$ImpactSnd: 85
$Flags: ( "in tech database"
"player allowed"
"stream")
$Icon: iconSD4
$Anim: SD4
$Impact Explosion: none

#End

#Secondary Weapons

$Name: EMP Adv.
+Title: XSTR("GTM-14 EMP Adv.", 3396)
+Description:
XSTR( "Advanced Missile
Electromagnetic Pulse Weapon
General Purpose Suppression", 3397)
$end_multi_text
+Tech Title: XSTR("GTM-14 EM Pulse Adv.", 3398)
+Tech Anim: Tech_EMP
+Tech Description:
XSTR(
"Descriptive text...", -1)
$end_multi_text
$Model File: EMPulse2.pof
$Mass: 15.0
$Velocity: 275.0
$Fire Wait: 2.0
$Damage: 45
$Blast Force: 20.0
$Inner Radius: 80.0
$Outer Radius: 300.0
$Shockwave Speed: 120.0
$Armor Factor: 1.0
$Shield Factor: 0.8
$Subsystem Factor: 0.5
$Lifetime: 5.0
$Energy Consumed: 0.0
$Cargo Size: 4.0
$Homing: YES
+Type: ASPECT
+Turn Time: 1.0
+Min Lock Time: 2.0
+Lock Pixels/Sec: 70
+Catch-up Pixels/Sec: 100
+Catch-up Penalty: 30
$LaunchSnd: 118
$ImpactSnd: 88
$FlyBySnd: -1
$Rearm Rate: 2.0
$Flags: ( "player allowed"
"EMP")
$Trail:
+Start Width: 0.25
+End Width: 0.75
+Start Alpha: 1.0
+End Alpha: 0.0
+Max Life: 1.5
+Bitmap: MissileTrail04
$Icon: iconEMPulse
$Anim: ecm
$Impact Explosion: ExpMissileHit1
$Impact Explosion Radius: 10.0
$EMP Intensity: 375.0
$EMP Time: 20.0

#End

$Player Weapon Precedence: (
"Subach HL-7"
"EMP Adv." )
</pre>

[[Category:Tables]]

Particle Effects

2016-08-04T13:08:36Z

M!m: Added example table

{{SCP_table}}

{{TableVersionGit|2016-08-04|a570eca}}

Particle Effects is a SCP feature which allows to define custom particle effects that can be assigned to various engine properties.

This table is one of the [[Modular Tables]] and can be extended with xxx-part.tbm. This table type does not have a main table like the other types. All particle effects must be specified in modular tables. Currently there is no support for the usual ''+nocreate'' ability the other modular tables have but that will be added in the future. Parts of this documentation are written with with ''+nocreate'' in mind for when that is implemented.

[[Tables|List of Tables]]

==General Info==
*Begins with #Particle Effects
*Contains zero or more particle effect definitions
*Ends with #End

Particle effects are created by specifying a name and a type. The type dictates which values are valid and will be described below.

===$Effect:===
*Creates a new effect and specifies its name. The name must be at least one character long.
*Syntax: '''String'''

====$Type:====
*Sets the type of this effect. See [[#Effect Types|Effect Types]] for possible values.
*Syntax: '''String'''

==Effect Types==
There are multiple different types of effects. They are specified by passing the given name to ''$Type''.

===Single===
This effect type creates exactly one particle per processing step.

====Properties====
The properties of this created particle can be specified by a [[#Particle properties]] construct.

====Timing properties====
For specifying how long this effect is active an [[#Effect timing]] construct is used.

===Composite===
A composite effects contains multiple other effects which are all displayed at the same time. The amount of child effects is not limited. This type currently does not support ''+nocreate''.

====+Child effect:====
*This specifies a child effect that should be added to the composite effect. The effect is specified using [[#Inline effect creation]].

===Cone===
This effects creates multiple particles which travel in a cone around a specific direction. The particles are created in a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution] around the direction vector. That means that more particle are created along the direction vector than far away from it. The velocity of a particle is scaled based on the angle it is away from the direction vector. This may be changed in the future to allow different effects.

====Properties====
The common properties of the created particles can be specified by a [[#Particle properties]] construct.

====+Deviation:====
*Sets the standard deviation from the direction vector.
*Required if ''+nocreate'' is not present
*Syntax: '''float''', in degrees

====+Velocity====
*Sets the velocity of the created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

====+Number====
*Sets the amount of created particles. This is a [[#Uniform random range]].
*Required if ''+nocreate'' is not present
*Syntax: See [[#Uniform random range]]

====+Direction====
*Sets the direction the cone will be centered around. Can be one of:
**''Incoming'': The direction vector is the direction of the particle source, e.g. for a weapon this would be the orientation it had when the effect was created.
**''Normal'': The normal of the impact.
**''Reflected'': The reflected vector from incoming and normal vector. This is a good way of simulating armor deflecting a shot.
**''Reverse'': The reverse of the incoming vector
*Optional
*Syntax: '''String''', one of the strings specified above

====+Trail effect:====
*Sets the particle effect used for the trail of the created particles. This option uses [[#Inline effect creation]].
*Optional
*Syntax: See [[#Inline effect creation]].

==Common syntax constructs==
Some syntax constructs are used multiple times by different types. Due to the similarity they are described one at this point and then references by the documentation of the individual effects.

===Particle properties===
This contains some common properties of particles, e.g. the used animation or the size.

====+Filename:====
*Sets the filename of the animation that should be used.
*Required if ''+nocreate'' wasn't used
*Syntax: '''String''', filename

====+Size:====
*Sets the size of the created particles. This is a uniformly distributed random range, see [[#Uniform random range]].
*Required if ''+nocreate'' wasn't used
*Syntax: See [[#Uniform random range]]

====+Lifetime:====
*Sets the life time of the particles. This is a uniformly distributed random range, see [[#Uniform random range]], or the string ''<none>'' in which case the runtime of the animation is used. Defaults to ''<none>''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===Effect timing===
Effect timings are used to specify for how long and after how much delay an effect is active. Each effect timing is parsed in its entirety each time it is expected. That means that if you use ''+nocreate'' then you must respecify all values. This restriction may be lifted in the future.

====+Duration:====
*Sets for how long this effect will be active. The duration can be once, always or a random range. If the effect should run only once then you can use the string ''Onetime''. If the effect should always be active you can specify the string ''Always''. Otherwise a non-negative random range is expected.
*This is optional
*Syntax: ''Onetime'', ''Always'', or a [[#Uniform random range]].

====+Delay:====
*Specifies after how much time after the effect is triggered the effect starts creating particles. This is not a valid option if the duration is ''Onetime''.
*This is optional
*Syntax: See [[#Uniform random range]], or the string ''<none>''

===Inline effect creation===
At some places in this table a particle effect may be created within another particle effect. This is used for composite effects and particle trails. If inline creation is valid for an option then you may either specify a name of a previously defined effect or use '''$New Effect''' which will create a new, unnamed effect. Some options using this construct require a specific type of effect. That will be noted in the documentation of the option.

If '''$New Effect''' is used then a new unnamed effect is created. If the surrounding option has not forced an effect type then you can specify it using the standard syntax described above. All options are the same as if the effect would have been parsed in the normal way. ''+nocreate'' is not valid within this element.

===Random range===
The particle effect system uses randomization to provide variation to the created particles. This is implemented by letting the mod author specify the values for the random distribution. There are different types of distributions which are explained below.

====Uniform random range====
*This accepts 1 or 2 values. If one value is used then the random range always returns that value. If two values are specified then a uniformly distributed random value will be picked from the range.
*Syntax: '''Float list''', one or two values

====Normal distribution random range====
*This accepts 1 or 2 values. This random range generates values according to a [https://en.wikipedia.org/wiki/Normal_distribution normal distribution]. The first value specified the mean value of the distribution. The second value specified the standard deviation of the distribution, this defaults to 1.
*Syntax: '''Float list''', one or two values

==Example==
<pre>
#Particle Effects

$Effect: MassDriverImpact
$Type: Cone
+Filename: exp05
+Size: (5 7)
+Lifetime: (0.6)
+Deviation: 5
+Velocity: (500 700)
+Number: (20 30)
+Direction: Reflected
+Trail effect: $New Effect
$Type: Single
+Filename: exp20
+Size: (10)
+Lifetime: (1)
+Duration: Always

$Effect: ApocalypseIgnition
$Type: Single
+Filename: exp20
+Size: (10 20)

$Effect: ApocalypseHomed
$Type: Composite
+Child effect: $New Effect
$Type: Single
+Filename: exp05
+Size: (5 7)
+Duration: (2 10)
+Child effect: $New Effect
$Type: Single
+Filename: exp06b
+Size: (5 7)
+Duration: (2 10)
+Delay: (8 15)

#End
</pre>