datafile_compiler(1)

NAME 0.1.

ClanLib datafile compiler - Used to build ClanLib datafile files from script files.

SYNOPSIS

datafile_compiler <scriptfile> <datafile>

DESCRIPTION

This program is part of the ClanLib Game SDK.

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 a program called the 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 Layer2 CL_ResourceManager class. This resource definition file (scriptfile) is also used by the datafilecompiler when datafiles are generated.

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

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 5 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;

boolean resources (type = boolean)

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

integer resources (type = integer)

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

string resources (type = string)

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

AUTHORS

Originally written by Magnus Norddahl <[email protected]> and Martin Starch <[email protected]>. ClanLib is now developed by the ClanLib Development team as an Open Source project.

The ClanLib man pages was created using the Perceps documentation system (another excellent piece of Open Source software, available at http://somewhere.in.the.world.org).

See clanlib (3) to find out how to get a full list of contributors and details on how to submit bug reports, comments etc.