Tutorial: How to Interact with UI Using Lua This tutorial walks you through the steps to interact with UI using Lua, including loading and unloading UI

canvases, listening to and handling UI events, working with EBus to execute events that interact with UI

elements, and attaching scripts to UI elements. At the end of the tutorial you will have learned how to interact

with UI through Lua scripts that are attached to world entities or UI elements.

You will learn how to do the following:

Load a UI Canvas from script using the UiCanvasAssetRefBus

Listen to UI Canvas events from script

Load a UI Canvas from script using the UiCanvasManagerBus

Access UI Elements from a script attached to a world entity

Attach a script to a UI Element

Access UI Elements from a script attached to a UI Element

Use UI Element Notification buses in script to handle UI events

Prerequisites This tutorial assumes that you have completed Lumberyard Basics, Lua Scripting and EBus Usage

tutorial, and that you have knowledge of the following items:

Creating a basic level in Lumberyard.

Creating UI Canvases and UI Elements with the UI Editor.

Adding and interacting with Component Entities.

Lua Script basics.

Completed the tutorials listed under UI Creation.

Step 1: Load a UI Canvas from Script Using the UiCanvasAssetRefBus The first step in the tutorial is to load a UI Canvas from script using the UiCanvasAssetRefBus.

To load a UI Canvas from script using the UiCanvasAssetRefBus

1. Open up Lumberyard and create a new level.

a. Set the Heightmap Resolution to 128x128 and Texture Dimensions to 512x512.

2. In your new level, create a Component Entity.

3. Add a Lua Script component to the entity.

4. Create and assign a new script to the Lua Script component.

a. For this tutorial, we created a Lua Script called “UIEditorLuaTutorial.lua”.

5. Add a UI Canvas Asset Ref component to the entity and assign a new UI canvas to it.

a. For this tutorial, we created a blank UI Canvas called “tutorial_uicanvas-lua_01.uicanvas” and

saved it in the following location:

dev/SamplesProject/Levels/Samples/UIEditor_Lua_Sample/UI/Canvases/

b. We then used our newly created UI Canvas as a reference in the UI Canvas Asset Ref

component.

6. Load the UI canvas using the UiCanvasAssetRefBus by adding the following line of code to your

OnActivate function.

local canvasEntityId = UiCanvasAssetRefBus.Event.LoadCanvas(self.entityId)

7. You may notice that the mouse isn’t showing when you run. To show the mouse cursor, we need to use

the LyShineLua.ShowMouseCursor function. Add the following code in the script’s OnActivate

function:

LyShineLua.ShowMouseCursor(true)

Step 2: Listen to UI Canvas Events from Script After you load a canvas from script, you will listen to UI Canvas events from the script.

To listen to UI Canvas events from script

1. Add the following code in the script’s OnActivate function:

self.canvasHandler = UiCanvasNotificationBus.Connect(self, canvasEntityId)

2. Now that we are connected to the UiCanvasNotificationBus, you can declare an OnAction function

for your Lua script that will get called on canvas events. Add the following function to the script:

function UIEditorLuaTutorial:OnAction(entityID, actionName) end

3. Set up a button click action in the UI Canvas

a. In the UI Editor, open the UI Canvas created in Step 1.5 and add a button element

to your UI Canvas.

b. Select the button from the Hierarchy Pane and make sure that the Button component in the

Properties Pane is expanded.

c. Under Button > Interactable > Actions in the Properties Pane, enter an action name such as

“ButtonClicked” in the Click field.

d. Change the button text to “Options”

i. Feel free to stylize your button’s look as you please. For now we’ll move on with the

standard button template.

4. Listen for button clicks by adding the following code in the script’s OnAction function:

if (actionName == "ButtonClicked") then end

5. We want to clean up properly by disconnecting from the buses that we are connected to. Add the

following function to the script:

function UIEditorLuaTutorial:OnDeactivate() self.canvasHandler:Disconnect() end

Step 3: Load a UI Canvas from Script Using the UiCanvasManagerBus After setting up for UI Canvas events from script, you will load another UI Canvas on a button click using the

UiCanvasManagerBus.

To load a UI Canvas from script using the UiCanvasManagerBus

1. Open the UI Editor, create a second (blank) UI Canvas and save it out.

a. For this tutorial, we saved our second canvas as “tutorial_uicanvas-lua_02.uicanvas”,

in dev/SamplesProject/UI/Canvases/

2. Back to the Lua Editor, add the following code in the if statement of the script’s OnAction function:

-- Load the sub UI canvas local subCanvasEntityId = UiCanvasManagerBus.Broadcast.LoadCanvas("UI/Canvases/ tutorial_uicanvas-lua_02.uicanvas")

Ensure that the path passed to LoadCanvas() matches that of your second canvas.

Step 4: Access UI Elements from a Script Attached to a World Entity After learning how to load a UI Canvas using the UiCanvasManagerBus, you will learn how to access UI

Elements from your script.

To access UI Elements from a script attached to a world entity

1. In the UI Editor, add a text UI Element to the first canvas.

2. Give the text UI Element a unique name such as “TitleText”.

3. Use the UiCanvasBus to get the entityId of the text UI Element.

Add the following code in the OnActivate function of the script:

local text = UiCanvasBus.Event.FindElementByName(canvasEntityId, "TitleText")

Ensure that the string passed to FindElementByName matches the name of the text UI Element in the

UI Editor, and that the name of the text UI Element is unique.

4. Use the UiTextBus to change the text string. Add the following code in the OnActivate function of the

script:

UiTextBus.Event.SetText(text, "Main Menu")

Step 5: Attach a Script to a UI Element After interacting with UI from a script attached to a world entity, you will learn how to attach a script to a UI

Element.

To attach a script to a UI Element

1. Open the second UI Canvas you created and add an image that will be used as the background of the

canvas.

a. For this tutorial, we’ve created a UI Canvas called “tutorial_uicanvas-lua_02.uicanvas” and

saved it in the following location:

dev/SamplesProject/Levels/Samples/UIEditor_Lua_Sample/UI/Canvases/

2. In the second UI Canvas, add a Lua Script component to the background image UI Element. To add a

Lua Script component in the UI Editor, do the following:

a. Select the background image UI Element in the UI Editor.

b. From the Properties Pane, click on Add Component… and choose Lua Script

c. Set the script property of the Lua Script component to a newly created Lua script.

i. For this tutorial, we created and saved a blank Lua Script called

“UIEditorLuaSubTutorial.lua” in the following location: dev/SamplesProject/Scripts/ and

added this file to the Script field of the Lua Script component in the UI Editor.

Step 6: Access UI Elements from a Script Attached to a UI Element After attaching a script to a UI Element, you will access UI Elements from that script.

To access UI Elements from a script attached to a UI Element

1. On the second Lua Script, which we added to the UI Element in Step 5, create a primary local table and

add the properties sub-table.

local UIEditorLuaSubTutorial = { Properties = { }, } return UIEditorLuaSubTutorial

2. Add the following code in the Properties sub-table:

Image = {default = EntityId()}, Slider = {default = EntityId()}, BackButton = {default = EntityId()},

3. In the UI Editor, open your second UI Canvas. You should now see additional fields above the Script

field, that’s mimicking the properties table we just set within the Lua script, attached to the UI element.

4. In those newly created fields, go ahead and add an image, a slider and a button as children of the

background image UI Element.

5. Assign the new UI Elements to the new script properties. In the UI Editor:

a. Select the background image UI Element to show the newly added script components

mentioned in Step 6.3.

b. Drag the image UI Element from the hierarchy pane to the Image property in the Properties

pane.

i. Go ahead add a texture file in the Sprite field so that we can see the Lua interaction with

this particular UI Element in the upcoming steps.

c. Drag the slider UI Element from the hierarchy pane to the Slider property in the Properties

pane.

d. Drag the Button UI Element from the hierarchy pane to the BackButton property in the

Properties pane.

i. Let’s also change the button text from “Button” to “Back".

e. Your final properties table should look like this:

6. Access the slider UI Element from script and initialize its minimum, maximum and current value.

Add the following code to the OnActivate function in your second script (attached to your UI element):

UiSliderBus.Event.SetMinValue(self.Properties.Slider, 0) UiSliderBus.Event.SetMaxValue(self.Properties.Slider, 360) UiSliderBus.Event.SetValue(self.Properties.Slider, 0)

Step 7: Use UI Notification Buses in Script to Handle UI Events After accessing UI Elements from script, you will listen to and handle UI events from script using the UI

notification buses. Each interactable UI Element has a notification bus that you can listen to and handle events

associated with that interactable.

1. Listen to button and slider events. Add the following code in the OnActivate method of your second

script:

self.sliderHandler = UiSliderNotificationBus.Connect(self, self.Properties.Slider) self.buttonHandler = UiButtonNotificationBus.Connect(self, self.Properties.BackButton)

2. Now that we are connected to the slider and button notification buses, you can declare functions for

your Lua script that will handle the slider and button events. Add the following functions to the second

script:

function UIEditorLuaSubTutorial:OnSliderValueChanging(value) self:HandleSliderValueChange(value) end function UIEditorLuaSubTutorial:OnSliderValueChanged(value) self:HandleSliderValueChange(value) end function UIEditorLuaSubTutorial:OnButtonClick() end function UIEditorLuaSubTutorial:HandleSliderValueChange(value) end

Note that the HandleSliderValueChange function is a helper function that we call from our slider event

handlers.

3. Let’s use the UiTransformBus to rotate our image when the slider value changes. Add the following

code in the HandleSliderValueChange function:

UiTransformBus.Event.SetZRotation(self.Properties.Image, value)

4. Let’s unload the canvas when the button is pressed. Add the following code in the OnButtonClick

function:

if (UiButtonNotificationBus.GetCurrentBusId() == self.Properties.BackButton) then local canvas = UiElementBus.Event.GetCanvas(self.entityId) UiCanvasManagerBus.Broadcast.UnloadCanvas(canvas) end

Note that since we only have one button, we don’t need to check if the BusId matches the EntityId of

the BackButton. If there were multiple buttons however, this is one way to determine which button was

clicked.

5. We want to clean up properly by disconnecting from the buses that we are connected to. Add the

following function to the second script:

function UIEditorLuaSubTutorial:OnDeactivate() self.buttonHandler:Disconnect() self.sliderHandler:Disconnect() end

That’s it! For comparison, your result should be close to the following image (functionality wise):

The “Back” button on the second UI Canvas, should clear/remove the second canvas and take you back to the

first canvas (Left most image above). Moving the Slider in the second canvas should rotate the image above it

(Right most image above), which in our case is the LEO logo.

Congratulations! You have successfully interacted with UI using Lua.

We’d love to hear from you! Head to our Tutorial Discussion forum to share any feedback you have, including

what you do or don’t like about our tutorials or new content you’d like to see in the near future.

Related Tasks and Tutorials Now that you have learned how to interact with UI using Lua scripting, here are some more references:

To see a level that implements all of its UI interaction with Lua scripting, refer to the level in

SamplesProject/Levels/Samples/UIEditor_Lua_Sample.