Migration from v2

Migration from v2

Version 3.x.x and newer uses a different database format. If you're upgrading from 2.x.x, follow these steps to preserve your binder connections.

Important: Follow the steps in exact order to avoid data loss.

Step 1 — Close Unity

Close the Unity project to prevent any data corruption during migration.

Step 2 — Backup

1. Make a backup copy of Assets/Resources/Unity-Theme Database.asset — save it outside the project
2. Take a screenshot of the colors in each theme so you can reproduce them later with the color picker

Step 3 — Download the New Database Template

1. Download Unity-Theme-Database.json
2. Save it at Assets/Resources/Unity-Theme-Database.json
3. Use it as a template — feel free to delete existing colors if you want to start fresh

Step 4 — Migrate Data (Copy GUIDs)

The key task is to copy GUIDs from the old .asset file to the new .json file. Binders reference colors by GUID, so preserving them keeps your bindings intact.

Old Format (.asset — YAML)

colors:
- guid: 6b934efb-0b9b-42fd-82fd-7a0dbd1de53c
  name: Primary
- guid: 520b0288-c5e4-4106-95ae-095ad2dcceb8
  name: Primary Text
- guid: 465741bc-25d8-4722-a981-7e4a18074d83
  name: Primary Container
themes:
- guid: 6d1fce4e-1938-4d6d-93b0-b4b9f6497293
  expanded: 1
  themeName: Light
  colors:
  - guid: 6b934efb-0b9b-42fd-82fd-7a0dbd1de53c
    color: {r: 0.40392157, g: 0.3137255, b: 0.6431373, a: 1}
  - guid: 520b0288-c5e4-4106-95ae-095ad2dcceb8
    color: {r: 1, g: 1, b: 1, a: 1}
  - guid: 465741bc-25d8-4722-a981-7e4a18074d83
    color: {r: 0.91764706, g: 0.8666667, b: 1, a: 1}
- guid: 54c71f36-6023-4d84-bce7-c8192cf7ba40
  expanded: 1
  themeName: Dark
  colors:
  - guid: 6b934efb-0b9b-42fd-82fd-7a0dbd1de53c
    color: {r: 0, g: 0.4784314, b: 1, a: 1}
  - guid: 520b0288-c5e4-4106-95ae-095ad2dcceb8
    color: {r: 1, g: 1, b: 1, a: 1}
  - guid: 465741bc-25d8-4722-a981-7e4a18074d83
    color: {r: 0.15294118, g: 0.15294118, b: 0.15686275, a: 1}

New Format (.json)

{
  "debugLevel": 2,
  "currentThemeIndex": 1,
  "colors": [
    { "guid": "6b934efb-0b9b-42fd-82fd-7a0dbd1de53c", "name": "Primary" },
    { "guid": "520b0288-c5e4-4106-95ae-095ad2dcceb8", "name": "Primary Text" },
    { "guid": "465741bc-25d8-4722-a981-7e4a18074d83", "name": "Primary Container" }
  ],
  "themes": [
    {
      "guid": "4cfe4185-bc3e-4247-969f-1da1d3f2bdec",
      "expanded": true,
      "themeName": "Light",
      "colors": [
        { "guid": "6b934efb-0b9b-42fd-82fd-7a0dbd1de53c", "colorHex": "#6750A4FF" },
        { "guid": "520b0288-c5e4-4106-95ae-095ad2dcceb8", "colorHex": "#FFFFFFFF" },
        { "guid": "465741bc-25d8-4722-a981-7e4a18074d83", "colorHex": "#EADDFFFF" }
      ]
    },
    {
      "guid": "dca52c83-4f79-4fee-854e-0defe9ccbe07",
      "expanded": true,
      "themeName": "Dark",
      "colors": [
        { "guid": "6b934efb-0b9b-42fd-82fd-7a0dbd1de53c", "colorHex": "#007AFFFF" },
        { "guid": "520b0288-c5e4-4106-95ae-095ad2dcceb8", "colorHex": "#FFFFFFFF" },
        { "guid": "465741bc-25d8-4722-a981-7e4a18074d83", "colorHex": "#272728FF" }
      ]
    }
  ]
}

What Changed

	Old (v2)	New (v3+)
File	Unity-Theme Database.asset (YAML)	Unity-Theme-Database.json (JSON)
Color values	{r, g, b, a} floats	colorHex string (#RRGGBBAA)
Color GUIDs	Same GUIDs	Must match — copy from old file
Theme GUIDs	Optional	Required (auto-generated if missing)

You can ignore the exact color hex values for now — it's easier to use the color picker tool later with your screenshots as reference.

Step 5 — Update the Package

With Unity still closed:

1. Remove the old package:

openupm remove extensions.unity.theme

2. Install the latest version:

openupm add extensions.unity.theme

Step 6 — Clean Up

1. Delete Assets/Resources/Unity-Theme Database.asset (the old file, both original and backup copy)
2. Open the Unity project
3. Verify your themes and colors in Window > Unity-Theme
4. Use the color picker to fine-tune hex values if needed

Migration complete!

See Also

• Data Model & Database — Understanding the new JSON format
• Getting Started — Fresh setup guide