sig-content/testing-guidance/workflow-tests/scripting/lua-scripting-tests.md

Lua Scripting Workflow Tests

Testing in this area should focus on the functionality of Lua Editor.

Common Issues to Watch For

Test guidance will sometimes note specific issues to watch for. The common issues below should be watched for through all testing, even if unrelated to the current workflow being tested.

1. Asset processor errors when loading/saving .lua files
2. Warnings or assets that appear in the Log
3. Unresponsive UI elements

Platforms:

• Windows
• Linux

Docs:

• O3DE Documentation: Writing Lua Scripts in Open 3D Engine
• O3DE Documentation: Introduction to Open 3D Engine’s Lua Editor
• O3DE Documentation: Basic Structure of a Lua Script
• O3DE Documentation: Debugging Lua Scripts
• O3DE Documentation: Debugging with Lua Editor
• O3DE Documentation: Using EBuses in Lua

Script Files:

• "Area: Creating a Lua skeleton script file" BaseScript.lua
• "Area: Properties usage in Lua scripts" BaseScript.lua
• "Area: Moving entity using Lua script" BaseScript.lua
• "Area: Using ScriptEvents to communicate between two Lua scripts" SendEvent.lua and ReceiveEvent.lua

Area: Opening Lua Editor, connecting to Editor and using Find tool

Project Requirements

• Any project with the Remote Tools Connection Gem

Product:

Running Lua Editor with basic functions checked.

Suggested Time Box:

20 minutes

Area: Creating a Lua skeleton script file

Project Requirements

• Any project

Assets:

• "Area: Creating a Lua skeleton script file" BaseScript.lua

Product:

Skeleton Lua script assigned to an entity and printing simple messages to console when entering/exiting Game Mode.

Suggested Time Box:

20 minutes

Workflow	Requests	Things to Watch For
Launch Lua Editor and connect to Editor	Check different methods of entry to Lua Editor: Tools → Lua Editor Lua Script component Modify Lua Editor layout: Resize the Lua Editor window Undock panes Move panes around Dock panes Connect to Editor by clicking Target button and choosing Editor.exe (xyzxyzxy) from the dropdown	Lua Editor launches and is stable Window and panes can be moved, resized and properly docked/undocked Lua Editor can be connected to Editor Class Reference is populated after connecting to Editor
Create a new .lua file and check Log messages	Create a new .lua file by selecting File → New in Lua Editor, make sure to save it in a path accessible to Editor (for example *\Assets\*) Type few random characters into the script and save it using: File → Save Ctrl+S shortcut File → Save As in a separate file Reopen the original .lua file after performing File → Save As operation Create one more new .lua file same way as in step 1 and move the script tabs between each other Add a change to each opened script (so that * is visible on their tabs) and use File → Save All	New file can be created and is opened in Lua Editor With multiple .lua files opened, their tabs can be rearranged freely Files can be saved using different available options Log produces error messages when saving .lua files with no valid script structure (random characters in this case)
Basic Find Tool usage	Add a unique string to any of the opened scripts (for example text) Check different methods of opening Find tool: Edit → Find Toolbar magnifying glass button Ctrl+F shortcut Type the unique string into Text to find: textbox and click Find Next button Add the same unique string to two other opened files In Find tool change Current File dropdown to All Open Files and click Find All button Type a new unique string into Replace With: textbox (for example Hello, World!) and click Replace All button	Find tool opens and is stable Text search highlights matching text in individual and multiple files Text can be replaced from Find tool's window

(Click to Expand) BaseScript.lua:

``` -- BaseScript.lua local BaseScript = { Properties = { -- Property definitions } } function BaseScript:OnActivate() Debug.Log(tostring("Hi!")); end function BaseScript:OnDeactivate() Debug.Log(tostring("Bye!")); end return BaseScript ```

Area: Properties usage in Lua scripts

Project Requirements

• Any project can be used
• Saved script from "Area: Lua skeleton script usage" helps with setup

Assets:

• "Area: Properties usage in Lua scripts" BaseScript.lua

Product:

Lua Script returning messages to Editor Console using properties declared in the script.

Suggested Time Box:

20 minutes

Workflow	Requests	Things to Watch For
Create a Lua skeleton script	Create a new .lua file by selecting File → New in Lua Editor, make sure to save it in a path accessible to Editor (for example *\Assets\*) Add a skeleton Lua script to the file - remember to replace BaseScript in the file to the name of your lua file if it is different (you can do this easily using Find tool and Replace All action) Replace -- Activation Code and -- Deactivation Code lines with Debug.Log(tostring("Hi!")); and Debug.Log(tostring("Bye!")); respectively Save the .lua file (for example File → Save or Ctrl+S)	Basic script can be created and saved After saving Compilation Succesful - is printed to Log and no errors occur
Create an entity using the created skeleton Lua script	In Editor, create a new entity and add a Lua Script component to it Select Lua Script component on your new entity, click the Pick Lua Script button and choose your skeleton script Enter and exit Game Mode (using for example Ctrl+G) while paying attention to the Editor's Console	Lua Script component can be assigned to an entity Lua script can be assigned to Lua Script component Hi! is printed to Console on entering the Game Mode and Bye! on exiting it Editor remains stable Final working script can be found below this table

Workflow	Requests	Things to Watch For
Add a property to Properties table in a script	Add a property to the Properties table of opened Lua script (example of this can be viewed under local BaseScript = {} table in the (Click to Expand) BaseScript.lua below) Add a line to OnActivate() that prints the property after a string (for example change Debug.Log(tostring("Hi!")); to Debug.Log(tostring("Hi! My value is: " .. BaseScript.Properties.MyValue)); - where BaseScript is the name of your Lua script) Save the file and run Game Mode with this script added to a Lua Script entity	File is saved without error When entering Game Mode, the property is properly printed (for example Hi! My value is: 1)
Add local properties in a script	Write a code which declares two properties, adds them together in a third property and prints that third property (example of this can be viewed under OnDeactivate() function in the (Click to Expand) BaseScript.lua below) Modify the Debug.Log line so that it uses the local properties - for example: Debug.Log(tostring(Bye .. NumberOne .. " + " .. NumberTwo .. " = " .. NumbersAdded)); Save the file and run and exit Game Mode with this script added to a Lua Script entity	File is saved without error When exiting Game Mode, the properties are properly printed (for example Bye! 1 + 2 = 3)

(Click to Expand) BaseScript.lua:

``` -- BaseScript.lua local BaseScript = { Properties = { MyValue = 1, } } function BaseScript:OnActivate() Debug.Log(tostring("Hi! My value is: " .. BaseScript.Properties.MyValue)); end function BaseScript:OnDeactivate() Bye = "Bye! " NumberOne = 1 NumberTwo = 2 NumbersAdded = NumberOne + NumberTwo Debug.Log(tostring(Bye .. NumberOne .. " + " .. NumberTwo .. " = " .. NumbersAdded)); end return BaseScript ```

Area: Debugging existing script

Project Requirements

• Any project with the Remote Tools Connection Gem added
• Lua Editor connected to Editor
• Saved BaseScript.lua from "Area: Properties usage in Lua scripts" helps with setup

Product:

Simple debugging setup created and confirmed to be working.

Suggested Time Box:

20 minutes

Area: Moving entity using Lua script

Project Requirements

• Any project with the Remote Tools Connection Gem
• Lua Editor connected to Editor
• Saved BaseScript.lua from "Area: Properties usage in Lua scripts" helps with setup

Assets:

• "Area: Moving entity using Lua script" BaseScript.lua

Product:

Entity that can be moved with keyboard input in Game Mode using Lua Script.

Suggested Time Box:

30 minutes

Workflow	Requests	Things to Watch For
Open Debugging tools	Open Breakpoints tool using any method: Toolbar Breakpoints button View → Breakpoints Add breakpoints to some lines on your script using any method: Select a line and click/press: Toggle Breakpoint button on toolbar Debug → Toggle Breakpoint F9 key Left-click the area next to the line number on the script Remove added breakpoints (This can be done using the same methods as adding them) Open Stack tool using any method: Toolbar Stack button View → Stack Open LUA Locals tool using any method: Toolbar LUA Locals button View → LUA Locals	Breakpoints tool can be opened and tracks placed breakpoints Breakpoints can be removed Stack tool can be opened LUA Locals tool can be opened
Basic breakpoint use	Add a breakpoint to a Debug.Log(); line in OnActivate() function (for example line 12 in the "Area: Properties usage in Lua scripts" script) Make sure that Lua Editor is connected to the Editor and enter Game Mode Change the window to the Lua Editor while the Game Mode is running (for example using Alt+Tab navigate to the Lua Editor window) Continue with script execution using any of the available options until the Game Mode is functional: Run/Continue: Toolbar Run/Continue button Debug → Run/Continue F5 key Step Over: Toolbar Step Over button Debug → Step Over F10 key Step Into: Toolbar Step In button Debug → Step Into F11 key Step Out: Toolbar Step Out button Debug → Step Out Shift+F11 shortcut	Stack and LUA Locals populate with data when entering Game Mode Script execution stops on the breakpoint (Current executed line is marked by a yellow triangle pointing to the right, next to the line number) Continuing with script execution updates the yellow triangle position until it leaves the OnActivate() function

Workflow	Requests	Things to Watch For
Create .inputbidings file	Open Asset Editor (for example Tools → Asset Editor) and create a new .inputbindings file (File → New → Input Bindings) Add three following Input Event Groups to the .inputbindings file: Event Name: Forward; Event Generators: keyboard_key_alphanumeric_W with Event value multiplier: 1.0 and keyboard_key_alphanumeric_S with Event value multiplier: -1.0 Event Name: Strafe; Event Generators: keyboard_key_alphanumeric_A with Event value multiplier: -1.0 and keyboard_key_alphanumeric_D with Event value multiplier: 1.0 Event Name: Look; Event Generators: mouse_delta_x with Event value multiplier: -1.0 Save the .inputbindings file for example in the project's Assets folder under the name PlayerMovement	New .inputbinding file can be created Event Groups can be added to Input Bindings and can be modified Input Bindings can be saved
Modify the Lua script so that it uses keyboard input to move the entity	Modify the script as shown below the table in under the (Click to Expand) BaseScript.lua Find the following copied functions in the Class Reference (Remember that Lua Editor has to be connected to the Editor): GetEntityForward AddVelocity GetEntityRight GetTickDeltaTime RotateAroundLocalZ Save the modified Lua script	Referenced functions can be found in Class Reference Lua script can be saved without errors
Create and move Player entity in Game Mode	Create an entity with the following components: Mesh Input PhysX Character Controller PhysX Character Gameplay Assign the PlayerMovement.inputbindings to the Input component Assign the Lua script to the Lua Script component. Add a Model Asset to the Mesh component (for example BeveledCylinder.fbx) Add a child Camera entity to the Player entity Add a Camera component to the Camera child entity and set the Transform's Translate to {X = 0.0; Y = -3.0; Z = 2.0} Enter the Game Mode and move the entity using mouse and WASD keys	Mentioned components can be added to entities and relevant files can be assigned to their respective components Child entity can be added to an entity and it's Transform adjusts based on the parent entity Player entity can be moved and rotated around in the Game Mode using defined input keys/mouse

(Click to Expand) BaseScript.lua:

``` -- BaseScript.lua local BaseScript = { Properties = { MyValue = 1, } } function BaseScript:OnActivate() --Bind Input Event Groups from PlayerMovement.inputbindings --Forward self.forwardBusId = InputEventNotificationId("Forward"); self.forwardBus = InputEventNotificationBus.Connect(self, self.forwardBusId); --Strafe self.strafeBusId = InputEventNotificationId("Strafe"); self.strafeBus = InputEventNotificationBus.Connect(self, self.strafeBusId); --Look self.lookBusId = InputEventNotificationId("Look"); self.lookBus = InputEventNotificationBus.Connect(self, self.lookBusId); end --OnHeld is activated when an input is being held or applied constantly (as in the case of mouse movement) function BaseScript:OnHeld(inputValue) --Create a reference to the currently used input local currentBusId = InputEventNotificationBus.GetCurrentBusId(); --If "Forward" input is held (current used input is equal to "Forward") then --Create a vector variable based on the entity's forward vector(EntityEntity_VM.GetEntityForward) with length equal to value of the input(inputValue) --Add velocity (CharacterControllerRequestBus.Event.AddVelocity) equal to the above vector (self.forwardVector) to the entity housing this script (self.entityId) if currentBusId == self.forwardBusId then self.forwardVector = EntityEntity_VM.GetEntityForward(self.entityId, inputValue); CharacterControllerRequestBus.Event.AddVelocity(self.entityId, self.forwardVector); end --If "Strafe" input is held (current used input is equal to "Strafe") then --Create a vector variable based on the entity's right vector(EntityEntity_VM.GetEntityRight) with length equal to value of the input(inputValue) --Add velocity (CharacterControllerRequestBus.Event.AddVelocity) equal to the above vector (self.rightVector) to the entity housing this script (self.entityId) if currentBusId == self.strafeBusId then self.rightVector = EntityEntity_VM.GetEntityRight(self.entityId, inputValue); CharacterControllerRequestBus.Event.AddVelocity(self.entityId, self.rightVector); end --If "Look" input (horizontal mouse movement) is used (current used input is equal to "Forward") then --Create a float variable that is a multiplication of the input value (inputValue) and time elapsed from the last tick (TickRequestBus.Broadcast.GetTickDeltaTime()) --Apply rotation around Z axis of entity housing this script (TransformBus.Event.RotateAroundLocalZ(self.entityId,...) equal to the above float (self.rotateSpeed) if currentBusId == self.lookBusId then self.rotateSpeed = inputValue * TickRequestBus.Broadcast.GetTickDeltaTime(); TransformBus.Event.RotateAroundLocalZ(self.entityId, self.rotateSpeed); end end function BaseScript:OnDeactivate() Bye = "Bye! " NumberOne = 1 NumberTwo = 2 NumbersAdded = NumberOne + NumberTwo Debug.Log(tostring(Bye .. NumberOne .. " + " .. NumberTwo .. " = " .. NumbersAdded)); end return BaseScript ```

Area: Using ScriptEvents to communicate between two Lua scripts

Project Requirements

• Any project

Assets:

• "Area: Using ScriptEvents to communicate between two Lua scripts" SendEvent.lua and ReceiveEvent.lua

Product:

Two Lua scripts, where one of the scripts uses variable passed to it from the other script.

Suggested Time Box:

20 minutes

Workflow	Requests	Things to Watch For
Create a Script Event	Open Asset Editor (for example Tools → Asset Editor) and create a new .scriptevents file (File → New → Script Events) Modify the created Script Events file: Name: SimpleScriptEvent Add an Event to the Events Event Name: SendNumber Add a Parameter to the Parameter of SendNumber event Parameter Name: Number Parameter Type: Number Save the .scriptevents file for example in the project's Assets folder under the name SimpleScriptEvent	New Script Events file can be created Script Events file can be modified Script Events file can be saved
Create Lua scripts utilizing the Script Event to send a variable from one to another	Create two new Lua scripts and copy the contents of SendEvent.lua and ReceiveEvent.lua found under the (Click to Expand) SendEvent.lua and ReceiveEvent.lua: to them Save the Lua scripts with their respective names: SendEvent.lua and ReceiveEvent.lua	New Lua scripts can be created Lua scripts save successfully with provided code
Create entities using the Lua scripts and enter Game Mode	Create two entities with Lua Script component added to them Assign SendEvent.lua to one of the entities and ReceiveEvent.lua to the other Enter Game Mode	Entities with Lua Script components can be created Lua scripts can be assigned to the Lua Script component Assigned scripts execute printing Received number: 123.0 about every second

(Click to Expand) SendEvent.lua and ReceiveEvent.lua:

*SendEvent.lua* ``` local SendEvent = { } function SendEvent:OnActivate() --Connect to Tick bus, so that OnTick(dt) function is available further on self.tickHandler = TickBus.Connect(self) --Create a timer variable with value of 1, later used in the delay setup timer = 1 --Connect to the created Script Event (SimpleScriptEvent is the name of the Script Event file) self.ScriptEventHandler = SimpleScriptEvent.Connect(self) end --The delay setup is put in place so that the Send event is guaranteed to launch after all other entities/scripts (including the Receive event) are active --OnTick is activated each tick returning delta time (dt) since the last tick function SendEvent:OnTick(dt) --Each tick subtract the time it took since the last tick from the current timer value and overwrite it (Can be looked at as "Count from 1 to 0 using ticks") timer = timer - dt --If timer variable reaches 0 or negative values then if timer <= 0 then --Send the SimpleScriptEvent's SendNumber event with a Number parameter 123 SimpleScriptEvent.Broadcast.SendNumber(123) --Reset the timer variable to 1 timer = 1 end end return SendEvent ``` *ReceiveEvent.lua* ``` local ReceiveEvent = { } function ReceiveEvent:OnActivate() --Connect to the created Script Event (SimpleScriptEvent is the name of the Script Event file) self.ScriptEventHandler = SimpleScriptEvent.Connect(self, self.entityId) end --Receive the SimpleScriptEvent's SendNumber event with it's parameter (number) function ReceiveEvent:SendNumber(number) --Print the received parameter to the Console Debug.Log("Received number: " .. tostring(number)) end return ReceiveEvent ```