NEOLearn

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.

Updated October 20, 2026

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#

  1. Start Play and open the Scripts panel (Project ▾ ▸ Scripts…).
  2. Choose Debug on a running script. The debugger view opens with the script's source.
  3. 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#

ButtonWhat it does
DebugAttaches the debugger to the script and opens the debugger view.
ContinueRuns to the next breakpoint, later in the recorded tick or in a later tick.
Step overThe next statement in this function or a function that called it.
Step intoThe next statement, including inside functions this one calls.
Step outThe next statement in a function that called this one.
Break nowStops at the next statement the script executes.
DetachReleases the script and reloads it without the debugger. Its state is kept.

What you see at a stop#

ShownWhat it is
SourceThe script with its breakpoints and the line it's held at.
LocalsThe variables in scope at this statement, and their values.
Call stackEach function from this one up to the handler, with its line.
this.stateThe script's state at this statement.
Contextshared, 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#

ScriptWho may debug it
The game's own scriptsYour Studio and tools on your machine.
A player's live scriptIts 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:

CommandWhat 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.listEvery 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.

See also#