mirror of
https://github.com/ciribob/DCS-CTLD.git
synced 2026-07-16 22:32:43 +00:00
David Pierron
76 lines
4.6 KiB
Markdown
76 lines
4.6 KiB
Markdown
# 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.
|