Debugging with Lua Editor

Open 3D Engine (O3DE) Lua Editor (Lua IDE) offers an intuitive integrated development environment (IDE) that makes it easy to author, debug, and edit Lua scripts when you create or extend your game. Lua Editor is a standalone application, but you can open it directly in O3DE Editor from the Tools menu.

This tutorial shows you how to use O3DE Lua Editor to perform debugging operations on a sample script.

Add sample Lua Script to an entity

  1. Open Lua Editor from the Tools menu.

  2. Select New from the File menu to create a new Lua script.

  3. Copy and Paste the following code into the new script.

    -- ConstantRotation.lua
       
    local ConstantRotation =
    {
        Properties =
            {
            Rotation = { default = Vector3(0, 0, 90), description = "Constant rotation (in degrees) to apply over time." },
            },
    }
    
    function ConstantRotation:OnActivate()
        self.rotationRadians = self.Properties.Rotation;
        self.rotationRadians.x = Math.DegToRad(self.rotationRadians.x);
        self.rotationRadians.y = Math.DegToRad(self.rotationRadians.y);
        self.rotationRadians.z = Math.DegToRad(self.rotationRadians.z);
        self.tickBusHandler = TickBus.Connect(self)
    end
    
    function ConstantRotation:OnTick(deltaTime, timePoint)
        TransformBus.Event.RotateAroundLocalX(self.entityId, self.rotationRadians.x * deltaTime);
        TransformBus.Event.RotateAroundLocalY(self.entityId, self.rotationRadians.y * deltaTime);
        TransformBus.Event.RotateAroundLocalZ(self.entityId, self.rotationRadians.z * deltaTime);
    end
    
    function ConstantRotation:OnDeactivate()
        self.tickBusHandler:Disconnect()
    end
    
    return ConstantRotation
    
  4. Save the script as ConstantRotation.lua in your project’s directory.

  5. Close Lua Editor.

  6. In Entity Outliner, choose an entity to add a Lua Script component to.

  7. In Entity Inspector, choose Add Component, and then choose Scripting, Lua Script.

  8. In Entity Inspector, locate the Lua Script component, and then click to open a file browser.

  9. In the Pick Lua Script window, select ConstantRotation.lua and choose OK.

  10. In the Lua Script component, click to launch Lua Editor.

Connect to O3DE Editor with GridHub

Connection is facilitated by GridHub, which is O3DE’s central connection hub for debugging. GridHub starts automatically when Lua Editor is started and must be running in the background for Lua Editor to find targets it can connect to. Because the debugging functionality is enabled through network sockets, you must connect Lua Editor to the target that is running the script before you can debug. In this tutorial, you connect to O3DE Editor.

  1. In the Lua Editor toolbar, choose Target: None, and then choose Editor(ID) to connect to O3DE Editor.

    Target selector

    Note:
    You may need to expand the Lua Editor window to see the buttons on the Lua Editor toolbar for the next few steps.
  2. In the Lua Editor toolbar, leave Context setting at Default for the debugging context. The default setting is good for debugging component entity scripts such as the one in this tutorial.

    Context selector

  3. The Debugging icon turns green to show that Lua Editor and O3DE Editor are connected:

    Lua Editor connected to O3DE Editor

    Click Classes in the Class Reference to show the available Lua libraries. You can do the same for EBuses and Globals.

    Note:
    You may need to switch focus to O3DE Editor before Class Reference will populate.

    Classes Reference

    Classes

    Note:
    The class reference feature is active only for the default context and component entity scripts.

Setting breakpoints

After you connect, you can pause a script by setting breakpoints.

  1. In the Lua Editor toolbar, click the Breakpoints icon Breakpoints Icon to show the Breakpoints window.

  2. In Lua Editor, click one or more line numbers in the constantrotation.lua script to set one or more breakpoints. As you add breakpoints, the line number and script path for each are added to the Breakpoints window.

  3. In O3DE Editor, press Ctrl+G to run the game, or click the Simulate icon at the bottom of the viewport to enable game simulation and run scripts. Lua Editor opens with a yellow marker stopped on the first breakpoint that it encounters.

    Debugger stopped on breakpoint

    When execution is halted at a breakpoint, more information becomes available in the Lua Locals, Stack, and Watched Variables panes.

  4. Click the Stack icon Stack Icon to show the Stack window.

  5. Click the Lua Locals icon Lua Locals Icon to show local Lua variables.

  6. Click Watched Variables icon Watched Variables Icon to open the Watched Variables window, where you can specify variables to watch.

  7. Press F11 a few times to step through the code. Note how the contents of the Stack, Lua Locals, and Watched Variables windows change.

    Tip:
    For greater convenience, you can float or dock these windows.
  8. To detach from debugging, click Debugging.

    Click to detach from debugging

  9. In O3DE Editor, Press Esc to stop the game.

Options available while debugging

The following table summarizes common options available while debugging.

IconActionKeyboard ShortcutDescription
Run in Editor IconRun in EditorAlt+F5Run in O3DE Editor.
Run on Target IconRun on TargetCtrl+F5Send script to the connected target and run it.
Run/Continue IconRun/ContinueF5Run or continue running the current script.
Step Into IconStep IntoF11Step into the function called on the current line.
Step Out IconStep OutShift+F11Step out of the called function.
Step Over IconStep OverF10Step over the function called on the current line.
Toggle Breakpoint IconToggle BreakpointF9Enable or disable a breakpoint on the current line.