Skip to content

Commit fa76054

Browse files
Pollux12Pollux12
committed
docs: update debugger docs
1 parent e3f8ef8 commit fa76054

1 file changed

Lines changed: 186 additions & 48 deletions

File tree

‎docs/mintlify/debugger/setup.mdx‎

Lines changed: 186 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -40,16 +40,153 @@ Download the correct binary for your server from the [GitHub releases page](http
4040

4141
Place the binary in `garrysmod/lua/bin/` on your server.
4242

43-
Create a loader script at `garrysmod/autorun/rdb_loader.lua`:
43+
Place this loader script at `garrysmod/autorun/debug.lua`:
44+
45+
```lua garrysmod/autorun/debug.lua
46+
-- [GLuaLS] Auto-managed by GLuaLS extension. Do not edit.
47+
_GLUALS = _GLUALS or {}
48+
49+
if SERVER then
50+
require("rdb")
51+
rdb.activate(21111)
52+
util.AddNetworkString("gm_rdb_exec")
53+
54+
local function normalizeRealm(realm)
55+
realm = string.lower(tostring(realm or "server"))
56+
if realm ~= "server" and realm ~= "client" and realm ~= "shared" then
57+
realm = "server"
58+
end
59+
return realm
60+
end
61+
62+
local function sendClientExec(kind, payload)
63+
net.Start("gm_rdb_exec")
64+
net.WriteString(kind)
65+
net.WriteString(payload)
66+
net.Broadcast()
67+
end
68+
69+
local function runServerChunk(code, chunkName)
70+
local fn, compileErr = CompileString(code, chunkName or "gluals_run_lua", false)
71+
if not isfunction(fn) then
72+
return false, tostring(compileErr)
73+
end
74+
local ok, runtimeErr = xpcall(fn, debug.traceback)
75+
if not ok then
76+
return false, tostring(runtimeErr)
77+
end
78+
return true
79+
end
80+
81+
local function includeServerFile(filePath)
82+
local ok, includeErr = pcall(include, filePath)
83+
if not ok then
84+
return false, tostring(includeErr)
85+
end
86+
return true
87+
end
88+
89+
local function readServerFileForClient(filePath)
90+
local content = file.Read(filePath, "LUA")
91+
if isstring(content) then
92+
return content
93+
end
94+
95+
content = file.Read("lua/" .. filePath, "GAME")
96+
if isstring(content) then
97+
return content
98+
end
99+
100+
return nil, "unable to read file for client execution: " .. filePath
101+
end
102+
103+
function _GLUALS.runLua(realm, code)
104+
realm = normalizeRealm(realm)
105+
if type(code) ~= "string" then
106+
return false, "lua chunk must be a string"
107+
end
108+
109+
if realm == "server" or realm == "shared" then
110+
local ok, err = runServerChunk(code, "gluals_run_lua")
111+
if not ok then
112+
return false, err
113+
end
114+
end
115+
116+
if realm == "client" or realm == "shared" then
117+
sendClientExec("lua", code)
118+
end
119+
120+
return true
121+
end
122+
123+
function _GLUALS.runFile(realm, filePath)
124+
realm = normalizeRealm(realm)
125+
filePath = tostring(filePath or "")
126+
if filePath == "" then
127+
return false, "file path is required"
128+
end
129+
130+
if realm == "server" or realm == "shared" then
131+
local ok, err = includeServerFile(filePath)
132+
if not ok then
133+
return false, err
134+
end
135+
end
136+
137+
if realm == "client" or realm == "shared" then
138+
local clientCode, readErr = readServerFileForClient(filePath)
139+
if not isstring(clientCode) then
140+
return false, tostring(readErr)
141+
end
142+
sendClientExec("lua", clientCode)
143+
end
144+
145+
return true
146+
end
147+
148+
function _GLUALS.refreshFile(filePath)
149+
filePath = tostring(filePath or "")
150+
if filePath == "" then
151+
return false, "file path is required"
152+
end
153+
154+
if not game or not game.ConsoleCommand then
155+
return false, "game.ConsoleCommand is unavailable"
156+
end
157+
158+
local quotedPath = string.format("%q", filePath)
159+
game.ConsoleCommand("lua_refresh_file " .. quotedPath .. "\n")
160+
return true
161+
end
162+
end
163+
164+
if CLIENT then
165+
net.Receive("gm_rdb_exec", function()
166+
local kind = net.ReadString()
167+
local payload = net.ReadString()
168+
if kind == "lua" then
169+
local func, err = CompileString(payload, "gluals_client_exec", false)
170+
if not isfunction(func) then
171+
ErrorNoHalt("[GLuaLS] Client exec compile error: " .. tostring(err) .. "\n")
172+
return
173+
end
174+
175+
local ok, runtimeErr = xpcall(func, debug.traceback)
176+
if not ok then
177+
ErrorNoHalt("[GLuaLS] Client exec runtime error: " .. tostring(runtimeErr) .. "\n")
178+
end
179+
return
180+
end
181+
182+
ErrorNoHalt("[GLuaLS] Unknown exec kind: " .. tostring(kind) .. "\n")
183+
end)
184+
end
44185

45-
```lua garrysmod/autorun/rdb_loader.lua
46-
if not SERVER then return end
47-
48-
require("rdb")
49186
```
50187

51188
<Note>
52-
The loader script ensures `gm_rdb` only loads on the server realm and starts automatically when the server loads.
189+
This script is copy-pasted from version 1.0.6 and may be outdated if you are using a newer version of the extension. It is always recommended to use the setup wizard for the latest version of the loader script.
53190
</Note>
54191

55192
---
@@ -65,46 +202,49 @@ Use **attach** when the server is already running (most common for development):
65202
<ConfigTip />
66203
```json .vscode/launch.json
67204
{
68-
"version": "0.2.0",
69-
"configurations": [
70-
{
71-
"type": "gluals_gmod",
72-
"request": "attach",
73-
"name": "Attach to SRCDS",
74-
"host": "127.0.0.1",
75-
"port": 21111,
76-
"sourceRoot": "${workspaceFolder}",
77-
"stopOnEntry": true,
78-
"stopOnError": false
79-
}
80-
]
205+
"version": "0.2.0",
206+
"configurations": [
207+
{
208+
"type": "gluals_gmod",
209+
"request": "attach",
210+
"name": "GMod Attach (SRCDS)",
211+
"host": "127.0.0.1",
212+
"port": 21111,
213+
"sourceRoot": "${workspaceFolder}/../..",
214+
"sourceFileMap": {
215+
"${workspaceFolder}/../../addons": "addons",
216+
"${workspaceFolder}/../../lua": "lua",
217+
"${workspaceFolder}/../../gamemodes/base": "gamemodes/base",
218+
"${workspaceFolder}/../../gamemodes/sandbox": "gamemodes/sandbox"
219+
},
220+
"stopOnEntry": false,
221+
"stopOnError": false,
222+
"realm": "server"
223+
}
224+
]
81225
}
82226
```
227+
- "sourceRoot": should point to your garrysmod folder (one level up from scrds)
228+
- "sourceFileMap" should map workspace folders to their corresponding paths, going from the sourceRoot folder.
83229

84-
### Launch a server
230+
You will need to edit the above configuration to match your workspace structure. This is likely to just require a new line within sourceFileMap.
85231

86-
<Warning>The `launch` option is unsupported and may not work on all systems. Use `attach` instead.</Warning>
87-
88-
Use **launch** to start SRCDS directly from VS Code:
232+
Addon example:
233+
```
234+
"${workspaceFolder}": "addons/your-addon-folder"
235+
```
89236

90-
<ConfigTip />
91-
```json .vscode/launch.json
92-
{
93-
"version": "0.2.0",
94-
"configurations": [
95-
{
96-
"type": "gluals_gmod",
97-
"request": "launch",
98-
"name": "Launch SRCDS",
99-
"program": "C:/srcds/srcds.exe",
100-
"args": ["-game garrysmod -console -port 27015"],
101-
"cwd": "C:/srcds",
102-
"port": 21111,
103-
"sourceRoot": "${workspaceFolder}"
104-
}
105-
]
106-
}
237+
Gamemode example:
107238
```
239+
"${workspaceFolder}": "gamemodes/your-addon-folder"
240+
```
241+
242+
The reason for it looking so complicated is due to it trying to be a generic example that will work for everyone - you can also use hardcoded direct paths if you want, but this means others won't be able to use your config without editing it.
243+
244+
245+
### Launch a server
246+
247+
<Warning>The `launch` option is unsupported and may not work on all systems. Use `attach` instead.</Warning>
108248

109249
---
110250

@@ -115,7 +255,7 @@ Use **launch** to start SRCDS directly from VS Code:
115255
3. Select your launch configuration from the dropdown
116256
4. Press **F5** (or click the green play button)
117257

118-
The debug toolbar appears at the top of the screen when connected.
258+
The debug toolbar appears at the top of the screen when connected. You should see the debug console output pop up in the bottom panel.
119259

120260
---
121261

@@ -135,6 +275,8 @@ The debug toolbar appears at the top of the screen when connected.
135275

136276
### Launch configuration (server process)
137277

278+
<Warning>The `launch` option is unsupported and may not work on all systems. Use `attach` instead.</Warning>
279+
138280
Includes the above, plus:
139281

140282
| Property | Type | Description |
@@ -147,14 +289,10 @@ Includes the above, plus:
147289

148290
## Changing the default port
149291

150-
You can configure `gm_rdb` to listen on a different port by adding a `CreateConVar` in your loader:
151-
152-
```lua garrysmod/autorun/rdb_loader.lua
153-
if not SERVER then return end
292+
You can configure `gm_rdb` to listen on a different port by changing the following line within `debug.lua`:
154293

155-
-- Change default port to 21200
156-
CreateConVar("rdb_port", "21200", FCVAR_NONE, "Debug port for gm_rdb")
157-
require("rdb")
294+
```lua garrysmod/autorun/debug.lua
295+
rdb.activate(<PORT_NUMBER>)
158296
```
159297

160298
Make sure to update `"port"` in your `launch.json` to match.

0 commit comments

Comments
 (0)