< index < 16. Name generator < 16.4 Retrieving available set names | ===================================== 16.5 Syllable set configuration ===================================== |

#### 16.5.1 Syllable set structure

The syllable sets need to be written in one or more text files that will be opened and parsed by the generator.
The data uses a standard TCODParser file and data should be inserted according to the general rules of creating a configuration file. For more information, please refer to 7.1 The libtcod config file format.
The structure type that's defined in the generator is "name". This structure type must also be accompanied by a structure name. It will be used for identification purposes in the generator. For instance, if you use a structure name "fantasy female", you will be able to access this syllable set by creating a generator using "fantasy female" syllables. In the initialisation function, this is the "const char * name" argument.
The structure contains different members, all of which must be of TCOD_TYPE_STRING type. The tokens inside the strings, be them phonemes or syllables, form a single string, but are separated with separator characters. Characters used for token separation are all characters that are not Latin upper- or lowercase characters, dashes or apostrophes. A comma, a space or a comma and a space are readable separators. In order to use a character inside a string that would normally be considered a separator, precede it with a slash (eg. "/:", "/.", "/!", etc.). An exception to this rule is the space character, which can be achieved by using an underscore (eg. "the_Great").
The structure members that may thus be defined are:

- phonemesVocals
- phonemesConsonants
- syllablesPre
- syllablesStart
- syllablesMiddle
- syllablesEnd
- syllablesPost

All of those strings are considered optional. However, if you don't define a string, but reference it in the name generation rules, you will see a warning displayed on stderr about missing data.

#### 16.5.2 Illegal strings

Another optional string is

- illegal

This string contains strings that are considered illegal and thus not desired in your names. Should a generated name contain any of the tokens specified in this string, it will be discarded and replaced by a new one. Illegal strings may be as short as single characters or as long as entire names. However, it is best to create a syllable set that generates very few names that sound bad. Otherwise, the illegal list might be very long.
Be aware that the generator will automatically reject certain words, so you don't need to place every undesired possibility in this string.
The generator will prune away the following:

- leading spaces ("_NAME")
- ending spaces ("NAME_")
- double spaces ("NAME1__NAME2")
- triple characters ("Raaagnar")
- two-character adjacent repetitions ("Bobofur")
- three-character (or more) repetitions, adjacent or not ("Bombombur", "Dagbjoerdag", "Gwaerdygwaern")

Remember that all of this is case-insensitive, so you don't need to care about uppercase/lowercase distinction in your illegal strings.

#### 16.5.3 Rules

There's one last string that's contained within the structure:

- rules

It is mandatory, so not defining it will trigger an error. It defines how the generator should join the supplied data in order to generate a name. This string uses a syntax of its own, which is also used when specifying a rule when generating a custom name (see chapter 16.2).
The rules are parsed pretty much the same way as all other strings, so all rules regarding separators and special characters apply as well. However, you can additionally use a set of wildcards and frequency markers. Each wildcard is preceded by the dollar sign ('$'), while frequency markers are preceded by the per cent sign ('%'). Here's the complete wildcard list:

Wildcard | Example | Description
--- | --- | ---
$[INT]P | $P, $25P | Use a random Pre syllable. The optional integer value denotes the per cent chance of adding the syllable.
$[INT]s | $s, $25s | Use a random Start syllable.
$[INT]m | $m, $25m | Use a random Middle syllable.
$[INT]e | $e, $25e | Use a random End syllable.
$[INT]p | $p, $25p | Use a random Post syllable.
$[INT]v | $v, $25v | Use a random vocal.
$[INT]c | $c, $25c | Use a random consonant.
$[INT]? | $?, $25? | Use a random phoneme (vocal or consonant).
%INT | %50, %25 | Frequency marker. Denotes the per cent chance for the rule to be accepted if it's picked. If the rule is not accepted, another roll is made to choose a name generation rule. It's used to reduce the frequency a given rule is chosen with. This marker may only appear at the beginning of a rule.

#### 16.5.4 Example structure

Consider this example structure. It does not contain syllables, but rather full names.

    name "king" {
      syllablesStart = "Alexander, Augustus, Casimir, Henry, John, Louis, Sigismund,
        Stanislao, Stephen, Wenceslaus"
      syllablesMiddle = "I, II, III, IV, V"
      syllablesEnd = "Bathory, Herman, Jogaila, Lambert, of_Bohemia, of_France,
        of_Hungary, of_Masovia, of_Poland, of_Valois, of_Varna, Probus,
        Spindleshanks, Tanglefoot, the_Bearded, the_Black, the_Bold, the_Brave,
        the_Chaste, the_Curly, the_Elbow-high, the_Exile, the_Great,
        the_Jagiellonian, the_Just, the_Old, the_Pious, the_Restorer, the_Saxon,
        the_Strong, the_Wheelwright, the_White, Vasa, Wrymouth"
      rules = "%50$s, $s_$m, $s_$50m_$e"
    }

The above structure only uses three syllable lists and has three different rules. Let's analyse them one by one.
%50$s - this will simply output a random Start syllable, but this rule is not intended to be picked with the same frequency as the others, so the frequency marker at the beginning ("%50") ensures that 50% of the time this syllable will be rejected and a different one will be picked.
$s_$m - this will output a Start syllable and a Middle syllable, separated with a space.
$s_$50m_$e - This will output a Start syllable, followed by a Middle syllable, followed by an End sylable, all separated with spaces. However, the Middle syllable has only 50% chance of appearing at all, so 50% of the time the rule will actually produce a Start syllable followed directly by an End syllable, separated with a space.
As you may have noticed, the third rule may produce a double space if the Middle syllable is not chosen. You do not have to worry about such cases, as the generator will automatically reduce all double spaces to single spaces, and leading/ending spaces will be removed completely.
Output from this example set would contain kings' names based on the names of real monarchs of Poland. Have a look at the sample:

    Alexander IV
    Alexander
    Sigismund
    Stanislao V
    Stanislao
    Henry I of Poland
    Augustus V
    Stanislao I the Pious
    Sigismund IV the Brave
    John the Great
    Henry the Old
    John the Bold
    Stanislao II the Saxon
    Wenceslaus of France
    John Probus
    Louis V
    Wenceslaus Lambert
    Stanislao Spindleshanks
    Henry Herman
    Alexander the Old
    Louis V the Curly
    Wenceslaus II
    Augustus IV
    Alexander V
    Augustus Probus