debugger

local debugger = require("@lute/debugger")

WARNING

These APIs are still open to future evolution. In new major versions, they may change in backwards incompatible ways.

Summary

Entry	Description
Breakpoint	A breakpoint that stops execution when encountered during runtime
BreakpointStatus	The status of a breakpoint, where pendingInstall and pendingUninstall means that the corresponding
LaunchConfig	A set of callbacks that we configure before launching our debugger
Target	A Target represents the target program under the debugger.
newTarget	Create a new Target handle on the current VM.

---

Types

Breakpoint

A breakpoint that stops execution when encountered during runtime

type Breakpoint = {
	id: number,
	line: number,
	sourcePath: string,
	status: BreakpointStatus,
}

---

BreakpointStatus

The status of a breakpoint, where pendingInstall and pendingUninstall means that the corresponding

operation is queued to happen when the script is next paused.

type BreakpointStatus = "pendingInstall" | "pendingUninstall" | "installed" | "invalid"

---

LaunchConfig

A set of callbacks that we configure before launching our debugger

type LaunchConfig = {
	--- called when a breakpoint `bp` is hit; execution is paused until continueProcess() is called
	onBreakpointHit: ((bp: Breakpoint) -> ())?,
	--- called when breakpoint `bp` is successfully installed in the VM
	onBreakpointInstall: ((bp: Breakpoint) -> ())?,
	--- called when a breakpoint `bp` is uninstalled from the VM
	onBreakpointUninstall: ((bp: Breakpoint) -> ())?,
	--- called when the debugged script exits. `success` reflects if the script exited without errors.
	onExit: ((success: boolean) -> ())?,
	--- called when a script actually pauses execution after a call to pauseProcess().
	onPause: (() -> ())?,
}

---

Target

A Target represents the target program under the debugger.

type Target = {
	--- Sets a breakpoint at `sourcePath` with a given line and queue it for installation.
	--- If this bp already existed return the preexisting breakpoint. Otherwise, it returns the new one.
	setBreakpoint: (self: Target, sourcePath: string, line: number) -> Breakpoint,
	--- Remove a breakpoint with a given `id` and queue for uninstall.
	--- Returns whether it was successful or not.
	removeBreakpoint: (self: Target, id: number) -> boolean,
	--- Get all breakpoints belonging to a target.
	getBreakpoints: (self: Target) -> { Breakpoint },
	--- Get all breakpoints belonging to a target with a certain status.
	getBreakpointsByStatus: (self: Target, status: BreakpointStatus) -> { Breakpoint },
	--- Get a breakpoint with a given id. Returns `nil` if not found.
	getBreakpointById: (self: Target, id: number) -> Breakpoint?,
	--- Get a breakpoint at a `sourcePath` at a given line. Returns `nil` if not found.
	getBreakpointBySourceLine: (self: Target, sourcePath: string, line: number) -> Breakpoint?,
	--- Launch a Luau script at at `sourcePath` with the relevant `args` and callbacks.
	--- Returns whether the script could be launched.
	launch: (self: Target, sourcePath: string, args: { string }?, config: LaunchConfig?) -> boolean,
	--- Continues a target script if it has been stopped. Return `true` if the target was actually stopped
	--- and `false` if it was not.
	continueProcess: (self: Target) -> boolean,
	--- Pauses a target script if it is running. Return `true` if the target was successfully paused
	--- and `false` if it was not.
	pauseProcess: (self: Target) -> boolean,
}

---

Functions and Properties

debugger.newTarget

Create a new Target handle on the current VM.

() -> Target

---