Colors

Mira API lets you register custom player colors that appear in the color selection screen alongside the vanilla colors.

Creating Custom Colors

Create a static class decorated with [RegisterCustomColors]. Each CustomColor or VariableColor property in the class is automatically discovered and registered.

[RegisterCustomColors]
public static class ExampleColors
{
    public static CustomColor Cerulean { get; } = new("Cerulean", new Color(0.0f, 0.48f, 0.65f))
    {
        ColorBrightness = CustomColorBrightness.Lighter,
    };

    public static CustomColor Rose { get; } = new("Rose", new Color(0.98f, 0.26f, 0.62f));

    public static CustomColor Gold { get; } = new("Gold", new Color(1.0f, 0.84f, 0.0f));

    public static VariableColor Rainbow { get; } = new("Rainbow", t => new HsbColor(MathUtilities.PingPong(t, 1f, 0.3f), 1f, 1f))
    {
        ColorBrightness = CustomColorBrightness.Lighter,
    };
}

CustomColor

CustomColor represents a single player color with a main color, a shadow color used for shading on the player body, a name, and an optional brightness hint.

Constructors

Constructor	Description
new CustomColor(StringNames name, Color32 main, Color32 shadow)	Full control over name, main color, and shadow color.
new CustomColor(StringNames name, Color32 main)	Shadow color is auto-generated by darkening main by 60 units per channel.
new CustomColor(string name, Color32 main, Color32 shadow)	Same as the first overload, but takes a plain string for the name (registered automatically as a StringNames).
new CustomColor(string name, Color32 main)	Same as the second overload, but takes a plain string name.

Properties

Property	Type	Default	Description
Name	StringNames	Set by constructor	The localization key for the color name shown in the color picker.
MainColor	Color32	Set by constructor	The primary color applied to the player body.
ShadowColor	Color32	Set by constructor or auto-derived from MainColor	The shadow/shading color on the player body.
ColorBrightness	CustomColorBrightness	Darker	A hint used for accessibility. Lighter or Darker.

VariableColor

VariableColor inherits from CustomColor and represents a dynamic custom color that changes over time. It uses evaluation delegates to shift colors dynamically while retaining static fallback colors for users who have disabled variable color settings.

Constructors

Constructor	Description
new VariableColor(StringNames name, Func<float, Color> mainEvaluator, Func<float, Color>? shadowEvaluator, Color32? mainColor = null, Color32? shadowColor = null, float defaultTime = 0f)	Full control over the name, time-based main/shadow evaluators, and static fallback colors. If static fallback colors are not provided, they default to the results of the evaluators at the provided defaultTime.
new VariableColor(StringNames name, Func<float, Color> mainEvaluator, Color32? mainColor = null, float defaultTime = 0f)	The shadow evaluator is auto-generated by darkening the result of mainEvaluator by 24%.
new VariableColor(string name, Func<float, Color> mainEvaluator, Func<float, Color>? shadowEvaluator, Color32? mainColor = null, Color32? shadowColor = null, float defaultTime = 0f)	Same as the first overload, but takes a plain string for the name (registered automatically as a StringNames).
new VariableColor(string name, Func<float, Color> mainEvaluator, Color32? mainColor = null, float defaultTime = 0f)	Same as the second overload, but takes a plain string for the name.

Properties

Note: VariableColor inherits Name, MainColor, ShadowColor, and ColorBrightness from CustomColor.

Property	Type	Default	Description
MainEvaluator	Func<float, Color>	Set by constructor	A delegate that takes in a time value (float) and returns the dynamic main color.
ShadowEvaluator	Func<float, Color>	Set by constructor or auto-derived from MainEvaluator	A delegate that takes in a time value (float) and returns the dynamic shadow color.

Methods

Method	Returns	Description
EvaluateMainColor(float time)	Color	Evaluates the dynamic main color based on the provided time value. If static variable colors are enabled in the user's settings, this method returns the static fallback MainColor instead.
EvaluateShadowColor(float time)	Color	Evaluates the dynamic shadow color based on the provided time value. If static variable colors are enabled in the user's settings, this method returns the static fallback ShadowColor instead.

PaletteManager

PaletteManager provides access to a bunch of color utilities.

Member	Description
RegisteredColors	A read-only list of all CustomColor instances that have been registered.
IsVariable(int)	Checks to see if a color with the provided ID exists and is a variable color.
IsCustomColor(int)	Checks to see if a color with the provided ID exists and is a color that has been injected via mods.
GetMainColor(int)	Gets the main color of the color associated with the provided ID. Returns pure white (#FFFFFF) if a color could not be found with the ID.
GetShadowColor(int)	GetMainColor(int) but provides the shadow color instead.
GetBrightness(int)	Gets a CustomColorBrightness enum value of a color with the associated ID. Returns Lighter or Darker based on what the mod set it as (or as predefined for vanilla colors), and Invalid if the color ID does not have an associated color.

Colors are automatically appended to the game's Palette.PlayerColors, Palette.ShadowColors, Palette.ColorNames, Palette.TextColors, and Palette.TextOutlineColors arrays at startup.

Color Spaces

The standard RGB format can sometimes be mathematically limiting for dynamic color manipulation. To solve this, MiraAPI.Colors.ColorSpaces provides three alternative color space structures: CmykColor, HsbColor, and HslColor.

Available Structs

Each struct supports an alpha channel, which defaults to 1f if not explicitly provided during initialization.

Struct	Components	Description
CmykColor	c (Cyan), m (Magenta), y (Yellow), k (Key/Black), a (Alpha)	Represents the CMYK color space.
HsbColor	h (Hue), s (Saturation), b (Brightness), a (Alpha)	Represents the HSB color space.
HslColor	h (Hue), s (Saturation), l (Lightness), a (Alpha)	Represents the HSL color space.

Conversions

These color spaces are designed to integrate directly with standard Unity color types:

• Implicit Conversion: You can implicitly convert between any of these structs and a standard Unity Color (and by extension, Color32).
• Explicit Methods: Every struct includes ToColor() to convert the custom space into a standard RGB Unity Color, and FromColor() to convert a standard Unity Color into the custom color space.

Interpolation

All three structs provide built-in static methods for linear interpolation:

• Lerp(a, b, t): Linearly interpolates between two colors, clamping the t interpolant between 0 and 1.
• LerpUnclamped(a, b, t): Linearly interpolates between two colors without clamping the t value.
• Hue Shortest-Path: When interpolating HsbColor or HslColor, both Lerp and LerpUnclamped automatically calculate the shortest path for the hue transition, ensuring smooth visual blending across the color wheel.

Accessibility

Due to potential health and other related issues that might arise from rapidly changing colors, you may render variable colors to be static, forcing them to instead be a singular color the entire time, instead of changing over time.