libtcoddocumentation

10.1. The libtcod config file format

Comments

Your file can contain single line or multi-line comments :

// This is a single line comment
/*
This is a
multi-line comment
*/

Multi-line comments can be nested :
/*
This is a
multi-line comment containing another
/*
    multi-line
    comment
*/
*/

The parser is not sensible to space characters, tabulations or carriage return except inside strings.

Structures

The libtcod config file format is basically a list of structures. A structure has a type, an optional name and contains properties. The type of the structure defines which properties are allowed / mandatory.

item_type "blade" {            // structure's type : 'item_type'. structure's name : 'blade'
cost=300 // an integer property
weight=3.5 // a float property
deal_damage=true // a boolean property
damages="3d6+2" // a dice property
col="#FF0000" // a color property, using #RRGGBB syntax
damaged_color="128,96,96" // another color property, using rrr,ggg,bbb syntax
damage_type="slash" // a string property
description="This is a long"
"description." // a multi-line string property
abstract // a flag (simplified boolean property)
intList= [ 1,2,3 ] // a list of int values
floatList= [ 1.0,2,3.5 ] // a list of float values
stringList= [ "string1","string2","string3" ] // a list of string values
}

A structure can also contain other structures either of the same type, or structures of another type :
item_type "blade" {
item_type "one-handed blades" {
// the item_type "blade" contains another item_type named "one-handed blades"
}
item_type "two-handed blades" {
// the item_type "blade" contains another item_type named "two-handed blades"
}
feature "damage" {
// the item_type "blade" contains another structure, type "feature", name "damage"
}
}

Sometimes, you don't know the list of properties at compile-time. Fortunately, since libtcod 1.5.1, you can add auto-declaring properties in the file, using one of the type keywords :
item_type "blade" {
bool deal_damage=true
char character='D'
int cost=300
float weight=3.5
string damage_type="slash"
color col="#FF0000"
dice damages="3d6+2"
int[] intList= [ 1,2,3 ]
float[] floatList= [ 1.0,2,3.5 ]
string[] stringList= [ "string1","string2","string3" ]
}

The properties declared with this syntax were not previously declared for the structure item_type. But since the type is specified, the parser won't reject them. Instead, it will add the property declaration to the structure dynamically (when it parses the file).
You can also dynamically create new structures and sub-structures with the struct keyword :
item_type "blade" {
struct component {
string name="blade"
float weight=1.0
}
}

With this syntax, you don't need to declare the "component" structure at all in the parser. It will be dynamically registered as the file is parsed.