Debugging

Roblox Studio offers many debugging tools commonly found in Integrated Development Environments (IDEs). The debugger is a tool that helps you inspect your scripts line-by-line as they run. It displays data in the Watch, Call Stack, Breakpoints, and Output windows for you to inspect.

Debugger in Studio

To disable and reenable the debugger, open the Studio Settings menu, toggle the Debugger Enabled setting, then restart Studio.

Enable Debugger in Studio settings

General Workflow

If you notice a problem in your experience or want to verify that it works as you intend, you can debug the code related to it as follows:

  1. Insert breakpoints on the lines of codes that you want to examine.

  2. In the Script tab, click Play or Run in the test tab to start a playtest session, also known as a debugging session.

    Script tab playtest options
  3. When a script hits a breakpoint, the playtest session pauses. Step through the code. Inspect the Watch, Call Stack, and Output windows to help you diagnose and understand the problem.

  4. Insert additional breakpoints on lines of code that haven't executed yet to inspect additional data. Disable or delete breakpoints that you don't need anymore.

  5. In the Script tab, click Stop to end the debugging session.

    Script tab shows test and stop buttons

Repeat the previous steps until you solve the problem or find its root cause. As you learn the general workflow, you can configure the breakpoints to break only if certain conditions are met, to print a message to the Output window, and to run only on the client or server. For more information, see Breakpoint Configurations.

Inserting Breakpoints

Breakpoints are checkpoints that pause or "break" the execution of your scripts at specific lines. You can use the pauses to inspect and debug your experience, watch variables, and inspect the call stack. Breakpoints are one of the most effective ways to debug functions, so they're one of the most important debugging tools. You can insert a breakpoint at any line of executable code.

To insert a standard breakpoint at a line of code, left-click the margin to the right of its line number. You can also right-click the margin and click Insert Breakpoint. The breakpoint appears as a red dot. To disable it, click the dot.

Breakpoint in gutter is a red dot

Stepping Through Code

If you insert a breakpoint at a line in a script, the script pauses before it executes that line. A yellow arrow called the "debugger" indicates which line of code executes next.

Active breakpoint in the debugger shows yellow arrow

When the script pauses, execute the following code one line at a time by stepping through them with the buttons in the Script tab tab. The buttons also appear in the top-left corner of the Call Stack window. As you step through the code, monitor how your experience changes as the current line executes.

Script Tab focused on the Debugger section

The following table summarizes the three ways to step through code. To continue executing your code after you hit a breakpoint, click Resume in the Script tab.

Button Action Shortcut Description
Button to step into a line of codeStep Into F11 The Step Into button moves the debugger into the code of the function on the current line. If there is no function on the current line, the debugger moves to the next line.
Button to step over a line of codeStep Over F10 The Step Over button moves the debugger to the next line of code, not moving into functions.
Button to step out of a line of codeStep Out Shift + F11 The Step Out button moves the debugger out of the current function and to the next line of code after the function call. If the current line isn't inside a function, the debugger moves to the next line.

Inspecting Code

When a breakpoint pauses the experience during a playtest, you can inspect the Watch window, Call Stack window, Output window, and Script Editor to find information about variable values and function executions. With this information, you can find the root cause of the problem in your experience.

In the Watch Window

The Watch window has two tabs: Variables and My Watches. The Variables tab shows information about the current variables in scope, and the My Watches tab shows the value of variables or expressions that you define. Both tabs show information before the line executes.

The Variables tab has the following columns:

  • Name – The declared name of the variable.
  • Scope – The scope of the variable: where it can be "seen" and accessed, such as Local, Global, or Upvalue.
  • Value – The current value of the variable.
  • Data Type – The data type of the variable.

The My Watches tab has the following columns:

  • Expression – The expression that you want to watch.
  • Value – The current value of the expression.
  • Data Type – The data type of the expression.

In the Variables tab, you can filter the scope of variables in the Variables tab by clicking the filter icon. You can also sort the rows by clicking the name of the column to sort by. The watch window provides both expanded and collapsed views of tables.

Watch Window with variable values

To inspect code in the Watch window:

  1. If the Watch window isn't open, then click Watch in the View tab.

  2. When your playtest session pauses at a breakpoint, think about how you expect the current line to change the values of variables in that script.

  3. As you step through code, watch how the value of variables change in the Variables tab. If you want to watch an expression not in the Variables tab, open the My Watches tab. Click an empty row in the Expression column, then type the expression into it. If you want to watch a variable in the Script Editor, double-click the name of the variable, right-click, then click Add Watch.

  4. Compare the values of variables and expressions from what you expect and what you see in the Watch window. If there's a difference between how you expect the variables to change and how they actually change, then the variables or the functions interacting with them might be causing problems or bugs.

In the Call Stack Window

The Call Stack window shows which line of code is going to execute next when the debugger reaches a breakpoint. The Call Stack indicates which line you call a function from and, if you call the function in other functions, the order of function calls and which lines you call the other functions. The top function of the Call Stack is the last called and first to execute. You can use the Call Stack to check whether the order of function calls in your scripts matches your mental model of the function calls.

Call Stack in Studio

If you have multiple breakpoints in different scripts, they might pause the playtest session at the same time. You can jump to the breakpoints by clicking the arrow next to the name of the script in the Call Stack window. If you click Resume, then you step over all the breakpoints that paused at the same time.

Call Stack with multiple breakpoints

To inspect code in the Call Stack window during a debugging session:

  1. If the Call Stack window isn't open, then click Call Stack in the View tab.

  2. When your experience pauses at a breakpoint, think about how you expect the order of function calls to be in that script.

    Script Editor with two functions and one breakpoint
  3. The Call Stack shows the order of function calls. If the breakpoint is inside a function, the Call Stack shows which function calls that function, if any. The Call Stack also shows the name and line number of each function. Click the row for a function to jump to it.

    Click in Call Stack to jump to line
  4. Compare the order of function calls that you thought of in step 2 and the actual order from step 3. If there are any differences, then there's a difference between how you expect the code to behave and how it actually behaves, thereby causing potential problems and bugs.

In the Output window

The Output window, accessible from the View tab, displays errors captured from running scripts, messages from Roblox Engine, log messages from Logpoints, messages from calls to print(), and errors from calls to warn(). For more information on the Output window and how to customize it, see Output.

In the Script Editor

The Debugger is integrated with the Script Editor. When your experience pauses at a breakpoint in a script, you can hover your mouse over the name of a variable to see its value. For example, you can see the value of a table that you pass as an argument in a function call.

Mouseover a variable in Script Editor to show value

Breakpoint Configurations

You can configure breakpoints to break only if certain conditions are met, to print a message to the Output window, and to run only on the client or server. You can also mix these configurations together to best suit your debugging needs.

Editing Breakpoints

You can edit the configuration of a breakpoint at any time, including during playtest sessions. If you edit breakpoints during a playtest session, the edits persist even after you finish it. You can also edit a breakpoint that's actively pausing your playtest session, but changes don't apply until the next playtest session.

To edit the configuration of a breakpoint:

  1. Right-click the breakpoint, then click Edit Breakpoint.

    Right click to edit a breakpoint in Studio
  2. In the Edit Breakpoint window, configure the breakpoint as you want.

    Edit Breakpoint window in Studio

Condition, Log Message, and Options

For each breakpoint, you can set its Condition, Log Message, Continue Execution, and Context.

The Condition is the expression that determines whether the breakpoint activates. The Condition is optional. If the Condition is empty, the breakpoint always activates. If the Condition exists, then the breakpoint activates only if the condition is true. For example, if you want the breakpoint to activate only if the variable n equals 42, then set the Condition as n == 42. Conditions are useful for debugging how functions execute when certain variables have certain values or if you want to break only on certain executions in a loop.

The Log Message is the expression that prints to the Output window when the condition is true. The format of the Log Message is the same as the argument for a print() statement. For example, set the Log Message as "The value of n:", n to print the same message as print("The value of n:", n). You can add and remove Log Messages without having to stop the execution, unlike print statements.

The Continue Execution option determines whether the breakpoint pauses the script if it activates. It's useful if you want to log values of variables or expressions without stopping execution. This option is disabled by default.

The Context of a breakpoint determines whether the breakpoint should activate on the Client, Server, or Edit. If the context is Client, then the breakpoint triggers in client-side scripts. If the context is Server, then the breakpoint triggers in server-side scripts. If the context is Edit, then the breakpoint triggers when you debug plugins. If you click Custom Context, the window indicates the current context.

Edit Breakpoint Window shows Custom Context

Conditional Breakpoints and Logpoints

Studio offers named variations of breakpoints to make breakpoint insertion faster. To insert a named variation, right-click the margin to the right of its line number, then click the variant you want to insert.

Right click to insert a breakpoint

A Conditional Breakpoint is a breakpoint with a Condition and Continued Execution disabled. Conditional Breakpoints pause your script only if a condition is true, so they're useful for debugging how functions execute when certain variables have certain values. Conditional Breakpoints use the values of the variables before the line executes. When you insert a Conditional Breakpoint, your cursor focuses on the Condition option for you to set quickly.

A Logpoint is a breakpoint with a Log Message and Continued Execution enabled. Logpoints log messages to the Output window without pausing your scripts, so they're useful for debugging variable values. Logpoints use the values of the variables before the line executes. When you insert a Logpoint, your cursor focuses on the Log Message for you to set it quickly.

Logpoints are often more efficient for debugging variables than print() statements because they allow you to log messages to the Output window without having to stop or restart the active playtest session. Compared to print() statements, they keep your code clean while debugging and are easier to remove after you finish debugging.

Disabling Breakpoints

There are many ways to disable and reenable a breakpoint:

  • Click the breakpoint's icon.
  • Edit the breakpoint and toggle its Enabled checkbox.
  • Right-click the breakpoint icon and click Disable Breakpoint or Enable Breakpoint.

Deleting Breakpoints

To delete a breakpoint, left-click its icon. You can also right-click its icon and click Delete Breakpoint.

Breakpoints Window

The Breakpoints window shows all the breakpoints in your experience. To open the Breakpoints window, click the View tab at the top of Studio, then click Breakpoints.

Breakpoints window in Studio

The Breakpoints window has the following columns: unlabeled, Script, Line, Source Line, Condition, Log Message, and Continue Execution. The unlabeled, Script, and Line columns always display, but you can toggle the other columns by clicking the three dots in the top-right corner of the window.

In the unlabeled column, the (x3) label indicates the number of breakpoints on the same line of code, and the icon indicates the breakpoint configuration. The breakpoints on the same line share the same Condition, Log Message, and Continue Execution but vary in context. You can edit the configuration of a breakpoint in the Breakpoints window. For example, you can edit the Condition of a breakpoint by editing the textarea in its Condition column.

Edit the Condition of a Breakpoint in the Breakpoints Window

You can enable and disable breakpoints by clicking its breakpoint icon in the Enabled column. You can also click the following buttons to enable, disable, and delete some or all breakpoints.

Button Action
Button to disable all breakpointsDisable all breakpoints. If any breakpoints are disabled, enable them all.
Button to delete all breakpointsDelete all breakpoints.

Breakpoint Icons

The icon of a breakpoint depends on whether it's enabled, has a condition, and has a log message. If a breakpoint has a log message, then it appears as a logpoint regardless of whether it has a condition.

Name Icon Enabled Condition Log Message
BreakpointYes No No
No No No
Conditional BreakpointYes Yes No
No Yes No
LogpointYes Maybe Yes
No Maybe Yes

Additional Debugging Tools

In addition to the debugger, Studio offers additional debugging tools for you to fix problems and bugs in your experience.

Command Bar

The Command Bar allows you to run Luau commands while the experience is running. It is available in Studio from the View tab and in the Developer Console.

Developer Console

The Developer Console provides a wide array of details including client and server output, memory usage, network performance, and more. To open the Developer Console while testing or playing an experience, type /console into the chat or press F9. For more information, see Developer Console.

Log Files

When a script prints or errors in Studio or the Player app, the app records the message in a log file in the local file system. These files are located in different places depending on the operating system:

  • On Windows, logs are in the directory %LOCALAPPDATA%\Roblox\logs. Sort the folder by date modified. The names of log files start with the format log_XXXXX. Logs with the same XXXXX value are from the same Studio session.
  • On macOS, logs are in the directory ~/Library/Logs/Roblox. In the Finder, click the Go menu, select Go to Folder, type in that directory, and confirm.