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.

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.

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

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 is useful when the same mask color contains several separated zones. Each component can then trigger once per room visit.

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

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