EWRS - Early Warning Radar System

Version: v5.3.0

Overview

EWRS.lua is a DCS World Lua mission script that provides automated Early Warning Radar (EWR) picture reports and BRA (Bearing/Range/Altitude) callouts to players based on ground-based radar detection.

Designed for the 4YA Project Overlord WWII Normandy theatre, the script scans designated ground radar units, collects their detected targets, filters for airborne units, categorizes them into geographic zones, and periodically sends formatted reports to active players who have line-of-sight (LOS) to at least one friendly radar.

The system is designed to: - Distribute per-player BRA callouts (automated, via scheduled timers) - Provide a general "picture" overview of enemy concentrations per zone - Scale update rates dynamically based on server population - Only report targets visible above the radio/radar horizon (Earth curvature approximation)

How It Works

1. Script Initialisation

-- All tunables live at the top of EWRS.lua
ewrs.messageUpdateInterval = 240        -- seconds between full message cycles
ewrs.messageDisplayTime = 20             -- seconds each message stays on screen
ewrs.enableRedTeam = true               -- enable for Axis/Red
ewrs.enableBlueTeam = true               -- enable for Allies/Blue
ewrs.useImprovedDetectionLogic = true    -- suppress range for targets without distance lock
ewrs.maxThreatDisplay = 2                -- max threats in BRA table (0 = unlimited)
ewrs.PictureCallouts = true              -- enable zone picture reports
ewrs.NoOfPictures = 2                     -- how many zone summaries to show
ewrs.heartbeatEnabled = false              -- periodic "script is still running" in-game message for debugging
ewrs.heartbeatInterval = 10               -- seconds between heartbeat messages
ewrs.minAltFriendlyContact = 75           -- AGL below which player gets "blind" warning
ewrs.minAltEnemyContact = 10              -- AGL below which enemy contacts are ignored

• Radar groups are configured by coalition: ```lua ewrs.blueRadarsByName = { "Allied RADAR ENG", "Allied RADAR Beaches", "RT2 Radars", }

ewrs.redRadarsByName = { "FREYA", "Freya 1", } `` *initializeZones()` sets up the 23 named polygon zones covering the Normandy map and adjacent Channel areas.

2. Player Discovery

buildActivePlayers() queries net.get_player_list() for all connected players, resolves slots to actual units, and populates activePlayers.

• Missing player names, slots, unit names, units, and groups are skipped. Each player lookup is protected separately so a stale object cannot prevent later players from being discovered.
• The round-robin cursor is anchored to a player name (ewrs.radarNextPlayer), not a list index, so a player joining or leaving the server cannot make the cycle skip someone or waste a report slot.

3. Radar Detection (15-second cycle)

pictureUpdate() drives the detection pipeline:

1. findRadarUnits() scans all group names in blueRadarsByName and redRadarsByName, populating blueEwrUnits and redEwrUnits.
2. findDetectedTargets(side) iterates each radar unit, pulls getDetectedTargets(RADAR), applies an Earth curvature / horizon filter, and returns a deduplicated list. The geometric horizon is sqrt(2 * R * radar_height) + sqrt(2 * R * target_height), with R = 6,371,000 m. Heights are above sea level (clamped to zero), and range is horizontal. For example, a radar at 1,000 m and a target at 100 m have a combined horizon of approximately 148.6 km. DCS radar detection still determines terrain masking.
3. filterUnits() performs O(N) hash-map deduplication and filters to air units only (Object.Category.UNIT, descriptor categories 0-1).
4. A nil guard checks getDetectedTargets(RADAR) before iterating to avoid pairs(nil) errors.
5. Results are stored in currentlyDetectedRedUnits and currentlyDetectedBlueUnits. Both lists are always replaced, even when a side has no radar units, so a destroyed radar cannot leave stale contacts in the picture report.

4. Zone Aggregation (Picture Report)

picture() runs when a report consumes the picture (see Lazy picture below):

1. Resets all 23 zone counters to 0.
2. For each detected target, calls findZone() to determine which zone it falls into.
3. findZone() first rejects zones using a precomputed bounding box (ewrs.zoneBounds), then runs the full point-in-polygon test only on surviving candidates. The zone boxes are pairwise disjoint, so this eliminates the vast majority of polygon tests.
4. pointInPolygon() is a local, allocation-free ray-casting test equivalent to mist.pointInPolygon for the {x=, z=} zone vertex format.
5. Increments the appropriate zone's contact counter.
6. sortPicture() copies zone data into redPicture / bluePicture and sorts by enemy contact count descending.

The picture is lazy: findRadarUnits() sets ewrs.pictureDirty when detection data changes, and updatePicture() re-aggregates only when a report actually reads the picture. Previously the aggregation ran on a fixed 8-second timer whether or not a report was sent, which wasted most of the work at low player counts.

23 zones cover: LE HAVRE, ROUEN, BERNAY, EVREUX, LAIGLE, ARGENTAN, ESSAY, CABOURG, VILLERS_BOCAGE, BAYEUX, FLERS, ST.LO, AVRANCHES, CARENTAN, CHARTRES, PARIS, BEAUVAIS, CHANNEL WEST, CHANNEL CENTRAL, CHANNEL EAST, ISLE OF WIGHT, SELSEY, BEACHY_HEAD.

5. Threat Table Building (per player)

buildThreatTable(activePlayer):

1. Gets the player's enemy detected units based on coalition.
2. For each target, calculates:
3. Bearing to target (degrees)
4. Heading from velocity vector
5. 3D range in km
6. AGL altitude
7. If useImprovedDetectionLogic is enabled and the target has no distance lock, Range is set to N/A.
8. Targets below minAltEnemyContact (10m AGL) are filtered out.
9. Results are sorted by range ascending (ipairs iteration) and returned.

6. Message Display (round-robin)

displayMessageToAll() runs every N seconds (default 240s, up to 360s at high player counts):

1. Picks 1 player round-robin from the active player list.
2. Checks line-of-sight (LOS) to any friendly radar.
3. If LOS is false, player receives "No radar contacts found".
4. If messages are enabled in groupSettings, builds the threat table.
5. outText() formats and sends the BRA report via trigger.action.outTextForGroup.
6. If player AGL is below minAltFriendlyContact (75m), appends "Kenway/Brutus is blind".
7. If PictureCallouts is enabled, appends the top zone summaries.

7. Dynamic Interval Adjustment

adjustInterval() runs every 10 minutes:

This keeps total message volume bounded as server population grows.

8. Reload Safety

All scheduled callbacks are registered through scheduleTracked(), which records the timer id in a per-instance registry (_G.EWRS_TIMER_IDS).

• The registry lives outside the ewrs table on purpose: the documented recovery for a stuck script is to nil _G.ewrs and dofile() the file again. Because the registry survives that, the new instance cancels the previous instance's chains before arming its own — otherwise both copies would keep reporting.
• ewrs.shutdown() cancels every timer the instance scheduled and clears the loaded flag, so a later dofile() starts a clean instance.

Key Data Stores

Coordinate System Notes

• DCS mission editor uses (x, y) for 2D positions.
• Lua runtime uses (x, z) where z corresponds to the mission editor y.
• All zone polygons in ewrs.Zones are defined in the N1 Normandy coordinate space.

Logic Flow Diagrams

Overall System Architecture

Overall System Architecture

pictureUpdate Loop (15s cycle)

pictureUpdate Loop (15s cycle)

Radar Detection Pipeline

Radar Detection Pipeline

Threat Table Building (per player)

Threat Table Building (per player)

Message Display Pipeline (per player)

Message Display Pipeline (per player)

Zone Processing (Picture Report)

Zone Processing (Picture Report)

Player Management

Player Management

Interval Adjustment Logic

Interval Adjustment Logic

Function Reference

Core / Display

Detection & Filtering

Player Management

Picture / Zone Processing

Timing & Intervals

Helpers

Performance Notes

• O(N) deduplication: filterUnits uses a hash map instead of nested loops.
• Round-robin messages: Only one player is messaged per cycle to avoid burst lag.
• Interval scaling: Higher player counts increase the cycle length so total message volume stays bounded.
• Localizations: Hot globals (table.insert, math.sqrt, trigger.action.outTextForGroup, etc.) are aliased to locals for faster lookup. Added mathCos localization for consistency.
• Allocation-free geometry: ewrs.pointInPolygon replaces mist.pointInPolygon, which deep-copies the polygon and allocates a Vec3 per vertex on every call. The local test allocates nothing.
• Bounding-box prefilter: ewrs.zoneBounds lets findZone() reject a zone with four integer comparisons before running the polygon test. The 23 zone boxes are pairwise disjoint, so at most one zone survives the prefilter for any point.
• Lazy picture: zone aggregation runs only when a report reads the picture, instead of on a fixed timer that fired whether or not anyone was listening.
• Reload safety: a single timer registry makes the whole script cancelable, so a reload does not leave a second copy reporting alongside the first.

Dependencies

• DCS World scripting environment
• No MIST dependency. The zone point-in-polygon test is implemented locally (ewrs.pointInPolygon), so mist.lua no longer has to be loaded before this script.

Files

Version History

Installation

1. Copy EWRS.lua into your DCS mission's "Scripts" folder or "l10n/DEFAULT" folder.
2. Update ewrs.blueRadarsByName and ewrs.redRadarsByName in the script to match your mission's radar group names.
3. The 23 default zones are calibrated for the Normandy (N1) map. If using a different theatre, adjust ewrs.Zones polygon coordinates.
4. Start the mission and check the server log for: EWRS Running v5.3.0
5. Players with LOS to friendly radar should begin receiving BRA callouts after the first cycle (~15 seconds).