This page explains how to write a dialog, and also how to add a character to the game. If you are interested in translating dialogs, please contact the translation project.
Dialogs in freedroidRPG reside in dialogs/*.dialog (repo version) 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.
All dialogs should be checked using the dialog validator (discussed below).
Implementing the dialog
The name of the file should be
An entry needs to be added to *npcs in src/npc.c (don't use the .dialog extension here), so that the dialog can be assigned to characters within the game.
Finally a new droid/npc has to be created with your dialog. This is done by adding an entry in the file map/ReturnOfTux.droids needs to be set to have
At the general level, dialogs can take a block
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
A node follows the following structure:
A node number 99 is required, as this is the node that the "ESC" key activates. (This is checked by the dialog validator below.)
For standard dialog we use the following lua functions from map/script_helpers.lua:
We also have:
To make writing and reading dialogs easier, as well as for translations, we have adopted some style guidelines. These are not checked by the Dialog Validator, as they are not errors in the sense of causing problems for the user, but rather they are something done to make life easier for your fellow writers/developers.
We follow the Linux style CodingConventions. That is to say we indent a TAB character for each level down. It ends up looking like this:
The core FreedroidRPG group no longer maintains translations, however there is a semi-separate translation project that does. Many people contribute to both projects.
The extent of support in core FreedroidRPG for the translation project is appending gettext characters '_' to the beginning of all strings that we think should be translated. An example:
Most strings should use this, although there are a few exceptions (including strings with only formatting in them).
According to the gettext manual, it is significantly easier to translate entire sentences rather than fragments concatenated together, so please use string.format() when you are putting variables into your text. The function string.format() has been integrated to function
This isn't consistently applied throughout the dialogs yet.
Other whitespace stuff
We follow the Linux-style for calling functions (comma space variable). See:
The player speaks in orange, the npc speaks in white, and a computer prompt is in blue. This is mostly handled by the selection of the tux_says(), npc_says(), and cli_says() functions. However, if the NPC is a robot or computer and needs to emphasize something (in blue), it can be done using the [b][/b] indicators, e.g. [b]emphasized text[/b]. Coloring like this should be done sparingly to not at all.
The dialog topics is used to make easily any sub-dialog. They allow multi-level dialog by divide it between many topics. Each topic have a pool of node, each node have only a topic and it can't be changed. You can only show a node with this topic equals to the current topic. All other node is hidden.
Dialog topic is saved in a stack. Current topic is pushed on the top level by a lua function. The maximum depth of topic is 10.
The root topic is the empty string (""). The root topic is the first level of the topic stack. A dialog begin by the root topic. The root topic is the default value of the field
The lua API is much more extensive than the above, and allows many aspects of characters and NPCs to be modified through the dialogs (in addition to being a full on programming language, see the manual).
There are two lists of custom functions available from LuaCode blocks:
In lua.c, look for "
Dialogs can be checked against errors in running the lua code by using the dialog validator. To run, execute freedroidRPG on the command-line with "
Most errors executing the lua code, will be marked (and with some terminals, highlighted in red).
If you are using subversion do:
and then upload the patch to the Review Board.
Of course it may help to contact us before/while you work on your patch.