debugger

The debugger namespace — 79 functions.

globals/debugger/__diagnostics

debugger.__diagnostics() -> DebuggerDiagnostics

Internal diagnostic counters for debugging the debugger itself: { installs, debugbreakHits }.

Returns DebuggerDiagnostics — Diagnostic counters.

globals/debugger/addWatch

debugger.addWatch(expr: string) -> number

Register an expression to re-evaluate on every pause.

Parameters

• expr string — Luau expression.

Returns number — Watch id.

globals/debugger/continue_

debugger.continue_() -> boolean

Resume the paused thread.

Returns boolean — True if a thread was paused, false if nothing was paused.

globals/debugger/disableAll

debugger.disableAll()

Disable every registered breakpoint. Records persist; bytecode BREAK ops are cleared.

globals/debugger/disconnect

debugger.disconnect(handle: number) -> boolean

Disconnect an onBreak or onResume callback.

Parameters

• handle number — Handle returned by onBreak/onResume.

Returns boolean — True if the handle existed.

globals/debugger/enableAll

debugger.enableAll()

Enable every registered breakpoint and re-install them in the VM bytecode.

globals/debugger/evaluate

debugger.evaluate(expr: string, frame: number?) -> (string?, string?)

Evaluate an expression against the paused frame's environment. Returns (value, error).

Parameters

• expr string — Luau expression.
• frame number (optional) — 1-based frame index (default 1).

Returns (string?, string?) — (value, error).

globals/debugger/getLocals

debugger.getLocals(frame: number?) -> { [string]: string }

Locals captured at the active pause for the given frame index (1 = top). Values are stringified for safe display.

Parameters

• frame number (optional) — 1-based frame index (default 1).

Returns { [string]: string } — { [name] = string }.

globals/debugger/getPauseInfo

debugger.getPauseInfo() -> PauseInfo?

Info about the active pause, or nil if nothing is paused.

Returns PauseInfo? — { path, line, reason } or nil.

globals/debugger/getStack

debugger.getStack() -> { Frame }

Captured stack from the active pause, top frame first. Empty when nothing is paused.

Returns { Frame } — Array of Frame tables.

globals/debugger/getUpvalues

debugger.getUpvalues(frame: number?) -> { [string]: string }

Upvalues captured at the active pause for the given frame.

Parameters

• frame number (optional) — 1-based frame index.

Returns { [string]: string } — { [name] = string }.

globals/debugger/getWatchValue

debugger.getWatchValue(id: number) -> (string?, string?)

Re-evaluate the watch expression against the paused frame's environment and return (value, error).

Parameters

• id number — Watch id.

Returns (string?, string?) — (value, error).

globals/debugger/getWatches

debugger.getWatches() -> { Watch }

Snapshot of all watches with their last evaluated value and error, sorted by id.

Returns { Watch } — Array of Watch tables.

globals/debugger/isPauseOnError

debugger.isPauseOnError() -> boolean

Current pause-on-error toggle state for this VM.

Returns boolean — True if enabled.

globals/debugger/isPaused

debugger.isPaused() -> boolean

Whether the debugger currently has a paused thread.

Returns boolean — True if paused.

globals/debugger/listBreakpoints

debugger.listBreakpoints() -> { Breakpoint }

Snapshot of every registered breakpoint, sorted by id ascending. Each entry reports whether it is installed: chunkNames lists the loaded chunks carrying it, and pendingReason says why an empty list is empty.

Returns { Breakpoint } — Array of breakpoint tables.

globals/debugger/onBreak

debugger.onBreak(fn: (PauseInfo) -> ()) -> number

Register a callback invoked on every pause with { path, line, reason }. Returns a handle usable with debugger.disconnect.

Parameters

• fn (PauseInfo) -> () — Callback.

Returns number — Handle.

globals/debugger/onResume

debugger.onResume(fn: () -> ()) -> number

Register a callback invoked when the paused thread is resumed.

Parameters

• fn () -> () — Callback.

Returns number — Handle.

globals/debugger/removeBreakpoint

debugger.removeBreakpoint(id: number) -> boolean

Remove the breakpoint with the given id.

Parameters

• id number — Breakpoint id returned by setBreakpoint.

Returns boolean — True if removed, false if the id was unknown.

globals/debugger/removeWatch

debugger.removeWatch(id: number) -> boolean

Remove the watch with the given id.

Parameters

• id number — Watch id.

Returns boolean — True if removed.

globals/debugger/setBreakpoint

debugger.setBreakpoint(path: string, line: number, opts: BreakpointOpts?) -> Breakpoint

Set a breakpoint at line in the script path names — its VFS path, its require identity, or the chunk name it loaded under. An installed breakpoint carries resolvedLine and lists the loaded chunks holding it in chunkNames; one whose script is not loaded carries pendingReason, an empty chunkNames, and installs itself when that script loads.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based source line.
• opts BreakpointOpts (optional) — { condition?, logMessage?, hitCount?, enabled? }.

Returns Breakpoint — The breakpoint table.

local bp = debugger.setBreakpoint("/zero/source/main.luau", 42)
print(bp.pendingReason or ("installed in " .. bp.chunkNames[1]))

globals/debugger/setPauseOnError

debugger.setPauseOnError(enabled: boolean)

When true, uncaught Luau errors fire the onBreak callback (observation only — the error still propagates).

Parameters

• enabled boolean — Toggle state.

globals/debugger/stepInto

debugger.stepInto() -> boolean

Run until the next line, descending into any function call.

Returns boolean — True if a step was scheduled.

globals/debugger/stepOut

debugger.stepOut() -> boolean

Run until the current frame returns; pauses in the caller.

Returns boolean — True if a step was scheduled.

globals/debugger/stepOver

debugger.stepOver() -> boolean

Run until the next line in the current frame. Calls inside the current line are skipped.

Returns boolean — True if a step was scheduled.

globals/debugger/toggleBreakpoint

debugger.toggleBreakpoint(path: string, line: number) -> Breakpoint?

Toggle a breakpoint at the given line: removes if present, adds otherwise.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based line.

Returns Breakpoint? — Breakpoint table if added, nil if removed.

modules/debugger/README

require("@builtin/modules/api/engine/debugger") -- debugger (also available as global 'debugger')

Luau debugger — breakpoints, stepping, stack inspection, watches. Public Luau surface over the __debugger Internal FFI namespace.

Usage: local debugger = require("@builtin/modules/api/engine/debugger") Also available as global: debugger

modules/debugger/__diagnostics

__diagnostics(): DebuggerDiagnostics

Internal diagnostic counters for debugging the debugger itself: { installs, debugbreakHits }.

modules/debugger/addWatch

addWatch(expr: string): number

Register an expression to re-evaluate on every pause.

Parameters

• expr string — Luau expression.

modules/debugger/continue_

continue_(): boolean

Resume the paused thread.

modules/debugger/disableAll

disableAll()

Disable every registered breakpoint. Records persist; bytecode BREAK ops are cleared.

modules/debugger/disconnect

disconnect(handle: number): boolean

Disconnect an onBreak or onResume callback.

Parameters

• handle number — Handle returned by onBreak/onResume.

modules/debugger/enableAll

enableAll()

Enable every registered breakpoint and re-install them in the VM bytecode.

modules/debugger/evaluate

evaluate(expr: string, frame: number?): (string?, string?)

Evaluate an expression against the paused frame's environment. Returns (value, error).

Parameters

• expr string — Luau expression.
• frame number? (optional) — 1-based frame index (default 1).

modules/debugger/getLocals

getLocals(frame: number?): { [string]: string }

Locals captured at the active pause for the given frame index (1 = top). Values are stringified for safe display.

Parameters

• frame number? (optional) — 1-based frame index (default 1).

modules/debugger/getPauseInfo

getPauseInfo(): PauseInfo?

Info about the active pause, or nil if nothing is paused.

modules/debugger/getStack

getStack(): { Frame }

Captured stack from the active pause, top frame first. Empty when nothing is paused.

modules/debugger/getUpvalues

getUpvalues(frame: number?): { [string]: string }

Upvalues captured at the active pause for the given frame.

Parameters

• frame number? (optional) — 1-based frame index.

modules/debugger/getWatchValue

getWatchValue(id: number): (string?, string?)

Re-evaluate the watch expression against the paused frame's environment and return (value, error).

Parameters

• id number — Watch id.

modules/debugger/getWatches

getWatches(): { Watch }

Snapshot of all watches with their last evaluated value and error, sorted by id.

modules/debugger/isPauseOnError

isPauseOnError(): boolean

Current pause-on-error toggle state for this VM.

modules/debugger/isPaused

isPaused(): boolean

Whether the debugger currently has a paused thread.

modules/debugger/listBreakpoints

listBreakpoints(): { Breakpoint }

Snapshot of every registered breakpoint, sorted by id ascending. Each entry reports whether it is installed: chunkNames lists the loaded chunks carrying it, and pendingReason says why an empty list is empty.

modules/debugger/onBreak

onBreak(fn: (PauseInfo) -> ()): number

Register a callback invoked on every pause with { path, line, reason }. Returns a handle usable with debugger.disconnect.

Parameters

• fn (PauseInfo) -> () — Callback.

modules/debugger/onResume

onResume(fn: () -> ()): number

Register a callback invoked when the paused thread is resumed.

Parameters

• fn () -> () — Callback.

modules/debugger/removeBreakpoint

removeBreakpoint(id: number): boolean

Remove the breakpoint with the given id.

Parameters

• id number — Breakpoint id returned by setBreakpoint.

modules/debugger/removeWatch

removeWatch(id: number): boolean

Remove the watch with the given id.

Parameters

• id number — Watch id.

modules/debugger/setBreakpoint

setBreakpoint(path: string, line: number, opts: BreakpointOpts?): Breakpoint

Set a breakpoint at line in the script path names — its VFS path, its require identity, or the chunk name it loaded under. An installed breakpoint carries resolvedLine and lists the loaded chunks holding it in chunkNames; one whose script is not loaded carries pendingReason, an empty chunkNames, and installs itself when that script loads.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based source line.
• opts BreakpointOpts? (optional) — { condition?, logMessage?, hitCount?, enabled? }.

local bp = debugger.setBreakpoint("/zero/source/main.luau", 42)
print(bp.pendingReason or ("installed in " .. bp.chunkNames[1]))

modules/debugger/setPauseOnError

setPauseOnError(enabled: boolean)

When true, uncaught Luau errors fire the onBreak callback (observation only — the error still propagates).

Parameters

• enabled boolean — Toggle state.

modules/debugger/stepInto

stepInto(): boolean

Run until the next line, descending into any function call.

modules/debugger/stepOut

stepOut(): boolean

Run until the current frame returns; pauses in the caller.

modules/debugger/stepOver

stepOver(): boolean

Run until the next line in the current frame. Calls inside the current line are skipped.

modules/debugger/toggleBreakpoint

toggleBreakpoint(path: string, line: number): Breakpoint?

Toggle a breakpoint at the given line: removes if present, adds otherwise.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based line.

typed/builtin//modules/api/engine/debugger/debugger/__diagnostics

debugger.__diagnostics() -> DebuggerDiagnostics

Internal diagnostic counters for debugging the debugger itself: { installs, debugbreakHits }.

Returns DebuggerDiagnostics — Diagnostic counters.

typed/builtin//modules/api/engine/debugger/debugger/addWatch

debugger.addWatch(expr: string) -> number

Register an expression to re-evaluate on every pause.

Parameters

• expr string — Luau expression.

Returns number — Watch id.

typed/builtin//modules/api/engine/debugger/debugger/continue_

debugger.continue_() -> boolean

Resume the paused thread.

Returns boolean — True if a thread was paused, false if nothing was paused.

typed/builtin//modules/api/engine/debugger/debugger/disableAll

debugger.disableAll()

Disable every registered breakpoint. Records persist; bytecode BREAK ops are cleared.

typed/builtin//modules/api/engine/debugger/debugger/disconnect

debugger.disconnect(handle: number) -> boolean

Disconnect an onBreak or onResume callback.

Parameters

• handle number — Handle returned by onBreak/onResume.

Returns boolean — True if the handle existed.

typed/builtin//modules/api/engine/debugger/debugger/enableAll

debugger.enableAll()

Enable every registered breakpoint and re-install them in the VM bytecode.

typed/builtin//modules/api/engine/debugger/debugger/evaluate

debugger.evaluate(expr: string, frame: number?) -> (string?, string?)

Evaluate an expression against the paused frame's environment. Returns (value, error).

Parameters

• expr string — Luau expression.
• frame number (optional) — 1-based frame index (default 1).

Returns (string?, string?) — (value, error).

typed/builtin//modules/api/engine/debugger/debugger/getLocals

debugger.getLocals(frame: number?) -> { [string]: string }

Locals captured at the active pause for the given frame index (1 = top). Values are stringified for safe display.

Parameters

• frame number (optional) — 1-based frame index (default 1).

Returns { [string]: string } — { [name] = string }.

typed/builtin//modules/api/engine/debugger/debugger/getPauseInfo

debugger.getPauseInfo() -> PauseInfo?

Info about the active pause, or nil if nothing is paused.

Returns PauseInfo? — { path, line, reason } or nil.

typed/builtin//modules/api/engine/debugger/debugger/getStack

debugger.getStack() -> { Frame }

Captured stack from the active pause, top frame first. Empty when nothing is paused.

Returns { Frame } — Array of Frame tables.

typed/builtin//modules/api/engine/debugger/debugger/getUpvalues

debugger.getUpvalues(frame: number?) -> { [string]: string }

Upvalues captured at the active pause for the given frame.

Parameters

• frame number (optional) — 1-based frame index.

Returns { [string]: string } — { [name] = string }.

typed/builtin//modules/api/engine/debugger/debugger/getWatchValue

debugger.getWatchValue(id: number) -> (string?, string?)

Re-evaluate the watch expression against the paused frame's environment and return (value, error).

Parameters

• id number — Watch id.

Returns (string?, string?) — (value, error).

typed/builtin//modules/api/engine/debugger/debugger/getWatches

debugger.getWatches() -> { Watch }

Snapshot of all watches with their last evaluated value and error, sorted by id.

Returns { Watch } — Array of Watch tables.

typed/builtin//modules/api/engine/debugger/debugger/isPauseOnError

debugger.isPauseOnError() -> boolean

Current pause-on-error toggle state for this VM.

Returns boolean — True if enabled.

typed/builtin//modules/api/engine/debugger/debugger/isPaused

debugger.isPaused() -> boolean

Whether the debugger currently has a paused thread.

Returns boolean — True if paused.

typed/builtin//modules/api/engine/debugger/debugger/listBreakpoints

debugger.listBreakpoints() -> { Breakpoint }

Snapshot of every registered breakpoint, sorted by id ascending. Each entry reports whether it is installed: chunkNames lists the loaded chunks carrying it, and pendingReason says why an empty list is empty.

Returns { Breakpoint } — Array of breakpoint tables.

typed/builtin//modules/api/engine/debugger/debugger/onBreak

debugger.onBreak(fn: (PauseInfo) -> ()) -> number

Register a callback invoked on every pause with { path, line, reason }. Returns a handle usable with debugger.disconnect.

Parameters

• fn (PauseInfo) -> () — Callback.

Returns number — Handle.

typed/builtin//modules/api/engine/debugger/debugger/onResume

debugger.onResume(fn: () -> ()) -> number

Register a callback invoked when the paused thread is resumed.

Parameters

• fn () -> () — Callback.

Returns number — Handle.

typed/builtin//modules/api/engine/debugger/debugger/removeBreakpoint

debugger.removeBreakpoint(id: number) -> boolean

Remove the breakpoint with the given id.

Parameters

• id number — Breakpoint id returned by setBreakpoint.

Returns boolean — True if removed, false if the id was unknown.

typed/builtin//modules/api/engine/debugger/debugger/removeWatch

debugger.removeWatch(id: number) -> boolean

Remove the watch with the given id.

Parameters

• id number — Watch id.

Returns boolean — True if removed.

typed/builtin//modules/api/engine/debugger/debugger/setBreakpoint

debugger.setBreakpoint(path: string, line: number, opts: BreakpointOpts?) -> Breakpoint

Set a breakpoint at line in the script path names — its VFS path, its require identity, or the chunk name it loaded under. An installed breakpoint carries resolvedLine and lists the loaded chunks holding it in chunkNames; one whose script is not loaded carries pendingReason, an empty chunkNames, and installs itself when that script loads.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based source line.
• opts BreakpointOpts (optional) — { condition?, logMessage?, hitCount?, enabled? }.

Returns Breakpoint — The breakpoint table.

local bp = debugger.setBreakpoint("/zero/source/main.luau", 42)
print(bp.pendingReason or ("installed in " .. bp.chunkNames[1]))

typed/builtin//modules/api/engine/debugger/debugger/setPauseOnError

debugger.setPauseOnError(enabled: boolean)

When true, uncaught Luau errors fire the onBreak callback (observation only — the error still propagates).

Parameters

• enabled boolean — Toggle state.

typed/builtin//modules/api/engine/debugger/debugger/stepInto

debugger.stepInto() -> boolean

Run until the next line, descending into any function call.

Returns boolean — True if a step was scheduled.

typed/builtin//modules/api/engine/debugger/debugger/stepOut

debugger.stepOut() -> boolean

Run until the current frame returns; pauses in the caller.

Returns boolean — True if a step was scheduled.

typed/builtin//modules/api/engine/debugger/debugger/stepOver

debugger.stepOver() -> boolean

Run until the next line in the current frame. Calls inside the current line are skipped.

Returns boolean — True if a step was scheduled.

typed/builtin//modules/api/engine/debugger/debugger/toggleBreakpoint

debugger.toggleBreakpoint(path: string, line: number) -> Breakpoint?

Toggle a breakpoint at the given line: removes if present, adds otherwise.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based line.

Returns Breakpoint? — Breakpoint table if added, nil if removed.