EWRS - Early Warning Radar System

Version: v5.2.3

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.

A slotID nil guard and unitName whitespace trimming prevent crashes when spectators or unslotted players are present.
radarIndex is not reset when the player list is rebuilt, so round-robin messaging continues across list rebuilds.

3. Radar Detection (15-second cycle)

pictureUpdate() drives the detection pipeline:

findRadarUnits() scans all group names in blueRadarsByName and redRadarsByName, populating blueEwrUnits and redEwrUnits.
findDetectedTargets(side) iterates each radar unit, pulls getDetectedTargets(RADAR), applies an Earth curvature / horizon filter, and returns a deduplicated list.
filterUnits() performs O(N) hash-map deduplication and filters to air units only (Object.Category.UNIT, descriptor categories 0-1).
A nil guard checks getDetectedTargets(RADAR) before iterating to avoid pairs(nil) errors.
Results are stored in currentlyDetectedRedUnits and currentlyDetectedBlueUnits.

4. Zone Aggregation (Picture Report)

picture() runs after radar detection:

Resets all 23 zone counters to 0.
For each detected target, calls mist.pointInPolygon() to determine which zone it falls into.
Increments the appropriate zone's contact counter.
sortPicture() copies zone data into redPicture / bluePicture and sorts by enemy contact count descending.

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):

Gets the player's enemy detected units based on coalition.
For each target, calculates:
Bearing to target (degrees)
Heading from velocity vector
3D range in km
AGL altitude
If useImprovedDetectionLogic is enabled and the target has no distance lock, Range is set to N/A.
Targets below minAltEnemyContact (10m AGL) are filtered out.
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):

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

7. Dynamic Interval Adjustment

adjustInterval() runs every 10 minutes:

Player Count	Interval
>= 40	360s
>= 30	300s
< 30	240s

This keeps total message volume bounded as server population grows.

Key Data Stores

Field	Purpose
`ewrs.blueEwrUnits` / `ewrs.redEwrUnits`	List of active radar unit names per side
`ewrs.currentlyDetectedRedUnits`	Detected targets visible to Blue radars
`ewrs.currentlyDetectedBlueUnits`	Detected targets visible to Red radars
`ewrs.activePlayers`	Table of connected players in valid slots
`ewrs.bluePicture` / `ewrs.redPicture`	Sorted zone summaries for picture reports
`ewrs.groupSettings`	Per-group message toggle state

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

Function	Purpose
`ewrs.displayMessageToAll()`	Main loop. Picks one player per cycle, checks LOS, calls `outText()` or sends empty report. Schedules next run.
`ewrs.buildThreatTable(activePlayer)`	Returns a range-sorted table of `{bearing, range, altitude, heading}` for the player's nearest enemy contacts.
`ewrs.outText(activePlayer, threatTable, LOS)`	Formats and sends the BRA picture report (and optional zone summary) to the player's group via `trigger.action.outTextForGroup`.

Detection & Filtering

Function	Purpose
`ewrs.getDetectedTargets()`	Wrapper that triggers detection for both sides.
`ewrs.findDetectedTargets(side)`	Iterates all radar units of `side`, pulls `getDetectedTargets(RADAR)`, applies horizon/curvature filter, returns deduplicated list.
`ewrs.filterUnits(units)`	O(N) deduplication using a hash map. Also filters to `Object.Category.UNIT` and aircraft descriptor categories only (0-1).
`ewrs.findRadarUnits()`	Resolves radar group names into active unit lists (`blueEwrUnits` / `redEwrUnits`).

Player Management

Function	Purpose
`ewrs.buildActivePlayers()`	Queries `net` API for all connected players, resolves slots to units, populates `activePlayers`.
`ewrs.addPlayer(playerName, groupID, unit)`	Adds one player record and bootstraps default `groupSettings`.
`ewrs.addGroupSettings(groupID)`	Initializes per-group settings (includes `messages` toggle).

Picture / Zone Processing

Function	Purpose
`ewrs.picture()`	Resets zone counters, maps all detected targets into zones via `mist.pointInPolygon`, then calls `sortPicture`.
`ewrs.sortPicture(zonesData)`	Copies zone data into `redPicture` / `bluePicture` and sorts each by enemy contact count descending.

Timing & Intervals

Function	Purpose
`ewrs.adjustInterval()`	Dynamic throttling: increases `messageUpdateInterval` at 30+ and 40+ player thresholds.
`ewrs.pictureUpdate()`	Master scheduler: runs every 15s, chains `buildActivePlayers` -> `findRadarUnits` -> `picture`.

Helpers

Function	Purpose
`getCardinalDirection(deg)`	Converts 0-360 heading to 8-point compass string (N, NE, E, SE, S, SW, W, NW).
`getRangeLabel(range)`	Buckets range into "MAX / LONG / MEDIUM / NEAR / MERGED".
`getAltLabel(alt)`	Buckets altitude into "V HIGH / HIGH / MED-HI / MED-LO / LOW / V LOW".
`getDistance3D(...)`	Euclidean 3D distance.
`getBearing(x1, z1, x2, z2)`	Bearing from (x1,z1) to (x2,z2) in degrees.
`getHeadingFromVec(vec)`	Computes heading from velocity vector.

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.

Dependencies

DCS World scripting environment
mist.lua (MIST scripting framework — used for mist.pointInPolygon)

Files

File	Purpose
`EWRS.lua`	Cleaned production script (use this one)
`EWRS_old.lua`	Original script (kept for reference)
`.luacheckrc`	Luacheck configuration for DCS globals whitelist
`README.md`	This documentation
`README.html`	Rendered HTML with D2 diagrams

Version History

Version	Date	Changes
v4.4	Original	Base version by 4YA PO Modifications. Original zone-based picture reporting and BRA callout system.
v4.5	--	Replaced O(N^2) duplicate check in `filterUnits` with O(N) hash-map implementation. Replaced if/else heading logic with math-based lookup (`getCardinalDirection`). Inlined math functions (`distance3D`, `bearing`) in hot loops as local aliases. Localized global table lookups for performance. Cleaned up redundant code and comments.
v5.0	--	Dead code removal (unused constants, options, variables, `mathAbs`). Wired up `PICTURE_DELAY` and `PICTURE_UPDATE_DELAY`. Changed `pairs` to `ipairs` in `buildThreatTable`. Removed dead `groupSettings` fields (`reference`, `measurements`). Simplified greeting (removed dead "Reference: self" line). Added "No radar contacts found" message when LOS is false. Removed unused variables (`side` fetch in `buildActivePlayers`, `contactType` variable and `unitType` threat field). Spectator crash fix (slotID nil guard, unitName trimming, radarIndex reset). Nil guard for `getDetectedTargets`. Added `mathCos` localization. Added `heartbeatEnabled` / `heartbeatInterval` debug options. Added comprehensive README with D2 diagrams.
v5.1	--	Lua 5.1 compliance fix: removed all `goto`/`::continue::` statements (Lua 5.2 feature incompatible with DCS). Replaced with inverted guard conditions in `buildThreatTable`, `buildActivePlayers`, and `filterUnits`. Heartbeat message now sent to all players in-game (was: log only). Added script-load message to players + log ("EWRS Running v5.1", 5s display). Updated AGENTS.md with Lua 5.1 constraint.
v5.2	--	Bug fix: Removed `ewrs.radarIndex = 1` reset in `buildActivePlayers()` (line 609). This reset was clobbering the round-robin index every 15s, causing `displayMessageToAll()` to always message `activePlayers[1]` only. With this fix, the round-robin properly advances through all players in `activePlayers`. Bumped version string.
v5.2.1	--	Coalition messaging: Localized the "blind" altitude warning so Red players receive German (`"Brutus hat keinen Sichtkontakt. Erhöhen Sie Ihre Höhe"`) and Blue players receive English (`"Kenway is blind on you. Increase your altitude"`). Fixed umlaut encoding (`ö`, `ü`, `ä`) in German strings.
v5.2.2	--	Reload safety: Added a reload guard (`_G.ewrs = { loaded = true }`) to prevent double-registration of event handlers and duplicate timers on hot-reload (`dofile` from the DCS console or mission editor). Also bumped the script-load message version string to `v5.2.2`.
v5.2.3	Current	Bug fixes: (1) Fixed double-escaped `\\n\\n` in the German "blind" altitude warning. The Lua source had `\\n\\n` (4 source chars: backslash-backslash-n-backslash-backslash-n) which Lua parses to 2 literal backslash-n sequences in the message string. The English version was already correct (`\n\n` = 2 source chars = 2 newlines when parsed). Red players below 75m AGL were seeing a literal `\n` at the end of the warning instead of a newline. (2) Fixed inverted heartbeat gating: `trigger.action.outText` was being called unconditionally on every mission start (even with `ewrs.heartbeatEnabled = false`, the default), and only the reschedule was gated on the flag. Moved the `outText` call inside the `if ewrs.heartbeatEnabled` block. (3) Cleanup: 4 unused loop variable `k` → `_` and 1 whitespace-only line. Bumped the script-load message version string to `v5.2.3`.

Installation

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