Scripting Engine Introduction
Contents
Intro
The Simulator Scripting Engine, SSE for short, is a feature that was initially introduced with the release of DCS: A-10C Warthog. The scripting engine provides mission designers with access to game world and game objects using scripts. It's possible to change object properties, control object behavior and read object properties. The scripting engine was developed primary to expand upon the possibilities of mission design by allowing mission makers a more sophisticated method of monitoring and controlling a mission in DCS.
How to use Scripting
The scripting engine uses the scripting language LUA. The scripting engine itself has access to most LUA functions in addition to scripting functions, objects, and classes specifically made for DCS. There are also custom scripts like MIST and MSF which build upon the DCS scripting engine functions. Additionally you are free to create your own functions. There are multiple ways within the mission editor to use scripting. See the following graphics.
| Initialization and Triggers | Group Spawn | Advanced Waypoint Actions | Triggered Actions |
|
|
|
|
Initialization and Triggers
The most obvious and powerful feature of the mission editor is where you can find the majority uses for the scripting engine.
Initialization
The initialization script is run as the mission is loading. It is the first scripting engine script to run.
Trigger Conditions
The condition "LUA PREDICATE" is the only trigger condition that can utilize lua. The condition must "return" a value true or false. The result of the condition and if applicable other conditions will dictate if the trigger action will execute.
IMPORTANT NOTE: Non-lua triggers will only be aware of groups placed in the mission editor. This means that if you dynamically respawn a group with the same group name as before, a trigger "Switched Condition>Group X is Alive> Message" will not execute if the respawned group is alive. This situation requires LUA Predicate to be used and a condition like the following
if Group.getByName('x') then
return true
else
return false
end
Trigger Actions
There trigger actions behave under the same rules as other trigger actions, they occur whenever the conditions of the trigger are true. There are two actions that directly use scripts, two actions that indirectly use scripts, and two scripts that use trigger script type to run setAITask and pushAITask.
Do Script Do Script File AI Set Task(Group Triggered Action Do Script or Do Script File) AI Push Task(Group Triggered Action Do Script or Do Script File) trigger.action.setAITask() trigger.action.pushAITask()
Group Actions
Scripts that occur inside group actions have the benefit to utilize a "self" variable to directly access the Group Class for the specific group in question. Specifically this means that some scripts can be added to a group and copy and pasted to other groups without having to make modifications to the script to make it work with the new group. The "self" variable in this case is designated as "...". Unfortunately you have to declare a new value to be equal to "..." in order to use it. See the following example.
local myTanks = Group.getByName('myTank1')
is the same as
local myTanks = ...
Group Spawn Condition
The Group spawn condition is run as the mission is loading shortly after the initialization script runs. This script is used to define whether or not the group it belongs to will spawn into the mission. Any code in this script must utilize a 'return' in order for the script to evaluate true (spawn the group) or false (don't spawn the group).
return
Advanced Waypoint Actions
Do Script and Do Script File are both command task types which will run when the group reaches the specified waypoint that the action is at. See page 146 of the English DCS User Manual by default found in the X:\Program Files\Eagle Dynamics\DCS World\Doc folder for a more deailed understand on how waypoint tasks function.
Triggered Actions
Scripts placed in triggered actions are group level scripts accessible to triggers and the scripting triggers.
Order of Precedence
An important part of programming is understand the order of precedence of when each script will run. This is important when utilizing multiple scripts which may depend on another script to be loaded first in order to function correctly. Below is a quick guide.
1. Initialization Script 2. Group Spawn Condition 3. Trigger: Mission Start 4. Group Waypoint 1 Scripts 5. Trigger: Once Time Less than 1 (anything that is true with no time elapsed) 6. Trigger: Once Time More than 0 (anything that is true once time has elapsed) 7. Group Waypoint 2+ Scripts
Triggers are evaluated top to bottom. This means that if multiple triggers will execute at the same time, the game will start at the top and work its way down. The same is true for conditions and actions. It is safe to have a trigger like the following if script C relies on B, and B relies on A:
Once> Time More than 3> Do Script File(A.lua) AND Do Script File(B.lua) AND Do Script File(C.lua)
Do Script vs Do Script File
The DCS Mission editor handles scripts in two different formats: 1 Raw Text(Do Script), 2 Within a File(Do Script File). The difference between the two is mostly down to interaction with the mission editor itself and how each file is stored within the mission. An identical script placed inside of a do script and a do script file will function exactly the same. To understand the difference you must first understand how DCS missions are stored and saved. Missions are saved as ".miz" files which are essentially a zipped archive. Utilizing 7-zip, winzip, or win-rar you can open up the file to see the files within. Inside by default are "mission", "warehouse", and "options". All three of these files are read and modified by the mission editor. When in the mission editor you add a sound file or briefing image, the files are added to the .miz. LUA files are no different.
Do Script is "raw" text and it is saved directly as text inside of the "mission" file. PRO: Using do script it is guaranteed that whatever code you have in there, will be written to the file whenever it is saved.
Do Script File is a lua file you would have edited in your favorite text editor and is saved into the .miz as its own file. PRO: Script is "how you saved it" inside of the .miz for you to update or others to study. CON: There is an occasional bug that occurs when you attempt to update an already loaded file where the file is not actually updated. Its rare enough that the Do Script File is still viable, but that rarity can lead to frustration when it does occur.
Tips and Tricks
Interactive Debugging
DCS Witchcraft includes a browser-based Lua debug console that allows you to interactively execute Lua snippets in a running mission. It is a great way to explore the capabilities of the scripting engine.
If the state of your script is accessible through a global variable, you can look at what is going on while it is running without having to add env.info() calls all over the place first. You can use the Lua functions trigger.misc.getUserFlag and trigger.action.setUserFlag to manipulate the flag variables.
As long as you provide a way to unregister any scheduled functions you set up, you can also replace your script with a new version without having to restart (and reload!) the mission.
