using Lua to load a UI canvas
Tutorial: How to Load a UI Canvas from Lua This tutorial walks you through the steps to load a UI canvas from a Lua script, including creating a Lua script file, adding the script to your level, and displaying the UI canvas. At the end of the tutorial you will have loaded a UI canvas in your level. Similar to Flow Graph, UI functionality can also be scripted via Lua. You will learn how to do the following:
Create a Lua script file Add the Lua script to your level Load a UI Canvas
Prerequisites Before starting the UI Scripting in Lua series of tutorials, it is recommended that you have familiarized yourself with the concepts introduced in the Your First Game Menu tutorial series. Additionally, you must meet the following prerequisites.
It is assumed that you are running on Windows (64-bit). In the file paths mentioned below, /lumberyard represents the path to your local Lumberyard installation folder. For reference, the sample canvas used in this tutorial series is located in dev/SamplesProject/Levels/Samples/UIEditor_Lua_Sample/UI with the completed demo UI.
* This tutorial requires you use the SamplesProject supplied with the Lumberyard.
Step 1: Create a Lua script file The first step in the tutorial is to create the Lua script file that we’ll use throughout the remainder of this series. To Create a Lua script file 1. In a text editor of your choice, type (or copy and paste) the following script: loadmainmenu = { Properties = { }, } function loadmainmenu:OnActivate() Debug.Log("Hello, world!") end 2. Save the file in the dev/SamplesProject/Scripts folder and name it loadmainmenu.lua. a. Note that the filename, “loadmainmenu”, and the table variable “loadmainmenu” must be named the same. That is, if either the filename or the table variable name changes, the other name must change too. You have now created a Lua script file.
Step 2: Add the Lua script to your level After creating the Lua script file, you will add the script to your level. Once the script is associated with your level, the script will execute when the level is loaded. To add a Lua script to your level 1. In the Lumberyard Editor, create a new level. a. In the Welcome to Lumberyard Editor screen, click the New level button. If the welcome screen isn’t displayed, click File, New.
2. In the New Level dialog, type the name of your level and select a Heightmap Resolution of 128x128.
3. The Generate Terrain Texture will appear. Select 512x512 for Texture Dimensions and click OK.
4. Right-click anywhere in the Viewport and select Create Component Entity.
5. The Entity Outliner and Entity Inspector panes should appear. If for some reason they don’t, click View, Open View Pane and select them.
6. With the entity selected in the Entity Outliner, go to the Entity Inspector window and click the Add Component button. 7. Click Scripting, Lua Script.
8. In the Entity Inspector window, in the Lua Script properties, click the Browse button next to the Script field.
9. In the Browse dialog, locate loadmainmenu.lua in the dev/SamplesProject/Scripts folder a. This is the same Lua script that you created in Step 1.
10. Open the Console (if it isn’t already open) by clicking View, Show Console. a. Verify that you can see the Console pane – you may need to adjust your window layout in order to make it visible.
11. Enter Game Mode by clicking Game, Switch to Game (Ctrl+G).
12. In the Console window, verify that you see the “Hello, world!” message.
You have now successfully added the Lua script to your level. Note that the “Hello, world!” message appears in the Console window because the loadmainmenu.lua script contains a Debug.Log statement in our entity’s OnActivate method. The Debug.Log statement is a handy tool for displaying diagnostic information that can assist you when creating functionality in Lua. Here, we’ve used the log statement to verify that the Lua script is successfully executing when the entity is activated.
Step 3: Load a UI canvas The Lua file created in Step 1, loadmainmenu.lua, is now running when we execute our level in Game Mode (see Step 2). This step in the tutorial will show you how to load and display a UI canvas in your Lua script. To load a UI canvas from Lua, we need to use the UiCanvasLuaProxy:LoadCanvas function. To load a UI canvas from Lua 1. In the text editor of your choice, open loadmainmenu.lua for editing (if it isn’t already). 2. In the loadmainmenu:OnActivate function, create a UiCanvasLuaProxy object: self.uiCanvasLuaProxy = UiCanvasLuaProxy() 3. Then, using the UiCanvasLuaProxy that you created, call the LoadCanvas method and specify the path to the canvas file that you want to load, as a parameter: local canvasEntityId = self.uiCanvasLuaProxy:LoadCanvas("Levels/Samples/UIEditor_Lua_Sample/UI/UiLuaSa mple.uicanvas") 4. Save your changes to loadmainmenu.lua. 5. In the Lumberyard Editor, enter Game Mode by clicking Game, Switch to Game (Ctrl+G).
6. Observe that the UI canvas has loaded. Also observe that the mouse isn’t accessible, and the menu options on the canvas can’t be interacted with. 7. To show the mouse cursor, we need to use the LyShineLua.ShowMouseCursor function. In your text editor, add the following line to the loadmainmenu:OnActivate function: LyShineLua.ShowMouseCursor(true) 8. Save your changes to loadmainmenu.lua. 9. In the Lumberyard Editor, enter Game Mode by clicking Game, Switch to Game (Ctrl+G). 10. Observe that the mouse cursor now displays and the menu options can be interacted with (although, they don’t do anything for now). Congratulations! You have successfully loaded a UI canvas using Lua.
Lua Script Contents At this point in the UI Scripting in Lua tutorial series, your Lua script should look similar to the following: loadmainmenu = { Properties = { }, } function loadmainmenu:OnActivate() Debug.Log("Hello, world!") self.uiCanvasLuaProxy = UiCanvasLuaProxy()
local canvasEntityId = self.uiCanvasLuaProxy:LoadCanvas("Levels/Samples/UIEditor_Lua_Sample/UI/UiLuaSample.u icanvas") LyShineLua.ShowMouseCursor(true) end
Related Tasks and Tutorials From this point forward, you can continue the UI Scripting in Lua tutorial series and learn more UI scripting concepts for Lua. Continue on to the next tutorial:
How to Listen for Canvas Actions in Lua Lua Scripting in Lumberyard
Want to learn more about Lumberyard? Visit the complete Lumberyard Tutorials Page. 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.
Create a Lua script file Add the Lua script to your level Load a UI Canvas
Prerequisites Before starting the UI Scripting in Lua series of tutorials, it is recommended that you have familiarized yourself with the concepts introduced in the Your First Game Menu tutorial series. Additionally, you must meet the following prerequisites.
It is assumed that you are running on Windows (64-bit). In the file paths mentioned below, /lumberyard represents the path to your local Lumberyard installation folder. For reference, the sample canvas used in this tutorial series is located in dev/SamplesProject/Levels/Samples/UIEditor_Lua_Sample/UI with the completed demo UI.
* This tutorial requires you use the SamplesProject supplied with the Lumberyard.
Step 1: Create a Lua script file The first step in the tutorial is to create the Lua script file that we’ll use throughout the remainder of this series. To Create a Lua script file 1. In a text editor of your choice, type (or copy and paste) the following script: loadmainmenu = { Properties = { }, } function loadmainmenu:OnActivate() Debug.Log("Hello, world!") end 2. Save the file in the dev/SamplesProject/Scripts folder and name it loadmainmenu.lua. a. Note that the filename, “loadmainmenu”, and the table variable “loadmainmenu” must be named the same. That is, if either the filename or the table variable name changes, the other name must change too. You have now created a Lua script file.
Step 2: Add the Lua script to your level After creating the Lua script file, you will add the script to your level. Once the script is associated with your level, the script will execute when the level is loaded. To add a Lua script to your level 1. In the Lumberyard Editor, create a new level. a. In the Welcome to Lumberyard Editor screen, click the New level button. If the welcome screen isn’t displayed, click File, New.
2. In the New Level dialog, type the name of your level and select a Heightmap Resolution of 128x128.
3. The Generate Terrain Texture will appear. Select 512x512 for Texture Dimensions and click OK.
4. Right-click anywhere in the Viewport and select Create Component Entity.
5. The Entity Outliner and Entity Inspector panes should appear. If for some reason they don’t, click View, Open View Pane and select them.
6. With the entity selected in the Entity Outliner, go to the Entity Inspector window and click the Add Component button. 7. Click Scripting, Lua Script.
8. In the Entity Inspector window, in the Lua Script properties, click the Browse button next to the Script field.
9. In the Browse dialog, locate loadmainmenu.lua in the dev/SamplesProject/Scripts folder a. This is the same Lua script that you created in Step 1.
10. Open the Console (if it isn’t already open) by clicking View, Show Console. a. Verify that you can see the Console pane – you may need to adjust your window layout in order to make it visible.
11. Enter Game Mode by clicking Game, Switch to Game (Ctrl+G).
12. In the Console window, verify that you see the “Hello, world!” message.
You have now successfully added the Lua script to your level. Note that the “Hello, world!” message appears in the Console window because the loadmainmenu.lua script contains a Debug.Log statement in our entity’s OnActivate method. The Debug.Log statement is a handy tool for displaying diagnostic information that can assist you when creating functionality in Lua. Here, we’ve used the log statement to verify that the Lua script is successfully executing when the entity is activated.
Step 3: Load a UI canvas The Lua file created in Step 1, loadmainmenu.lua, is now running when we execute our level in Game Mode (see Step 2). This step in the tutorial will show you how to load and display a UI canvas in your Lua script. To load a UI canvas from Lua, we need to use the UiCanvasLuaProxy:LoadCanvas function. To load a UI canvas from Lua 1. In the text editor of your choice, open loadmainmenu.lua for editing (if it isn’t already). 2. In the loadmainmenu:OnActivate function, create a UiCanvasLuaProxy object: self.uiCanvasLuaProxy = UiCanvasLuaProxy() 3. Then, using the UiCanvasLuaProxy that you created, call the LoadCanvas method and specify the path to the canvas file that you want to load, as a parameter: local canvasEntityId = self.uiCanvasLuaProxy:LoadCanvas("Levels/Samples/UIEditor_Lua_Sample/UI/UiLuaSa mple.uicanvas") 4. Save your changes to loadmainmenu.lua. 5. In the Lumberyard Editor, enter Game Mode by clicking Game, Switch to Game (Ctrl+G).
6. Observe that the UI canvas has loaded. Also observe that the mouse isn’t accessible, and the menu options on the canvas can’t be interacted with. 7. To show the mouse cursor, we need to use the LyShineLua.ShowMouseCursor function. In your text editor, add the following line to the loadmainmenu:OnActivate function: LyShineLua.ShowMouseCursor(true) 8. Save your changes to loadmainmenu.lua. 9. In the Lumberyard Editor, enter Game Mode by clicking Game, Switch to Game (Ctrl+G). 10. Observe that the mouse cursor now displays and the menu options can be interacted with (although, they don’t do anything for now). Congratulations! You have successfully loaded a UI canvas using Lua.
Lua Script Contents At this point in the UI Scripting in Lua tutorial series, your Lua script should look similar to the following: loadmainmenu = { Properties = { }, } function loadmainmenu:OnActivate() Debug.Log("Hello, world!") self.uiCanvasLuaProxy = UiCanvasLuaProxy()
local canvasEntityId = self.uiCanvasLuaProxy:LoadCanvas("Levels/Samples/UIEditor_Lua_Sample/UI/UiLuaSample.u icanvas") LyShineLua.ShowMouseCursor(true) end
Related Tasks and Tutorials From this point forward, you can continue the UI Scripting in Lua tutorial series and learn more UI scripting concepts for Lua. Continue on to the next tutorial:
How to Listen for Canvas Actions in Lua Lua Scripting in Lumberyard
Want to learn more about Lumberyard? Visit the complete Lumberyard Tutorials Page. 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.
