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.

Inside room text or inside a HUD panel:

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]]"

General format:

[[#map:id:image.png|mask.png]]

• 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.

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

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

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

• 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.

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

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."

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.

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

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

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

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.

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.

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

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.

events:
  - id: touch_bottles
    once: color
    text: "Every bottle bears the same symbol."

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

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:

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:

zones:
  scene:
    colors:
      - color: "#00FFF3"
        click: touch_bottle
        highlight: true
        outline: true
        after-click: "#000000"
        after-mode: fill

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

An image map can remain visible inside a HUD panel:

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

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

• 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: Interactive tooltips, Clickable elements, HUD panels.