EWRS - Early Warning Radar System

Version: v5.1

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:

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 reset when the player list is rebuilt to maintain stable round-robin messaging.

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

flowchart TD A[Game Starts] --> B[Initialize Tables] B --> C[Schedule pictureUpdate Loop] C --> D[Schedule displayMessageToAll Loop] D --> E[Schedule adjustInterval Loop] E --> F{Every 15s} G[pictureUpdate] F --> H{Every N seconds} I[displayMessageToAll] F --> J{Every 10 min} K[adjustInterval] G --> F I --> H K --> J style A fill:#1a1a2e,color:#fff

pictureUpdate Loop (15s cycle)

flowchart TD A[pictureUpdate] --> B[buildActivePlayers] B --> C[Schedule findRadarUnits in 2s] C --> D[Schedule picture in 8s] D --> E[Schedule next pictureUpdate in 15s] style A fill:#1a1a2e,color:#fff

Radar Detection Pipeline

flowchart TD A[findRadarUnits] --> B[Scan blueRadarsByName] A --> C[Scan redRadarsByName] B --> D[Populate blueEwrUnits] C --> E[Populate redEwrUnits] D --> F[getDetectedTargets] E --> F F --> G[findDetectedTargets red] F --> H[findDetectedTargets blue] G --> I{For each radar unit} H --> I I --> J[getController:getDetectedTargets RADAR] J --> K{Target visible?} K -->|Yes| L[Earth curvature check] L -->|Above horizon| M[Collect target] M --> N[filterUnits] N --> O[Hash-map deduplication] O --> P[Filter air units only] P --> Q[Store currentlyDetectedXUnits] style A fill:#1a1a2e,color:#fff style K fill:#e94560,color:#fff style L fill:#e94560,color:#fff

Threat Table Building (per player)

flowchart TD A[buildThreatTable activePlayer] --> B[Get enemy detected units] B --> C[Get self position] C --> D[For each detected target] D --> E{Target exists?} E -->|No| D E -->|Yes| F[Calc bearing to target] F --> G[Calc heading from velocity] C --> I[Calc 3D range in km] G --> I I --> J{useImprovedDetectionLogic?} J -->|Yes & no distance| K[Range = N/A] J -->|No| L[Range = calculated] K --> M[Calc target AGL] L --> M M --> N{Alt > minAltEnemyContact?} N -->|Yes| O[Add to threatTable] N -->|No| D O --> P[Sort by range ascending] P --> Q[Return threatTable] style A fill:#1a1a2e,color:#fff style E fill:#e94560,color:#fff style J fill:#e94560,color:#fff style N fill:#e94560,color:#fff

Message Display Pipeline (per player)

flowchart TD A[displayMessageToAll] --> B{Players connected?} B -->|No| Z[Reschedule with default interval] B -->|Yes| C[Pick 1 player round-robin] C --> D[Check LOS to any friendly radar] D --> E{LOS true?} E -->|No| F["No radar contacts found"] E -->|Yes| G{Messages enabled?} G -->|No| H[Skip] G -->|Yes| I[buildThreatTable] I --> J[outText] J --> K{Player AGL < 75m?} K -->|Yes| L["Kenway/Brutus is blind"] K -->|No| M{Threats found?} M -->|Yes| N[Format BRA header] N --> O[For each threat up to max] O --> P[Format BRG/RNG/ALT/HDG row] P --> Q{PictureCallouts?} M -->|No| R[No nearby targets] R --> Q L --> S[Send message to group] Q -->|Yes| T[Append zone summaries] T --> S Q -->|No| S S --> U[Schedule next cycle / playerCount] style A fill:#1a1a2e,color:#fff style B fill:#e94560,color:#fff style E fill:#e94560,color:#fff style G fill:#e94560,color:#fff style K fill:#e94560,color:#fff style M fill:#e94560,color:#fff style Q fill:#e94560,color:#fff

Zone Processing (Picture Report)

flowchart TD A[picture] --> B[Reset all zone counters to 0] B --> C[processTargets redTargets / blueContacts] B --> D[processTargets blueTargets / redContacts] C --> E[For each target] D --> E E --> F[mist.pointInPolygon] F --> G{Inside zone?} G -->|Yes| H[Increment zone.contactKey] H --> I[Break to next target] G -->|No| J[Check next zone] J --> G I --> K[sortPicture] K --> L[Sort redPicture by blueContacts desc] K --> M[Sort bluePicture by redContacts desc] style A fill:#1a1a2e,color:#fff style G fill:#e94560,color:#fff

Player Management

flowchart TD A[buildActivePlayers] --> B[Query net.get_player_list] B --> C[For each player ID] C --> D[Get name, slot, unitName] D --> E[Unit.getByName] E --> F{Unit active?} F -->|No| C F -->|Yes| G{Coalition enabled?} G -->|Yes| H[addPlayer] G -->|No| C H --> I[Store player, groupID, unitname, side] I --> J{groupSettings missing?} J -->|Yes| K[addGroupSettings] J -->|No| L[Done] K --> L style A fill:#1a1a2e,color:#fff style F fill:#e94560,color:#fff style G fill:#e94560,color:#fff style J fill:#e94560,color:#fff

Interval Adjustment Logic

flowchart TD A[adjustInterval] --> B[Count activePlayers] B --> C{>= 40 players?} C -->|Yes| D[Set interval to 360s] C -->|No| E{>= 30 players?} E -->|Yes| F[Set interval to 300s] E -->|No| G[Set interval to 240s] D --> H[Reschedule adjustInterval in 600s] F --> H G --> H style A fill:#1a1a2e,color:#fff style C fill:#e94560,color:#fff style E fill:#e94560,color:#fff

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

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.1	Current	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.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 Mermaid diagrams.

Installation

Prerequisites
- DCS World server or mission with scripting enabled
- mist.lua (MIST scripting framework) loaded in the mission before EWRS
Mission Setup
- Place EWRS.lua in your mission's script folder
- Add a Mission Start trigger that executes EWRS.lua via "Do Script File"
- Ensure mist.lua is loaded first (add it before EWRS in the trigger order)
Configure Radar Units
- Create ground-based radar units in your mission
- Place them in named groups (e.g., Allied RADAR ENG, FREYA)
- Update ewrs.blueRadarsByName and ewrs.redRadarsByName in EWRS.lua to match your group names
Zone Verification (Optional)
- The 23 default zones are calibrated for the Normandy (N1) map
- If using a different theatre, adjust ewrs.Zones polygon coordinates to match your map
Verification
- Start the mission and check the server log for:
```
EWRS Running v5.1
```
- Players with LOS to friendly radar should begin receiving BRA callouts after the first cycle (~15 seconds)