trigger#

trigger provides programmatic equivalents of many Mission Editor trigger actions, letting scripts set flags, display messages, draw on the F10 map, and more, without needing a corresponding trigger defined in the Mission Editor.

Functions#

trigger.action.outText(text, displayTime, clearView)#

Displays text on screen for all players for displayTime seconds. clearView optionally clears any previously displayed message first.

Parameters:

  • text (string) – Message text to display.

  • displayTime (number) – How long to display the message, in seconds.

  • clearView (boolean) – Optional; clear any previously displayed message first.

trigger.action.outTextForCoalition(coalitionId, text, displayTime, clearView)#

As outText(), but only visible to players on the given coalition.

Parameters:

  • coalitionId (number) – Coalition to display the message to.

  • text (string) – Message text to display.

  • displayTime (number) – How long to display the message, in seconds.

  • clearView (boolean) – Optional; clear any previously displayed message first.

trigger.action.setUserFlag(flagName, value)#

Sets a mission flag, identified by name or number, to value. Flags are used to coordinate state between triggers and scripts.

Parameters:

  • flagName – Flag name or number.

  • value – New flag value.

trigger.action.getUserFlag(flagName)#

Returns the current value of a mission flag.

Parameters:

flagName – Flag name or number.

Returns:

Current flag value.

trigger.action.markToAll(id, text, point, readOnly, message)#

Adds a mark panel visible to all players at the given point on the F10 map.

Parameters:

  • id (number) – Unique mark panel ID.

  • text (string) – Mark panel title text.

  • point (table) – A {x, y, z} point.

  • readOnly (boolean) – Optional; prevents players from editing the mark.

  • message (string) – Optional message body text.

trigger.action.explosion(point, power)#

Creates an explosion effect of the given power at the specified point.

Parameters:

  • point (table) – A {x, y, z} point.

  • power (number) – Explosion power.

trigger.action.smoke(point, smokeType)#

Creates a smoke effect of the given type at the specified point.

Parameters:

  • point (table) – A {x, y, z} point.

  • smokeType (number) – Smoke preset/type enumerator (see trigger.smokeColor).

trigger.action.effectSmokeBig(point, presetId, density, name)#

Creates a large smoke and/or fire effect at point.

Parameters:

  • point (table) – A {x, y, z} point.

  • presetId (number) – Effect preset. 1-4 are small/medium/large/huge smoke and fire; 5-8 are small/medium/large/huge smoke only.

  • density (number) – Smoke density, from 0 to 1.

  • name (string) – Unique name for the effect, used to stop it later with effectSmokeStop().

Example:

local p = trigger.misc.getZone('whatever').point
p.y = land.getHeight({x = p.x, y = p.z})
trigger.action.effectSmokeBig(p, 3, 0.75, 'fire1')
trigger.action.effectSmokeStop(name)#

Stops a big smoke effect previously started with effectSmokeBig().

Parameters:

name (string) – Name passed to effectSmokeBig().

trigger.action.ctfColorTag(unitName, smokeColor, altitude)#

Creates a colored smoke plume behind the named aircraft, automatically toggling on/off based on altitude. Passing 0 for smokeColor disables the plume; calling again with a different color on the same unit changes its color.

Parameters:

  • unitName (string) – Name of the unit to attach the smoke plume to.

  • smokeColor (number) – 0 disable, 1 Green, 2 Red, 3 White, 4 Orange, 5 Blue. (Offset by +1 from trigger.smokeColor.)

  • altitude (number) – Optional altitude, in meters, above which the smoke is active.

trigger.action.illuminationBomb(point, power)#

Creates an illumination flare at point that burns for 300 seconds (5 minutes) while falling toward the ground.

Parameters:

  • point (table) – A {x, y, z} point; y is the initial altitude.

  • power (number) – Illumination power, from 1 to 1000000.

trigger.action.signalFlare(point, flareColor, azimuth)#

Creates a signal flare at point, launched in the direction of azimuth.

Parameters:

  • point (table) – A {x, y, z} point.

  • flareColor (number) – Flare color (see trigger.flareColor).

  • azimuth (number) – Direction, in radians, the flare is launched toward.

trigger.action.radioTransmission(filename, point, modulation, loop, frequency, power, name)#

Broadcasts an audio file over a radio frequency, emanating from point.

Parameters:

  • filename (string) – Path to the sound file (relative to the mission’s l10n folder), e.g. 'l10n/DEFAULT/file.wav'.

  • point (table) – A {x, y, z} point the transmission emanates from.

  • modulation (number) – 0 for AM, 1 for FM.

  • loop (boolean) – Whether the transmission repeats continuously.

  • frequency (number) – Frequency, in Hz (9 digits, e.g. 124000000 for 124 MHz).

  • power (number) – Transmitter power, in Watts.

  • name (string) – Unique name for the transmission, used to stop it with stopRadioTransmission().

trigger.action.stopRadioTransmission(name)#

Stops a radio transmission previously started with radioTransmission().

Parameters:

name (string) – Name passed to radioTransmission().

trigger.action.setUnitInternalCargo(unitName, mass)#

Sets the internal cargo mass carried by the named unit, overriding any previous value. Only affects airplanes and helicopters.

Parameters:

  • unitName (string) – Name of the unit.

  • mass (number) – Cargo mass, in kilograms.

trigger.action.outSound(soundfile)#

Plays a sound file to all players. The file must be included in the .miz.

Parameters:

soundfile (string) – Path to the sound file within the mission.

trigger.action.outSoundForCoalition(coalitionId, soundfile)#

As outSound(), but only audible to players on the given coalition.

Parameters:

  • coalitionId (number) – Coalition to play the sound for.

  • soundfile (string) – Path to the sound file within the mission.

trigger.action.outSoundForCountry(countryId, soundfile)#

As outSound(), but only audible to players belonging to the given country.

Parameters:

  • countryId (number) – Country to play the sound for.

  • soundfile (string) – Path to the sound file within the mission.

trigger.action.outSoundForGroup(groupId, soundfile)#

As outSound(), but only audible to players in the given group.

Parameters:

  • groupId (number) – Group to play the sound for.

  • soundfile (string) – Path to the sound file within the mission.

trigger.action.outSoundForUnit(unitId, soundfile)#

As outSound(), but only audible to players controlling the given unit.

Parameters:

  • unitId (number) – Unit to play the sound for.

  • soundfile (string) – Path to the sound file within the mission.

trigger.action.outTextForCountry(countryId, text, displayTime, clearView)#

As outText(), but only visible to players belonging to the given country.

Parameters:

  • countryId (number) – Country to display the message to.

  • text (string) – Message text to display.

  • displayTime (number) – How long to display the message, in seconds.

  • clearView (boolean) – Optional; clear any previously displayed message first.

trigger.action.outTextForGroup(groupId, text, displayTime, clearView)#

As outText(), but only visible to players in the given group.

Parameters:

  • groupId (number) – Group to display the message to.

  • text (string) – Message text to display.

  • displayTime (number) – How long to display the message, in seconds.

  • clearView (boolean) – Optional; clear any previously displayed message first.

trigger.action.outTextForUnit(unitId, text, displayTime, clearView)#

As outText(), but only visible to players controlling the given unit.

Parameters:

  • unitId (number) – Unit to display the message to.

  • text (string) – Message text to display.

  • displayTime (number) – How long to display the message, in seconds.

  • clearView (boolean) – Optional; clear any previously displayed message first.

trigger.action.markToCoalition(id, text, point, coalitionId, readOnly, message)#

As markToAll(), but only visible to the given coalition.

Parameters:

  • id (number) – Unique mark panel ID.

  • text (string) – Mark panel title text.

  • point (table) – A {x, y, z} point.

  • coalitionId (number) – Coalition the mark is visible to.

  • readOnly (boolean) – Optional; prevents players from editing the mark.

  • message (string) – Optional message body text.

trigger.action.markToGroup(id, text, point, groupId, readOnly, message)#

As markToAll(), but only visible to the given group.

Parameters:

  • id (number) – Unique mark panel ID.

  • text (string) – Mark panel title text.

  • point (table) – A {x, y, z} point.

  • groupId (number) – Group the mark is visible to.

  • readOnly (boolean) – Optional; prevents players from editing the mark.

  • message (string) – Optional message body text.

trigger.action.removeMark(id)#

Removes a mark panel or F10 map shape (see the Markup drawing functions below) with the given ID.

Parameters:

id (number) – The unique ID passed when the mark/shape was created.

Markup drawing (F10 map)#

The following functions draw persistent shapes and text on the F10 map, distinct from the simpler mark panels created via markToAll() and friends. All share a common id numbering space with mark panels (IDs must be unique across both), and are removed with removeMark().

Coalition IDs used by these functions: -1 all, 0 neutral, 1 red, 2 blue. Colors are {r, g, b, a} tables with components from 0 to 1. lineType accepts the values in the line type enumerator below.

trigger.action.lineToAll(coalition, id, startPoint, endPoint, color, lineType, readOnly, message)#

Draws a line between two points on the F10 map.

Parameters:

  • coalition (number) – Coalition the shape is visible to.

  • id (number) – Unique shape ID.

  • startPoint (table) – A {x, y, z} point.

  • endPoint (table) – A {x, y, z} point.

  • color (table) – Outline color, {r, g, b, a}.

  • lineType (number) – Line style (see lineType).

  • readOnly (boolean) – Optional; whether clients may edit/remove the shape.

  • message (string) – Optional message shown when the shape is added.

trigger.action.circleToAll(coalition, id, center, radius, color, fillColor, lineType, readOnly, message)#

Draws a circle on the F10 map.

Parameters:

  • coalition (number) – Coalition the shape is visible to.

  • id (number) – Unique shape ID.

  • center (table) – A {x, y, z} point.

  • radius (number) – Circle radius, in meters.

  • color (table) – Outline color, {r, g, b, a}.

  • fillColor (table) – Fill color, {r, g, b, a}.

  • lineType (number) – Line style (see lineType).

  • readOnly (boolean) – Optional; whether clients may edit/remove the shape.

  • message (string) – Optional message shown when the shape is added.

trigger.action.rectToAll(coalition, id, startPoint, endPoint, color, fillColor, lineType, readOnly, message)#

Draws a rectangle between opposite corners startPoint and endPoint on the F10 map.

Parameters:

  • coalition (number) – Coalition the shape is visible to.

  • id (number) – Unique shape ID.

  • startPoint (table) – A {x, y, z} point (one corner).

  • endPoint (table) – A {x, y, z} point (opposite corner).

  • color (table) – Outline color, {r, g, b, a}.

  • fillColor (table) – Fill color, {r, g, b, a}.

  • lineType (number) – Line style (see lineType).

  • readOnly (boolean) – Optional; whether clients may edit/remove the shape.

  • message (string) – Optional message shown when the shape is added.

trigger.action.quadToAll(coalition, id, point1, point2, point3, point4, color, fillColor, lineType, readOnly, message)#

Draws an arbitrary quadrilateral defined by four points on the F10 map.

Parameters:

  • coalition (number) – Coalition the shape is visible to.

  • id (number) – Unique shape ID.

  • point1 (table) – A {x, y, z} point.

  • point2 (table) – A {x, y, z} point.

  • point3 (table) – A {x, y, z} point.

  • point4 (table) – A {x, y, z} point.

  • color (table) – Outline color, {r, g, b, a}.

  • fillColor (table) – Fill color, {r, g, b, a}.

  • lineType (number) – Line style (see lineType).

  • readOnly (boolean) – Optional; whether clients may edit/remove the shape.

  • message (string) – Optional message shown when the shape is added.

trigger.action.arrowToAll(coalition, id, startPoint, endPoint, color, fillColor, lineType, readOnly, message)#

Draws an arrow from startPoint to endPoint on the F10 map, pointing at startPoint.

Parameters:

  • coalition (number) – Coalition the shape is visible to.

  • id (number) – Unique shape ID.

  • startPoint (table) – A {x, y, z} point (the arrowhead).

  • endPoint (table) – A {x, y, z} point (the tail).

  • color (table) – Outline color, {r, g, b, a}.

  • fillColor (table) – Fill color, {r, g, b, a}.

  • lineType (number) – Line style (see lineType).

  • readOnly (boolean) – Optional; whether clients may edit/remove the shape.

  • message (string) – Optional message shown when the shape is added.

trigger.action.textToAll(coalition, id, point, color, fillColor, fontSize, readOnly, text)#

Draws text on the F10 map at point, scaling with the map zoom level.

Parameters:

  • coalition (number) – Coalition the text is visible to.

  • id (number) – Unique shape ID.

  • point (table) – A {x, y, z} point.

  • color (table) – Text color, {r, g, b, a}.

  • fillColor (table) – Background rectangle color, {r, g, b, a}.

  • fontSize (number) – Font size.

  • readOnly (boolean) – Optional; whether clients may edit/remove the shape.

  • text (string) – The text to display.

trigger.action.markupToAll(shapeId, coalition, id, point1, ..., color, fillColor, lineType, readOnly, message)#

A generic version of the shape functions above, selecting the shape via shapeId (1 line, 2 circle, 3 rect, 4 arrow, 5 text, 6 quad, 7 freeform). 7 (freeform) additionally accepts 3 or more points to build an arbitrary polygon that the dedicated shape functions cannot create.

Parameters:

  • shapeId (number) – Shape type; see description.

  • coalition (number) – Coalition the shape is visible to.

  • id (number) – Unique shape ID.

  • point1 (table) – First {x, y, z} point; further points follow positionally depending on shapeId.

  • color (table) – Outline color, {r, g, b, a}.

  • fillColor (table) – Fill color, {r, g, b, a}.

  • lineType (number) – Line style (see lineType).

  • readOnly (boolean) – Optional; whether clients may edit/remove the shape.

  • message (string) – Optional message shown when the shape is added.

Example:

-- A 6-point freeform shape with a light grey fill and teal outline.
trigger.action.markupToAll(7, -1, 1,
    trigger.misc.getZone('point1').point,
    trigger.misc.getZone('point2').point,
    trigger.misc.getZone('point3').point,
    trigger.misc.getZone('point4').point,
    trigger.misc.getZone('point5').point,
    trigger.misc.getZone('point6').point,
    {0, .6, .6, 1}, {0.8, 0.8, 0.8, .3}, 4)
trigger.action.setMarkupColor(id, color)#

Updates the outline color of an existing markup shape.

Parameters:

  • id (number) – Shape ID.

  • color (table) – New outline color, {r, g, b, a}.

trigger.action.setMarkupColorFill(id, fillColor)#

Updates the fill color of an existing markup shape.

Parameters:

  • id (number) – Shape ID.

  • fillColor (table) – New fill color, {r, g, b, a}.

trigger.action.setMarkupFontSize(id, fontSize)#

Updates the font size of an existing text markup. Has no effect if the shape has no text.

Parameters:

  • id (number) – Shape ID.

  • fontSize (number) – New font size.

trigger.action.setMarkupPositionStart(id, point)#

Moves the first point of an existing markup shape.

Parameters:

  • id (number) – Shape ID.

  • point (table) – New {x, y, z} position for the shape’s first point.

trigger.action.setMarkupPositionEnd(id, point)#

Moves the last point of an existing markup shape.

Parameters:

  • id (number) – Shape ID.

  • point (table) – New {x, y, z} position for the shape’s last point.

trigger.action.setMarkupRadius(id, radius)#

Updates the radius of an existing circle markup. Has no effect on non-circle shapes.

Parameters:

  • id (number) – Shape ID.

  • radius (number) – New radius, in meters.

trigger.action.setMarkupText(id, text)#

Updates the text of an existing text markup. Has no effect if the shape has no text.

Parameters:

  • id (number) – Shape ID.

  • text (string) – New text.

trigger.action.setMarkupTypeLine(id, lineType)#

Updates the line style of an existing markup shape.

Warning

As of DCS 2.7.0, changes made with this function are not synced to multiplayer clients.

Parameters:

  • id (number) – Shape ID.

  • lineType (number) – New line style (see lineType).

Zones#

trigger.misc.getZone(zoneName)#

Returns the trigger zone table for the named Mission Editor trigger zone.

Parameters:

zoneName (string) – Name of the trigger zone.

Returns:

A {point, radius} zone descriptor table.

Return type:

table

Note

If the zone is a quad zone (drawn with 4 arbitrary points rather than a circle), no positional information is returned.

Example:

local zone = trigger.misc.getZone('shortBusStop')
trigger.action.outText('The radius of the bus stop zone is: ' .. zone.radius, 20)

Enumerators#

trigger.smokeColor identifies the smoke color used by smoke():

Value

Meaning

trigger.smokeColor.Green

Green (0)

trigger.smokeColor.Red

Red (1)

trigger.smokeColor.White

White (2)

trigger.smokeColor.Orange

Orange (3)

trigger.smokeColor.Blue

Blue (4)

trigger.flareColor identifies the flare color used by signalFlare():

Value

Meaning

trigger.flareColor.Green

Green (0)

trigger.flareColor.Red

Red (1)

trigger.flareColor.White

White (2)

trigger.flareColor.Yellow

Yellow (3)

lineType (used by the markup drawing functions above) accepts one of the following numeric values:

Value

Meaning

0

No line

1

Solid

2

Dashed

3

Dotted

4

Dot dash

5

Long dash

6

Two dash

Lua-authored wrappers#

A number of trigger.action.* functions are not native engine bindings, but plain Lua convenience wrappers layered on top of the mission command menu system and the Group/Controller member functions described elsewhere in this documentation.

trigger.action.addOtherCommand(name, userFlagName, userFlagValue)#

Adds a radio/F10 “other” command that, when selected, sets a user flag to the given value (defaulting to true if not specified).

Parameters:

  • name (string) – Command label.

  • userFlagName – Flag to set when the command is selected.

  • userFlagValue – Optional value to set the flag to.

trigger.action.removeOtherCommand(name)#

Removes a previously added “other” command by name.

Parameters:

name (string) – Command label previously passed to addOtherCommand().

trigger.action.addOtherCommandForCoalition(coalition, name, userFlagName, userFlagValue)#

As addOtherCommand(), scoped to a single coalition’s menu.

Parameters:

  • coalition – Coalition to add the command for.

  • name (string) – Command label.

  • userFlagName – Flag to set when the command is selected.

  • userFlagValue – Optional value to set the flag to.

trigger.action.removeOtherCommandForCoalition(coalition, name)#

Removes a previously added coalition-scoped “other” command by name.

Parameters:

  • coalition – Coalition the command was added for.

  • name (string) – Command label.

trigger.action.addOtherCommandForGroup(groupId, name, userFlagName, userFlagValue)#

As addOtherCommand(), scoped to a single group’s menu.

Parameters:

  • groupId – Group to add the command for.

  • name (string) – Command label.

  • userFlagName – Flag to set when the command is selected.

  • userFlagValue – Optional value to set the flag to.

trigger.action.removeOtherCommandForGroup(groupId, name)#

Removes a previously added group-scoped “other” command by name.

Parameters:

  • groupId – Group the command was added for.

  • name (string) – Command label.

trigger.action.activateGroup(group)#

Activates a late-activated group by calling its :activate() member function.

Parameters:

group (Group) – The group to activate.

trigger.action.deactivateGroup(group)#

Deactivates group by calling its :destroy() member function.

Note

Despite the name, this destroys the group rather than merely deactivating it – there is no way to reactivate it afterward.

Parameters:

group (Group) – The group to deactivate/destroy.

trigger.action.setGroupAIOn(group)#

Enables AI control for group by calling group:getController():setOnOff(true).

Parameters:

group (Group) – The group to enable AI for.

trigger.action.setGroupAIOff(group)#

Disables AI control for group by calling group:getController():setOnOff(false).

Parameters:

group (Group) – The group to disable AI for.

trigger.action.groupStopMoving(group)#

Issues a StopRoute controller command to halt group along its current route.

Parameters:

group (Group) – The group to stop.

trigger.action.groupContinueMoving(group)#

Issues a StopRoute controller command (with value = false) to resume group along its current route.

Parameters:

group (Group) – The group to resume.

Footnotes#

  • trigger functions are grouped under the trigger.action sub-table; there is no top-level trigger.foo() – all actions are namespaced.

  • Many of these functions correspond directly to actions available in the Mission Editor’s trigger action list, making it straightforward to move logic between the editor and scripts.