Official UI Toolkit migration guide

Hi @benoitd_unity,

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.

 

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.

 

@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 (Edit: Please see the discussion below, deleting Library and reinstalling UI Builder seems to help).

 

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 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:

Also, this one goes on constantly in console:

 

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.TextInputBaseField`1+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.TextInputBaseField`1+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.GUIUtilityrocessEvent(Int32, IntPtr, Boolean&) (at /Users/bokken/buildslave/unity/build/Modules/IMGUI/GUIUtility.cs:189)

 

Thanks for clearing that up for me.

 

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<VisualElement> 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.

 

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

 

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

 

Right, sorry, I forgot to precise.
I'm on Unity 2021.2.0b7. I also tried with a previous beta, 0b4.
It works with 2021.1, but I can't use it as the package I'm developing uses quite some C#9.0 features.
Thanks!

 

I see! To be honest I never tried to install the package manually until now, but I wanted to try since preview.16 apparently fixed an issue regarding missing font asset warnings. I'll revert back to how it was.

So, is the UI toolkit that is bundled with Unity 2021.2 updated in the same way as the package? / Am I getting these updates?

Thanks!

 

This has been a nightmare to upgrade 2020.3 from preview 14 to 16.

After adding the assembly reference and adding UIElementsModual, I have 100's of "The type or namespace" errors. Some of them have assembly references that I can add "Unity.Mathematics", "Cinemachine", etc. I'm randomly adding a dozen+ of them to the list, this seems somewhat absurd. You can't expect that everyone who uses UIToolkit is going to create this assembly reference file?

What do I add for these?
does not exist in the namespace 'UnityEngine.VFX'
does not exist in the namespace 'TMPro'

Then I have asset store purchases that have namespaces... What do I need to do for each of these? There is no "Digger" reference, do i need to create something for all my purchased assets too?

Assets\Digger\Sources\Digger\Editor\Upgrading.cs(4,14): error CS0234: The type or namespace name 'Unsafe' does not exist in the namespace 'Digger' (are you missing an assembly reference?)
Assets\Plugins\Easy performant outline\Scripts\PipelineAssetUtility.cs(106,23): error CS0246: The type or namespace name 'ForwardRendererData' could not be found (are you missing a using directive or an assembly reference?)

 

Okay great! Thanks a lot for the clarification

 

I removed the Assembly Definition asset to get it to compile. I was then able to use the object explorer to find the assemblies for the unity namespaces I'm using. I'm still stuck unable to reference some of the asset store included references.

For instance:
Assets\Digger\Sources\Tests\Editor\VoxelTests.cs(3,7): error CS0246: The type or namespace name 'NUnit' could not be found

Object explorer says NUnit is a member of nunit.framework, but I don't see that as an option to add as an assembly reference. (dll exists in Library\PackageCache\com.unity.ext.nunit@1.0.6\net35\unity-custom\nunit.framework.dll)

Another even more confusing one is:
Assets\Digger\Sources\Digger\Editor\Upgrading2.cs(4,14): error CS0234: The type or namespace name 'Unsafe' does not exist in the namespace 'Digger'

Where Digger is a member of the Assembly-CSharp-Editor project (the main unity game c# project). It's code that was added via package to the assets directory. Is there a way I can reference it? Or?

 

In my case for a number of my assets I had to add an assembly definition file inside each "Editor" folder that only compiles that folder for the editor - see this thread:

https://forum.unity.com/threads/assembly-definition-woes.509541/

As the scripts inside the Editor folder generally depended on scripts from elsewhere in that asset, I would then need to create a regular assembly definition at the root of that asset. I then needed to add the asset assembly file to the assembly definition reference section in the asset editor assembly and to the main assembly file.

 

Is this becoming standard? I personally use assembly definitions in every one of my projects, but it seems odd to force them onto users, it's a lot to communicate to beginners (I understand this is a preview package, just speaking generally.)

If not, I'd be interested to hear why they've become a requirement for this package.
I'm hearing compilation order - I imagine there's something weird going on specifically with UIT's requirements.

 

Thanks @antoine-unity, @uMathieu

We have tried to use the package Copycatz, but we didn't manage to make it work unfortunately.

We are ready to convert our old canvas with the GUIsystem made with Unity 2019 version, into the new UIBuilder.

You said we can do it "manually" : does it mean we have to start all over again the UI of our app with UIbuilder?, or is there any way we could convert our UI made on the GUI System from the Unity version 2019 into the UiBuilder version 2020.2.4f ?
Is your Manual going to help in this matter?

 

Hmm, following this guide on Unity 2020.3.1f, after creating an assembly definition precisely as per the above I can no longer compile because UI Toolkit is no longer available during compilation (e.g. UIDocument is no longer present, so I get a compile error).
This happens with or without the upgrade (I am on preview-14).
Simply deleting the assembly definition again fixes the issue.

 

Hey there!

I'm using 2021.1.22f and ui toolkit 17, and I'm having this critical error when subscenes get imported :

Error: Could not load signature of UnityEngine.UIElements.InputSystem.InputSystemEventSystem:get_focusedPanel due to: Could not resolve type with token 01000024 (from typeref, class/assembly UnityEngine.UIElements.RuntimePanel, UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null) assembly:UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null type:UnityEngine.UIElements.RuntimePanel membernull) signature:<none>
Crash!!!

I currently don't even have any UIDocument in the scene or anything, just imported the package and setup the assembly definition (I don't have any compile errors).

deleting library folder didn't help, reimport all didn't help. Any suggestions ? thanks !

 

Thanks for reaching out, yes i'm using DOTS.

I just reproduced the issue within 10 minutes or so, in a new project, here's the steps :

1. Create new project with 2021.1.22f1 (3D hdrp sample)
2. Close unity
3. Swap out package manifest (see manifest below)
4. open project again
5. setup assembly def just in Assets, I called it RootAssembly (add UnityEditor.UIElementsModule + Unity.InputSystem, remove auto referenced and toggle by guid, like in this guide explained)
6. Rightclick in hierarchy > create new subscene (it will be open by default)
7. close subscene (this will trigger the reimport, at this point an error in the console should appear)
8. look at Logs folder (AssetImportWorker0.log), scroll down a bit and you'll find the error message i posted previously


The manifest I use (you can copy paste as is):

{
"dependencies": {
"com.unity.2d.sprite": "1.0.0",
"com.unity.addressables": "1.18.9",
"com.unity.cinemachine": "2.7.8",
"com.unity.collab-proxy": "1.9.0",
"com.unity.dots.editor": "0.12.0-preview.6",
"com.unity.ide.rider": "3.0.7",
"com.unity.ide.visualstudio": "2.0.11",
"com.unity.ide.vscode": "1.2.4",
"com.unity.inputsystem": "1.0.2",
"com.unity.platforms.windows": "0.10.0-preview.10",
"com.unity.polybrush": "1.1.2",
"com.unity.render-pipelines.high-definition": "11.0.0",
"com.unity.rendering.hybrid": "0.11.0-preview.44",
"com.unity.test-framework": "1.1.29",
"com.unity.textmeshpro": "3.0.6",
"com.unity.timeline": "1.5.6",
"com.unity.ui": "1.0.0-preview.17",
"com.unity.visualscripting": "1.6.1",
"com.unity.modules.ai": "1.0.0",
"com.unity.modules.androidjni": "1.0.0",
"com.unity.modules.animation": "1.0.0",
"com.unity.modules.assetbundle": "1.0.0",
"com.unity.modules.audio": "1.0.0",
"com.unity.modules.cloth": "1.0.0",
"com.unity.modules.director": "1.0.0",
"com.unity.modules.imageconversion": "1.0.0",
"com.unity.modules.imgui": "1.0.0",
"com.unity.modules.jsonserialize": "1.0.0",
"com.unity.modules.particlesystem": "1.0.0",
"com.unity.modules.physics": "1.0.0",
"com.unity.modules.physics2d": "1.0.0",
"com.unity.modules.screencapture": "1.0.0",
"com.unity.modules.terrain": "1.0.0",
"com.unity.modules.terrainphysics": "1.0.0",
"com.unity.modules.tilemap": "1.0.0",
"com.unity.modules.ui": "1.0.0",
"com.unity.modules.uielements": "1.0.0",
"com.unity.modules.umbra": "1.0.0",
"com.unity.modules.unityanalytics": "1.0.0",
"com.unity.modules.unitywebrequest": "1.0.0",
"com.unity.modules.unitywebrequestassetbundle": "1.0.0",
"com.unity.modules.unitywebrequestaudio": "1.0.0",
"com.unity.modules.unitywebrequesttexture": "1.0.0",
"com.unity.modules.unitywebrequestwww": "1.0.0",
"com.unity.modules.vehicles": "1.0.0",
"com.unity.modules.video": "1.0.0",
"com.unity.modules.vr": "1.0.0",
"com.unity.modules.wind": "1.0.0",
"com.unity.modules.xr": "1.0.0"
}
}

Thanks for investigating! It is quite a crucial bug because no subscene works anymore

 

Hello @JuliaP_Unity ,

I run in the same issue.
Is has been a lingering issue when using Entities in combination with both UITK and New Input system packages.

here is what I have as trace i nhte assertImportLog :

Code (CSharp):

1. Symbol file LoadedFromMemory is not a mono symbol file
2. Error: Could not load signature of Unity.UI.Builder.BuilderTextShadow:.ctor due to: Could not resolve type with token 010000e6 (from typeref, class/assembly UnityEngine.UIElements.StyleTextShadow, UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null) assembly:UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null type:UnityEngine.UIElements.StyleTextShadow member:(null) signature:<none>
3. Error: Could not load signature of UnityEngine.UIElements.InputSystem.InputSystemEventSystem:get_focusedPanel due to: Could not resolve type with token 01000022 (from typeref, class/assembly UnityEngine.UIElements.RuntimePanel, UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null) assembly:UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null type:UnityEngine.UIElements.RuntimePanel member:(null) signature:<none>
4. ..\mono\metadata\custom-attrs.c:1273: Could not load type UnityEngine.UIElements.UIDocument, UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null while decoding custom attribute: (null) assembly:<unknown assembly> type:UnityEngine.UIElements.UIDocument, UnityEngine.UIElementsModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null member:(null) signature:<none>
5.  
6. Crash!!!

As far as I can tell it has to do with a change the way unity build and signs it's package manifest. this issue was not present in 2021 last time I check but since it's recommended for DOTS to remain on 2020, we face the issue...
I think there was a similar issue wit hthe UITK package alone in int's previous version (15 and lower) but it was resolved.
Now entiteis and UITK (alone) work together with subscene. Entites and new input (alone) work togetehr wit hsubscene
but Entites+UITK+New Input don't work together in subscene (even when the subscene is empty...) but without subscene there is no conflict/issue.

 

@JuliaP_Unity,
I tryied pushing investigation a bit on this one but with no luck (I'm well out my depth ).
My understanding is that when using DOTS subscene, the asset importer run a headless unity instance to convert the subscene to entities and cache the serialized version of the sub scene.
This headless version crashes and restart undefinitly leading to a pile up of assetImportWorker log in error.
You'll find attached on of the crash log.

 

I just tried to follow this guide going from 2021.1.2 to 2021.2.0f1 and failed.
I force opened the project in safe mode (this would be a handy option to add to unity hub BTW)
I removed the UI Toolkit from package manager, and no "Asset Converter" popped up.
I checked the menu location specified, and there was no asset converter listed.

I thought I read it wrong, and maybe I should have opened my project in 2021.2 FIRST and undergone the rest of the tutorial, but that fell apart to.

For now I am just opening the project in the new version I want and manually implemented the broken and or needed UI document / object UITK objects.

I AM however flooded with errors now that I have mentioned here:
https://forum.unity.com/threads/une...spamming-console-after-unity-upgrade.1192108/

 

Edit: This guide is not for the old unity version. Upgraded the whole project to Unity 2021. Seems to work again

Hi,

not sure if I missed something essential here. I added the assembly as described after the "UI Document not found" error occurred today.

Facts:

• Unity 2020.3.16f1
• UI Builder 1.0.0-preview.18
• UI Toolkit 1.0.0-preview.17

My Warnings / Errors

Code (CSharp):

1. Assembly for Assembly Definition File 'Assets/UI Toolkit/UIAssembly.asmdef' will not be compiled, because it has no scripts associated with it.
2. UnityEditor.Scripting.ScriptCompilation.EditorCompilationInterface:CompileScriptsNoStop (UnityEditor.Scripting.ScriptCompilation.EditorScriptCompilationOptions,UnityEditor.BuildTargetGroup,UnityEditor.BuildTarget,string[])
3.  
4. Assets\Scripts\UIController.cs(11,12): error CS0246: The type or namespace name 'UIDocument' could not be found (are you missing a using directive or an assembly reference?)

 

With 2020.3.25f1 everything was fine. I just upgraded from Unity 2020.3.25f1 to 2020.3.30f1. And now I got the following errors:

Code (CSharp):

1. error CS0234: The type or namespace name 'UIDocument' does not exist in the namespace 'UnityEngine.UIElements' (are you missing an assembly reference?)
2. Shader error in 'Hidden/TextCore/Editor/Distance Field SSD': Couldn't open include file 'TextCore_Properties.cginc'. at line 60

What steps I should follow in this scenario?

 

Eventually I created an assembly definition and that solved the issue. I just totally surprised that I have to do that even if I upgrade from Unity 2020.3.25f1 to 2020.3.30f1. Especially since I am using the new Input System and DOTS now the assembly definition looks like this:

 

I also ran in to partially the same issue as DevViktora posted. While I do not have any compile errors I get a shader error

Shader error in 'Hidden/TextCore/Editor/Distance Field SSD': Couldn't open include file 'TextCore_Properties.cginc'. at line 60

I do have Asmdefs for my project (not auto references, manually referencing UnityEngine.UIElementsModule). If I try manually reimporting the offending file

UI Toolkit/Shaders/TextCore-SDF-SSD

it keeps throwing the same error.

Since it's a shader related issue I should point out that I am using URP. It's worth noting that the error doesn't persist. Clearing the console gets rid of it, but like mentioned a reimport of said file causes it to appear again.

Unity 2020.3.30f1, here are my packages:

 

Was that guide ever published @uMathieu? The only official reference covering this that I've found is this https://docs.unity3d.com/Manual/UIE-Transitioning-From-UGUI.html.

As @benoitwiener pointed out, for UI-heavy applications it is not trivial how to minimize the amount of UI that must be re-done from scratch.

I asked about this issue here too https://forum.unity.com/threads/ugui-or-ui-toolkit.936155/#post-8556056