**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.
  * ''display-color:'' : color used for the highlight or permanent paint.
  * ''display-mode:'' : ''fill'' or ''outline''.
  * ''state:'' : ''visible'', ''disabled'' or ''invisible''.

===== 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>

Related events keep their usual fields: ''if:'', ''do:'', ''to:'', ''text:'', ''failure-text:'' and ''once:''. The ''visible-if:'' and ''disabled-if:'' keys apply to the whole map. To condition a specific zone, use ''state:'' and its ''if:'' layers.

===== Zone state =====

The state is checked both when the map is displayed and when a click is received.

^ Value ^ Effect ^
| ''visible'' | Default state. Click, hover and tooltip work normally. |
| ''disabled'' | Click and hover highlight are disabled. The tooltip remains available. If ''display-color:'' is set, the zone stays painted. |
| ''invisible'' | Click, hover and tooltip are disabled. |

A zone may contain several ''if:'' layers. They are evaluated in order and only replace the keys they declare.

<code yaml>
zones:
  scene:
    colors:
      - color: "#F21010"
        click: find_key
        highlight: true
        if:
          - if: "v_keyfound_v.=.1"
            state: disabled
            display-color: "#777777"
            display-mode: fill
</code>

A decorative zone may use ''state:'' and ''display-color:'' without a ''click:''. A ''disabled'' or ''invisible'' zone cannot be triggered by a forged click sent to the server.

===== once: zone / once: zone-room =====

When the same mask color contains several separated zones, each component can be triggered individually:

  * ''once: zone'': each component triggers only once **per game**;
  * ''once: zone-room'': components re-arm every time the player returns to the room.

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

===== once: color / once: color-room =====

These values group every separate mask area that uses the same color:

  * ''once: color'': the first click consumes the whole color for the rest of the game;
  * ''once: color-room'': the first click consumes the whole color until the next room visit.

<code yaml>
events:
  - id: touch_bottles
    once: color
    text: "Every bottle bears the same symbol."
</code>

Use ''once: zone'' to handle several same-colored objects separately. Use ''once: color'' when one click should disable them together.

===== after-click: - marking consumed zones =====

On a zone whose click event uses one of the ''zone'' or ''color'' modes, the ''after-click:'' key picks how it is rendered once the interaction is consumed:

^ Value ^ Effect ^
| ''hide'' | No more hover highlight, inert zone. |
| ''fixed'' | Highlight shown permanently (already clicked). |
| ''"#RRGGBB"'' | Permanent highlight in that color. |

The optional ''after-mode:'' key (''fill'' or ''outline'') changes the highlight type of the mark - for instance outline on hover, but a full fill once the element is found. Ideal for seek-and-find scenes:

<code yaml>
zones:
  scene:
    colors:
      - color: "#00FFF3"
        click: touch_bottle
        highlight: true
        outline: true
        after-click: "#000000"
        after-mode: fill
</code>

With the ''zone'' and ''color'' variants, marks persist when returning to the room. The ''zone-room'' and ''color-room'' variants reset on each visit.

===== 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'' or ''once: zone-room'' 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]].