--- title: "debugger" description: "The debugger namespace — the engine's Luau API reference for debugger." section: "API Reference" slug: "api-debugger" canonical: "https://origozero.ai/docs/api-debugger" updated: "2026-09-05T23:13:46.330573552+00:00" tags: ["api", "reference"] --- # debugger The `debugger` namespace — 79 functions. ## globals/debugger/__diagnostics {#globals-debugger-diagnostics} ```lua debugger.__diagnostics() -> DebuggerDiagnostics ``` Internal diagnostic counters for debugging the debugger itself: `{ installs, debugbreakHits }`. **Returns** `DebuggerDiagnostics` — Diagnostic counters. ## globals/debugger/addWatch {#globals-debugger-addwatch} ```lua 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_ {#globals-debugger-continue} ```lua debugger.continue_() -> boolean ``` Resume the paused thread. **Returns** `boolean` — True if a thread was paused, false if nothing was paused. ## globals/debugger/disableAll {#globals-debugger-disableall} ```lua debugger.disableAll() ``` Disable every registered breakpoint. Records persist; bytecode BREAK ops are cleared. ## globals/debugger/disconnect {#globals-debugger-disconnect} ```lua 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 {#globals-debugger-enableall} ```lua debugger.enableAll() ``` Enable every registered breakpoint and re-install them in the VM bytecode. ## globals/debugger/evaluate {#globals-debugger-evaluate} ```lua 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 {#globals-debugger-getlocals} ```lua 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 {#globals-debugger-getpauseinfo} ```lua debugger.getPauseInfo() -> PauseInfo? ``` Info about the active pause, or nil if nothing is paused. **Returns** `PauseInfo?` — `{ path, line, reason }` or nil. ## globals/debugger/getStack {#globals-debugger-getstack} ```lua 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 {#globals-debugger-getupvalues} ```lua 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 {#globals-debugger-getwatchvalue} ```lua 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 {#globals-debugger-getwatches} ```lua 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 {#globals-debugger-ispauseonerror} ```lua debugger.isPauseOnError() -> boolean ``` Current pause-on-error toggle state for this VM. **Returns** `boolean` — True if enabled. ## globals/debugger/isPaused {#globals-debugger-ispaused} ```lua debugger.isPaused() -> boolean ``` Whether the debugger currently has a paused thread. **Returns** `boolean` — True if paused. ## globals/debugger/listBreakpoints {#globals-debugger-listbreakpoints} ```lua 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 {#globals-debugger-onbreak} ```lua 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 {#globals-debugger-onresume} ```lua debugger.onResume(fn: () -> ()) -> number ``` Register a callback invoked when the paused thread is resumed. **Parameters** - `fn` `() -> ()` — Callback. **Returns** `number` — Handle. ## globals/debugger/removeBreakpoint {#globals-debugger-removebreakpoint} ```lua 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 {#globals-debugger-removewatch} ```lua 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 {#globals-debugger-setbreakpoint} ```lua 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. ```lua local bp = debugger.setBreakpoint("/zero/source/main.luau", 42) print(bp.pendingReason or ("installed in " .. bp.chunkNames[1])) ``` ## globals/debugger/setPauseOnError {#globals-debugger-setpauseonerror} ```lua 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 {#globals-debugger-stepinto} ```lua debugger.stepInto() -> boolean ``` Run until the next line, descending into any function call. **Returns** `boolean` — True if a step was scheduled. ## globals/debugger/stepOut {#globals-debugger-stepout} ```lua debugger.stepOut() -> boolean ``` Run until the current frame returns; pauses in the caller. **Returns** `boolean` — True if a step was scheduled. ## globals/debugger/stepOver {#globals-debugger-stepover} ```lua 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 {#globals-debugger-togglebreakpoint} ```lua 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 {#modules-debugger-readme} ```lua 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 {#modules-debugger-diagnostics} ```lua __diagnostics(): DebuggerDiagnostics ``` Internal diagnostic counters for debugging the debugger itself: `{ installs, debugbreakHits }`. ## modules/debugger/addWatch {#modules-debugger-addwatch} ```lua addWatch(expr: string): number ``` Register an expression to re-evaluate on every pause. **Parameters** - `expr` `string` — Luau expression. ## modules/debugger/continue_ {#modules-debugger-continue} ```lua continue_(): boolean ``` Resume the paused thread. ## modules/debugger/disableAll {#modules-debugger-disableall} ```lua disableAll() ``` Disable every registered breakpoint. Records persist; bytecode BREAK ops are cleared. ## modules/debugger/disconnect {#modules-debugger-disconnect} ```lua disconnect(handle: number): boolean ``` Disconnect an onBreak or onResume callback. **Parameters** - `handle` `number` — Handle returned by onBreak/onResume. ## modules/debugger/enableAll {#modules-debugger-enableall} ```lua enableAll() ``` Enable every registered breakpoint and re-install them in the VM bytecode. ## modules/debugger/evaluate {#modules-debugger-evaluate} ```lua 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 {#modules-debugger-getlocals} ```lua 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 {#modules-debugger-getpauseinfo} ```lua getPauseInfo(): PauseInfo? ``` Info about the active pause, or nil if nothing is paused. ## modules/debugger/getStack {#modules-debugger-getstack} ```lua getStack(): { Frame } ``` Captured stack from the active pause, top frame first. Empty when nothing is paused. ## modules/debugger/getUpvalues {#modules-debugger-getupvalues} ```lua 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 {#modules-debugger-getwatchvalue} ```lua 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 {#modules-debugger-getwatches} ```lua getWatches(): { Watch } ``` Snapshot of all watches with their last evaluated value and error, sorted by id. ## modules/debugger/isPauseOnError {#modules-debugger-ispauseonerror} ```lua isPauseOnError(): boolean ``` Current pause-on-error toggle state for this VM. ## modules/debugger/isPaused {#modules-debugger-ispaused} ```lua isPaused(): boolean ``` Whether the debugger currently has a paused thread. ## modules/debugger/listBreakpoints {#modules-debugger-listbreakpoints} ```lua 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 {#modules-debugger-onbreak} ```lua 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 {#modules-debugger-onresume} ```lua onResume(fn: () -> ()): number ``` Register a callback invoked when the paused thread is resumed. **Parameters** - `fn` `() -> ()` — Callback. ## modules/debugger/removeBreakpoint {#modules-debugger-removebreakpoint} ```lua removeBreakpoint(id: number): boolean ``` Remove the breakpoint with the given id. **Parameters** - `id` `number` — Breakpoint id returned by setBreakpoint. ## modules/debugger/removeWatch {#modules-debugger-removewatch} ```lua removeWatch(id: number): boolean ``` Remove the watch with the given id. **Parameters** - `id` `number` — Watch id. ## modules/debugger/setBreakpoint {#modules-debugger-setbreakpoint} ```lua 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? }`. ```lua local bp = debugger.setBreakpoint("/zero/source/main.luau", 42) print(bp.pendingReason or ("installed in " .. bp.chunkNames[1])) ``` ## modules/debugger/setPauseOnError {#modules-debugger-setpauseonerror} ```lua 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 {#modules-debugger-stepinto} ```lua stepInto(): boolean ``` Run until the next line, descending into any function call. ## modules/debugger/stepOut {#modules-debugger-stepout} ```lua stepOut(): boolean ``` Run until the current frame returns; pauses in the caller. ## modules/debugger/stepOver {#modules-debugger-stepover} ```lua stepOver(): boolean ``` Run until the next line in the current frame. Calls inside the current line are skipped. ## modules/debugger/toggleBreakpoint {#modules-debugger-togglebreakpoint} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-diagnostics} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-addwatch} ```lua 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_ {#typed-builtin-modules-api-engine-debugger-debugger-continue} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-disableall} ```lua debugger.disableAll() ``` Disable every registered breakpoint. Records persist; bytecode BREAK ops are cleared. ## typed/builtin//modules/api/engine/debugger/debugger/disconnect {#typed-builtin-modules-api-engine-debugger-debugger-disconnect} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-enableall} ```lua debugger.enableAll() ``` Enable every registered breakpoint and re-install them in the VM bytecode. ## typed/builtin//modules/api/engine/debugger/debugger/evaluate {#typed-builtin-modules-api-engine-debugger-debugger-evaluate} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-getlocals} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-getpauseinfo} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-getstack} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-getupvalues} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-getwatchvalue} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-getwatches} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-ispauseonerror} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-ispaused} ```lua debugger.isPaused() -> boolean ``` Whether the debugger currently has a paused thread. **Returns** `boolean` — True if paused. ## typed/builtin//modules/api/engine/debugger/debugger/listBreakpoints {#typed-builtin-modules-api-engine-debugger-debugger-listbreakpoints} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-onbreak} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-onresume} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-removebreakpoint} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-removewatch} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-setbreakpoint} ```lua 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. ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-setpauseonerror} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-stepinto} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-stepout} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-stepover} ```lua 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 {#typed-builtin-modules-api-engine-debugger-debugger-togglebreakpoint} ```lua 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.