<type>how-to</type>
<domain>install</domain>
<id>maya</id>
<title>Using Wing with Unreal Engine</title>
<date>$Date: 2006-05-26 17:43:42 -0400 (Fri, 26 May 2006) $</date>
<product>pro+</product>
<summary>Tips for using Wing with Python code running under Unreal Editor, a 3D world creation tool from Epic Games.</summary>

.. image:: /images/screenshots/wing7-screenshot-dark.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing Pro <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code written for `Unreal Engine <https://www.unrealengine.com/>`__, a 3D
world creation tool from Epic Games.

If you do not already have Wing Pro installed, `download it now
<https://wingware.com/downloads/wingpro>`__.

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 <ref:howtos/quickstart>`__.

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
  
.. note::

  On macOS and possibly some other systems the Python command line included with Unreal
  Engine crashes on startup. In that case, you cannot use it for the ``Command Line``
  setting in Wing. Instead, select ``Use default`` or point Wing to some other Python
  installation. 
  
  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:

.. python::

  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:

.. python::

  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 <ref:howtos/quickstart>`__.

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:

.. python::
  
  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 <https://www.unrealengine.com/>`__

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.
