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.

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.

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.

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.

enum that contains options identifiers.

val

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