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

====== Dialogues and sequences ======

A room text can become a **sequence of replies**: the player clicks to move the conversation forward, with a speaker, a portrait, a frame and a background.

Everything is optional. A sequence without portrait or background is simply a series of replies shown one after another.

===== A first sequence =====

<code yaml>
rooms:
  - id: tavern
    text:
      type: sequence
      replies:
        - speaker: Mara
          text: "You are late. Was the road bad?"
        - speaker: You
          text: "Let us say I did not choose it."
</code>

The player reads the first reply, clicks, then reads the second one. Once the sequence ends, the room shows its choices as usual.

Use ''replies:'' and ''text:'' in an English scenario. The French aliases ''repliques:'' and ''texte:'' are accepted too.

===== Character registry =====

Instead of repeating the name and portrait on every reply, declare your characters once for the whole scenario.

<code yaml>
characters:
  mara:
    name: Mara
    portrait: /scenarios/images/my-game/mara.png
  guard:
    name: The guard
    portrait: /scenarios/images/my-game/guard.png
    portrait-position: right

rooms:
  - id: checkpoint
    text:
      type: sequence
      replies:
        - character: mara
          text: "Let us through."
        - character: guard
          text: "Nobody passes tonight."
</code>

A reply that only sets ''character:'' inherits the stored name, portrait and presentation. Any property can be overridden on the reply itself, and then takes precedence over the registry.

<code yaml>
        - character: guard
          text: "Fine... get inside, quickly."
          portrait: /scenarios/images/my-game/guard-smiling.png
</code>

===== Inheritance between replies =====

A reply that redefines nothing **keeps** the character, portrait and background of the previous one. This is what lets you write a long speech without repeating the speaker.

<code yaml>
      replies:
        - character: mara
          text: "I knew this town before the fire."
        - text: "People came here for the spice market."
        - text: "Nothing of it is left."
</code>

To remove an element explicitly, use ''null''.

<code yaml>
        - text: "The voice comes from nowhere."
          portrait: null
</code>

===== Default presentation =====

''dialogue-default:'' sets the presentation of every sequence in the scenario. Each sequence, then each reply, may depart from it.

<code yaml>
dialogue-default:
  speaker-position: top-left
  portrait-position: left
  portrait-size: 30
</code>

===== Portraits =====

  * ''portrait:'' image displayed next to the text.
  * ''portrait-position:'' ''left'' or ''right''.
  * ''portrait-size:'' percentage of the height of the narrative area.
  * ''portrait-offset-x:'' and ''portrait-offset-y:'' move the portrait.
  * ''portrait-overlap:'' lets the portrait overlap the dialogue frame.

<code yaml>
        - character: mara
          text: "Come closer, I do not bite."
          portrait-size: 43
          portrait-offset-y: 18
          portrait-overlap: 24
</code>

===== Speaker name =====

''speaker:'' displays a name without using the registry.

<code yaml>
        - speaker: Mara
          text: "You are late."
</code>

To give it its own typography, write ''speaker:'' as a block:

<code yaml>
        - speaker:
            name: Mara
            color: "#d8c9a3"
            font: Georgia
          text: "You are late."
</code>

Two keys complete the presentation, on the reply or in ''dialogue-default:'':

  * ''speaker-position:'' ''top-left'', ''top-right'', ''bottom-left'', ''bottom-right''.
  * ''speaker-frame:'' a frame for the name label itself.

With no colour set by the author, the engine picks black or white automatically, based on the background actually displayed, so the name stays readable. A colour written by the author is always kept.

===== Backgrounds =====

''background-image:'' places an image behind the scene. It can be set on a reply, on the sequence, or directly on the room, even without any dialogue.

<code yaml>
rooms:
  - id: laboratory
    background-image: /scenarios/images/my-game/lab.png
    background-mode: cover
    text: "The tanks hum in the half-light."
</code>

The background **stays active in the following rooms** until it is replaced or removed with ''background-image: null''.

''background-mode:'' selects the framing:

^ Value ^ Effect ^
| ''contain'' | the whole image is visible, keeping its proportions |
| ''cover'' | the image fills the area, cropping the edges if needed |
| ''stretch'' | the image is distorted to fit the area exactly |
| ''center'' | the image keeps its size, centred in the area |
| ''repeat'' | the pattern is tiled |

Without ''background-mode:'', the whole image is shown while keeping its proportions. An animated image behaves like a still one.

===== Frames =====

A frame surrounds the dialogue box. There are two ways to get one.

**From an image**, sliced into nine zones so it stretches without distorting the corners:

<code yaml>
      frame: /scenarios/images/my-game/frame.png
      slice: 24
</code>

**Without any file**, by describing the stroke:

<code yaml>
      frame:
        thickness: 2
        color: "#d8c9a3"
        background: "#1b1a17"
        corners: rounded
        radius: 12
        style: solid
</code>

  * ''corners:'' ''square'' or ''rounded'' (with ''radius:'').
  * ''style:'' ''solid'', ''dashed'', ''dotted'' or ''double''.

===== Text animation =====

By default a reply appears **immediately**. Animation is a choice, not a requirement.

<code yaml>
        - character: mara
          text: "Each letter arrives in turn."
          animation:
            type: character
            speed: 20
</code>

''type:'' is ''character'' (letter by letter) or ''fragment'' (by groups of words). ''speed:'' is the delay in milliseconds.

A first click completes the running animation, the next one moves to the following reply. Links, interactive words, buttons and drag and drop **never** advance the sequence by accident: the player can use them freely.

===== Transitions =====

The background, the portrait and the dialogue box each have their own transition.

<code yaml>
        - character: guard
          text: "Who goes there?"
          transition:
            portrait:
              type: slide
              duration: 300
              direction: right
            dialogue:
              type: fade
              duration: 220
</code>

A single value applies to all of them:

<code yaml>
          transition: fade
</code>

''type:'' is ''slide'' (the element glides in) or ''fade'' (a soft appearance, the default behaviour). ''duration:'' is in milliseconds, and ''direction:'' only makes sense for a slide.

===== Hiding the controls =====

''hide-controls: true'' hides the buttons during a sequence, for a scene that must play without interruption. They come back at the end.

<code yaml>
    text:
      type: sequence
      hide-controls: true
      replies:
        - text: "The door closes behind you."
</code>

===== Mixing text and sequences =====

A ''text:'' field accepts a list: plain texts and sequences follow one another in the order written.

<code yaml>
    text:
      - "You push the office door open."
      - type: sequence
        replies:
          - character: mara
            text: "I was expecting you."
      - "She closes the file lying in front of her."
</code>

Text placed after a sequence only appears once that sequence is over. This also works inside an event, an action or a HUD box.

===== Reusing the text of another room =====

''%%[[ROOM:n]]%%'' inserts the narrative content of room number //n//. Useful for a recurring reply written only once.

<code yaml>
        - character: guard
          text: "Always the same answer.[[ROOM:12]]"
</code>

The French form is ''%%[[SALLE:n]]%%''. Circular references are detected and stopped.

===== On other platforms =====

Sequences are displayed in every web and desktop interface: classic, cards, deck, phone, fullscreen, and inside a HUD box.

Discord, the Terminal and the PDF export have no dialogue box: they produce a linear ''Speaker: text'' reading, in the order of the replies. The scenario stays playable everywhere.

===== See also =====

  * [[en:yaml:texte|Text and formatting]]
  * [[en:yaml:medias|Images, sounds and videos]]
  * [[en:yaml:hud|HUD boxes]]
  * [[en:ui:presentation|Interface modes]]