4YA Project Overlord – HQ Mission Subscription Script

Version: 2.2

Overview

4YA_HQ.lua is a DCS World Lua mission script that adds a dynamic HQ mission subscription system. Players use the F10 menu to register for pre-defined strike / escort objectives. Once enough players sign up for the same target, an AI support flight is automatically scheduled and spawned to accompany them.

Designed for the 4YA Project Overlord WWII Normandy theatre, the script coordinates ground-attack sorties for both Allied (blue) and Axis (red) coalitions across a rotating set of 8 mission days.

How It Works

1. Script Initialisation

function HQ.Init()
  HQ.UnitsList()              -- Scan existing DCS groups to find safe IDs
  HQ.assignedPlayers_Init()   -- Build empty roster tables for current mission
  HQ.update()                 -- Start periodic player-scan loop (every 15 s)
  timer.scheduleFunction(HQ.countAssignedPlayers, nil, timer.getTime() + 20)
end

• HQ.UnitsList() queries mist.DBs.groupsById / mist.DBs.unitsById to set the starting counters for AI group/unit IDs so dynamically spawned flights never collide with existing mission objects.
• assignedPlayers_Init() walks the mission data table and creates empty player rosters for every target/role slot.

2. Player Discovery (every 15 seconds)

HQ.PlayerGroups() scans all [all][plane] and [all][helicopter] units via mist.makeUnitTable(). For each unit that:

• has a player in it (Unit.getPlayerName() is not nil), and
• is active (Unit.isActive())

the group is added to HQ.PilotGroups and HQ.F10Menu() is called to build customised per-group F10 menus.

3. F10 Menu Construction

HQ.F10Menu() creates a "Mission registration" root menu for each new player group, then populates sub-menus like:

Mission registration
  ├─ Objective: TARGET 1 Coastwatcher radar
  │    ├─ Intended Role: Ground attack
  │    └─ Intended Role: Escort
  └─ Objective: TARGET 2 Naval radar
       ...

Menu entries are cached (HQ.builtF10Menus) so they are built only once per group.

4. Mission Registration

When a player clicks a role, HQ.registeredMission(args) runs:

1. Looks up the pilot name from HQ.PilotGroups.
2. Checks HQ.PlayerOccupied – a player can only register once until they land, crash, die, or leave the aircraft.
3. Calculates RV, IP, and TGT coordinates (ground elevation is filled automatically).
4. Stores the player in HQ.assignedPlayers (global pool + per-role pool).
5. Drops F10 map marks (RV, IP, TGT) for that group only.
6. Broadcasts the intent to the whole coalition.
7. Schedules a text briefing to be sent 15 seconds later.

5. Event Handling (clearing state)

A world.addEventHandler (HQ.playerEventHandler) listens for:

6. AI Support Trigger

HQ.countAssignedPlayers() runs every 20 seconds:

• Counts registered players per mission.
• Finds the mission with the most registrations for each coalition.
• If that count is >= HQ.requiredPlayersForAISupport (default 4) and an AI flight is not already active for that mission, HQ.setupAI() is called.
• A cool-down timer prevents AI spawning more than once every hour for each coalition.

7. AI Setup & Spawn

HQ.setupAI():

1. Generates random offsets around the IP (spawn) and target points.
2. Deep-copies an AI template from AIDB (so the original template is never mutated).
3. Assigns fresh group/unit IDs and names (AI support 1, AI support 2, …).
4. Overwrites the template's waypoints with the actual mission RV, IP and TGT coordinates.
5. Schedules the spawn after TimeToRV seconds.
6. Schedules a proximity check (HQ.AIswitchWP) that switches the AI to their bombing waypoint when the lead player gets within 8 km of the IP.

HQ.BombsAway() polls the AI group's bomb load every 20 seconds. Once all bombs are expended, the AI are sent to their RTB waypoint (#4).

8. Data Tables

HQ.missions[missionNumber][coalition][targetIndex]

{
  Title    = "TARGET 1",
  Target   = "Coastwatcher radar",
  Roles    = { { RoleName = "Ground attack" }, { RoleName = "Escort" } },
  Briefing = "Ramrod 970. Coastwatcher radar station ...",
  Coordinates = {
    RV  = { x = ..., y = ... },
    IP  = { x = ..., y = ... },
    TGT = { x = ..., y = ... }
  },
  TimeToRV = 600   -- seconds until AI spawns
}

AIDB

Two templates per coalition (red[1], red[2], blue[1], blue[2]). These are DCS Group table definitions (identical to mission.lua exports) containing a 4-ship flight with waypoints, tasks, and weapons.

Logic Flow Diagrams

Overall Script Lifecycle

Overall Script Lifecycle

Player Discovery & F10 Menu

Player Discovery & F10 Menu

Mission Registration Flow

Mission Registration Flow

AI Support Spawn Flow

AI Support Spawn Flow

Event Handler (State Cleanup)

Event Handler (State Cleanup)

Installation

1. Copy 4YA_HQ.lua into your DCS mission's "Scripts" folder or "l10n/DEFAULT" folder.
2. In the Mission Editor, create a trigger flag named "Mission" and set it to a value between 1 and 8 (the server rotation day).
3. Add a "Do Script File" trigger at mission start that loads 4YA_HQ.lua.
4. Ensure the MIST scripting framework is loaded before this script.

Fix List (4YA_HQ.lua vs 4YA_HQ_old.lua)

Critical Runtime Bugs

Structural / Scope Fixes

Data / Memory Fixes

Typos / Consistency

Style / Lint

Files

Version History