Authoring Workflow
Authoring UI is aimed to be seamless. You author your UI as usual.
- Create a canvas
- Create children UI elements
- Parent and group elements together
The major difference is where the UI is supposed to live. Instead, the UI lives in a subscene. This is so that the GameObjects are converted to their entity format.
To create a subscene, right click in your Hierarchy Window and select, "New Subscene." You can create an empty subscene now and move GameObjects to the subscene later or create subscenes from a selection of GameObjects.
Subscenes convert your GameObjects into an Entity on a background thread so not all Unity APIs are supported.
One of the caveats of the using UGUI and Unity's subscenes is that data needs to be embedded into MonoBehaviours.
Because UGUI needs to always update to keep the data relevant, the data only lives when the subscene is opened. To
work around this, we bake transform data to a ScriptableObject called the BakedCanvasData and we read this data on
conversion.
Right click in your project view and select UGUIDOTS -> BakedCanvasInfomation . This will create a ScriptableObject
where we can register and copy the transform data.
Add the BakedCanvasDataProxy to your Canvas. Drag your Scriptable Object into the Baked Canvas Data field.
When first adding the component, you will get a warning stating:
The Canvas' transform hierarchy has not yet been baked.
Click the Bake Canvas Hierarchy button to bake the data to the Scriptable Object. Canvases that are not baked will throw a warning message in the Console stating that conversion will be skipped. All baked canvases will store the Instance ID at that point in time. This is how each canvas is mapped.
When baking infomation, make sure that your screen resolution matches your ideal reference resolution that you are working with. This ensures that your initial transform has a 1:1 ratio of what you are currently editing in.
So if your reference resolution is 1920 x 1080, ensure your game view has a resolution of 1920 x 1080.
If your structural hierarchy changes, it's highly recommended that your BakedCanvasData is updated with the new
structure of the hierarchy. In this case, you would click the Update Baked Canvas button, so that the representation
at the Instance ID is updated.
Click the Remove Baked Canvas data to remove the baked information from the Scriptable Object. This will set the
Instance ID to 0, which is an invalid ID.
Currently on Filled and Simple images are supported. Tiled and sliced images will throw an error during conversion.
When authoring Filled Images, it is recommended to use the DefaultImage material which can be found in
UGUIDOTS/Materials. Please see more information on the Images page.
Input is authored via the PrimaryMouseAuthoring and CursorAuthoring components. The PrimaryMouseAuthoring is
specifically used for Standalone PC/Mac/Linux and stores a KeyCode to detect clicks.
The CursorAuthoring component stores how many clicks you want to account for. This is generally used for mobile,
where you can use multiple fingers as inputs.
To interface with URP, we use a Scriptable Render Pass (SRP), which executes the rendering step. The SRP is typically
called the an Orthographic Render Pass. To create one, in your Forward Renderer asset, click Add Renderer Feature ->
Orthographic Render Feature.
The render feature must be linked with the OrthographicRenderSystem. This is done via the RenderCommandAuthoring
component. You must assign the RenderFeature in the component and a runtime ConvertToEntity. This cannot be done
in subscenes due to limitations of adding managed components and baking that data in subscenes. You may get an error
in the console about the subscene header missing.
