#summary File structure of themes

= File structure of themes =

== Introduction ==

This page explains the meaning of the several files which are used by themes. Please note that not all files are neccessary to create a theme, many files have default fallback versions with identical names in `Data/Graphics` or `Data/Graphics/SuddenDeath` of your Hedgewars installation.

To create a theme, you need a bunch of graphics and a `theme.cfg` (explained under [ThemeCfg]). All graphics mentioned here have to in the PNG format.

Please note that this is not a tutorial, it is a reference page designed to look up how to do stuff. Start at [Themes].

Careful! All file names are case-sensitive on case-sensitive platforms! Please ensure you used the correct casing if you want to share your theme online.

<wiki:toc max_depth="3" />

== Mandatory files ==

Only a very few files are mandatory, almost everything has a default image. Of course, using defaults only does not make a good theme, so you should add enough images for your theme until you got a decent theme.

All themes need at least `theme.cfg`.

`icon.png` or `icon@2x.png` are required for the theme to show up in the list of selectable themes in Hedgewars.

Full themes, that is, themes which can be used on random maps or hand-drawn maps, also require `LandTex.png` and `Border.png`.

But those files are not required if you only want to use a theme in combination with an [PresetMaps image map] or in fort mode, but not for random maps or hand-drawn maps.

== Basic files ==

=== `icon.png` and `icon@2x.png` ===

A preview icon for the theme. It is used in the frontend. This is not mandatory for the theme to work. But if the icon is missing, the theme will be automatically hidden from the theme selection dialog. The icon comes in two sizes.

==== `icon.png` ====

Small version of the icon. It must be of size 33×32 pixels.

==== `icon@2x.png` ====

Large version of the icon. It must be of size 65×64 pixels.

=== `theme.cfg` ===

A text file which configures various aspects of the theme. The structure of this file is explained in [ThemeCfg].

=== `credits.txt` ===

Optional text file containing the name of the author of the theme. Don't use line-breaks. This file is currently unused by Hedgewars and only used for documentation purposes.

== Terrain ==

=== `LandTex.png` ===

This is the basic land texture for the main terrain. It is an image tile which will be simple repeated horizontally and vertically all over the landscape. Theoretically, there are no size constraints.

Ideally, you would want to make sure this texture tiles well and is seamless in both axes.

This file is mandatory for full themes but not for themes only to be used as background for maps.

=== `LandBackTex.png` ===

This is similar to `LandTex.png`, but this image is for the terrain background. This texture becomes visible when a piece of landscape has been destroyed. By default, no terrain background is used.

=== `Border.png` ===

Border of the landscape. 128×32 pixels in size. This is used to “paint over” the borders of the landscape. This image consists of two parts: the upper half is used for the floor, the lower half for the ceiling.

This file is mandatory for full themes but not for themes only to be used as background for maps.

=== `Girder.png` ===

An optional image for the landscape girders, large horizontal constructions which are added to the landscape when it is enabled in the game scheme.

This image will be repeated horizontally, so for a better theme quality, make sure this image has no seams horizontally.

If unspecified, `Data/Graphics/Girder.png` is used.

=== `Chunk.png` ===

A sprite sheet of 4 images for “chunks”. These images appear and “fall off” when some piece of landscape has been blown away. The image has a size of 64×64 and the images are in a raster of 2×2 images.

This image is optional. If missing, no chunks are used.

=== `Dust.png` ===

A dust particle animation which appear when something hits the ground hard. This is a sprite sheet with a size of 22×176 pixels, each image has a size of 22×22 pixels. The topmost image shows the start of the animation, the lowest image the end of the animation.

By default this is `Data/Graphics/Dust.png`.

=== Objects ===

Objects are single images of any size, they will be “attached” to the landscape and so become part of the landscape themselves. The name has to follow the following rules:

 * It must have the suffix “`.png`”

 * It must not end with “`_mask.png`”

 * It must not be equal with any other file name mentioned on this page

Objects have to be configured in `theme.cfg`.

=== Object masks ===

Object masks are images which are applied to objects. They determine the terrain type of the pixels of an object. The image has to be of the same dimensions of the object in question. The masks work like `mask.png` of image maps, see [PresetMaps#mask.png].

The name of an object mask file has to follow the pattern “`<object name>_mask.png`”, where “`<object name>`” is the file name of the object the mask is applied to, minus the suffix. For example, the mask of `cheese.png` would be `cheese_mask.png`. (See the Cheese theme in `Data/Themes/Cheese` in the Hedgewars installation directory for an example.)

If an object mask is not provided, the object in question can be destroyed but will, unlike the main terrain, not leave the terrain background texture behind.

=== Sprays ===

Sprays are single images of any size, they will be drawn onto the land texture (by `LandTex.png`). You can choose the file name by yourselves, but it must follow the following rules:

 * It must have the suffix “`.png`”

 * It must not be equal with any other file name mentioned on this page

Sprays have to be configured in `theme.cfg`.

== Weapons and utilities ==

You can replace certain images of weapons and utilities. All these images are optional and have default images. The default images often serve as a good template to create your own graphics.

=== `amGirder.png` ===

You can create a custom image for manually built girders (from the  “Construction” utility) by adding this file to your theme. Don’t confuse this with `Girder.png`! If unspecified, `Data/Graphics/amGirder.png` is used.

The image is of size 480×480 pixels and consists of 9 sub-images of size 160×160 each in a 3×3 grid, but only 8 sub-images are used. This table shows the starting and ending coordinates of the squares which make the sub-images:

|| *x minimum* || *y minimum* || *x maximum* || *y maximum* || *Orientation* || *Length* ||

|| 0 || 0 || 160 || 160 || Horizontal || Short ||

|| 0 || 160 || 160 || 320 || Falling right || Short ||

|| 0 || 320 || 160 || 480 || Vertical || Short ||

|| 160 || 0 || 320 || 160 || Rising right || Short ||

|| 160 || 160 || 320 || 320 || Horizontal || Long ||

|| 160 || 320 || 320 || 480 || Falling right || Long ||

|| 320 || 0 || 480 || 160 || Vertical || Long ||

|| 320 || 160 || 480 || 320 || Rising right || Long ||

*Important*: Please make sure to test your custom girder image in-game with all orientations to make sure it works correctly.

=== `Snowball.png` ===

This is the image of the mudball when thrown. It has a size of 16×16 pixels. If you specifiy this image in your theme, you should specify `amSnowball.png` as well.

By default, `Data/Graphics/Snowball.png` is used.

=== `amSnowball.png` ===

This is the image of the mudball with the hand of a hedgehog. It has a size of 128×128 pixels. If you specifiy this image in your theme, you should specify `Snowball.png` as well.

By default, `Data/Graphics/amSnowball.png` is used.

=== `RopeNode.png` (1.0.0) ===

A piece of the rope. Use this to customize the rope. The default image has a size of 16×16 pixels. You can use this in combination with `rope-step` in `theme.cfg`.

Default image: `Data/Graphics/RopeNode.png

== Background ==

=== `Sky.png` ===

This image will be drawn far in the background behind the water, the horizont images and the landscape.

It is repeated horizontally, unless you use `SkyL.png` and/or `SkyR.png`, then it is just the center image. It is recommended that you make sure that this images blends well with the sky color as specified in the `sky` variable in `theme.cfg. You also would want to make sure this image has no horizontal seams.

If not present, there will be no sky.

=== `SkyL.png` and `SkyR.png` ===

If both are present, `Sky.png` will only be drawn once in the center, `SkyL.png` will be drawn left of `Sky.png` and will be repeated into the left direction. `SkyR.png` will be drawn right of `Sky.png` and is repeated to the right direction.

If only `SkyL.png` is present, this image will be drawn and repeated both left and right of `Sky.png`.

=== `horizont.png` ===

This image is drawn behind the water and the landscape, but in front of the “sky” images. There is also a slight parrallax scrolling effect, this means, if the player moves the view to the left, the horizont will appear to move faster than the sky.

It is repeated horizontally, unless you use `horizontL.png` and/or `horizontR.png`, then it is just the center image. You also would want to make sure this image has no horizontal seams.

If not present, there will be no horizont.

=== `horizontL.png` and `horizontR.png` ===

These images are completely analogous to `SkyL.png` and `SkyR.png`.

=== `Clouds.png` ===

A sprite sheet of one or more cloud images for the clouds before Sudden Death. Each in size of 256×128. The cloud images have to be stacked vertically, so if you have 5 clouds, you have to use an image of size 256×640.

If missing, `Data/Graphics/Clouds.png` is used.

=== `SDClouds.png` ===

Sudden Death version of `Clouds.png`. If missing, `Data/Graphics/SuddenDeath/SDClouds.png` is used.

=== `Flake.png` ===

Contains a sprite sheet of 64×64 images. A flake is a background image which rotates and falls from the cloud line, flows with the wind and it can optionally be animated. This file is only for the flakes before Sudden Death. Each image in `Flake.png` is also called a “frame” (as in “animation frame”).

The game will cycle through each frame in order (for each individual flake).

As alternative to having one kind of animated flake, you can use frames to have static, but visually different kinds of flakes

Flakes can be configured in `theme.cfg`.

If this file is missing, no flakes are shown before Sudden Death.

=== `SDFlake.png` ===

Sudden Death version of `Flake.png`. If missing, `Data/Graphics/SuddenDeath/SDFlake.png` is used. This image contains skulls and bones.

=== `Snow.png` ===

A snowflake. A snowflake is a type of flake which might become part of the terrain. This is used in themes in which snow flakes are enabled (see [ThemeCfg]). The default image size is 3×3, but different sizes might work as well. If missing, `Data/Graphics/Snow.png` is used. The default image works just fine, only override this if you really want to.

=== `CloudsL.png`, `SDCloudsL.png`, `FlakeL.png`, `SDFlakeL.png` ===

Optional horizonally mirrored version of `Clouds.png`, `SDClouds.png`, `Flake.png` and `SDFlakeL.png`, respectively. If present, these images instead of the unmirrored ones are used when the wind blows the flakes or clouds to the left.

== Water ==

All water images are optional and all have defaults (in `Data/Graphics`). Water images come in 2 groups of 3 images each, for the time before Sudden Death and for Sudden Death. It is recommended that you edit all images in a group at once, so the colors match neatly. You probably don’t want to have blue water driplets if you have made the water blood-red.

=== `BlueWater.png` ===

This will be drawn on the top of the water, before Sudden Death. The size is 128×48 pixels. It does not have to be blue, despite the name. This image will be repeated horizontally. It is recommended to edit `water-top` and `water-bottom` in `theme.cfg` as well if you use a custom image, so the colors match nicely.

By default, this image is a single blue wave found in `Data/Graphics/BlueWater.png`.

=== `Splash.png` ===

The water splash animation before Sudden Death. It is shown when something large falls into the water. A sprite sheet containing a splash animation of 20 frames. The image has a total size of 160×500 pixels and the sprites are arranged in a grid 2×10 images. The single images have a size of 80×50 pixels each. In order to avoid rendering problems, the 4 borders of each frame (1 pixel wide) must be fully transparent. The animation starts with the leftmost image and continues downwards, after the 10th image, it continues with the top right image and continues downwards again. 

If missing, `Data/Graphics/Splash.png` is used.

=== `Droplet.png` ===

This images contains a few droplets (before Sudden Death) which will be drawn when something walls into the water. A sprite sheet of 4 images of size 16×16 sprites each, total size 16×64 pixels.

If missing, `Data/Graphics/Droplet.png` is used.

=== `SDWater.png` ===

Sudden Death version of `BlueWater.png`. By default, this is a single purple wave. If missing, `Data/Graphics/SuddenDeath/SDWater.png` is used.

=== `SDSplash.png` ===

Sudden Death version of `Splash.png`. If missing, `Data/Graphics/SuddenDeath/SDSplash.png` is used.

=== `SDDroplet.png` ===

Sudden Death version of `Droplet.png`. If missing, `Data/Graphics/SuddenDeath/SDDroplet.png` is used.

== Sounds ==

A few custom water-related sounds can be added, they will override the default ones. The following files can be added (see [Sounds] to learn what they mean):

 * `splash.ogg`

 * `Droplet1.ogg`

 * `Droplet2.ogg`

 * `Droplet3.ogg`

 * `skip.ogg`