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

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

Image maps turn an image into an interactive area. The author provides two files:

  * a visible image displayed to the player;
  * a PNG mask where each flat color represents a zone.

The feature is interactive on web, desktop and standalone HTML5 export. On Discord and terminal, the image remains visible as a readable media/fallback, without point & click interaction.

===== Insert an image map =====

Inside room text or inside a HUD panel:

<code yaml>
text: "[[#map:scene:https://cyril-fiesta.fr/jdr-bot/scripts/images/showcase/tavern.png|https://cyril-fiesta.fr/jdr-bot/scripts/images/showcase/tavern-mask.png]]"
</code>

General format:

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

  * ''id'' identifies the map in the room.
  * ''image.png'' is the visible image.
  * ''mask.png'' is the mask image: each solid color represents a zone.

===== Declare zones =====

Zones are declared in the room with ''zones:'' and the map id.

<code yaml>
zones:
  scene:
    colors:
      - color: "#FF0000"
        click: talk_barman
        highlight: true

      - color: "#0000FF"
        click: inspect_room
        hover-tooltip: "Look carefully around the room..."
        highlight: true

      - color: "#00FF00"
        hover-tooltip: "An exit to the street."
        hover-event: inspect_exit
</code>

Each ''colors:'' entry maps one mask color to an interaction.

===== Zone options =====

  * ''color:'' : HTML mask color, in ''#RRGGBB'' format.
  * ''click:'' : id of a local event triggered on click.
  * ''hover-tooltip:'' : text displayed in a hover bubble.
  * ''hover-event:'' : id of a local event triggered on hover.
  * ''highlight: true'' : highlights the zone on hover.

===== Related events =====

Ids referenced by ''click:'' or ''hover-event:'' must match events from the room.

<code yaml>
events:
  - id: talk_barman
    text: |
      The barman grumbles:+n+
      **"Order something or leave."**
    do: "talked_barman.=.1"

  - id: inspect_room
    text: "The low-ceiling room smells like stale ale."

  - id: inspect_exit
    once: true
    text: "Fresh street air slips under the door."
</code>

Usual fields remain available: ''if:'', ''visible-if:'', ''disabled-if:'', ''do:'', ''to:'', ''text:'', ''failure-text:'' and ''once:''. Zones respect conditions carried by the referenced event.

===== once: zone =====

''once: zone'' is useful when the same mask color contains several separated zones. Each component can then trigger once per room visit.

<code yaml>
events:
  - id: touch_bottle
    once: zone
    text: "You inspect an empty bottle."
    do: "bottles.+.1"
</code>

===== Inside a HUD =====

An image map can remain visible inside a HUD panel:

<code yaml>
hud:
  - position: top
    height: 42
    text: "[[#map:scene:/scripts/images/tavern.png|/scripts/images/tavern-mask.png]]"
</code>

Event texts appear in the main flow while the scene remains clickable.

===== Tips =====

  * Use a PNG mask with clean flat colors, no lossy compression.
  * Avoid colors that are too close to each other in the mask.
  * Keep one zone per color when possible; use ''once: zone'' if one color represents several identical elements.
  * Keep a classic choice as fallback if navigation depends entirely on point & click.

See also: [[en:yaml:tooltips|Interactive tooltips]], [[en:yaml:clickable-elements|Clickable elements]], [[en:yaml:hud|HUD panels]].