#summary Structure of the theme.cfg file

== `theme.cfg` ==

The file `theme.cfg` gives the engine the values associated with a certain theme, to complement the graphics. To learn more about the general file structure of themes, see [ThemeFiles].

It is structured with a key followed by an equals sign followed a value. The value depends on the key.

 Example:

<code>sky = 120, 40, 80</code>

There is also keys that replace existing keys under certain conditions, all keys preceding with “`sd-`” are used during sudden death and all keys with “`rq-`” are used when quality is reduced. These keys must be placed after the regular keys and they are all optional.

Following is the list of all current keys and their values, it is important to have the right number of values. Most keys may only be used once.

The values red, green, blue and opacity are in the range of one byte and can be specified in both decimal or hexadecimal form. The range are `0` - `255` or `$00` - `$FF`.

Comments may be added by prefixing a semicolon (“`;`”) to the comment.

=== `sky` ===

The colour of the sky.

<code>Values: red, green, blue</code>

=== `rq-sky` ===

=== `border` ===

The colour of the outline of explosions.

<code>Values: red, green, blue</code>

=== `water-top` ===

The colour of the topmost part of the water (under the `BlueWater.png`) before Sudden Death.

This makes a gradient together with `water-bottom`.

<code>Values: red, green, blue</code>

=== `water-bottom` ===

The colour of the lowest part of the water before Sudden Death.

This makes a gradient together with `water-top`.

<code>Values: red, green, blue</code>

=== `sd-water-bottom` ===

The colour of the lowest part of the water while in Sudden Death.

This makes a gradient together with `sd-water-top`.

If unspecified, it has a default value.

<code>Values: red, green, blue</code>

=== `sd-water-top` ===

The colour of the topmost part of the water (under the `SDWater.png`) while in Sudden Death.

This makes a gradient together with `sd-water-bottom`.

If unspecified, it has a default value.

<code>Values: red, green, blue</code>

=== `water-opacity` ===

The water opacity before Sudden Death. Opacity of the water affects how visible gears in the water are.

<code>Values: opacity</code>

=== `sd-water-opacity` ===

The water opacity while in Sudden Death. By default, it has the same value as `water-opacity`.

=== `music` ===

Name of the track to be played in the theme before Sudden Death, e.g. `Nature.ogg`. You find music tracks in `Data/Music` of the Hedgewars installation directory. The file name is case-sensitive!

<code>Values: name</code>

=== `sd-music` (0.9.21) ===

Name of the track to be played in the theme while in Sudden Death, e.g. `hell.ogg`. By default, no music is played. You find music tracks in `Data/Music` of the Hedgewars installation directory. The file name is case-sensitive!

=== `clouds` ===

The number of clouds to create, before Sudden Death. Uses `Clouds.png`.

<code>Values: number</code>

=== `sd-clouds` ===

Number of clouds while in Sudden Death, uses the file `SDClouds.png`. By default it is the same number as `clouds`.

=== `flakes` ===

Values for the flakes of this theme before Sudden Death. Uses `Flake.png`. If this field is left out, then there are no flakes.

 * `number`: Number of visible flakes

 * `frames`: Number of frames used in `Flake.png`

 * `frame ticks`: Number of ticks a frame is shown, after that the next frame is shown (a tick currently equals 1 millisecond).

Since 0.9.21: A value of 0 indicates that each flake should keep displaying the exact frame that was selected randomly when the flake was created.

*Tip*: If you want to have multiple static flakes in 0.9.20 or earlier, you can set the animation length to a ridiculous high value. Sometimes, a flake will still change the displayed frame, but it will rarely happen.

 * `speed`: Rotation speed of flake

 * `fall speed`: Falling speed of flake

<code>Values: number, frames, frame ticks, speed, fall speed</code>

=== `sd-flakes` ===

Sudden death version of `flakes`, the parameters are the same as in `flakes`. This uses `SDFlake.png`. By default, the flakes are skulls and bones.

=== `object` ===

There may be multiple object keys in the file, each one representing one land object.

 * `filename`: The object’s filename (without the “.png”). Case-sensitive.

 * `max`: The maximum number of this object that may be generated in a map

 * `buriedrec`: A rectangle that must be buried in the terrain (`left, top, width,  height`)

 * `minvisible`: The minimum amount of rectangles that must be visible

 * `visiblerec`: list of the rectangles for being visible (`left, top, width, height`)

<code>Values: filename, max, buriedrec, minvisible, visiblerec</code>

`visiblerec` and the `buriedrec` visualized on an ancient picture:

http://hedgewars.org/images/avematantheme/hw-avematan.rects.png

=== `spray` ===

There may be several spray keys in the file, each one representing one spray object.

The `name` is the case-sensitive name of the PNG file (without the file name suffix) of the graphics file, and `number` is the number of instances of this spray that may be added.

<code>Values: name, number</code>