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..3402e76bc6 --- /dev/null +++ b/evennia/contrib/utils/debugpy/README.md @@ -0,0 +1,122 @@ +# In-game debugpy command + +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! +0xDEADFED5 simply tied a pretty bow around it and stuck it here for everybody else. + + + +## Dependencies + +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)` + +For a newly initialized game, the result would look like this at the top of the file: + +```python +""" +Command sets + +All commands in the game must be grouped in a cmdset. A given command +can be part of any number of cmdsets and cmdsets can be added/removed +and merged onto entities at runtime. + +To create new commands to populate the cmdset, see +`commands/command.py`. + +This module wraps the default command sets of Evennia; overloads them +to add/remove commands from the default lineup. You can create your +own cmdsets by inheriting from them or directly from `evennia.CmdSet`. + +""" + +from evennia import default_cmds +from evennia.contrib.utils.debugpy.cmd import CmdDebugPy + +class CharacterCmdSet(default_cmds.CharacterCmdSet): + """ + The `CharacterCmdSet` contains general in-game commands like `look`, + `get`, etc available on in-game Character objects. It is merged with + the `AccountCmdSet` when an Account puppets a Character. + """ + + key = "DefaultCharacter" + + def at_cmdset_creation(self): + """ + Populates the cmdset + """ + super().at_cmdset_creation() + # + # any commands you add below will overload the default ones. + # + 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: + +``` + { + "name": "Python Debugger: Remote Attach", + "justMyCode": false, + "type": "debugpy", + "request": "attach", + "connect": { + "host": "localhost", + "port": 5678 + }, + "pathMappings": [ + { + "localRoot": "${workspaceFolder}", + "remoteRoot": "${workspaceFolder}" + } + ] + }, +``` + +Use `localhost` 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 as necessary. + +Afterwards it should look something like this: + +![screenshot](./launch.png) + +(notice the comma between the curly braces) + +## Use it + +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..5ef70c0e70 --- /dev/null +++ b/evennia/contrib/utils/debugpy/cmd.py @@ -0,0 +1,31 @@ +import sys +from django.conf import settings +from evennia.utils import utils + +COMMAND_DEFAULT_CLASS = utils.class_from_module(settings.COMMAND_DEFAULT_CLASS) + +try: + import debugpy +except ImportError: + print("Error, debugpy not found! Please install debugpy by running: pip install debugpy") + 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(("localhost", 5678)) + debugpy.wait_for_client() + caller.msg("Debugger attached.") diff --git a/evennia/contrib/utils/debugpy/launch.png b/evennia/contrib/utils/debugpy/launch.png new file mode 100644 index 0000000000..04612b4102 Binary files /dev/null and b/evennia/contrib/utils/debugpy/launch.png differ 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