There’s a little-known feature in Godot that allows you to debug editor-only plugins and @tool scripts. It’s briefly mentioned in the official docs. You can use either the Godot editor or an external IDE to debug these scripts.
This post describes two approaches to debugging these editor-only scripts:
Using the Godot Editor
With this approach, you will open one Godot editor as a host for debugging your editor-only scripts and run a second Godot editor that you will use normally. This is the same as running and debugging your game, except you will be debugging the Godot editor instead.
Step 1: Customize Run Instances
Open your project in the Godot editor. Choose Debug → Customize Run Instances and set the Main Run Args to: -e
Note: The -e run argument is a short form of the --editor run argument.
Step 2: Set the embedded run mode
Since you will be running the Godot editor from the Godot editor, you probably want to turn off the Embed Game on Next Play run setting.
Note: the location of this setting is different depending on your version of Godot.
Step 3: Run Project (F5)
Run the project as you would when running your game. Because of the -e run argument, Godot will launch another editor instance of your project.
Step 4: Deal with “Files have been modified outside Godot”
Because you now have two editor instances both running the same project, you will get these popups from time to time. You will likely want to tap Reload from disk.
Step 5: Debug!
In the host editor, you can now set breakpoints and debug your scripts similar to when you’re running your game.
Step 6: Running your game
If you want to run your game, remove the -e run argument that was set in Step 1. You may want to do this in the second editor instance so you can debug your editor through the host instance and debug your game through the second editor instance at the same time.
Using an External IDE
An alternative approach is to debug your editor scripts using an external IDE, such as Visual Studio Code. The following example describes how to use Visual Studio Code, but the steps should be similar for other IDE that can be used to debug GDScript files.
Step 1: Setup game debugging
Follow any setup and configuration instructions to get your IDE debugging your Godot game and its game scripts. I have had success with the godot-tools Visual Studio Code plugin. Once you have successfully completed this step, you should be able to launch and debug your game directly from Visual Studio Code without even needing to have the Godot editor running.
Step 2: Configure additional_options
In the .vscode/launch.json settings file, set the additional_options to "-e".
Note: The -e run argument is a short form of the --editor run argument.
Step 3: Start Debugging (F5)
Launch the project to start debugging. You can set breakpoints and debug your editor-only scripts just like you would when debugging your game scripts.
Step 4: Running your game
If you want to run your game, remove the -e from additional_options that was set in Step 2 to revert to game debugging.