# ScriptDebuggerService

Roblox Engine API class from Roblox Studio 0.744.0.7441077 (version-7aaa6838d36c4448).

- Inherits from, nearest first: [Instance](https://rapi.sleaze.dev/classes/Instance.md), [Object](https://rapi.sleaze.dev/classes/Object.md)
- Tags: Not creatable, Not replicated, Service
- Memory category: Instances
- HTML page: https://rapi.sleaze.dev/classes/ScriptDebuggerService/
- Roblox documentation: https://create.roblox.com/docs/reference/engine/classes/ScriptDebuggerService

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

## Methods

### AddBreakpoint

```luau
ScriptDebuggerService:AddBreakpoint(scriptInstance: LuaSourceContainer, breakpoint: { [string]: any }): { [string]: any }
```

- Tags: Plugin security

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

Parameters:

- `scriptInstance`: The [`LuaSourceContainer`](https://rapi.sleaze.dev/classes/LuaSourceContainer.md) to place the breakpoint on.
- `breakpoint`: 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 `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`](https://rapi.sleaze.dev/classes/DataModel.md) does not pause when the breakpoint is hit. Default is `false`.

Returns: 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`](https://rapi.sleaze.dev/classes/Message.md) — Optional explanation if `Verified` is `false`.

### ClearBreakpoints

```luau
ScriptDebuggerService:ClearBreakpoints()
```

- Tags: Plugin security

Removes all breakpoints across all scripts.

### Evaluate

```luau
ScriptDebuggerService:Evaluate(expression: string, frameId: number? = nil): { [string]: any }
```

- Tags: Plugin security

Evaluates a Luau expression in a stack frame's context.

Parameters:

- `expression`: The Luau expression to evaluate.
- `frameId`: Optional frame identifier. If omitted, evaluates globally.

Returns: 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()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md).

### GetRootVariables

```luau
ScriptDebuggerService:GetRootVariables(frameId: number): { any }
```

- Tags: Plugin security

Returns the root variables (locals, upvalues, globals) for a stack frame.

Parameters:

- `frameId`: The frame identifier from a debug stack frame `Id` field (see [`GetStackTrace()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md)).

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

- [`Name`](https://rapi.sleaze.dev/classes/Instance.md) — 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()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md) with this to get children.

### GetStackTrace

```luau
ScriptDebuggerService:GetStackTrace(threadId: number, startFrame: number? = nil): { [string]: any }
```

- Tags: Plugin security

Returns the call stack for a paused thread.

Parameters:

- `threadId`: The thread identifier from a script debug thread `Id` field (see [`GetThreads()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md)).
- `startFrame`: Optional 1-based frame index for paginated retrieval.

Returns: 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()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md) and [`Evaluate()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md).
- [`Name`](https://rapi.sleaze.dev/classes/Instance.md) — 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

```luau
ScriptDebuggerService:GetThreads(): { any }
```

- Tags: Plugin security

Returns all paused Luau threads.

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

- `Id` — Numerical thread identifier; use with [`GetStackTrace()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md) and stepping.
- [`Name`](https://rapi.sleaze.dev/classes/Instance.md) — Human-readable name of the script.

### GetVariables

```luau
ScriptDebuggerService:GetVariables(variablesReference: number): { any }
```

- Tags: Plugin security

Drills into structured variables (tables, [`Instances`](https://rapi.sleaze.dev/index/types/Instances.md)).

Parameters:

- `variablesReference`: A reference from a previous script variable's `VariablesReference` field (see [`GetRootVariables()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md)).

Returns: An array of script variable dictionaries representing the children in the same format as variable dictionaries from [`GetRootVariables()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md). Returns empty if the [`DataModel`](https://rapi.sleaze.dev/classes/DataModel.md) is not stopped at a breakpoint or exception, or when stopped via [`Pause()`](https://rapi.sleaze.dev/classes/ScriptDebuggerService.md).

### Pause

```luau
ScriptDebuggerService:Pause()
```

- Tags: Plugin security

Requests the debugger to pause at the next safe point.

### RemoveBreakpoint

```luau
ScriptDebuggerService:RemoveBreakpoint(scriptInstance: LuaSourceContainer, line: number): boolean
```

- Tags: Plugin security

Removes the breakpoint on the given script and line.

Parameters:

- `scriptInstance`: The [`LuaSourceContainer`](https://rapi.sleaze.dev/classes/LuaSourceContainer.md) containing the breakpoint.
- `line`: The 1-based line number of the breakpoint to remove.

Returns: `true` if a breakpoint was removed, `false` if no breakpoint existed on the line.

### SetExceptionBreakMode

```luau
ScriptDebuggerService:SetExceptionBreakMode(breakMode: Enum.DebugBreakModeType)
```

- Tags: Plugin security

Controls when the debugger pauses on exceptions.

Parameters:

- `breakMode`: The `DebugBreakModeType` to set.

## Events

### Resumed

```luau
ScriptDebuggerService.Resumed: RBXScriptSignal<(threadIds: { any })>
```

- Tags: Plugin security

Fires when a previously paused thread resumes execution.

## Callbacks

### OnStopped

```luau
ScriptDebuggerService.OnStopped: (stopped: { [string]: any }) -> { [string]: any }
```

- Tags: Plugin security

The primary callback for reacting to debugger pauses. Returns a resume action.

Parameters:

- `stopped`: 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: 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

- From [Instance](https://rapi.sleaze.dev/classes/Instance.md): `Archivable`, `archivable`, `Attributes`, `AttributesReplicate`, `AttributesSerialize`, `HistoryId`, `Name`, `Parent`, `PredictionMode`, `PropertyStatusStudio`, `RobloxLocked`, `SerializedOverrides`, `SourceAssetId`, `Tags`, `UniqueId`, `numExpectedDirectChildren`, `DataCost`, `Capabilities`, `DefinesCapabilities`, `IsInSandbox`, `Sandboxed`, `AddTag`, `ClearAllChildren`, `Clone`, `Destroy`, `FindFirstAncestor`, `FindFirstAncestorOfClass`, `FindFirstAncestorWhichIsA`, `FindFirstChild`, `FindFirstChildOfClass`, `FindFirstChildWhichIsA`, `FindFirstDescendant`, `GetActor`, `GetAttribute`, `GetAttributeChangedSignal`, `GetAttributes`, `GetChildren`, `GetDebugId`, `GetDescendants`, `GetFullName`, `GetStyled`, `GetStyledPropertyChangedSignal`, `GetTags`, `HasTag`, `IsAncestorOf`, `IsDescendantOf`, `IsPropertyModified`, `QueryDescendants`, `RemoveTag`, `ResetPropertyToDefault`, `SetAttribute`, `WaitForChild`, `Remove`, `children`, `clone`, `destroy`, `findFirstChild`, `getChildren`, `isDescendantOf`, `remove`, `AncestryChanged`, `AttributeChanged`, `ChildAdded`, `ChildRemoved`, `DescendantAdded`, `DescendantRemoving`, `Destroying`, `StyledPropertiesChanged`, `childAdded`
- From [Object](https://rapi.sleaze.dev/classes/Object.md): `ClassName`, `className`, `GetPropertyChangedSignal`, `IsA`, `isA`, `Changed`