Back to homepage
How to create your own themes
Updated Sat, 01 Aug 2020 15:47:12 -0400 by nemo


Themes in Hedgewars control the look of many elements that appear on screen (especially the map) and are the base on which random maps are built.

Understanding themes

First of all, you should understand themes from the player perspective. Read the Theme page on the Hedgewars Wiki to learn the player basics.

Theme types

Full themes are themes which can be used together with random maps. Those usually appear in the multiplayer screen for selection as well. Most themes are full themes and when talking about themes without qualification, full themes are meant.

Background themes are minimal themes without this capability. They lack land textures, thus they can only be used as a background (hence the name). Background themes work only together with image maps or forts. As of 1.0.0, there are no background themes in Hedgewars. Background themes must be hidden.

Theme structure

Technically, a theme consists of a configuration file and many media files (PNG images). Themes can define many images, or just a very few. You can set flakes, clouds, water color, the background, land texture and much, much more. Many files and settings are optional and have (more or less) sane defaults.

The theme allows for further customization in Sudden Death. A good theme maker should definitely at least consider a custom SD style. But intentionally keeping the default SD style is still an option, of course.

The background music file is not part of the theme, as all music is stored in %USERDIR%/Data/Music . The theme just accessed it via theme.cfg .

Theme elements (overview)

To give you a feeling of how themes are structured, here's a basic list of elements of which themes are made of. In ThemeFiles everything is explained in great detail.


  • Land textures: Basic tiled image of terrain, in front and background layer. Mandatory for full themes
  • Land border: The border of the land texture. Mandatory for full themes
  • Explosion border: A fixed-width border of a single color when the land exploded
  • Objects: Theme objects are things like obelisks, statues and things which extend ouf of the basic landscape
  • Land girder: Look, shape and thickness of “land bridges”
  • Construction overwrite: The shape and look of girder placed from the Construction utility can be overwritten as well

Eye candy

  • Sprays: Sprays are added on top of the land textures randomly
  • Background: Consists of background color and two image layers with parrallax scrolling
  • Flakes: Flakes are decorational fall from the clouds and follow the wind. Flakes can be animated.
  • Clouds: Clouds move horizontally with the wind. There can
  • Water: You may customize the water style and related images (if you wish). Water can be animated (unused in default themes)
  • Particles: Land chunLs, mudball, collision dust, water drops, etc.

Remember many theme elements have a Sudden Death variant as well!

Getting started

All themes are located at %USERDIR%/Data/Themes , being each of the folders inside is a theme. %USERDIR% is the user directory, see User directory on the Hedgewars Wiki. On Windows, you use backslashes, of course. ;-)

In order to create a new theme, you need to create a new folder there first and add the name of that folder to theme.cfg . This file defines not only the parameters of the theme, but also what objects are present and their behavior.

Then you'll need to create a bunch of data files (mostly PNG images) for the landscape, land objects, background, etc. Note the music is not considered to be part of the theme.

Full themes need at least: theme.cfg , an icon file ( icon.png or icon@2x.png ), LandTex.png and Border.png . A background theme theorecitally does not need any files besides theme.cfg (but it doesn't have much to look at, then :D).

These were the basics. Read the following pages to continue:

Theme editor (unofficial)

KoBeWi created an unofficial theme editor to make the creation of themes a little bit easier:

Hedgewars Theme Editor

Sharing themes

You can only play with a theme against other players online if all participating players have the theme installed under the same name. You can find some themes in DLC, players will likely have those installed. If not, either try a default theme or politely point the other players to DLC.

If any player does not have the theme installed, the game will fail to start and an error message is displayed.

You are encouraged to share your themes in the “Content Creations” subforum, where submissions are considered for official inclusion into Hedgewars.

Inclusion in Hedgewars

If you want a theme to be included with Hedgewars, it must follow Hedgewars graphics rules, style constraints and guidelines, so if you're unfamiliar with those, please read that first.

Note that there is no guarantee we'll include any theme, no matter how good.

Note that themes we consider to be inappropriate for the general Hedgewars “feel”, we might still reject it, even if it perfectly follows all style guidelines. We prefer a kinda “family-friendly” setting, although this term is very loosely defined. Two examples for such rejected themes are Military_v1 and Belly_v1 .