Structure of
theme.cfg
Introduction
The file
theme.cfg
gives the engine the values associated with a certain theme, to complement the graphics. To understand themes in general, start at Themes. To learn more about the general file structure of themes, see ThemeFiles.
Syntax
A
theme.cfg
is a text file which is structured with a list of keys, each separated by line breaks. Each key is followed by an equals sign followed a value. Values can be numbers, strings, or comma-separated lists of these.
Example:
sky = 23, 8, 33
border = 7, 72, 102
music = Art.ogg
There are 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 the graphics quality is reduced.
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. A hexadecimal number must be prepended with a dollar sign. The range is
0
-
255
or
$00
-
$FF
.
Any line can be made into a comment line by having a semicolon (“
;
”) at the beginning. Comments are ignored by Hedgewars.
Literally all lines in the
theme.cfg
file are optional, thus an empty file is valid. Everything has a default value. However, some default values are not really useful (e.g. the water or sky color) and you should therefore explicitly specify enough values.
General configuration keys
hidden
If this key is present in
theme.cfg
(the value does not matter), the theme will be hidden from the theme selection menu. Background themes
must be hidden.
ice
If this key is present (any value), girders become slippery like ice. This also applies to placed girders. This significantly changes the gameplay of your theme, so use wisely. If this key is not present, the terrain is not slippery.
snow
If this key is present (any value), the flakes which are normally purely decorational now behave like snowflakes. When they collide with terrain, they become a part of the landscape. This significantly changes the gameplay of your theme, so use wisely. If this key is not present, the flakes are purely decorational.
rope-step
(1.0.0)
Changes the rope appearance. This changes the distance between rope pieces. This only makes sense if you also use a custom rope image (
RopeNode.png
).
Default: 4
Land object keys
Land objects are images that are placed randomly on the map. Objects become part of the terrain.
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 (must by between 1 and 32)
-
buriedrects_num
: (optional): Number of rectangles that must be buried in the terrain. If this value is ommitted, a value of 1 is assumed
-
buriedrects
: A rectangle that must be buried in the terrain (
left, top, width, height
). If all 4 values are 0, the object will be placed on top of the water
-
minvisible
: The minimum amount of rectangles that must be visible
-
visiblerects
: List of the rectangles for being visible (
left, top, width, height
)
Syntax when you only need 1 buried rectangle:
Values: filename, max, buriedrect, minvisible, visiblerec
Syntax when you want to use multiple buried rectangles:
Values: filename, max, buriedrects_num, buriedrects, minvisible, visiblerects
Here's an example where
visiblerects
and the
buriedrects
are visualized on an ancient picture:
The large rectangle shows a
visiblerects
and the small one shows a
buriedrects
.
overlays
An overlay is an extension of an object. It is an image that is drawn relative to the position of an object that was already placed. Overlays create land just like objects do, but unlike objects, they are drawn on top of the main landmass, instead of behind it. An object can have multiple overlays.
This key allows you to assign 1 or more overlays to a given object. If multiple overlays are used, all overlays will be drawn for each object. This key must be added after the definition of the object you want to add overlays for.
Values: object_filename, overlay_count, x_offset_1, y_offset_1, overlay_filename_1, ...
-
object_filename
: File name of the object to which this overlay applies
-
overlay_count
: Number of overlays for this object
-
x_offset_1
: X position offset of the overlay image relative to the object. Note: The top left corner acts as the image origin
-
y_offset_1
: Y position offset of the overlay
-
overlay_filename_1
: File name of the overlay image to use
- You must repeat the last 3 arguments if
overlay_count
is greater than 1; each overlay needs its own offset and file name.
anchors
An anchor does not create land itself, but instead is a setting that alters the positioning of an object. Each object can have multiple anchors. An anchor is a rectangle that is similar to a
buriedrect
, but it can be outside of the object boundaries. Anchors are useful for objects that spawn on the water.
For an object with anchors to be placed, at least one of the anchors has to “match” in order for the object to be placed. Anchors can “match” in regular land and other land objects. This is different from normal land objects, which can only be buried inside land.
This key needs an object file name, an anchor count and a rectangle for each anchor. This key needs to be defined after the object definition.
Values: object_filename, anchor_count, anchor_rect1, anchor_rect2, ...
-
object_filename
: File name of the object to which this overlay applies
-
anchor_count
: Number of anchor for this object
-
anchor_rect1
, etc.: A rectangle defining the anchor (
left, top, width, height
)
Land decoration keys
Land decorations alter the appearance of the main terrain without adding any terrain. They are purely decorational.
border
The colour of the outline of explosions.
Values: red, green, blue
Default: $50, $50, $50
spray
A spray is an image that is simply drawn on top of the land.
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 rough number of instances of this spray that may be added to the map. The number is the average number of sprays that are normally placed on a random medium-sized island. For larger and smaller landscapes, this number will be automatically scaled up or down. Please note that this number only specifies a rough goal, the actual number of created sprays may vary and you may have to play a bit with this number in order to find a good value.
Values: name, number
Water keys
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
. The default color is blue and matches the default
BlueColor.png
.
Values: red, green, blue
Default: $54, $5C, $9D
water-bottom
The colour of the lowest part of the water before Sudden Death.
This makes a gradient together with
water-top
. The default color is blue and matches the default
BlueColor.png
.
Values: red, green, blue
Default: $34, $3C, $7D
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
.
The default color neatly matches the default
SDWater.png
.
Values: red, green, blue
Default: $96, $70, $A9
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
.
The default color neatly matches the default
SDWater.png
.
Values: red, green, blue
Default: $B9, $72, $C9
water-opacity
The water opacity before Sudden Death. Opacity of the water affects how visible gears in the water are.
0
makes it fully transparent, whereas
255
or
$FF
makes it fully opaque. If the water is fully opaque, the drowning animation is skipped when a hedgehog drowns.
In combination with the default
BlueWater.png
, the recommended value for this is
$80
, which also is the default.
Values: opacity
Default: $80
sd-water-opacity
The water opacity while in Sudden Death. Syntax and default value is equivalent to
water-opacity
.
water-animation
Specified a custom water animation and flowing speed before Sudden Death. By default, the water just moves to the right and has no special animation.
Values: frames, frame ticks, movement speed
-
frames
: Number of frames in
BlueWater.png
. The frames in this image should be stacked horizontally. The height of this image must be divisible by
frames
-
frame ticks
: Duration of a single frame. Must be >0 if
frames
>1, otherwise it is ignored
-
movement speed
: How fast the water moves to the right. Higher values means faster movement. If negative, it moves to the left. Use 0 to stop movement
Default: 1, 0, 1
sd-water-animation
Sudden Death equivalent of
water-animation
, uses
SDWater.png
.
Background keys
sky
The colour of the sky.
Values: red, green, blue
Default: $00, $00, $00
rq-sky
The sky color in reduced quality mode. If present, it is used instead of
sky
on low quality.
Values: red, green, blue
sd-tint
Custom tinting of the background in Sudden Death. The background color will be multiplied by the RGB and opacity values. With
$FF, $FF, $FF, $FF
, there is no change, while with
$00, $00, $00, $FF
, the backgroun turns completely black. The opacity value controls how visible the background image will still be. With an opacity of
$00
, the background image is not visible, only the
sd-tint
color can be seen.
Values: red, green, blue, opacity
Default: $80, $80, $80, $FF
clouds
The number of clouds to create, before Sudden Death. Uses
Clouds.png
.
Values: number
Default: 9
sd-clouds
Number of clouds while in Sudden Death, uses the file
SDClouds.png
. By default it is the same number as
clouds
or
9
if
clouds
was not specified as well.
Values: number
Default: 9
flatten-clouds
Normally, the clouds vary in size and are drawn on different layers. But if this key is present (any value) in
theme.cfg
, all clouds have the same size and are on the same layer (background).
flakes
Values for the flakes of this theme before Sudden Death. Uses
Flake.png
.
-
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). A value of 0 indicates that each flake should keep displaying the exact frame that was selected randomly when the flake was created.
-
rotation speed
: How fast the flakes rotate.
0
= no rotation, and all flakes spawn unrotated. With any other value, flakes also spawn with a random rotation
-
vertical speed
: Vertical speed of the flakes. A positive value makes the flakes fall, while a negative value makes them rise
Values: number, frames, frame ticks, rotation speed, vertical speed
No flakes are used by default.
sd-flakes
Sudden Death version of
flakes
, the parameters are the same as in
flakes
. This uses
SDFlake.png
.
Values: number, frames, frame ticks, rotation speed, vertical speed
If
sd-flakes
is unspecified, skulls and bones are used as images and the following default values are used:
Default: X, 4, 0, 15, 250
(The “X” means the default number of Sudden Death flakes is variable. It depends on the window size and the terrain width.)
flatten-flakes
Normally, the flakes vary in size and are drawn on different layers, some of them even in front of the terrain. But if this key is present (any value) in
theme.cfg
, all flakes have the same size and are on the same layer: In front of the sky and horizont and behind the terrain.
Music keys
music
Name of the music file 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!
If you choose a custom music (i.e. a music which does not come with Hedgewars by default), you should also set
fallback-music
.
Values: filename
No music is played by default.
Example:
music = Nature.ogg
sd-music
Name of the music file to be played in the theme while in Sudden Death, e.g.
hell.ogg
. If
music
was not specified, the Sudden Death has no default music as well. You find music tracks in
Data/Music
of the Hedgewars installation directory. The file name is case-sensitive!
If you choose a custom music, you should also set
fallback-sd-music
.
Values: filename
Default:
sdmusic.ogg
(only if
music
was specified, no music otherwise)
fallback-music
Fallback music for the
music
setting. This setting should be added whenever you use a custom music which is not part of the official Hedgewars install. Otherwise you don't need to set this.
If the music specified in
music
is missing, Hedgewars attempts to use this fallback music istead.
Only use tracks which come with the official Hedgewars install.
Note that if Hedgewars fails to find a music, it defaults to silence.
Example usage (in combination with
music
):
music = My_Custom_Music.ogg
fallback-music = Nature.ogg
fallback-sd-music
Like
fallback-music
, except it's for
sd-music
. If you have set a custom
sd-music
, you should also set
fallback-sd-music
, otherwise there will be silence if the track in
sd-music
is missing.
In version 1.0.0, this will default to
sdmusic.ogg
instead of silence.