Class ColorPalette

An immutable, ordered collection of named UnityEngine.Color entries representing a color palette. Provides indexed access, case-insensitive name lookup, semantic role lookup, and perceptual nearest-color matching.

Inheritance
object
ColorPalette
Implements
Inherited Members
Namespace: Scylla.Core.Util.Palette
Assembly: ScyllaCore.dll
Syntax
public sealed class ColorPalette : IEquatable<ColorPalette>
Remarks

Immutability. Once constructed, a ColorPalette cannot be modified. The constructor makes a defensive copy of the supplied ColorPaletteEntry array, so callers cannot mutate the palette's contents after construction. All properties and methods are therefore safe to call from multiple threads concurrently without synchronization.

Color precision. Primary storage is UnityEngine.Color (float, 4x32-bit) for full precision in UI themes and alpha transparency. A secondary UnityEngine.Color32 (byte, 4x8-bit) cache is computed once at construction for terminal and retro palette consumers. Both are exposed via zero-allocation ReadOnlySpan<T> properties.

Name lookup. The internal name-to-index dictionary is built once during construction using OrdinalIgnoreCase, enabling O(1) case-insensitive lookups by color name.

Role lookup. Entries may carry a ColorRole annotation (e.g., Primary, Background). The TryGetColorByRole(ColorRole, out Color) method finds the first entry with a matching role in palette order.

Nearest-color matching. GetNearestIndex(Color), GetNearest(Color), and GetNearestEntry(Color) all use the "redmean" weighted RGB approximation for perceptually accurate matching.

Constructors

ColorPalette(string, string, ColorPaletteEntry[])

Creates a new immutable color palette from the specified entries.

Declaration
public ColorPalette(string name, string description, ColorPaletteEntry[] entries)
Parameters
Type Name Description
string name

Human-readable identifier. Must not be null.
string description

Short description of the palette. Must not be null.
ColorPaletteEntry[] entries

Ordered set of entries. Must not be null, must contain at least one element. A defensive copy is made; modifying the original array after construction has no effect.
Exceptions
Type Condition
ArgumentNullException

If name, description, or entries is null.
ArgumentException

If entries is empty, any entry has a null name, or duplicate names exist (case-insensitive).

ColorPalette(string, string, ColorPaletteEntry[], string[])

Creates a new immutable color palette with optional asset-level tags.

Declaration
public ColorPalette(string name, string description, ColorPaletteEntry[] entries, string[] tags)
Parameters
Type Name Description
string name

Human-readable identifier. Must not be null.
string description

Short description of the palette. Must not be null.
ColorPaletteEntry[] entries

Ordered set of entries. Must not be null, must contain at least one element. A defensive copy is made; modifying the original array after construction has no effect.
string[] tags

Optional asset-level tags (e.g. "UI", "Demo", "Retro"). A defensive copy is made; modifying the original array after construction has no effect. Null is treated as an empty tag set. Null or whitespace tag entries are skipped silently.
Exceptions
Type Condition
ArgumentNullException

If name, description, or entries is null.
ArgumentException

If entries is empty, any entry has a null name, or duplicate names exist (case-insensitive).

Properties

Colors

Gets a read-only span over all color values (float precision) in palette order.

Declaration
public ReadOnlySpan<Color> Colors { get; }
Property Value
Type Description
ReadOnlySpan<Color>

A zero-allocation ReadOnlySpan<T> backed by the pre-allocated float color array. Prefer this over Entries when only the color value is needed and allocation must be avoided.

Colors32

Gets a read-only span over all color values (byte precision) in palette order. Pre-computed at construction time for zero-conversion access.

Declaration
public ReadOnlySpan<Color32> Colors32 { get; }
Property Value
Type Description
ReadOnlySpan<Color32>

A zero-allocation ReadOnlySpan<T> backed by the pre-allocated UnityEngine.Color32 array. Use this for terminal rendering, retro palette display, or any consumer that requires byte-precision color without per-entry float-to-byte conversion overhead.

Count

The number of color entries in this palette.

Declaration
public int Count { get; }
Property Value
Type Description
int

Always greater than zero; the constructor rejects empty entry arrays.

Description

A short description of this palette and its origin.

Declaration
public string Description { get; }
Property Value
Type Description
string

A non-null string assigned at construction time. Describes the palette's source, purpose, or visual character (e.g., "IBM PC CGA hardware palette").

Entries

Gets a read-only span over all palette entries, in palette order.

Declaration
public ReadOnlySpan<ColorPaletteEntry> Entries { get; }
Property Value
Type Description
ReadOnlySpan<ColorPaletteEntry>

A zero-allocation ReadOnlySpan<T> backed by the internal entry array. Iterate over this when both the name and color value are needed simultaneously.

this[int]

Gets the color at the specified palette index (float precision).

Declaration
public Color this[int index] { get; }
Parameters
Type Name Description
int index

Zero-based index. Must be in range [0, Count-1].
Property Value
Type Description
Color

The UnityEngine.Color at the specified index.
Exceptions
Type Condition
IndexOutOfRangeException

If index is out of range.

this[string]

Gets the color with the specified name using a case-insensitive lookup (float precision).

Declaration
public Color this[string name] { get; }
Parameters
Type Name Description
string name

The color name to look up. Must not be null.
Property Value
Type Description
Color

The UnityEngine.Color whose name matches.
Exceptions
Type Condition
ArgumentNullException

If name is null.
KeyNotFoundException

If no color with the specified name exists.

Name

The human-readable name of this palette (e.g. "CGA", "Scylla UI Light").

Declaration
public string Name { get; }
Property Value
Type Description
string

A non-null, non-empty string assigned at construction time and guaranteed never to change. Used as the key in IEquatable<T> comparisons (case-sensitive, ordinal) and as the display label for palette picker UIs.

TagCount

Gets the number of asset-level tags attached to this palette.

Declaration
public int TagCount { get; }
Property Value
Type Description
int

Zero if no tags were supplied. Use GetTag(int) or HasTag(string) to inspect individual tags.

Tags

Gets a read-only span over all asset-level tag strings.

Declaration
public ReadOnlySpan<string> Tags { get; }
Property Value
Type Description
ReadOnlySpan<string>

A zero-allocation ReadOnlySpan<T> backed by the internal tag array. Empty when no tags were supplied. Used by GetPalettesByTag(string) to group palettes by category.

Methods

ContainsName(string)

Checks whether this palette contains an entry with the specified name.

Declaration
public bool ContainsName(string name)
Parameters
Type Name Description
string name

The color name to test. Case-insensitive. Passing null always returns false without performing a dictionary lookup.
Returns
Type Description
bool

true if an entry with the given name exists in this palette; otherwise false.

CreateMapping(ColorPalette)

Creates a cached mapping from this palette to the specified target palette, using the three-step fallback resolution chain (name, role, perceptual nearest).

Declaration
public ColorPaletteMapping CreateMapping(ColorPalette target)
Parameters
Type Name Description
ColorPalette target

The target palette to map to. Must not be null.
Returns
Type Description
ColorPaletteMapping

A reusable ColorPaletteMapping instance.
Remarks

Cache the returned mapping when switching between the same palette pair frequently. The mapping is immutable and safe to reuse.

Exceptions
Type Condition
ArgumentNullException

If target is null.

Equals(ColorPalette)

Determines whether this palette is equal to another palette. Equality is based solely on the palette name (case-sensitive, ordinal comparison).

Declaration
public bool Equals(ColorPalette other)
Parameters
Type Name Description
ColorPalette other

The ColorPalette to compare with this instance.
Returns
Type Description
bool

true if other is non-null and its Name matches this palette's Name exactly (ordinal, case-sensitive); otherwise false.
Remarks

Two palettes with the same name but different entries are considered equal by this definition. Identity by name is deliberate: it allows the same logical palette to be compared regardless of how it was constructed or loaded.

Equals(object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
object obj
Returns
Type Description
bool
Overrides

GetColor32(int)

Gets the color at the specified index in byte precision.

Declaration
public Color32 GetColor32(int index)
Parameters
Type Name Description
int index

Zero-based index.
Returns
Type Description
Color32

The UnityEngine.Color32 at the specified index.
Exceptions
Type Condition
IndexOutOfRangeException

If index is out of range.

GetColor32(string)

Gets the color with the specified name in byte precision.

Declaration
public Color32 GetColor32(string name)
Parameters
Type Name Description
string name

The color name (case-insensitive).
Returns
Type Description
Color32

The UnityEngine.Color32 for the matching entry.
Exceptions
Type Condition
ArgumentNullException

If name is null.
KeyNotFoundException

If the name is not found.

GetColorName(int)

Gets the name of the color at the specified palette index.

Declaration
public string GetColorName(int index)
Parameters
Type Name Description
int index

Zero-based index.
Returns
Type Description
string

The name string of the entry.
Exceptions
Type Condition
IndexOutOfRangeException

If index is out of range.

GetEntry(int)

Gets the full entry (name, color, and role) at the specified palette index.

Declaration
public ColorPaletteEntry GetEntry(int index)
Parameters
Type Name Description
int index

Zero-based index.
Returns
Type Description
ColorPaletteEntry

The ColorPaletteEntry at the specified index.
Exceptions
Type Condition
IndexOutOfRangeException

If index is out of range.

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
int
Overrides

GetNearest(Color)

Finds the palette color perceptually nearest to the target (float precision).

Declaration
public Color GetNearest(Color target)
Parameters
Type Name Description
Color target

The color to match. Alpha is ignored.
Returns
Type Description
Color

The nearest UnityEngine.Color.

GetNearest(Color32)

Finds the palette color perceptually nearest to the target (byte precision).

Declaration
public Color32 GetNearest(Color32 target)
Parameters
Type Name Description
Color32 target

The color to match. Alpha is ignored.
Returns
Type Description
Color32

The nearest UnityEngine.Color32.

GetNearestEntry(Color)

Finds the full entry perceptually nearest to the target.

Declaration
public ColorPaletteEntry GetNearestEntry(Color target)
Parameters
Type Name Description
Color target

The color to match. Alpha is ignored.
Returns
Type Description
ColorPaletteEntry

The nearest ColorPaletteEntry.

GetNearestEntry(Color32)

Finds the full entry perceptually nearest to the target.

Declaration
public ColorPaletteEntry GetNearestEntry(Color32 target)
Parameters
Type Name Description
Color32 target

The color to match. Alpha is ignored.
Returns
Type Description
ColorPaletteEntry

The nearest ColorPaletteEntry.

GetNearestIndex(Color)

Finds the index of the palette color perceptually nearest to the target. Uses redmean weighted RGB distance. Alpha is not considered.

Declaration
public int GetNearestIndex(Color target)
Parameters
Type Name Description
Color target

The color to match against. Alpha is ignored.
Returns
Type Description
int

Zero-based index of the nearest entry.

GetNearestIndex(Color32)

Finds the index of the palette color perceptually nearest to the target. Uses redmean weighted RGB distance. Alpha is not considered.

Declaration
public int GetNearestIndex(Color32 target)
Parameters
Type Name Description
Color32 target

The color to match against. Alpha is ignored.
Returns
Type Description
int

Zero-based index of the nearest entry.

GetTag(int)

Gets the asset-level tag at the specified index.

Declaration
public string GetTag(int index)
Parameters
Type Name Description
int index

Zero-based tag index, must be in [0, TagCount).
Returns
Type Description
string

The tag string at the specified index.
Exceptions
Type Condition
IndexOutOfRangeException

If index is out of range.

HasTag(string)

Tests whether this palette carries the given tag (case-insensitive).

Declaration
public bool HasTag(string tag)
Parameters
Type Name Description
string tag

The tag to look up. Null returns false.
Returns
Type Description
bool

true if any tag matches, otherwise false.

IndexOf(string)

Gets the zero-based index of the entry with the specified name, or -1 if no matching entry exists.

Declaration
public int IndexOf(string name)
Parameters
Type Name Description
string name

The color name to find. Case-insensitive. Passing null always returns -1 without performing a dictionary lookup.
Returns
Type Description
int

The zero-based index of the matching entry in palette order, or -1 if the name was not found.

ResolveColor(string, ColorPalette)

Resolves a single named color from this palette to the best match in the target palette, using the three-step fallback chain.

Declaration
public Color ResolveColor(string name, ColorPalette target)
Parameters
Type Name Description
string name

The color name in this palette (case-insensitive).
ColorPalette target

The target palette to resolve against.
Returns
Type Description
Color

The resolved UnityEngine.Color from the target palette.
Remarks

For one-off lookups. If resolving many colors from the same pair, use CreateMapping(ColorPalette) instead to avoid repeated fallback computation.

Exceptions
Type Condition
ArgumentNullException

If name or target is null.
ArgumentException

If name is not found in this (source) palette.

ToString()

Returns a human-readable string representation of this palette.

Declaration
public override string ToString()
Returns
Type Description
string

A string in the format "Name (N colors)", for example "CGA (16 colors)" or "Scylla UI Light (16 colors)".
Overrides

TryGetColor(string, out Color)

Tries to get a color by name (float precision) without throwing on failure. The preferred non-throwing alternative to the string indexer.

Declaration
public bool TryGetColor(string name, out Color color)
Parameters
Type Name Description
string name

The color name to look up. Case-insensitive. Passing null immediately returns false without performing a dictionary lookup.
Color color

When this method returns true, contains the float-precision UnityEngine.Color for the matching entry. When false, contains default(Color) (transparent black).
Returns
Type Description
bool

true if an entry with the specified name was found; otherwise false.

TryGetColor32(string, out Color32)

Tries to get a color by name (byte precision) without throwing on failure. The preferred non-throwing alternative to GetColor32(string).

Declaration
public bool TryGetColor32(string name, out Color32 color)
Parameters
Type Name Description
string name

The color name to look up. Case-insensitive. Passing null immediately returns false without performing a dictionary lookup.
Color32 color

When this method returns true, contains the byte-precision UnityEngine.Color32 for the matching entry. When false, contains default(Color32) (transparent black, all components zero).
Returns
Type Description
bool

true if an entry with the specified name was found; otherwise false.

TryGetColorByRole(ColorRole, out Color)

Tries to get the first color with the specified semantic role.

Declaration
public bool TryGetColorByRole(ColorRole role, out Color color)
Parameters
Type Name Description
ColorRole role

The role to search for. None always returns false.
Color color

The color if found, or default.
Returns
Type Description
bool

True if an entry with the specified role was found.
Remarks

Scans entries in palette order and returns the first match. O(n) where n is palette size. For typical UI palettes (16 entries), this is negligible.

TryGetIndexByRole(ColorRole, out int)

Tries to get the index of the first entry with the specified semantic role.

Declaration
public bool TryGetIndexByRole(ColorRole role, out int index)
Parameters
Type Name Description
ColorRole role

The role to search for. None always returns false.
int index

The zero-based index if found, or -1.
Returns
Type Description
bool

True if an entry with the specified role was found.

Operators

operator ==(ColorPalette, ColorPalette)

Determines whether two palettes are equal, comparing by name (case-sensitive, ordinal).

Declaration
public static bool operator ==(ColorPalette left, ColorPalette right)
Parameters
Type Name Description
ColorPalette left

The left-hand palette, or null.
ColorPalette right

The right-hand palette, or null.
Returns
Type Description
bool

true if both are null, or both are non-null with identical Name strings; otherwise false.

operator !=(ColorPalette, ColorPalette)

Determines whether two palettes are not equal.

Declaration
public static bool operator !=(ColorPalette left, ColorPalette right)
Parameters
Type Name Description
ColorPalette left

The left-hand palette, or null.
ColorPalette right

The right-hand palette, or null.
Returns
Type Description
bool

true if the two palettes differ in name or exactly one is null; otherwise false.

Implements

Extension Methods

See Also