**Language / Langue :** **FR** | [[en:yaml:imagemaps|EN]]

====== Image maps / Point & clic (YAML) ======

Les image maps transforment une image en zone interactive. L'auteur fournit deux fichiers :

  * une image visible, affichée au joueur ;
  * un masque PNG, où chaque couleur plate correspond à une zone.

La fonctionnalité est interactive sur web, desktop et export HTML5 standalone. Sur Discord et terminal, l'image reste affichée comme média lisible, sans interaction point & clic.

===== Insérer une image map =====

Dans un texte de salle ou dans un encadré HUD :

<code yaml>
texte: "[[#map:scene:https://cyril-fiesta.fr/jdr-bot/scenarios/images/showcase/taverne.png|https://cyril-fiesta.fr/jdr-bot/scenarios/images/showcase/taverne-masque.png]]"
</code>

Format général :

<code>
[[#map:id:image.png|masque.png]]
</code>

  * ''id'' identifie la map dans la salle.
  * ''image.png'' est l'image visible.
  * ''masque.png'' est l'image de masque : chaque couleur pleine représente une zone.

===== Déclarer les zones =====

Les zones se déclarent dans la salle avec la clé ''zones:'' puis l'id de la map.

<code yaml>
zones:
  scene:
    couleurs:
      - couleur: "#FF0000"
        clic: parler_barman
        highlight: true

      - couleur: "#0000FF"
        clic: examiner_salle
        survol-tooltip: "Regardez attentivement la salle..."
        highlight: true

      - couleur: "#00FF00"
        survol-tooltip: "Une sortie vers la rue."
        survol-event: observer_sortie
</code>

Chaque entrée de ''couleurs:'' associe une couleur du masque à une interaction.

===== Options de zone =====

  * ''couleur:'' : couleur HTML du masque, au format ''#RRGGBB''.
  * ''clic:'' : id d'un événement local déclenché au clic.
  * ''survol-tooltip:'' : texte affiché dans une bulle au survol.
  * ''survol-event:'' : id d'un événement local déclenché au survol.
  * ''highlight: true'' : affiche la zone en surbrillance au survol.
  * ''couleur-affichage:'' : couleur utilisée pour la surbrillance ou la peinture permanente.
  * ''mode-affichage:'' : ''plein'' ou ''contour''.
  * ''etat:'' : ''visible'', ''desactive'' ou ''invisible''.

===== Événements associés =====

Les ids référencés par ''clic:'' ou ''survol-event:'' doivent correspondre à des événements de la salle.

<code yaml>
evenements:
  - id: parler_barman
    texte: |
      Le barman grommelle :+n+
      **« On commande ou on dégage. »**
    faire: "parle_barman.=.1"

  - id: examiner_salle
    texte: "La salle est basse de plafond et sent la bière éventée."

  - id: observer_sortie
    once: true
    texte: "L'air frais de la rue passe sous la porte."
</code>

Les événements associés gardent leurs champs habituels : ''si:'', ''faire:'', ''vers:'', ''texte:'', ''texte-ko:'' et ''once:''. Les clés ''visible-si:'' et ''grise-si:'' s'appliquent à la map entière. Pour conditionner une zone précise, utilisez ''etat:'' et ses couches ''si:''.

===== État d'une zone =====

L'état est vérifié à l'affichage et au moment du clic.

^ Valeur ^ Effet ^
| ''visible'' | État par défaut. Le clic, le survol et le tooltip fonctionnent. |
| ''desactive'' | Le clic et la surbrillance de survol sont coupés. Le tooltip reste disponible. Si ''couleur-affichage:'' est définie, la zone reste peinte. |
| ''invisible'' | Le clic, le survol et le tooltip sont coupés. |

Une zone peut porter plusieurs couches ''si:''. Elles sont évaluées dans l'ordre et ne remplacent que les clés qu'elles déclarent.

<code yaml>
zones:
  scene:
    couleurs:
      - couleur: "#F21010"
        clic: trouver_cle
        highlight: true
        si:
          - si: "v_cletrouvee_v.=.1"
            etat: desactive
            couleur-affichage: "#777777"
            mode-affichage: plein
</code>

Une zone décorative peut utiliser ''etat:'' et ''couleur-affichage:'' sans avoir de ''clic:''. Une zone ''desactive'' ou ''invisible'' ne peut pas être déclenchée par un clic forcé envoyé au serveur.

===== once: zone / once: zone-salle =====

Quand une même couleur du masque contient plusieurs zones séparées, chaque composante peut être déclenchée individuellement :

  * ''once: zone'' : chaque composante ne se déclenche qu'une seule fois **par partie** ;
  * ''once: zone-salle'' : les composantes se réarment à chaque retour dans la salle.

<code yaml>
evenements:
  - id: toucher_bouteille
    once: zone-salle
    texte: "Vous inspectez une bouteille vide."
    faire: "bouteilles.+.1"
</code>

===== once: couleur / once: couleur-salle =====

Ces deux valeurs regroupent toutes les taches qui utilisent la même couleur du masque :

  * ''once: couleur'' : le premier clic consomme toute la couleur pour le reste de la partie ;
  * ''once: couleur-salle'' : le premier clic consomme toute la couleur jusqu'à la prochaine visite de la salle.

<code yaml>
evenements:
  - id: toucher_bouteilles
    once: couleur
    texte: "Toutes les bouteilles portent le même symbole."
</code>

Utilisez ''once: zone'' pour traiter séparément plusieurs objets d'une même couleur. Utilisez ''once: couleur'' quand un seul clic doit les désactiver ensemble.

===== apres-clic: - marquer les zones consommées =====

Sur une zone dont l'événement de clic utilise l'un des modes ''zone'' ou ''couleur'', la clé ''apres-clic:'' choisit le rendu une fois l'interaction consommée :

^ Valeur ^ Effet ^
| ''masquer'' | Plus de highlight au survol, zone inerte. |
| ''fixe'' | Highlight affiché en permanence (déjà cliqué). |
| ''"#RRGGBB"'' | Highlight permanent de cette couleur. |

La clé optionnelle ''apres-mode:'' (''plein'' ou ''contour'') change le type de highlight de la marque - par exemple contour au survol, mais remplissage plein une fois l'élément trouvé. Idéal pour un cherche-et-trouve :

<code yaml>
zones:
  scene:
    couleurs:
      - couleur: "#00FFF3"
        clic: toucher_bouteille
        highlight: true
        contour-seul: true
        apres-clic: "#000000"
        apres-mode: plein
</code>

Avec les variantes ''zone'' et ''couleur'', les marques persistent au retour dans la salle. Les variantes ''zone-salle'' et ''couleur-salle'' se réarment à chaque visite.

===== Dans un HUD =====

Une image map peut rester affichée en permanence dans un encadré :

<code yaml>
encadre:
  - position: haut
    hauteur: 42
    texte: "[[#map:scene:/scenarios/images/taverne.png|/scenarios/images/taverne-masque.png]]"
</code>

Les textes d'événements apparaissent alors dans le flux principal pendant que la scène reste cliquable.

===== Conseils =====

  * Utiliser un masque PNG sans compression destructrice, avec des aplats nets.
  * Éviter les couleurs trop proches dans le masque.
  * Garder une zone par couleur quand c'est possible ; utiliser ''once: zone'' ou ''once: zone-salle'' si une couleur représente plusieurs éléments identiques.
  * Prévoir un choix classique de secours si la navigation dépend entièrement du point & clic hors du mode ''ui: plein-ecran''.

Voir aussi : [[fr:yaml:tooltips|Tooltips interactifs]], [[fr:yaml:elements-cliquables|Éléments cliquables]], [[fr:yaml:hud|HUD]].