Creating new themes

Warning: Very outdated and dusty

Note: This guide is very, very outdated. In fact, it is so outdated and dusty, you'll get a black lung just by reading it. ;-)

See Themes on the Hedgewars Knowledge Base for more up-to date theme.cfg and file references.

If you have landed here because you searched for information on themes in general, go to the Theme page in ths wiki.

Below this line begins the old guide. You have been warned!


Themes in Hedgewars control the look of all elements that appear on screen but weapons and hedgehogs, and are the base on which random maps are built.

In this article we'll explain step by step how to create a new theme and how to make it look good.

All themes must follow the Hedgewars graphics rules, style constraints and guidelines, so if you're unfamiliar with those, please read that first.

Your first theme

All themes are located at %DATA_DIR%/Data/Themes, being each of the folders inside it a full theme.
%DATA_DIR% is platform dependant, but as a general guideline it should default to /usr/share/hedgewars for UNIX-like machines and C:\Program Files\hedgewars for Windows machines. Inside that dir is also located the themes.cfg file, which control what themes are shown in the GUI in order to exclude those intended to be only for maps or missions.

In order to create a new theme you need to create a new folder there first and add the name of that folder to themes.cfg
For this article, let's create a new theme named "Wiki".

The main file of any theme is theme.cfg. Theme.cfg defines not only the parameters of the theme, but also what objects are present and their behavior.
All themes must contain a theme.cfg, so for now create a blank text file named theme.cfg in you Wiki directory.


IMPORTANT NOTE: The syntax shown below is OUTDATED, see for a description of the new, easier to read, syntax of theme.cfg!

theme.cfg file defines the basic elements all themes must contain, following a very strict syntax.
Let's take a look at an example:
0 0 0
64 64 64
62 123 148
53 105 133 128
1 98 252 60 4 1 43 0 170 196
8 80 50 10

As you can see, the file is rather spartan, but don't let it scare you. What you're seeing here is the definition of the various parameter of the theme, each one in a separate line.
Those lines are:

  1. 0 0 0
    Sky color, in RGB format
  2. 64 64 64
    Explosion border color, in RGB format
  3. 62 123 148
    Top water color, in RGBA format (alpha is optional)
  4. 53 105 133 128
    Bottom water color, in RGBA format (alpha is optional)
  5. Freeway.ogg
    Background music.
  6. 8
    Number of clouds
  7. 1
    Number of (optional) land objects the theme contains

Next comes the definitions of those objects. It's very important the number of definitions and the number defined in the previous line coincide, otherwise the theme won't load.
Each object definition consists of two lines, which define the name of the object and it's parameters, such as which parts of the object will be buried in land and which will be visible. If you find this confusing don't worry, we'll come back to that later.

  1. Object
    Image name (without extension, .png is assumed)
  2. 1 98 252 60 4 1 43 0 170 196
    Description of the object:
    1. 1
      Number of instances of the object game should spawn in a regular-sized map. This value is automatically scaled accordingly to map size.
    2. 98 252 60 4
      Rectangle that is guaranteed be hidden from view, ie, buried in land, in "left top width height" format.
    3. 1
      Number of rectangles that must remain visible 
    4. 43 0 170 196
      0 or more rectangles defining visible parts of the image in "left top width heigth" format.
  1. 1
    Number of (optional) spray objects the theme contains

Next comes the definitions of those objects. It's very important the number of definitions and the number defined in the previous line coincide, otherwise the theme won't load.
Each object definition consists of two lines:

  1. Spray
    Image name (without extension, .png is assumed)
  2. 1
    Number of instances of the object game should spawn in a regular-sized map. This value is automatically scaled accordingly to map size.

The last two lines of the theme.cfg define flake parameters:

  1. 10
    Number of flakes
  2. 8 80 50 10
    Parameters of the flakes in "number_of_frames frame_duration rotation_velocity falling_speed" format

Of course, your new theme won't load because Object.png and Spray.png are still missing, so grab this example file and extract it into your Wiki folder. Now you have a complete theme to play with.

Remember when we talked about land objects definitions? If you now open Object.png you should see a regular orange tree-like shape that looks like this:

As you can see, the object itself has no particular hint for the game on how it should be placed in land, so we need to detail that data in theme.cfg.
As we mentioned earlier, we do that by defining rectangles, one that will be hidden from view, ie, used to latch the object to land, and as many as you want that will be visible to the user.
This is how the game sees out object combined with the parameters from theme.cfg:

Beyond theme.cfg

theme.cfg defines the basic aspects of our new theme, but we won't stop there.
Engine allows themes to customize the game further by loading custom images from the theme folder, replacing default ones.

Let's take a look at a how an schematic of how our really ugly Wiki theme looks in game:

That image reflects not only our previously defined theme.cfg parameters, numbered as the line they appear in, but also our custom images:

  1. Sky color
  2. Explosion border color
  3. Top water color
  4. Bottom water color
  5. Cloud
  6. Land object: land objects are placed around the land
  7. Spray object: spray objects are placed inside land
  8. Flake
  1. Sky.png: background texture. Here it's represented as horizontal red lines.
  2. horizont.png: background texture, closer to the player than Sky. Here it's represented as vertical red lines
  3. Cloud.png: image containing 4 different clouds
  4. Border.png: image containing both upper and lower land border
  5. LandTex.png: land texture
  6. LandBackTex.png: backland texture. It's revealed after digging and explosions
  7. Girder.png
  8. Flake.png: image containing various flakes or a flake animation
  9. BlueWater: image that sits on top of waterline
They're not visible in the screen capture, but the following images can be customized too:
  • Droplet.png
  • Splash.png: both used when something falls into water
  • Dust.png: animation used when falling on land
Note that you don't actually need to draw all those images. If your theme doesn't use flakes, clouds or don't feel like creating girders or bluewater textures you can just avoid creating those and the game will simply use default pixmaps for those elements that are required or don't display anything for those that aren't.

Important considerations

Your theme is now ready, but there are a few considerations you should take into account before releasing it to the world:
  • First and more important, remember the game has a broad audience, avoid using strong subjects for your theme, such as death, gore, pr0n, etc...
  • Second, the game runs in a variety of devices, not all of them having great graphics capabilities. As such, there is one limitation when it comes to images: images can't be bigger than 1024 x 1024 pixels!
    There are two exceptions to this rule, Sky.png and horizont.png, but you should provide a max 1024 x 1024px fallback version of those images named Sky-lowres.png and Sky-lowres.png for wimpier devices, otherwise your theme will be background-less in them.

Tips and tricks

  • Leave room between the hidden and visible rectangles of your objects. If you place them too close, the engine will have a hard time finding spots that meet your specifications, so you may end up never seeing them.
  • Also avoid too big hidden or visible areas unless necessary. Too restrictive visible areas means less random objects (engine has less room to play); too restrictive hidden areas means less probability to find a spot for the object.
  • Your theme has a central subject that is not supposed to be repeated? There are 4 special images for that matter, SkyL.png, SkyR.png, horizontL.png and horizontR.png. Those will be repeated instead of Sky and horizont.png, which will be drawn just once instead.

User login

Copyright © 2004-2024 Hedgewars Project. All rights reserved. [ contact ]