Creating new themes

Sat, 2010-04-10 14:27 — Palewolf

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!

Introduction

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.

theme.cfg

IMPORTANT NOTE: The syntax shown below is OUTDATED, see http://code.google.com/p/hedgewars/wiki/Theme 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
Freeway.ogg
8
1
Object
1 98 252 60 4 1 43 0 170 196
1
Spray
1
10
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:

```
0 0 0
```
Sky color, in RGB format
```
64 64 64
```
Explosion border color, in RGB format
```
62 123 148
```
Top water color, in RGBA format (alpha is optional)
```
53 105 133 128
```
Bottom water color, in RGBA format (alpha is optional)
```
Freeway.ogg
```
Background music.
```
8
```
Number of clouds
```
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.

```
Object
```
Image name (without extension, .png is assumed)
```
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
```
Number of (optional) spray objects the theme contains

```
Spray
```
Image name (without extension, .png is assumed)
```
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:

```
10
```
Number of flakes
```
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:

Sky color
Explosion border color
Top water color
Bottom water color
Cloud
Land object: land objects are placed around the land
Spray object: spray objects are placed inside land
Flake

Sky.png: background texture. Here it's represented as horizontal red lines.
horizont.png: background texture, closer to the player than Sky. Here it's represented as vertical red lines
Cloud.png: image containing 4 different clouds
Border.png: image containing both upper and lower land border
LandTex.png: land texture
LandBackTex.png: backland texture. It's revealed after digging and explosions
Girder.png
Flake.png: image containing various flakes or a flake animation
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.