DCS_MissionDev/.github/copilot-instructions.md

Copilot instructions for DCS_MissionDev

These notes teach AI coding agents how to be productive in this DCS World mission-scripting workspace. Keep responses concrete, reference the files below, and prefer making small targeted edits over broad rewrites.

Big picture

• This repo is a DCS mission lab focused on Lua scripting for the MOOSE, MIST, CTLD, and CSAR ecosystems.
• Structure:
  • Root hosts shared framework scripts and utilities: Moose_.lua, Moose.lua, mist.lua, multiple pinned mist_* versions, CTLD.lua, CSAR.lua, plus helper and mission glue scripts (e.g., NukeBlockerScriptv1_2_1.lua, OnBirthMessage.lua).
  • Mission families live under DCS_<Theater>/... with individual .miz files and scenario folders.
  • Purpose-built modules live under Moose_*/* with a main Lua, demo .miz, and a README describing setup.
• Loading order matters in DCS: framework(s) first, then modules, then mission glue. Typical trigger order: Moose_.lua → framework/middleware → module script(s) → custom mission logic.

Core modules and patterns (examples in repo)

• Zone Capture (dual coalition): Moose_DualCoalitionZoneCapture/Moose_DualCoalitionZoneCapture.lua
  • Edit-only config tables: ZONE_CONFIG (BLUE/RED/NEUTRAL lists) and ZONE_SETTINGS (scan/capture/guard).
  • Uses MOOSE classes like ZONE, ZONE_CAPTURE_COALITION, COMMANDCENTER, MISSION; logs via env.info with [CAPTURE Module] prefix.
  • Visuals driven by ZONE_COLORS; contested/attacked overrides ownership color.
• Dynamic Ground Battle: Moose_DynamicGroundBattle/Moose_DynamicGroundBattle.lua
  • User-edit section defines red/blue ZONE:New(...), warehouse STATIC:FindByName(...), and template arrays. After the “DO NOT EDIT BELOW THIS LINE” banner core logic runs.
  • Spawn rates scale with warehouse survival; periodic tasking (ASSIGN_TASKS_SCHED) retasks idle groups; optional infantry movement via MOVING_INFANTRY_PATROLS.
• CTLD: CTLD.lua
  • Large, configurable logistics/troop script; user config at top: smoke, hover pickup, crate rules, pickup/drop/wp zones, vehicle weights, JTAC settings, and transport pilot names.
  • Important distances: ctld.maximumDistanceLogistic, ctld.minimumDeployDistance, etc. Keep names matching ME zones strictly.
• CSAR: CSAR.lua
  • Note: the current file contains an HTML GitHub page artifact. When updating, replace with the raw Lua from ciribob/DCS-CSAR (use the Raw file, not the HTML page).

Developer workflows (what to run and how)

• Script load in missions (Mission Editor → Triggers):
  1. DO SCRIPT FILE Moose_.lua
  2. DO SCRIPT FILE your module(s) (e.g., DualCoalitionZoneCapture or DynamicGroundBattle)
  3. DO SCRIPT FILE mission glue (CTLD/CSAR/others), respecting their config requirements
• Fast mission patching without opening the editor: Patch-MooseMissions/
  • Use Patch-MooseMissions.ps1 to inject or replace a Lua inside a .miz and auto-bump version numbers.
  • See Patch-MooseMissions/README.md for examples (pipeline-friendly; default script location inside miz: l10n/DEFAULT/*.lua).
• Versioning conventions for missions: filenames embed the version (F99th-Operation Ronin 1.4.miz → next 1.5); the patcher respects X, X.Y, X.Y.Z.
• Debugging:
  • Prefer env.info("[Tag] message"); check Saved Games\DCS\Logs\DCS.log. Modules log with distinct prefixes (e.g., [CAPTURE Module]).
  • Common issues: wrong zone/group/static names; framework not loaded first; CTLD/CSAR configs mismatched with ME. Fix by aligning names and load order.

Conventions and gotchas (repo-specific)

• Name matching is strict across modules. Examples to copy:
  • Zones: "Capture Zone-1", "FrontLine7", etc.
  • HQ groups: BLUEHQ, REDHQ for MOOSE COMMANDCENTER/MISSION creation.
  • Warehouses: use Static object Unit Name: RedWarehouse1-1, BlueWarehouse3-1.
• Module layout: top “user config” section, followed by -- DO NOT EDIT BELOW THIS LINE guard. Keep PRs to config when possible; avoid editing engine logic unless necessary.
• Framework pinning: multiple mist_* versions live alongside mist.lua. Mission scripts may expect a specific version; don’t silently swap them—load the version matching the mission.
• CTLD settings commonly used here: ctld.enableCrates, ctld.slingLoad, ctld.pickupZones, ctld.dropOffZones, ctld.wpZones, ctld.transportPilotNames. Follow the existing style when extending.
• CSAR file hygiene: replace HTML artifacts with raw Lua. Verify by ensuring the file starts with Lua, not <!DOCTYPE html>.

Integration points

• MOOSE: all advanced orchestration depends on Moose_.lua/Moose.lua APIs (ZONE, GROUP, STATIC, ZONE_CAPTURE_COALITION, COMMANDCENTER, MISSION, SCORING). Load it first.
• CTLD/CSAR interop: DynamicGroundBattle notes CTLD troops integrate automatically; ensure CTLD is active if you expect troop drops to influence zones.
• VoiceAttack: profiles under Moose_CTLD_Pure/Voice Attack/ are player tooling, not runtime dependencies. Don’t reference them from mission scripts.

Making changes safely

• When adding new zones/templates/warehouses, update the corresponding arrays in the module’s user config and mirror the names in the Mission Editor.
• When changing visuals or scan cadence, update ZONE_COLORS and ZONE_SETTINGS in Zone Capture, or scheduler values in Dynamic Ground Battle.
• For patching .miz with new Moose_.lua/scripts, prefer the PowerShell patcher; it preserves originals and bumps the version.

Pointers to examples in this repo

• Dual coalition capture: Moose_DualCoalitionZoneCapture/README.md and example .miz in same folder.
• Dynamic ground battle: Moose_DynamicGroundBattle/README.md.
• Mission patching: Patch-MooseMissions/README.md.

If anything above is ambiguous (e.g., CSAR expected version, CTLD defaults for a specific mission family), ask for the target mission and we’ll codify the exact load order and script set.