UI
UI
UI Components
To include UI in a level, a UI file must be loaded through a entity component. The UI canvas isn’t necessarily loaded in at run-time, and the loading of the canvas and enabling of the canvas can be controlled through script. The 3 available components to attach to level entities are: UI Canvas Asset Ref, UI Canvas Proxy Ref, and UI Canvas on Mesh. The UI Canvas Asset Ref is the component which contains the pointer to the canvas, as well as whether the canvas is loaded on awake. The canvas is able to directly communicate with the entity its attached to, without having an additional entity pointer. In scripting this entity is associated with loading and getting. The UI Canvas Proxy Ref has a pointer to the entity holding the canvas, and because it is a pointer modifying either canvas will modify the other — the canvases are shallow copies. The UI Canvas on Mesh does what expected, it places the the UI on a mesh which can be modified directly on the mesh.
UI Editor
Lumberyard’s UI system can’t be edited within the level, but rather through a separate panel, the UI Editor. The UI Editor can be docked within the editor, however like other windows cannot overlay the perspective window. The two options for opening the editor are circled in white below.
The UI Editor automatically creates an empty canvas, and to edit your canvas it must be loaded from a save file. Entities are referred to elements within the canvas. There are a list of preset elements which can be selected from the Slice Library, these elements include sliders, images, etc. To edit the properties of the canvas, simply deselect all entities (click within the hierarchy), and to edit elements select one as you would within the level.
Tools
The UI Editor consists of the following:
- Toolbar – Commonly used tools and settings
- Hierarchy pane – List of UI elements that you create
- UI canvas tab bar – Tabbed display of open canvases
- Viewport – Display of the UI elements on the current UI canvas
- Properties pane – Component properties for the selected element
- Animation Editor – Tool for animating UI elements
The UI Inspector isn’t the same inspector as the Entity Inspector, and has a customized Transform component for 2D elements. The elements can be anchored within the canvas/parent and the grid has a quick select of the typical anchors desired, but also percentages to the right for customization. The Pivot grid selection is for where the pivot of the specific element selected is, and can also be numerically customized.
The UI can be previewed with real-time UI effects without playing a specific level, since the information is local to the canvas and not the level. To preview the UI, select the preview button which will put the canvas into an intractable, non-editable state.
To import a font [NICOLE]
Scripting Interface
The UI in Lumberyard is incorporated in 2 parts, one part being attached to an entity in the perspective view and the other part is integrated into the UI editor. The UI editor component can’t directly communicate with any entity located in the level. Within the UI Editor, entities can only attach UI-specific components, which includes a Lua Script component. There is a separate reference documentation for Lua UI Scripting included within Lumberyard’s documentation, see resources.
If the script has a property of entity, that entity cannot be selected from level and is restricted to entities within the same canvas. To communicate with entities in the level, see below. This does also mean that canvases can be reused in multiple levels and projects without worrying about broken connections.
To send/receive messages from entities in the level, the level entities need a reference to the canvas and either the name in the hierarchy of that element or use of the Gameplay Bus. For level entities to reference a canvas, a component either need a reference to the entity holding the canvas or a component of proxy. Entities in the level and elements in the canvas can both reference the entity id of the canvas, through their own function calls. A common issue with communicating between the level and elements on the canvas is getting the EntityId of canvas entity. The level elements can get the canvas EntityId OnActivate, however this does depend on the order of components added into level, typically it is better practice to wait for first tick to call the function or listen to OnCanvasEntityLoaded (however the problem with waiting for this is in the case the canvas loads prior the function will never be called). The canvas element cannot get the EntityId of the canvas OnActivate, the function will not return an error but will return an invalid EntityId, the only option is to get the canvas EntityId on the first tick.
To have UI appear in the level and not be an overlay, the canvas must be set as a render texture. Render textures must have an assigned render target, which is a string that connects the canvas to a material. The render target in the canvas must match a material with the diffuse texture set to the same string, however if the canvas will be used in multiple instances different materials are required each with a variation on the render target string. For example, a render target: “$uicanvas” can have a diffuse materials: “$uicanvasLit”, “$uicanvasTest”, etc (no special characters or numbers can be part of the string).
