> ## Documentation Index
> Fetch the complete documentation index at: https://gluals.arnux.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup & installation

> Install gm_rdb on your SRCDS server and configure VS Code to connect for debugging.

## Automatic setup

`gm_rdb` is a binary module that runs inside SRCDS and exposes Lua state for debugging.

### Using the setup wizard (recommended)

Use the built-in setup wizard. The walkthrough should appear when you install the extension for the first time. You can also start it yourself:

1. Open the Command Palette (`Ctrl+Shift+P`)
2. Run **GLua: Setup Debugger**
3. Follow the wizard steps. It will download the correct `gm_rdb` binary for your server's OS and architecture, then guide you through placing the files

You can also click **GLuaLS** in the status bar to start the setup wizard.

## Manual installation

<Warning>
  The VS Code extension can set up the debugger for you. Use manual setup only if the extension setup fails.
</Warning>

### Step 1: Download and install gm\_rdb

Download the correct binary for your server from the [GitHub releases page](https://github.com/Pollux12/gmod-glua-ls/releases):

| Platform       | File                   |
| -------------- | ---------------------- |
| Windows 64-bit | `gmsv_rdb_win64.dll`   |
| Windows 32-bit | `gmsv_rdb_win32.dll`   |
| Linux 64-bit   | `gmsv_rdb_linux64.dll` |
| Linux 32-bit   | `gmsv_rdb_linux.dll`   |

Place the binary in `garrysmod/lua/bin/` on your server. Create the `bin` folder if it does not exist. The final path should be `garrysmod/lua/bin/gmsv_rdb_*.dll`.

Create `garrysmod/lua/autorun/debug.lua`:

```lua garrysmod/lua/autorun/debug.lua theme={null}
if SERVER then
    require("rdb")
    rdb.activate(21111)
end
```

This is enough to attach to and debug the server. Use the setup wizard when you also need its current client-execution and file-refresh helpers.

### Runtime launch flags

`gm_rdb` reads these command-line flags when the module loads. You can skip them unless you need the listed behavior.

| Flag                               | Effect                                                                                                             | Default without flag                               |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `-rdb_allow_remote`                | Accept debugger connections from non-loopback addresses                                                            | Only localhost or loopback connections are allowed |
| `-rdb_pause_on_activate [seconds]` | Pause on the next event after `rdb.activate(...)` runs. Optional timeout in seconds; use `0` to wait indefinitely. | `activate` does not pause                          |

Add these CLI flags to your Garry's Mod or SRCDS launch options.

***

## Step 2: Configure VS Code

Create a `launch.json` in your `.vscode/` folder (or use the VS Code **Run & Debug** panel → **Create a launch.json file**):

### Attach to a running server

Use **attach** when the server is already running. Most addon development uses this option.

<Tip>
  Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.
</Tip>

```json .vscode/launch.json theme={null}
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "gluals_gmod",
            "request": "attach",
            "name": "GMod Attach (SRCDS)",
            "host": "127.0.0.1",
            "port": 21111,
            "sourceRoot": "${workspaceFolder}/../..",
            "sourceFileMap": {
                "${workspaceFolder}/../../addons": "addons",
                "${workspaceFolder}/../../lua": "lua",
                "${workspaceFolder}/../../gamemodes/base": "gamemodes/base",
                "${workspaceFolder}/../../gamemodes/sandbox": "gamemodes/sandbox"
            },
            "stopOnEntry": false,
            "stopOnError": false,
            "realm": "server"
        }
    ]
}
```

* "sourceRoot": should point to your garrysmod folder (one level up from scrds)
* "sourceFileMap" should map workspace folders to their corresponding paths, going from the sourceRoot folder.

Edit the configuration above to match your workspace structure. Most setups only need one new line in `sourceFileMap`.

Addon example:

```
"${workspaceFolder}": "addons/your-addon-folder"
```

Gamemode example:

```
"${workspaceFolder}": "gamemodes/your-addon-folder"
```

This example covers common addon and gamemode layouts. You can use hardcoded paths, but other developers will need to edit them before using your config.

### Launch a server

<Warning>The `launch` option is unsupported and may not work on all systems. Use `attach` instead.</Warning>

***

## Step 3: Start debugging

1. Start your SRCDS server
2. In VS Code, open the **Run & Debug** panel (`Ctrl+Shift+D`)
3. Select your launch configuration from the dropdown
4. Press **F5** (or click the green play button)

When VS Code connects, the debug toolbar appears at the top of the screen. The Debug Console opens in the bottom panel.

***

## Configuration reference

### Attach configuration

| Property        | Type      | Description                                                          |
| --------------- | --------- | -------------------------------------------------------------------- |
| `host`          | `string`  | Server hostname or IP. Default: `"127.0.0.1"`                        |
| `port`          | `number`  | Port `gm_rdb` is listening on. Default: `21111`                      |
| `sourceRoot`    | `string`  | Workspace path to map server files to. Default: `${workspaceFolder}` |
| `sourceFileMap` | `object`  | Map server paths to workspace paths manually                         |
| `stopOnEntry`   | `boolean` | Pause at first line when connecting. Default: `true`                 |
| `stopOnError`   | `boolean` | Pause when a Lua error is thrown. Default: `false`                   |
| `realm`         | `string`  | Default realm for code execution (`"server"` or `"client"`)          |

### Launch configuration (server process)

<Warning>The `launch` option is unsupported and may not work on all systems. Use `attach` instead.</Warning>

Includes the above, plus:

| Property  | Type       | Description                              |
| --------- | ---------- | ---------------------------------------- |
| `program` | `string`   | Path to `srcds.exe` or `srcds_run`       |
| `args`    | `string[]` | Additional server command-line arguments |
| `cwd`     | `string`   | Working directory for the server process |

***

## Changing the default port

To make `gm_rdb` listen on a different port, change this line in `debug.lua`:

```lua garrysmod/lua/autorun/debug.lua theme={null}
rdb.activate(<PORT_NUMBER>)
```

Update `"port"` in your `launch.json` to match.

***

## Remote debugging

<Warning>Do not use the debugger on untrusted or public networks. Use remote debugging only if you understand and accept the risk.</Warning>

If debugging a remote server, start SRCDS with `-rdb_allow_remote`, open the `gm_rdb` port (default `21111`) in your server's firewall, and set `host` in your `launch.json` to the server's reachable address.

Without `-rdb_allow_remote`, `gm_rdb` only accepts loopback connections, so remote attach fails.

<Danger>Do not enable this option unless you understand and accept the risk. If you enable this option on the client and expose your local port, any server could activate the debugger through clientside Lua.</Danger>

***

## Pause on activation

<Warning>Do not use the debugger on untrusted or public networks. This option pauses execution once loaded (usually during startup/initial join). If no timeout is provided, execution resumes automatically after 60 seconds if no debugger connects.</Warning>

`rdb.activate(...)` does not pause execution by default. The debugger may miss the server or client startup sequence unless you connect fast.

To pause on the next hook event after `rdb.activate(...)` runs, add `-rdb_pause_on_activate` to the server startup arguments or client Steam launch options. You can provide a timeout in seconds.

```txt theme={null}
-rdb_pause_on_activate
-rdb_pause_on_activate 120
-rdb_pause_on_activate 0
```

* `-rdb_pause_on_activate` pauses on activation and resumes after 60 seconds if no debugger connects.
* `-rdb_pause_on_activate 120` pauses on activation with a 120-second timeout.
* `-rdb_pause_on_activate 0` pauses until a debugger connects.

Use this when you need to capture the server or client startup sequence.

<Danger>If you enable this option on the client, any server could activate the debugger and freeze your game.</Danger>