---
tags: Guide, Frontend, Greyscale
---
# Follow along GAGS walkthrough

This guide assumes no previous knowledge of GAGS, though it is recommended that you understand the basics of adding new sprites to the game.

## Step 0: Choose your target
For your first project, if you don't know dm code that well, you should select an item that doesn't have any complex mechanics or sprite changes. For this guide we'll be using the sombrero and shamebrero. If you'd like to use them as well to more closely follow this guide, here they are in png form . Just download and rename the file extension to `.dmi`

## Step 1: Break it up
GAGS uses layers to generate complete sprites from multiple distinct partial sprites. To turn a normal sprite into one generated by GAGS you're going to want to identify the parts of the sprite to break into seperate layers. The sombrero and the shamebrero have basicaly the same look but the shamebrero has a bit extra so we'll focus on that one.


Two easy pieces of the shamebrero that are distinct from the rest are those black and white dangling bits, and the piece that looks like a plate of metal at the front. We're going to make some new icon states that have only these parts of the sprite so we can use them seperately in the generation process.

In some cases creative freedom may need to be taken advantage of in order to cleanly seperate things into layers, but don't worry too much about it in this step.



Now there's two remaining distinct parts of the sprite: The gold fringe and the main pink body of the hat. Let's get those into their own layers as well.



When looking at all the sprites you have now, it should look something like this:


## Step 2: Get something in game

At this point you could start on the work to take all the color out but we're going to set up the basics of GAGS so you can see your work in game. You don't actually need to use any greyscale sprites to make use of GAGS, just some sprite layers to put together and an item in game to use them. Let's put together the configuration needed now to take these layers and show a shamebrero to the player.

In your text editor of choice make a new json file in `code/datums/greyscale/json_configs`. For this project we'll use one called `sombrero.json`

{
    "shamebrero": [
        {
            "type": "icon_state",
            "icon_state": "cloth",
            "blend_mode": "overlay",
            "color_ids": [ 1 ]
        }
    ]
}

The first bit of text here is the icon state name that will be created. The output will contain an icon state with the name "shamebrero". The configuration inside that block has a single layer that loads the icon state called "cloth" and overlays it onto the result of the "shamebrero" icon state. As there's only one layer we're basicaly just going to display the "cloth" icon state from what we made before. This is fine for now.

For the next step we need to connect this json configuration with the dmi file we were working with before. The code for this is kept in the folder `code/datums/greyscale/config_types/` and is very simple. Just add something like the following to a new or existing file (don't forget to include any new files in `tgstation.dme`):

/datum/greyscale_config/shamebrero
    name = "Shamebrero"
    icon_file = 'icons/obj/clothing/head/sombrero.dmi'
    json_config = 'code/datums/greyscale/json_configs/sombrero.json'

Now for the final step! We need the shamebrero to actualy use all this configuration we've set up, so let's go to the type definition and make some minor changes there:

/obj/item/clothing/head/sombrero/shamebrero
    name = "shamebrero"
    icon_state = "shamebrero"
    inhand_icon_state = "shamebrero"
    desc = "Once it's on, it never comes off."
    dog_fashion = null
    greyscale_config = /datum/greyscale_config/shamebrero
    greyscale_colors = "#555555"

Those last two lines are what need to be added. Let's start it up and see what it looks like! Spawn it in annnd...


It looks like shit!

## Step 3: Debugging greyscale sprites

I hope you weren't surprised by the appearance at the end of the last step, after all it's only one of our layers getting colored grey, but it's a start and we can see it in game. Don't shut the game down now, we'll not have to recompile and restart until we need to add the worn and inhand sprites. There's a handy debug menu for reloading all the external files needed once you have the bare minimum like we have here implemented.

Go the the view variables menu for the hat you just spawned:


In the dropdown on the top right, there's a selection for greyscale debugging:


This opens up a menu that should look something like this:


Feel free to mess around with the menu here a bit. From top to bottom:

- The config section allows you to select a greyscale configuration to work with. For now we'll not need to touch this.
- The colors section allows you to specify what color arguments are given to the generation process, feel free to click the blue button to the left which allows you to more easily select colors.
- If you change the above values, you can click the apply button to assign them to the object this all started with, in this case the hat. The refresh button reloads all external files so that if you make changes outside the game you can load those changes in to an existing round.
- The preview section shows what the above options would look like. You can select a direction to preview and the images below show every step of the generation process. Each step creates the sprite on the left and applies it to the result, shown on the right.

Try changing the color to red!

## Step 4: Put it all back together

To get back together our original hat let's get the rest of the layers into the configuration. Don't shut the game down! As previously mentioned, you can reload the dmi and json config as much as you like without having to restart the game. Change the color in the debug menu to white to have the original colors get used.

So let's take a look at our sprites again:


Currently only the cloth layer is getting shown in game. This is because it's the only layer we've configured in the json configuration. Let's fix that real quick and duplicate the configuration for the cloth layer for the other three layers.

{
    "shamebrero": [
        {
            "type": "icon_state",
            "icon_state": "cloth",
            "blend_mode": "overlay",
            "color_ids": [ 1 ]
        },
        {
            "type": "icon_state",
            "icon_state": "ornamentation",
            "blend_mode": "overlay"
        },
        {
            "type": "icon_state",
            "icon_state": "plate",
            "blend_mode": "overlay"
        },
        {
            "type": "icon_state",
            "icon_state": "dongles",
            "blend_mode": "overlay"
        }
    ]
}

The color ids are optional, you just need at least one layer to be using it. We'll get to that later. The important thing here is that now every layer is loading a different icon state to be overlaid on the result. Save the file and we can get back to the game.

Back in the debug menu, click the refresh button and the rest of the hat layers will be displayed in the preview.


On the left are all the layers, you can see them get loaded in one at a time and get applied to the output on the right. Hit apply and it'll all get transferred to the hat on the map.


## Step 5: Extracting the colors

Now on to the real work, back in the sprite editor it's time to take out the color so that GAGS can apply the colors instead. The gold ornamentation seems the easiest so let's start there.


There's not much differentiation in the colors here but the left side is ever so slightly brighter than the right. We can capture that easily enough in the greyscale version. The default coloration replaces pure white with the color given and the darker grey you use the darker it will color whatever is given at the start. Make the few bits that are brightest here white...


Then color the rest just ever so slightly darker...


Save your results here and refresh the debug menu in game again. What used to be gold in the preview is now white. To make it colorable go to your json configuration and add a color id to the ornamentation layer:

        {
            "type": "icon_state",
            "icon_state": "ornamentation",
            "blend_mode": "overlay",
            "color_ids": [ 2 ]
        },

We use a different color id here so that we can color it differently than the main part of the hat. Refresh the debug menu once again and a new color option will appear.


Change the second color group to something you like and hit apply. The gold ornamentation gets recolored to your color of choice!


For reference, the original color was `#F8DB18`, you can put that in to the color text box directly and get the original gold ornamentation.

Now repeat all that for the main part of the hat. Leave the plate alone for now as we'll do a different kind of layer for that one. You'll need to mess around a lot with your choices of grey until it looks how you want but by the end you should get something like this:


Back in the debug menu again, refresh and choose a pink that gets you about what you want, and we once again have a normal looking shamebrero:


Now for the final colored layer, that metal plate looking bit at the front and center of the hat. It's too bright to just be some darkened pink like the rest of the hat but you know what it does look like? Some grey overtones applied over the pink. Easiest way to handle this is instead of making this a colored layer like the other two, have a partialy transparent grey plate that will go over the pink underneath.

However, you're going to need to go back and make adjustments to the cloth layer. Before now there was nothing there where the metal plate was, but we need something there now to be seen through the partialy transparent plate. Easy enough, pick a nearby light grey on the hat and bucket in the empty space.

You should end up with something like this after getting the colors as you like:




You now have a hat that can be colored any way you like!


## Step 6: Worn and inhand icons

This is where you're going to have to make some more code changes as we don't (yet) have something as simple as a few variable edits to change inhand and worn icons. The changes needed still aren't that big though. Let's start off with the worn icon's sprites.

Worn icons have four directions they need to be viewable from. Luckily for us the shamebrero is basicaly just the normal item icon but shifted up a bit to go on the head.


There's also that additional buckle there but nothing here too fancy. Copy over the worn icon from the appropriate file and put it into our new `sombrero.dmi` file that was created above. It can all be in the same file without issue as we can split it up in the json configuration step. Do the same things you did in the previous steps and your dmi file should look something like this:


Note: In this particular case, while the output worn icon needs to have four directions, only the ornamentation actualy needed to be adjusted based on the direction. As long as any of the sprites used in the generation process has multiple directions sprited, the output sprite will also be multi-directional.

The json configuration for the worn icon is basicaly the same thing as well:

{
    "shamebrero": [
        {
            "type": "icon_state",
            "icon_state": "cloth_worn",
            "blend_mode": "overlay",
            "color_ids": [ 1 ]
        },
        {
            "type": "icon_state",
            "icon_state": "ornamentation_worn",
            "blend_mode": "overlay",
            "color_ids": [ 2 ]
        },
        {
            "type": "icon_state",
            "icon_state": "plate_worn",
            "blend_mode": "overlay"
        },
        {
            "type": "icon_state",
            "icon_state": "dongles_worn",
            "blend_mode": "overlay"
        }
    ]
}

And finally the greyscale config type:

/datum/greyscale_config/shamebrero/worn
    json_config = 'code/datums/greyscale/json_configs/sombrero_worn.json'

Note: I was able to leave out the icon file definition because this is a subtype of the shamebrero config. They both use the same icon file so no change is needed there.

You should get it by now, do the same for the left and right hand sprites, those look a bit different. Once you've got the json config and code config set up, let's go back to look at the shamebrero type again.

Underneath where we changed the greyscale config on the type before we just need to add some additional values for the worn and inhand icons. The greyscale colors get reused so that all the sprites are colored the same.

/obj/item/clothing/head/sombrero
    ...
    greyscale_config_worn = /datum/greyscale_config/sombrero/worn
    greyscale_config_inhand_left = /datum/greyscale_config/sombrero/lefthand
    greyscale_config_inhand_right = /datum/greyscale_config/sombrero/righthand

Once you've got all that done, you can boot the game up and debug those worn and inhand sprites.


Horrendous multi colored hats for all!

You can see the end result of the changes done in this guide in [this pull request](https://github.com/tgstation/tgstation/pull/58854/files).