Difference between revisions of "Dynamic SEXPs"

From FreeSpace Wiki
Jump to: navigation, search
 
(15 intermediate revisions by 3 users not shown)
Line 6: Line 6:
 
==Table syntax==
 
==Table syntax==
 
This section will describe the syntax and effects of the individual options.
 
This section will describe the syntax and effects of the individual options.
 +
 +
===#Lua Enums===
 +
 +
{{Table232|
 +
Specifies lists of dynamic Enums that can be referenced in in Lua sexps This section must end with <tt>#End</tt>}}
 +
 +
====$Name:====
 +
{{Table232|
 +
*The name of this enum list. Must be unique.
 +
*Syntax: '''''String'''''}}
 +
 +
====+Enum:====
 +
{{Table232|
 +
*The enum item itself.
 +
*No limit to the number of enums listed
 +
*Syntax: '''''String'''''}}
  
 
===#Lua SEXPs===
 
===#Lua SEXPs===
Line 83: Line 99:
 
**; soundentry: This is a reference to a table defined game sound. The script will receive it as a <tt>soundentry</tt> handle.
 
**; soundentry: This is a reference to a table defined game sound. The script will receive it as a <tt>soundentry</tt> handle.
 
{{Table220|
 
{{Table220|
**; ship+waypoint: This can be a reference to either a ship, both present and not yet present, or a waypoint. The script will recieve it as an <tt>oswpt</tt> handle.
+
**; ship+waypoint: This can be a reference to either a ship, both present and not yet present, or a waypoint. The script will receive it as an <tt>oswpt</tt> handle.
**; ship+wing: This can be a reference to either a ship or a wing, both present and not yet present. The script will recieve it as an <tt>oswpt</tt> handle.
+
**; ship+wing: This can be a reference to either a ship or a wing, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
**; ship+wing+team: This can be a reference to either a ship, a wing or a whole team, both present and not yet present. The script will recieve it as an <tt>oswpt</tt> handle.
+
**; ship+wing+team: This can be a reference to either a ship, a wing or a whole team, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
**; ship+wing+ship_on_team+waypoint: This can be a reference to either a ship, a wing, any ship on a team, or a waypoint, both present and not yet present. The script will recieve it as an <tt>oswpt</tt> handle.
+
**; ship+wing+ship_on_team+waypoint: This can be a reference to either a ship, a wing, any ship on a team, or a waypoint, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
**; ship+wing+waypoint: This can be a reference to either a ship, a wing, or a waypoint, both present and not yet present. The script will recieve it as an <tt>oswpt</tt> handle.
+
**; ship+wing+waypoint: This can be a reference to either a ship, a wing, or a waypoint, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
**; ship+wing+waypoint+none: This can be a reference to either a ship, a wing, a waypoint, both present and not yet present, or none. The script will recieve it as an <tt>oswpt</tt> handle.
+
**; ship+wing+waypoint+none: This can be a reference to either a ship, a wing, a waypoint, both present and not yet present, or none. The script will receive it as an <tt>oswpt</tt> handle.
 +
}}
 +
{{Table224|
 +
**; enum: A pre-defined enumeration list. The script will receive it as a string.
 +
}}
 +
{{Table232|
 +
**; hudgauge: This is a reference to any built-in or custom hud gauge. The script will receive it as a <tt>hudgauge</tt> handle.
 +
**; event: This is a reference to existing mission events. The script will receive it as an <tt>event</tt> handle.
 +
**; subsystem: This is a reference to a ship's subsystems and requires [[Dynamic_SEXPs#+Parent Parameter Index:|+Parent Parameter Index]]. The script will receive it as a <tt>subsystem</tt> handle.
 +
**; dockpoint: This is a reference to a ship's docking points and requires [[Dynamic_SEXPs#+Parent Parameter Index:|+Parent Parameter Index]]. The script will receive it as a <tt>dockingbay</tt> handle.
 +
}}
 +
{{Table234|
 +
**; waypoint: This is a reference to a waypoint. The script will receive it as an <tt>oswpt</tt> handle.
 +
**; child_enum: A pre-defined enumeration list, but gets the list name from [[Dynamic_SEXPs#+Parent Parameter Index:|+Parent Parameter Index]]. Can optionally use [[Dynamic_SEXPs#+Suffix:|+Suffix]]. The script will receive it as a string.
 
}}
 
}}
 
*Syntax: '''''String'''''
 
*Syntax: '''''String'''''
 +
 +
====+Enum name:====
 +
{{Table224|
 +
*Required if the +Type is an enum.
 +
*The name of the enum list.
 +
{{Table232|
 +
*Can reference a pre-parsed enum list.}}
 +
*Syntax: '''''String'''''}}
 +
 +
====+Enum:====
 +
{{Table224|
 +
*An item to add to the enum list.
 +
*As many +Enum: entries can be specified as needed.
 +
{{Table232|
 +
*If +Enum Name references a pre-parsed enum list and this field is used, then it will add to that list just for this specific sexp.}}
 +
*Syntax: '''''String'''''}}
 +
 +
====+Parent Parameter Index:====
 +
{{Table232|
 +
*The zero-based index to the parent parameter that should be used for types that require it.
 +
*If [[Dynamic_SEXPs#$Repeat|$Repeat]] is used then the last parsed index is the one that will be repeated.
 +
*An index setting of -1 will always return the immediately previous sexp argument, even if [[Dynamic_SEXPs#$Repeat|$Repeat]] is active.
 +
*Defaults to -1 if this is not provided for a type that requires it
 +
*Syntax: '''''Integer'''''}}
 +
 +
====+Suffix:====
 +
{{Table240|
 +
*An arbitrary string to suffix to the enum parent's name.
 +
*For example, if the parent enum is a ship type, you can add the suffix and the enum list that will be used will be SHIPNAME + suffix
 +
*Syntax: '''''string'''''}}
  
 
{{Table222|
 
{{Table222|
Line 144: Line 203:
  
 
=====+Target Restrictions:=====
 
=====+Target Restrictions:=====
*If the AI goal requires a target, defines which requirements a ship must fulfill to be a valid target for this order
+
*Requirements a ship must fulfill to be a valid target for this order. This may be fine-tuned by registering a `TargetRestrict` function.
**; All: Any ship is a valid target
+
**; All: Any ship is a valid target.
**; Allies: The target must be of a team that is not attacked by the player
+
**; Allies: The target must be of a team that is not attacked by the player.
**; Own Team: The target must be of the same team as the player
+
**; Own Team: The target must be of the same team as the player.
**; Hostiles: The target must be of a team that is attacked by the player
+
**; Hostiles: The target must be of a team that is attacked by the player.
**; Same Wing: The target and the ship receiving the order must be on the same wing
+
**; Same Wing: The target and the ship receiving the order must be on the same wing.
**; Player Wing: The target and the player must be on the same wing
+
**; Player Wing: The target and the player must be on the same wing.
**; Capitals: The ship must be a capital ship
+
**; Capitals: The ship must be a capital ship (i.e. any large ship, including a transport or freighter).
**; Allied Capitals: The ship must be an ally and a capital ship
+
**; Allied Capitals: The ship must be an ally and a capital ship.
**; Enemy Capitals: The ship must be a hostile and a capital ship
+
**; Enemy Capitals: The ship must be a hostile and a capital ship.
*Optional. All by default
+
**; Not Self: The ship must not be the ship receiving the order.
 +
*Optional. All by default.
 
*Syntax: '''''String'''''
 
*Syntax: '''''String'''''
  
 +
{{Table232|
 +
=====+Ship Restrictions:=====
 +
*Requirements on what can receive this order.
 +
**; Any: Any ship or wing can receive this order.
 +
**; On Player Wing: Only a ship on the player's wing can receive this order.
 +
**; Wing: This order may only be sent to wings, not individual ships.
 +
**; Player Wing: This order may only be sent to the player's wing.
 +
*Optional. All by default.
 +
*Syntax: '''''String'''''
 +
}}
 +
 +
=====+Acknowledge Message:=====
 +
*Once the player gives the player order, this message will be played. Can be any of the messages listed [[Messages.tbl#.24Name:_2|here]].
 +
*Optional, the "Yes Sir!"-message (<tt>yes</tt>) by default.
 +
*Syntax: '''''String'''''
 +
 +
{{Table224|
 +
====$Minimum Additional Arguments:====
 +
*Specifies what minimum number of parameters this SEXP needs to work. If fewer parameters are specified, then the SEXP parser will treat this as an error.
 +
*Optional. 0 by default. Must be at least 0.
 +
*Syntax: '''''Integer'''''
 +
 +
====$Maximum Additional 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.
 +
 +
====$Repeat====
 +
*This option must be combined with the additional parameter specification 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.
 +
 +
====$Additional Parameter:====
 +
*Adds additional parameters beyond the target 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 Additional Arguments</tt> and <tt>$Maximum Additional Arguments</tt>. When called from a player order, all Additional Parameters beyond the Target Parameter will be nil
 +
*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:
 +
**; 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.
 +
**; 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.
 +
**; 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.
 +
**; shipname: This parameter is the name of a ship. Unlike the '''ship''' parameter, the script will receive this value as a <tt>string</tt>. This provides a way to refer to ships which may not be present yet or which may have exited 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.
 +
**; 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.
 +
**; ship+waypoint: This can be a reference to either a ship, both present and not yet present, or a waypoint. The script will receive it as an <tt>oswpt</tt> handle.
 +
**; ship+wing: This can be a reference to either a ship or a wing, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
 +
**; ship+wing+team: This can be a reference to either a ship, a wing or a whole team, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
 +
**; ship+wing+ship_on_team+waypoint: This can be a reference to either a ship, a wing, any ship on a team, or a waypoint, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
 +
**; ship+wing+waypoint: This can be a reference to either a ship, a wing, or a waypoint, both present and not yet present. The script will receive it as an <tt>oswpt</tt> handle.
 +
**; ship+wing+waypoint+none: This can be a reference to either a ship, a wing, a waypoint, both present and not yet present, or none. The script will receive it as an <tt>oswpt</tt> handle.
 +
*Syntax: '''''String'''''
 +
}}
 
}}
 
}}
  
Line 215: Line 336:
 
#End
 
#End
 
</pre>
 
</pre>
 +
 
===Lua AI===
 
===Lua AI===
The setup for Lua AI is very similar to the setup to Lua SEXP, except that two functions must be supplied, one for when the AI starts executing, and one that is called each frame.
+
 
These functions will be passed an AI control helper object that can be used to easily control the ships behaviour from Lua, as well as an oswpt-type object containing the target data, if applicable.
+
LuaAI operators are more complicated than standard Lua operators. They are defined by two main functions and two optional functions.
In addition, the functions are expected to return a boolean value, representing the state of the action. Returning true implies that the action is complete, and that the AI goal should be removed automatically (similarly to how a chase order is removed when the target is killed).
+
 
 +
The <code>ActionEnter</code> and <code>ActionFrame</code> functions define the operator's behavior. <code>ActionEnter</code> is called only once, when a ship receives the order; it may be used for any needed setup. <code>ActionFrame</code> is called once per frame. Both functions receive an <code>ai_helper</code> object, the target (if any), and any additional arguments; they should return <code>true</code> if the order is complete, and <code>false</code> otherwise.
 +
 
 +
The <code>Achievability</code> function defines whether the order is currently achievable. It accepts the ship executing the order, the target (if any), and any additional arguments. It may return <code>LUAAI_ACHIEVABLE</code> if the order can currently be achieved, <code>LUAAI_UNACHIEVABLE</code> if the order cannot be achieved and should be removed from the ship, and <code>LUAAI_NOT_YET_ACHIEVABLE</code> if the order cannot currently be achieved, but may become possible later; this allows an order which doesn't make sense right now to be suspended until later.
 +
 
 +
Lastly, the <code>TargetRestrict</code> function may be used to fine-tune the order's targeting. It accepts a ship and a nilable OSWPT handle representing the target, and returns whether or not the target is valid. This is checked only if the target already satisfies the `+Target Restrictions:`.
  
 
Example:
 
Example:
Line 227: Line 354:
 
$Application: FS2_Open
 
$Application: FS2_Open
 
$On Game Init: [
 
$On Game Init: [
mn.LuaAISEXPs["dynamic-ai"].ActionEnter = function(ai_helper, target)
+
mn.LuaAISEXPs["ai-ram"].ActionEnter = function(ai_helper, target)
 
--Print info to the log
 
--Print info to the log
 
ba.print("Targeting " .. target:get().Name .. " from " .. ai_helper.Ship.Name .. "!")
 
ba.print("Targeting " .. target:get().Name .. " from " .. ai_helper.Ship.Name .. "!")
Line 233: Line 360:
 
end
 
end
  
mn.LuaAISEXPs["dynamic-ai"].ActionFrame = function(ai_helper, target)
+
mn.LuaAISEXPs["ai-ram"].ActionFrame = function(ai_helper, target)
 
--Turn towards and fly into the target
 
--Turn towards and fly into the target
 
helper:turnTowardsPoint(target:get().Position)
 
helper:turnTowardsPoint(target:get().Position)
 
helper.ForwardThrust = 1
 
helper.ForwardThrust = 1
 
return false
 
return false
 +
end
 +
 +
mn.LuaAISEXPs["ai-ram"].Achievability = function(ship, target)
 +
if ship.Disabled then
 +
-- Contrived example
 +
return LUAAI_NOT_YET_ACHIEVABLE
 +
elseif target:isValid() then
 +
return LUAAI_ACHIEVABLE
 +
else
 +
return LUAAI_UNACHIEVABLE
 +
end
 
end
 
end
 
]
 
]

Latest revision as of 21:15, 6 May 2024

List of Tables and related code files
* Notes Modular Tables
** Notes tables which only use modular tables
Ai.tbl* /ai/aicode.cpp
Ai_profiles.tbl* /ai/ai_profiles.cpp
Animation.tbl** /model/modelanimation.cpp
Armor.tbl* /ship/ship.cpp
Asteroid.tbl* /asteroid/asteroid.cpp
Autopilot.tbl* /autopilot/autopilot.cpp
Cheats.tbl* /cheats_table/cheats_table.cpp
Colors.tbl* /globalincs/alphacolors.cpp
Curves.tbl* /math/curves.cpp
Controlconfigdefaults.tbl /controlconfig/controlsconfigcommon.cpp
Credits.tbl* /menuui/credits.cpp
Cutscenes.tbl* /cutscene/cutscenes.cpp
Decals.tbl** /decals/decals.cpp
Fireball.tbl* /fireball/fireballs.cpp
Fonts.tbl* /graphics/font.cpp
Game_settings.tbl* /mod_table/mod_table.cpp
Glowpoints.tbl* /model/modelread.cpp
Help.tbl* /gamehelp/contexthelp.cpp
Hud_gauges.tbl* /hud/hudparse.cpp
Icons.tbl* /mission/missionbriefcommon.cpp
Iff_defs.tbl* /iff_defs/iff_defs.cpp
Keywords.tbl* Not In Codebase
Lighting_Profiles.tbl* /lighting/lighting_profiles.cpp
Lightning.tbl* /nebula/neblightning.cpp
Mainhall.tbl* /menuui/mainhallmenu.cpp
Medals.tbl* /stats/medals.cpp
Messages.tbl* /mission/missionmessage.cpp
Mflash.tbl* /weapon/muzzleflash.cpp
Music.tbl* /gamesnd/eventmusic.cpp
Nebula.tbl* /nebula/neb.cpp
Objecttypes.tbl* /ship/ship.cpp
Options.tbl* Not In Codebase
Particle effects(-part.tbm)** /particle/effects...
Post_processing.tbl /graphics/gropenglpostprocessing.cpp
Rank.tbl* /stats/scoring.cpp
Scpui.tbl* Not In Codebase
Scripting.tbl* /parse/scripting.cpp
Ships.tbl* /ship/ship.cpp
Sexps.tbl** /parse/sexp/sexp_lookup.cpp
Sounds.tbl* /gamesnd/gamesnd.cpp
Species_defs.tbl* /species_defs/species_defs.cpp
Species.tbl* /menuui/techmenu.cpp
Ssm.tbl* /hud/hudartillery.cpp
Stars.tbl* /starfield/starfield.cpp
Strings.tbl* /localization/localize.cpp
Tips.tbl* /menuui/playermenu.cpp
Traitor.tbl* /stats/scoring.cpp
Tstrings.tbl* /localization/localize.cpp
Virtual_pofs.tbl* /model/modelreplace.cpp
Weapon_expl.tbl* /weapon/weapons.cpp
Weapons.tbl* /weapon/weapons.cpp

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 -sexp.tbm

Table syntax

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

#Lua Enums

FS2 Open, 23.2: Specifies lists of dynamic Enums that can be referenced in in Lua sexps This section must end with #End

$Name:

FS2 Open, 23.2:
  • The name of this enum list. Must be unique.
  • Syntax: String

+Enum:

FS2 Open, 23.2:
  • The enum item itself.
  • No limit to the number of enums listed
  • Syntax: String

#Lua SEXPs

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

$Operator:

  • Adds a new SEXP operator with the specified name. The name may not contain the following characters: ()\"'. 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 cloak- 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 cloak-disable.
  • 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 what minimum number of parameters this SEXP needs to work. If fewer 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) 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 $Minimum Arguments and $Maximum Arguments.
  • 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:
    • 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.
      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.
      ship
      This parameter is the name of a ship. The script will receive this value as a ship 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 ship handle.
      shipname
      This parameter is the name of a ship. Unlike the ship parameter, the script will receive this value as a string. This provides a way to refer to ships which may not be present yet or which may have exited 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 team handle.
      waypointpath
      This parameter is a reference to a specific waypoint path. The script will receive this as a waypointlist 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 sexpvariable handle.
      message
      This is a reference to a mission message. The script will receive it as a message handle.
      wing
      This is a reference to a wing in the mission. The script will receive it as a wing handle.
      shipclass
      This is a reference to a table ship class. The script will receive it as a shipclass handle.
      weaponclass
      This is a reference to a table weapon class. The script will receive it as a weaponclass handle.
      soundentry
      This is a reference to a table defined game sound. The script will receive it as a soundentry handle.
FS2 Open, 22.0:
    • ship+waypoint
      This can be a reference to either a ship, both present and not yet present, or a waypoint. The script will receive it as an oswpt handle.
      ship+wing
      This can be a reference to either a ship or a wing, both present and not yet present. The script will receive it as an oswpt handle.
      ship+wing+team
      This can be a reference to either a ship, a wing or a whole team, both present and not yet present. The script will receive it as an oswpt handle.
      ship+wing+ship_on_team+waypoint
      This can be a reference to either a ship, a wing, any ship on a team, or a waypoint, both present and not yet present. The script will receive it as an oswpt handle.
      ship+wing+waypoint
      This can be a reference to either a ship, a wing, or a waypoint, both present and not yet present. The script will receive it as an oswpt handle.
      ship+wing+waypoint+none
      This can be a reference to either a ship, a wing, a waypoint, both present and not yet present, or none. The script will receive it as an oswpt handle.
FS2 Open, 23.0:
    • enum
      A pre-defined enumeration list. The script will receive it as a string.
FS2 Open, 23.2:
    • hudgauge
      This is a reference to any built-in or custom hud gauge. The script will receive it as a hudgauge handle.
      event
      This is a reference to existing mission events. The script will receive it as an event handle.
      subsystem
      This is a reference to a ship's subsystems and requires +Parent Parameter Index. The script will receive it as a subsystem handle.
      dockpoint
      This is a reference to a ship's docking points and requires +Parent Parameter Index. The script will receive it as a dockingbay handle.
FS2 Open, 24.0:
    • waypoint
      This is a reference to a waypoint. The script will receive it as an oswpt handle.
      child_enum
      A pre-defined enumeration list, but gets the list name from +Parent Parameter Index. Can optionally use +Suffix. The script will receive it as a string.
  • Syntax: String

+Enum name:

FS2 Open, 23.0:
  • Required if the +Type is an enum.
  • The name of the enum list.
FS2 Open, 23.2:
  • Can reference a pre-parsed enum list.
  • Syntax: String
  • +Enum:

    FS2 Open, 23.0:
    • An item to add to the enum list.
    • As many +Enum: entries can be specified as needed.
    FS2 Open, 23.2:
    • If +Enum Name references a pre-parsed enum list and this field is used, then it will add to that list just for this specific sexp.
  • Syntax: String
  • +Parent Parameter Index:

    FS2 Open, 23.2:
    • The zero-based index to the parent parameter that should be used for types that require it.
    • If $Repeat is used then the last parsed index is the one that will be repeated.
    • An index setting of -1 will always return the immediately previous sexp argument, even if $Repeat is active.
    • Defaults to -1 if this is not provided for a type that requires it
    • Syntax: Integer

    +Suffix:

    FS2 Open, 24.0:
    • An arbitrary string to suffix to the enum parent's name.
    • For example, if the parent enum is a ship type, you can add the suffix and the enum list that will be used will be SHIPNAME + suffix
    • Syntax: string


    FS2 Open, 22.2:

    #Lua AI

    Specifies new SEXPs that can be used as AI-goals in FRED, which execute custom Lua script.

    $Operator:

    • Adds a new SEXP operator with the specified name. The name may not contain the following characters: ()\"'. 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.
    • 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

    $Description:

    • Sets the help text displayed in the FRED help box. This should be the generic description of what this AI Goal does.
    • Syntax: String

    +HUD String:

    • If set, this string will be displayed when targeting a ship executing this AI goal, similar to "attacking" when given a chase goal.
    • Optional.
    • Syntax: String

    $Target Parameter:

    • If set, this AI mode will take a target as the first parameter of the AI goal SEXP.
    • Optional.
    +Description:
    • The description of the target parameter
    • Syntax: String
    +Type:
    • The type the target parameter requires. The script will receive all of the following parameter types as an oswpt handle. Only the following are permitted:
      • ship
        This parameter is the name of a ship.
        wing
        This is a reference to a wing in the mission.
        ship+waypoint
        This can be a reference to either a ship, both present and not yet present, or a waypoint.
        ship+wing
        This can be a reference to either a ship or a wing, both present and not yet present.
        ship+wing+team
        This can be a reference to either a ship, a wing or a whole team, both present and not yet present.
        ship+wing+ship_on_team+waypoint
        This can be a reference to either a ship, a wing, any ship on a team, or a waypoint, both present and not yet present.
        ship+wing+waypoint
        This can be a reference to either a ship, a wing, or a waypoint, both present and not yet present.
        ship+wing+waypoint+none
        This can be a reference to either a ship, a wing, a waypoint, both present and not yet present, or none.
    • Syntax: String

    $Player Order:

    • If set, this AI mode will be available as a player order (in the comms menu). As of now only 16 more player orders can be registered like this. Any player order registered like this also needs to be added as a valid player order in the Objecttypes.tbl table. Player orders must have either no target parameter at all, or a target parameter of the ship type.
    • Optional.
    +Display String:
    • The name of the order shown to the player in the comms menu
    • Syntax: String
    +Parse String:
    • The name of the order as it needs to be entered in the Objecttypes.tbl.
    • Optional. Equal to the display string by default.
    • Syntax: String
    +Target Restrictions:
    • Requirements a ship must fulfill to be a valid target for this order. This may be fine-tuned by registering a `TargetRestrict` function.
      • All
        Any ship is a valid target.
        Allies
        The target must be of a team that is not attacked by the player.
        Own Team
        The target must be of the same team as the player.
        Hostiles
        The target must be of a team that is attacked by the player.
        Same Wing
        The target and the ship receiving the order must be on the same wing.
        Player Wing
        The target and the player must be on the same wing.
        Capitals
        The ship must be a capital ship (i.e. any large ship, including a transport or freighter).
        Allied Capitals
        The ship must be an ally and a capital ship.
        Enemy Capitals
        The ship must be a hostile and a capital ship.
        Not Self
        The ship must not be the ship receiving the order.
    • Optional. All by default.
    • Syntax: String


    FS2 Open, 23.2:
    +Ship Restrictions:
    • Requirements on what can receive this order.
      • Any
        Any ship or wing can receive this order.
        On Player Wing
        Only a ship on the player's wing can receive this order.
        Wing
        This order may only be sent to wings, not individual ships.
        Player Wing
        This order may only be sent to the player's wing.
    • Optional. All by default.
    • Syntax: String
    +Acknowledge Message:
    • Once the player gives the player order, this message will be played. Can be any of the messages listed here.
    • Optional, the "Yes Sir!"-message (yes) by default.
    • Syntax: String


    FS2 Open, 23.0:

    $Minimum Additional Arguments:

    • Specifies what minimum number of parameters this SEXP needs to work. If fewer parameters are specified, then the SEXP parser will treat this as an error.
    • Optional. 0 by default. Must be at least 0.
    • Syntax: Integer

    $Maximum Additional 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.

    $Repeat

    • This option must be combined with the additional parameter specification 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) to make it easier to use the values without having to separate them again in the script.

    $Additional Parameter:

    • Adds additional parameters beyond the target and specifies what type they need to have. This option may appear multiple times and should match the number of parameters specified by $Minimum Additional Arguments and $Maximum Additional Arguments. When called from a player order, all Additional Parameters beyond the Target Parameter will be nil
    • 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:
      • 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.
        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.
        ship
        This parameter is the name of a ship. The script will receive this value as a ship 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 ship handle.
        shipname
        This parameter is the name of a ship. Unlike the ship parameter, the script will receive this value as a string. This provides a way to refer to ships which may not be present yet or which may have exited 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 team handle.
        waypointpath
        This parameter is a reference to a specific waypoint path. The script will receive this as a waypointlist 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 sexpvariable handle.
        message
        This is a reference to a mission message. The script will receive it as a message handle.
        wing
        This is a reference to a wing in the mission. The script will receive it as a wing handle.
        shipclass
        This is a reference to a table ship class. The script will receive it as a shipclass handle.
        weaponclass
        This is a reference to a table weapon class. The script will receive it as a weaponclass handle.
        soundentry
        This is a reference to a table defined game sound. The script will receive it as a soundentry handle.
        ship+waypoint
        This can be a reference to either a ship, both present and not yet present, or a waypoint. The script will receive it as an oswpt handle.
        ship+wing
        This can be a reference to either a ship or a wing, both present and not yet present. The script will receive it as an oswpt handle.
        ship+wing+team
        This can be a reference to either a ship, a wing or a whole team, both present and not yet present. The script will receive it as an oswpt handle.
        ship+wing+ship_on_team+waypoint
        This can be a reference to either a ship, a wing, any ship on a team, or a waypoint, both present and not yet present. The script will receive it as an oswpt handle.
        ship+wing+waypoint
        This can be a reference to either a ship, a wing, or a waypoint, both present and not yet present. The script will receive it as an oswpt handle.
        ship+wing+waypoint+none
        This can be a reference to either a ship, a wing, a waypoint, both present and not yet present, or none. The script will receive it as an oswpt handle.
    • Syntax: String

    Example

    #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
    

    Lua interface

    Lua SEXPs

    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 mn.LuaSEXPs variable. This is a variable which can be indexed using the SEXP name. The returned value is of type LuaSEXP which only has a single field, Action. 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 $On Game Init 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 ... 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 nil 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.

    #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
    

    Lua AI

    LuaAI operators are more complicated than standard Lua operators. They are defined by two main functions and two optional functions.

    The ActionEnter and ActionFrame functions define the operator's behavior. ActionEnter is called only once, when a ship receives the order; it may be used for any needed setup. ActionFrame is called once per frame. Both functions receive an ai_helper object, the target (if any), and any additional arguments; they should return true if the order is complete, and false otherwise.

    The Achievability function defines whether the order is currently achievable. It accepts the ship executing the order, the target (if any), and any additional arguments. It may return LUAAI_ACHIEVABLE if the order can currently be achieved, LUAAI_UNACHIEVABLE if the order cannot be achieved and should be removed from the ship, and LUAAI_NOT_YET_ACHIEVABLE if the order cannot currently be achieved, but may become possible later; this allows an order which doesn't make sense right now to be suspended until later.

    Lastly, the TargetRestrict function may be used to fine-tune the order's targeting. It accepts a ship and a nilable OSWPT handle representing the target, and returns whether or not the target is valid. This is checked only if the target already satisfies the `+Target Restrictions:`.

    Example:

    #Conditional Hooks
    
    $Application: FS2_Open
    $On Game Init: [
    mn.LuaAISEXPs["ai-ram"].ActionEnter = function(ai_helper, target)
    	--Print info to the log
    	ba.print("Targeting " .. target:get().Name .. " from " .. ai_helper.Ship.Name .. "!")
    	return false
    end
    
    mn.LuaAISEXPs["ai-ram"].ActionFrame = function(ai_helper, target)
    	--Turn towards and fly into the target
    	helper:turnTowardsPoint(target:get().Position)
    	helper.ForwardThrust = 1
    	return false
    end
    
    mn.LuaAISEXPs["ai-ram"].Achievability = function(ship, target)
    	if ship.Disabled then
    		-- Contrived example
    		return LUAAI_NOT_YET_ACHIEVABLE
    	elseif target:isValid() then
    		return LUAAI_ACHIEVABLE
    	else
    		return LUAAI_UNACHIEVABLE
    	end
    end
    ]
    
    #End