diff --git a/docs/source/Coding/Debugging.md b/docs/source/Coding/Debugging.md index 7fc291e471..cd168a2ca8 100644 --- a/docs/source/Coding/Debugging.md +++ b/docs/source/Coding/Debugging.md @@ -251,4 +251,10 @@ this directly). | | `` | Repeat the last command (don't type `n` repeatedly, just type it once and then press `` to repeat it). | -If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that topic here](https://pymotw.com/3/pdb/). \ No newline at end of file +If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that topic here](https://pymotw.com/3/pdb/). + +## Debugging with debugpy + +If you use Visual Studio Code and would like to debug Evennia using a graphical debugger, please follow the instructions here: + +[debugpy contrib](https://github.com/evennia/evennia/tree/main/evennia/contrib/utils/debugpy) \ No newline at end of file diff --git a/evennia/contrib/utils/debugpy/README.md b/evennia/contrib/utils/debugpy/README.md new file mode 100644 index 0000000000..5538defa83 --- /dev/null +++ b/evennia/contrib/utils/debugpy/README.md @@ -0,0 +1,114 @@ +# debugpy + +Contribution by electroglyph, 2025 + +This registers an in-game command `debugpy` which starts the debugpy debugger and listens on port 5678. +For now this is only available for Visual Studio Code (VS Code). + +If you are a JetBrains PyCharm user and would like to use this, make some noise at: +https://youtrack.jetbrains.com/issue/PY-63403/Support-debugpy + + +Credit for this goes to Moony on the Evennia Discord getting-help channel, thx Moony! + + +## Installation + +This requires VS Code and debugpy, so make sure you're using VS Code. + +From the venv where you installed Evennia run: + +`pip install debugpy` + +### Enable the command in Evennia + +In your Evennia mygame folder, open up `/commands/default_cmdsets.py` + +add `from evennia.contrib.utils.debugpy.cmd import CmdDebugPy` somewhere near the top. + +in CharacterCmdSet.at_cmdset_creation add this under `super().at_cmdset_creation()`: + +`self.add(CmdDebugPy)` + +### Add "remote attach" option to VS Code debugger + +Start VS Code and open your launch.json like this: + +![screenshot](./vscode.png) + +Add this to your configuration: + +```json + { + "name": "Python Debugger: Remote Attach", + "justMyCode": false, + "type": "debugpy", + "request": "attach", + "connect": { + "host": "127.0.0.1", + "port": 5678 + }, + "pathMappings": [ + { + "localRoot": "${workspaceFolder}", + "remoteRoot": "${workspaceFolder}" + } + ] + }, +``` + +Use `127.0.0.1` for the host if you are running Evennia from the same machine you'll be debugging from. Otherwise, if you want to debug a remote server, change host (and possibly remoteRoot mapping) as necessary. + +Afterwards it should look something like this: + +```json +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "Python Debugger: Current File", + "type": "debugpy", + "request": "launch", + "program": "${file}", + "console": "integratedTerminal", + }, + { + "name": "Python Debugger: Remote Attach", + "justMyCode": false, + "type": "debugpy", + "request": "attach", + "connect": { + "host": "127.0.0.1", + "port": 5678 + }, + "pathMappings": [ + { + "localRoot": "${workspaceFolder}", + "remoteRoot": "${workspaceFolder}" + } + ] + }, + ] +} +``` + +(notice the comma between the curly braces) + +## Usage + +Set a breakpoint in VS Code where you want the debugger to stop at. + +In Evennia run `debugpy` command. + +You should see "Waiting for debugger attach..." + +Back in VS Code attach the debugger: + +![screenshot](./attach.png) + +Back in Evennia you should see "Debugger attached." + +Now trigger the breakpoint you set and you'll be using a nice graphical debugger. \ No newline at end of file diff --git a/evennia/contrib/utils/debugpy/__init__.py b/evennia/contrib/utils/debugpy/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/evennia/contrib/utils/debugpy/attach.png b/evennia/contrib/utils/debugpy/attach.png new file mode 100644 index 0000000000..27b992890a Binary files /dev/null and b/evennia/contrib/utils/debugpy/attach.png differ diff --git a/evennia/contrib/utils/debugpy/cmd.py b/evennia/contrib/utils/debugpy/cmd.py new file mode 100644 index 0000000000..58f127013e --- /dev/null +++ b/evennia/contrib/utils/debugpy/cmd.py @@ -0,0 +1,34 @@ +import sys +from django.conf import settings +from evennia.utils import utils + +COMMAND_DEFAULT_CLASS = utils.class_from_module(settings.COMMAND_DEFAULT_CLASS) + +ERROR_MSG = """Error, debugpy not found! Please install debugpy by running: `pip install debugpy` +After that please reboot Evennia with `evennia reboot`""" + +try: + import debugpy +except ImportError: + print(ERROR_MSG) + sys.exit() + + +class CmdDebugPy(COMMAND_DEFAULT_CLASS): + """ + Launch debugpy debugger and wait for attach on port 5678 + + Usage: + debugpy + """ + + key = "debugpy" + locks = "cmd:perm(debugpy) or perm(Builder)" + + def func(self): + caller = self.caller + caller.msg("Waiting for debugger attach...") + yield 0.1 # make sure msg is sent first + debugpy.listen(5678) + debugpy.wait_for_client() + caller.msg("Debugger attached.") diff --git a/evennia/contrib/utils/debugpy/vscode.png b/evennia/contrib/utils/debugpy/vscode.png new file mode 100644 index 0000000000..cf193e6ad2 Binary files /dev/null and b/evennia/contrib/utils/debugpy/vscode.png differ