SourcePawn Console Debugger
This extension allows you to set breakpoints in your SourcePawn plugins, step through them, and inspect the variables in scope as well as manipulate their values. It exposes a console debugger within a local "shell" to debug SourceMod plugins, similar to gdb or cdb. The interface is based on
pawndbg, the Pawn debugger, by ITB CompuPhase.
The extension adds a new "debug" option to the "sm" root menu which allows you to start a debugging session on a selected plugin:
Code:
sm debug
SourceMod Debug Menu:
start - Start debugging a plugin
next - Start debugging the plugin which is loaded next
bp - Handle breakpoints in a plugin
sm debug start
[SM] Usage: sm debug start <#|file>
sm debug bp
[SM] Usage: sm debug bp <#|file> <option>
list - List breakpoints
add - Add a breakpoint
remove - Remove a breakpoint
sm debug bp plugin add
[SM] Usage: sm debug bp <#|file> add <file:line | file:function>
The debugger works on source-code level (not on bytecode instruction level) and allows you to step through the lines in your source code and inspect variables by their name instead of using registers and adresses.
Since SourceMod is event based, the plugin might not execute code right away after you start debugging it. Depending on how you started debugging, you have to trigger the right code path through some event in order to start debugging. You can use "sm debug next" if you need to debug the plugin startup code which would otherwise already have run.
The debugger only works on a local server and not through a RCon connection. The whole process is paused while inside the debugger shell, so players might timeout if you take too long

. The watchdogs are disabled while you're in the debugger though.
Using the debugger shell
Once a breakpoint is reached or the next instruction is executed, you're presented with a "dbg>" prompt to issue debugger commands. Type "
?" or "
help" to see available commands and "
help command" to get more details on a specific command.
Code:
At the prompt, you can type debug commands. For example, the word "step" is a
command to execute a single line in the source code. The commands that you will
use most frequently may be abbreviated to a single letter: instead of the full
word "step", you can also type the letter "s" followed by the enter key.
Available commands:
backtrace display the stack trace
break set breakpoint at line number or function name
cbreak remove breakpoint
cwatch remove a "watchpoint"
continue run program (until breakpoint)
files list all files that this program is composed off
frame select a frame from the back trace to operate on
funcs display functions
next run until next line, step over functions
position show current file and line
print display the value of a variable, list variables
quit exit debugger
set set a variable to a value
step single step, step into functions
x eXamine plugin memory: x/FMT ADDRESS
watch set a "watchpoint" on a variable
Use "? <command name>" to view more information on a command
The command names and interfaces are not final and feedback is welcome.
Example debug session
We start debugging the currently running "basechat" plugin on the next instruciton, run a command it registers and change a variable's value.
Code:
sm debug start basechat
[SM] Pausing plugin Basic Chat for debugging. Will halt on next instruction.
sm_say lol
STOP at line 156 in basechat.sp in Command_SmSay frame: 1
dbg> n
STOP at line 158 in basechat.sp in Command_SmSay frame: 1
dbg>
STOP at line 164 in basechat.sp in Command_SmSay frame: 1
dbg>
STOP at line 165 in basechat.sp in Command_SmSay frame: 1
dbg>
STOP at line 167 in basechat.sp in Command_SmSay frame: 1
dbg> print
loc < 0x5454> char text[192] "lol"
arg < 0x5468> int args 1
arg < 0x5464> int client 0
dbg> set text="hello"
text set to "hello"
dbg> continue
L 01/19/2025 - 15:25:38: [basechat.smx] "Console<0><Console><Console>" triggered sm_say (text hello)
sm debug bp basechat add 167
[SM] Added breakpoint in file basechat.sp on line 167
sm_say lol
BREAK at line 167 in basechat.sp in Command_SmSay frame: 1
dbg> quit
Clearing all breakpoints. Running normally.
L 01/19/2025 - 15:26:13: [basechat.smx] "Console<0><Console><Console>" triggered sm_say (text lol)
sm_say lol
L 01/19/2025 - 15:26:29: [basechat.smx] "Console<0><Console><Console>" triggered sm_say (text lol)
Installation
Most of the required support in the SourcePawn Virtual Machine was added and merged over the years, which allows to step through plugins and map source line numbers to addresses. The last part, inspecting program state and variables, is not finalized yet and thus not merged in the upstream SourcePawn repository. This extension requires a
modified SourcePawn VM to work until the API is stable enough to be merged. The provided package includes such a VM build for your convenience.
- Download the build artifact for your Platform from Github. The one attached to this post might be outdated.
- Extract it on your server
- Restart your server
- The "sm debug" root menu entry should be available
https://github.com/peace-maker/sp-console-debugger/
Garey implemented a debugger adapter for Visual Studio Code based on this work. That might work for you too.