Latest revision as of 00:25, 19 April 2018

Intro

The scripting engine is a new feature of DCS since DCS: A-10C. The engine provides mission designer 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 be used for A.I. control. This is the way to create more sophisticated behavior of A.I. units than it possible using ME GUI because you can take in account more factors.

Note: The engine was initially developed for debug purposes. It was not tested properly, not tweaked, not reworked or extended due the requests of the community, so now it may contain bugs and disadvantages.

The document is actual for DCS: World 1.2.6.

Lua environment

The scripting engine uses the Lua language. Mission scripts run in a special, isolated Lua environment - the Mission Scripting Environment. There are two ways to run a Lua script:

AI Tasking System

1. "Script" command of A.I. Tasking System (available in a group's advanced waypoint actions and in triggered actions). If "Script" command is a waypoint action, then the command will run when the group reaches the waypoint the command is associated with. If "Script" command is a triggered action, then the command will run when the triggered action is called via the "AI TASK" trigger action.

2. "Script File" command of A.I. Tasking System (available in a group's advanced waypoint actions and in triggered actions). If "Script File" command is a waypoint action, then the command file will run when the group reaches the waypoint the script is associated with. If "Script File" command is a triggered action, then the command file will run when the triggered action is called via the "AI TASK" trigger action.

3. "CONDITION (LUA EXPRESSION)" for condition / stop condition for any type of action of the A.I. Tasking System. Such code should return boolean value or nil.

Triggers

1. "DO SCRIPT" trigger action.

2. "DO SCRIPT FILE" trigger action.

3. "EXPRESSTION" trigger condition. Such code must return boolean value of nil.

Other

1. Initialization script.

or

2. Initialization script file.

This script runs before spawn of first unit and before run of first trigger action. Script of script file can be selected, no both ways at the same time.

Game objects

There are several types of objects which the mission designer has access to. Some of these objects consist of a single instance (singleton), while several types may have multiple instances.

env. The simulator environment. Singleton. Provides access to program environment.

timer. The model timer of the simulator. Singleton. Provides current model time and current mission time.

land. The terrain. Singleton. Contains several functions for terrain analyzing.

atmosphere. The atmosphere. Singleton. Wind an other parameters.

world. The game world. Singleton.

coalition. The game coalitions: red, blue and neutral. Provides access to properties of coalitions such as bullseye, reference points and services.

country. The game countries. Provides only country list.

trigger. The trigger system. Singleton. Provides access to some trigger actions, trigger zones and user flags.

coord. Provides access to functions that convert between LO, MGRS, and latitude/longitude coordinate systems.

radio. Provides access to game radio system.

missionCommands. Provides access to mission commands in "F10. Other" menu.

AI. Provides constants used in Controller functions.

Object. The base category for static objects and units. Object is a static rigid body that has position (coordinate and orientation), category, type and descriptor.

CoalitionObject. Objects that belongs to a coalition and country. Intermediate class. This is the base class for static objects, airbases and unit and weapon.

Airbase. Airdrome, helipad or ship that acts as a base for aircraft.

StaticObject. It's possible to create new static objects during the mission and destroy them.

Weapon. Weapon utilities.

Unit. Active game object: aircraft, vehicle or ship. A Unit has several properties: name, coalition, state, type, number (in group), health, velocity, etc.

Units are always stored in a group.

A Unit may or may not have its own "Controller" object. If the unit does not have its own controller, then the unit is always under control of its group's controller, and thus, it is not possible to control the unit independently from its group.

For example, each aircraft has its own controller. An airborne group has its own controller too. This makes it possible to assign a task to any unit in the group, or to the whole group at once.

Naval and ground units do not have a controller for each unit, and only have a group controller, so you can only set a task to a whole naval or ground group.

Group. A group of units (ground, airborne and naval). Provides access to a group's properties, and to the units that a group consists of.

Controller. An instance of A.I. for a single unit or of a whole group. The mission designer may set a task to a controller, order a controller to perform a command, or change AI behavior options.

Symbol structure

Simulator exports some functions and constants to the Mission Scripting Environment. All symbols are grouped in tables.

Class emulation

Simulator has many entities which behave like an objects and classes in terms of object-oriented languages. To make manipulation with such objects easer "class-object" relations were emulated in the Lua environement with metatables. This framework is located in ./Scripts/Common/LuaClass.Lua.

Lua-"class" is a table that has following structure:

 Class = { 
   static = { 
     staticFunc1 = function(...) 
     ... 
     end, 
   ... 
     staticFuncN = function(...) 
     ... 
     end 
   }, 
   member = { 
     memberFunc1 = function(objectID, ...) 
     ... 
     end, 
   ... 
     memberFuncM = function(objectID, ...) 
     ... 
     end 
   },
   className_ = "ClassName", 
   parentClass_ = Class 
 }

static

Table with "static" functions. These functions have no object id as a parameter.

member

Table with "member" functions. These functions always have object id as a first parameter.

className_

String class name.

parentClass_

Reference to parent class table.

Lua-"object" is a table that has following structure:

 ObjectName = { 
   id_ = ... 
 }

id_

Object identifier. Its type depends on class. Member functions of Lua-"classes" has this identifier as a first argument.

Objects of the same class have set the same metatable - the class table.

The framework allows single inheritance, but doesn't allow multiple inheritance. Table of base class must be value of parentClass_ field table of derivative class.

LuaClass table must be assigned as a metatable to all Lua-"classes". LuaClass does all the job when user uses Lua-"classes" and Lua-"objects". LuaClass.__index metamethod is a function that looks for function that user want to call in Lua-"class" that the Lua-"object" belongs to or in base "classes" and calls the function.

LuaClass has also useful several functions those may be called any Lua-"class".

 function LuaClass.createFor(class, id_)

creates and returns Lua-"object" that belongs to class Lua-"class" and has identifier id_. No new entity created. The function just creates and initializies Lua-"object" table for existing entity.

 function LuaClass.create(class, ...)

uses class.static.create function to create new entity and then uses LuaClass.createFor to create Lua-"object" class for just created entity.

 function LuaClass.cast(class, object)

casts object to object of another class. Downcast must be unsafe if user will cast the object to class that object not realy belongs to.

 function class(tbl, parent)

declares table tbl as a Lua-"class" and as a derrivative class of a parent if parent is not nil

How does it works

Simulator exported some tables with functions and constants to the Mission Scripting Environment and then runs ./Scripts/MissionScripting.lua script do declare these tables a Lua-"classes".

However you may declare your own classes. To do it you must:

Create table and complete the table same way it shown here.
Declare the table as a class (and if you want as a derivative class). To do this call class function.

Basic terms and types

Enum

Enumeration types are given as

EnumType = enum EnumTable

This means the EnumType is enum type. Constants are stored in EnumTable table. It doesn't matter what is the real type of the EnumType. Mission developer must NEVER operate constant values! Only constant names must be used!

Array

Given as

ArrayType = array of ElementType

This means ArrayType is table that contains ElementType

 ArrayType = {
   [1] = ElementType,
   [2] = ElementType,
   ...
   [N] = ElementType
 }

Map

Given as

MapType = map KeyType, ElementType

This means MapType is table that contains ElementType each with key of type KeyType.

 MapType = {
   [KeyType] = ElementType,
   [KeyType] = ElementType,
   ...
   [KeyType] = ElementType
 }

Time

Time = number

Time is given in seconds.

Model time is the time that drives the simulation. Model time may be stopped, accelerated and decelerated relative real time.

Mission time is a model time plus time of the mission start.

Distance

Distance = number

Distance is given in meters.

Angle

Angle = number

Angle is given in radians.

Azimuth = Angle

Azimuth is an angle of rotation around world axis y counter-clockwise.

Mass

Mass = number

Mass is given in kilograms.

Coordinate system

DCS world has 3-dimensional coordinate system. DCS ground is an infinite plain.

Main axes:

x is directed to the north
z is directed to the east
y is directed up

Vectors

Vec3 type is a 3D-vector. It is a table that has following format:

 Vec3 = { 
   x = Distance, 
   y = Distance, 
   z = Distance 
 }

Vec2 is a 2D-vector for the ground plane as a reference plane.

 Vec2 = { 
   x = Distance, 
   y = Distance 
 }

 Vec2.x = Vec3.x
 Vec2.y = Vec3.z

Another coordinate systems

Geographic coordinates are represented by latitude/longitude pair given in degrees.

GeoCoord = number

Latitude positive direction is North. Longitude positive direction is East.

MGRS coordinates are represented by table:

 MGRS = {
   UTMZone = string,
   MGRSDigraph = string,
   Easting = number,
   Northing = number
 }

MGRS.UTMZone identifies MGRS zone.

MGRS.MGRSDigraph is a pair of letters - identifier of 100x100 km square in the zone.

MGRS.Easting/MGRS.Northing pair determines location within the 100x100 km square. Precision depends on how many digits used. no digits - precision level 100 km 1 digits - precision level 10 km 2 digits - precision level 1 km 3 digits - precision level 100 m 4 digits - precision level 10 m

Orientation

Object orientation is represented by 3x3 orthogonal row-major matrix. Matrix rows are orthogonal normalized vectors (also called unit vectors):

x is the Vec3 unit vector that points in the direction of the object's front
y is the Vec3 unit vector that points in the direction of the object's top
z is the Vec3 unit vector that points in the direction of the object's right side

 Orientation = { 
   x = Vec3, 
   y = Vec3, 
   z = Vec3 
 }

A "normalized vector", also known as a "unit vector", is a vector that has a length equal to 1.

As an example, an object that was oriented pointing due east, with its top pointed straight up, would have the following set of orientation vectors:

Orientation = {
   x = { x = 0, y = 0, z = 1},
   y = { x = 0, y = 1, z = 0},
   z = { x = -1, y = 0, z = 0}
}

Position

Position is a composite structure. It consists of both coordinate vector and orientation matrix.

Position3 (also known as "Pos3" for short) is a table that has following format:

 Position3 = {   p = Vec3,
                 x = Vec3,
                 y = Vec3,
                 z = Vec3 }

An illustration of the Pos3 structure and how it relates to simulation objects is shown below.

Box3

 Box3 = {
   min = Vec3,
   max = Vec3
 }

3-dimensional box.

TypeName

TypeName = string

Each object belongs to a type. Object type is a named couple of properties those independent of mission and common for all units of the same type. Name of unit type is a string. Samples of unit type: "Su-27", "KAMAZ" and "M2 Bradley".

AttributeName

AttributeName = string

Each object type may have attributes.

Attributes are enlisted in ./Scripts/Database/db_attributes.Lua.

To know what attributes the object type has, look for the unit type script in sub-directories planes/, helicopter/s, vehicles, navy/ of ./Scripts/Database/ directory.

Desc

 Desc = {
   typeName = TypeName, --type name
   displayName = string, --localized display name
   attributes = array of AttributeName --object type attributes
 }

Each object type has its own descriptor. Descriptor is a table that contains common information about all objects of this type, including common and specific (depending on object category and type) parameters. All descriptors inherit Desc.

Singletons

Singletons represent the types of object those have only single instance. Here are the usual Lua tables.

env

 function env.info(string message, bool showMessageBox = false)
 function env.warning(string message, bool showMessageBox = false)
 function env.error(string message, bool showMessageBox = false)

add message to simulator log with caption "INFO", "WARNING" or "ERROR". Message box is optional.

message

message string to add to log.

showMessageBox

If the parameter is true Message Box will appear. Optional.

 function env.setErrorMessageBoxEnabled(boolean on)

enables/disables appearance of message box each time lua error occurs.

on

if true message box appearance is enabled

timer

 Time function timer.getTime()

returns model time in seconds.

 Time function timer.getAbsTime()

returns mission time in seconds.

 Time function timer.getTime0()

returns mission start time

 Time function FunctionToCall(any argument, Time time)
   ...
   return ...
 end

Must return model time of next call or nil. Note that the DCS scheduler calls the function in protected mode and any Lua errors in the called function will be trapped and not reported. If the function triggers a Lua error then it will be terminated and not scheduled to run again.

 FunctionId = number

is a numeric identifier of scheduled FunctionToCall.

 FunctionId function timer.scheduleFunction(FunctionToCall functionToCall, any functionArgument, Time time)

schedules function to call at desired model time.

functionToCall

Lua-function to call. Must have prototype of FunctionToCall.

functionArgument

Function argument of any type to pass to functionToCall.

time

Model time of the function call.

 function timer.setFunctionTime(FunctionId functionId, Time time)

re-schedules function to call at another model time.

functionToCall

Lua-function to call. Must have prototype of FunctionToCall.

time

Model time of the function call.

 function timer.removeFunction(FunctionId functionId)

removes the function from schedule.

functionId

Function identifier to remove from schedule

land

 land.SurfaceType = {
   LAND,
   SHALLOW_WATER,
   WATER,
   ROAD,
   RUNWAY
 }

enum contains identifiers of surface types.

 boolean function land.isVisible(Vec3 from, Vec3 to)

returns true if there is LOS between point from and point to. Function verifies only obstruction due the terrain and don't takes in account objects (units, static and terrain objects).

 Distance function land.getHeight(Vec2 point)

returns altitude MSL of the point.

point

point on the ground.

 Vec3 function land.getIP(Vec3 from, Vec3 direction, Distance maxDistance)

returns point where the ray intersects the terrain. If no intersection found the function will return nil.

from

Ray vertex.

direction

Ray normalized direction.

maxDistance

Maximal search distance from ray vertex.

 array of Vec3 function land.profile(Vec3 from, Vec3 to)

returns table of vectors those are form profile of the terrain between point from and point to.

Only x and z components of both vectors matters. The first Vec3 in the result table is equal to vector from, the last vector in the result table is equal to vector to.

 enum land.SurfaceType function land.getSurfaceType(Vec2 point)

returns surface type at the given point.

point

Point on the land.

atmosphere

 Vec3 atmosphere.getWind(Vec3 point)

returns wind velocity at the given point. No turbulence.

point

Point in the air.

 Vec3 atmosphere.getWindWithTurbulence(Vec3 point)

returns wind velocity at the given point. With turbulence.

point

Point in the air.

world

 world.event = {
   S_EVENT_INVALID = 0,
   S_EVENT_SHOT = 1,
   S_EVENT_HIT = 2,
   S_EVENT_TAKEOFF = 3,
   S_EVENT_LAND = 4,
   S_EVENT_CRASH = 5,
   S_EVENT_EJECTION = 6,
   S_EVENT_REFUELING = 7,
   S_EVENT_DEAD = 8,
   S_EVENT_PILOT_DEAD = 9,
   S_EVENT_BASE_CAPTURED = 10,
   S_EVENT_MISSION_START = 11,
   S_EVENT_MISSION_END = 12,
   S_EVENT_TOOK_CONTROL = 13,
   S_EVENT_REFUELING_STOP = 14,
   S_EVENT_BIRTH = 15,
   S_EVENT_HUMAN_FAILURE = 16,
   S_EVENT_ENGINE_STARTUP = 17,
   S_EVENT_ENGINE_SHUTDOWN = 18,
   S_EVENT_PLAYER_ENTER_UNIT = 19,
   S_EVENT_PLAYER_LEAVE_UNIT = 20,
   S_EVENT_PLAYER_COMMENT = 21,
   S_EVENT_SHOOTING_START = 22,
   S_EVENT_SHOOTING_END = 23,
   S_EVENT_MAX = 24
 }

enum contains identifiers of simulator events.

 world.BirthPlace = {
   wsBirthPlace_Air,
   wsBirthPlace_RunWay,
   wsBirthPlace_Park,
   wsBirthPlace_Heliport_Hot,
   wsBirthPlace_Heliport_Cold,
 }

enum contains identifiers of birth place.

 Event = {
   id = enum world.event,
   time = Time,
   initiator = Unit,
   target = Unit,
   place = Unit,
   subPlace = enum world.BirthPlace,
   weapon = Weapon
 }

table represents a simulator event. Not all the parameters are valid for any event.

 EventHandler = {
   onEvent = function(Event event)
     ...
   end
 }

is a handler of simulator event.

 function world.addEventHandler(EventHandler handler)

adds event handler.

handler

event handler. Must have prototype of EventHandler.

 function world.removeEventHandler(EventHandler handler)

removes event handler.

Note: event handling will be moved from ./Scripts/World/EventHandlers.lua to the code. Function world.addEventHandler will support argument passing.

handler

event handler. Must have form of EventHandler.

 Unit function Unit world.getPlayer()

returns Unit player's aircraft.

 function array of Airbase world.getAirbases()

returns list of airbases

 world.VolumeType = {
   SEGMENT,
   BOX,
   SPHERE,
   PYRAMID
 }

enum contains types of volume to search.

 Volume = {
   id = enum world.VolumeType,
   params = {
     ...    
   }
 }

Table that contains information about the given volume.

id

Identifies volume type.

params

Table that contains parameters of the volume. Content is depended on volume type.

 VolumeSegment = {
   id = world.VolumeType.SEGMENT,
   params = {
     from = Vec3,
     to = Vec3
   }
 }

Represents 3D-segment.

from

Point where is the segment started.

to

Point where is the segment finished.

 VolumeBox = {
   id = world.VolumeType.BOX,
   params = {
     min = Vec3,
     max = Vec3
   }
 }

Represents 3D-box.

min

Coordinates of western-southern-lower vertex of the box.

max

Coordinates of eastern-northern-upper vertex of the box.

 VolumeSphere = {
   id = world.VolumeType.SPHERE,
   params = {
     point = Vec3,
     radius = Distance
   }
 }

Represents sphere.

point

Coordinates of the sphere center.

radius

Radius of the sphere.

 VolumePyramid = {
   id = world.VolumeType.PYRAMID,
   params = {
     pos = Position3,
     length = Distance,
     halfAngleHor = Angle,
     halfAngleVer = Angle
   }
 }

Represents camera FOV or oriented pyramid.

pos

Position of the pyramid.

length

Maximal distance from the pyramid vertex to an object.

halfAngleHor

Horizontal half angle.

halfAngleVer

Vertical half angle.

 ObjectSearchHandler = function(Object object, any data)
   ...
   return boolean
 end

Function to be called for each found object. Returns true to continue search and false to stop it.

 function array of Airbase world.searchObjects([array of enum Object.Category] or [Object.Category] objectCategory, Volume volume, ObjectSearchHandler handler, any data)

searches objects of the given categories in the given volume and calls handler function for each found object with data as 2nd argument.

objectCategory

Category or categories of objects to search.

volume

Volume to search.

handler

Function to call.

data

Data to pass to handler as 2nd argument.

coalition

 coalition.side = {
   NEUTRAL,
   RED,
   BLUE
 }

enum contains side identifiers.

 coalition.service = {
   ATC,
   AWACS,
   TANKER,
   FAC
 }

enum stores identifiers of coalition services.

 enum coalition.side function coalition.getCountryCoalition(enum country.id country)

returns coalition of the given country.

country

country identifier.

 Vec3 function coalition.getMainRefPoint(enum coalition.side coalition)

returns main reference point (bullseye).

coalition

coalition identifier.

 RefPoint = {
   callsign = number,
   type = number,
   point = Vec3
 }

table is a reference point (used by JTAC AI for example).

 array of RefPoint function coalition.getRefPoints(enum coalition.side coalition)

returns coalition reference points.

coalition

coalition identifier

 function coalition.addRefPoint(enum coalition.side coalition, RefPoint refPoint)

adds reference point to the coalition's list.

coalition

coalition identifier.

refPoint

reference point to add.

 array of Unit function coalition.getServiceProviders(enum coalition.side coalition, enum country.service serviceId)

returns list of units which are the coalition service providers

coalition

coalition identifier

 array of Unit function coalition.getPlayers(enum coalition.side coalition)

coalition

coalition identifier

returns list of units controlled by players (local and remote)

serviceId

coalition service identifier

 array of Airbase function coalition.getAirbases(enum coalition.side coalition)

returns list of airbases owned by the coalition

coalition

coalition identifier

 array of Unit function coalition.getGroups(enum coalition.side coalition, enum Group.Category groupCategory or nil)

returns list of groups belong to the coalition. It returns all groups or groups of specified type.

coalition

coalition identifier

groupCategory

group category. If nil the function will return list of groups of all categories.

 array of StaticObject function coalition.getStaticObjects(enum coalition.side coalition)

returns list of static objects belong to the coalition.

coalition

coalition identifier

 Group function coalition.addGroup(enum country.id country, enum Group.Category groupCategory, table groupData)

country

country identifier

groupCategory

group category.

groupData

table with group data. The table has the same format groups have in a mission file.

Note:

Coalition of a group is determined by its country

If another group has the same name new group has, that group will be destroyed and new group will take its mission ID.

If another units has the same name an unit of new group has, that unit will be destroyed and the unit of new group will take its mission ID.

If new group contains player's aircraft current unit that is under player's control will be destroyed.

Groups with client aircraft are not allowed.

If group mission ID or unit mission ID are not specified or busy, simulator will assign mission ID automatically.

 Group function coalition.addStaticObject(enum country.id country, table staticObjectData)

country

country identifier

staticObjectData

table with static object data. The table has the same format static objects have in a mission file.

Note:

Coalition of a static object is determined by its country

If another static object has the same name new static object has, that static object will be destroyed and new static object will take its mission ID.

If static object mission ID is not specified or busy, simulator will assign new mission ID automatically.

country

 country.id = {
   RUSSIA,
   UKRAINE,
   USA,
   TURKEY,
   UK,
   FRANCE,
   GERMANY,
   CANADA,
   SPAIN,
   THE_NETHERLANDS,
   BELGIUM,
   NORWAY,
   DENMARK,
   ISRAEL,
   GEORGIA,
   INSURGENTS,
   ABKHAZIA,
   SOUTH_OSETIA,
   ITALY
 }

enum contains country identifiers.

trigger

 trigger.smokeColor = {
   Green,
   Red,
   White,
   Orange,
   Blue
 }

enum contains identifiers of smoke color.

 trigger.flareColor = {
   Green,
   Red,
   White,
   Yellow
 }

enum contains identifiers of signal flare color.

 number function trigger.misc.getUserFlag(string userFlagName)

returns value of the user flag.

userFlagName

User flag name.

 TriggerZone = {
   point = Vec3,
   radius = Distance
 }

is a trigger zone.

 TriggerZone function trigger.misc.getZone(string triggerZoneName)

returns trigger zone.

triggerZoneName

Trigger zone name.

 function trigger.action.setUserFlag(string userFlagName, boolean or number userFlagValue)

sets new value of the user flag

userFlagName

User flag name.

userFlagValue

New value of the user flag. Numeric or boolean (0 or 1).

 function trigger.action.outSound(string soundFile)

plays sound file to all players.

soundFile

name of sound file stored in the mission archive (miz).

 function trigger.action.outSoundForCoalition(enum coalition.side coalition, string soundFile)

plays sound file to all players on a specific coalition.

coalition

coalition identifier.

soundFile

name of sound file stored in the mission archive (miz).

 function trigger.action.outSoundForCountry(enum country.id country, string soundFile)

plays sound file to all players on a specific country.

country

country identifier.

soundFile

name of sound file stored in the mission archive (miz).

 function trigger.action.outSoundForGroup(GroupId groupId, string soundFile)

plays sound file to players in a specific group.

groupId

group identifier.

soundFile

name of sound file stored in the mission archive (miz).

 function trigger.action.outText(string text, Time delay)

output text to screen to all players.

text

text to show.

delay

text delay.

 function trigger.action.outTextForCoalition(enum coalition.side coalition, string text, Time delay)

output text to screen to all players on a specific coalition.

coalition

coalition identifier.

text

text to show.

delay

text delay.

 function trigger.action.outTextForCountry(enum country.id country, string text, Time delay)

output text to screen to all players on a specific country.

country

country identifier.

text

text to show.

delay

text delay.

 function trigger.action.outTextForGroup(GroupId groupId, string text, Time delay)

output text to screen to all players in a specific unit group.

groupId

group identifier.

text

text to show.

delay

text delay.

 function trigger.action.explosion(Vec3 point, number power)

creates an explosion.

point

point in 3D space.

power

explosion power.

 function trigger.action.smoke(Vec3 point, enum trigger.smokeColor color)

creates a smoke marker.

point

point in 3D space.

color

color of the smoke.

 function trigger.action.illuminationBomb(Vec3 point)

creates illumination bomb at the point.

point

point where the illumination bomb will appear.

 trigger.action.signalFlare(Vec3 point, enum trigger.flareColor color, Azimuth azimuth)

launches signal flare from the point.

point

point the signal flare will be launched from.

color

signal flare color.

azimuth

signal flare flight direction.

 function trigger.action.addOtherCommand(string name, string userFlagName, number userFlagValue = 1)

adds command to "F10. Other" menu of the Radio Command Panel. The command will set the flag userFlagName to userFlagValue.

Calls missionCommands.addCommand().

name

menu command name.

userFlagName

user flag name.

userFlagValue

user flag value. By default equals to 1.

 function trigger.action.removeOtherCommand(string name)

removes menu item.

Calls missionCommands.removeItem().

 function trigger.action.addOtherCommandForCoalition(enum coalition.id coalition, string name, string userFlagName, number userFlagValue = 1)

adds command to "F10. Other" menu of the Radio Command Panel for the coalition. The command will set the flag userFlagName to userFlagValue.

Calls missionCommands.addCommandForCoalition().

coalition

coalition the command to add for

name

menu command name.

userFlagName

user flag name.

userFlagValue

user flag value. By default equals to 1.

 function trigger.action.removeOtherCommandForCoalition(enum coalition.id coalition, string name)

removes the item for the coalition.

Calls missionCommands.removeItemForCoalition().

coalition

coalition the command to remove for

name

name of the menu item to remove

 function trigger.action.addOtherCommandForGroup(GroupId groupId, string name, string userFlagName, number userFlagValue = 1)

adds command to "F10. Other" menu of the Radio Command Panel for the group. The command will set the flag userFlagName to userFlagValue.

Calls missionCommands.addCommandForGroup()

groupId

id of the group to add the command for

name

menu command name.

userFlagName

user flag name.

userFlagValue

user flag value. By default equals to 1.

 function trigger.action.removeOtherCommandForGroup(GroupId groupId, string name)

removes the item for the group.

Calls missionCommands.removeItemForGroup()

groupId

id of the group to remove the command for

name

name of the menu item to remove

 function trigger.action.radioTransmission(string fileName, Vec3 point, enum radio.modulation modulation, boolean loop, number frequency, number power)

transmits audio file to broadcast.

fileName

name of audio file. The file must be packed into the mission archive (miz).

point

position of the transmitter

modulation

modulation of the transmission

loop

indicates if the transmission is looped or not

frequency

transmitter frequency in Hz (9 digits)

power

transmitter power in Watts

 function trigger.action.setAITask(Group group, number taskIndex)

sets triggered task for the group.

group

the group to set the task for.

taskIndex

index of triggered task.

 function trigger.action.pushAITask(Group group, number taskIndex)

pushes triggered task for the group.

group

the group to push the task for.

taskIndex

index of triggered task.

 function trigger.action.activateGroup(Group group)

activates the group. Calls group:activate().

group

group to activate.

 function trigger.action.deactivateGroup(Group group)

deactivates the group. Calls group:destroy().

group

group to deactivate.

 function trigger.action.setGroupAIOn(Group group)

sets the controller of the group on. Calls group:getController():setOnOff(true).

group

group to set the controller on.

 function trigger.action.setGroupAIOff(Group group)

sets the controller of the group off. Calls group:getController():setOnOff(false).

group

group to set the controller off.

 function trigger.action.groupStopMoving(Group group)

orders the group to stop moving. Sets StopRoute command with value = true to the group controller.

group

group order to stop moving.

 function trigger.action.groupContinueMoving(Group group)

orders the group to continue moving. Sets StopRoute command with value = false to the group controller.

group

group order to continue moving.

coord

 Vec3 coord.LLtoLO(GeoCoord latitude, GeoCoord longitude, Distance altitude = 0)

returns point converted from latitude/longitude to Vec3.

latitude, longitude

latitude and longitude.

altitude

point altitude. Vec3.y = altitude. Optional parameter, equals to 0 by default.

 GeoCoord, GeoCoord, Distance function coord.LOtoLL(Vec3 point)

returns point converted to latitude/longitude/altitude from Vec3. Altitude is equals to point.y.

point

point to convert. Only x and z matters.

 MGRS function coord.LLtoMGRS(GeoCoord latitude, GeoCoord longitude)

converts latitude/longitude to MGRS.

latitude, longitude

latitude and longitude.

 GeoCoord, GeoCoord function coord.MGRStoLL(MGRS mgrs)

converts point from MGRS to latitude/longitude

mgrs

MGRS-coordinates of the point.

radio

 radio.modulation = {
   AM,
   FM
 }

enum contains identifiers of modulation types.

missionCommands

Provides access to the mission commands available for players in "F10. Other" menu in the communication menu.

 Path

contains menu item path.

Note: Path is the inner type. Do not construct variables of this type, use values returned from addCommand... and addSubMenu instead!

 Time function CommandFunction(any argument)
   ...
 end

function to be called by selecting the menu item

All

 Path missionCommands.addCommand(string name, Path or nil path, CommandFunction сommandFunction, any argument)

adds the command for all

name

command caption

path

path to the submenu the command must be inserted to. If nil the command will be inserted into root menu.

commandFunction

function to call

argument

argument to pass to the function

 Path missionCommands.addSubMenu(string name, Path or nil path)

adds the submenu for all

name

command caption

path

path to the submenu the command must be inserted to. If nil the command will be inserted into root menu.

 Path missionCommands.removeItem(Path or nil path)

removes the item for all

path

path to the item (command or submenu) to remove. If nil all items will be removed from the root menu.

Coalition

 Path missionCommands.addCommandForCoalition(enum coalition.side coalition, string name, Path or nil path, CommandFunction сommandFunction, any argument)

adds the command for the coalition

coalition

the coalition to add the command for

name

command caption

path

path to the submenu the command must be inserted to. If nil the command will be inserted into root menu.

commandFunction

function to call

argument

argument to pass to the function

 Path missionCommands.addSubMenuForCoalition(enum coalition.side coalition, string name, Path or nil path)

adds the submenu the coalition

coalition

the coalition to add the submenu for

name

command caption

path

path to the submenu the command must be inserted to. If nil the command will be inserted into root menu.

 Path missionCommands.removeItemForCoalition(enum coalition.side coalition, Path or nil path)

removes the item for the coalition

coalition

the coalition to remove the item for

path

path to the item (command or submenu) to remove. If nil all items will be removed from the root menu.

Group

 Path missionCommands.addCommandForGroup(GroupId groupId, string name, Path or nil path, CommandFunction сommandFunction, any argument)

adds the command for the group. Any type of groups available: airborne, ground, naval.

groupId

id of the group to add the command for

name

command caption

path

path to the submenu the command must be inserted to. If nil the command will be inserted into root menu.

commandFunction

function to call

argument

argument to pass to the function

 Path missionCommands.addSubMenuForGroup(GroupId groupId, string name, Path or nil path)

adds submenu to menu for the coalition

groupId

id of the group to add the submenu for

name

command caption

path

path to the submenu the command must be inserted to. If nil the command will be inserted into root menu.

 Path missionCommands.removeItemForGroup(GroupId groupId, Path or nil path)

removes the item for the coalition

groupId

id of the group to remove the item for

coalition

the coalition to remove the item for

path

path to the item (command or submenu) to remove. If nil all items will be removed from the root menu.

AI

Contains constants used in Controller functions.

 AI.Skill = {
   AVERAGE,
   GOOD,
   HIGH,
   EXCELLENT,
   PLAYER,
   CLIENT
 }

enum contains unit skill values.

 AI = {
   Task = {
     ...
   },
   Option = {
     ...
   }
 }

Task subtable contains constants used in tasks, Option subtable contains behavior option constants and their values.

 AI.Task.WeaponExpend = {
   ONE,
   TWO,
   FOUR,
   QUARTER,
   HALF,
   ALL
 }

enum contains identifiers of weapon expend modes.

 AI.Task.OrbitPattern = {
   CIRCLE,
   RACE_TRACK
 }

enum contains identifiers of orbit patterns.

 AI.Task.Designation = {
   NO,
   AUTO,
   WP,
   IR_POINTER,
   LASER
 }

enum contains identifiers of target designation modes.

 AI.Task.WaypointType = {
   TAKEOFF,
   TAKEOFF_PARKING,
   TURNING_POINT,
   LAND,
 }

enum contains identifiers of waypoint types.

 AI.Task.TurnMethod = {
   FLY_OVER_POINT,
   FIN_POINT
 }

enum contains identifiers of turn methods

 AI.Task.AltitudeType = {
   BARO,
   RADIO
 }

enum contains identifiers of altitude types

 AI.Task.VehicleFormation = {
   OFF_ROAD,
   ON_ROAD,
   RANK,
   CONE,
   DIAMOND,
   VEE,
   ECHELON_LEFT,
   ECHELON_RIGHT
 }

enum contains identifiers of vehicle formations

  AI.Option = {
     Air = {
        id = enum ???,
        val = map ???, enum ???
     },
     Ground = {
        id = enum ???,
        val = map ???, enum ???
     },
     Naval = {
        id = enum ???,
        val = map ???, enum ???
     }
  }

table contains identifiers of behavior options (id) and their values (val) as enums for airborne, ground and naval units / groups.

id

enum that contains options identifiers.

val

map that contains identifiers of option values for each option. Keys match names of option identifiers.

Difference between revisions of "DCS Scripting orig Part 1"

Latest revision as of 00:25, 19 April 2018

Contents

Intro

Lua environment

Game objects

Symbol structure

Class emulation

How does it works

Basic terms and types

Singletons

env

timer

land

atmosphere

world

coalition

country

trigger

coord

radio

missionCommands

AI