Repository files navigation

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 oneOKColor class and a bunch of methods providingsetting the color,models conversion,mixing andgetting the color for rendering.

Navigate toInstallation andHow to use.

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 notlook like these rules were followed.

For example, if two colors only differ inhue, they won't be consistent for our eyes and seems like they also have differentsaturation/value, despite having the same ones in the code. Thehue 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, whereL representslightness as the loose analogue ofvalue,C is thechroma which is equal tosaturation andH as in thehue.

Here is an example of a gradient generated with HSV model, all colors have the samesaturation andvalue and showing all the possiblehue:

And here is another one, generated with theperceptually uniform OKLCH model with the samelightness andchroma and differenthue 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:

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

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 basichue shift in the HSV space. Another option is to use the OKLCH model and apply ahue 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 samehue 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 increasingvalue).

Otherwise, if instead youneed 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 thevalue drops by 10% for every next color to make it darker):

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

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.

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/

Perceptual models can be also beneficial when generating gradients or blending colors gradually over time. GameMaker'smerge_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.

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.

Copy theOKColor script into your project.
Or get the latest asset package from thereleases page and import it into IDE.

The basic using is pretty simple and straightforward. To create a new color, use theOKColor constructor to create a new instance and set the color with a wide choice ofsetter methods.

varokcolor=newOKColor().setColor(#3f97d8);

Method chaining and optional arguments for setting components separately are also supported so you can do:

varokcolor=newOKColor().setColor(#3f97d8).setOKLCH(,,120);

You can convert colors to other model withgetter functions:

varhsv=okcolor.getHSV();show_debug_message($"hue: {hsv.h}, saturation: {hsv.s}, value: {hsv.v}");

Mixing colors works likemerge_color /lerp:

varokcolor1=newOKColor().setColor(#3f97d8).setOKLCH(,,120);varokcolor2=newOKColor().setRGB(242,42,133);okcolor1.mix(okcolor2,0.5);

To get color for rendering you should usecolor getter methods:

varokcolor=newOKColor().setColor(#3f97d8).setOKLCH(,,120);draw_set_color(okcolor.color());

The library is bothFeather andGMEdit-friendly, with typing and hints.
For deep info on extended functionality about setters, getters, mixing, gamut mapping, and other check out the next section.

• API Reference
  • Setters
  • Getters
  • Color Getters
  • Gamut Mapping
  • Mixing
  • Cloning
• Architecture
• How to contribute

• "Missing" color components
  • Useful for propercolor mixing.
  • Treat as 0 outside of mixing purposes.
  • UseNaN (powerless) as a missing component?
• “Powerless” color components
  • Basically the color components that are not contributing to the resulting rendered color, likehue in HSV, when thesaturation is 0: no matter what hue angle is, the resulting color will be grey.
  • Already implemented as NaN forhue in HSV/HSL implementations, should probably be extended tolightness cases and LCH models.
  • Combine with "missing" as the same thing?
• Alpha and premultiplied alpha
  • More sensible color mixing withalpha interpolation.
• Linear RGB color mixing
• Hue/Chroma interpolation for color mixing?
  • Not sure if it is needed as Lab and OKLab models provide the subjectively best-looking mixing and LCH to my understanding should give the same results as Lab, but may be useful for someone.
• Wider color gamuts like P3 and Rec.2020?
  • For now, the only supported color space used inmapping the colors for the rendering is sRGB. With the introduction of a wider rangesurface formats in GameMaker it's probably possible now to render colors outside of 0-1 sRGB gamut on HDR monitors and this feature might be useful. Even without that, it still can be useful for passing a wider range colors in surface buffers for the sake of HDR lighting and rendering.
• More white points than D65?
  • D50 white point for XYZ for better consistency?
• HWB color model?
• Shader function equivalents of generating and mixing colors?

Nikita Musatov -MusNik / KeeVee Games

Sitnik, A. and Turner, T. (2022) "OKLCH in CSS: why we moved from RGB and HSL"
Ottosson, Björn (2020) "A perceptual color space for image processing"
Ottosson, Björn (2020) "How software gets color wrong"
Ottosson, Björn (2021) "sRGB gamut clipping"
Cereda, M., Plutino, A. and Rizzi A. (2021) "Quick Gamut mapping for simplified color correction", University of Milan
Morovič, Ján (2008) "Color gamut mapping", Chapter 10, John Wiley & Sons
Schanda, J. (2007) "Colorimetry: understanding the CIE system", Chapter 3, John Wiley & Sons
Fairchild, Mark D. (2013) "Color Appearance Models, John Wiley & Sons
Verou, Lea and Lilley, Chris (2023) "Color.js"
Atkins Jr., T., Lilley, C., Verou, L., and Baron, D. (2021) "CSS Color Module Level 4", W3C
Lilley, C., Kravets, U., Verou, L., and Argyle, A. (2022) "CSS Color Module Level 5", W3C
Levien, Raph (2021) "An interactive review of Oklab"