Debugging scripts
Stop a running script at a breakpoint in the Studio's Scripts panel, step through it, and read its locals, call stack and state.
On this page
The Studio's Scripts panel has a debugger. It stops a running script at a breakpoint, steps through it, and shows the locals, the call stack and this.state at each statement. It works for JavaScript and Python, and for shared, @server and @client code.
Start debugging#
- Start Play and open the Scripts panel (Project ▾ ▸ Scripts…).
- Choose Debug on a running script. The debugger view opens with the script's source.
- Click a line to set a breakpoint on it. Click it again to clear it.
When a statement on that line runs, the script stops, and the view marks the line it's at.
Attaching reloads the script with checks before each statement. Its this.state is kept and its pending timers are dropped, like any hot reload. A debugged script uses a little more fuel per statement; nothing else about it changes.
How a stop works#
A script can't be frozen in the middle of a tick, so the debugger records instead:
- When the script stops, the debugger records the statement it stopped at and every statement after it in that tick, each with its line, locals, call stack and
this.state. - The tick then finishes, and the script is held: it runs no more ticks until you go on.
- Stepping moves through the recording. Every value you see is the value at that statement.
- Past the last recorded statement, the script runs on and stops at the next statement it executes.
The controls#
| Button | What it does |
|---|---|
| Debug | Attaches the debugger to the script and opens the debugger view. |
| Continue | Runs to the next breakpoint, later in the recorded tick or in a later tick. |
| Step over | The next statement in this function or a function that called it. |
| Step into | The next statement, including inside functions this one calls. |
| Step out | The next statement in a function that called this one. |
| Break now | Stops at the next statement the script executes. |
| Detach | Releases the script and reloads it without the debugger. Its state is kept. |
What you see at a stop#
| Shown | What it is |
|---|---|
| Source | The script with its breakpoints and the line it's held at. |
| Locals | The variables in scope at this statement, and their values. |
| Call stack | Each function from this one up to the handler, with its line. |
| this.state | The script's state at this statement. |
| Context | shared, server or client: which sandbox stopped. See Contexts and remotes. |
Python scripts show Python lines and Python values (None, True).
In a multiplayer session#
Holding a script holds it on your machine only. The other players' games keep running it. While it's held, your script hash chain differs from theirs; it matches again once you continue or detach.
Who may debug a script#
| Script | Who may debug it |
|---|---|
| The game's own scripts | Your Studio and tools on your machine. |
| A player's live script | Its author, the game's owner, or a moderator. The session host's own tools can too. Never another player. |
When a tool debugs a player's live script, it says who is asking with as (a player id).
Commands#
Everything in the debugger is also a command, for tools and agents:
| Command | What it does |
|---|---|
script.debug.attach {name, as?} | Attaches the debugger (the panel's Debug). |
script.debug.break {name, line, on?, as?} | Sets a breakpoint on a line (on: false clears it). Attaches if needed. |
script.debug.pause {name, as?} | Stops at the next statement (Break now). |
script.debug.continue {name, as?} | Goes on to the next breakpoint. |
script.debug.step {name, mode, as?} | Steps: mode is into, over (the default) or out. |
script.debug.detach {name, as?} | Releases the script and reloads it without the debugger. |
script.debug.state {name} | The session: breakpoints, the lines that can stop, and at a stop the line, function, call stack, locals, this.state and the tick's recording. |
script.debug.list | Every debugger session. |
editor.scripts.debugger {name?, open?, top?} | Shows (attaching the debugger) or hides the panel's debugger view, and scrolls its source so line top is first. |
See Script commands for the results.
Known limits#
- The list of lines that can take a breakpoint can include a few stray lines before
"use strict"or the imports. Set breakpoints on your own statements.