You will learn how to do the following:

Transcription

1 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 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 512x 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.

2 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)

3 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) 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.

4 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

5 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() 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:

6 -- 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")

7 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.

8 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.

9 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)

10 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) function UIEditorLuaSubTutorial:OnSliderValueChanged(value) self:handleslidervaluechange(value) function UIEditorLuaSubTutorial:OnButtonClick() function UIEditorLuaSubTutorial:HandleSliderValueChange(value)

11 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)

12 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() 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.

13 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.