Dialog implementation

A proposal/draft specification for the Dialog System's implementation.

Components
The Dialog System should be separated logically into two main components: a dialog script interpreter and a graphical dialog box component.

Dialog Box GUI Component
The GUI component should handle all input and manage all resources (fonts, images, etc.) used during the course of the dialog. In the mock-up below, three main parts have been specified for the component: a caption, an image area, and the main text/choice area. Other parts might include: quick-numbers for choice options (Neverwinter Nights uses these), a graphical indication of whether there is more dialog (such as a small arrow) or whether the end of the dialog text has been reached (such as a small square).

Example Dialog Box GUI Mock-Up for reference:



Dialog Script Interpreter
Dialog scripts need to allow branching based on direct player choices as well as conditional branching based on other variable states (the world, current quest status, difficulty level, etc.). The following specification for the dialog script format is intended to be trivial to implement/parse and powerful enough to fulfill the story's requirements. Consider the syntax below as a placeholder, though improvements/suggestions are welcome; gaps in functionality are the most important to identify. In the syntax below, for instance, the variable lookup table must either be local to the individual script or global for all scripts (ditto for being transient or persistent) because there is no current method for differentiating between global and local variables.


 * Dialog scripts are processed line by line sequentially except where branching occurs.
 * Branches use sections/labels as targets. A section identifier would be enclosed in square brackets: [1] or [EXIT] for instance.
 * variables are referenced like makefile variables: $(variable name)
 * $ denotes a variable assignment. variables are dynamically typed at assignment but require the type (int/float/bool/string) to be specified: $(variable name) type value
 * # denotes a line comment
 * " denotes a line of dialog text that is passed to the GUI component after interpolating any variables found within it: "Greetings $(PLAYER_NAME)!
 * ' denotes a line of dialog text that is passed to the GUI component with scanning for variables
 * ^ causes the dialog to be flushed, that is for the current dialog to be displayed and the script execution to halt until an input event advances the dialog. otherwise the dialog flushes whenever it becomes full (the GUI component handles any line wrapping) or whenever a choice section is encountered.
 * @ jumps to the script section specified, which may be specified by a variable: @ $(EXIT_SECTION_VAR), @PATH_OF_EVIL
 * ! evaluates the specified variable as a boolean and skips the next line's command if it is false (undeclared, zero, empty length): !$(STARTED_DIALOG)
 * ?? begins and ends a choice section (the choice section title follows on the same line): ??Choice section title text
 * ? denotes the text to display for this choice: ? Choice text with a space at the start!
 * > denotes the section to jump to if the preceding choice option is selected: >SECTION_8
 * E specifies a return value and exits the script: E8008135 returns 8008135

The modifying the GUI component or interacting with other delegated tasks (sounds, for instance) can be accomplished either by adding commands to the base dialog script syntax or by using the values of special variables. The advantage of using special variables is that only the controller function (dialog box GUI component, for instance) needs to be updated to check for the variables, the script interpreter remains unchanged (and scripts will still parse correctly, even if a sub-system isn't implemented). Examples of special variables and their use are given below.
 * DBOX_TITLE, evaluated as a string and used to set the title/caption of the dialog box
 * DBOX_IMG, evaluated as a string and used to specify the image to load and display in the dialog box
 * DBOX_SND, evaluated as a string and used to specify the sound to play when the dialog box is next redrawn. the value is auto automatically cleared and the sound stopped when the dialog box is closed.
 * DBOX_SNDLOOPS, evaluated as an integer and determines how many additional times to play the sound specified by DBOX_SND. a value of 1 plays the sound effect 2 times total. -1 will attempt to loop forever. automatically reset to 0 when closed.