[unity] Support for UI Toolkit

[HaraldCsaszar]

Support for UI Toolkit (previously UIElements), most likely by providing a custom VisualElement subclass rendering Spine skeletons within the provided element layout context.

Requested via email: FMfcgzGkZsvwrjhxchhjMhSHCttZqNPC

[jjaine]

Any updates on this? Unity has recently published a blog post and a sample on how UI Toolkit can be used for runtime UI, and it's now recommended since Unity 2021 LTS. We have been using UI Toolkit for a long time, and would like to use Spine with it 😊 As a workaround, I think render textures could be used, but that seems quite overkill.

[HaraldCsaszar]

@jjaine Sorry for the late reply! While we have created a prototype implementation together with Unity some time ago, unfortunately there have been some major limitations in the UI Toolkit API at that time which made the integration too clunky to work with (and it even required API additions only present in Unity 2022.1, not in 2021.2). As a consequence, we decided to wait until the API has received the necessary changes. We have contacted Unity on the subject and should receive feedback hopefully soon on whether there have been any API additions which allow us to resolve the existing problems. We will post any info here as soon as we have received any update from Unity's side.

[HaraldCsaszar]

@jjaine We received feedback from Unity stating that the most important missing feature for our use case has now been added in Unity 2023.1 (not in 2022.x). Since 2023.1 however is still in Alpha state, I'm afraid it will take some more time until we will get to integrate the added feature and officially release a UI Toolkit compatible Spine component.

[jjaine]

Thanks for getting back to me about this! Good to hear that the work is in progress, and a bit about the schedule so we can evaluate our possibilities with Spine & UI Toolkit a bit better.

[gustavoboni]

Hi, any updates on this as 2023 is not on Alpha anymore and we are in the middle of the cycle of Unity 2022 LTS?

[HaraldCsaszar]

Sorry for the delay!

We have just uploaded experimental versions of a spine-unity integration for UI Toolkit we've developed together with Unity which are using the older UI Toolkit API compatible with Unity 2021.3 (likely also with 2021.2).

While this implementation comes with some ease-of-use drawbacks due to the limited UI Toolkit API available at these older versions, we thought that it would be good to share them with you nonetheless. A current limitation in this implementation is that you can't directly use SkeletonDataAsset asset references but instead have to add the file URL to the .uxml file as can be seen in the included TestSpine.uxml file: --skeleton-asset: url('./relative/path%20with%20spaces/to/my_SkeletonData.asset'); This line is then resolved and replaced with a longer asset url automatically. This is a major drawback which will be addressed in future releases (which should be possible in the latest UI Toolkit for Unity 2023.2), but until a new package is released, you can use the experimental packages below, provided on an as-is basis.

The packages below are compatible with the latest spine-unity runtime packages of the 4.0, 4.1 and 4.2 runtimes. Spine UITK extension package: http://esotericsoftware.com/files/runtimes/unity/ui-toolkit/experimental/SpineUITK-4.0-Unity2021.3-2024-06-21.unitypackage http://esotericsoftware.com/files/runtimes/unity/ui-toolkit/experimental/SpineUITK-4.1-Unity2021.3-2024-06-21.unitypackage http://esotericsoftware.com/files/runtimes/unity/ui-toolkit/experimental/SpineUITK-4.2-Unity2021.3-2024-06-21.unitypackage

Example projects using the latest spine-unity 4.0, 4.1 and 4.2 runtimes (as available today). http://esotericsoftware.com/files/runtimes/unity/ui-toolkit/experimental/SpineUITK-4.0-Unity2021.3-Example-2024-06-21.zip http://esotericsoftware.com/files/runtimes/unity/ui-toolkit/experimental/SpineUITK-4.1-Unity2021.3-Example-2024-06-21.zip http://esotericsoftware.com/files/runtimes/unity/ui-toolkit/experimental/SpineUITK-4.2-Unity2021.3-Example-2024-06-21.zip

We hope that this helps with your UI Toolkit projects.

[gustavoboni]

@HaraldCsaszar thank you for this. We are getting two errors when importing the extension, seems two methods are missing in MeshGenerator:

Assets\SpineUITK\SpineVisualElement.cs(318,74): error CS1061: 'MeshGeneratorUIElements' does not contain a definition for 'SubmeshIndexCount' and no accessible extension method 'SubmeshIndexCount' accepting a first argument of type 'MeshGeneratorUIElements' could be found (are you missing a using directive or an assembly reference?) Assets\SpineUITK\SpineVisualElement.cs(345,40): error CS1061: 'MeshGeneratorUIElements' does not contain a definition for 'GetMeshBounds' and no accessible extension method 'GetMeshBounds' accepting a first argument of type 'MeshGeneratorUIElements' could be found (are you missing a using directive or an assembly reference?)

[HaraldCsaszar]

@gustavoboni Then you're using an old version of the spine-unity runtime, with an old MeshGenerator base class. We've provided zip files for the latest 4.0, 4.1 and 4.2 runtimes.

You can also check out the zip files below the line "Example projects using the latest spine-unity 4.0, 4.1 and 4.2 runtimes (as available today)." These are Unity projects using the latest unitypackages successfully. If something does not work on your end, please have a look at the examples there.

[gustavoboni]

@HaraldCsaszar thanks, i was able to run it! Is there any way to workaround the limitation of not being able to set the SkeletonDataAsset? Would work if i set "--skeleton-asset" via script? In our case we have an inventory screen where we display in the ListView several items that are basically spine skeleton assets so basically i need to assign the skeletonDataAsset via script to each of the ListView elements.

[HaraldCsaszar]

@gustavoboni When adding a new SpineVisualElement to a document, you can manually add the section via a text editor to the uxml file at the respective element:

--skeleton-asset: url('./relative/path%20with%20spaces/to/my_SkeletonData.asset');

This line is then resolved and replaced with the longer asset url automatically. (I've updated the --skeleton-asset string in the above comment as well to show the shorter form)

[HaraldCsaszar]

Sorry for the long delay! With additions to the UI Toolkit API with Unity 2023.2, we are now happy to provide a more user-friendly experimental version of a Spine UI Toolkit integration package. This new version allows you to drag-and-drop select a SkeletonDataAsset instead of having to write an asset path string to your .uxml file, and provides dropdown popup lists to select the initial skin and animation from. Note that this version requires Unity 2023.2 or newer versions.

You can try the new com.esotericsoftware.spine.ui-toolkit UPM package via one of the following installation procedures:

A) You can install the package via the Unity Package Manager if you've installed the spine-unity runtime via the Package Manager as well, using the normal Add package from git URL .. button using the following git URL:

https://github.com/EsotericSoftware/spine-runtimes.git?path=spine-unity/Modules/com.esotericsoftware.ui-toolkit#4.2

B) If you've installed the spine-unity runtime via unitypackage, you need to download the package above and before adding it to your project remove the lines "com.esotericsoftware.spine.spine-unity": "4.1.21" from the package.json file (removing the spine-unity UPM package dependency). More comfortable official zip packages will be released in the future, this serves as a first test package to not keep you waiting longer than necessary.

For usage of the SpineVisualElement control element, you can check out the included UI Toolkit Example.unity example scene and SpineUIToolkit.uxml file which can be installed via the Samples tab after selecting the package in the Unity Package Manager window. The new SpineVisualElement can be found in the Unity UI Builder window under Library - Project - Custom Controls Spine - Unity - SpineVisualElement. It can be added to your hierarchy and configured as normal UI Toolkit elements while providing Spine skeleton attributes as well.

Please share your thoughts on the forum, especially if you encounter any problems or have ideas for improvement. Hope you like it! :)

[HaraldCsaszar]

The UPM package also requires the latest spine-unity package (4.2.75 or newer) for AttributeDrawer changes, sorry for the inconvenience! The latest spine-unity package is available for download: https://esotericsoftware.com/spine-unity-download