Modding GearHead Caramel: How to Make Portrait Bits

Now that GearHead Caramel is in a properly playable state, I thought I should start explaining how it works. Unlike previous GearHead games, Caramel uses a portrait generator that assembles characters from component parts. Each portrait bit can be anchored to a particular spot on the portrait, can contain multiple images, and each of those images can be placed at different depths. Also, while the portrait is being constructed, a matching 64×64 pixel avatar is also built.

That’s a lot of information to dump at once, so let’s look at a specific example: por_hair_halftail.png.

This hairstyle comes in three parts. The first goes on top of the head, in front of any facial features. The second goes on top of the head but behind the ear. The third goes behind the head and the body. You will also notice that the hair is colored pure green (#000100 to #00FF00) and placed on a pure blue (#0000FF) background. Assembled, the hair looks like this:

Let’s start with the color. Most GearHead sprites come with five color channels: pure red, pure yellow, pure green, pure cyan, and pure magenta. For characters, these channels correspond to clothing, skin, hair, metal, and accent color, respectively. The pure colors are used by the color switcher to decide what color each pixel should be in the final portrait.

The easiest way to get the color channels right is to first draw your sprite in black and white, then color it using a multiply layer on top. This can be done in Gimp, Photoshop, and probably whatever graphics program you use unless it’s MS Paint. Use #FF0000, #FFFF00, #00FF00, #00FFFF, and #FF00FF as your colors on the multiply layer.

Next question: How do we tell GearHead Caramel about the new portrait bit? For that, we turn to JSON. Inside the image folder there are a bunch of portrait definition files. Here’s the portrait definition for the hairstyle shown above:

Each portrait bit needs a unique name. The bit type tells the portrait generator when to use this bit; in this case, the type is “hair”, so this bit may be used whenever the portrait requests hair. Next you see definitions for each of the layers giving the image filename, anchor, offsets, depth, and frame information. After that, there’s layer information for the 64x64px avatar. The avatar layers have the same format as the portrait layers. Finally, there is a style tag. This particular hairstyle will normally only be chosen for a character with the “Feminine” tag, but you can disable style tags in the character creator and give this hairstyle to anyone you want.

I have uploaded my portrait work files and JSON definition files to Google Drive, so you can play around with them without needing to download the source code. You can place new portrait bits and JSON files in the image subfolder of your user folder (which should be “ghcaramel/” in your home directory). Please let me know if you have any questions.