Merge branch 'debugpy' of github.com:electroglyph/evennia into electroglyph-debugpy

docs/source/Coding/Debugging.md

@@ -251,4 +251,10 @@ this directly). |
 | `<RETURN>` | Repeat the last command (don't type `n` repeatedly, just type it once and then press
 `<RETURN>` 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/).
+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)

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.

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.")