/UGUIDOTS

Converting UGUI to be DOTS compliant

Primary LanguageC#MIT LicenseMIT

UGUIDOTS

Logo done by Sabrina Lam

UGUIDots is a Data Oriented Tech Stack library aimed to bridge the gap in between Unity's WYSIWYG UI and the Entity Component System. This is a low level library which augments on top of Unity's UI and does not serve as a replacement - so the workflow of authoring UI designs in games largely remains the same.

Why do this?

A DOTS compliant UI is still underway (which will be based off of UIElements). Until then, I need a UI solution the works with the Scriptable Render Pipeline - without building too many custom tooling. Similarly - one that has the performance capabilities and low overhead for both mobile and desktops. That said supported platforms are primarily for:

  • Android
  • iOS (? - currently hard for me to test)
  • Linux 64 bit
  • macOS
  • Windows 64 bit

Beta/Experimental Content

Check out the develop branch of the repository for the redesigned system! This is something I've been working on lately and it redesigns how conversion and transformations are done. I haven't decided to merge this into the master branch as of late because I am trying to update the entire documentation and some features are missing.

Wiki

The wiki is currently being worked on and contains basic information about Image/Text pipelines.

Changelog

General purpose change log can be found here.

Contributions

If you would like to help contribute to the development of UGUIDots, please see the contribution guidelines here.

TODO

Support for the following will come over time - depends on the needs for my own game.

  • Canvas Scaling
  • Anchoring
  • Image stretching
  • Button actions
  • Button states (with color support)
  • Hierarchy based disabling
  • Text Rendering
  • Input fields
  • Subscene support
  • Support manual image / text batching of static UI elements (static analysis)

Installation

OpenUPM

There is currently a known issue with OpenUPM, where Unity internal scopes are added to the registry. After adding the package via OpenUPM, head over to the manifest file and delete the com.unity.* under the scopes entry.

cd <path-to-project>
openupm add com.initialprefabs.uguidots

Git Submodule

git submodule add https://github.com/InitialPrefabs/UGUIDots.git <path-to-folder>

Manually

Download the latest release and add it to your project directly.

QuickStart

Below are the basic steps to get the package working in game.

Setting up the Render Command

  • Set up project to use the Universal Render Pipeline
  • Add the RenderCommandAuthoring component with a scriptable render feature to a GameObject.
  • Add the ConvertToEntity component to the RenderCommandAuthoring GameObject

Converting GameObjects to Entities

  • Design your UI normally using the WYSWYG editor in Unity
  • Add the BatchedMeshAuthoring component to your root canvas
  • Build the batch on the BatchedMeshAuthoring component
  • Add the ConvertToEntity component to convert the GameObject hierarchy to its Entities' format

Setting up input

  • Add the MobileMouseInputAuthoring component to a GameObject for Mobile support
  • Add the StandaloneInputAuthoring component to a GameObject for Windows/macOS/*nix support
  • Put the GameObject into a subscene or add the ConvertToEntity component to it

Sample Repository

Please see the Sample repository here.

Dependencies

  • Unity 2020.1.x

Grab these from Unity's package manager.

  • Burst 1.3.4
  • Collections 0.12.0-preview.13
  • Entities 0.14.0-preview.18
  • Jobs 0.5.0-preview.14
  • Mathematics 1.2.1
  • TextMeshPro 3.0.1
  • UGUI 1.0.0
  • Universal RP 9.0.0-preview.35

Limitations

Development is still underway - so not all of the features Unity has by default is supported. Similarly - there are certain cases that are not accounted for, like sub canvases as I barely use features like that.

Credits

Some thanks to a few folks who've helped me figure out things along the way

  • Sabrina Lam (Logo artwork)
  • Valentina S.
  • Arthur D.
  • Mason R.