UI Toolkit migration guide

[benoitd_unity]

Updated migration guide!

With the preview.15 and preview.16 updates, here come the new details you’ll need to know to both move between package versions and from package to 2021.2

NOTE: You need both UI Toolkit and UI Builder packages to be on version preview.15 or preview.16 if you want to use both, as they’re not compatible with other versions. We highly recommend using preview.16 due to important fixes.

Package version migration guide

This guide provides step-by-step instructions for those looking to upgrade all projects using the UI Toolkit Package (com.unity.ui) for runtime assets from preview.14, preview.15, or preview.16. The steps should be valid for editor versions 2020.3.xxx and 2021.1.xxx. Due to some issues with IL2CPP, in order to make builds it is required to use the most recent version of the Unity Editor.

NOTE: version preview.15 had serious issues and was quickly replaced by preview.16, we highly recommend going to preview.16 straight away.

Migration process
Project Setup

• Open your project as usual with the desired Unity version.

• Update the UI Toolkit package using the Package Manager.

• If you don’t yet have one, create an Assembly Definition on your project either through the Assets menu or through right-clicking on your Project window and selecting Create > Assembly Definition. If you have an Assembly Definition already, follow the next step to make sure the references are set correctly anyway.
  

• Remove the “Auto Referenced” option on the Assembly Definition. Under “Assembly Definition References”, unselect “Use GUIDs” and add a reference to the “UnityEngine.UIElementsModule”. By doing these changes, we guarantee the order of compilation will be the expected one (your project will compile after the UI Toolkit package). Don’t forget to click “Apply” in the inspector for the Assembly Definition.

• If you have other assemblies you reference (e.g. Addressables, Cinemachine, Timeline), you’ll have to add those Assembly Definition References as well.
  

Known issues
This section addresses known issues with migrating UI Toolkit from package version 14 to 15. We’re working on fixing them for future updates.

Editor text is missing when using System Font preference (preview.15)
NOTE: update to preview.16 to avoid having this issue

• Open a project that is not using the UI Toolkit package or remove it from your project

• Open Preferences > General and change the setting from System Font to Inter

• You can now add your project containing the UI Toolkit package or re-add it to the current project.

Editor text is missing or broken after saving a scene or building the player
NOTE: update to preview.16 to avoid having this issue

• Close and reopen the project.

• If the problem appears to happen without building the player, try cleaning the Library folder by either deleting it with Unity not running, or selecting “Reimport All” from the Project view inside Unity.

Text stop showing up in Runtime

• Create a new Panel Settings Asset.
  

• Set the default UITK text asset in the Inspector when selecting the new Panel Asset.
  

• Reference the new Panel Asset for Panel Settings in the UIDocument.
  

Runtime asset migration guide

This guide provides step-by-step instructions for those looking to upgrade all projects using the UI Toolkit Package (com.unity.ui) for runtime assets to 2021.2. Several issues will be addressed in a future beta build of the Editor, which will simplify the update process.

Prerequisites
This migration guide is designed to migrate the following versions of Unity to 2021.2:

• 2020.3
• 2021.1

Package compatibility
The migration guide is compatible with the following package versions of com.unity.ui:

• com.unity.ui Version 1.0.0-preview.14
• com.unity.ui Version 1.0.0-preview.15
• com.unity.ui Version 1.0.0-preview.16

NOTE: version preview.15 had serious issues and was quickly replaced by preview.16, we highly recommend going to preview.16 straight away.

Migration process
Project Startup - for preview.14, preview.15 and preview.16 versions

• Open the project you wish to update (2020.3 or 2021.1) in Safe Mode.

• Ignore all compilation errors.

• From the Editor toolbar, go to Window > Package Manager.

• Choose the UI Toolkit package (com.unity.ui), then select Remove.

UI Toolkit Package Asset Converter
After removal of UI Toolkit, the UI Toolkit Package Asset Converter dialog box appears. You can also access it from the Editor toolbar, under Window > UI Toolkit > Package Asset Converter.

Verify the selected assets are correct, then select Convert to start the conversion process.

Attach the default style sheet - for preview.14 version only
Panel Settings styles now use a new Theme asset format. You must manually create and assign one to the existing PanelSettings. To create a new default style sheet:

• In the project window, right-click and select Create > UI Toolkit > Panel Settings Asset to create a new PanelSettings. This imports the default theme style sheet into your project. You can delete the PanelSettings asset you just created.
• Under Panel Settings, change the Theme Style Sheet parameter for each PanelSettings asset in your project to the UnityDefaultRuntimeTheme asset.

Known issues
This section addresses known issues with migrating UI Toolkit from packages to Core.

Default style sheets
Affected versions:

• 2020.3
• 2021.1

Default style sheets are not automatically created and assigned during the migration from Package Version preview.14 to 2021.2. This issue is fixed for com.unity.ui Versions 1.0.0-preview.15 and preview.16.

TextCore assets
Affected versions:

• 2021.2.0b1

In 2021.2.0b1, the package conversion tool does not convert TextCore assets. A new version of 2021.2 will come soon with a fix to this problem. You must recreate the following assets in your project:

• FontAsset
• SpriteAsset
• TextColorGradient
• TextStyleSheet
• PanelTextSettings

Support for migrating TextCore assets will be added to UI Toolkit Package Asset Converter in the near future.

[benoitwiener]

Hi @[benoitd_unity]( UI Toolkit migration guide members/benoitd_unity.1632639/),

Do you have also a migration guide for project with UI (made with GUI and canvas system) as an overlay to convert into UIToolkit?

thanks for your reply

P.S: If needed I can post a new thread if it doesn’t exist. In reality we have a project with a lot of GUI in overlay (it’s an app) and we have performance issues because of the canvas system and we would like to use the UIbuilder to improve our performance and also the simplicity for our designers. But we would like to be sure we don’t have to start over with the new UIToolkit system again.

[uMathieu]

@benoitwiener We have one such guide in the works. We’ll keep you updated once it’s up!

[benoitwiener]

@uMathieu

@benoitwiener We have one such guide in the works. We’ll keep you updated once it’s up!

Thanks for your answer.
But do you mean, it is already possible and easy to convert from old UI system to the new UItoolkit system in our project ? (If yes from which version?)
if it’s the case it could save us months of work!!

So could you elaborate your answer?
Do you mean the feature to convert is already implemented and we can use it but you still have to do a guide for that? or do you mean the feature is not yet implemented but planned?

Thanks for the details.

P.S: we would like to know if you convert your old UI and have performance issues (because too many batches) it will be solved because with the migration to the new system.

[antoine-unity]

What @uMathieu meant is that we will publish a manual to explain how to migrate manually from UGUI system to the UI Toolkit system.
We have no plans to make this automated – but you could have a look at this Asset Store plugin (not affiliated to Unity).

Unity ID

[oobartez]

@JuliaP_Unity , @benoitd_unity regarding this:

Editor text is missing or broken after building the player
Close and reopen the project.

I understand that this is something you are aware of, but it is happening all the time, after a few minutes (or less than a minute) of using Unity. As such it is not currently possible to migrate to preview-15.

We saw that you have fixed A LOT of bugs in preview-15 which is great! But migrating would make it impossible for our team to work with our project (Edit: Please see the discussion below, deleting Library and reinstalling UI Builder seems to help).

[JuliaP_Unity]

@oobartez

@JuliaP_Unity , @benoitd_unity regarding this:

I understand that this is something you are aware of, but it is happening all the time, after a few minutes (or less than a minute) of using Unity. As such it is not currently possible to migrate to preview-15.

We saw that you have fixed A LOT of bugs in preview-15 which is great! But migrating would make it impossible for our team to work with our project, so as it is, we are stuck with preview-14 and all its bugs.

I’m sorry you’re facing issues but we had to publish this version in order to unblock a lot of our users, and we’ll be working on fixing other issues right away, including this one. Can you try doing a “Reimport All” from the Project view to see if this improves? In our experience it has helped!

[oobartez]

@JuliaP_Unity

I’m sorry you’re facing issues but we had to publish this version in order to unblock a lot of our users, and we’ll be working on fixing other issues right away, including this one. Can you try doing a “Reimport All” from the Project view to see if this improves? In our experience it has helped!

Thank you for the reply! As you suggested, we deleted the Library folder and uninstalled and reinstalled UI Builder. It appears to have helped, I’ll keep you posted.

[JuliaP_Unity]

@oobartez

Thank you for the reply! As you suggested, we deleted the Library folder and uninstalled and reinstalled UI Builder. It appears to have helped, I’ll keep you posted.

Thanks for letting me know, I’m updating the troubleshooting text to mention cleaning the Library (Reimport All does the same) can help

[pawelduda]

@JuliaP_Unity

Thanks for letting me know, I’m updating the troubleshooting text to mention cleaning the Library (Reimport All does the same) can help

@JuliaP_Unity To update on the issue @oobartez was describing on my behalf.

After Reimport All etc. editor still misbehaves each time I press Ctrl + S. Most of the text on labels is gone:

Here is the warning that is printed to the console during this:

The package cache was invalidated and rebuilt because the following immutable asset(s) were unexpectedly altered:
Packages/com.unity.ui/PackageResources/Fonts/Inter/Inter-Regular SDF.asset

UnityEditor.EditorApplication:Internal_CallGlobalEventHandler ()

Also, this one goes on constantly in console:

A meta data file (.meta) exists but its folder ‘Packages/com.unity.ui/Core/Delegates’ can’t be found, and has been created. Empty directories cannot be stored in version control, so it’s assumed that the meta data file is for an empty directory in version control. When moving or deleting folders outside of Unity, please ensure that the corresponding .meta file is moved or deleted along with it.

[JuliaP_Unity]

Thanks for all the info @pawelduda , we’re taking note here and this should help us find a fix! Let us know if you find anything else

[JuliaP_Unity]

For people following this thread, preview.16 has been published with fixes to some issues discussed here. The migration guide contents have been updated. Cheers!

[tenukii]

Now I’m stuck at this error - cleared library:

IndexOutOfRangeException: Index was outside the bounds of the array.
UnityEngine.UIElements.TextCoreHandle.GetLineHeight (System.Int32 characterIndex, UnityEngine.UIElements.MeshGenerationContextUtils+TextParams textParams, System.Single textScaling, System.Single pixelPerPoint) (at Library/PackageCache/com.unity.ui@1.0.0-preview.16/Core/Text/TextHandle.cs:175)
UnityEngine.UIElements.TextInputBaseField1+TextInputBase[TValueType].DrawWithTextSelectionAndCursor (UnityEngine.UIElements.MeshGenerationContext mgc, System.String newText, System.Single pixelsPerPoint) (at Library/PackageCache/com.unity.ui@1.0.0-preview.16/Core/Controls/TextInputFieldBase.cs:759) UnityEngine.UIElements.TextInputBaseField1+TextInputBase[TValueType].OnGenerateVisualContent (UnityEngine.UIElements.MeshGenerationContext mgc) (at Library/PackageCache/com.unity.ui@1.0.0-preview.16/Core/Controls/TextInputFieldBase.cs:735)
UnityEngine.UIElements.VisualElement.InvokeGenerateVisualContent (UnityEngine.UIElements.MeshGenerationContext mgc) (at Library/PackageCache/com.unity.ui@1.0.0-preview.16/Core/VisualElement.cs:1456)
UnityEngine.GUIUtility:ProcessEvent(Int32, IntPtr, Boolean&) (at /Users/bokken/buildslave/unity/build/Modules/IMGUI/GUIUtility.cs:189)

[JuliaP_Unity]

@tenukii I’m not sure what’s happening there, but I believed you commented earlier about it not being clear whether you have to convert assets or not and the answer is that if you’re not moving to 2021.2, you do not want to convert your assets indeed.

This migration guide has 2 separate parts: 1 for moving between the Package versions since there was an important change from 14 to 15 (adding the assembly definition) and explaining potential problems you may face; the other is for moving between the Package and 2021.2.

Hope this is clearer now!

[tenukii]

Thanks for clearing that up for me.

[tenukii]

@tenukii

Now I’m stuck at this error - cleared library:

IndexOutOfRangeException: Index was outside the bounds of the array.
UnityEngine.UIElements.TextCoreHandle.GetLineHeight (System.Int32 …

Found a ‘fix’ although it means removing functionality, hopefully this is temporary:

Turns out .Focus() doesn’t work on TextFields anymore - or at least the pre .15 way of doing it. I did figure out I could get the ‘unity-text-input’ reference with Q to set the color, etc, but Focus() on that or the TextField both throw this error.

Hopefully I’m just doing it wrong and it isn’t a bug in UIToolkit.

[influxus]

Just wondering, if a future package might enable migrating past preview.14 without the assembly definition step?

[JuliaP_Unity]

@influxus

Just wondering, if a future package might enable migrating past preview.14 without the assembly definition step?

Sadly no, from now on you’ll always need the assembly definition asset in order to guarantee the correct compilation order.

[CSStudentsGoe]

Hello,

After migrating to preview.16, I’ve got these two errors:

I tried deleting the Library folder and reimporting, but they remain. Any ideas?
Cheers

[JuliaP_Unity]

@CSStudentsGoe

Hello,

After migrating to preview.16, I’ve got these two errors:

I tried deleting the Library folder and reimporting, but they remain. Any ideas?
Cheers

What version of Unity are you on?