**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 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. By default, the room's choices remain visible during the sequence. To hide the controls until it ends, add ''hide-controls: true'' to the sequence.

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

===== Reply types =====

A reply can specify ''type: dialogue'' (the default), ''narration'', ''thought'', ''system'', ''journal'', ''message'' or ''sent-message''. These types distinguish the presentation of speech, narration, thoughts, notices, journal entries and phone messages. They also work as single blocks outside a sequence.

In ''ui: phone'' with ''screen: conversation'', ''message'' is a received bubble and ''sent-message'' is a sent bubble. Earlier replies remain visible as conversation history.

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

An explicit ''character:'' rebuilds the presentation in this order: scenario defaults > character registry > sequence properties > reply properties. Later values take precedence; local overrides from the previous reply are not automatically carried over. Changing only ''speaker:'' does not remove the portrait: use ''portrait: null'' when needed.

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>

A portrait can also use one cell from a spritesheet: ''portrait: portraits.png:4x2:1:0'' selects column 1, row 0 from a sheet with 4 columns and 2 rows. Coordinates start at **0**, at the top left. Use the image reference directly, without ''%%[[...]]%%''.

''portrait-frame:'' adds a frame around the portrait. It accepts the same image or generated frame forms as ''frame:'' (see below):

<code yaml>
        - character: mara
          text: "Come closer."
          portrait-frame:
            image: /scenarios/images/my-game/frames.png:4x2:1:0
            slice: 24
            corners: rounded
            radius: 12
</code>

The spritesheet suffix also works for dialogue and speaker frame images. The cell is selected first, then its frame is sliced into nine zones.

===== 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 color set by the author, the engine picks black or white automatically, based on the background actually displayed, so the name stays readable. A color 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 is centred, with its width controlled by ''background-size'' |
| ''tile'' | the pattern is tiled |

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

With ''background-mode: center'', ''background-size:'' sets the image width as a percentage of the background area (50 by default), keeping its proportions. For example:

<code yaml>
    background-mode: center
    background-size: 70
</code>

The last background actually displayed by a reply is kept when moving to another room, including another interface mode. A room can change only its mode or size without replacing the image.

===== 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
      frame-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'' (word by word). ''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>

To set a shared duration, use a block:

<code yaml>
          transition:
            type: fade
            duration: 700
</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. Inside an existing reply, an inserted sequence is flattened into text; it does not create a nested clickable sequence.

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