Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.
ScriptDebuggerService
Inherits from: Instance → Object
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.
Inherits from: Instance
Memory category: Instances
Tags: NotCreatable, Service, NotReplicated
Methods
| Name | Type / Returns | Description |
|---|---|---|
| ScriptDebuggerService:AddBreakpoint | ScriptBreakpointResult | Adds a breakpoint to a script. If a breakpoint already exists on the same script and line, its data is replaced. |
| ScriptDebuggerService:ClearBreakpoints | () | Removes all breakpoints across all scripts. |
| ScriptDebuggerService:Evaluate | ScriptEvaluateResult | Evaluates a Luau expression in a stack frame's context. |
| ScriptDebuggerService:GetRootVariables | List | Returns the root variables (locals, upvalues, globals) for a stack frame. |
| ScriptDebuggerService:GetStackTrace | DebugStackTraceResult | Returns the call stack for a paused thread. |
| ScriptDebuggerService:GetThreads | List | Returns all paused Luau threads. |
| ScriptDebuggerService:GetVariables | List | Drills into structured variables (tables, Instances). |
| ScriptDebuggerService:Pause | () | Requests the debugger to pause at the next safe point. |
| ScriptDebuggerService:RemoveBreakpoint | boolean | Removes the breakpoint on the given script and line. |
| ScriptDebuggerService:SetExceptionBreakMode | () | Controls when the debugger pauses on exceptions. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance:AddTag | () | Applies a tag to the instance. |
| Instance:children | Instances | Returns an array of the object's children. |
| Instance:ClearAllChildren | () | This method destroys all of an instance's children. |
| Instance:Clone | Instance | Create a copy of an instance and all its descendants, ignoring instances that are not Archivable. |
| Instance:clone | Instance | |
| Instance:Destroy | () | Sets the Instance.Parent property to nil, locks the Instance.Parent property, disconnects all connections, and calls Destroy() on all children. |
| Instance:destroy | () | |
| Instance:FindFirstAncestor | Instance? | Returns the first ancestor of the Instance whose Instance.Name is equal to the given name. |
| Instance:FindFirstAncestorOfClass | Instance? | Returns the first ancestor of the Instance whose Object.ClassName is equal to the given className. |
| Instance:FindFirstAncestorWhichIsA | Instance? | Returns the first ancestor of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstChild | Instance? | Returns the first child of the Instance found with the given name. |
| Instance:findFirstChild | Instance | |
| Instance:FindFirstChildOfClass | Instance? | Returns the first child of the Instance whose ClassName is equal to the given class name. |
| Instance:FindFirstChildWhichIsA | Instance? | Returns the first child of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstDescendant | Instance? | Returns the first descendant found with the given Instance.Name. |
| Instance:GetActor | Actor? | Returns the Actor associated with the Instance, if any. |
| Instance:GetAttribute | Variant | Returns the value which has been assigned to the given attribute name. |
| Instance:GetAttributeChangedSignal | RBXScriptSignal | Returns an event that fires when the given attribute changes. |
| Instance:GetAttributes | Dictionary | Returns a dictionary of the instance's attributes. |
| Instance:GetChildren | Instances | Returns an array containing all of the instance's children. |
| Instance:getChildren | Instances | |
| Instance:GetDebugId | string | Returns a coded string of the debug ID used internally by Roblox. |
| Instance:GetDescendants | Instances | Returns an array containing all of the descendants of the instance. |
| Instance:GetFullName | string | Returns a string describing the instance's ancestry. |
| Instance:GetStyled | Variant | Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified. |
| Instance:GetStyledPropertyChangedSignal | RBXScriptSignal | Returns an event that fires when the given style property changes on the instance. |
| Instance:GetTags | Array | Gets an array of all tags applied to the instance. |
| Instance:HasTag | boolean | Check whether the instance has a given tag. |
| Instance:IsAncestorOf | boolean | Returns true if an Instance is an ancestor of the given descendant. |
| Instance:IsDescendantOf | boolean | Returns true if an Instance is a descendant of the given ancestor. |
| Instance:isDescendantOf | boolean | |
| Instance:IsPropertyModified | boolean | Returns true if the value stored in the specified property is not equal to the code-instantiated default. |
| Instance:QueryDescendants | Instances | Returns an array containing all descendants of the instance that match the selector string. |
| Instance:Remove | () | Sets the object's Parent to nil, and does the same for all its descendants. |
| Instance:remove | () | |
| Instance:RemoveTag | () | Removes a tag from the instance. |
| Instance:ResetPropertyToDefault | () | Resets a property to its default value. |
| Instance:SetAttribute | () | Sets the attribute with the given name to the given value. |
| Instance:WaitForChild | Instance | Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object:GetPropertyChangedSignal | RBXScriptSignal | Get an event that fires when a given property of the object changes. |
| Object:IsA | boolean | Returns true if an object's class matches or inherits from a given class. |
| Object:isA | boolean |
ScriptDebuggerService:AddBreakpoint
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| scriptInstance | LuaSourceContainer | The LuaSourceContainer to place the breakpoint on. | |
| breakpoint | Dictionary | 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
| Type | Description |
|---|---|
| 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. |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:ClearBreakpoints
Removes all breakpoints across all scripts.
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:Evaluate
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| expression | string | The Luau expression to evaluate. | |
| frameId | int? | nil | Optional frame identifier. If omitted, evaluates globally. |
Returns
| Type | Description |
|---|---|
| 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(). |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:GetRootVariables
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().
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| frameId | int | The frame identifier from a debug stack frame Id field (see GetStackTrace()). |
Returns
| Type | Description |
|---|---|
| List | 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. |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:GetStackTrace
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| threadId | int | The thread identifier from a script debug thread Id field (see GetThreads()). | |
| startFrame | int? | nil | Optional 1-based frame index for paginated retrieval. |
Returns
| Type | Description |
|---|---|
| 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. |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:GetThreads
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
| Type | Description |
|---|---|
| List | 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. |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:GetVariables
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| variablesReference | int | A reference from a previous script variable's VariablesReference field (see GetRootVariables()). |
Returns
| Type | Description |
|---|---|
| List | 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(). |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:Pause
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
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:RemoveBreakpoint
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| scriptInstance | LuaSourceContainer | The LuaSourceContainer containing the breakpoint. | |
| line | int | The 1-based line number of the breakpoint to remove. |
Returns
| Type | Description |
|---|---|
| boolean | true if a breakpoint was removed, false if no breakpoint existed on the line. |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
ScriptDebuggerService:SetExceptionBreakMode
Sets the exception break mode on all DataModels. Use DebugBreakModeType to specify when the debugger should pause on exceptions.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| breakMode | DebugBreakModeType | The DebugBreakModeType to set. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
Events
| Name | Type / Returns | Description |
|---|---|---|
| ScriptDebuggerService.Resumed | Fires when a previously paused thread resumes execution. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.AncestryChanged | Fires when the Instance.Parent property of this object or one of its ancestors is changed. | |
| Instance.AttributeChanged | Fires whenever an attribute is changed on the Instance. | |
| Instance.ChildAdded | Fires after an object is parented to this Instance. | |
| Instance.childAdded | ||
| Instance.ChildRemoved | Fires after a child is removed from this Instance. | |
| Instance.DescendantAdded | Fires after a descendant is added to the Instance. | |
| Instance.DescendantRemoving | Fires immediately before a descendant of the Instance is removed. | |
| Instance.Destroying | Fires immediately before (or is deferred until after) the instance is destroyed via Instance:Destroy(). | |
| Instance.StyledPropertiesChanged | Fires whenever any style property is changed on the instance, including when a property is set to nil. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.Changed | Fires immediately after a property of the object changes, with some limitations. |
ScriptDebuggerService.Resumed
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| threadIds | Array | An array of thread identifiers that resumed. |
| Field | Value |
|---|---|
| security | PluginSecurity |
Callbacks
| Name | Type / Returns | Description |
|---|---|---|
| ScriptDebuggerService.OnStopped | ScriptResumeAction | The primary callback for reacting to debugger pauses. Returns a resume action. |
ScriptDebuggerService.OnStopped
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| stopped | Dictionary | Dictionary describing why the debugger paused. The following key-value pairs are valid: - Reason — ScriptStoppedReason why the debugger paused. - ThreadIds — Array of thread identifiers that stopped. - ExceptionText — Error message present when Reason is ScriptStoppedReason.Exception. |
Returns
| Type | Description |
|---|---|
| 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. |
| Field | Value |
|---|---|
| security | PluginSecurity |
| thread safety | Unsafe |
Properties
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.Archivable | boolean | Determines if an Instance and its descendants can be cloned using Instance:Clone(), and can be saved/published. |
| Instance.archivable | boolean | |
| Instance.Capabilities | SecurityCapabilities | The set of capabilities allowed to be used for scripts inside this container. |
| Instance.IsInSandbox | boolean | Indicates whether the instance is inside a sandboxed container. |
| Instance.Name | string | A non-unique identifier of the Instance. |
| Instance.Parent | Instance | Determines the hierarchical parent of the Instance. |
| Instance.PredictionMode | PredictionMode | Reflects the client-side prediction mode applied to the instance under server-authoritative physics. |
| Instance.RobloxLocked | boolean | A deprecated property that used to protect CoreGui objects. |
| Instance.Sandboxed | boolean | When enabled, the instance can only access abilities in its Capabilities list. |
| Instance.UniqueId | UniqueId | A unique identifier for the instance. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.ClassName | string | A read-only string representing the class this Object belongs to. |
| Object.className | string |