Roblox UtilitiesDevlHub Roblox Documentation

Class

ScriptDebuggerService

NotCreatableServiceNotReplicated
Inherits
Instance › Object
Memory category
Instances

Provides programmatic breakpoint management, execution control, and runtime inspection of Luau scripts during a playtest.

ScriptDebuggerService exposes the Roblox Studio Luau debugger for programmatic use. It provides functionality for breakpoint management, execution control, and runtime state inspection.

APIs in this class are currently in beta and are subject to breaking changes.

Breakpoint Propagation#

Breakpoints set in the edit DataModel are set on the specific script instance and do not propagate to clones, but they propagate to corresponding scripts in play data models at the start of a playtest. Breakpoints set in a play DataModel propagate to script clones in the same data model and to corresponding scripts in other data models.

Parallel Threads#

The behavior of this API with parallel Luau is undefined.

Methods 10#

AddBreakpointAdds a breakpoint to a script. If a breakpoint already exists on the same script and line, its data is replaced.PluginSecurity security
ClearBreakpointsRemoves all breakpoints across all scripts.PluginSecurity security
EvaluateEvaluates a Luau expression in a stack frame's context.PluginSecurity security
GetRootVariablesReturns the root variables (locals, upvalues, globals) for a stack frame.PluginSecurity security
GetStackTraceReturns the call stack for a paused thread.PluginSecurity security
GetThreadsReturns all paused Luau threads.PluginSecurity security
GetVariablesDrills into structured variables (tables, Instances).PluginSecurity security
PauseRequests the debugger to pause at the next safe point.PluginSecurity security
RemoveBreakpointRemoves the breakpoint on the given script and line.PluginSecurity security
SetExceptionBreakModeControls when the debugger pauses on exceptions.PluginSecurity security

AddBreakpoint(scriptInstance: LuaSourceContainer, breakpoint: Dictionary): ScriptBreakpointResult#

PluginSecurity security

Adds a breakpoint to the specified script. If a breakpoint already exists on the same script and line, its data is replaced with the new configuration.

Errors if the script instance or breakpoint argument is invalid.

NameTypeDefaultDescription
scriptInstanceLuaSourceContainerThe LuaSourceContainer to place the breakpoint on.
breakpointDictionary

Dictionary describing the breakpoint configuration through the following key-value pairs:

  • Line — Required 1-based line number.
  • Enabled — Optional boolean whether the breakpoint is active. Default is true.
  • Condition — Optional string indicating the Luau expression which must be truthy to pause, for example "health < 10".
  • LogMessage — Optional string message logged when the breakpoint is hit. This string is parsed as a comma-separated list of Luau expressions, evaluated in the breakpoint's scope, and concatenated LuaGlobals.print()‑style with spaces between segments. String literals are quoted; bare identifiers reference live values. For example, "'count is', count" produces output like count is 7.
  • ContinueExecution — If true, the DataModel does not pause when the breakpoint is hit. Default is false.
Returns
  • ScriptBreakpointResult —

    Dictionary indicating whether the breakpoint was placed successfully and on which line. Includes the following key-value pairs:

    • Verified — Boolean value indicating whether the breakpoint was placed successfully.
    • Line — The line number the breakpoint was placed on.
    • Message — Optional explanation if Verified is false.

ClearBreakpoints(): ()#

PluginSecurity security

Removes all breakpoints across all scripts.

Returns
  • ()

Evaluate(expression: string, frameId: int? = nil): ScriptEvaluateResult#

PluginSecurity security

Evaluates a Luau expression in the context of the specified stack frame, or globally if no frameId is provided.

Errors if the expression has a syntax error or frameId is invalid.

NameTypeDefaultDescription
expressionstringThe Luau expression to evaluate.
frameIdint?nilOptional frame identifier. If omitted, evaluates globally.
Returns
  • ScriptEvaluateResult —

    Dictionary with the following key-value pairs:

    • Result — String representation of the evaluated result.
    • Type — String indicating the Luau type of the result ("number", "string", "table", "Instance", etc.).
    • VariablesReference — If greater than 0, drill into with GetVariables().

GetRootVariables(frameId: int): List<ScriptVariable>#

PluginSecurity security

Returns the root variables (locals, upvalues, globals) for the specified stack frame. Each variable includes a VariablesReference field; if greater than 0, pass it to GetVariables() to drill into children.

Errors if frameId is invalid. Returns empty if the DataModel is not stopped at a breakpoint or exception, or when stopped via Pause().

NameTypeDefaultDescription
frameIdintThe frame identifier from a debug stack frame Id field (see GetStackTrace()).
Returns
  • List<ScriptVariable> —

    An array of script variable dictionaries, each containing the following key-value pairs:

    • Name — String value indicating the variable name or table key.
    • Value — String representation of the value.
    • Type — String indicating the Luau type ("number", "string", "table", "Instance", etc.).
    • Scope — ScriptVariableScope value (children inherit parent's scope).
    • VariablesReference — If greater than 0, call GetVariables() with this to get children.

GetStackTrace(threadId: int, startFrame: int? = nil): DebugStackTraceResult#

PluginSecurity security

Returns the call stack for a paused thread, ordered innermost (current execution point) to outermost. Use startFrame (1‑based) for paginated retrieval of large stacks.

Errors if threadId or startFrame is invalid.

NameTypeDefaultDescription
threadIdintThe thread identifier from a script debug thread Id field (see GetThreads()).
startFrameint?nilOptional 1-based frame index for paginated retrieval.
Returns
  • DebugStackTraceResult —

    Dictionary containing the frames ordered innermost (current) to outermost. Contains the following key-value pairs:

    • Frames — Array of debug stack frame dictionaries. Each dictionary item contains the following key-value pairs:
      • Id — Numerical frame identifier; use with GetRootVariables() and Evaluate().
      • Name — Human-readable name of the function at this frame.
      • ScriptPath — Full instance path of the script, for example "ServerScriptService.MainScript".
      • Line — 1-based line number where execution is paused at this frame.
    • TotalFrames — Total frame count, provided when paginating.

GetThreads(): List<ScriptDebugThread>#

PluginSecurity security

Returns all paused Luau threads. Should be called when the DataModel is stopped (typically inside OnStopped). Returns empty results when the DataModel is not stopped at a breakpoint or exception, or when stopped via Pause().

Returns
  • List<ScriptDebugThread> —

    An array of script debug thread dictionaries, each containing the following key-value pairs:

    • Id — Numerical thread identifier; use with GetStackTrace() and stepping.
    • Name — Human-readable name of the script.

GetVariables(variablesReference: int): List<ScriptVariable>#

PluginSecurity security

Drills into structured variables such as tables and Instances. Pass a VariablesReference obtained from a script variable returned by GetRootVariables() or a previous call to this method.

NameTypeDefaultDescription
variablesReferenceintA reference from a previous script variable's VariablesReference field (see GetRootVariables()).
Returns
  • List<ScriptVariable> — An array of script variable dictionaries representing the children in the same format as variable dictionaries from GetRootVariables(). Returns empty if the DataModel is not stopped at a breakpoint or exception, or when stopped via Pause().

Pause(): ()#

PluginSecurity security

Requests the debugger to pause at the next safe point. This method is asynchronous and returns immediately. When the thread pauses, OnStopped fires with reason ScriptStoppedReason.Pause. Has no effect if already stopped.

Only meaningful when the DataModel is running during a playtest. Calling Pause() while already stopped at a breakpoint has no effect.

Returns
  • ()

RemoveBreakpoint(scriptInstance: LuaSourceContainer, line: int): boolean#

PluginSecurity security

Removes the breakpoint at the specified line in the given script. Returns false if no breakpoint exists on the line (no-op). Errors if the script instance or line number is invalid.

NameTypeDefaultDescription
scriptInstanceLuaSourceContainerThe LuaSourceContainer containing the breakpoint.
lineintThe 1-based line number of the breakpoint to remove.
Returns
  • boolean — true if a breakpoint was removed, false if no breakpoint existed on the line.

SetExceptionBreakMode(breakMode: DebugBreakModeType): ()#

PluginSecurity security

Sets the exception break mode on all DataModels. Use DebugBreakModeType to specify when the debugger should pause on exceptions.

NameTypeDefaultDescription
breakModeDebugBreakModeTypeThe DebugBreakModeType to set.
Returns
  • ()

Events 1#

ResumedFires when a previously paused thread resumes execution.PluginSecurity security

Resumed(threadIds: Array)#

PluginSecurity security

Fires when a previously paused thread resumes. After this event, all frameId values, VariablesReference values, and script variable objects from that thread are invalidated. Re-fetch them the next time the DataModel stops if needed.

Avoid modifying the DataModel, throwing unhandled errors, or calling async yielding functions inside this event handler.

NameTypeDefaultDescription
threadIdsArrayAn array of thread identifiers that resumed.

Callbacks 1#

OnStoppedThe primary callback for reacting to debugger pauses. Returns a resume action.PluginSecurity security

OnStopped(stopped: Dictionary): ScriptResumeAction#

PluginSecurity security

The primary mechanism for reacting to debugger pauses. Set this to a function that receives a stopped payload and returns a script resume action dictionary indicating how execution should continue.

Only one OnStopped per DataModel is allowed; it is not inherited from the edit DataModel.

If the callback returns nothing or throws, DebuggerResumeType.Resume is assumed. Avoid modifying the DataModel, throwing unhandled errors, or calling async yielding functions inside this callback.

Late-Set Behavior#

If OnStopped is set while the DataModel is already stopped at a breakpoint and the previous value was nil, the callback runs immediately.

NameTypeDefaultDescription
stoppedDictionary

Dictionary describing why the debugger paused. The following key-value pairs are valid:

Returns
  • ScriptResumeAction —

    Dictionary specifying how to resume execution. Contains the following key-value pairs:

    • steppedType — DebuggerResumeType describing how to resume.
    • threadId — Number indicating which thread to step. Required for step actions.

Inherited members#

Inherited from Instance 58
Properties (10)

Archivable, archivable, Capabilities, IsInSandbox, Name, Parent, PredictionMode, RobloxLocked, Sandboxed, UniqueId

Methods (39)

AddTag, children, ClearAllChildren, Clone, clone, Destroy, destroy, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, FindFirstChild, findFirstChild, FindFirstChildOfClass, FindFirstChildWhichIsA, FindFirstDescendant, GetActor, GetAttribute, GetAttributeChangedSignal, GetAttributes, GetChildren, getChildren, GetDebugId, GetDescendants, GetFullName, GetStyled, GetStyledPropertyChangedSignal, GetTags, HasTag, IsAncestorOf, IsDescendantOf, isDescendantOf, IsPropertyModified, QueryDescendants, Remove, remove, RemoveTag, ResetPropertyToDefault, SetAttribute, WaitForChild

Events (9)

AncestryChanged, AttributeChanged, ChildAdded, childAdded, ChildRemoved, DescendantAdded, DescendantRemoving, Destroying, StyledPropertiesChanged

Inherited from Object 6
Properties (2)

ClassName, className

Methods (3)

GetPropertyChangedSignal, IsA, isA

Events (1)

Changed