DCS-CTLD/.github/copilot-instructions.md

Copilot Instructions for DCS-CTLD

Working mode / Mode de travail

• Communication language: French (français) for all conversations and commit messages.
• Documentation language: English for all technical documentation (code comments, docs/, README). French summaries in docs are acceptable but English is the primary language.
• Development methodology: TDD (Test-Driven Development) — write tests before implementation when possible.
• Programming paradigm: OOP Lua 5.1 with metatables and classes. No procedural spaghetti.
• Branching strategy: Git flow on the next branch. Feature branches named feature/<phase>-<description>. Never commit directly to main or next.
• Commit style: Conventional Commits (feat:, fix:, refactor:, test:, docs:, chore:).
• Build target: Individual source modules in src/ are concatenated into a single dist/CTLD.lua deliverable by a build script. Never edit the built file directly.
• MIST dependency: CTLD code must never call mist.* directly. All MIST usage goes through the middleware layer (src/mist_compat/).
• Legacy API: When refactoring a public ctld.* function, always create a deprecated wrapper in src/compat/legacy_api.lua that logs a warning and delegates to the new API.
• Refer to the modernization plan: See .github/MODERNIZATION-PLAN.md for the full roadmap and architectural decisions.

Project context

• This repository contains Lua mission scripts for DCS World.
• The primary script is CTLD.lua.
• Internationalization tables are split between CTLD.lua (English reference keys) and CTLD-i18n.lua (translated values).
• Runtime is DCS mission scripting environment (Lua 5.1, metatables available, no LuaJIT, no goto).
• Assumes desanitized server (io, os, lfs accessible).
• MIST is being progressively replaced by an internal middleware layer.

Architecture (v2 target)

• Source modules live in src/ organized by domain: lib/, core/, transport/, logistics/, jtac/, ui/, recon/, ai/, compat/, mist_compat/.
• OOP via a micro class system using metatables (src/lib/class.lua).
• State is managed by a StateManager singleton and per-coalition Coalition instances — no more ctld.xxxRED/ctld.xxxBLUE table pairs.
• Tests live in test/ and use busted with DCS/MIST mocks.

Compatibility (v1 legacy)

• Preserve existing public ctld.* APIs used by Mission Editor DO SCRIPT triggers.
• Do not rename exported ctld functions or change their parameter semantics unless explicitly requested.
• Keep behavior compatible with existing .miz missions in this repository.
• Keep script load order assumptions intact: MIST first, CTLD-i18n.lua before CTLD.lua.

CTLD.lua editing rules

• Keep user-tunable options in the USER CONFIGURATION section with clear comments and safe defaults.
• Keep coalition conventions consistent:
  • 1 = red
  • 2 = blue
  • 0 = both (where applicable)
• Keep pickup/dropoff/waypoint zone tuple formats compatible with current parser logic.
• Keep crate weight values unique in ctld.spawnableCrates.
• Preserve callback behavior and action names used by ctld.processCallback.
• Use defensive nil checks before calling methods on DCS objects (Unit/Group/zone lookups).
• Prefer existing logging patterns (ctld.logInfo, env.info, env.error) over ad-hoc prints.
• Avoid adding heavy polling loops; prefer bounded searches and scheduled checks.

I18N rules

• For every new player-visible string, add an English reference key and use ctld.i18n_translate at call sites.
• Do not hardcode new menu or gameplay text without i18n_translate.
• When adding keys, keep translation_version alignment in mind and add placeholders in CTLD-i18n.lua tables.
• Do not remove or rename existing i18n keys unless all language tables are updated.

Testing expectations

• Prefer the dynamic loading workflow documented in README for fast iteration.
• After gameplay logic changes, validate at least:
  • troop load/unload flows
  • crate spawn/load/unpack flows
  • JTAC-related flows (if touched)
• Use repository missions for smoke tests when relevant:
  • test-dev-dynamic.miz
  • test-dev-static.miz
  • test-mission.miz
• If user-facing behavior or configuration changes, update README examples in the same change.

Code style conventions

• Follow existing file style and indentation.
• OOP Lua 5.1: use the project class system (src/lib/class.lua) for new classes.
• For internal helpers, follow existing naming patterns (local variables often prefixed with _).
• Keep mission-designer guidance comments concise and practical.
• No direct mist.* calls — use the middleware.
• Every new public function should have at least one unit test.