Upload
others
View
36
Download
0
Embed Size (px)
Citation preview
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.