Writing Dialogs

Introduction

A 'dialog' is an game event stored in the dialog.yaml file that runs a defined conversation that can print text with handwriting effect, ask for confirmation and input or ask for a choice and run specific stuff if a statement is True or False. As well as displaying text, a dialog can modify some of the player attributes, add new ones, remove other ones. A dialog can also add custom attributes. For a dialog to be displayed, it has to be in a point definition. A dialog can also be set so it is only activated if the player has or has not a custom attributes. The custom attributes are in the player save file. Note that you can use text replacements in the dialog data type.

An example of a map point that displays a dialog:

point11:
  x: 12
  y: -7
  map zone: "Kathallion Palace"
  dialog: "Palace Enter"
  blocked:
  - North
  - South

And the "Palace Enter" dialog definition:

Palace Enter:
  conversation:
    - label 1:
      - print(As you enter the beautiful palace, there is already someone waiting for you in the enter hall.)
      - print(He walks toward you and start to talk:“Hey! I hope it wasn't too difficult to get here, because of all the monsters in the Kathallion Plains.”)
      - print(He propose you to give you some gold. Do you want to accept it?)
      - ask-confirmation(confirmation_variable)
      - if(confirmation_variable, True):
        - create-variable(gold_addon, 19)
        - print(He gives you 19 royal gold coins before opening a great door, letting you enter the palace and look at all the marble statues and other beautiful sculptures.)
      - if(confirmation_variable, False):
        - create-variable(gold_addon, 0)
        - print(He opens a great door, letting you enter the palace and look at all the marble statues and other beautiful sculptures.)
  use actions: true
  actions:
    gold modification:
      augmentation: $gold_addon
    add to diary:
      known npcs:
      - Kathallion Palace Butler Guy

When the player will enter this map point, the dialog will shown like that:

And the player will have the Kathallion Palace Butler Guy npc added to its diary and he will be given 19 gold.

Full Explanation

Here is the full syntax of a dialog definition:

<dialog id>:
  to display: # not required
    player attributes: <custom attributes(list)>
    visited locations: <map points digit(list)>
    known enemies: <enemies id(list)>
    known npcs: <npcs id(list)>
    has items: <items id(list)>
    has missions offered: <missions id(list)>
    has missions active: <missions id(list)>
    random: <percentage(float)>
  conversation:
  - label 1: # required naming for making it work properly
    [...]
  - label 2: # required naming for making it work properly
    [...]
  scene: <image name in the imgs folder(str)> # not required
  use actions: <true | false(bool)>
  actions: # not required
    add attributes: <custom attributes(list)>
    give item: <items id(list)>
    health modification:
      diminution: <health removal(int)>
      augmentation: <health addition(int)>
      max health:
        diminution: <max health removal(int)>
        augmentation: <max health addition(int)>
    gold modification:
      augmentation: <gold addition(float)>
      diminution: <gold removal(float)>
    remove item: <items id(list)>
    add to diary:
      known zones: <map zones id(list)>
      known enemies: <enemies id(list)>
      known npcs: <npcs id(list)>
    remove to diary:
      known zones: <map zones id(list)>
      known enemies: <enemies id(list)>
      known npcs: <npcs id(list)>
    use drink: <drinks id(list)>
    run scripts:
      - script 0:
        arguments: <arguments(list)>
        script name: <script in scripts dir(str)>
      - script 1:
      [...]

Full explanation of all attributes

• to display:
  • player attributes // Here you will list all required custom attributes for this dialog to display.
  • visited locations // Here you will list all required map point id (the number) for the player to have visited for the dialog to display. (it will look in the save visited points list)
  • known enemies // Here you will list all required enemies that the player have to already encountered for the dialog to display. (it will look in the save enemies list list)
  • known npcs // Here you will list all required npcs that the player have already encountered for the dialog to display. (it will look in the save met npcs names list)
  • has items // Here you will list all required items that the player have in its inventory for the dialog to display.
  • has active missions // Here you will list all required active missions that the player have in its inventory for the dialog to display.
  • has offered missions // Here you will list all required offered missions that the player have in its inventory for the dialog to display.
  • random // The percentage of chance the player has to get this dialog displayed.
• conversation // Here you will list all labels to be run with the functions in it.
• scene // Here you will write the name of the scene ASCII thumbnail. Ex: imgs/Example Scene.txt. You can use the yaml data color code
• use actions true | false // Here you will put false or true whether you want the dialog to use actions or not.
• actions:
  • add attributes // Here you will list all the custom attributes that'll be added the player if this dialog appears to him.
  • give item // Here you will list all items that will be given to the player. Note that if the player doesn't have enough inventory slots, the items will still be given.
  • health modification:
    • diminution // Here you will put an integer that will be removed from the player current health
    • augmentation // Here you will put an integer that will be added to the player current health. Set it to 999 to set the player health to its maximum.
    • max health:
      • diminution // Here you will put an integer that will be removed from the player max health
      • augmentation // Here you will put an integer that will be added to the player max health
  • gold modification:
    • diminution // Here you will put an integer that will be removed from the player current gold
    • augmentation // Here you will put an integer that will be added to the player current gold
  • remove item // Here you will list all items that should be removed from the player inventory if the player has one or more in his inventory. Note that if the player doesn't own some of these items, it'll skip them.
  • add to diary:
    • known zones // Here you will list all zones to be added to the player diary.
    • known enemies // Here you will list all enemies to be added to the player diary.
    • known npcs // Here you will list all npcs to be added to the player diary.
  • remove to diary:
    • known zones // Here you will list all zones to be removed from the player diary. Note that if the player doesn't already have some of these in its knowledge, it'll skip them.
    • known enemies // Here you will list all enemies to be removed from the player diary. Note that if the player doesn't already have some of these in its knowledge, it'll skip them.
    • known npcs // Here you will list all npcs to be removed from the player diary. Note that if the player doesn't already have some of these in its knowledge, it'll skip them.
  • use drink // Here you will list all drinks the player will consume. It does the same action that when you buy a drink at an hostel or an npc.
  • run scripts // here you'll enter the list of dictionaries that'll be used to run custom scripts, which are located in the script/ directory.
    • script <digit> // digit can go from 1 to 120.
      • arguments // here you'll enter the list of arguments, which are game re-usable variables. Don't put this key if your script doesn't require any arguments.
      • script name // the name of the script file, which's in the script/ directory. Find a full guide on custom scripting here.

Full explanation of conversations

Dialog conversations are split in different labels, named label x, where x can go from 1 to 120. In every labels, you will find what's called 'conversations functions', which are actions that are ran when displaying the dialog. Note that only the label 1 will be automatically ran but other ones will need to be triggered by 'conversations functions' to be ran. There are currently 8 possible functions by now. Here are they:

print(<text>) # print text in a speech text effect

ask-input(<input_variable>) # ask the player for input and stores the player's input to the specified variable

goto(<label>) # change of label

wait(<seconds>) # wait for x second

ask-confirmation(<input_variable>) # ask to the player a yes/no input and stores it to the specified variable

if(<variable>, <equality>) # run specified functions if the variable x is equal to specified y

choice():
  - create-choice(<choice_name>, <action>) # create a selecting menu and defines functions to run if the player choose certain choices

create-variable(<variable_name>, <variable_value>) # creates a variables with a value and stores it in the dialog 'RAM' variables

accept() # if this dialog was triggered by a mission 'to offer' statement, accept the mission and stops the dialog here. Does not run any related triggers.

decline() # if this dialog was triggered by a mission 'to offer' statement, decline the mission and stops the dialog here. Does not run any related triggers.

defer() # same as decline, but the mission won't be declared as 'offered', so it can be offered again. Does not run any related triggers.

die() # kills the player. Does not run any related triggers.

display-scene(<image name in imgs directory>) # displays an image from the `imgs/` directory, as a dialog scene

Created variables during the conversation process can be used in the dialog actions, by entering $<variable> as a value. It's highly recommended to check the vanilla dialogs data to really understand better.