This page explains how to write a dialog for a character you have added to the game.
Introduction
Dialogs in freedroidRPG reside in dialogs/*.dialog.
A dialog works by letting the user select dialog options (or "nodes"). Each node represents one thing the player can tell the NPC, and can contain replies from the NPC, as well as a piece of Lua script to interact with the game engine.
Any non-recognized string in a .dialog file represents a comment and is ignored.
"recognized" strings are the ones that specify the beginning of the file, the Lua scripts for initialization/startup, or dialog options.
Implementing the dialog
The name of the file should be
NameOfCharacter.dialog or, in case of a subdialog,
subdlg_NameOfCharacter_OptionalPart.dialog and placed in the dialogs/ folder.
Then the file map/ReturnOfTux.droids needs to be set to have
DialogSectionToUse="NameOfCharacter". Do note that the .dialog extension should not be added here.
Top level
FirstTime LuaCode
At the general level, dialogs can take a block
FirstTime LuaCode={ }. This is a block of code that will be executed the first time the player talks to the NPC (and only the first time). It cannot be used in subdialogs.
Its intended use is to properly set which dialog options should be shown the first time, since they are all disable by default. Use
show() for this. Calling anything else than
show() is likely to be a mistake of yours, check out AtStartup below.
AtStartup LuaCode
Arthur, should we not rename it to
EveryTime?? / SH
The block
AtStartup LuaCode={ } is very similar to FirstTime, except that it will be executed every time the player talks to the NPC. This can be useful to check whether a quest has been accomplished, or for options you always want to be turned back on when starting to talk to an NPC even after it has been turned off during a previous dialog.
There are no arbitrary limitations so you can do anything you wish.
Nodes
Intro
A node is where things happen in the dialogs. It generally consists of an option that will be selectable by Tux at some point in the dialog, which is why it is also referred to as an option. But since it's not strictly necessary for Tux to select it, the term option is not 100% correct (e.g. it can also be run automatically via FirstTime).
Available fields
A node follows the following structure:
The first line is
Nr=0
Text=_"Some text for Tux to say
" The
Nr=number is a file unique ID for the node and the value is between 0-99. It's a very bad idea to use the exact string
Nr= anywhere else in the dialog file other than to define a node.
The number order of the nodes in the dialog file is irrelevant, though it's recommended to use sequential number order since makes it makes it easier to find what is where by the next person helping out.
Text_="" This field corresponds to what Tux is going to say when the node is run.
The _ is a gettext marker for "this should be translated". Use it if the text in the field corresponds to something that Tux is actually saying, if this is a placeholder string do not place a _. (See below for placeholder strings.)
The field OptionSample is used to indicate what sound file is associated to the text. It is optional, and can take a special value "NO_SAMPLE_HERE_AND_DONT_WAIT_EITHER". This value means that the text in the Text field will not appear on screen and be skipped completely. In this case the Text field ought to contain a little place holder string like for example "THIS WILL NOT EVER BE VISIBLE" so bugs are easier to spot.
The field NPC can be present anywhere between 1 and +infinite times. It corresponds to one reply given by the NPC : two fields will deliver the two lines one after another (with a delay between them).
NPC=_"You are Tux, aren't you..."
NPC=_"The hero..."
The field LuaCode={ (yes, the curly brace has to be right next to the equal sign) contains a piece of Lua code that will be executed whenever this option is run.
It can jump to another option, end the dialog, show or hide options, run subdialogs, and basically do anything that API allows.
Lua API
The up-to-date list of functions available from
LuaCode? blocks can be found in lua.c. Look for "luaL_register", this is where the Lua functions are listed.