DCS_ControlAPI.html

<!-- TOC depthFrom:1 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->

<ul>
<li><a href="#intro">DCS Simulation Control User Scripts</a><ul>
<li><a href="#example-script">The example user script 'testGameGUI.lua':</a></li>
</ul>
</li>
<li><a href="#lua-api">Lua API</a><ul>
<li><a href="#lfs-api">Lua File System (lfs) API</a></li>
<li><a href="#dcs-api">DCS Control API, table 'DCS.*'</a></li>
<li><a href="#log-api">Logging API 'log.*'</a></li>
<li><a href="#net-api">Network specific API, available through the table 'net.'</a></li>
<li><a href="#export-api">LuaExport API 'Export.Lo*'</a></li>
</ul>
</li>
<li><a href="#the-callbacks">The Callbacks.</a><ul>
<li><a href="#sim-callbacks">Simulation Callbacks.</a></li>
<li><a href="#gui-callbacks">GUI callbacks</a></li>
</ul>
</li>
</ul>
<!-- /TOC -->

<h1><a name="intro"></a> DCS Simulation Control User Scripts</h1>
<p>The behaviour of the DCS can be altered using the Lua scripts.
You define the hooks to the DCS events, and then do what you want using the provided API.</p>
<p>When loading, DCS searches for <em>Saved Games\DCS\Scripts\Hooks\*.lua</em> files,
sorts them by name and then loads into the GUI Lua-state.
Each user script is loaded into an isolated environment, so the only
thing they share is the state of the simulator.</p>
<p>Each script defines a set of callbacks to the DCS events and sets them with the call
    <em>DCS.setUserCallbacks(cb_table)</em>
For each callback type the hooks of all user scripts will be called in order of loading.</p>
<p>For callbacks which are supposed to return a value, currently there are 3 of them:</p>
<ul>
<li><em>onPlayerTryConnect</em></li>
<li><em>onPlayerTrySendChat</em></li>
<li><em>onPlayerTryChangeSlot</em></li>
</ul>
<p>returning a value means breaking the hook call chain.
Returning nothing (or nil) means continuing the hook chain, which ends with the default allow-all handlers.</p>
<h2><a name="example-script"></a> The example user script 'Hooks/test.lua':</h2>
<pre><code>local test = {}

function test.onPlayerTryConnect(ipaddr, name, ucid, playerID)
    print('onPlayerTryConnect(%s, %s, %s, %d)', ipaddr, name, ucid, playerID)
    -- if you want to gently intercept the call, allowing other user scripts to get it,
    -- you better return nothing here
    return true -- allow the player to connect
end

function test.onSimulationStart()
    print('Current mission is '..DCS.getMissionName())
end

DCS.setUserCallbacks(test)  -- here we set our callbacks
</code></pre>
<p>The available API is documented below.
The full list of the callbacks is at <a href="#the-callbacks">the end of this document</a>.</p>
<p>In addition, all standard lua 5.1 libraries are available as well, namely:</p>
<ul>
<li>base api, like print, etc,</li>
<li>math.*</li>
<li>table.*</li>
<li>string.*</li>
<li>io.*</li>
<li>os.*</li>
<li>debug.*</li>
</ul>
<h1><a name="lua-api"></a> Lua API</h1>
<h2><a name="lfs-api"></a> Lua File System (lfs) API</h2>
<ul>
<li>
<p><em>lfs.currentdir() -&gt; string</em></p>
<pre><code>Returns the path of the DCS install folder
</code></pre>
</li>
<li>
<p><em>lfs.writedir() -&gt; string</em></p>
<p>Returns the path of the current 'Saved Games\DCS' folder.</p>
</li>
<li>
<p><em>lfs.tempdir() -&gt; string</em></p>
<p>Returns the pat of the DCS Temp folder (AppData\Local\Temp\DCS).</p>
</li>
<li>
<p><em>lfs.mkdir()</em></p>
</li>
<li><em>lfs.rmdir()</em></li>
<li><em>lfs.attributes()</em></li>
<li><em>lfs.dir()</em></li>
<li><em>lfs.normpath()</em></li>
<li><em>lfs.realpath()</em></li>
</ul>
<h2><a name="dcs-api"></a> DCS Control API, table 'DCS.*'</h2>
<ul>
<li>
<p><em>DCS.setPause(bool)</em></p>
<p>Pauses/resumes the simulation. Server-side only.</p>
</li>
<li>
<p><em>DCS.getPause() -&gt; bool</em></p>
<p>true if simulation is paused</p>
</li>
<li>
<p><em>DCS.stopMission()</em></p>
<p>stops current mission</p>
</li>
<li>
<p><em>DCS.exitProcess()</em></p>
<p>Exits the DCS process.</p>
</li>
<li>
<p><em>DCS.isMultiplayer() -&gt; bool</em></p>
<p>True when running in the multiplayer mode.</p>
</li>
<li>
<p><em>DCS.isServer() -&gt; bool</em></p>
<p>True when running as a server or in the single-player mode.</p>
</li>
<li>
<p><em>DCS.getModelTime() -&gt; number</em></p>
<p>returns current DCS simulation time in seconds.</p>
</li>
<li>
<p><em>DCS.getRealTime() -&gt; number</em></p>
<p>returns current DCS real time in seconds relative to the DCS start time.</p>
</li>
<li>
<p><em>DCS.getMissionOptions() -&gt; table</em></p>
<p>Returns the value of 'mission.options'</p>
</li>
<li>
<p><em>DCS.getMissionDescription() -&gt; string</em></p>
<p>translated mission.descriptionText string</p>
</li>
<li>
<p><em>DCS.getAvailableCoalitions() -&gt; table {</em>
           [coalition_id] = { name = "coalition name", }
            ...
           }</p>
<p>Returns a list of coalitions which have available slots.</p>
</li>
<li>
<p><em>DCS.getAvailableSlots(coalitionID) -&gt; array of {unitId, type, role, callsign, groupName, country}</em></p>
<p>Returns the list of available slots.</p>
<p>NOTE: the returned unitID is actually a slotID, which for multi-seat units is 'unitID_seatID'</p>
</li>
<li>
<p><em>DCS.getCurrentMission() -&gt; table with the currently loaded mission</em></p>
<p>NOTE: to get valid mission.options use <em>DCS.getMissionOptions()</em></p>
</li>
<li>
<p><em>DCS.getMissionName() -&gt; string</em></p>
<p>Returns the name of the current mission</p>
</li>
<li>
<p><em>DCS.getMissionFilename() -&gt; string</em></p>
<p>Returns the file name of the current mission (returns nil when acting as a multiplayer client).</p>
</li>
<li>
<p><em>DCS.getMissionResult(string side) -&gt; integer [0, 100]</em></p>
<p>Gets mission result for either 'red' or 'blue'</p>
</li>
<li>
<p><em>DCS.getUnitProperty(missionId, propertyId) -&gt; string</em></p>
<p>propertyId:</p>
<pre><code>   DCS.UNIT_RUNTIME_ID, // unique within runtime mission. int
   DCS.UNIT_MISSION_ID, // unique within mission file. int&gt;0
   DCS.UNIT_NAME, // unit name, as assigned by mission designer.
   DCS.UNIT_TYPE, // unit type (Ural, ZU-23, etc)
   DCS.UNIT_CATEGORY,
   DCS.UNIT_GROUP_MISSION_ID, // group ID, unique within mission file. int&gt;0
   DCS.UNIT_GROUPNAME, // group name, as assigned by mission designer.
   DCS.UNIT_GROUPCATEGORY,
   DCS.UNIT_CALLSIGN,
   DCS.UNIT_HIDDEN,// ME hiding
   DCS.UNIT_COALITION,// "blue", "red" or "unknown"
   DCS.UNIT_COUNTRY_ID,
   DCS.UNIT_TASK, //"unit.group.task"
   DCS.UNIT_PLAYER_NAME, // valid for network "humanable" units
   DCS.UNIT_ROLE,//"artillery_commander", "instructor", etc
   DCS.UNIT_INVISIBLE_MAP_ICON,//ME invisible map icon
</code></pre>
</li>
<li>
<p><em>DCS.getUnitType(missionId) -&gt; typeId</em></p>
<p>a shortcut for DCS.getUnitProperty(missionId, DCS.UNIT_TYPE)</p>
</li>
<li>
<p><em>DCS.getUnitTypeAttribute(typeId, attr) -&gt; string</em></p>
<p>Returns a value from Database: Objects[typeId][attr],</p>
<p>For example:</p>
<pre><code>   DCS.getUnitTypeAttribute("Ural", "DisplayName")
</code></pre>
</li>
<li>
<p><em>DCS.writeDebriefing(str)</em></p>
<p>Writes a custom string to the debriefing file</p>
</li>
<li>
<p><em>DCS.setUserCallbacks(cb_table)</em></p>
<p>Hooks the callbacks using the handlers from the provided table.</p>
<p>See: "GameGUI scripts" section.</p>
</li>
<li>
<p><em>DCS.makeScreenShot(name)</em></p>
<p>Makes screenshot with given name.</p>
</li>
<li>
<p><em>DCS.getLogHistory(from) -&gt; {{abstime, level, subsystem, message}, ...}, last_index</em></p>
<p>Returns last log messages starting from a given index.</p>
<p>Usage:</p>
<pre><code>  local logIndex = 0;
  local logHistory = {}
  logHistory, logIndex = DCS.getLogHistory(logIndex)
</code></pre>
</li>
</ul>
<h2><a name="log-api"></a> Logging API 'log.*'</h2>
<p>Logging works as follows:</p>
<ul>
<li>each log message is accompanied with 2 attributes: a subsystem, and level.</li>
<li>after each messages gets into the logger it passes (asynchronously) through
   a series of output filters which decide where the message will be written to.</li>
</ul>
<p>The API is:</p>
<ul>
<li>
<p><em>log.write(SUBSYSTEM_NAME, LOG_LEVEL, message, ...)</em></p>
<p>Sends the message to the logger. If there are any arguments after <em>message</em>,
  the actual string is formed as <em>string.format(message, ...)</em></p>
<p>SUBSYSTEM_NAME is a string</p>
<p>LOG_LEVEL is one of the values, listed below</p>
<p>see log.set_output() below.</p>
</li>
<li>
<p><em>log.set_output(log_file_name_wo_ext, rule_subsystem_name, rule_level_mask, rule_output_mode)</em></p>
<p>log_file_name_wo_ext: resulting log will be written to $WRITE_DIR/Logs/<log_file_name_wo_ext>.log</p>
<p>rule_subsytem_name: the name of the subsystem whose messages to write or empty string to match all subsystems</p>
<p>rule_level_mask: a sum of log-level bit flags to match messages, valid flags are:</p>
<pre><code>   log.ALERT
   log.ERROR
   log.WARNING
   log.INFO
   log.DEBUG
   log.ALL - includes all of the above
   log.TRACE - a special level which is excluded from dcs.log file
</code></pre>
<p>rule_output_mode: a sum of output flags:</p>
<pre><code>   log.MESSAGE
   log.TIME_UTC or log.TIME_LOCAL or log.TIME_RELATIVE
   log.MODULE - this means a 'subsystem', not a DLC
   log.LEVEL
   log.FULL = log.MESSAGE + log.TIME_UTC + log.MODULE + log.LEVEL
</code></pre>
</li>
</ul>
<p>So, in order to save net.trace(msg) messages to a file, you should issue a call:</p>
<pre><code>log.set_output('lua-net', 'LuaNET', log.TRACE, log.MESSAGE + log.TIME_UTC)
</code></pre>
<p>This will write to a Logs/lua-net.log file</p>
<p>Or, to save everything lua-network-related:</p>
<pre><code>log.set_output('lua-net', 'LuaNET', log.TRACE + log.ALL, log.MESSAGE + log.TIME_UTC + log.LEVEL)
</code></pre>
<p>To close the log file, you must use</p>
<pre><code>log.set_output('lua-net', '', 0, 0)
</code></pre>
<p>log.* API is also available from the <em>Saved Games\DCS\Config\autoexec.cfg</em> file so you can control log output in you local machine.</p>
<h2><a name="net-api"></a> Network specific API, available through the table 'net.'</h2>
<ul>
<li><em>net.log(msg) -- equivalent of log.write('LuaNET', log.INFO, msg)</em></li>
<li><em>net.trace(msg) -- equivalent of log.write('LuaNET', log.TRACE, msg)</em></li>
</ul>
<p>What is the difference:</p>
<ul>
<li><em>log()</em> always writes to <strong>dcs.log</strong>, but may lose messages if the output rate is too high.</li>
<li><em>trace()</em> output never appears in the <strong>dcs.log</strong> file, it must be explicitly directed to a log file.
It never loses messages when there's an active output, but it may block if output rate is faster than writing to the log file.</li>
</ul>
<p>To control logger output you can use <em>$WRITE_DIR/Config/autoexec.cfg</em> file, or call this from your network script
<a href="#log-api">(log.* API, see above)</a></p>
<ul>
<li>
<p><em>net.dostring_in(state, string) -&gt; string</em></p>
<p>Executes a lua-string in a given internal lua-state and returns a string result</p>
<p>Valid state names are:</p>
<pre><code>  'config': the state in which $INSTALL_DIR/Config/main.cfg is executed, as well as $WRITE_DIR/Config/autoexec.cfg
            used for configuration settings
  'mission': holds current mission
  'export': runs $WRITE_DIR/Scripts/Export.lua and the relevant export API
</code></pre>
</li>
<li>
<p><em>net.send_chat(string message, bool all)</em></p>
<p>Send chat message. If not all, then send to my coalition (side) only.</p>
</li>
<li>
<p><em>net.send_chat_to(string message, playerID to)</em></p>
<p><em>net.send_chat_to(string message, playerID to[, playerID from]) -- SERVER ONLY</em></p>
<p>Send direct chat message to a player</p>
</li>
<li>
<p><em>net.recv_chat(message[, int from=0])</em></p>
<p>Receive chat message locally[, pretending it was sent by another player].</p>
<p>from = 0 means from the system</p>
</li>
<li>
<p><em>net.get_chat_history(from) -&gt; {{abstime, side, playerName, message}, ...}, last_index</em></p>
<p>Returns last chat messages starting from a given index.</p>
<p>Usage:</p>
<pre><code>  local chatIndex = 0;
  local chatHistory = {}
  chatHistory, chatIndex = net.get_chat_history(chatIndex)
</code></pre>
</li>
<li>
<p><em>net.load_mission(miz_filename) -- SERVER ONLY</em></p>
<p>Loads a specified mission, temporarily overriding the server mission list.</p>
</li>
<li>
<p><em>net.load_next_mission() -&gt; bool -- SERVER ONLY</em></p>
<p>Load the next mission from the server mission list. Returns false if list end is reached</p>
</li>
<li>
<p><em>net.get_player_list() -&gt; array of playerID</em></p>
<p>Returns the list of currently connected players</p>
</li>
<li>
<p><em>net.get_my_player_id() -&gt; playerID</em></p>
<p>Returns the playerID of the local player. Currently always 1 for the server.</p>
</li>
<li>
<p><em>net.get_server_id() -&gt; playerID</em></p>
<p>Returns playerID of the server. Currently, always 1.</p>
</li>
<li>
<p><em>net.get_player_info(playerID) -&gt; table</em></p>
<p>Returns a table of all player attributes or nil if playerID is invalid</p>
</li>
<li>
<p><em>net.get_player_info(playerID, attrName) -&gt; value</em></p>
<p>Returns a value of a given attribute for the playerID.</p>
<p>Currently defined attributes are:</p>
<pre><code>  'id': playerID
  'name': player name
  'side': 0 - spectators, 1 - red, 2 - blue
  'slot': slotID of the player or ''
  'ping': ping of the player in ms
  'ipaddr': IP address of the player, SERVER ONLY
  'ucid': Unique Client Identifier, SERVER ONLY
</code></pre>
</li>
<li>
<p><em>net.kick(playerID, message)</em></p>
<p>Kick a player.</p>
</li>
<li>
<p><em>net.get_stat(playerID, statID) -&gt; integer</em></p>
<p>Get statistics for player. statIDs are:</p>
<pre><code>  net.PS_PING  (0) - ping (in ms)
  net.PS_CRASH (1) - number of crashes
  net.PS_CAR   (2) - number of destroyed vehicles
  net.PS_PLANE (3) - ... planes/helicopters
  net.PS_SHIP  (4) - ... ships
  net.PS_SCORE (5) - total score
  net.PS_LAND  (6) - number of landings
  net.PS_EJECT (7) - of ejects
</code></pre>
</li>
<li>
<p><em>net.get_name(playerID) -&gt; string</em></p>
<pre><code>The same as net.get_player_info(playerID, 'name')
</code></pre>
</li>
<li>
<p><em>net.get_slot(playerID) -&gt; sideID, slotID</em></p>
<p>The same as:</p>
<pre><code>   net.get_player_info(playerID, 'side'), net.get_player_info(playerID, 'slot')
</code></pre>
</li>
<li>
<p><em>net.set_slot(sideID, slotID)</em></p>
<p>Try to set the local player's slot. Empty slotID ('') puts the player into spectators.</p>
</li>
<li>
<p><em>net.force_player_slot(playerID, sideID, slotID) -&gt; boolean</em></p>
<p>Forces a player to occupy a set slot. Slot '' means no slot (moves player to spectators)</p>
<p>SideID: 0 - spectators, 1 - red, 2 - blue</p>
</li>
<li>
<p><em>net.set_name(playerID, name) -- OBSOLETE, works only locally</em></p>
</li>
<li>
<p><em>net.lua2json(value) -&gt; string</em></p>
<p>Convert a Lua value to JSON string</p>
</li>
<li>
<p><em>net.json2lua(json_string) -&gt; value</em></p>
<p>Convert JSON string to a Lua value</p>
</li>
</ul>
<h2><a name="export-api"></a> LuaExport API 'Export.Lo*'</h2>
<p>See <em>Scripts/Export.lua</em> for the documentation. Note that all export
API functions are available here in the Export. namespace, not the global one.
In multiplayer the availability of the API on clients depends on the server setting.</p>
<p>The calls to check export capabilities:</p>
<pre><code>Export.LoIsObjectExportAllowed()  -- returns the value of server.advanced.allow_object_export
Export.LoIsSensorExportAllowed()  -- returns the value of server.advanced.allow_sensor_export
Export.LoIsOwnshipExportAllowed() -- returns the value of  server.advanced.allow_ownship_export
</code></pre>
<p>These calls are only available on clients when LoIsObjectExportAllowed() is true:</p>
<pre><code>Export.LoGetObjectById
Export.LoGetWorldObjects
</code></pre>
<p>These calls are only available on clients when LoIsSensorExportAllowed() is true:</p>
<pre><code>Export.LoGetTWSInfo
Export.LoGetTargetInformation
Export.LoGetLockedTargetInformation
Export.LoGetF15_TWS_Contacts
Export.LoGetSightingSystemInfo
Export.LoGetWingTargets
</code></pre>
<p>These calls are only available on clients when LoIsOwnshipExportAllowed() is true:</p>
<pre><code>Export.LoGetPlayerPlaneId
Export.LoGetIndicatedAirSpeed
Export.LoGetAngleOfAttack
Export.LoGetAngleOfSideSlip
Export.LoGetAccelerationUnits
Export.LoGetVerticalVelocity
Export.LoGetADIPitchBankYaw
Export.LoGetTrueAirSpeed
Export.LoGetAltitudeAboveSeaLevel
Export.LoGetAltitudeAboveGroundLevel
Export.LoGetMachNumber
Export.LoGetRadarAltimeter
Export.LoGetMagneticYaw
Export.LoGetGlideDeviation
Export.LoGetSideDeviation
Export.LoGetSlipBallPosition
Export.LoGetBasicAtmospherePressure
Export.LoGetControlPanel_HSI
Export.LoGetEngineInfo
Export.LoGetSelfData
Export.LoGetCameraPosition
Export.LoSetCameraPosition
Export.LoSetCommand
Export.LoGetMCPState
Export.LoGetRoute
Export.LoGetNavigationInfo
Export.LoGetPayloadInfo
Export.LoGetWingInfo
Export.LoGetMechInfo
Export.LoGetRadioBeaconsStatus
Export.LoGetVectorVelocity
Export.LoGetVectorWindVelocity
Export.LoGetSnares
Export.LoGetAngularVelocity
Export.LoGetHeightWithObjects
Export.LoGetFMData
</code></pre>
<p>These functions are always available:</p>
<pre><code>Export.LoGetPilotName
Export.LoGetAltitude
Export.LoGetNameByType
Export.LoGeoCoordinatesToLoCoordinates
Export.LoCoordinatesToGeoCoordinates
Export.LoGetVersionInfo
Export.LoGetWindAtPoint
Export.LoGetModelTime
Export.LoGetMissionStartTime
</code></pre>
<p>These are not available in the hooks:</p>
<pre><code>--Export.LoSetSharedTexture
--Export.LoRemoveSharedTexture
--Export.LoUpdateSharedTexture
</code></pre>
<h1><a name="the-callbacks"></a> The Callbacks.</h1>
<h2><a name="sim-callbacks"></a> Simulation Callbacks.</h2>
<pre><code>function onMissionLoadBegin()
end

function onMissionLoadProgress(progress, message)
end

function onMissionLoadEnd()
end

function onSimulationStart()
end

function onSimulationStop()
end

function onSimulationFrame()
end

function onSimulationPause()
end

function onSimulationResume()
end

function onGameEvent(eventName,arg1,arg2,arg3,arg4)
    --"friendly_fire", playerID, weaponName, victimPlayerID
    --"mission_end", winner, msg
    --"kill", killerPlayerID, killerUnitType, killerSide, victimPlayerID, victimUnitType, victimSide, weaponName
    --"self_kill", playerID
    --"change_slot", playerID, slotID, prevSide
    --"connect", playerID, name
    --"disconnect", playerID, name, playerSide, reason_code
    --"crash", playerID, unit_missionID
    --"eject", playerID, unit_missionID
    --"takeoff", playerID, unit_missionID, airdromeName
    --"landing", playerID, unit_missionID, airdromeName
    --"pilot_death", playerID, unit_missionID
end

function onNetConnect(localPlayerID)
end

function onNetMissionChanged(newMissionName)
end

function onNetDisconnect(reason_msg, err_code)
end

-- disconnect reason codes:
  net.ERR_INVALID_ADDRESS
  net.ERR_CONNECT_FAILED
  net.ERR_WRONG_VERSION
  net.ERR_PROTOCOL_ERROR
  net.ERR_TAINTED_CLIENT
  net.ERR_INVALID_PASSWORD
  net.ERR_BANNED
  net.ERR_BAD_CALLSIGN

  net.ERR_TIMEOUT
  net.ERR_KICKED


function onPlayerConnect(id)
end

function onPlayerDisconnect(id, err_code)
    -- this is never called for local playerID
end

function onPlayerStart(id)
    -- a player entered the simulation
    -- this is never called for local playerID
end

function onPlayerStop(id)
    -- a player left the simulation (happens right before a disconnect, if player exited by desire)
    -- this is never called for local playerID
end

function onPlayerChangeSlot(id)
    -- a player successfully changed the slot
    -- this will also come as onGameEvent('change_slot', playerID, slotID),
    -- if allowed by server.advanced.event_Connect setting
end


--- These 3 functions are different from the rest:
--- 1. they are called directly from the network code, so try to make them as fast as possible
--- 2. they return a result
-- The code shows the default implementations.

function onPlayerTryConnect(addr, name, ucid, playerID) --&gt; true | false, "disconnect reason"
    return true
end

function onPlayerTrySendChat(playerID, msg, all) -- -&gt; filteredMessage | "" - empty string drops the message
    return msg
end

function onPlayerTryChangeSlot(playerID, side, slotID) -- -&gt; true | false
    return true
end
</code></pre>
<h2><a name="gui-callbacks"></a> GUI Callbacks.</h2>
<pre><code>function onChatMessage(message, from)
    -- this one may be useful for chat archiving
end

function onShowRadioMenu(a_h)
end

function onShowPool()
end

function onShowGameMenu()
end

function onShowBriefing()
end

function onShowChatAll()
end

function onShowChatTeam()
end

function onShowChatRead()
end

function onShowMessage(a_text, a_duration)
end

function onTriggerMessage(message, duration, clearView)
end

function onRadioMessage(message, duration)
end

function onRadioCommand(command_message)
end
</code></pre>
<hr />
<p>Happy hacking!</p>
<p>Sincerely,
dsb at eagle dot ru</p>
<p><a href="#intro">To the top.</a></p>