ClanSoft logo
ClanSoft logo

    ClanLib datafile compiler

Used to build ClanLib datafile files from script files.

Synopsis

datafile_compiler <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 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. 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 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 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;

boolean resources (type = boolean )

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

font resources (type = font )
    tga-Interpret this file as a targa image.
    pcx-Interpret this file as a pcx image.
    pos=(<xpos>, <ypos>)-Font position in image source.
    spacelen=<width>-Pixel width of the space character.
    tcol=(<col1>, <col2>, ...)-Transparent colors in the font.
    letters=<ABCDEF...>-The list of letters in the font.

    The font resource type is used by the CL_Font class to load a font from a datafile.
    The datafile compiler creates the font by cut each letter out of the specified image file. It uses the last three colors in the palette to do that. Color index 255 is used to find the height, 254 is used to seperate the letters (find the width), and 253 is used to break the line.
    For an example, have a look on the Pacman demo application.

integer resources (type = integer )
    base=<x>-specifies the base on which the integer is based

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

palette resources (type = palette )
    tga-Interpret this file as a targa image. (does this work?)
    pcx-Interpret this file as a pcx image.

    The palette resource is used by the CL_Palette class to load a palette from a datafile.

raw resources (type = raw )

    Includes a file into the datafile without altering the data in any way.

sample resources (type = sample )
    wav-Interpret this file as a PCM Wave file.
    stream-This sample should be streamed.
    loop-This sample should be looped (only used for streamed samples).

    A sound sample resource in ClanLib. Used by the static and streamed sound providers.

string resources (type = string )

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

surface resources (type = surface )
    tga-Interpret this file as a targa image.
    pcx-Interpret this file as a pcx image.
    x=<val>-Specify the starting x coordinate in the image file.
    y=<val>-Specify the starting y coordinate in the image file.
    width=<val>-Specify the number of horizontal pixels to store from the image.
    height=<val>-Specify the number of vertical pixels to store from the image.
    array=<xval>x<yval>-Creates a surface containing <xval> * <yval> sprites. This option requires the existance of x, y, width, height option values in the resource definition; otherwise the option is ignored. The sprites are read from left to right, top to bottom, and are each saved with width, height equal to the width, height options specified.
    tcol=<val>-Specifies a given color as transparency color for this surface. This option is only meaningful for palettisized input image formats (PCX).
    tcol=(<val>, <val2>, ...)-Same as above, but specifies several transpareny colors.

See also

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



This page was built using the Perceps documentation system.