1. Créer le dossier du scénario

Créez un dossier sur votre ordinateur. Son nom est le slug de votre scénario : choisissez un identifiant court, tout en minuscules, avec des underscores (tirets bas) à la place des espaces, sans accents.

À l'intérieur de ce dossier, vous créerez les fichiers décrits dans ce guide. Les fichiers obligatoires sont indispensables pour que le scénario fonctionne. Les fichiers optionnels enrichissent l'expérience mais le jeu marche sans eux.

2. Transmettre le scénario à l'administrateur

Une fois vos fichiers prêts, envoyez le dossier complet à l'administrateur du site (par email, partage de fichier ou autre), accompagné des informations suivantes :

3. meta.php — Période historique Obligatoire

Classe le scénario dans un groupe affiché dans le menu de création de partie.

<?php return ['period' => 'hundred_years_war'];

Pour ajouter une nouvelle période, déclarez-la dans games/hexes_med/create.php ($periodLabels et $periodOrder).

4. map.php — Carte hexagonale Obligatoire

Définit la grille de terrain. La carte est un tableau 2D de valeurs entières, chaque ligne représentant une rangée d'hexagones (de haut en bas).

<?php return [

    'rotation_default'    => 0,           // Rotation initiale : 0, 90, 180 ou 270 degrés
    'type_draw_default'   => 'generic',   // Style graphique (laisser 'generic')
    'type_ground_default' => 'greenlands',// Fond de carte (laisser 'greenlands')
    'special_tiles'       => [],          // Tuiles spéciales (laisser [] pour l'instant)

    'offset_x' => 280,   // Décalage horizontal en pixels (centrage de la carte)
    'offset_y' => 215,   // Décalage vertical en pixels

    // La carte : tableau de lignes, chaque ligne = tableau de colonnes
    // Conseil : ajouter les numéros de colonnes en commentaire pour s'y retrouver
    'map' => [
    //   1    2    3    4    5
      [  0,   0,   1,   2,   0 ],  // ligne 1
      [  0,   5,   0,   0,   0 ],  // ligne 2
      [ -1,   0,   3,   0,  -1 ],  // ligne 3 (-1 = case inexistante)
    ],

];

Types de terrain disponibles

Identifiants d'hexagones (hex ID)

Le moteur identifie chaque hexagone par colonne × 100 + ligne. Exemple : colonne 5, ligne 3 → hex ID 503. Les colonnes et lignes commencent à 1.

5. units.php — Unités Obligatoire

Définit toutes les unités des deux camps avec leur position de départ.

<?php

require_once __DIR__ . '/../../unit_types.php'; // indispensable pour les constantes

return [

    // Chaque unité est un tableau associatif
    ['id'=>1, 'name'=>'Nom affiché', 'camp'=>1, 'sprite'=>0,
     'type'=>T_ELITE_CAVALRY, 'side'=>1, 'is_leader'=>0, 'hex'=>503, 'in_game'=>1],

    ['id'=>2, 'name'=>'Chef de guerre', 'camp'=>1, 'sprite'=>0,
     'type'=>T_HEAVY_INFANTRY, 'side'=>1, 'is_leader'=>1, 'hex'=>504, 'in_game'=>1],

    // Camp 2
    ['id'=>10, 'name'=>'Ennemi', 'camp'=>2, 'sprite'=>0,
     'type'=>T_LIGHT_INFANTRY, 'side'=>1, 'is_leader'=>0, 'hex'=>509, 'in_game'=>1],

];

Champs d'une unité

Types d'unités disponibles

6. gamedatas.php — Configuration générale Obligatoire

<?php return [

    // Couleurs des camps (hexadécimal sans #, pour les pions et l'interface)
    'campColor1'   => 'cc0000',   // couleur du texte / bordure camp 1
    'campColor2'   => '003399',   // couleur du texte / bordure camp 2
    'campBgColor1' => 'e88080',   // couleur de fond des pions camp 1
    'campBgColor2' => '7090cc',   // couleur de fond des pions camp 2

    // Noms des camps affichés dans l'interface
    'campName1' => 'Francs',
    'campName2' => 'Sarrasins',

    // Nombre de tours maximum par joueur (total de tours = turn_max × 2)
    'turn_max' => 6,

    // Camp qui joue en premier (1 ou 2)
    'first_camp' => 1,

    // Personnalité IA de base (utilisé si pas de ai.php)
    // aggression 0-5 : témérité au combat
    // pursuit    0-5 : agressivité des déplacements vers l'ennemi
    // objectives 0-5 : priorité aux hexes objectifs
    'ai' => [
        1 => ['aggression' => 3, 'pursuit' => 3, 'objectives' => 2],
        2 => ['aggression' => 3, 'pursuit' => 3, 'objectives' => 2],
    ],

    // Noms traduits du scénario (affichés dans les menus)
    'names' => [
        'fr' => 'Mon Scénario',
        'en' => 'My Scenario',
    ],

];

7. victory.php — Conditions de victoire Obligatoire

<?php return [

    // Camp vainqueur par défaut si aucun objectif n'est rempli au dernier tour
    // 0 = match nul, 1 = camp 1 gagne, 2 = camp 2 gagne
    'default' => 1,

    // Unités commandantes affichées sur l'écran de victoire
    // Format : [camp => id_de_l_unité_dans_units.php]
    'commanders' => [1 => 1, 2 => 10],

    // Objectifs de victoire (vérifiés à chaque fin de tour sauf 'endgame')
    'objectives' => [

        // --- Tuer un chef ---
        [
            'type' => 'leader_killed',
            'camp' => 1,            // camp qui gagne si cette condition est remplie
            'name' => 'Saladin',    // nom exact de l'unité (champ 'name' dans units.php)
            'when' => 'per_turn',   // vérifié après chaque tour
        ],

        // --- Destruction d'un pourcentage de l'armée adverse ---
        [
            'type'   => 'destruction_pct',
            'camp'   => 2,          // camp qui gagne
            'target' => 1,          // camp dont on compte les pertes
            'value'  => 50,         // 50 % des forces (en valeur de mêlée) éliminées
            'when'   => 'per_turn',
        ],

        // --- Contrôle d'hexagones ---
        [
            'type'  => 'control',
            'camp'  => 1,
            'hexes' => [503, 504, 505], // IDs des hexes à contrôler (tous nécessaires)
            'when'  => 'endgame',       // vérifié seulement au dernier tour
        ],

    ],

];

Types d'objectifs

Valeur when

8. ai.php — Intelligence artificielle Optionnel

Ce fichier remplace les paramètres ai de gamedatas.php par des comportements précis et historiquement réalistes. Le fichier contient sa propre documentation complète — il suffit d'ouvrir le fichier de n'importe quel scénario pour y trouver le guide intégral.

Cas simple (une stratégie fixe par camp)

<?php return [
    1 => ['strategy' => 'hold',   'aggression' => 2],
    2 => ['strategy' => 'charge', 'aggression' => 4],
];

Stratégies disponibles

Cas complexe (phases séquentielles)

<?php return [
    1 => ['strategy' => 'hold', 'aggression' => 2],
    2 => [
        'aggression' => 4,
        'phases' => [
            [
                'label'    => 'Arbalétriers en avant',
                'active'   => ['Arbalétriers génois'], // noms dans units.php
                'others'   => 'hold',                  // les autres attendent
                'strategy' => 'advance',
                'exit'     => [                        // plusieurs conditions : passe si l'une est vraie
                    ['losses_pct'    => ['Arbalétriers génois' => 50]],
                    ['turn'          => 4],
                ],
            ],
            [
                'label'    => 'Fuite des Génois',
                'active'   => ['Arbalétriers génois'],
                'others'   => 'hold',
                'strategy' => 'retreat',
                'exit'     => ['all_eliminated' => ['Arbalétriers génois']],
            ],
            [
                'label'    => '1ère charge',
                'active'   => 'group:vague_1',
                'others'   => 'hold',
                'strategy' => 'charge',
                'exit'     => ['group_broken' => 'vague_1', 'threshold' => 50],
            ],
            [
                'label'    => '2ème vague',
                'active'   => 'group:vague_2',
                'strategy' => 'charge',
                // Pas de 'exit' : reste ici jusqu'à la fin
            ],
        ],
        'groups' => [
            'vague_1' => [16, 17, 18, 19, 20],  // IDs d'units.php
            'vague_2' => [21, 22, 23, 24, 25],
        ],
        // Modifications historiques de stats (valeur affichée en gris sur les pions)
        'unit_overrides' => [
            'Arbalétriers génois' => ['melee_malus' => -2],
        ],
    ],
];

Conditions de sortie de phase

9. context.php — Texte historique Optionnel

Texte affiché sur la page publique du scénario. Il doit expliquer le contexte historique, les forces en présence, et peut mentionner les modifications de stats (unit_overrides) si besoin.

<?php return [

    'fr' => "En [date], [résumé historique court, 2-4 phrases].

Ce scénario reconstitue [moment clé]. Les [camp 1] doivent [objectif],
tandis que les [camp 2] cherchent à [objectif adverse].

Note historique : [expliquer ici les unit_overrides si utilisés,
ex : les arbalétriers génois avaient laissé leurs boucliers sur les chariots,
réduisant leur valeur de défense de 2 points].",

    'en' => "In [date], [short historical summary].

This scenario recreates [key moment]...",

];

Enrichissement depuis le panneau d'administration

Une fois le scénario en ligne, l'administrateur peut compléter la page publique sans modifier context.php, directement depuis le panneau admin :

• Texte override : réécrire ou enrichir le texte par langue (écrase context.php)
• Liens externes : ajouter des liens vers des vidéos YouTube, articles, sources historiques — avec titre, durée optionnelle, note courte et langue(s) de destination
• Images : uploader context_img.jpg et context_map.jpg (voir section suivante)

Ces enrichissements sont stockés dans context_override.json (généré automatiquement, ne pas créer à la main).

10. Images du scénario Optionnel

Deux images peuvent illustrer la page publique du scénario. Elles sont uploadées directement depuis le panneau d'administration — pas besoin de les créer dans le dossier.