ClanLib (embedded) datafile compiler

Used to build ClanLib datafile files from script files.

Synopsis

FooBar -datafile <scriptfile> <datafile>

Description

When creating a game using many resources in the form of graphics, samples, leveldefinitions etc., a structuring of this data becomes important. For this purpose ClanLib includes an embedded datafilecompiler that can store all game resources in a single compressed file, thus hiding the names of the actual filenames from the gameplayer, while saving space.

When all resources are stored in a single datafile (or several) containing all data used in the game, a method must be devised for the game to locate a given resource inside the datafile. This could of course be the name of the original file, but a descriptive string (a resource-id) is more useful, as it separates the issue of file-names/locations from the source code.

In ClanLib all resources (graphics, samples, fonts, palettes, raw-data) are mapped to resource-id's in a resource script file, interpreted inside the game using the CL_ResourceManager class. This resource definition file (scriptfile) is also used by the embedded datafilecompiler when datafiles are generated. Note, the datafilecompiler does not support song-modules.

When a scriptfile has been defined using the syntax explained above, a datafile can be generated by executing your program.

This will map all physical resource files mentioned in the scriptfile into "logical" datafile entries mapped using the resource-id's specified in the scriptfile. Now you have a usable datafile, which can be used by the resource manager given that you specify the name of this datafile inside the scriptfile (explained below).

Script file

The format of the scriptfiles are as follows; A scriptfile consists of sections or resources of the form;

<section_name>
{
	// section content...
}

Sections are allowed to be nested within eachother, so this is legal;

MySection
{
	Graphics
	{
	}

	Sounds
	{
	}
}

Resources can be placed inside sections or globally, and are of the form;

<resource_name> = <resource_location> ( <options> );

Options are of the form;

<option_name>
<option_name> = <option_value>
<option_name> = (<option_value>, <option_value>, ...)

examples of valid resource definitions are;

my_sprite = sprite.tga (
	type=surface,
	x=100, y=100,
	width=64, height=64,
	array=2x4);

my_sound = test.wav (
	type=sample,
	loop,
	stream);

my_font = font.pcx (
	type=font,
	x=177, y=232,
	spacelen=6,
	letters="abcdefghijklmnopqrstuvwxyz",
	tcol=0);

Within scriptfiles, remarks are allowed in the form of '//' or '#' which both remarks the end of the current line. End of line is not considered, so it is legal to split a resource definition up like;

my_test = test.pcx (
	type=surface, 
	width=256, 
	height=256);

Resource types

Currently 8 resource types exist. Each resource type understands different options. Unrecognized options are ignored. All resource types understand the option 'type' which specifies the resource type of the given resource. If no type is specified the type of the resource is determined by examining the type of the resource file (.tga, .pcx -> surface resource, .wav -> sample resource). This is a list of the usable options for each resource type;

The boolean resource is used to read a boolean from a resourcefile

The integer resource is used to read a integer from a resourcefile

The string resource is used to read a string from a resourcefile

See also

All ClanLib API classes can be found here. More documentation can be found at http://clanlib.org.