Using Wing with Unreal Engine
Wing Pro is a Python IDE that can be used to develop, test, and debug Python code written for Unreal Engine, a 3D world creation tool from Epic Games.
If you do not already have Wing Pro installed, download it now.
This document describes how to configure Wing for Unreal. To learn more about using Wing as your Python IDE, please refer to the tutorial in Wing's Help menu or read the Quickstart Guide.
Creating a Project
To get started developing and debugging Python code written for Unreal Engine, you first need to create your Unreal project from Unreal Editor. This creates a directory that contains various starter files and directories and also your *.uproject file.
Once this is done, select New Project from Wing Pro's Project menu, choose Local Host and Use Existing Directory and then enter the full path of the directory that contains your *.uproject file.
Next select Unreal Engine under Project Type and press the Next button.
On the second New Project screen, select Use Existing Python and Command Line. Then enter the full path to the python.exe or python inside your Unreal Engine installation. For example:
c:\Program Files\Epic Games\UE_4.27\Engine\Binaries\ThirdParty\Python3\Win64\python.exe
This does mean that on systems where the Unreal Engine Python command line is broken, you will need to install Python separately if you don't already have it. Ideally this would match the version of Python that Unreal Engine uses (as of early 2022 this was Python 3.7) so that auto-completion on builtins and the standard library are accurate.
Now you can complete creation of your Wing project by pressing the Create Project button.
Wing will show the result of this operation, including all steps taken. It may warn about needing to restart Unreal Editor and/or turning on Developer Mode in Unreal Editor, which is done from Preferences > Plugins > Python. Developer Mode is needed to generate the stubs file that Wing uses to provide auto-completion for Unreal Engine's API. Even if that is already enabled, you may need to restart Unreal Editor before debugging works, since it does not rescan the disk for new Python Path directories created while it is running.
That's all there is to it!
Working with Wing
You can now type import unreal and should receive auto-completion and other support after typing unreal. in the editor.
You can also debug Python code in Unreal Editor. To start the debugger, run the following Python code in Unreal Editor:
import wingdbstub
You should see Wing's toolbar change to indicate that a debug process is connected.
Now you can open your Python script(s) in Wing and place breakpoints by clicking on the leftmost editor margin. Wing will stop on breakpoints and also any unhandled exceptions that are reach in your code.
If you drop the debug connection and want to reestablish it without restarting Unreal Editor, you can do this by executing the following code:
wingdbstub.Ensure()
You may need to import wingdbstub again before doing that, if you are executing this code from a different context than your original import of that module.
Debugging Notes
(1) While stopped at a breakpoint in Wing, Unreal Editor will be unresponsive, because the debugger has taken over control. You will need to continue in the debugger or disconnect Wing's debugger by pressing the red Stop item or using the Debug > Stop Debugging menu item before you can return to using Unreal Editor's UI.
(2) Because Unreal Engine does not normally call into any Python code on a regular basis, Wing's debugger cannot always immediately process requests from the IDE, such as those that add or remove breakpoints or request the debug process to Pause.
As a result, breakpoints set may initially appear as a small dash and only convert into a round circle once the debugger confirms setting the breakpoint. This may not be until you next execute a Python script, but should usually occur before the breakpoint is actually reached. However, sometimes old breakpoints removed in the IDE will not yet be removed inside Unreal Engine, causing Wing to stop there before the breakpoint updates are completed.
This should only occur during times when no Python code is being executed by Unreal Engine. For example, if you have a timer written in Python or other Python script activity occuring on a regular basis, then you should not see this issue.
(3) In rare cases, it may to be possible to get into a state where breakpoints are no longer reached at all. In this case, restarting Unreal Engine solves the problem.
Using Live Runtime Analysis
A way to get even better auto-completion in Wing is to run to a breakpoint in the debugger and then work in the editor or the Debug Console accessed from the Wing's Tools menu. If you're working in the current Python stack frame, Wing inspects the live runtime to populate the auto-completer and other code intelligence tools. This also has the advantage that you can immediately try out the code that you are writing in the Debug Console.
For more information on Wing's capabilities, see the Tutorial in the Help menu or the Quick Start Guide.
How it Works
Wing's auto-completion for Unreal Editor depends on its creation of the unreal.py stubs file, which is located in Intermediate/PythonStub inside your Unreal Editor project directory (where the *.uproject is located). This is created for any project opened by Unreal Editor after you've turned on Developer Mode in Unreal Editor from Preferences > Plugins > Python.
If you follow the above instructions for creating a Wing project for Unreal Editor, Wing will automatically add the Intermediate/PythonStub directory to the Python Path that is configured in Project Properties under the Environment tab. You can also add this manually to an existing Wing project.
Notes on sys.path
Because of how Unreal Engine packages Python, Wing cannot obtain the Python path from the command line executable, as it usually does.
This means that you need to manually add any other directories from which you import code to your Python Path in Wing's Project Properties. Otherwise, Wing will not be able to find and offer auto-completion and other code intelligence for code in those directories.
One way to review all the directories that are on the Python path inside Unreal Editor is to run the following code there:
import sys, os
print(os.pathsep.join(sys.path))
The output of this can be pasted into the Python Path field in Wing's Project Properties after selecting View as Text.
Note that many of the entries Unreal places on sys.path do not exist, and thus are not actually needed. However, you can still add them to the Python Path in Wing's Project Properties. Wing will warn about them but allows them in the configuration and will update its knowledge of your code if those directories are later created and populated.
Debug Configuration Details
When you created your Wing project for Unreal Engine, Wing wrote a pre-configured copy of its wingdbstub.py module into Content/Python inside your Unreal Engine project directory (where the *.uproject is located). The values that Wing sets in this module are WINGHOME, to tell the debugger where to find the debugger implementation, and kEmbedded, to tell Wing that it is debugging code running in an embedded instance of Python. The latter alters how it treats an exit from the outermost stack frame; without it, the debug connection would drop and need to be reestablished with wingdbstub.Ensure() after each invocation of Python code.
Wing also turns on Accept Debug Connections` in the menu for the bug icon in the lower left of Wing's window, so that debugging initiated from outside of Wing can connect to the IDE.
Related Documents
For more information see:
- Unreal Engine website
- Quickstart Guide contains additional basic information about getting started with Wing.
- Tutorial provides a gentler introduction to Wing's features.
- Wing Reference Manual documents Wing in detail.
