UI Themes

What is a UI-Theme?

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.

Why should I use it?

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!

Colors of a theme

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 several 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
Your CI colors
THEME_MAIN	#6969E5	The main color of your theme, the main CI (corporate identity) color
THEME_BRIGHT	#8787FF	A brighter version of the main color
THEME_DARK	#4B4BA5	A darker version of the main color
THEME_ACCENT	#AA11FF	An accent color (mostly a bit brighter than main, if you want to highlight something in your text)
Greyscales
THEME_WHITE	#FAFAFA	The color to use for white
THEME_BLACK	#070707	The color to use for black
THEME_SHADOW	#808080	Shadow color
UI controls
THEME_CONTROL_DARK	#A0A0A0	Dark control color
THEME_CONTROL_BACK	#C0C0C0	Control background color
THEME_CONTROL_BRIGHT	#E0E0E0	Light control color
THEME_CONTROL_TEXT	#070707	Text color
THEME_WINDOW_BACK	#FAFAFA	Window background color
THEME_WINDOW_FOCUS	#4080FF	Window focus border

The UiThemeManager

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.

UiThemeManager functions

/// @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.

Access the currently active theme

You have seen the THEME_* macros above, which let you access the predefined colors directly.
In addition to them, there is also an 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 THEME.your_color. This also works in variable definitions of your objects (see the last chapter at the bottom of this page).

The UiTheme class

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(_name = "default") : UiTheme(_name) constructor {

	// "Your" colors
	main		= CI_GLOBAL_MAIN;
	bright		= CI_GLOBAL_BRIGHT;
	dark		= CI_GLOBAL_DARK;
	accent		= CI_GLOBAL_ACCENT;

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

	// UI controls
	control_back	= CI_GLOBAL_CONTROL_BACK;
	control_dark	= CI_GLOBAL_CONTROL_DARK;
	control_bright	= CI_GLOBAL_CONTROL_BRIGHT;
	control_text	= CI_GLOBAL_CONTROL_TEXT;
	window_back	= CI_GLOBAL_WINDOW_BACK;
	window_focus	= CI_GLOBAL_WINDOW_FOCUS;

}

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

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

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

/// @function set_control_colors(_control_back, _dark, _bright, _text, _window_back, _window_focus)
/// @description Set the "ui controls" values of a theme in one go.
static set_control_colors = function(_control_back, _dark, _bright, _text, _window_back, _window_focus) {

The DefaultTheme

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

Caution

DO NOT DELETE THIS THEME.
It used by raptor core on game start to initialize the first theme, as there must always be an active theme in the game!
You may adapt all the values, or create your own theme, but do not delete the default theme!

Extending themes with new colors

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 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.

Using extended colors for object variable definitions

When you look at the default values of the variable definitions of a control, you can see, that the 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: 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!