⚠️ Warning: Tutorial still under construction ⚠️
This will need some major proofreading. Most of the content is copied from the gba4ios tutorial, some of it is edited to my own knowledge of the updated skin system. It also lacks any specifics for the iPad compatible skins, I figured it would be better to add that once its actually implemented.
Delta Custom Skins
Delta Emulator Controllers were designed with the purpose of allowing custom skins to be produced. This allows anyone to create their own skins that may or may not resemble a controller and map the button presses however they want. Please read on if you are interested in making your own skin, or just want to know how custom skins work.
All delta skins are contained in .deltaskin files like Standard.deltaskin for example. These are actually just .zip files with the extension renamed. So if you if change the extension name back to .zip you can now access the files contained within. These files should include images of different sizes and orientations and a the info.json file.
The info.json contains all the necessary information for a skin to function, excluding the images. This information includes:
- Image Names
- Button Mappings
- Whether landscape supports opacity
- Whether the skin should be displayed in debug mode
(Don’t worry if you’re already confused, all of these will be explained further in this tutorial.)
As you can tell from the extension, this file is a JSON file. Although JSON files are primarily used by web services to transfer data, it was chosen to be used in Delta skin files due to its simplicity. Everything in this tutorial can be done via the included text editor on your computer, but it's strongly recommended you use an application designed to open and edit JSON files, as this is much less error-prone (and easy!). If you're using a Mac, Cocoa JSON Editor is what is used to make the JSON files for the included skins, but any other JSON editor will work fine.
Open up the info.json file and you should see these five items.
In this section, we’ll focus on the first 4.
This item is rather self-explanatory, this is what the skin will be called within Delta’s skin selection menu. Replace the name with whatever you would like to name your skin.
This is how Delta internally uses and stores skin files. To ensure that one skin doesn't overwrite another skin, each skin identifier should be unique. For example, the default Delta skins have the identifier com.Delta.gba.standard.
This is how Delta further determines the compatibility of each skin and identifies it. Similar to the identifier, the goal is for each gameTypeIndentifier to be unique. Apple recommends using the reverse-DNS format (com.[designer name].[skin name]) when making an app identifier, so we recommend a similar format for skin identifiers. For example, the default Delta skins have the gameTypeIdentifier com.rileytestut.Delta.game.gba.
This determines whether the skin should be displayed in “debug mode.” By default this is set to false, but when set to true, Delta will overlay red squares on top of where the buttons are mapped to. It’s recommended that you set this to true while making your skin, so that the buttons can nicely match up with the image.
Almost every time you create or modify a skin, you'll be changing the images that are displayed when actually using the skin. Luckily, changing the images is rather straightforward!
Delta detects what orientations are supported in a skin by the presence of the portrait and landscape items in the info.json file. If you wanted to have a portrait-only skin, you'd need to delete the landscape item; similarly, if you wanted to have a landscape-only skin, you'd need to delete the portrait item. Of course, if you wanted to support both orientations, you don't need to delete either.
It is suggested that you close all brackets (using the arrows found on the left side of the JSON editor) for the purpose of readability.
On the info.json file, contained within “representations,” open up the device (iPad/iPhone) of your choice and the orientation of your choice (typically by clicking an arrow to the left of the name). Once opened up, you'll see three new items:
For the purposes of this section, we will only focus on the assets and translucent items.
You can determine whether the orientation you're editing should support Delta's customizable opacity feature. Typically, only landscape skins that go on top of the game screen support this feature, but there's nothing stopping you from enabling it on other types of skins, or even disabling it for your own landscape overlay skin. To enable this feature, set the value to true. If you want to disable this feature, set it to false.
assets (needs updated information)
The assets section is used to load the controller skin images. It should be in this format "resizable" : "name_of_file" In the standard skins it looks like this "resizable" : "iphone_landscape.pdf" and we strongly recommend that you name your images in a similar naming convention. But you can change the names of your images to anything you want so long as each one is unique and your info.json file reflects that name.
If all you want to do is change the images of an existing skin or one of the "default" templates, at this point you have all the necessary pieces to make your skin, and can skip to the Finishing the Skin section below to learn how to turn these files into an actual .deltaskin file. However, if you want to customize the button mapping for your skins, carry on into the next section, Mapping Buttons.
Congratulations, if you have gotten this far in the tutorial, you know enough to make simple modifications of how a skin looks. However, skins offer more than just the ability to switch out images; they also give you full control over exactly where the buttons should go, how big they should be, and also where the game screen itself should be placed. Combining all of these, you can create very unique (read: strange) layouts for your skins, or maybe just make the game screen a bit smaller when in landscape mode. The point is, skins were designed to be flexible, and this section will show you just how to take advantage of everything!
Now, let's take a look at the format of how each button is mapped. Open any button up, and you should see four or five items:
- extendedEdges (certain button mappings in the default skins may not have this)
The first four items define the exact location of the button in the image in pixels, with no padding around it. The extendedEdges item is something special that we use to add padding around the buttons to increase the touch area, but we'll look at that later.
Everything on each skin is mapped in points. On regular displays one point is one pixel but on retina displays, one point is actually four pixels; two pixels wide and two pixels tall. So even though the iPhone image is 640 x 480 pixels, everything should be mapped as if it were 320 x 240.
NOTE: All types of screens are retina except for the iPhone X which has a Super Retina display. So, if you're mapping anything other than an iPhone X image, it's recommended that you copy the image, downsize it to half its original width and height, and then map it.
Exactly how you find the location and size of the skin buttons may vary, but all Delta skins were mapped by downsizing images to non-retina sizes, opening them in Photoshop, and using a combination of masks and the Info window to find the exact pixel locations of each button. Once you find the required information, you can fill in the button mappings for each button ( x and y refer to the x and y co-ordinates of the top left of the button location).
Just so you know what each button does, they're each listed individually below. Some have (slightly) different mapping requirements than others, so make sure to read them all!
The plus-button-like control usually located on the left side of the skin. Typically, it controls movement in games. Unlike other controls, this control is actually divided up into nine sections: eight control directions, and a center neutral section. However, there aren't nine separate mappings for each section; there's only one for the entire D-Pad. So how does Delta know how to divide up the D-Pad into different sections? Simple, it just divides the button mapping you give it into three equal sections horizontally and three equal sections vertically. Because of this, it is very important that you map the D-Pad exactly as it appears on the skin, and with no extra padding, or else the directions will not exactly match what the user sees. To properly add padding without messing up the mapping, you can take advantage of the extendedEdges property, which will be explained in more detail below.
The A button. Typically, this is used to select or confirm options in the game. It is considered the primary button.
The B button. Typically, this is used to cancel or perform secondary functions in the game.
Some skins may have an AB button. When pressed, this button actually presses both the A and B buttons at once, which can be useful for certain games. Including it is the designers choice.
The Start button. Typically, this pauses the game.
The Select button. Typically, this performs a secondary function in the game.
The L button. Because Game Boys / Game Boy Colors don't have an L button, it's strongly recommended that you delete it from your GBC skin, or else you may confuse the user when they feel a vibration by tapping it and it doesn't do anything.
The R button. Because Game Boys / Game Boy Colors don't have an R button, it's strongly recommended that you delete it from your GBC skin, or else you may confuse the user when they feel a vibration by tapping it and it doesn't do anything.
While the Start button typically pauses the game, this pauses the entire emulator, and allows you to access features such as Save States, Cheat Codes and Fast Forward. As always, make sure to map it exactly without padding, since the pause menu that appears relies on the mapping to position itself next to the button on an iPad.
Some skins (typically landscape skins) may choose to position the game screen themselves, either to fit it in a hole designed for the screen in the image, or possibly just to change how big the game screen is.
In addition to the extendedEdges item in each button mapping, there is also a orientation-specific extendedEdges item. Each extendedEdges item consists of four sub-items: top, bottom, left, and right. These four items "extend" the edge of a button in that direction by whatever value it has been set to. For example, the A button may have a mapping of:
- x: 15
- y: 100
- width: 80
- height: 80
However, maybe the orientation-specific extendedEdges has a value of 10 in all directions. Now, the actual touch target of the A button would be:
- x: 5
- y: 90
- width: 100
- height: 100
This has two benefits:
- It is easier to map buttons, since all you need to worry about is mapping the exact location of the button, and adding the padding later.
- This allows padding to be added to the D-Pad and Menu button without messing up the internal calculations Delta uses for each button.
Another reason to use extendedEdges is to ensure the touch targets of buttons near the edges of the screen actually extend to the edge. This is very important, because if you don't do this, it's easy for the user to tap near the edge of the screen but not perform any action due to the touch targets not extending far enough. To make this an easy fix, each button mapping also has its own extendedEdges item, which will overwrite the orientation-specific version if you enter a value for it. For example, let's take the A button example above. With the orientation-specific extendedEdges, you may notice that it is only 5 points away from the left edge of the screen. To get the best experience out of using your skin, you should make sure it extends all the way to the left edge. To do this, open up the a button mapping, and then open up its own extendedEdges. Once that's opened, set left to 5, and save. Now, the touch target of the A button will be:
- x: 0
- y: 90
- width: 105
- height: 100
Good, it extends all the way to edge! Per-button extendedEdges can also be applied simply to tweak the extendedEdges of a button. For instance, typically Delta uses a global 7-point padding for every button on iPhones, but uses 15-points on the D-Pad, since the user is more likely to miss it due to moving their finger around more. Just remember, map all buttons exactly as they appear on the skin with no padding, and then use extendedEdges to add the padding later.
Finishing the Skin
At this point, you have everything you need to convert the files into a skin file you can start using in Delta! Now, the last thing to do is to actually import it into Delta, which thankfully is the easiest part.
Every .deltaskin file is just a zip file with the .zip extension renamed. That means, to turn your files into a skin file, all you need to do is compress all the individual files into one zip file and rename the extension .deltaskin. Something important to remember: because GBA skins have all the buttons required by GBC games, GBA skins can be used for both GBA and GBC games. However, because GBC skins lack L and R buttons, they can only be used for GBC games.
NOTE 1: When compressing the files, make sure to compress the files themselves, and not the containing folder. If you zip the folder and not the files directly, Delta will not extract the files correctly upon import, which will prevent the skin file from being used.
NOTE 2: When renaming the extension, make sure the extension actually changes. Sometimes, the file may look like its extension was changed, but the computer might have (invisibly) added the extension back on the end of the filename. On a Mac, the best way to ensure the extension changes properly is to right-click the file, click Get Info, and then change the extension there.
Once you have your .deltaskin file, you need to import it into Delta. If you're working at your computer, generally the easiest way to do this is via iTunes. To import via iTunes, you can follow these instructions:
- Connect your iOS device to your computer.
- Open iTunes.
- Click on your device that appears in the top right corner.
- Click the Apps tab near the top of the iTunes window.
- Scroll down to File Sharing.
- Click Delta, then drag the skin file into Delta Documents.
- Launch Delta on your device, open Settings, and select the new skin you imported.
If you don't want to transfer through iTunes, you can always send it to your device via Email, iMessage, or via downloading through a web server. Once you receive it on your device, Open In... Delta, and then you can select the newly imported skin in Delta’s settings.
Once you've imported your custom skin, the last step is to start a game of your choice, and start playing with your creation. Congrats, you worked hard for it!