Singletons

Home > Support > Technical questions > DCS: World Scripting Engine > Part 1 >  Singletons

Singletons

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.

 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_SHOT,
   S_EVENT_HIT,
   S_EVENT_TAKEOFF,
   S_EVENT_LAND,
   S_EVENT_CRASH,
   S_EVENT_EJECTION,
   S_EVENT_REFUELING,
   S_EVENT_DEAD,
   S_EVENT_PILOT_DEAD,
   S_EVENT_BASE_CAPTURED,
   S_EVENT_MISSION_START, -- currently can not be caught in script due to happens before script load
   S_EVENT_MISSION_END,
   S_EVENT_TOOK_CONTROL,
   S_EVENT_REFUELING_STOP,
   S_EVENT_BIRTH,
   S_EVENT_HUMAN_FAILURE,
   S_EVENT_ENGINE_STARTUP,
   S_EVENT_ENGINE_SHUTDOWN,
   S_EVENT_PLAYER_ENTER_UNIT,
   S_EVENT_PLAYER_LEAVE_UNIT,
   S_EVENT_PLAYER_COMMENT,
   S_EVENT_SHOOTING_START,
   S_EVENT_SHOOTING_END,
   S_EVENT_MARK_ADDED,
   S_EVENT_MARK_CHANGE,
   S_EVENT_MARK_REMOVED,
   S_EVENT_KILL,
   S_EVENT_SCORE,
   S_EVENT_UNIT_LOST,
   S_EVENT_LANDING_AFTER_EJECTION,
   S_EVENT_PARATROOPER_LENDING,
   S_EVENT_DISCARD_CHAIR_AFTER_EJECTION,
   S_EVENT_WEAPON_ADD,
   S_EVENT_TRIGGER_ZONE,
   S_EVENT_LANDING_QUALITY_MARK,
   S_EVENT_BDA,
   S_EVENT_AI_ABORT_MISSION,
   S_EVENT_DAYNIGHT,
   S_EVENT_FLIGHT_TIME,
   S_EVENT_PLAYER_SELF_KILL_PILOT,
   S_EVENT_PLAYER_CAPTURE_AIRFIELD,
   S_EVENT_EMERGENCY_LANDING,  -- useful event to handle when a bot ditches, and "group dead" condition can't be met 
 }

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.

 function EventHandler(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 are not specified or busy, simulator will assign mission ID automatically.
  • If unit mission ID are not specified or busy, simulator will assign mission ID = unit name.
 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

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.

FOLLOW US