Key Takeaways
ScriptDebuggerServiceships today in beta, giving plugins programmatic control over the Studio debugger. Set conditional breakpoints and logpoints, inspect the variables and call stack of stopped threads, and control script execution, all from Luau. Studio Assistant can now drive the debugger itself, setting breakpoints, running your game, and reading live runtime state to track down bugs that static code review can’t catch.Try the new API in Studio.
Hi Creators,
We’re excited to announce the beta release ofScriptDebuggerService, a Luau API that gives you programmatic control over the Studio debugger.
Studio debugging has always been hands-on: click to set breakpoints, step through by hand, hover to read values. ScriptDebuggerService opens that whole workflow up to code. Build your own debugging plugins and tooling on the API, or let Assistant drive the debugger for you through the new debugging Skill. Both paths use the same API.
The API
ScriptDebuggerService lets your plugins:
- Manage breakpoints and logpoints: Attach them to specific scripts, gate breakpoints behind a condition so they only fire in the state you care about, and print runtime values with logpoints that never pause execution.
- Inspect stopped threads: Walk the call stack of any paused thread, read every variable in a frame (including nested tables) by scope, name, value, and type, and evaluate arbitrary Luau expressions against the paused frame.
- Control execution: Decide how the debugger responds to each stop, step into, over, and out of calls line by line, and set exception break modes to halt automatically on errors.
Workflows This API Unlocks
- Conditional bug hunting: Break only when a variable hits the bad state you’re chasing (
num < 6, health < 0, a nil where you expected an instance), so you skip every healthy iteration and stop exactly where it goes wrong. - Non-invasive logging: Drop logpoints to print runtime values without editing your scripts, pausing the game, or leaving behind stray
print()calls to clean up later. - Automatic exception triage: Break on every error, or only on the ones your code doesn’t catch, then dump the variables and call stack at the moment of failure. This is how you pin down the intermittent crash that only shows up one run in fifty.
- Interactive inspection: Step through code line by line and evaluate Luau against a paused frame, REPL-style, to test a hypothesis or read a derived value without editing and re-running.
Examples
Add breakpoints and logpoints - Click to expand
local sds = game:GetService("ScriptDebuggerService")
-- Breakpoints pause execution when a line
-- is about to run. Conditionally break when
-- a condition is met (variable "num" < 6)
local breakpoint: ScriptBreakpoint = {
Line = 1,
Condition = "num < 6"
}
-- Logpoints do not pause execution. They
-- typically print a message to debug
-- without needing to edit scripts or stop.
local logpoint: ScriptBreakpoint = {
Line = 2,
LogMessage = "Hit breakpoint!",
ContinueExecution = true
}
-- Attach the created breakpoint/logpoint
-- to specific scripts
sds:AddBreakpoint(workspace.Script1, breakpoint)
sds:AddBreakpoint(workspace.Script2, logpoint)
Inspect runtime state on a stop, with exception breaking turned on - Click to expand
local sds = game:GetService("ScriptDebuggerService")
-- Stop execution for EVERY error hit
sds:SetExceptionBreakMode(Enum.DebugBreakModeType.Always)
-- OnStopped is called whenever the
-- debugger pauses
sds.OnStopped = function(info: ScriptDebugStopped)
-- Resume past non-error stops (e.g., breakpoints)
if info.Reason ~= Enum.ScriptStoppedReason.Exception then
return Enum.DebuggerResumeType.Resume
end
print("EXCEPTION:", info.ExceptionText)
-- Find where the error happened and dump all the
-- variables there to inspect the current state
local stack = sds:GetStackTrace(info.ThreadIds[1])
local vars = sds:GetRootVariables(stack.Frames[1].Id)
for _, v in vars do
print(string.format("%s = %s (%s)", v.Name, v.Value, v.Type))
end
return Enum.DebuggerResumeType.Resume
end
Full method lists, the ScriptBreakpoint schema, and every enum live in the ScriptDebuggerService documentation.
Debugging with Studio Assistant
With the new debugging Skill, Assistant can debug from your game’s live runtime state, not just from reading your code.
We’ve integrated ScriptDebuggerService into Studio’s Assistant with a new debugging Skill, and it changes what Assistant can do with a bug report.
Reading code only gets Assistant so far. Some bugs only become clear while the game is running: a variable turns nil on the third spawn, or a value drifts out of range mid-playtest. Until now, Assistant could reason about what should happen. Now, it can run the debugger and see what actually happens.
When you describe a bug, the Skill drives the whole loop on its own:
- Sets breakpoints and logpoints in the relevant scripts, gated behind conditions so they fire only in the state you care about.
- Runs your game and waits for the debugger to stop at the right moment.
- Inspects the live state, walking the call stack, reading variables, drilling into nested tables, and evaluating expressions against the paused frame.
- Finds the root cause by comparing what’s happening against what you expected, then proposes a fix grounded in what it observed.
Some things you can hand it:
- “Players sometimes spawn without a weapon. Set breakpoints, find out why, and fix it.”
- “Something errors a few minutes into a playtest. Break on the exception and show me the state at the crash.”
When your request looks like a debugging problem, Assistant applies this Skill automatically.
What’s Next
We’re excited to gather your feedback on this feature, hear your suggestions for future improvements, and keep improving how AI handles debugging workflows in Studio. Let us know what you run into and what you’d like to debug next.
Happy debugging,
The Roblox Studio Team
