Runtime API

Medusa exposes a small public API on Medusa.API for other mission scripts to call at runtime. These functions are available after Medusa finishes initialization (after the DO SCRIPT FILE trigger fires).

ROE Control

Medusa.API.setROE(networkName, roeValue)

Changes the Rules of Engagement for a network.

Parameters:

• networkName (string): The network name from your MEDUSA_CONFIG, e.g. "RED" or "PVO"
• roeValue (string): One of "FREE", "TIGHT", or "HOLD"

Returns: true on success, false if the network was not found or the ROE value was invalid.

Example: trigger zone sets HOLD when friendlies enter

-- In a DO SCRIPT trigger action:
Medusa.API.setROE("RED", "HOLD")

Example: scheduled ROE change

-- Set HOLD at mission start, FREE after 10 minutes
timer.scheduleFunction(function()
    Medusa.API.setROE("RED", "FREE")
    return nil
end, nil, timer.getTime() + 600)

Medusa.API.getROE(networkName)

Returns the current ROE for a network.

Parameters:

• networkName (string): The network name

Returns: The ROE string ("FREE", "TIGHT", or "HOLD"), or nil if the network was not found.

local roe = Medusa.API.getROE("RED")
if roe == "HOLD" then
    trigger.action.outText("RED IADS is weapons hold", 10)
end

Posture Control

Medusa.API.setPosture(networkName, postureValue)

Changes the posture (war footing) for a network. This controls how fast the IADS identifies contacts and what criteria are needed to declare them hostile.

Parameters:

• networkName (string): The network name from your MEDUSA_CONFIG
• postureValue (string): One of "HOT_WAR", "WARM_WAR", or "COLD_WAR"

Returns: true on success, false if the network was not found or the value was invalid.

Example: escalate when first bomb drops

-- In a DO SCRIPT trigger when hostilities begin:
Medusa.API.setPosture("SyADF", "HOT_WAR")

Medusa.API.getPosture(networkName)

Returns the current posture for a network.

Parameters:

• networkName (string): The network name

Returns: The posture string ("HOT_WAR", "WARM_WAR", or "COLD_WAR"), or nil if the network was not found.

local posture = Medusa.API.getPosture("SyADF")
if posture == "COLD_WAR" then
    trigger.action.outText("SyADF is in peacetime posture", 10)
end

EMCON Control

Medusa.API.setEMCON(networkName, policyValue, role)

Changes the emission control policy for a network. If role is omitted, all roles are set to the same policy.

Parameters:

• networkName (string): The network name from your MEDUSA_CONFIG
• policyValue (string): One of "MINIMIZE", "PERIODIC_SCAN", "COORDINATED_ROTATION", "ALWAYS_ON"
• role (string, optional): A specific role, a group, or omitted for all roles.
  • Individual: "VLR_SAM", "LR_SAM", "MR_SAM", "SR_SAM", "AAA", "GENERIC_SAM", "EWR", "GCI"
  • Groups: "SAM" (all SAM + AAA roles), "RADAR" (EWR + GCI)
  • Omitted: sets all roles

Returns: true on success, false if the network, policy, or role was invalid.

Changes take effect on the next tick (~100ms). EmconService reads the doctrine every tick.

Example: escalate all radars to always-on

Medusa.API.setEMCON("RED", "ALWAYS_ON")

Example: set only long-range SAMs to periodic scan

Medusa.API.setEMCON("RED", "PERIODIC_SCAN", "LR_SAM")

Example: all SAMs to periodic scan, radars always on

Medusa.API.setEMCON("RED", "PERIODIC_SCAN", "SAM")
Medusa.API.setEMCON("RED", "ALWAYS_ON", "RADAR")

Example: staged escalation via timer

-- Transition EMCON: PERIODIC_SCAN at T+600s, ALWAYS_ON at T+1200s
timer.scheduleFunction(function()
    Medusa.API.setEMCON("RED", "PERIODIC_SCAN")
    return nil
end, nil, timer.getTime() + 600)

timer.scheduleFunction(function()
    Medusa.API.setEMCON("RED", "ALWAYS_ON")
    return nil
end, nil, timer.getTime() + 1200)

Medusa.API.getEMCON(networkName, role)

Returns the current EMCON policy for a specific role.

Parameters:

• networkName (string): The network name
• role (string): The role to query

Returns: The policy string, or the default policy for that role if no override is set, or nil if the network was not found.

local policy = Medusa.API.getEMCON("RED", "LR_SAM")

Medusa.API.setScanTiming(networkName, scanSec, quietSec)

Changes the radar scan and quiet period durations used by PERIODIC_SCAN and COORDINATED_ROTATION policies.

Parameters:

• networkName (string): The network name
• scanSec (number): Seconds the radar is ON per cycle (>= 0)
• quietSec (number): Seconds the radar is OFF per cycle (>= 0)

Returns: true on success, false if values were invalid or network not found.

Note

Changing scan timing mid-mission may cause a brief phase shift in the radar cycle as the modular arithmetic adjusts. Batteries may briefly all radiate or go dark for one cycle.

-- 45 seconds on, 15 seconds quiet
Medusa.API.setScanTiming("RED", 45, 15)

Medusa.API.getScanTiming(networkName)

Returns the current scan and quiet period durations.

Parameters:

• networkName (string): The network name

Returns: scanSec, quietSec (two numbers), or nil, nil if the network was not found.

local scan, quiet = Medusa.API.getScanTiming("RED")

Medusa.API.setRotationGroups(networkName, count)

Changes the number of rotation groups used by the COORDINATED_ROTATION policy. Each group takes turns radiating.

Parameters:

• networkName (string): The network name
• count (number): Number of groups (integer >= 1)

Returns: true on success, false if the value was invalid or network not found.

-- Split radars into 3 groups instead of the default 2
Medusa.API.setRotationGroups("RED", 3)

Medusa.API.getRotationGroups(networkName)

Returns the current number of rotation groups.

Parameters:

• networkName (string): The network name

Returns: The group count (number), or nil if the network was not found.

local groups = Medusa.API.getRotationGroups("RED")

Error Handling

API functions log errors to dcs.log but never throw. If you pass an invalid network name or parameter value, the function returns false or nil and logs the error.