@jtff/miztemplate-lib

Bibliothèque Node.js pour injecter les scripts JTFF dans une mission DCS World (.miz), générer un workspace de travail, reconstruire les missions et les publier (FTP / Google Drive).

Licence : GPL-3.0-or-later

Prérequis

• Node.js >= 18
• npm
• Un fichier mission DCS World (.miz)

Démarrage rapide (recommandé)

Pour un usage quotidien, préférez le CLI @jtff/template-builder, qui s’appuie sur cette bibliothèque :

npx @jtff/template-builder inject ./ma-mission.miz

Répondez aux prompts interactifs (Entrée = valeur par défaut).
Le workspace est créé dans out/<nom-de-la-mission>/.

Astuce cache npx : si le comportement ne correspond pas à la dernière version publiée, forcez le rafraîchissement :

npx --yes @jtff/template-builder@latest inject ./ma-mission.miz

Installation en dépendance

npm install @jtff/miztemplate-lib

Concepts

| Concept | Rôle | |---|---| | Mission source | Fichier .miz DCS à transformer | | Workspace | Dossier de travail généré (settings/, src/, resources/, .workspace/, scripts CI) | | Injection | Ajout des libs (Moose, Mist, Skynet, Hound…), scripts JTFF, settings, sons, radios, etc. dans le .miz | | Build | Reconstruction du .miz de sortie à partir du template + fichiers du workspace | | Publication | Upload FTP ou Google Drive via les fichiers *.pub.json |

Workflow utilisateur typique

1. Injecter          →  crée le workspace + un .miz enrichi
2. Personnaliser     →  éditer settings/, src/, resources/
3. Construire        →  npm run build  (génère le .miz versionné)
4. Tester en DCS
5. Publier           →  FTP / Google Drive (optionnel)
6. Version suivante  →  release / nextversion-prepare

1. Injection

Via le CLI :

npx @jtff/template-builder inject /chemin/vers/test.miz

Ou en code :

const templatelib = require("@jtff/miztemplate-lib");

const jtffci = new templatelib.MizTemplateCI({
  general: { missionFolder: "out" },
});

templatelib.injectScripts(jtffci, "/chemin/vers/test.miz");

Prompts proposés

| Prompt | Défaut | Contenu injecté (extrait) | |---|---|---| | inject_tankers | non | Tankers + settings associés | | inject_airboss | non | Airboss + sons | | inject_awacs | non | AWACS | | inject_atis | non | ATIS | | inject_A2A | non | CAP / FOX / QRA / Intercept / RAT… | | inject_Logistics | non | Logistique | | inject_A2G | non | Ranges, SAMs, Reapers, ELINT, Skynet… | | inject_mission | oui | Script mission spécifique 200-mission.lua | | inject_radio_presets | non | Presets radio du théâtre |

Des éléments de base sont toujours injectés (SplashDamage, Moose, Mist, Skynet/Hound, menus JTFF, settings globaux, sons généraux, etc.).

2. Structure du workspace

Pour une mission test.miz et missionFolder: "out" :

out/test/
├── test.miz                          # mission injectée
├── config.json                       # config du projet généré
├── package.json                      # scripts npm CI
├── settings/test/                    # settings Lua à personnaliser
├── src/test/                         # scripts mission spécifiques
├── resources/
│   ├── radios/                       # presets radio (par théâtre)
│   ├── sounds/
│   ├── config/
│   └── kneeboards/
│       ├── common/
│       └── test/
└── .workspace/
    ├── src/                          # copies des scripts lib
    ├── lib/
    └── src/nodejs/                   # scripts CI (build, clean, …)

Personnalisez surtout :

• settings/<mission>/settings-*.lua
• src/<mission>/ (scripts spécifiques)
• resources/ (sons, kneeboards, radios, config)

3. Build du projet généré

Dans le workspace :

cd out/test
npm install
npm run build

Le fichier de sortie suit le motif :

<missionFolder>/<prefix>_<theatre>[_<suffix>]_<version>.miz

Un fichier *.pub.json est aussi généré pour la publication.

4. Scripts npm du projet généré

| Script | Action | |---|---| | npm run build | Construit le(s) .miz versionné(s) | | npm run clean | Supprime le dossier de sortie (missionFolder) | | npm run template-update | Met à jour le .miz template avec la lib | | npm run version | Affiche la version (config.json) | | npm run version -- 1.2.3 | Fixe la version | | npm run release | Retire le suffixe (ex. -snapshot) | | npm run nextversion-prepare | Incrémente le patch | | npm run getmiz | Liste les .miz générés | | npm run gdrive-upload | Publie sur Google Drive | | npm run ftp-upload | Publie via FTP |

Configuration (config.json)

Généré automatiquement à l’injection. Exemple :

{
  "general": {
    "missionFolder": "dist",
    "missionPrefix": "test",
    "missionSuffix": "",
    "missionVersion": "1.0.0-snapshot"
  },
  "google": {
    "scopes": ["https://www.googleapis.com/auth/drive"],
    "tokenPath": "dist/gtoken.json"
  },
  "missionTemplates": [
    {
      "theatre": "Syria",
      "filename": "test.miz",
      "destFolderId": "<google-drive-folder-id>"
    }
  ]
}

Champs principaux

| Champ | Description | |---|---| | general.missionFolder | Dossier de sortie des builds (dist par défaut dans le projet généré ; out via template-builder) | | general.missionPrefix | Préfixe du nom de fichier généré | | general.missionSuffix | Suffixe optionnel | | general.missionVersion | Version semver (1.0.0 ou 1.0.0-snapshot) | | missionTemplates[].theatre | Théâtre DCS | | missionTemplates[].filename | Fichier .miz source / template | | missionTemplates[].destFolderId | ID dossier Google Drive de destination | | missionTemplates[].prefix | (variante sans filename) préfixe du template <prefix>_<theatre>.miz |

Publication

FTP

Variable d’environnement attendue :

export JTFF_FTP_SECRET_JSON='{"host":"...","user":"...","password":"...","folder":"..."}'
npm run ftp-upload

Google Drive

export GDRIVE_TOKEN_CACHE_JSON='{ ... credentials service account ... }'
npm run gdrive-upload

Les fichiers à publier sont décrits par les *.pub.json présents dans missionFolder.

API principale

const {
  MizTemplateCI,   // contexte CI + config + helpers version / chemins / upload
  Mizlib,          // bas niveau : lecture/écriture .miz, injection Lua, sons, radios…
  injectScripts,   // flux interactif d’injection
  doInject,        // injection non interactive (resultats de prompts déjà fournis)
  createProjectSkel,
  build,
  clean,
  templateUpdate,
  getVersion,
  setVersion,
  nextversionPrepare,
  release,
  getmizfiles,
  ftpupload,
  gdriveupload,
} = require("@jtff/miztemplate-lib");

Exemple minimal

const templatelib = require("@jtff/miztemplate-lib");
const config = require("./config.json");

const jtffci = new templatelib.MizTemplateCI(config);

// Nettoyage
templatelib.clean(config);

// Build
templatelib.build(jtffci);

// Version
templatelib.getVersion(jtffci);
templatelib.setVersion(jtffci, "1.2.0", "./config.json");

createProjectSkel(rootPath, missionName)

Crée l’arborescence vide du workspace :

• settings/<missionName>/
• src/<missionName>/
• .workspace/src, .workspace/lib
• resources/radios, sounds, config
• resources/kneeboards/common, resources/kneeboards/<missionName>

Contenu fourni par la bibliothèque

| Dossier | Contenu | |---|---| | lua/lib/ | Bibliothèques tierces (Moose, Mist, Skynet, Hound, SplashDamage…) | | lua/src/ | Scripts JTFF (menus, tankers, airboss, ranges…) | | lua/settings/ | Modèles de settings Lua | | resources/ | Sons, presets radio, kneeboards, configs | | ci/ | Wrappers Node copiés dans .workspace/src/nodejs du projet généré | | scripts/ | Implémentation des commandes exposées par l’API |

Nettoyage

Via CLI :

npx @jtff/template-builder clean

Via API (supprime entièrement config.general.missionFolder) :

templatelib.clean(jtffci.config);

Liens

• Paquet npm : https://www.npmjs.com/package/@jtff/miztemplate-lib
• CLI associé : https://www.npmjs.com/package/@jtff/template-builder
• Issues : https://gitlab.platform.klanik.com/open-source/jtff/miztemplate-lib/-/issues

Licence

GPL-3.0-or-later — © Sebastien LONGO