DOCSEARCHbyAlgolia
Submit Docs

uPalette Documentation

repository·master·Indexed 18 days ago

https://github.com/haruma-k/upalette

A Unity tool for centralized management of colors, gradients, and text styles. uPalette allows developers to define a central Palette Store and link project components via Synchronizers, enabling project-wide visual updates from a single entry. It supports themes, hierarchical folder organization, automatic C# enum generation for type-safe scripting, and compatibility with uGUI and TextMesh Pro (TMP) character styles.

Tokens
8.1K
Snippets
16
Records
36
Agent score
62%

What's inside uPalette

  1. What is uPalette?

    master
    uPalette is a system for Unity projects designed to centrally manage colors, text styles, and gradients. Instead of manually updating individual Prefabs or Scenes when a design change occurs (e.g., changing a brand color from blue to green), uPalette allows you to manage these values in a single location and apply changes globally across your project. It also supports a 'Theme' feature, allowing you to switch between different sets of colors and styles by simply changing the active theme.

  2. What is uPalette and how does it work?

    master

    uPalette is a centralized management system for colors, text styles, and gradients in Unity projects.

    Instead of manually updating color values across multiple Prefabs and Scenes, you define a central Palette Store containing Entries (individual color or style values). You then link components in your project to these Entries using Synchronizers. When an Entry value is changed in the Palette Editor, all synchronized properties across your project are automatically updated.

    Key features include:

    • Centralized Management: Change a single color entry to update all linked UI elements.
    • Theme Support: Save sets of colors and styles as themes and switch between them.
    • Multiple Palette Types: Supports Colors, Gradients, uGUI Character Styles, and TextMesh Pro (TMP) Character Styles.
    • Folder Organization: Hierarchical organization of entries using slash-separated names.

  3. How Themes work in uPalette

    master

    A Theme is a saved set of entry values. By switching themes, you can instantly change the colors or text styles across your entire project.

    Workflow:

    1. Create Themes: Open Window > uPalette > Theme Editor. Create new themes using the "+" button. You can rename, delete, or reorder them.
    2. Configure Theme Values: Once a theme is created, new columns appear in the Palette Editor. You can define specific values for each entry for that specific theme.
    3. Switch Themes (Editor): In the Theme Editor, click the Activate button to apply a theme immediately in the editor.
    4. Switch Themes (Runtime): Use the Palette.SetActiveTheme() method via script.

  4. How uPalette reflects Entries in Unity

    master

    To avoid corrupting Scenes and Prefabs with serialized values, uPalette stores Entries as IDs rather than raw values. The actual values are reflected onto components based on the following lifecycle rules:

    • Edit Mode: Entries are reflected and observed for changes when OnEnable is called.
    • Play Mode: Entries are reflected when Start() is called.

    Note on Scene Integrity: To prevent accidental changes when opening a Scene in Edit Mode, uPalette does not set the 'dirty' flag when reflecting an Entry.

  5. Migrate from uPalette version 1 to version 2

    master

    If you are upgrading from version 1 to version 2, note that data structures and storage locations have changed significantly.

    To migrate your existing data, go to Project Settings and click the migration button before creating any new Palette Stores. This will prompt you to save a new Palette Store asset.

    Important: Since Palette Store assets are used at runtime, do not place the migrated asset in an Editor folder or a StreamingAssets folder.

  6. Create a Palette Store

    master

    A Palette Store is the asset that holds all your uPalette data.

    1. Open the Palette Editor via Window > uPalette > Palette Editor.
    2. Click the Create Palette Store button in the center of the window.
    3. Save the asset anywhere in your project.

    Important: Do NOT place the Palette Store asset in an Editor folder or the Streaming Assets folder, as it must be accessible at runtime.

  7. Apply Entries to GameObjects

    master

    To link an entry (color, text style, etc.) to a component:

    1. Select the target GameObject in the scene.
    2. In the Palette Editor, click the Apply button next to the desired entry.
    3. A list of applicable components and property names will appear. Select the one you want to synchronize.

    Key Concepts:

    • Synchronizer: When an entry is applied, a Synchronizer component is attached to the GameObject. This component manages the link. You can switch entries via the Synchronizer's Inspector or remove synchronization by detaching the component.
    • Multiple Synchronizers: If multiple Synchronizers exist for the same component/property, you can choose which one to use from the menu.
    • Prefabs: If you apply an entry to a Prefab, it follows standard Prefab workflows. You must use the right-click menu to Apply changes to the Prefab asset to ensure they are serialized.

  8. Use Themes to switch color and style sets

    master

    The Theme feature allows you to group Entries into named sets (e.g., 'Dark Mode', 'Forest Theme'). You can switch between these themes to instantly update the colors and character styles across your project.

    In the Editor

    1. Open the Theme Editor via Window > uPalette > Theme Editor.
    2. Create a new Theme using the + button.
    3. Assign values to Entries for each Theme in the columns provided in the Palette Editor.
    4. Switch themes by clicking the Activate button in the Theme Editor.

    At Runtime via Script

    Use SetActiveTheme() on a Palette instance. It is recommended to use the automatically generated enums for type safety.

    using System;
using UnityEngine;
using uPalette.Generated;
using uPalette.Runtime.Core;

public class Example : MonoBehaviour
{
    public void OnGUI()
    {
        // Iterating through auto-generated ColorTheme enum to switch themes
        foreach (ColorTheme colorTheme in Enum.GetValues(typeof(ColorTheme)))
            if (GUILayout.Button(colorTheme.ToString()))
            {
                var colorPalette = PaletteStore.Instance.ColorPalette;
                colorPalette.SetActiveTheme(colorTheme.ToThemeId());
            }
    }
}

  9. Generate Enums for Entries and Themes

    master

    To interact with uPalette via script using type-safe names, you can automatically generate Enums for your entries and themes.

    Configuration:

    • Project Settings > uPalette > Name Enums File Generation: Set to When Window Loses Focus to trigger generation when the Palette or Theme Editor loses focus.
    • Project Settings > uPalette > Name Enums File Location: Specify a folder for the generated file (defaults to Assets/).
    • Project Settings > uPalette > Contains Folder Name to Name Enums: If checked, folder names are included in the Enum members; if unchecked, they are excluded.

    Example Generated Enum:

    namespace uPalette.Generated
{
    public enum ColorEntry
    {
        Red,
        Green,
        Blue,
    }
}

    Accessing Entry IDs: Use the ToEntryId() extension method on the generated Enum to get the unique ID for an entry.

    using uPalette.Generated;

public class Example
{
    private void Foo()
    {
        // Converts the enum member to its corresponding Entry ID
        var id = ColorEntry.Red.ToEntryId();
    }
}

  10. Configure manual PaletteStore loading for AssetBundles

    master

    By default, uPalette registers Palette Data to PreloadedAssets, meaning it is always included in the build. If you want to manage Palette Data manually (e.g., via AssetBundles):

    1. Uncheck Project Settings > uPalette > Automatic Runtime Data Loading.
    2. Manually load the PaletteStore using Resources.Load (or your preferred asset loading method) before any UI or components that depend on uPalette are initialized.

    Once loaded, it is automatically registered to PaletteStore.Instance.

    // Load manually before loading GUIs that use uPalette
var _ = Resources.Load<PaletteStore>("PaletteStore");

  12. Create and Manage Entries

    master

    Entries are the individual color or style settings within a Palette Store.

    • Add Entry: Click the + button in the upper right corner of the Palette Editor.
    • Rename Entry: Click directly on the entry's name.
    • Delete Entry: Right-click an entry in the list and select the delete option.
    • Reorder Entries: Drag and drop entries to change their order.
    • Folder Organization: You can create a hierarchy by using slashes in the entry name (e.g., UI/Buttons/Primary). To enable this view, go to Project Settings > uPalette > Use Folder View in Palette Editor.