ZoneAttackAlert

Version: v3.3.1

A DCS World Lua mission script that sends coalition-specific attack alerts when ground or ship units inside defined trigger zones are hit.

Overview

ZoneAttackAlert monitors the DCS World event stream for S_EVENT_HIT events. When a ground unit or ship inside a configured trigger zone is hit, the script broadcasts a location-aware alert message to the coalition that owns the actual unit being hit (read dynamically via target:getCoalition()). Blue coalition receives distances in nautical miles (NM) and English alert text; Red coalition receives distances in kilometers (KM) and German alert text. A per-zone cooldown timer prevents message spam.

Features

• S_EVENT_HIT only — Listens exclusively for hit events; no kill or dead event handling
• No friendly-fire filter — Alerts trigger regardless of which coalition fired the shot
• Ground + Ship target filter — Alerts only for Unit.Category.GROUND_UNIT and Unit.Category.SHIP
• Zone-based filtering — Only hits inside configured trigger zones produce alerts
• Per-zone cooldown — 180-second cooldown prevents message spam per trigger zone; each zone alerts independently
• Dynamic location callouts — Location strings built at alert-time from zone center to nearest airbase, using the recipient's preferred units
• Coalition-specific language — English for Blue (ALERT: Friendly forces under attack!); German for Red (ALARM: Freundliche Kräfte unter Beschuss!)
• Coalition-specific units — NM for Blue, KM for Red
• Cardinal direction navigation — Location described as "north-east of Kobuleti" (Blue, in English) or "nordöstlich von Kobuleti" (Red, in German)
• Nearest airbase reference — All distances are relative to the closest airbase
• Reload-safe — Duplicate script loads are detected and skipped, preventing double alerts
• Debug logging — Toggle config.debug to emit [ZAA] prefixed diagnostics to DCS.log

Logic Flow Diagrams

Initialization Flow

Event Handler Flow

Airbase Distance Lookup

Cooldown Logic

Message Construction Flow

Changes in v3.3

Robust Coalition Detection

Configuration

ZAA.config = {
    zone_names = {
        "RT1", "RT2", "RT3", "RT4", "RT5",
        "BT1", "BT2", "BT3", "BT4", "BT5"
    },
    message_cooldown = 180,   -- seconds per zone
    message_duration   = 18,  -- seconds on screen
    debug              = false, -- enable DCS.log diagnostics
}

Zone prefixes:

• RT* — Red Team trigger zones
• BT* — Blue Team trigger zones

Note: Prefixes are for organisational convenience only. Alert routing is determined by target:getCoalition() at runtime, so a Blue unit inside an RT* zone will alert Blue, and a Red unit inside a BT* zone will alert Red.

Debug Logging

Set debug = true in the config table to emit detailed diagnostics to the DCS log file. When enabled the script logs every step of event processing, including zone cache initialization, hit-event receipt, target category validation, distance checks against each zone, cooldown state, the detected target coalition, and the final alert dispatch. This produces zero runtime overhead when disabled.

Script Architecture

ZoneAttackAlert.lua
├── RELOAD GUARD (skip if ZAA.loaded already set)
├── ZAA CONFIGURATION (table, user-editable)
├── GLOBAL LOCALIZATION (captured locals for hot path)
├── STATIC DATA (cardinal_directions)
├── ZONE CACHE (built at load time; geometry only, no coalition)
├── AIRBASE CACHE (built at load time; nearest-airbase lookup)
├── build_zone_loc() (runtime location formatter, NM for Blue / KM for Red)
│   └── Compass bearing: atan2(East, North) using DCS axes (+x=N, +z=E)
├── STATE (last_alert_time table)
└── EVENT HANDLER (onEvent -> S_EVENT_HIT only, stored in ZAA.event_handler)

DCS Coordinate System Reference

ZoneAttackAlert uses the DCS world coordinate system for all bearing and distance calculations:

• +x = North
• +z = East
• +y = Up (altitude)

The compass bearing from North is computed with the standard formula:

local north_offset = px - airbase.x   -- positive when target is North
local east_offset  = pz - airbase.z   -- positive when target is East
local bearing_deg  = math.deg(math.atan2(east_offset, north_offset)) % 360

This follows the DCS scripting engine FAQ definition (atan2(East, North)) and requires no additional rotational offsets. The result is a clockwise bearing from North in the range [0, 360).

Installation

1. Copy ZoneAttackAlert.lua to your DCS mission's trigger DO SCRIPT action or load it via require in your mission scripting
2. Ensure trigger zones named RT1–RT5 and BT1–BT5 exist in your mission
3. Run the mission; alerts appear automatically when criteria are met

Dependencies

• DCS World (any version supporting world.addEventHandler)
• No external libraries required (standalone)

Version History