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.