Class MutableColorPalette

An editable color palette for runtime player customization and editor tooling. Provides add, remove, ID change, reorder, and color/role modification operations. Call Build() to produce an immutable ColorPalette snapshot.

Inheritance
object
MutableColorPalette
Inherited Members
Namespace: Scylla.Core.Util.Palette
Assembly: ScyllaCore.dll
Syntax
public sealed class MutableColorPalette
Remarks

Runtime use. MutableColorPalette is available in shipped builds, not just the editor. Use it for player color customization, accessibility settings, unlockable color schemes, or any scenario where colors need to be modified at runtime.

Thread safety. This class is NOT thread-safe. It is intended for main-thread use (Unity UI, editor tooling). Call Build() to produce an immutable, thread-safe ColorPalette snapshot for cross-thread sharing.

Change notification. The Changed event fires after every mutation operation. Subscribe to update previews, refresh UI, or trigger palette reapplication.

Constructors

MutableColorPalette(ColorPalette)

Creates a mutable copy of an existing immutable palette.

Declaration
public MutableColorPalette(ColorPalette source)
Parameters
Type Name Description
ColorPalette source

The palette to copy. Must not be null.
Exceptions
Type Condition
ArgumentNullException

If source is null.

MutableColorPalette(string, string)

Creates a new empty mutable palette.

Declaration
public MutableColorPalette(string name, string description)
Parameters
Type Name Description
string name

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

Short description. Must not be null.
Exceptions
Type Condition
ArgumentNullException

If name or description is null.

Properties

Count

The current number of entries in this palette.

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

Zero when the palette is empty or after Clear() is called. Build() requires this to be greater than zero.

Description

A short description of this palette. Cannot be set to null.

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

A non-null string describing the palette's purpose or origin. Corresponds to Description on the palette built by Build().
Exceptions
Type Condition
ArgumentNullException

Thrown when set to null.

this[int]

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

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

Zero-based index.
Property Value
Type Description
Color

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

If index is out of range.

this[string]

Gets the color with the specified ID (case-insensitive, float precision).

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

The color ID. Must not be null.
Property Value
Type Description
Color

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

If id is null.
KeyNotFoundException

If the ID is not found.

Name

The human-readable name of this palette. Cannot be set to null.

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

A non-null string used as the name in the ColorPalette produced by Build(). Corresponds to Name on the built palette.
Exceptions
Type Condition
ArgumentNullException

Thrown when set to null.

Methods

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

Appends a new color entry to the end of the palette.

Declaration
public void Add(string id, Color color, ColorRole role = ColorRole.None, string[] tags = null, bool isLocked = false)
Parameters
Type Name Description
string id

Unique color ID. Must not be null, empty, whitespace, or duplicate (case-insensitive).
Color color

The color value.
ColorRole role

Optional semantic role. Defaults to None.
string[] tags
bool isLocked
Exceptions
Type Condition
ArgumentException

If id is null/empty/whitespace or already exists in this palette.

Build()

Creates an immutable ColorPalette snapshot of the current state. The returned palette is thread-safe and independent of future mutations.

Declaration
public ColorPalette Build()
Returns
Type Description
ColorPalette

A new immutable ColorPalette.
Exceptions
Type Condition
InvalidOperationException

If the palette is empty.

Clear()

Removes all entries from the palette.

Declaration
public void Clear()

ContainsID(string)

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

Declaration
public bool ContainsID(string id)
Parameters
Type Name Description
string id

The color ID (case-insensitive).
Returns
Type Description
bool

True if the ID exists.

GetEntry(int)

Gets the full entry at the specified index as an immutable snapshot.

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

Zero-based index.
Returns
Type Description
ColorPaletteEntry

A ColorPaletteEntry snapshot of the entry.
Exceptions
Type Condition
ArgumentOutOfRangeException

If index is out of range.

IndexOf(string)

Gets the index of the entry with the specified ID, or -1 if not found.

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

The color ID (case-insensitive).
Returns
Type Description
int

Zero-based index, or -1 if not found.

Remove(string)

Removes the entry with the specified ID.

Declaration
public bool Remove(string id)
Parameters
Type Name Description
string id

The color ID (case-insensitive).
Returns
Type Description
bool

True if the entry was found and removed.

Reorder(int, int)

Moves an entry from one position to another, shifting other entries accordingly.

Declaration
public void Reorder(int fromIndex, int toIndex)
Parameters
Type Name Description
int fromIndex

Current position (zero-based).
int toIndex

Target position (zero-based).
Exceptions
Type Condition
ArgumentOutOfRangeException

If either index is out of range.

SetColor(int, Color)

Updates the color of an existing entry by index.

Declaration
public void SetColor(int index, Color color)
Parameters
Type Name Description
int index

Zero-based index.
Color color

The new color value.
Exceptions
Type Condition
ArgumentOutOfRangeException

If index is out of range.

SetColor(string, Color)

Updates the color of an existing entry by ID.

Declaration
public void SetColor(string id, Color color)
Parameters
Type Name Description
string id

The color ID (case-insensitive). Must exist.
Color color

The new color value.
Exceptions
Type Condition
ArgumentNullException

If id is null.
KeyNotFoundException

If the ID is not found.

SetID(string, string)

Changes the ID of an existing entry. The new ID must not already exist in the palette.

Declaration
public void SetID(string id, string newID)
Parameters
Type Name Description
string id

Current ID (case-insensitive). Must exist.
string newID

New ID. Must not be null, empty, whitespace, or duplicate.
Exceptions
Type Condition
KeyNotFoundException

If id is not found.
ArgumentException

If newID is null/empty/whitespace or already exists.

SetLocked(int, bool)

Updates the lock state of an existing entry by index.

Declaration
public void SetLocked(int index, bool isLocked)
Parameters
Type Name Description
int index

Zero-based index.
bool isLocked

Whether the entry is locked against editing.
Exceptions
Type Condition
ArgumentOutOfRangeException

If index is out of range.

SetLocked(string, bool)

Updates the lock state of an existing entry by ID.

Declaration
public void SetLocked(string id, bool isLocked)
Parameters
Type Name Description
string id

The color ID (case-insensitive). Must exist.
bool isLocked

Whether the entry is locked against editing.
Exceptions
Type Condition
ArgumentNullException

If id is null.
KeyNotFoundException

If the ID is not found.

SetRole(int, ColorRole)

Updates the semantic role of an existing entry by index.

Declaration
public void SetRole(int index, ColorRole role)
Parameters
Type Name Description
int index

Zero-based index.
ColorRole role

The new role.
Exceptions
Type Condition
ArgumentOutOfRangeException

If index is out of range.

SetRole(string, ColorRole)

Updates the semantic role of an existing entry by ID.

Declaration
public void SetRole(string id, ColorRole role)
Parameters
Type Name Description
string id

The color ID (case-insensitive). Must exist.
ColorRole role

The new role.
Exceptions
Type Condition
ArgumentNullException

If id is null.
KeyNotFoundException

If the ID is not found.

SetTags(int, string[])

Updates the tags of an existing entry by index.

Declaration
public void SetTags(int index, string[] tags)
Parameters
Type Name Description
int index

Zero-based index.
string[] tags

The new tags array. Null is treated as empty.
Exceptions
Type Condition
ArgumentOutOfRangeException

If index is out of range.

SetTags(string, string[])

Updates the tags of an existing entry by ID.

Declaration
public void SetTags(string id, string[] tags)
Parameters
Type Name Description
string id

The color ID (case-insensitive). Must exist.
string[] tags

The new tags array. Null is treated as empty.
Exceptions
Type Condition
ArgumentNullException

If id is null.
KeyNotFoundException

If the ID is not found.

TryGetColor(string, out Color)

Tries to get a color by ID without throwing on failure.

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

The color ID (case-insensitive). Null returns false.
Color color

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

True if found.

Events

Changed

Fired after every successful mutation operation: Add(string, Color, ColorRole, string[], bool), Remove(string), SetColor(string, Color), SetColor(int, Color), SetRole(string, ColorRole), SetRole(int, ColorRole), SetID(string, string), Reorder(int, int), and Clear() (only when at least one entry was present). The event is not fired on no-op calls (e.g., Reorder(int, int) with equal indices, Clear() on an already empty palette).

Declaration
public event Action<MutableColorPalette> Changed
Event Type
Type Description
Action<MutableColorPalette>
Remarks

The event argument is the MutableColorPalette instance that fired the event (i.e., this). Subscribers can read the current palette state directly from the argument.

This event fires on the same thread as the mutation. Because MutableColorPalette is intended for main-thread use, handlers should not perform thread-unsafe operations or dispatch back to the main thread.

Extension Methods

See Also