Dialogue

The built in dialogue (speech) system can be used to create conversations between any number of players or 'items' (typically NPCs). It fully supports the localisation system and can be cued from speech playback, synthesis, the player or anything else via scripting. It's also built on top of the window system so dialogue can be easily displayed inside drop-and-go templates.

Basic structure

All dialogue is JSON compatible with PowerSlide. Here's the general structure of those JSON files:

[
  {"speaker":"player"},
  "Hello! My name is &Username;.",
  "All of this text will be said <b>by the player</b>.",
  "It's just an array of text. Because we aren't defining any timing information, it will be cued by the player.",
  "That typically means the player will see something like <i>'press x to continue'</i>.",
  
  {"speaker":"system"},
  "You feel a rush of excitement",
  
  {"speaker":"player"},
  "Ah. That was the system speaker - speaker names can be whatever you want",
  "'system' is reserved as meaning a narrator-style speaker usually present in RPGs.",
  "By convention, spaces are added between speakers, so you can clearly see when a speaker changes."
]

Save a file like that in Resources/Dialogue. For example, Resources/Dialogue/myDialogue.json. To use it, you just then use document.startDialogue("myDialogue","templateToUse"). For example, call that when a player clicked on an NPC.

As it's PowerSlide, you can also define other tracks in there too (such as a style track and potentially in the future a variety of cutscene management tracks - camera position etc).

Localisation

As seen above with 'Username', localisation variables are fully supported. However, for the purposes of translating all your dialogue, there is also another option: As these files are almost entirely the actual text anyway, you can also inline your translations like this:

[
  {"speaker":"player"},
  {"markup":{
    "en":"Hello! My name is &Username;.",
    "fr":"Salut! Je m'appelle &Username;."
  },
  {"markup":{
    "en":"All of this text will be said <b>by the player</b>.",
    "fr":"Tout ce texte sera <b>dit par le joueur</b>."
  }},
  
  {"speaker":"system"},
  {"markup":{
    "en":"You feel a rush of excitement",
    "fr":"Vous sentez une pointe d'excitation"
  }}
]

Further Details

Like other PowerSlide tracks, a dialogue track is just a list of slides. If a slide does not define a speaker then it adopts the speaker applied to the previous slide. If a slide only defines a speaker, then it's completely ignored from the dialogue stream (but does affect the speaker of the following slides).

So, the first example is short for:

[
  {
    "speaker":"player",
    "markup":"Hello! My name is &Username;."
  },
  {
    "speaker":"player",
    "markup":"All of this text will be said <b>by the player</b>."
  },
  {
    "speaker":"player",
    "markup":"It's just an array of text. Because we aren't defining any timing information, it will be cued by the player."
  },
  {
    "speaker":"player",
    "markup":"That typically means the player will see something like <i>'press x to continue'</i>."
  },

  "etc"
]

Available properties

Here's the available properties on dialogue slides.

Name	Description	Optional	Example
speaker or speakers	The people/ items saying the text.	Yes, except for the very first slide.	{"speaker":"joey"}
markup	The text to say, optionally in multiple languages indexed by the language code. This is implied if you just have a line of text.	No, unless speaker/speakers or options is defined.	"Hello", {"markup":"Hello!"}, {"markup":{"en":"English","fr","Français"}}
start	(Same as PowerSlide). The time the dialogue appears at.	Yes	"start":"1.23s"
duration	(Same as PowerSlide). How long the dialogue lasts for. If omitted, the slide is cued by the player.	Yes	"duration":"1.44s"
template	Overrides the visual template to use. Makes it change if needed.	Yes	"template":"subtitles"
Used if the player should pick from one or more options. See more on options below.	Yes	"options":[{"markup":"Yes!","goto":".."},{"markup":"No!","goto":".."}]
wait-for-cue	Rarely needed. True/false indicates if it should wait for a cue. E.g. if "click to continue" should appear or not.	Yes. It's true if no duration is declared, or if options are declared. False otherwise.	"wait-for-cue":"true"

Speakers

Most of the time, speaker information is already available elsewhere. So, PowerSlide does not include a way for storing speaker details (like their name, a chat head etc). Instead, you'll need to provide those details via the PowerSlide.Dialogue.OnGetSpeaker delegate:

// using PowerSlide;

Dialogue.OnGetSpeaker=delegate(SpeakerType type,string id){
    
    // Create the speaker object (instance/ return a custom type if you want):
    Speaker speaker=new Speaker(type,id);
    
    /* 
        Get the information for whatever type/id refers to now!
    
    e.g:
    
    if(type==SpeakerType.Player && id==null){
        
        // Current player! You can use localisation variables 
        // here if you want, or directly set it:
        speaker.fullName="&Username;";
        
    }
    
    */
    // Ok!
    return speaker;
};

Multiple speakers

A single speaker name could represent a group; for example "clan-members" could be all clan members in the scene. However, if you need to list out multiple speakers, then you simply provide an array like so:

[
   {"speakers":["player","joey"]},
   "STOP!!"
]

Advanced speakers

You might want dialogue between two players in a multiplayer game. The above speaker strings are actually short forms of this:

"speaker":{"type":"player","id":"2"} /* Some remote player */

"speaker":{"type":"player"} /* Current player */

Events

Along with all the ordinary window events and PowerSlide events, dialogue also generates these:

Name	Event object type	Purpose
dialoguestart	PowerSlide.SlideEvent	Fires when a particular dialogue slide should now be visible.
dialogueend	PowerSlide.SlideEvent	Fires when a particular dialogue slide is no longer visible.

Mood

Mood can change very rapidly throughout dialogue, and can occasionally be hard to translate.

Speech markup language (SSML)

All dialogue is actually an extended version of SSML. It can contain all HTML as well as speech hints. It may potentially be forwarded to a speech synthesis engine or otherwise checked for mood cues within the speech.

<!-- The SSML describes both how it sounds and how it appears on the UI (it fully supports HTML too) -->
<happy>Hello &Username; - I'm feeling <i>great</i> today!</happy>