Developer Guide (Version 1.12)

Using the Lua Remote Debugger

Lumberyard includes a standalone visual script debugger for Lua. To start the debugger, you first enable it in the console, and then run the LuaRemoteDebugger.exe executable file.

  1. In Lumberyard Editor console or the game console, type lua_debugger 1 or lua_debugger 2. This enables enable debugging in one of the following two modes:

    • Mode 1 – The debugger breaks on both breakpoints and script errors.

    • Mode 2 – The debugger breaks only on script errors.

  2. Run the Lua remote debugger executable file at the Lumberyard directory location \dev\Tools\LuaRemoteDebugger\LuaRemoteDebugger.exe.

  3. In the Lua remote debugger, on the File menu, choose Connect.

  4. If you are running the game in the editor (you pressed Ctrl+G) and want to debug your scripts, choose PC (Editor). If you want to attach the debugger to the built game executable, choose PC (Game).

    For IP address and Port, type the IP address and port of the computer to which you want to connect. The default options connect to the game on your local computer. The default IP address is 127.0.01 (localhost). For PC (Editor), the default port is 9433. For PC (Game), the default port is 9432.

  5. Choose Connect. In Lumberyard Editor, the console window displays Lua remote debug client connected.

    The first time you run Lua remote debugger, it prompts you for the scripts folder:

                                                Lua remote debugger scripts folder

    The default folder is the Scripts folder of the project that you are running. For example, if you are running the samples project, the folder is samplesproject/Scripts.

  6. To accept the default location, click Yes.


    To change the scripts folder location, choose File, Set Scripts Folder.

    After you choose the location for your scripts folder, the folder's contents are shown in the navigation tree on the left.

Performing Tasks in the Lua Remote Debugger

To perform specific tasks in the Lua remote debugger, see the following table:

To do this Do this
Open a script file Double click the script file in the navigation pane, or press Ctrl+O to open the Find File dialog.
Set a break point Place the cursor on the line in the script where you want the break to occur, and then click the red dot in the toolbar or press F9. When program execution stops on a break point, the Call Stack and Locals tabs populate.
Remove a break point Place the cursor on the line with the breakpoint that you want to remove, and then click the red dot in the toolbar or press F9.
Use the Breakpoints tab The Breakpoints tab window displays each of your breakpoints with a check box next to it. To enable or disable a breakpoint, select or clear its check box. In the script window, the breakpoint's status is indicated by its color: red is active; gray is disabled.
To watch (inspect) variable values When execution is paused on a breakpoint, click the Watch tab, click the first column of a blank row, and then type the name of the variable that you want to watch.
Pause execution Click the pause (break) button on the toolbar or press Ctrl+Alt+Pause.
Resume execution Click the play button on the toolbar or press F5.
Step over a procedure Click the toolbar icon or press F10.
Step into a procedure Click the toolbar icon or press F11.
Step out of a procedure Click the toolbar icon or press Shift+F11.
Close a script file Choose File, Close, or press Ctrl+W
Disconnect from the editor or game In the Lua debugger, choose File, Disconnect. The Lumberyard console displays a network connection terminated message.


Code changes that you make in the debugger window do not change the loaded script and are discarded after the debugger window is closed.