> ## Documentation Index
> Fetch the complete documentation index at: https://docs-unity.molca.id/llms.txt
> Use this file to discover all available pages before exploring further.
# ColorID (theming)
> ColorModule SettingModule, ColorID components, ColorSchemeManager, ColorIDReference, and ColorUtility.
**Folder:** `Assets/_Molca/_Core/ColorID/`\
**Namespace:** `Molca.ColorID`
Central **swatch + color id** theming for Unity UI and renderers. Data lives in a **`ColorModule`** asset registered on [Global Settings](/setup/global-settings). Optional **`ColorSchemeManager`** subsystem swaps whole **`ColorModule`** instances (e.g. light/dark).
## ColorModule (`SettingModule`)
**File:** `ColorModule.cs`\
**Create asset:** **Molca → Settings → Color Settings**
* **Swatches** — named groups (e.g. `Default`) each holding **`colorId` → Color** definitions. Cache keys are **`SwatchName.ColorId`** internally.
* **Runtime API** — `ColorModule.GetColor(swatchName, colorId)`, `GetColor(colorId)` (default swatch / search), `HasColor`, `GetAllColorIds`, `SetActiveModule` (used when switching schemes).
* **Persistence** — per-color overrides can be stored in **PlayerPrefs** via module save/load paths (see source for `UpdateColor` / `GetColorWithFallback`).
Add the asset to the **`GlobalSettings`** module list like other [setting modules](/setup/global-settings).
## ColorID component
**File:** `ColorID.cs`\
**Add component:** **Molca → Utilities → Color ID**
* **Swatch name** + **color id** select which entry from the active **`ColorModule`** to apply.
* **Targets** — list of **`ColorTarget`** entries (type: Auto, Renderer, Image, TMP, etc.). If the list is empty at runtime, the component can **auto-discover** renderers/UI on this object (and optionally **children** via **`applyToChildren`**).
* After **`RuntimeManager.WaitForInitialization()`**, subscribes to **`ColorSchemeManager.OnSchemeChanged`** and reapplies colors.
* **`SetColor(swatchName, colorId)`** / **`SetColorId(...)`** — `SetColorId` supports composite **`"SwatchName/colorId"`** (note: **`ColorModule`** cache uses **dot** `SwatchName.ColorId`; the component’s composite split uses **slash** for the two-field API only).
### Renderers in the Editor
**`Renderer`** color application runs in **play mode only** (see source) so shared materials are not mutated in edit mode.
## ColorSchemeManager (`RuntimeSubsystem`)
**File:** `ColorSchemeManager.cs`
Child on the [RuntimeManager](/core/runtime-manager) prefab alongside other subsystems. Holds an array of **`ColorModule`** assets and activates one at init ( **`PlayerPrefs`** key **`ColorScheme_Active`**).
**API:** `ColorSchemeManager.SetScheme(index | name, save)`, `ToggleScheme`, `PreviousScheme`, `RefreshAllColorIDs`. Changing scheme calls **`ColorModule.SetActiveModule`** and raises **`OnSchemeChanged`**.
## ColorIDReference (serialized field)
**File:** `ColorIDReference.cs`
Serializable **swatch + id** pair with **`Color`**, **`GetColorWithAlpha`**, **`IsValid()`**, implicit conversions from **`string`** and to **`Color`**. Use on your own **`MonoBehaviour`** when you assign colors in code rather than using the **`ColorID`** driver component.
SDK example: `ColorID/Examples/ColorIDReferenceExample.cs`.
## ColorUtility
**File:** `ColorUtility.cs`
Static helpers: **`ApplyColorToGameObject`** (adds/configures **`ColorID`**), **`ApplyColorToComponent`**, **`CreateColorID`**, **`RefreshColorIDs`**, **`LerpColor`**, etc.
## Editor menu (ColorModule)
From **`ColorModule`** (editor section):
* **Molca → ColorID → Apply Colors to all IDs** — refresh all **`ColorID`** instances in the open scene(s).
* **Molca → ColorID → Scan and select invalid IDs** — select objects whose swatch/id is missing from the cache.
## Code
**Resolve a color after startup:**
```csharp theme={null}
using Molca;
using Molca.ColorID;
using UnityEngine;
using UnityEngine.UI;
public class ThemedPanel : MonoBehaviour
{
[SerializeField] private ColorIDReference headerFill = new ColorIDReference("Primary", "Default");
[SerializeField] private Image headerImage;
private async void Start()
{
await RuntimeManager.WaitForInitialization();
if (headerImage != null)
headerImage.color = headerFill.Color;
}
}
```
**Switch scheme from gameplay:**
```csharp theme={null}
using Molca.ColorID;
using UnityEngine;
public class ThemeToggle : MonoBehaviour
{
public void UseDarkMode() => ColorSchemeManager.SetScheme("Dark", save: true);
}
```
## Troubleshooting
* **Color stays wrong or never updates** — Confirm **`RuntimeManager.WaitForInitialization()`** has completed before reading **`ColorIDReference.Color`** or calling **`ColorSchemeManager.SetScheme`**. Ensure a **`ColorModule`** is registered on [Global Settings](/setup/global-settings) and **`ColorSchemeManager`** is present on the [RuntimeManager](/core/runtime-manager) prefab if you rely on scheme switching.
* **Swatch/id exists in the asset but resolves incorrectly at runtime** — Remember **`ColorModule`** cache keys use **`SwatchName.ColorId`** (dot). **`ColorID.SetColorId`** accepts a composite **`SwatchName/colorId`** (slash) for the two-part overload only; mismatched strings or typos show up as missing entries in **Scan and select invalid IDs**.
* **UI updates but meshes/renderers do not in the Editor** — **`Renderer`** targets apply in **play mode only** by design so shared materials are not edited in the Inspector; enter Play Mode or use UI/Image/TMP targets for edit-time previews where supported.
* **`SetScheme` has no visible effect** — Check the **`ColorSchemeManager`** module list and **`PlayerPrefs`** key **`ColorScheme_Active`**; call **`RefreshAllColorIDs`** after bulk changes. Ensure **`ColorID`** components subscribe after init (they listen for **`OnSchemeChanged`**).
* **Invalid ID scan finds false positives** — Active module vs asset mismatch (wrong **`ColorModule`** on Global Settings) or stale scene references after renaming swatches; re-run **Apply Colors to all IDs** after fixing the **`ColorModule`** asset.
## Related
* [Global Settings](/setup/global-settings) — register **`ColorModule`**
* [RuntimeManager](/core/runtime-manager) — bootstrap; **`ColorSchemeManager`** lives on the prefab
* [UI widgets](/shared/ui-widgets) — shared **`ColorIDButton`** (`RequireComponent(ColorID)`), **`ColorSchemeToggle`**, **`ColorSchemeDropdown`** (`_MolcaSDK/Code/Scripts/UI/`)
## Unity Editor
