MissionVM

The MissionVM is the Lua environment that runs while a mission is active. It is the most feature-rich of the three SSE virtual machines, exposing global singletons and classes that let scripts read and manipulate the simulated world: spawning and controlling groups, querying the environment, reacting to in-game events, and influencing coalition and AI behaviour.

Execution

Scripts activate in the MissionVM in the following contexts:

• Triggers - DO SCRIPT trigger action - DO SCRIPT FILE trigger action - EXPRESSION trigger condition (must return a boolean or nil)

• A.I. Tasking System - Script command (waypoint action or triggered action) - Script File command (waypoint action or triggered action) - CONDITION (LUA EXPRESSION) for action/stop conditions (must return a boolean

  or nil)

• Mission initialization - The mission’s initialization script or initialization script file, which runs

  before the first unit spawns and before the first trigger fires.

Sandboxing

MissionVM code runs inside a sandboxed Lua state. Before any mission script runs, the environment is sanitized by removing the os, io, and lfs modules entirely, and nil-ing out require, loadlib, and package. This prevents mission scripts (which may come from an untrusted server or mission file) from touching the filesystem or loading arbitrary native libraries. Only the symbols explicitly exported by the simulator (described in the sections below) are guaranteed to be available.

Warning

Restoring access to os, io, or lfs re-exposes filesystem and native library access to any mission script, including ones downloaded from a multiplayer server. This is a known, engine-acknowledged security risk and should only be considered locally and at your own risk.

Class emulation

Most MissionVM classes (Group, Unit, StaticObject, and others) are backed by a small class-emulation framework built with Lua metatables. Objects are plain tables holding an internal identifier, and their metatable is the class table itself, so method calls resolve by walking up a parent-class chain until a matching function is found (raising an error if none exists). Declaring a class assigns this shared metatable, along with equality/ordering comparisons based on the object’s identifier, and a protective handler that raises an error on any attempt to directly assign a field on an object instance.

Note

Because Lua-object tables cannot be modified directly by user scripts, any apparent “mutation” of an object (e.g. changing a unit’s state) must go through the class’s own member functions rather than direct field assignment.

API Hierarchy

The API surface exposed to the MissionVM is organised into two broad categories:

• Global Singletons

  • Pre-existing global tables such as env, timer, land, atmosphere, coord, world, coalition, trigger, net, missionCommands, and VoiceChat. These provide direct access to world state, logging, timing, and event/trigger/menu utilities without needing to obtain an object reference first.

• Classes

  • Lua-“class” tables (per DCS’ class emulation framework) representing in-game entities and concepts, such as Group, Controller/execution tasks, Spot, and CoalitionObject. Instances (“objects”) of these classes are typically obtained via static functions (e.g. Group.getByName()) or returned from other API calls and events.

See the following sections for details:

• Global Singletons
• Classes