OKColor.gml

<img align="left" src="https://keevee.games/wp-content/uploads/2023/11/logo-300x300.png" alt="Logo" width="150">

OKColor is a color management library for GameMaker written in pure GML that implements the new "industry standard" OKLab/OKLCH perceptual models, among many others.

It's simple to use with only one OKColor class and a bunch of methods providing setting the color, models conversion, mixing and getting the color for rendering.

Navigate to Installation and How to use.

Why to use?

Premise

The problem with the standard RGB and HSV models is that they're not taking into consideration the human perception of the color. That means that if you follow the same rules to set the color components, the resulting colors might not look like these rules were followed.

For example, if two colors only differ in hue, they won't be consistent for our eyes and seems like they also have different saturation/value, despite having the same ones in the code. The hue itself is not perfect either: it distributes colors unevenly, so adding the same amount of hue to different colors won't make them "move" the same distance in the color wheel. To overcome these issues, there have been attempts to create a perceptually correct color model with the most recent one being the "OK" family of color models.

OKLab is the starting point of it and is inspired by a perceptual model called CIELab, fixing some of its flaws. OKLCH is another member of the family and just a representation of OKLab in a "cylindrical" form, meaning it has the same relation to OKLab as HSV has to RGB. So OKLCH is a better alternative to HSV, where L represents lightness as the loose analogue of value, C is the chroma which is equal to saturation and H as in the hue.

[!NOTE] Provided examples may read incorrectly if you have a badly calibrated display and or non-trichromatic color vision.

Here is an example of a gradient generated with HSV model, all colors have the same saturation and value and showing all the possible hue:

And here is another one, generated with the perceptually uniform OKLCH model with the same lightness and chroma and different hue giving more consistent color, reflecting how human vision works:

Notice how there are differences in lightness for different hues in the top one and how the hue itself is distributed unevenly.

Converting both examples to perceptual grayscale shows the lightness flaws more obviously:

Generating new colors

Usually, the choice of specific colors in the game is made manually by the game artists or art directors. However, there are some cases where colors need to be generated dynamically. This could be due to the specifics of a particular visual effect, a large number of assets requiring recolor or user-inputted customization. So, if you're generating color palettes for your game in-code and need consistent and predictable outcomes you should consider using this library with OKLCH color model instead of standard make_color_rgb and make_color_hsv.

[!NOTE] You can use this OKLCH color picker to choose reference colors: oklch.com. Uncheck "Show P3" colors too see only sRGB colors that GameMaker rendering supports.

Consistent matching colors

Let's say you want to recolor specific features of your character sprite in-game. One way is to generate a new palette using a basic hue shift in the HSV space. Another option is to use the OKLCH model and apply a hue shift there. This latter approach often provides more appealing results:

With OKLCH the lightness is consistent throughout all the hue changes, shadows and highlights remain intact, and the overall visual is enhanced. This extends to other components: you can be sure that colors with the same hue will have the same perceptual hue, unlike HSV which tends to shift it when brightness is changed (for example making blue become more purple when increasing value).

Predictable different colors

Otherwise, if instead you need the difference in color qualities such as for better accessibility, a perceptual color model is also beneficial.

For example, you want to color-code different collectables: blue one is standard, green is lighter and red is darker to make it easier for subconscious distinction and more accessible for color-blind people. You can generate the colors in HSV (note how the value drops by 10% for every next color to make it darker):

| HSV | hue | saturation | value | | - | - | - | - | | green | 120 | 80% | 90% | | blue | 180 | 80% | 80% | | red | 0 | 80% | 70% |

You can also generate three colors with OKLCH in a similar way (lightness is also decreased by 10% each time):

| OKLCH | lightness | chroma | hue | | - | - | - | - | | green | 75% | 0.18 | 142 | | blue | 65% | 0.18 | 202 | | red | 55% | 0.18 | 27 |

And apply these colors to a collectable sprite:

 

Testing would reveal that HSV results are not predictable: with the red appearing much darker than intended, and green and blue seemingly having similar brightness. OKLCH, on the other hand, provides more consistent and reasonable results, with each subsequent color being equally darker than the previous one, complementing the 10% change.

Palettes for GUI

Aside from actual gameplay graphics, OKLCH is valuable for generating colors for elements initially colored in code, such as text and GUI elements. It's not without reason that this model is emerging as a new standard for CSS. With it, you can define a formula, choose a few colors, and automatically generate an entire design system palette.

You can learn more on that here:
https://stripe.com/blog/accessible-color-systems
https://huetone.ardov.me/

Mixing the colors

Perceptual models can be also beneficial when generating gradients or blending colors gradually over time. GameMaker's merge_color uses RGB model to mix colors and may suffer from the same disadvantages of unpredictable color qualities, non-linear distribution and component shifts. OKColor offers additional methods for mixing colors perceptually using Lab and OKLab models.

[!IMPORTANT] Color mixing is a peculiar case. While it's almost universally better to use the advanced OKLab/OKLCH model for generating new colors, blending colors can perform better with a simpler Lab/LCH model or even the standard RGB for certain requirements. Make your decision based on tests with your specific colors and/or provided examples.

Here are some examples of gradients created in RGB, OKLab and Lab:

 

Take a look at how RGB produces ugly grayish colors in the middle, whereas perceptual models yield more consistent results. The Lab variant can also provide a bit more saturation.

 

When dealing with colors that are fairly distant from each other on the hue wheel, Lab introduces a hue shift that is not present in OKLab. However, you can use it if it aligns with your requirements for mixing while moving along the hue.

 

Gradients that transition to white exhibit significant hue shifts for some colors in RGB and Lab models, as shown in this example, which is usually unnecessary. In such cases, OKLab should be preferred. The black and white variant also highlights the difference in the linear distribution of OKLab and the non-linearity of RGB and Lab.

Installation

Copy the [OKColor](https://github.com/KeeVeeGames/OKColor.gml/blob/main/OKColor/scripts/OKColor/OKColo