Using the IDE
Debugger
A debug session pauses your Lua so you can see where the game stopped, which function called it, and what the variables are. Normal Play and published games use the release runtime, which has no breakpoints or stepping.
The numbers on the picture match the descriptions below.
Starting and stopping
1. Start Debugging. On the expanded sidebar, the bug mark beside Play starts a session and opens Play. The mark turns green while debugging is on. Click it again to stop. Play reloads on the release runtime. Leaving Play also ends the session. The collapsed sidebar has only the Play icon, so expand the sidebar to start or stop debugging.
Breakpoints and watches are kept when you stop, leave Play, or restart.
Beside the game
These buttons sit to the right of the game. Continue, Step Into, Step Over, and Step Out are available while the game is paused. Pause is available while it is running. Restart is always available.
2. Game. The running cart. Click the canvas if the keyboard controls have moved to another panel.
3. Continue (F5). Runs until the next breakpoint.
4. Pause. Stops on the next line of your code.
5. Step Into (F11). Enters the next call in your code. Generated runtime code is skipped. Stepping moves one line at a time.
6. Step Over (F10). Runs the current line, including any call on it, then stops on the next line of your code. That next line can be a node method the game calls after the current function returns.
7. Step Out (Shift+F11). Runs until the current function returns.
8. Restart. Reloads the cart and clears the pause. Breakpoints stay. Edits made in the Code Editor apply on the next Restart.
Pause on Exception. Under the step buttons. On stops at a Lua error that nothing catches, with the call stack and locals still available. The error text appears in a popup over the game. Continue then reports the error and ends that call. Off lets the error through, and the console still reports it. An error caught by pcall or xpcall does not pause. The control stays disabled until a debug session is running. The IDE remembers On or Off.
F5 is left to the browser until a debug session is running.
Source
While debugging, the panel beside the game shows source instead of the player instructions. The source is read-only. Change the file in the Code Editor. Opening another file does not resume the game.
9. File path. The file open in this panel.
10. File list. Opens another project file here, so you can set breakpoints without leaving Play. node files are left out. A red dot means the file has breakpoints. A yellow dot means execution is stopped in that file. A tooltip on the row repeats the file name and those notes. Stepping, or choosing a stack frame, opens the stopped file again.
11. Source. Click the gutter, to the left of the line numbers, to set or clear a breakpoint. A red dot marks a breakpoint. The paused line is tinted, with a yellow arrow in the gutter. F9 toggles a breakpoint on the current line, here and in the Code Editor. Breakpoints apply in any of your files, including node methods. Nodes with an empty script are omitted from this list; open them from the Code Editor if needed. Frames that belong only to generated runtime code are omitted from the call stack and leave this file in place.
Debug pane
The bottom-right panel is the Debug pane during a session, and the performance timeline during normal Play. The Console stays on the bottom left. Drag the dividers to resize the game, the source, the Console, and this pane. The IDE remembers those sizes.
12. Status. Beside the Debug heading:
- Running — the game is executing;
- Breakpoint — a breakpoint stopped it;
- Step — a step stopped it;
- Pause — Pause stopped it;
- Exception — an uncaught Lua error stopped it. The error text appears in a popup over the game. Continue reports it and ends that call;
- Not debugging — the session is off.
13. Call Stack. The paused function is at the top. The rows below it are the functions that called it. Each row is the function name, then the file and line, such as update — main.lua:24. A row with no function name shows only the file and line. Select a row to show that file, and to read its locals and watches. Generated runtime frames are not listed. The stack is empty until the game is paused.
14. Watches. Lua expressions you want to keep in view. Type an expression and choose Add Watch, or press Enter. The value is shown while the game is paused, using the selected stack frame. A failed expression is shown in red. The trash icon removes a watch. Watches run real Lua and can change the game. While the game is running, the row reads Paused values appear here.
15. Locals. Variables in the selected function, including values captured from an outer function. They appear only while the game is paused.
16. Globals. Names the cart created, including state, variables assigned in main, and the class tables for nodes and modules. Engine functions are not listed. This list does not change when you select another stack frame.
A table in Locals, Globals, or Watches can be opened one level at a time. Opening it reads only that level. The rows close when you step or continue. Expanding a watch runs its expression again. A metatable row shows that table's metatable. Fields that exist only through the metatable are not listed on the table. Internal runtime fields are hidden. A very large table ends with More fields are not shown.
The Lua debug library is not available to cart scripts. For print and printError, see the Debug API.
Shortcuts
These apply while a debug session is active. The same keys are listed under Tools & Shortcuts.
F5— ContinueF9— toggle a breakpoint on the current lineF10— Step OverF11— Step IntoShift+F11— Step Out