### SDK_OnLoad Function

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Initializes the debugger extension and installs the debug break handler.

```APIDOC
## SDK_ONLOAD FUNCTION

### Description
Initializes the debugger extension and installs the debug break handler.

### Signature
```cpp
bool ConsoleDebugger::SDK_OnLoad(char *error, size_t maxlength, bool late)
```

### Parameters
*   `error` (char *): Buffer to store error messages.
*   `maxlength` (size_t): Maximum length of the error buffer.
*   `late` (bool): Flag indicating if the extension is loaded late.

### Return Value
*   `true` on success, `false` on failure (error message set in `error` buffer).

### Implementation Details
*   Checks for VM debugging API version (>= 5).
*   Initializes the debugger map.
*   Installs the `OnDebugBreak` handler.
*   Registers console commands and plugin listener.
```

--------------------------------

### SDK_OnLoad Function (C++)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Initializes the SourceMod console debugger extension by checking VM compatibility, setting up internal mappings, and installing the debug break handler. It also registers console commands and plugin listeners.

```cpp
bool ConsoleDebugger::SDK_OnLoad(char *error, size_t maxlength, bool late)
{
    // Check VM supports debugging (API version 5+)
    if (smutils->GetScriptingEngine()->GetEngineAPIVersion() < 5)
    {
        ke::SafeStrcpy(error, maxlength,
            "This SourcePawn VM doesn't support line debugging.");
        return false;
    }

    // Initialize debugger map for tracking plugin instances
    if (!debugger_map_.init())
    {
        ke::SafeStrcpy(error, maxlength,
            "Failed to setup plugin -> debugger instance map.");
        return false;
    }

    // Install debug break handler in SourcePawn VM
    if (smutils->GetScriptingEngine()->SetDebugBreakHandler(OnDebugBreak)
        != SP_ERROR_NONE)
    {
        ke::SafeStrcpy(error, maxlength,
            "Failed to install debugger in the SourcePawn VM.");
        return false;
    }

    // Register console commands and plugin listener
    plsys->AddPluginsListener(this);
    rootconsole->AddRootConsoleCommand3("debug", "Debug Plugins", this);

    return true;
}
// Returns true on success, false on failure with error message set
```

--------------------------------

### SourceMod Debug Console Commands

Source: https://github.com/peace-maker/sp-console-debugger/blob/master/README.md

Demonstrates the basic commands available within the SourceMod debug console menu for starting and managing plugin debugging and breakpoints. These commands are accessed via the 'sm debug' command.

```sourcepawn_console
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>
```

--------------------------------

### Build sp-console-debugger Extension

Source: https://github.com/peace-maker/sp-console-debugger/blob/master/README.md

Steps to clone the sp-console-debugger repository and build the extension using a configured SourceMod installation. This process involves Python configuration and the ambuild tool.

```bash
git clone https://github.com/peace-maker/sp-console-debugger
cd sp-console-debugger
python configure.py --enable-optimize --sm-path /path/to/sourcemod_debugger
ambuild objdir
# install extension from objdir/package. make sure to copy the .autoload file too.
```

--------------------------------

### List Files and Functions (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Display all source files that make up the current plugin or list all defined functions with their memory addresses. These commands aid in understanding the plugin's structure and code locations.

```shell
# List all source files
dbg> files

# Expected output:
# Files in this plugin:
# [0] include/sourcemod.inc
# [1] include/sdktools.inc
# [2] myplugin.sp

# Display all functions
dbg> funcs

# Expected output:
# Functions:
# OnPluginStart @ 0x00000120
# OnClientPutInServer @ 0x00000350
# CheckPlayerStatus @ 0x00000560
# OnPlayerDeath @ 0x00000780
```

--------------------------------

### Files Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Lists all source files that are part of the currently loaded plugin.

```APIDOC
## FILES COMMAND

### Description
Lists all source files that compose the current plugin.

### Syntax
```
dbg> files
```

### Example
```bash
dbg> files

# Expected output:
# Files in this plugin:
# [0] include/sourcemod.inc
# [1] include/sdktools.inc
# [2] myplugin.sp
```
```

--------------------------------

### Initialize Debugger on Plugin Load (C++)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

This function initializes a debugger instance for each plugin when it is loaded. It creates a Debugger object, attempts to initialize it, and stores it in a map for later retrieval. It also handles the auto-start of debugging if requested.

```cpp
void ConsoleDebugger::OnPluginLoaded(IPlugin *plugin)
{
    // Create debugger instance for this plugin
    Debugger *debugger = new Debugger(plugin->GetBaseContext());
    if (!debugger->Initialize()) {
        smutils->LogError(myself,
            "Failed to initialize debugger instance for plugin %s.",
            plugin->GetFilename());
        delete debugger;
        return;
    }

    // Store in map for later retrieval
    DebuggerMap::Insert i = debugger_map_.findForAdd(plugin->GetBaseContext());
    debugger_map_.add(i, plugin->GetBaseContext(), debugger);

    // Auto-start debugging if requested via "sm debug next"
    if (debug_next_plugin_) {
        debug_next_plugin_ = false;
        debugger->Activate();
        debugger->SetRunmode(STEPPING);
    }
}
// Automatically called by SourceMod when any plugin loads
```

--------------------------------

### Build SourceMod with Modified SourcePawn VM

Source: https://github.com/peace-maker/sp-console-debugger/blob/master/README.md

Instructions for cloning and building SourceMod with a forked SourcePawn VM that includes necessary changes for debug API symbols. This is a prerequisite for building the sp-console-debugger extension.

```bash
git clone --recurse-submodules https://github.com/alliedmodders/sourcemod sourcemod_debugger
# Switch to the debug symbol modification of SourcePawn
cd sourcemod_debugger/sourcepawn
git remote add peace-maker https://github.com/peace-maker/sourcepawn
git fetch peace-maker
git switch debug_api_symbols
cd ..
python configure.py --sdks css --enable-optimize --no-mysql
ambuild objdir
# install sourcemod from objdir/package
```

--------------------------------

### Functions Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Displays all functions defined within the plugin, along with their memory addresses.

```APIDOC
## FUNCTIONS COMMAND

### Description
Display all functions defined in the plugin with their addresses.

### Syntax
```
dbg> funcs
```

### Example
```bash
dbg> funcs

# Expected output:
# Functions:
# OnPluginStart @ 0x00000120
# OnClientPutInServer @ 0x00000350
# CheckPlayerStatus @ 0x00000560
# OnPlayerDeath @ 0x00000780
```
```

--------------------------------

### Examine Memory Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Inspects raw plugin memory at specified addresses with various formatting options.

```APIDOC
## EXAMINE MEMORY COMMAND

### Description
Inspect raw plugin memory at specific addresses with various formatting options.

### Syntax
```
x/COUNT[FORMAT][SIZE] ADDRESS
```

### Format Specifiers
*   **COUNT**: Number of units to display.
*   **FORMAT**: `x` (hex), `d` (decimal), `u` (unsigned), `o` (octal), `t` (binary), `c` (char).
*   **SIZE**: `b` (byte), `h` (halfword), `w` (word), `g` (giant, 8 bytes).

### Examples
```bash
# Examine 16 bytes as hexadecimal words at address 0x1000
dbg> x/16xw 0x1000

# Expected output:
# 0x00001000: 0x00000001 0x00000064 0x00000000 0x00000014
# 0x00001010: 0x00000050 0x0000006c 0x00000061 0x00000079

# Examine as decimal integers
dbg> x/8dw 0x1000
# Output: decimal values

# Examine as characters
dbg> x/32cb 0x1020
# Output: ASCII character representation
```
```

--------------------------------

### Examine Memory (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Inspect raw plugin memory at specified addresses using various formatting options like hexadecimal, decimal, or character representation. The command format is 'x/COUNT[FORMAT][SIZE] ADDRESS'.

```shell
# Examine 16 bytes as hexadecimal words at address 0x1000
dbg> x/16xw 0x1000

# Expected output:
# 0x00001000: 0x00000001 0x00000064 0x00000000 0x00000014
# 0x00001010: 0x00000050 0x0000006c 0x00000061 0x00000079

# Examine as decimal integers
dbg> x/8dw 0x1000
# Output: decimal values

# Examine as characters
dbg> x/32cb 0x1020
# Output: ASCII character representation

# Format: x/COUNT[FORMAT][SIZE] ADDRESS
# FORMAT: x (hex), d (decimal), u (unsigned), o (octal), t (binary), c (char)
# SIZE: b (byte), h (halfword), w (word), g (giant, 8 bytes)
```

--------------------------------

### SourcePawn Debugger Shell Commands

Source: https://github.com/peace-maker/sp-console-debugger/blob/master/README.md

Lists the available commands for interacting with the SourcePawn debugger once it's active in the shell. These commands allow for control over program execution, breakpoint management, and variable inspection.

```debugger_shell
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       xEamine plugin memory: x/FMT ADDRESS
        watch   set a "watchpoint" on a variable

        Use "? <command name>" to view more information on a command
```

--------------------------------

### Handle Debug Break Events (C++)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

This function is called by the SourcePawn VM when a debug break instruction is encountered. It retrieves the relevant debugger instance, handles exceptions, checks for breakpoints, looks up the current code location, and enters the interactive debugger shell.

```cpp
void OnDebugBreak(IPluginContext *ctx, sp_debug_break_info_t& dbginfo,
                  const SourcePawn::IErrorReport *report)
{
    // Get debugger instance for this plugin
    Debugger *debugger = g_Debugger.GetPluginDebugger(ctx);
    if (!debugger || !debugger->active())
        return; // Continue if not being debugged

    // Handle exceptions
    if (report) {
        if (report->IsFatal())
            printf("STOP on FATAL exception: %s\n", report->Message());
        else
            printf("STOP on exception: %s\n", report->Message());
    }

    // Check for breakpoint
    bool isBreakpoint = false;
    if (debugger->runmode() != Runmode::STEPPING &&
        debugger->runmode() != Runmode::STEPOVER)
    {
        isBreakpoint = debugger->breakpoints().CheckBreakpoint(dbginfo.cip);
        if (!isBreakpoint)
            return; // Continue execution
    }

    // Lookup current location
    uint32_t line = 0;
    debuginfo->LookupLine(dbginfo.cip, &line);
    debugger->SetCurrentLine(line);

    // Enable console input and disable watchdog
    unsigned int old_flags = EnableTerminalEcho();
    unsigned int oldtimeout = DisableEngineWatchdog();

    // Enter debugger shell
    debugger->HandleInput(dbginfo.cip, dbginfo.frm, isBreakpoint);

    // Restore console and watchdog
    ResetEngineWatchdog(oldtimeout);
    ResetTerminalEcho(old_flags);

    // Update frame tracking for step over/out
    if (debugger->runmode() == Runmode::STEPOVER ||
        debugger->runmode() == Runmode::STEPOUT)
    {
        debugger->SetLastFrame(dbginfo.frm);
    }
}
// Called by SourcePawn VM on debug break instruction
```

--------------------------------

### Print Variables and Array Elements (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Display the value of variables or specific array elements. Supports integers, strings, and array indices. The output format depends on the variable type.

```shell
# Print specific variable
dbg> print client
# Output: client = 1

# Print array element
dbg> print playerName[0]
# Output: playerName[0] = 80 ('P')

# Print string variable
dbg> print playerName
# Output: playerName = "Player1"
```

--------------------------------

### Position Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Shows the current execution location within the source code, including file, line number, and function.

```APIDOC
## POSITION COMMAND

### Description
Show the current file, line number, and function where execution is paused.

### Syntax
```
dbg> position
```

### Example
```bash
dbg> position

# Expected output:
# STOP at line 120 in myplugin.sp in CheckPlayerStatus    frame: 0
```
```

--------------------------------

### Quit Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Exits the debugger and allows the plugin to resume normal execution.

```APIDOC
## QUIT COMMAND

### Description
Exit the debugger and resume plugin execution without debugging.

### Syntax
```
dbg> quit
dbg> exit
```

### Expected Behavior
*   Debugger deactivates.
*   Plugin continues normal execution.
*   Breakpoints remain set but won't trigger until debugging is restarted.
```

--------------------------------

### Print Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Prints the value of a variable or a specific array element. Supports various data types and formats.

```APIDOC
## PRINT COMMAND

### Description
Prints the value of a variable or an array element.

### Syntax
```
dbg> print <variable_name>
dbg> print <array_name>[<index>]
```

### Examples
```
dbg> print client
# Output: client = 1

dbg> print playerName[0]
# Output: playerName[0] = 80 ('P')

dbg> print playerName
# Output: playerName = "Player1"
```
```

--------------------------------

### Show Current Position (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Indicate the exact file, line number, and function where the debugger is currently paused. This provides context for the debugging session.

```shell
dbg> position

# Expected output:
# STOP at line 120 in myplugin.sp in CheckPlayerStatus    frame: 0
```

--------------------------------

### Exit Debugger (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Terminate the debugging session and allow the plugin to continue execution. Breakpoints remain set but will not trigger until debugging is restarted. The 'exit' command is a shorthand.

```shell
dbg> quit
# or use shorthand
dbg> exit

# Expected behavior:
# Debugger deactivates
# Plugin continues normal execution
# Breakpoints remain set but won't trigger until debugging restarted
```

--------------------------------

### Breakpoint Management Commands

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Commands for adding and removing breakpoints in the debugger shell.

```APIDOC
## BREAKPOINT MANAGEMENT IN SHELL

### Description
Add or remove breakpoints from within the debugger shell.

### Commands
*   `tbreak <line_number>`: Add a temporary breakpoint (removed after first hit).
*   `break <function_name>`: Add a permanent breakpoint at the specified function.
*   `cbreak <breakpoint_number>`: Remove a breakpoint by its number.

### Examples
```bash
# Add temporary breakpoint
dbg> tbreak 150

# Expected output:
# Breakpoint set at line 150 (temporary)

# Add permanent breakpoint
dbg> break OnPlayerDeath

# Expected output:
# Breakpoint set at OnPlayerDeath

# Remove breakpoint by number
dbg> cbreak 0

# Expected output:
# Breakpoint removed
```
```

--------------------------------

### Breakpoint Management (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Add temporary or permanent breakpoints at specific lines or function names. Remove breakpoints using their assigned numbers. This allows precise control over where execution pauses.

```shell
# Add temporary breakpoint (removed after first hit)
dbg> tbreak 150

# Expected output:
# Breakpoint set at line 150 (temporary)

# Add permanent breakpoint
dbg> break OnPlayerDeath

# Expected output:
# Breakpoint set at OnPlayerDeath

# Remove breakpoint by number
dbg> cbreak 0

# Expected output:
# Breakpoint removed
```

--------------------------------

### Watch Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Adds a watchpoint to automatically display a variable's value whenever the debugger stops.

```APIDOC
## WATCH COMMAND

### Description
Adds a watchpoint to automatically display a variable's value each time the debugger stops.

### Syntax
```
dbg> watch <variable_name>
```

### Example
```bash
# Watch a variable
dbg> watch health

# Expected behavior:
# Every time debugger stops (breakpoint, step, etc.), displays:
# Watches:
# health = 100

# Step through code
dbg> step
# Output shows:
# STOP at line 121 in myplugin.sp
# Watches:
# health = 95
```
```

--------------------------------

### Add Breakpoint to Plugin (C++)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

This function adds a breakpoint to a specific line or function within a plugin's debug information. It finds the requested file, looks up the address corresponding to the line number, and creates a new Breakpoint object. It handles cases where the file or line is not found, or if a breakpoint already exists at the specified address.

```cpp
Breakpoint* BreakpointManager::AddBreakpoint(const std::string& file,
                                             cell_t line, bool temporary)
{
    IPluginDebugInfo *debuginfo = debugger_->GetDebugInfo();

    // Find the file in debug info
    const char *filename = debugger_->FindFileByPartialName(file);
    if (!filename) {
        std::cout << "Unknown file \"" << file << "\"\n";
        return nullptr;
    }

    // Lookup address for file:line
    ucell_t addr;
    if (debuginfo->LookupLineAddress(line, filename, &addr) != SP_ERROR_NONE) {
        std::cout << "No code at line " << line << " in " << filename << "\n";
        return nullptr;
    }

    // Create and store breakpoint
    Breakpoint *bp = new Breakpoint(debuginfo, addr, "", temporary);
    BreakpointMap::Insert i = breakpoint_map_.findForAdd(addr);
    if (i.found()) {
        delete bp;
        return i->value; // Breakpoint already exists
    }

    breakpoint_map_.add(i, addr, bp);
    return bp;
}
// Returns pointer to breakpoint or nullptr on failure
```

--------------------------------

### Watch and Clear Watchpoints (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Set a watchpoint to automatically display a variable's value whenever the debugger stops. Remove watchpoints using the 'cwatch' command. This helps monitor variable changes across execution steps.

```shell
# Watch a variable
dbg> watch health

# Expected behavior:
# Every time debugger stops (breakpoint, step, etc.), displays:
# Watches:
# health = 100

# Step through code
dbg> step
# Output shows:
# STOP at line 121 in myplugin.sp
# Watches:
# health = 95

# Clear watch by variable name
dbg> cwatch health

# Expected behavior:
# Variable no longer displayed automatically
# Can still be printed manually with print command
```

--------------------------------

### Find Debug Symbol by Name and Scope (C++)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Locates a variable by its name within a specified scope address using a debug symbol iterator. It parses array indices from the name if present and returns a SymbolWrapper upon successful finding, or nullptr if the symbol is not found. Dependencies include the debugger instance, symbol iterator, and SymbolWrapper class.

```cpp
std::unique_ptr<SymbolWrapper> SymbolManager::FindDebugSymbol(
    const std::string& name, cell_t scopeaddr,
    IDebugSymbolIterator* symbol_iterator)
{
    // Parse array indices from name (e.g., "arr[5][10]")
    std::string varname = name;
    std::vector<uint32_t> indices;
    size_t pos = varname.find('[');
    if (pos != std::string::npos) {
        // Extract indices
        while (pos != std::string::npos) {
            size_t end = varname.find(']', pos);
            std::string idx = varname.substr(pos + 1, end - pos - 1);
            indices.push_back(std::stoi(idx));
            pos = varname.find('[', end);
        }
        varname = varname.substr(0, varname.find('['));
    }

    // Search for symbol in current scope
    const IDebugSymbol *sym;
    while (symbol_iterator->Next(&sym) == SP_ERROR_NONE) {
        if (sym->scope() != kScope_Unknown &&
            sym->scope_start() <= scopeaddr &&
            sym->scope_end() > scopeaddr)
        {
            if (varname == sym->name()) {
                return std::make_unique<SymbolWrapper>(debugger_, sym);
            }
        }
    }

    return nullptr; // Symbol not found
}
// Returns unique_ptr to SymbolWrapper or nullptr if not found
```

--------------------------------

### Set Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Modifies the value of a variable or an array element during a debugging session.

```APIDOC
## SET COMMAND

### Description
Modifies a variable's value during debugging to test different execution paths.

### Syntax
```
dbg> set <variable_name> <value>
dbg> set <array_name>[<index>] <value>
```

### Examples
```bash
# Set integer variable
dbg> set isAdmin 1

# Expected output:
isAdmin = 1

# Set array element
dbg> set playerName[0] 65

# Expected output:
playerName[0] = 65 ('A')
# playerName becomes "Alayer1"

# Continue execution with modified values
dbg> continue
```
```

--------------------------------

### Clear Watch Command

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Removes a previously set watchpoint for a specific variable.

```APIDOC
## CLEAR WATCH COMMAND

### Description
Removes a watchpoint from a variable.

### Syntax
```
dbg> cwatch <variable_name>
```

### Example
```bash
# Clear watch by variable name
dbg> cwatch health

# Expected behavior:
# Variable no longer displayed automatically
# Can still be printed manually with print command
```
```

--------------------------------

### Set Variable Values (Shell)

Source: https://context7.com/peace-maker/sp-console-debugger/llms.txt

Modify the value of a variable or array element during a debugging session. This is useful for testing different scenarios. The debugger indicates the new value and its character representation if applicable.

```shell
# Set integer variable
dbg> set isAdmin 1

# Expected output:
# isAdmin = 1

# Set array element
dbg> set playerName[0] 65

# Expected output:
# playerName[0] = 65 ('A')
# playerName becomes "Alayer1"

# Continue execution with modified values
dbg> continue
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.