Struct ColorPaletteEntry

Represents a single color entry within a ColorPalette. Each entry associates an identifier (ID) with a UnityEngine.Color value and an optional ColorRole annotation.

Implements

IEquatable<ColorPaletteEntry>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Palette

Assembly: ScyllaCore.dll

Syntax

public readonly struct ColorPaletteEntry : IEquatable<ColorPaletteEntry>

Remarks

Value semantics. ColorPaletteEntry is a readonly struct, providing zero-allocation, stack-allocated value semantics. Copying an entry is cheap. Because the struct is readonly, all fields are guaranteed not to change after construction.

Color precision. The primary color storage is UnityEngine.Color (float, 4x32-bit) for full precision in UI themes and alpha transparency. A Color32 (byte, 4x8-bit) accessor is available via the Color32 property for retro palette and terminal use cases. The conversion is computed on access (implicit Unity conversion).

Semantic roles. The Role property optionally annotates an entry with a ColorRole (e.g., Primary, Background, Destructive). Retro/generic palettes default to None. UI theme palettes use roles to enable fallback resolution when switching between palettes with different naming conventions.

Validation. The constructor rejects null, empty, and whitespace-only IDs with an immediate ArgumentException (fail-fast). The color value is accepted as-is with no modification.

Tags. The Tags property provides optional string tags for categorization and filtering (e.g., "background", "ui", "environment"). Tags default to an empty array. A defensive copy is made at construction time to preserve immutability.

Locking. The IsLocked flag marks an entry as protected from editing in editor tools. A locked entry cannot be modified or deleted through the Chroma editor UI. This is useful for enforcing brand colors or critical palette entries.

Equality. Two entries are equal if and only if their IDs match exactly (case-sensitive, ordinal comparison), all four RGBA color components are identical, their roles match, their lock states match, and their tag arrays contain the same elements in the same order.

Constructors

ColorPaletteEntry(string, Color, ColorRole)

Creates a new color palette entry with the specified ID, float-precision color, and optional semantic role.

Declaration

public ColorPaletteEntry(string id, Color color, ColorRole role = ColorRole.None)

Parameters

Type	Name	Description
string	id	The identifier for this color (e.g. "BrightCyan", "Primary"). Must not be null, empty, or whitespace-only.
Color	color	The RGBA color value in float precision (0.0-1.0 per component).
ColorRole	role	Optional semantic role for fallback resolution. Defaults to None.

Exceptions

Type	Condition
ArgumentException	Thrown immediately if id is null, empty, or consists only of whitespace characters (fail-fast validation).

ColorPaletteEntry(string, Color, ColorRole, string[], bool)

Creates a new color palette entry with all fields specified, including tags and lock state.

Declaration

public ColorPaletteEntry(string id, Color color, ColorRole role, string[] tags, bool isLocked)

Parameters

Type	Name	Description
string	id	The identifier for this color. Must not be null, empty, or whitespace-only.
Color	color	The RGBA color value in float precision.
ColorRole	role	Semantic role for fallback resolution. Use None for entries without semantic meaning.
string[]	tags	Optional string tags for categorization and filtering. A defensive copy is made. Pass null or an empty array for no tags.
bool	isLocked	Whether this entry is protected from editing in editor tools.

Exceptions

Type	Condition
ArgumentException	Thrown immediately if id is null, empty, or consists only of whitespace characters (fail-fast validation).

ColorPaletteEntry(string, Color32, ColorRole)

Creates a new color palette entry with the specified ID and byte-precision color. The UnityEngine.Color32 is converted to UnityEngine.Color (float) internally for storage.

Declaration

public ColorPaletteEntry(string id, Color32 color, ColorRole role = ColorRole.None)

Parameters

Type	Name	Description
string	id	The identifier for this color (e.g. "BrightCyan"). Must not be null, empty, or whitespace-only.
Color32	color	The RGBA color value in byte precision (0-255 per component). Converted to float precision internally via Unity's implicit UnityEngine.Color32 to UnityEngine.Color conversion.
ColorRole	role	Optional semantic role for fallback resolution. Defaults to None.

Remarks

This constructor overload exists for backward compatibility with existing retro palette definitions that specify colors as UnityEngine.Color32 literals.

Exceptions

Type	Condition
ArgumentException	Thrown immediately if id is null, empty, or consists only of whitespace characters (fail-fast validation).

ColorPaletteEntry(string, Color32, ColorRole, string[], bool)

Creates a new color palette entry with byte-precision color, tags, and lock state.

Declaration

public ColorPaletteEntry(string id, Color32 color, ColorRole role, string[] tags, bool isLocked)

Parameters

Type	Name	Description
string	id	The identifier for this color. Must not be null, empty, or whitespace-only.
Color32	color	The RGBA color value in byte precision (0-255 per component).
ColorRole	role	Semantic role for fallback resolution.
string[]	tags	Optional string tags for categorization and filtering.
bool	isLocked	Whether this entry is protected from editing in editor tools.

Exceptions

Type	Condition
ArgumentException	Thrown immediately if id is null, empty, or consists only of whitespace characters (fail-fast validation).

Properties

Color

The RGBA color value associated with this entry, in float precision.

Declaration

public Color Color { get; }

Property Value

Type	Description
Color	A UnityEngine.Color whose red, green, blue, and alpha float components each range from 0.0 to 1.0. Stored as-is from the constructor with no modification.

Remarks

This is the primary color representation. Use Color32 when byte-precision (0-255) is needed, e.g. for terminal rendering or retro palette display. The alpha channel is fully supported but is not considered by GetNearestIndex(Color) for nearest-color matching.

Color32

The RGBA color value in byte precision (0-255 per component).

Declaration

public Color32 Color32 { get; }

Property Value

Type	Description
Color32	A UnityEngine.Color32 computed from the float-precision Color via Unity's implicit conversion.

Remarks

Computed on each access (no caching). For performance-critical loops over many entries, prefer accessing Colors32 which provides a pre-computed Color32 span.

ID

The identifier of this color entry (e.g. "BrightCyan", "Primary", "Background"). Code looks colors up by this ID, so it should describe what the color is used for and stay stable when the color value changes.

Declaration

public string ID { get; }

Property Value

Type	Description
string	A non-null, non-empty, non-whitespace string assigned at construction time. Guaranteed never to change after the struct is created.

Remarks

Used as the lookup key in the parent ColorPalette's internal ID-to-index dictionary (case-insensitive at the palette level) and as the left-hand side of case-sensitive ordinal equality in Equals(ColorPaletteEntry).

IsLocked

Whether this entry is locked against editing in editor tools. A locked entry cannot be modified or deleted through the editor UI.

Declaration

public bool IsLocked { get; }

Property Value

Type	Description
bool	true if the entry is protected from editing; false (default) otherwise.

Role

The semantic role of this color entry, used for fallback resolution when mapping between palettes with different naming conventions.

Declaration

public ColorRole Role { get; }

Property Value

Type	Description
ColorRole	A ColorRole value. Defaults to None for retro/generic palette entries. UI theme palettes use specific roles (e.g., Primary, Background).

Remarks

When switching palettes, the resolution chain tries ID match first, then role match, then perceptual nearest. Entries with None are skipped during role-based resolution.

Tags

Optional string tags for categorization and filtering of palette entries (e.g., "background", "ui", "environment").

Declaration

public string[] Tags { get; }

Property Value

Type	Description
string[]	A non-null string array. Defaults to Empty<T>() when no tags are specified. A defensive copy is made at construction time.

Methods

Equals(ColorPaletteEntry)

Determines whether this entry is equal to another entry by comparing the ID, all four RGBA color components, and the semantic role.

Declaration

public bool Equals(ColorPaletteEntry other)

Parameters

Type	Name	Description
ColorPaletteEntry	other	The ColorPaletteEntry to compare with this instance.

Returns

Type	Description
bool	true if other has the same ID (case-sensitive, ordinal), identical Color RGBA components, and the same Role; otherwise, false.

Remarks

Color components are compared using exact float equality. For approximate comparison, use Approximately(float, float, float) on individual components.

Equals(object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj

Returns

Type	Description
bool

Overrides

ValueType.Equals(object)

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
int

Overrides

ValueType.GetHashCode()

Remarks

Combines the ID, all four RGBA float components of Color, and the Role via Combine<T1, T2, T3, T4, T5>(T1, T2, T3, T4, T5) for good distribution. Consistent with Equals(ColorPaletteEntry): two entries that are equal always produce the same hash code.

ToString()

Returns a human-readable string representation of this entry.

Declaration

public override string ToString()

Returns

Type	Description
string	A string in the format "ID (#RRGGBB)" when the role is None, or "ID (#RRGGBB, Role)" when a semantic role is assigned. Hex digits are uppercase. For example: "BrightCyan (#55FFFF)", "Primary (#1A1A2E, Primary)".

Overrides

ValueType.ToString()

Operators

operator ==(ColorPaletteEntry, ColorPaletteEntry)

Determines whether two ColorPaletteEntry instances are equal, comparing ID, all four RGBA color components, and semantic role.

Declaration

public static bool operator ==(ColorPaletteEntry left, ColorPaletteEntry right)

Parameters

Type	Name	Description
ColorPaletteEntry	left	The left-hand entry.
ColorPaletteEntry	right	The right-hand entry.

Returns

Type	Description
bool	true if left and right have identical IDs, RGBA float components, and roles; otherwise false.

operator !=(ColorPaletteEntry, ColorPaletteEntry)

Determines whether two ColorPaletteEntry instances are not equal.

Declaration

public static bool operator !=(ColorPaletteEntry left, ColorPaletteEntry right)

Parameters

Type	Name	Description
ColorPaletteEntry	left	The left-hand entry.
ColorPaletteEntry	right	The right-hand entry.

Returns

Type	Description
bool	true if left and right differ in ID, any RGBA float component, or role; otherwise false.

Implements

IEquatable<T>

See Also

ColorPalette

ColorAssetRegistry

ColorRole