Resource script

Resource script files are used with hgeResourceManager helper class to define complex resources. They are just plain text files containing resource definitions.

Common rules

Resource script consists of commands separated by whitespace characters ('\t', '\n', '\r' or ' '). If a semicolon (';') encountered, the rest of the line is treated as user's comment and is not parsed. All the commands and names are case sensitive.

The common command format is:

ResourceType ResourceName : BaseResourceName
{
 Parameter1=Value1
 Parameter2=Value2
 ...
 ParameterN=ValueN
}

Parameters could appear in any order. Most of the parameters have default values and can be omitted. If a parameter has multiple values, all of them must be specified. Multiple values are separated with comma: ','.

Resource names are words started from a letter and separated by whitespace characters. Resources of different types could share the same name. It is not allowed to use script commands or parameters as names. Characters ',', ':', '{', '}' and '=' are also not allowed in names. To define a resource name or file path containing whitespace and/or special characters use quoted strings: "01name:part1 part2". Note that quoted strings can not be placed on several lines.

If BaseResourceName is specified and the resource with this name of the same type already was defined, all it's parameters are copied for the new resource and only specified ones are replaced with new values.

If hgeResourceManager encounters problem reading script, it tries to skip the smallest possible part and continue parsing. All the parsing errors are written to the log file in the most meaningful way possible.

Quick reference

Include
Resource
Texture
Sound
Music
Stream
Target
Sprite
Animation
Font
Particle
Distortion
StringTable

Include

Command "Include" includes another script file into processing. This allows you to split your script into several files and use them in various combinations. Self- and loop-references are automatically detected and denied.

Example:

Include level2.res

Resource

Command "Resource" defines a raw resource. Supported parameters:

filename: Raw resource filename, either absolute or relative to the application folder or resource package root.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Resource level1
{
 filename=levels\level1.dat
 resgroup=1
}

Texture

Command "Texture" defines a texture. Supported parameters:

filename: Texture filename, either absolute or relative to the application folder or resource package root.
mipmap: If "true", a set of mipmap levels will be created and used for the texture.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Texture background
{
 filename=images\bg.jpg
 resgroup=1
}

Sound

Command "Sound" defines a sound effect. Supported parameters:

filename: Sound effect filename, either absolute or relative to the application folder or resource package root.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Sound explosion1
{
 filename=sounds\expl1.ogg
 resgroup=1
}

Music

Command "Music" defines a music. Supported parameters:

filename: Music filename, either absolute or relative to the application folder or resource package root.
amplify: Level of amplification for the music. Default is 50.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Music main_theme
{
 filename=sounds\music1.xm
 amplify=70
 resgroup=1
}

Stream

Command "Stream" defines an audio stream. Supported parameters:

filename: Stream filename, either absolute or relative to the application folder or resource package root.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Stream sountrack1
{
 filename=ost.mp3
 resgroup=1
}

Target

Command "Target" defines a render target. Supported parameters:

size: Render target dimensions, two integers: width and height. Should be a power of two numbers. The default dimensions are 256x256.
zbuffer: A boolean value, specifying whether to use Z-buffer for this render target or not. The default value is false.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Target HUD
{
 size=256,256
 zbuffer=false
 resgroup=1
}

Sprite

Command "Sprite" defines a sprite. Supported parameters:

texture: Name of the texture to use for the sprite. Could be a defined texture resource name or just plain filename.
rect: Texture region to use for the sprite, four float values: top-left corner X-coordinate, top-left corner Y-coordinate, width and height.
hotspot: The sprite anchor point, two floats: X-offset and Y-offset from the sprite's top-left corner. The default value is 0,0.
blendmode: The sprite blending mode, list of one or more of the following constants: COLORMUL, COLORADD, ALPHABLEND, ALPHAADD, ZWRITE, NOZWRITE. See Blending modes for detailed description. The default value is COLORMUL, ALPHABLEND, NOZWRITE.
color: The sprite color, a hexadecimal value. See Hardware color format for details. The default value is FFFFFFFF.
zorder: The sprite Z-order: a float value. The default value is 0.5.
flip: Two boolean values, specifying whether the sprite should be flipped horizontally and vertically. The default value is false, false.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Sprite wizard
{
 texture=characters
 rect=0,0,32,32
 hotspot=16,16
 blendmode=COLORMUL,ALPHABLEND,NOZWRITE
 resgroup=1
}

Sprite orc : wizard
{
 rect=0,64,32,32
 color=FF808000
}

Animation

Command "Animation" defines an animation. It supports all the Sprite parameters plus the following ones:

frames: Overall number of animation frames, an integer value. Default is 1.
fps: The animation playback speed in frames per second, a float value. Default is 12.0.
mode: The animation playback mode, list of one or more of the following constants: FORWARD, REVERSE, PINGPONG, NOPINGPONG, LOOP, NOLOOP. See hgeAnimation::SetMode for detailed description. The default value is FORWARD, LOOP.

Example:

Animation hero.walk
{
 texture=characters
 rect=0,128,32,32
 frames=8
 fps=6.0
 mode=FORWARD,NOLOOP
 hotspot=16,16
 blendmode=COLORMUL,ALPHABLEND,NOZWRITE
 resgroup=1
}

Font

Command "Font" defines a font. Supported parameters:

filename: Font description file name relative to the application folder or resource package root.
mipmap: If "true", a set of mipmap levels will be created and used for font texture.
blendmode: The font blending mode, list of one or more of the following constants: COLORMUL, COLORADD, ALPHABLEND, ALPHAADD, ZWRITE, NOZWRITE. See Blending modes for detailed description. The default value is COLORMUL, ALPHABLEND, NOZWRITE.
color: The font color, a hexadecimal value. See Hardware color format for details. The default value is FFFFFFFF.
zorder: The font Z-order: a float value. The default value is 0.5.
scale: The font scaling, a float value. Default is 1.0.
proportion: The font proportion, a float value. Default is 1.0.
rotation: The letters rotation in radians, a float value. Default is 0.0.
tracking: The font tracking in pixels, a float value. Could be negative. Default is 0.0.
spacing: Line spacing multiplier, a float value. Default is 1.0.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Font tengwar
{
 filename=fonts\tengwar.fnt
 tracking=1.0
 resgroup=1
}

Particle

Command "Particle" defines a particle system. Supported parameters:

filename: Particle system preset filename relative to the application folder or resource package root.
sprite: The sprite name to use for the particle system.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Particle explosion1
{
 filename=data\explosion1.psi
 sprite=explosion1
 resgroup=1
}

Distortion

Command "Distortion" defines a distortion mesh. Supported parameters:

texture: Name of the texture to use for the mesh. Could be a defined texture resource name or just plain filename.
rect: Texture region to use for the mesh, four float values: top-left corner X-coordinate, top-left corner Y-coordinate, width and height.
mesh: The mesh resolution, two integer values: columns and rows. The default value is 2,2.
blendmode: The mesh blending mode, list of one or more of the following constants: COLORMUL, COLORADD, ALPHABLEND, ALPHAADD, ZWRITE, NOZWRITE. See Blending modes for detailed description. The default value is COLORMUL, ALPHABLEND, NOZWRITE.
color: The mesh color, a hexadecimal value. See Hardware color format for details. The default value is FFFFFFFF.
zorder: The mesh Z-order: a float value. The default value is 0.5.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

Distortion waves
{
 texture=title
 rect=0,0,400,200
 mesh=16,8
 color=FF2060F0
 resgroup=1
}

StringTable

Command "StringTable" defines a string table. Supported parameters:

filename: The string table filename, either absolute or relative to the application folder or resource package root.
resgroup: Integer resource group identificator. Default is 0, meaning no specific group.

Example:

StringTable dialogs
{
 filename=strings\dialogs.txt
 resgroup=1
}