## Introduction
This Tutorial will take you through the basics of creating a theme for EmulationStation (ES) and RetroPie.
It will create a simple theme called Spare. The default Carbon theme as a reference, while creating all the XML from scratch, so you will get a better understanding of it.
During the course, three systems will be covered as example:
- Game Boy (folder: `gb`)
- Nintendo Entertainment System (folder: `nes`)
- Super Nintendo Entertainment System (folder: `snes`)
These systems are not only ubiquitous but contain some graphically layout challenges, for example the different shaped box art (square, portrait and landscape respectively), and we will be using those differences for some more advanced concepts in a later tutorial.
After the exercise with three theme-layouts for these systems you should have got an understanding how theming works in general. Three is the minimum of systems to fill the carousel and also the maximum visible at the same time.
The theme you are going to make will look like this:
Spare Theme System View
Spare Theme Basic View
Spare Theme Detailed View
It is a simple, clean theme, not very outlandish, but it's enough to teach the essentials, and a few of the more advanced ideas.
**Note**
> This tutorial was developed on Windows, but all the main parts (the XML and images) can be done on any Operating System, as long as you can access and modify files in the `theme` folder on your Raspberry Pi (e.g., with Samba, see [setup](#use-samba-share-of-emulationstations-themes-on-retropie)).
### What You Will Need
- A text editor
- Notepad will do fine, but something with syntax highlighting is way more helpful. Whatever editor you prefer: It should support XML formatting and maybe even XML linting.
- EmulationStation
- This tutorial uses a version on a Windows machine (more on that below), but the version on your Pi is fine.
- An image editor
- This is optional as all the images will be supplied, however you can use these images as a base to create your own, or make your own from scratch. On Windows you may use Photoshop, but other programs like GIMP, Inkscape, Krita or Paint.net would work too. Whenever possible use SVG format for your graphics instead of pixel based formats (JPG/PNG) as the former scales properly without visible artifacts.
- The ES Theme Helper by @Rookervik
- Not essential, but very, very handy
- [Get it from @Rookervik's DropBox here](https://dl.dropboxusercontent.com/u/60872572/EmulationStation/ES%20Theme%20Helper3.rar)
- Any coding experience
- Again, not essential, but it makes things easier. To be honest, as long as you know that `` opens a tag (more precisely an XML element) and `` closes a tag, then you should be fine.
The (sample) files you will need for this tutorial are listed [here](#references).
### Primer on EmulationStation Views
EmulationStation has three main navigation sections, called _Views_:
Carbon Theme System View
The _System View_ is what you see when EmulationStation starts. It has a large white bar along the middle that houses a carousel that shows three System logos at a time.
Carbon Theme Basic View
This is a simple game list page. You see this if you haven't scraped any metadata for that system.
Carbon Theme Detailed View
The _Detailed View_ is what you see if you *have* scraped metadata. Different themes can show different data, in different places or a different order, but every theme can only display these values (along with the Game List):
- `md_description`
- `md_developer`
- `md_genre`
- `md_image`
- `md_thumbnail`
- `md_lastplayed`: Stored as ISO8601 date time format e.g., 2023-03-17T19:14:12+00:00
- `md_playcount`
- `md_players`
- `md_publisher`
- `md_rating`
- `md_marquee`
- `md_releasedate`: Stored as ISO8601 date format e.g., 2023-03-17
Finally, the _Video View_ is what you see if your scraped metadata includes videos. The video view is an extension of the Detailed View. It can display all the values found in the Detailed View along with a _video_ metadata tag:
- `md_video`
Extra values can be added by the Theme Maker, but the ones above are the only ones that get scraped by EmulationStation. Any others have to have their data entered by hand. More on the `extra` attribute later, in the [System View Section](#system-view).
## Setup
This tutorial uses the portable version of EmulationStation created by @herb_fargus. But this is not a restriction, you can use your own ES setup on a different system and may use for example Samba to serve the theme files.
### Set Up EmulationStation on PC
- Download the portable EmulationStation by @herb_fargus, see [references](#references)
- Install/unzip it where you want it. For example if you have it on `F:\` drive, so the path is `F:\emulationstation`
- Download the fake games' collection, see [references](#references). Within it are three folders: `gb`, `nes` and `snes`. Within each folder are 15 empty files, each named after a game on that system. These files have also had their extensions changed to something that EmulationStation will recognize as a ROM.
- _These are not real ROMs. They are blank text files that have been renamed to look like ROMs._
- EmulationStation sees these as real games. You won't be able to play them (since they are really just empty files), but they will scrape with the built-in EmulationStation scraper. They are also tiny, so you don't have to worry about your test-bed getting too big.
- Copy those folders into `F:\emulationstation\\.emulationstation\roms`
EmulationStation should now be set up with 45 (fake) games on three Systems, and ready for you to use.
Double click `Launch Portable (Windowed).bat` to start EmulationStation.
### Use Samba Share of EmulationStation's Themes on RetroPie
You may also edit theme files directly on the Raspberry. However, you should use a wired network connection between your desktop and the Raspberry to enable smooth editing. Open `\\retropie\configs\all\emulationstation\themes\` in the Windows File Explorer. You should be able to see (and edit) the currently installed themes of your EmulationStation installation. If you do not see any theme, then install the Spare theme as outlined below. For reloading a theme (see [shortcuts](#keyboard-shortcuts-in-emulationstation)) you should also have a keyboard attached to your RetroPie, and it should be in reach from your desktop system.
## Creating a Theme
We're going to make the theme straight in the Portable EmulationStation's theme folder. Of course, you are free to act directly on the Samba Share, which does not require file copy operations.
If you use the portable EmulationStation on `F:\` drive, so the path to the `themes` folder would be `F:\emulationstation\\.emulationstation\themes`.
First, [download the full Spare theme from GitHub](https://github.com/mattrixk/es-theme-spare), so you have the images and fonts you need, and also, so you have something to reference.
We'll start by setting up a simple file structure, with folders for the three console systems; Game Boy (`gb`), Nintendo Entertainment System (`nes`) and Super Nintendo Entertainment System (`snes`).
- Within the themes folder make a folder called `spare`.
- In the `spare` folder make a new file called `spare.xml`.
- Within the `spare` folder make folders called `nes`, `snes`, `gb` and `_inc`.
- In each of `nes`, `snes`, `gb` make a new file called `theme.xml`.
- Also copy the system images from the downloaded file into the system folders
- `_inc` is your includes folder where you will hold your fonts and theme images. You can call it anything you like. Some other themes use `art`, others use `common`. This tutorial uses `_inc` with an underscore which keeps it at the top of the file tree.
- Within `_inc` create two folders, called `fonts` and `images`. Copy the fonts and images from the downloaded file into their respective folders.
Your folder structure should now look like this:
Folder Structure
Now onto the code.
Open `spare.xml` and add these lines:
```xml
4
```
When you are making your own theme you would obviously change the 'theme name' and 'author' fields to suit.
- The theme details at the top just tell anyone looking who made the theme.
- Anything within `` is a comment, visible to humans who read the code, but invisible to EmulationStation.
- The `` fields tell EmulationStation that the code within is for a theme.
- The `4` sets the theme version. The version 3 is the latest by the original author of EmulationStation, within RetroPie's fork of EmulationStation the current Version is 4 which -among other things- support the Child-Friendly setup (aka "kid mode" in UI settings).
- `` governs what happens in each of those views.
Save `spare.xml`
Open `spare/gb/theme.xml` and add these lines:
```xml
4./../spare.xml
```
Notice that it's almost identical to `spare.xml`, except for a few things. You don't need to specify any theme details, because we are using this line:
`./../spare.xml`
That line means, find a file up one level from here, called `spare.xml`, and include it in this file.
This is handy because it means you can have the bulk of your code in `spare.xml` and just call the file in each `theme.xml` instead of having to put the code in each individual `theme.xml` file.
Save `theme.xml`
If you switch EmulationStation to the Spare theme now, this is what you should see:
Blank System View
Blank Basic View
Blank Detailed View
What you are seeing are the EmulationStation defaults. We haven't yet told EmulationStation how we want anything to look, so for now it's just raw data with very, very basic styling. It's our job as "Themers" to change that.
### System View
Now let's create the System View.
Spare Theme System View
Take note of how it differs from the blank theme.
- There are now Logos in place of simple folder names.
- The white carousel and the gray bar below it hadn't changed (unfortunately, they are hard coded into EmulationStation and for the time being are not theme-able).
- Note the gray background color behind the carousel.
- This System View has now a repeating background image behind the carousel.
- There is a semi-transparent white bar behind the _Help Menu_ text in the footer.
- The _Help Menu_ now has a different color and different font.
Open `spare.xml`
We'll start simple. Let's change the background color.
Expand `` so it looks like this:
```xml
```
Now we add some **Elements** to the View. To start with we'll change the background color by creating a new Image Element called `background_color`.
```xml
```
**The `extra` attribute**
> The `extra="true"` XML attribute means that this is a new XML **Element** being added, not something that is already defined by EmulationStation
We need to add some **Properties** (as XML child elements) to the Element to tell it what to do. There are seven Properties accepted by the image Element. They are:
- ``: The position of the image within the screen, given in percentage of the actual display resolution.
- ``:The absolute size of the image given in percentage of the actual display resolution. Does not maintain aspect ratio. Use either this or ``, not both.
- ``: The maximum size to stretch an image. Maintains aspect ratio. Use either this or ``, not both.
- ``: The origin point of the image. Default is top-left.
- ``: The relative path to the image file.
- ``: If the image repeats or not.
- ``: A color overlay, allowing you to change the color and opacity of the image. Uses four bytes values. The first three bytes represent the Hex color code (one byte per red, green, blue) with the last byte is defining the opacity (alpha channel).
If you want a more detailed explanation of Element Properties you can read [this section](https://github.com/RetroPie/EmulationStation/blob/master/THEMES.md#image) of the EmulationStation themes documentation. Especially if you want to use absolute pixel sizes (see [``](https://github.com/RetroPie/EmulationStation/blob/master/THEMES.md#the-resolution-tag) element).
The first thing we'll do is set the path to the image: You should already have `bg_color.png` in your images' folder. If not, grab it from the Spare theme you downloaded earlier and place it in the `spare/_inc/images` folder. This image is a simple, white 32 x 32px PNG.
**Warning**
> Do not omit the heading dot (`.`) in ``.
Add the line:
`./_inc/images/bg_color.png`
to
``
so it looks like this:
```xml
./_inc/images/bg_color.png
```
Here we are telling ES to look for an image called `bg_color.png` within a folder called `images` that sits within a folder called `_inc` that sits at `root` level.
Now we tell the Image where we want it to sit and how big we want it to be. We want it to start at the top left of the screen and stretch all the way to the bottom right. For that we need the ``, `` and `` Properties.
- `0 0` tells ES that the image originates at X position = 0 (left) and Y position = 0 (top).
- `0 0` tells ES to place the `` of the image in X position = 0 (left) and Y position = 0 (top).
- `1 1` tells ES the stretch the image 100% along the X-axis (horizontal) and 100% along the Y-axis (vertical).
Put it all together and it looks like this:
```xml
./_inc/images/bg_white.png0 00 01 1
```
**Tip: Reloading the theme changes**
> If you want to see any changes you have made to your theme files, first save the file. Start EmulationStation with the `--debug`. Within EmulationStation press _left_ ++ctrl+r++ whenever you want to force the theme to be re-applied. This will be referred as "refresh the theme" in this tutorial.
If you refresh the ES theme now (see tip on the right) you wouldn't see anything different, because the background was already white.
This is where the `` Property comes into play. You can use this Property to change the white PNG to any color you want using [Hex color codes](https://www.htmlgoodies.com/tutorials/colors/article.php/3478951). There are many online [color picker tools](https://htmlcolorcodes.com/color-picker/) you can use to get your Hex color codes, just remember they need to be six numbers/letters to work correctly.
If we want to change our background color to Red, we add this line to the `background_color` Element:
`FF0000`
Other randomly chosen colors:
**Tip: Transparency**
> If you do not define a value for alpha channel (the fourth byte). Alpha channel will be 255 (hex: `0xff`), which means full opacity.
- `70D6F3` = Light Blue
- `229C29` = Dark Green
- `FF7700` = Orange
- `CF1F97` = Purple
Let's choose a light gray color, so it stands out a little, but not too much. Your `background_color` Element should now look like this:
```xml
./_inc/images/bg_color.png0 00 01 1d4d4d4
```
And if you refresh ES, you'll now see a light gray background behind the Carousel.
It should look like this:
Spare Theme System View - Background Colour
Now for the Background Pattern:
- `bg_pattern.png` should already be in your `spare/_inc/images` folder.
- Duplicate the `background_color` Element and change it, so it looks like this:
```xml
./_inc/images/bg_pattern.png0.5 0.50.5 0.51 1aeaeaetrue
```
What we've done here is:
- Renamed the Element to `background_pattern`.
- Changed the `` to point to the `bg_pattern.png` image.
- Adapted the `` to be the center of the image instead of the left-top.
- Adapted the `` to be the center of the screen instead of the left-top.
- Modified the `` to be a darker gray.
- Added the line `true`. This line tells ES to repeat the image over the space instead of stretching it out.
**Note**
> Changing the `` and `` isn't strictly necessary, but it looks more interesting with most patterns, so they start from the center of the screen instead of the left-top. As usual, it's up to you what you prefer.
It should look like this:
Spare Theme System View - Background Pattern
#### Help Menu Background
This is the background that covers the Help menu items in the bottom left of the screen.
- Again, duplicate the `background_color` Element and change it, so it looks like this:
```xml
./_inc/images/bg_color.png0 10 11 0.070FFFFFF99
```
What we've done here is:
- Renamed the Element to `background_help`.
- Changed the `` to point to the `bg_help.png` image.
- Adapted the `` to be the left-bottom of the image instead of the left-top.
- Adapted the `` to be the left-bottom of the screen instead of the left-top.
- Changed the `` from '1 1' to '1 0.070'. What this means is, we still want the image to stretch the full width of the screen, but we only want it to be 7% of the screen height.
- Told the background to be white `FFFFFF`, but we also added `99` to the end of the `` to give it a slight transparency. `FF` is fully opaque and `00` is completely transparent.
It should look like this:
Spare Theme System View - Help Background
#### Help Menu Font
We're going to change the Font used in this theme to Roboto Light (and a little Roboto Bold), and also change the color of the Font.
Add these lines to `spare.xml` under `background_help`:
```xml
000000000000./_inc/fonts/Roboto-Light.ttf0.03
```
This changes:
- Text and icon color to black.
- Font from default to Roboto Light.
- Font size.
It should look like this:
Spare Theme System View - Help Font
Save `spare.xml`
We're nearly done with the _System View_. All that remains is to add the System **Logos** to the Carousel.
Open `spare/gb/theme.xml`
Expand `` and insert the following line:
```xml
./logo.png
```
So it looks like this:
```xml
./system.svg
```
This tells ES to look in the same folder for an image called `system.svg` and to use it as the image for the Carousel in the System View.
Save `theme.xml`
Do this for both the `nes` and `snes` folders as well.
Refresh ES and have a look at the _System View_. It should now look like this:
Spare Theme System View
### Basic View
The Basic View should look like this:
Spare Theme Basic View
As you can see, the background color, background pattern and Help menu are the same as the System View. That means we can use the same code for both.
Open `spare.xml`. It should look like this:
```xml
4./_inc/images/bg_color.png0 00 01 1d4d4d4./_inc/images/bg_pattern.png0.5 0.50.5 0.51 1aeaeaetrue./_inc/images/bg_color.png0 10 11 0.070FFFFFF99000000000000./_inc/fonts/Roboto-Light.ttf0.03
```
Now, we could just copy all the `` Elements and paste them into ``, but there is an easier way.
Change:
``
to
``
Done. Now, instead of saying that the following code is just for the System View, it's also for the Basic, Detailed and Video Views. How easy was that? This trick will come in handy a lot later on.
Now we just need to style the System Logo and the Gamelist.
**System Logo**
For the **System Logo**, we're going to use the same trick as above. Open `spare/gb/theme.xml` and change:
``
to
``
That means anything within that `` will apply to all four views.
The Basic View should now look like this:
Spare Theme Basic View - Background
Save `theme.xml`.
Back in `spare.xml` we are going to create a semi-transparent white background box in the header to match the one in the footer (behind the Help menu).
Expand `` and insert the following:
```xml
./_inc/images/bg_color.png0 00 01 0.18FFFFFF99
```
This places a white box across the top of the screen that is 100% of the screen in width and 18% of the screen in height:
Spare Theme Basic View - Logo Background
The concept of **Helper Boxes**. These are just semi-transparent colored boxes that can be used to work out where an Element will sit on the screen. For example: Use one to place the Logo.
```xml
./_inc/images/bg_color.png0.5 0.50.5 0.090.4 0.16ff0000aa
```
- `0.5 0.5` sets the Origin Point to the center of the box.
- `0.5 0.09` puts the Origin Point of the box at 50% of the screen width, and at 9% of the screen height.
- `0.4 0.16` means the box is 40% wide and 16% high.
- `ff0000aa` gives the box a transparent red color.
Like this:
Spare Theme Basic View - Logo Helper
Now we can place the logo inside that box:
```xml
0.5 0.50.5 0.090.4 0.16
```
Notice we are setting the `` and `` the same as "logo_helper". Instead of `` we have used ``, but kept the numbers the same. If we used `` the logo would stretch to fill the box, lose aspect ratio and look weird. Using `` forces the image to maintain aspect ratio. It will grow until either the sides or top/bottom hit the edge and then stop.
Spare Theme Basic View - Logo
We'll use another Helper Box to get the right spacing for the Gamelist:
```xml
./_inc/images/bg_color.png0 00.05 0.20.9 0.71ff0000aa
```
Spare Theme Basic View - Gamelist Helper
Now we know the size for the Gamelist:
```xml
000000FFFFFF000000888888./_inc/fonts/Roboto-Light.ttf0.05 0.20.9 0.710.04
```
- `` is the color of the bar that shows which game is selected. Set here to black.
- `` is the color of the text of the selected game. Set here to white.
- `` is the main text color of the Gamelist. Set here to black.
- `` is the color of any folders in your Gamelist. Set here to a mid-point gray.
Spare Theme Basic View - Gamelist
All that is left is to remove the Helper Boxes.
Delete the `` Element to remove the red box in the header.
Instead of deleting ``, we can use it as the white background:
- Rename it from `gamelist_helper` to `background_gamelist`.
- Change `ff0000aa` to `FFFFFF99`.
You should now be the owner of a shiny new Basic View:
Spare Theme Basic View - Complete
### Detailed View
Now for the Big One; the _Detailed View_: This one isn't too bad mostly, but the metadata can be a real hassle to order, so it looks nice. Each part of the metadata has to be done individually... but we'll jump off that bridge when we come to it.
This is what we want to end up with:
Spare Theme Detailed View - Complete
However, it starts off looking like this:
Spare Theme Detailed View - Background
Remember we have already styled the Logo, the Background and the Help menu.
Open `spare.xml`.
We're going to start by placing a bunch of Helper boxes to block out where we want everything.
- You can use an image editing program to mock this up beforehand, and this is where the ES Theme Helper comes in very handy.
- Or you can just sort of freehand it. Add a box, check its shape, move it, resize it, check it again. Keep doing that until you are happy with it, and then add another box.
Add this code to ``:
```xml
./_inc/images/bg_color.png0 00.01 0.020.35 0.89DC143C44./_inc/images/bg_color.png0 00.37 0.020.35 0.624169E144./_inc/images/bg_color.png0 00.73 0.020.26 0.6200C5CD44./_inc/images/bg_color.png0 00.37 0.660.62 0.25EEC90044
```
Which makes it look like this:
Spare Theme Detailed View - Helpers
These colored boxes will eventually be the semi-transparent white boxes that go behind the content, but for now we make them colored, so they are easier to see.
Now we want to add in some more Helper boxes within these, so the content will have some padding:
```xml
./_inc/images/bg_color.png0.5 0.50.186 0.140.33 0.198B636C44./_inc/images/bg_color.png0 00.02 0.250.33 0.648B636C44./_inc/images/bg_color.png0.5 0.50.545 0.330.33 0.580000EE44./_inc/images/bg_color.png0 00.74 0.040.24 0.5800868B44./_inc/images/bg_color.png0 00.38 0.680.60 0.21CDAD0044
```
Spare Theme Detailed View - Helpers Padding
**Note**
> Notice `logo_helper` and `image_helper_2` both have `0.5 0.5`. This is because we want the images to be aligned from the very center of their Helper box. It takes a bit more work to get these aligned properly, but it looks better once they are.
Now it's just a matter of moving each piece of metadata into its correct place.
Move the Logo:
```xml
0.5 0.50.186 0.140.33 0.19
```
Spare Theme Detailed View - Logo
Now the Image:
```xml
0.5 0.50.545 0.330.33 0.58
```
Spare Theme Detailed View - Image
The Gamelist:
```xml
000000FFFFFF000000888888./_inc/fonts/Roboto-Light.ttf0.02 0.250.33 0.640.040.01
```
Spare Theme Detailed View - Gamelist
The Description:
```xml
0.38 0.680.60 0.21000000./_inc/fonts/Roboto-Light.ttf0.026left01.6
```
Spare Theme Detailed View - Description
Now... the fun part. The metadata. So far everything has been pretty simple. Logos, game lists, images, etc. are all big things that you can place without too much thought. Metadata is different.
Metadata is split up into eight main sections (without counting Image and Description in this list), and each of those sections has both a Label and a Value.
- `md_lbl_rating`, `md_rating`
- `md_lbl_releasedate`, `md_releasedate`
- `md_lbl_developer`, `md_developer`
- `md_lbl_publisher`, `md_publisher`
- `md_lbl_genre`, `md_genre`
- `md_lbl_players`, `md_players`
- `md_lbl_lastplayed`, `md_lastplayed`
- `md_lbl_playcount`, `md_playcount`
To make things more annoying, `md_releasedate` and `md_lastplayed` are both `` fields instead of just plain `` fields, so there are certain things they can't do, like be center aligned.
This is the XML excerpt to place the metadata as shown in this tutorial (long XML fragment):
```xml
0000001./_inc/fonts/Roboto-Medium.ttf0.020.24 0.010000000./_inc/fonts/Roboto-Light.ttf0.0240.23 0.020000000./_inc/fonts/Roboto-Light.ttf0.0240.23 0.02./_inc/images/bg_color.png0 00.74 0.040.24 0.025bb800440.74 0.04./_inc/images/bg_color.png0 00.75 0.070.23 0.045bb800440.75 0.070.23 0.03./_inc/images/star_full.png./_inc/images/star_hollow.png./_inc/images/bg_color.png0 00.74 0.120.24 0.025bb800440.74 0.12./_inc/images/bg_color.png0 00.75 0.140.23 0.035bb800440.75 0.14./_inc/images/bg_color.png0 00.74 0.180.24 0.025bb800440.74 0.18./_inc/images/bg_color.png0 00.75 0.200.23 0.035bb800440.75 0.20./_inc/images/bg_color.png0 00.74 0.240.24 0.025bb800440.74 0.24./_inc/images/bg_color.png0 00.75 0.260.23 0.035bb800440.75 0.26./_inc/images/bg_color.png0 00.74 0.300.24 0.025bb800440.74 0.30./_inc/images/bg_color.png0 00.75 0.320.23 0.035bb800440.75 0.32./_inc/images/bg_color.png0 00.74 0.360.24 0.025bb800440.74 0.36./_inc/images/bg_color.png0 00.75 0.380.23 0.035bb800440.75 0.38./_inc/images/bg_color.png0 00.74 0.420.24 0.025bb800440.74 0.42./_inc/images/bg_color.png0 00.75 0.440.23 0.035bb800440.75 0.44./_inc/images/bg_color.png0 00.74 0.480.24 0.025bb800440.74 0.48./_inc/images/bg_color.png0 00.75 0.500.23 0.035bb800440.75 0.50
```
That comes out looking like this:
Spare Theme Detailed View - Metadata Helpers
Noticed how more Helper boxes are used for each piece of metadata? This was a long process of trail and error. Originally the font and spacing were too big, so they took up too much room. In the end they had to be shrunk down thus they don't take all the space.
Now just remove the second layer of padding Helpers, and change the main helper boxes color to `FFFFFF99`. The white helper boxes have the prefix to `background_` because they are now backgrounds rather than helpers.
### Video View
Now for the _Video View_. Video support is a newer feature of EmulationStation, so we have to take care to ensure our theme is backward compatible. Video view is an extension of the _Detailed View_ and should only require a few modifications.
The first step is to open `spare.xml`. We will be moving `md_image` into a separate view definition. Then we will add `video` to the original `detail` view element. The result should look like the following.
```xml
0.5 0.50.545 0.330.33 0.58
```
Next we want to theme the new elements that video view adds.
```xml
0.5 0.50.545 0.330.33 0.580.5 0.50.545 0.110.33 0.15
```
The final step is to ensure backward compatibility with earlier versions of EmulationStation that do no support video. To do this, we use a `feature` element. The feature element is used to hide portions of the theme XML from versions that do not support the specified feature.
```xml
0.5 0.50.545 0.330.33 0.580.5 0.50.545 0.390.33 0.460.5 0.50.545 0.110.33 0.15
```
You're all done. Congratulations!
Spare Theme Detailed View - Complete
This is the complete `spare.xml`:
```xml
4./_inc/images/bg_color.png0 00 01 1d4d4d4./_inc/images/bg_pattern.png0.5 0.50.5 0.51 1aeaeaetrue./_inc/images/bg_color.png0 10 11 0.070FFFFFF99000000000000./_inc/fonts/Roboto-Light.ttf0.03./_inc/images/bg_color.png0 00 01 0.18FFFFFF990.5 0.50.5 0.090.4 0.16./_inc/images/bg_color.png0 00.05 0.20.9 0.71FFFFFF99000000FFFFFF000000888888./_inc/fonts/Roboto-Light.ttf0.05 0.20.9 0.710.04./_inc/images/bg_color.png0 00.01 0.020.35 0.89FFFFFF990.5 0.50.186 0.140.33 0.19000000FFFFFF000000888888./_inc/fonts/Roboto-Light.ttf0.02 0.250.33 0.640.040.01./_inc/images/bg_color.png0 00.37 0.020.35 0.62FFFFFF990.5 0.50.545 0.330.33 0.58./_inc/images/bg_color.png0 00.73 0.020.26 0.62FFFFFF990000001./_inc/fonts/Roboto-Medium.ttf0.020.24 0.010000000./_inc/fonts/Roboto-Light.ttf0.0240.23 0.020000000./_inc/fonts/Roboto-Light.ttf0.0240.23 0.020.74 0.040.75 0.070.23 0.03./_inc/images/star_full.png./_inc/images/star_hollow.png0.74 0.120.75 0.140.74 0.180.75 0.200.74 0.240.75 0.260.74 0.300.75 0.320.74 0.360.75 0.380.74 0.420.75 0.440.74 0.480.75 0.50./_inc/images/bg_color.png0 00.37 0.660.62 0.25FFFFFF990.38 0.680.60 0.21000000./_inc/fonts/Roboto-Light.ttf0.026left01.6
```
The complete `theme.xml`, which is identical in each system folder:
```xml
4./../spare.xml./system.svg
```
## Tips and Tricks
### Keyboard Shortcuts in EmulationStation
When you start EmulationStation with the debug flag on the command line, you have these keyboard combos available (to be used with _left_ ++ctrl++):
- ++ctrl+r++: Reload all UI views (system carousel and in-system view)
- ++ctrl+i++: Toggle visibility the image components (``) boundary boxes
- ++ctrl+t++: Toggle visibility the text component (``) boundary boxes
- ++ctrl+g++: Toggle visibility Gridlayout boundary boxes (if you develop a theme for grid layout)
### The Size Element for Text Components
The `` element takes a pair of values. However, depending on the values of the pair you may also control the layout of the text element. This section will illustrate the different values and their impact on the layout.
As you may have already noticed the size element takes percent values of the actual screen size for _images_. For the layout of _text components_ with a given , additionally the selected font (its [Glyphs](https://en.wikipedia.org/wiki/Glyph)), the `` and the defined `` are factors for the layout. The last two values are also expected to be percent values. The glyph values are calculated by ES depending on the `` the theme has defined.
The pair of values is referenced as `width` (x-value) and `height` (y-value) e.g., `width height`.
The actual height of one line of text (`lineHeight`) is calculated by the `height` times the `lineSpacing` [times the largest height of the glyphs](https://github.com/RetroPie/EmulationStation/blob/9afa234f3c779ca23f832141f819886a984c1ee6/es-core/src/resources/Font.cpp#L476) times `fontSize`.
For your information: The images are taken from the [Epic Noir](https://github.com/c64-dev/es-theme-epicnoir) theme on a 5:4 display (1280x1024), cropped for this tutorial.
#### Case 1: Overly Large Size
Case 1: Text bounding box height greater than wrapped text height
This shows the theme layout as-is when you check it out from GitHub. Notice how the "Games Available" bounding box (bbox) and the bbox of the text below overlap (the latter is named long description or `longdescription`). However, the texts do not overlap coincidentally as the bbox for the long description is large enough, and the text is put in the middle of the text bbox by default (instead of top or bottom vertical alignment).
This is the respective section in the theme file. Note line #8 and #21 (using same position) and #22 (size of long description):
```xml title="Part of es-theme-epicnoir/themes.xml" linenums="1" hl_lines="8 21 22"
./_art/Acre.otfleft000000001A3332D0 00.12 0.36110 0.0390.0315./_art/Acre.otfleft00.0218F8F8F1.180 00.12 0.3600.28 0.20
```
**Tip**
> All elements with fractions represent percentage values from 0.0 to 1.0. `` and `` may also use values greater than 1.0 (100%). You may use absolute pixel values for some elements, but you have to use the [``](https://github.com/RetroPie/EmulationStation/blob/master/THEMES.md#the-resolution-tag) element for this.
**Takeaway #1**: If the size is large enough, more precisely the `width` is greater than zero and the `height` is greater than the sum of the `lineHeight`s used for the wrapped text it is wrapped and vertically aligned middle.
#### Case 2: Zero Width
Case 2: Text bounding box defines width equal to zero and any height value
The `width` zero definition in XML (note line #10):
```xml linenums="1" hl_lines="10"
./_art/Acre.otfleft00.0218F8F8F1.180 00.12 0.4150 0.20
```
**Note**
> The `` element (line #9) has been adapted from the original value to not clash with the bbox of "Games Available".
**Takeaway #2**: If the `width` of the size is zero, the text will be put on one line and not abbreviated. As the `height` is not interpreted in this case the bbox `height` is set to one `lineHeight` by ES, and the `height` value from the XML file is ignored. The text after the first newline character is cut off. It is not shown in the screenshot, but this cut-off is [implemented in ES](https://github.com/RetroPie/EmulationStation/blob/9afa234f3c779ca23f832141f819886a984c1ee6/es-core/src/components/TextComponent.cpp#L194).
#### Case 3: Zero Height
Case 3: Text bounding box defines width greater zero and height equal to zero
Example from the theme file:
```xml linenums="1" hl_lines="10"
./_art/Acre.otfleft00.0218F8F8F1.180 00.12 0.4150.28 0
```
**Takeaway #3**: If the `height` is zero the text is wrapped to not exceed the line width, the bbox grows downwards (if needed) while `pos` stays fixed. The actual line width is the product of the font's glyphs, `fontSize` and the display's x-resolution.
**Tip: Preferred approach**
> This (`height` = 0) makes the intention of the theme layout clear to other users. If you want wrapped multiline text choose this approach.
#### Case 4: Force Abbreviation
Case 4: Text bounding box defines width greater zero, and height greater than zero and less than or equal to one lineHeight
This sample in the XML definition (note the small `height` value in line #10):
```xml linenums="1" hl_lines="10"
./_art/Acre.otfleft00.0218F8F8F1.180 00.12 0.4150.28 0.022
```
**Takeaway #4**: When the `height` _evaluates_ (remember how the line height is calculated) to be less than or equal to one `lineHeight` the text will be abbreviated with ellipsis to fit into the width of the bbox. Additionally, text after a newline character is cut off before abbreviated, if this shortened text fits into one line no ellipsis is added. It can not be shown in a screenshot, but this behavior is implemented in ES.
#### Case 5: Too Small Height
Case 5: Text bounding box defines width greater zero, and height greater than one lineHeight but less than the sum of line heights of the wrapped text
Representation in XML (the `height` value in line #10 represents a little more than one line height):
```xml linenums="1" hl_lines="10"
./_art/Acre.otfleft00.0218F8F8F1.180 00.12 0.4150.28 0.045
```
**Takeaway #5**: The result is the same as in case 1 or case 3, but is more difficult to grasp when maintaining the theme and may result in unwanted layouts, as the `size` _suggest_ the specific text for that element will fit into size when wrapped. Better use either `height` of zero or define a `height` with enough space for the longest text so that the bbox will not grow downwards on texts that exceed the height.
## Closing
Congratulations to those that made it this far. It's been a heck of a journey. You now have everything you need to make your own themes. Feel free after you have gained confidence with creating a theme to pay the RetroPie project forward by amending to this guide. For more sophisticated questions be invited to place your question in the [forum](https://retropie.org.uk/forum/category/9/projects-and-themes).
## References
- Themes Documentation by original ES author: [The ES Themes Reference Documentation](https://github.com/RetroPie/EmulationStation/blob/master/THEMES.md#the-resolution-tag)
- The Spare theme on GitHub: [es-theme-spare](https://github.com/mattrixk/es-theme-spare)
- Another theme from the original contributor of this tutorial: [MetaPixel](https://github.com/mattrixk/es-theme-metapixel)
- The full album of images used in this tutorial: [Imgur](https://imgur.com/a/LjRZk)
- Fake games Zip archive from this DropBox: [fake_games.zip](https://dl.dropboxusercontent.com/u/14838442/fake-games.zip)
- Portable EmulationStation by @herb_fargus: [EmulationStation Windows Portable (USB Stick)](https://www.youtube.com/watch?v=oHtCnBiyzOY), [Download the file](https://drive.google.com/file/d/0B2TMeZ6iEFvHYkNrMGVQSldkZ0U/view?usp=sharing)
- The ES Theme Helper by @Rookervik: [DropBox](https://dl.dropboxusercontent.com/u/60872572/EmulationStation/ES%20Theme%20Helper3.rar)
- RetroPie EmulationStation Themes Showcase: [ES Themes Showcase](Themes.md)
- A generic tutorial on how to convert a raster image to vector image: