DEdit – Database Editor

Documentation version 1.0 , 2009-12-19

Description Tutorial 3: Advanced scripting

This tutorial will explain some of the more advanced scripting concepts. It is assumed that you have performed tutorial 2 first. This tutorial does not give examples for all the described commands. Those can be found in the scripting command examples section of this help documentation.

 

Variables

TavernMaker allows a very simple style of programming. Besides the most direct commands described in the earlier tutorials, it is possible to achieve simple calculations and branching to generate really flexible descriptions without losing coherence and logic within them.
A basic part of any programming language are variables. TavernMaker recognizes only two types of variables, numeric integer values and string values.

Variables can either be declared locally or globally.

Local variables are only defined and used within one dataset and cannot be accessed from outside the dataset. However, once defined, they can be used in both parts (Text & PPL or Long & Short) of a dataset. As variables can only be used after being defined, it is important to note that the two parts are evaluated in the following order:
            TextàPPL (in descriptions)             and:                 LongàShort (in PPItems).
Thus, one can define a variable in the Text part of a description and use it in the PPL part, but one cannot use a variable in the Text part which is defined in the PPL part.

Local variables are defined by the command $NewVar{varName, varType} where varName is the variable name, and varType is either string or integer.

All variable values are set using the command $SetVar{ varName, varValue} where varName is the variable name, and varValue is the value of appropriate type (string or integer).

The value of a variable is returned by the command $Var{varName}.

è

Note, that myOtherNumber is not used in Text because it is defined afterwards in PPL

è

Note, that myString is not used in Long because it is defined afterwards in Short

There is only one command other than $SetVar{} to alter the value of a number variable:

·       $+{varName, addValue} adds the value addValue to the number variable varName.
(Negative values are allowed. Simply add negative values to subtract a value.)

Several commands derive a new value from the value of a variable. One can use them in combination with $SetVar{} to change variables:

·       $Average{}, $Max{}, $Min{},  $Sum{}, $*{} work on number variables

·       $Length{}, $SwitchCase{} work on string variables

·       $CaseOf{} allows branching dependent on variable values

Logical operators compare variable values and return a Boolean (true/false) answer:

·       $>{}, $>={}, $<{}, $<={}, $=={}, $!={} compare variables with values

·       $And{}, $Or{}, $Not{}  can built more complex Boolean expressions

·       $If{}, $Break{}, $Exclude{} react on Boolean answers

Finally, the $ForEach{} command allows loops and uses variables for counting.

Displaying variable properties

Most often one wants to retrieve a variable’s value, which is done by the $Var{} command. However, sometimes one is rather interested in a variable’s properties, e.g. its name or its array-size (see below). For this, the command $GetVar{}is used. (see tutorial)

Array variables

Simple variables contain just one value of a certain type, but TavernMaker also supports array-variables where each variable contains several values of its type. Each value is stored at a certain indexed position of the variable, and the variable size defines how many positions there are. Note, that the first variable has the index 1.

Array variables are defined by the command $NewVar{varName, varType, varSize} where varSize is the variable size. If an array variable is displayed by $Var{varName} all its values are shown as a comma-separated list. Specific elements of the array can be accessed by using the index ins square brackets. For example, $Var{varName[4]} displays the 4th element (without comma) only. Likewise, $SetVar{varName[4], varValue} sets the 4th element of the array to the given value, whereas $SetVar{varName, varValue} sets all elements.

Element ranges can be defined by a start and a end value in square brackets separated by two dots. For example, $Var{varName[2..4]} displays the elements 2, 3 and 4 in a comma separated list, and $SetVar{varName[2..4], varValue} sets all these elements to the given value.

It is possible to assign the values of arrays of different size to each other. The script language re-iterates the given values to match the sizes to each other. While this can be useful and prevents size-mismatch errors, it can be the source of some unwanted results, if one does not take proper care.

The array size of a variable can be altered, and its elements can be sorted (see tutorial). Some commands act on all elements individually, and others act on the variable array itself. A short list of commands in combination with arrays:

·       $Average{}, $Max{}, $Min{},  $Sum{} handle each element as an independent variable.
Note, that $Average{} returns a truncated integer value,i.e.: 2.9=2 and -2.9=-2!

·       $+{varName, addValue} adds the value to each element.

·       $*{} is not defined for arrays and does not return anything.

·       $Dim{} returns the variable size.

·       $AddItem{} and $DeleteItem{} can change the variable size.

·       $IsElement{}, $ItemPos{}, $SortItem{}, $Swap{} can manipulated arrays.

·       $ForEach{} evaluates a string for each element of an array.

 Global Variables

The only difference between local variables as described above and global variables is that global variables keep their value during tavern generation and can be accessed from all individual datasets. They form a kind of “link” between the datasets and are defined for the RPS. The will automatically be set to a default value at the beginning of a tavern generation, and their values can be accessed/altered during the generation by all scripts, including those from descriptions and pick-pocket items as well as pre- and post-generation scripts and output formation templates. Their main goal is to “count” information during generation (e.g. how often are waiters mentioned? How much magic is used? etc.) and to provide “common” contents (e.g. the tavern name).

Global variables cannot be defined within a script but are stored in a separate “global variable” database which is created by DEdit. However, as this is a rather fundamental part of the general “design” of an RPS, the functionality of creating variable databases can only be accessed with administrator rights and in coordination with the project managers.

All defined global variables of the current RPS can be seen in the Command Syntax (F2)  window in the according section:

Some typical examples for the use of global variables in the AD&D system:

·      Each dataset which describes a magical item, creature or action has $+{magic,1} in its text. A later dataset, e.g. a wizard speaking to his fellow adventurers - can then for example create an output of “I can feel no magic” or “I sense some magic in this room” depending on the value of the global variable.

·      The same global variables can also be accessed in the pre-generation scripts of the output-format templates, summarizing the tavern, e.g. some output like “This tavern sparkles full of magic” or “No arcane aura is detectable” can be created.

·      Some global variables can be set in the pre-generation scripts, e.g. a most common rumour. All datasets can then use the same rumour, e.g. “The man tells you the latest rumour: $Var{rumor}.”

Using global variables it is essential to point out the following things:

·      As the values of the variables are modified during the generation, datasets always “see” the information gathered up to the point they are chosen, rather than the information of the complete tavern. For example: If a generation creates ten table-descriptions and the first 3 do not change the magic variable (so that it is still 0), then the 4th description might report some magic-related output like “no magic found” even though a later description (5-10th) could add some magic to the tavern...

·      In order to have global variables working properly, all databases must adhere to the same rules, i.e. all descriptions telling of magic must increase the magic variable, etc.
Because of this, it is hard to introduce new global variables to an RPS. It means that all datasets need to be checked and maybe modified.

Displaying all global variables

As all global variables are defined in the RPS it is sometimes needed to list all defined variables and their respective values. In particular, output-formating scripts might want to display the “total information”. For this, the command $ShowVars{}is used. In its simplest form (without parameters) it returns a complete tab-separated list giving the variable name, type, scope and value, like in the following example:

$ShowVars{}

   entertainer  integer     Global         0

   keeper       integer     Global         1

   keepername   string      Global         Gregor Wickley

   magic        integer     Global         6

   noise        integer     Global         0

   rumorID      string      Global         id:414

   tavernname   string      Global         The Slender Pilgrim Dining & Spirits

   waiter       integer     Global         0, 3

However, the command allows for a lot of filtering parameters and output formation. A format string defines what will be resulted. One such line is returned for each variable, and the following format tags are currently supported:

Format tags

%c                   creation context of variable

%n                   short name of variable

%N                  long name of variable

%t                   variable type

%v                   value(s) of variable

%v[rg]             value(s) of variable of array range as indicated by rg

\n                     new line

\t                      tab

$ShowVars{<Var:%N\t= %v\t of type %t in %c\n>}

Var:dummyint    = 0                                       of type integer in Global

Var:dummystr    = big                                     of type string in Global

Var:entertainer = 0                                       of type integer in Global

Var:keeper      = 1                                       of type integer in Global

Var:keepername  = Gregor Wickley                          of type string in Global

Var:magic       = 6                                       of type integer in Global

Var:noise       = 0                                       of type integer in Global

Var:rumorID     = id:414                                  of type string in Global

Var:tavernname  = The Slender Pilgrim Dining & Spirits    of type string in Global

Var:waiter      = 0, 3                                    of type integer in Global

A second parameter can be used to restrict all returned variables according to their type (integer or string) and their creation context (i.e. the place where it was created. Most often only global is of importance, but it is possible to use $ShowVars{}within all scripts and one can then restrict to variables defined within its context, e.g. pre-map in pre-map generation scripts etc.)

Resetting global variables

Global variables are automatically reset to their default value (as defined in the variable database) on tavern generation. However, they are not reset on re-population of a generated tavern, as some of the generated information (e.g. tavern name, etc.) should stay constant. Other global variables (e.g. the magic counter) should be reset. This is done in the pre-description script which can be defined in the RPS. One could manually reset all variables there, but a more elegant (and universal) way is the $ResetVars{}command, which does exactly what it says. It resets all variables of the variable database to its defaults value, provided the variable is marked with the “reset” flag within the database. (e.g. tavernname does not have this flag, magic does.)