UE5 Pythonデバッグ環境の構築手順（VSCode）

目的

既にいくつか記事はありますが、ちょっとだけすっきりした手順で行えたので共有します。

上記の記事は素晴らしく、大変参考になったのですが、エンジン内のコード(debugpy_unreal.py)を直接変更したり、直接debugpyを使用したり等もう少し改善出来るんじゃないかと思いました。

環境

UE5.3
Windows 11

準備

VSCodeやVSCodeのPython拡張はインストール済みの想定です。

プラグイン

エディタを起動し、Python Editor Script Pluginを有効化します。
※デフォルトでオンになっていると思います。

Config/DefaultEngine.ini

プロジェクト内のConfig/DefaultEngine.iniに以下を追記します。
プラグインの場合でもプラグインフォルダ内のConfig/DefaultEngine.iniに追記すれば大丈夫だと思います。

DefaultEnginge.ini

[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
+StartupScripts=EditorStartup.py
bIsolateInterpreterEnvironment=False
bDeveloperMode=True
bRemoteExecution=False
RemoteExecutionMulticastGroupEndpoint=239.0.0.1:6766
RemoteExecutionMulticastBindAddress=127.0.0.1
RemoteExecutionSendBufferSizeBytes=2097152
RemoteExecutionReceiveBufferSizeBytes=2097152
RemoteExecutionMulticastTtl=0

.vscode/launch.json

DebugGame Editorだとデフォルトのポート番号5678のままではPythonのデバッグ実行が出来ないそうなので、ポート番号を5679に変更しました。

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Unreal Python",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "127.0.0.1",
                "port": 5679
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "${workspaceFolder}"
                }
            ],
        }
    ]
}

Content/Python/EditorStartup.py

上記DefaultEnginge.iniに+StartupScripts=EditorStartup.pyとありますが、これによりエディタ起動時にContent/Python/EditorStartup.pyが自動で実行されるようになります。

debugpy_unreal.pyはUE5.3では以下のパスにあります。
/Engine/Plugins/Experimental/PythonScriptPlugin/Content/Python/debugpy_unreal.py
このスクリプトはdebugpyをインストールしたりする関数が定義されている為これを一部利用します。
UE Pythonではこのファイルを直接参照出来るので、sys.path.appendとかやる必要はありません。（Pythonのバージョンを変更したりしている場合は別ですが）

EditorStartup.py

import debugpy_unreal
import unreal

# デバッグ用ポート番号
DEBUGPY_PORT = 5679


def is_debugpy_installed():
    """debugpyがインストール済みかを確認する"""
    try:
        import debugpy
        unreal.log("debugpy is already installed")
        return True
    except ImportError:
        unreal.log("debugpy is not installed")
        return False


def setup_debug_environment():
    """デバッグ環境のセットアップを実行"""
    try:
        # debugpyのインストール状態確認とインストール
        if not is_debugpy_installed():
            unreal.log("Installing debugpy...")
            debugpy_unreal.install_debugpy()
            unreal.log("debugpy installation completed")

        # デバッグセッション開始（待機なし）
        import debugpy

        # 既にリスニング中かチェック
        if getattr(debugpy, '_listening', False):
            unreal.log(f"debugpy is already listening on port {DEBUGPY_PORT}")
            return

        # リスニング開始
        debugpy.configure(python=unreal.get_interpreter_executable_path())
        debugpy.listen(DEBUGPY_PORT)
        debugpy._listening = True

        unreal.log(f"debugpy started listening on port {DEBUGPY_PORT}")
        unreal.log("Ready for debugger attachment. Use debugpy_unreal.breakpoint() to break into debugger.")
    except Exception as e:
        unreal.log_error(f"Failed to setup debug environment: {e}")


def main():
    """エディタ起動時のデバッグ環境セットアップを実行"""
    unreal.log("Setting up debug environment...")
    setup_debug_environment()


if __name__ == "__main__":
    main()

このファイルの機能としては以下の通りです。

• エディタ実行時にdebugpyがインストールされていない場合はインストール
• UEエディタがVSCodeからのアタッチ(接続)待ちの状態にしつつフリーズしない状態
  debugpy_unreal.pyのstart関数のdebugpy.wait_for_client()がフリーズ状態になる原因の為、ここだけdebugpyを直接実行するようにしました
  debugpy_unreal.py

  def start(port=5678):
      '''Start a debugging session on the given port and wait for a debugger to attach'''
      try:
          import debugpy
      except ImportError:
          print('Failed to import debugpy! Use debugpy_unreal.install_debugpy() to attempt installation.')
  
      # Need to set this otherwise debugpy tries to run another UE instance as an adapter
      # This has it run the Python interpreter executable instead
      debugpy.configure(python=_PYTHON_INTERPRETER_PATH)
  
      debugpy.listen(port)
      print('Waiting for a debugger to attach...')
      debugpy.wait_for_client() # ★ フリーズの原因
      print('Debugger attached! Use debugpy_unreal.breakpoint() to break into the debugger.')
  

デバッグ実行

ここまでやれば実行できるはずですので、最後にテスト実行の手順を記載します。

Content/Python/init_unreal.py

デバッグ実行が出来ているか確認のためテスト用のファイルを用意します。
このファイル自体はデフォルトで実行されるファイルの為、追加の設定は不要です。

init_unreal.py

import unreal

def hoge():
    unreal.log("hoge")

実行

1. エディタを起動する。（既に起動中の場合は一旦閉じてください。）
   EditorStartup.pyを作成して初めての実行の場合にはコマンドプロンプトが立ち上がると思いますが、debugpyをインストールしています
   何らかエラーが起きる場合はネットワーク設定（プロキシ等）を確認してください
2. 上記init_unreal.pyのunreal.log("hoge")にブレークポイントを貼る
3. VSCodeでデバッグ設定Attach to Unreal Pythonを選択した状態でF5を押下
   
4. UEエディタ上のOutput LogでPythonを選択
   
5. 下記コマンドを順に実行する

   > import init_unreal
   > init_unreal.hoge()
   

6. 以下のようにブレークポイントで止まれば設定完了です
   
   出力は以下