A set of colors with standard names that you can use throughout your game to have a consistent look and feel.

If you set up a theme for your game, you have those colors available through predefined named macros and as scribble colors with the same name.

Because this is the most easy way to ensure a consistent set of colors through your entire game, for all dialogs.

Instead of using RGB (or BGR) values in your scribble texts, just use named colors, so you can change a color in the entire game by simply adapting one single rgb value in the theme. I have seen so many developers struggle with text colors, where they had epic "search & replace" sessions in .json files, the source code, even in the serverside database of their game, just to get one single color exchanged.

Use themes, create a SPOT (Single Point of Truth), also called SSOT (Single Source of Truth) for your coloring!

You can access each color of the active theme through global #macros (the very left column in the table below). Due to the fact, that behind these macros, global variables are defined, you can even use these names in the variable definitions of your objects (in fact, all the raptor UI controls do exactly that to align with the current theme).

If you do not set any theme, there's always the default theme (or global theme, if you prefer) active in your game. In the Example Project, theming is demonstrated. You can switch there between two themes in the demo.

These colors define your theme, the default RGB values shown are raptor's default theme colors:

Color name	Default RGB	Description
APP_THEME_MAIN	#4080FF	The main color of your theme, the main CI (corporate identity) color
APP_THEME_BRIGHT	#60AAFF	A brighter version of the main color
APP_THEME_DARK	#3060DD	A darker version of the main color
APP_THEME_ACCENT	#8080FF	An accent color (mostly a bit brighter than main, if you want to highlight something in your text)
APP_THEME_WHITE	#FAFAFA	The color to use for white
APP_THEME_BLACK	#070707	The color to use for black
APP_THEME_SHADOW	#808080	Shadow color

One instance of this class is created at game startup for you. You can reach it through the global UI_THEMES macro.
It is used to manage all known themes and offers methods to switch, add, remove or get a theme reference.

/// @function add_theme(_theme, _activate_now = false)
/// @description Add a theme to the manager. If a theme with the same name already exists,
///              it is overwritten.

/// @function activate_theme(_theme_name)
/// @description Activate a registered theme. Requires room_restart.

/// @function remove_theme(_theme_name)
/// @description Delete a registered theme.

/// @function get_theme(_theme_name)
/// @description Access a registered theme through its name.

You have seen the APP_THEME_* macros above, which let you access the predefined colors directly.
In addition to them, there is also an APP_THEME macro available, which points to the instance of the active theme. So you can access any custom added colors of the active theme through APP_THEME.your_color. This also works in variable definitions of your objects (see the last chapter at the bottom of this page).

As you can see in the DefaultTheme you received with the project template in the _gml_raptor_ui_/themes folder, this is a simple, straightforward class, which just holds some color values:

function DefaultTheme() : UiTheme("default") constructor {

	main	= CI_GLOBAL_MAIN;
	bright	= CI_GLOBAL_BRIGHT;
	dark	= CI_GLOBAL_DARK;
	accent	= CI_GLOBAL_ACCENT;

	white	= CI_GLOBAL_WHITE;
	black	= CI_GLOBAL_BLACK;
	shadow	= CI_GLOBAL_SHADOW;

}

However, if you prefer to set your colors through method calls instead of assigning variables, it also offers two methods:

/// @function set_colors(_main, _bright, _dark, _accent)
/// @description Set the four "colorful" values of a theme in one go.

/// @function set_grayscales(_white, _black, _shadow)
/// @description Set the three "grayscale" values of a theme in one go.

As mentioned above, one theme is delivered to you with the project template as the default theme of raptor.

As the UiTheme class is a simple code class, you are free to create any additional color values in a theme.
However, keep in mind, that for each color, there's also a global variable defined (the APP_THEME_* colors mentioned at the top of this page), so to fully integrate additional colors, you should also defined those variables for your new colors, to have them integrated seamlessly into your game's code.

When you look at the default values of the variable definitions of a control, you can see, that the APP_THEME_* macros are used a lot here to settle default colors on controls.

Here is a small example:

This means, GameMaker is capable of interpreting at least macro definitions in variables of type "Colour". This means, we can use our extended colors in these variable definitions, too.

Even without defining a new global variable for it, because the UiThemeManager also offers this global macro for us: APP_THEME, which is a reference to the theme instance, that is currently active!
So, even if we don't want to create a global macro + variable for each extended color, it is still usable here!

This image is taken from a game of mine:

The theme (at least a part of it, to keep the text smaller here), looks like this:

function DigiTheme() : DefaultTheme() constructor {

	btn_dark = #CCCCCC; // button, when no mouse is over (for color anim)
	
	accent = #FFD800;

}

I simply derived from the DefaultTheme() (which keeps the name "default" and overwrites the raptor-default, which is ok in this game, as it uses only one single UiTheme), and there I just add a new color, btn_dark and I also overwrite the accent color of the default theme with some yellow-ish value.

And this btn_dark can be used now to change variable definitions!

I hope, this little trick helped you even more to see, how powerful, but still on the SPOT, themes are!