Unreal Engine (UE) Python Script Plugin を使用するプラグインの多くは、Python Package Index (PyPI) で入手可能なものなどの Python コードパッケージに依存しています。Unreal Editor における Python 環境とパス では、Python スクリプトの作成方法と Unreal Editor Python 環境で利用可能なライブラリについて説明しています。それらのメソッドに加えて、組み込まれた Unreal Editor Python 環境からアクセスできるようにするため、Unreal Editor はプラグインのパッケージ化とその Python 依存関係のための他の 2 つのメソッドをサポートしています。
/Content/Python の特別なサブディレクトリ
Unreal Editor は、有効なプラグインごとに自動的に Python sys.path リストへプラグイン依存関係のための以下のパスを追加します。各パスが存在する場合のみ追加されます。
-
<PluginDir>/Content/Python/Lib/site-packages -
<PluginDir>/Content/Python/<CurrentPlatform>/Lib/site-packages
純粋な Python ライブラリをプラグインでパッケージするには、ライブラリを <PluginDir>/Content/Python/Lib/site-packages にコピーまたはインストールします。
ライブラリにコンパイルされたバイナリも含まれる場合 (たとえば、Python バインディングのある C/C++ ライブラリ)、サポートされている各プラットフォーム (Linux、Mac、および/または Win64) について <Plugin>/Content/Python/<CurrentPlatform>/Lib/site-packages にライブラリをコピーまたはインストールする必要があります。
プラグイン Pip インストール依存関係
Unreal Editor は、pip を使用して、または特別な Unreal Build Tool (UBT) を使用して、起動時の有効なプラグインのすべての Python 依存関係のダウンロードとインストールをサポートします。この機能を使用するには、インストールされた依存関係が必要な各「.uplugin」記述子ファイルに PythonRequirements を追加する必要があります。
バイナリ パッケージ (ホイール) は pip でしかインストールできません。
Pip インストーラ設定
Pip インストーラのプロジェクト固有の設定は、[Plugins - Python (プライグイン - Python)] セクションの [Project Settings (プロジェクト設定)] にあります。
| パラメータ | 説明 |
|---|---|
| Run Pip Install on Startup (スタートアップ時に Pip インストールを実行) | エディタ起動時に pip インストーラを有効にします。 |
| Advanced - Pip Strict Hash Checking (詳細設定 - Pip の厳格なハッシュ確認) | 有効なパッケージのみがインストールされていることを確認してください。Epic で有効なすべてのプラグインは pip の厳格なハッシュ確認を使用します。これは、信頼できないオーバーライド インデックス URL を提供する場合、特に重要です (サプライチェーン攻撃)。厳格なハッシュ確認では、すべてのパッケージのバージョンがピン止めされ、ハッシュがリストアップされている必要があります。Python 依存関係のある独自のプラグインを作成する場合、シンプルにするため、開発中はこのオプションを無効にしてもよいでしょう。 このオプションが無効な場合、すべてのパッケージがインストールされていなければ、Python 依存関係のあるプラグインは正常に実行されない可能性があります。 |
| 詳細設定 - オフライン限定 | オフライン限定モードは、pip インストール ツールを実行して依存関係がすべて利用可能であることを確認しますが、依存関係がまだインストールされていない場合、ログ メッセージを表示し、失敗します。 |
| 詳細設定 - インデックス URL をオーバーライド | 指定されたインデックス URL のみの強制使用。これは、必要なすべてのパッケージとバージョンがローカル devpi または同様のパッケージ インデックス キャッシュ サーバーにキャッシュされる可能性がある制限的なファイアウォールのシナリオに特に有用です。 この設定は、プラグイン記述子で指定されたすべての ExtraIndexUrl もオーバーライドするため (下記の Pip インストール プラグイン記述子構成を参照してください)、すべてのインデックスからのすべてのパッケージをキャッシュする必要があります。 |
スタートアップ時に Pip インストールを無効にする
Python 依存関係がすでにインストールされていることが保証されている場合、または特定の Commandlet またはエディタ インスタンスでは必要ない場合、2 つの方法でエディタのスタートアップ時の pip インストールの実行を無効にできます。まず、上記で説明したように、Run Pip Install on Startup の設定のチェックを外し、インストーラを無効にできます。また、pip インストールはコマンドライン フラグ -DisablePipInstall でも無効にできます。
Unreal Build Tool (UBT) で pip インストールを実行する
プラグイン デベロッパーや上級ユーザーには、Unreal Build Tool (UBT) を使用して pip インストーラをテストすることも役に立ちます。-Mode=PipInstall UBT フラグは、コマンド ラインから pip インストーラを実行します。以下の例は、ユーザーが UE ルート ディレクトリから実行していると仮定した、EngineTest プロジェクトへの pip インストールを示しています。
コマンド ライン
Engine\Build\BatchFiles\RunUBT.bat EngineTestEditor Win64 Development -Project=..\..\EngineTest\EngineTest.uproject -Mode=PipInstall
オフライン インストール
Pip インストール ツールには、Python パッケージ インデックスから Python パッケージをダウンロードするためのインターネット アクセスが必要です。制限のあるファイアウォール規則などのため、オンライン インストールが不可能な場合、インターネット接続のある別のコンピュータで必要な依存関係すべてをダウンロードしたあと、ダウンロードしたパッケージを対象のマシンの pip インストール site-package にコピーできます。
-
インターネット アクセスのあるマシンで同じエディタ プロジェクトまたは pip インストール UBT モードを実行し、パッケージ依存関係のダウンロードを許可します。
-
「
site-packages」フォルダを圧縮します (「パッケージのインストール先」を参照してください)。 -
この zip ファイルを対象のマシンにコピーし、適切なプロジェクト
site-packagesディレクトリに展開します (「パッケージのインストール先」を参照してください)。
パッケージのインストール先
すべての Python 依存関係は以下の場所にインストールされます。
-
Windows：
<ProjectDir>/Intermediate/PipInstall/Lib/site-packages -
Linux/MacOS：
<ProjectDir>/Intermediate/PipInstall/lib/python3.11/site-packages
Pip インストール プラグイン記述子構成
プラグイン記述子ファイルの PythonRequirements には、オブジェクトの JSON 配列が含まれます。プラットフォームごとに 1 つのオブジェクトです。各 JSON オブジェクトは次のことを指定します。
-
Platform(すべて、Linux、Mac または Win64)。 -
pip
requirements.txt行形式のRequirements行の配列。
各オブジェクトはオプションで他のパッケージ インデックスの追加の URL のリストを含む ExtraIndexUrls 配列も含みます (PyPI は常に含まれます)。
UE は最も一般的な pip 要件の行指定子をサポートしていますが、コマンド フラグを無視します (たとえば、インデックス URL を強制)。
以下は、numpy 1.24.4、scipy 1.11.0、および torch 2.1.0 のインストールのための [PythonRequirements] フィールドの使用を示すエンジン「PythonFoundationPackages.uplugin」ファイルからの注釈付き抜粋です。Windows/Linux プラットフォームが CUDA 対応のパッケージ バージョンをインストールできるように、torch 要件は、各プラットフォームに設定されます。
厳格なハッシュ確認が有効な場合、各要件行はサポートされたすべてのホイールのハッシュを含む必要があります。
PythonFoundationPackages.uplugin
{
"FriendlyName": "Python Foundation Packages",
...
"PythonRequirements":
[
{
// 「すべて」に記載されている要件はすべてのプラットフォームにインストールされます。
"Platform": "All", // 「すべて」、「Linux」、「Mac」、または「Win64」
"Requirements":
[
"numpy==1.24.4 --hash=sha256:9667575fb6d13c95f1b36aca12c5ee3356bf001b714fc354eb5465ce1609e62f --hash=sha256:7ffe43c74893dbf38c2b0a1f5428760a1a9c98285553c89e12d70a96a7f3a4d6 --hash=sha256:7215847ce88a85ce39baf9e89070cb860c98fdddacbaa6c0da3ffb31b3350bd5 --hash=sha256:ed094d4f0c177b1b8e7aa9cba7d6ceed51c0e569a5318ac0ca9a090680a6a1b1 --hash=sha256:befe2bf740fd8373cf56149a5c23a0f601e82869598d41f8e188a0e9869926f8 --hash=sha256:b4bea75e47d9586d31e892a7401f76e909712a0fd510f58f5337bea9572c571e --hash=sha256:f136bab9c2cfd8da131132c2cf6cc27331dd6fae65f95f69dcd4ae3c3639c810 --hash=sha256:c0bfb52d2169d58c1cdb8cc1f16989101639b34c7d3ce60ed70b19c63eba0b64 --hash=sha256:d11efb4dbecbdf22508d55e48d9c8384db795e1b7b51ea735289ff96613ff74d --hash=sha256:2541312fbf09977f3b3ad449c4e5f4bb55d0dbf79226d7724211acc905049400 --hash=sha256:e2926dac25b313635e4d6cf4dc4e51c8c0ebfed60b801c799ffc4c32bf3d1254 --hash=sha256:b7b1fc9864d7d39e28f41d089bfd6353cb5f27ecd9905348c24187a768c79694",
"scipy==1.11.0 --hash=sha256:ee410e6de8f88fd5cf6eadd73c135020bfbbbdfcd0f6162c36a7638a1ea8cc65 --hash=sha256:6550466fbeec7453d7465e74d4f4b19f905642c89a7525571ee91dd7adabb5a3 --hash=sha256:028eccd22e654b3ea01ee63705681ee79933652b2d8f873e7949898dda6d11b6 --hash=sha256:f3cd9e7b3c2c1ec26364856f9fbe78695fe631150f94cd1c22228456404cf1ec --hash=sha256:36750b7733d960d7994888f0d148d31ea3017ac15eef664194b4ef68d36a4a97 --hash=sha256:2c6ff6ef9cc27f9b3db93a6f8b38f97387e6e0591600369a297a50a8e96e835d --hash=sha256:933baf588daa8dc9a92c20a0be32f56d43faf3d1a60ab11b3f08c356430f6e56 --hash=sha256:acf8ed278cc03f5aff035e69cb511741e0418681d25fbbb86ca65429c4f4d9cd --hash=sha256:530f9ad26440e85766509dbf78edcfe13ffd0ab7fec2560ee5c36ff74d6269ff --hash=sha256:f313b39a7e94f296025e3cffc2c567618174c0b1dde173960cf23808f9fae4be --hash=sha256:cf00bd2b1b0211888d4dc75656c0412213a8b25e80d73898083f402b50f47e41 --hash=sha256:91af76a68eeae0064887a48e25c4e616fa519fa0d38602eda7e0f97d65d57937 --hash=sha256:ad669df80528aeca5f557712102538f4f37e503f0c5b9541655016dd0932ca79 --hash=sha256:1b7c3dca977f30a739e0409fb001056484661cb2541a01aba0bb0029f7b68db8 --hash=sha256:6e619aba2df228a9b34718efb023966da781e89dd3d21637b27f2e54db0410d7 --hash=sha256:bc9a714581f561af0848e6b69947fda0614915f072dfd14142ed1bfe1b806710"
]
},
{
"Platform": "Linux",
// CUDA ベースのトーチはホイールを検索するため追加のインデックスが必要です。
"ExtraIndexUrls":
["https://download.pytorch.org/whl/"],
"Requirements":
[
"torch==2.1.0+cu118 --hash=sha256:bcb17e2de6ca634d326203694d0bfb552587335e536c1917be3f28c5664b5506 --hash=sha256:8ecf52ba49cfd3b7303d4e57e7b5c2106b77dbc9bdeaf880870162138bc70e18 --hash=sha256:a81b554184492005543ddc32e96469f9369d778dedd195d73bda9bed407d6589"
]
},
{
"Platform": "Mac",
"ExtraIndexUrls":
["https://download.pytorch.org/whl/"],
"Requirements":
[
"torch==2.1.0 --hash=sha256:3cd1dedff13884d890f18eea620184fb4cd8fd3c68ce3300498f427ae93aa962 --hash=sha256:601b0a2a9d9233fb4b81f7d47dca9680d4f3a78ca3f781078b6ad1ced8a90523 --hash=sha256:05661c32ec14bc3a157193d0f19a7b19d8e61eb787b33353cad30202c295e83b --hash=sha256:101c139152959cb20ab370fc192672c50093747906ee4ceace44d8dd703f29af --hash=sha256:421739685eba5e0beba42cb649740b15d44b0d565c04e6ed667b41148734a75b --hash=sha256:a6b7438a90a870e4cdeb15301519ae6c043c883fcd224d303c5b118082814767 --hash=sha256:c8bf7eaf9514465e5d9101e05195183470a6215bb50295c61b52302a04edb690 --hash=sha256:6ad491e70dbe4288d17fdbfc7fbfa766d66cbe219bc4871c7a8096f4a37c98df"
]
}
]
}
Pip の厳格なハッシュ確認
厳格なハッシュ確認 によって、ダウンロードしたパッケージが必要なコンテンツと完全に一致します。新規プロジェクトとプラグインではデフォルトで有効です。厳格なハッシュ確認には、Requirements の .uplugin file にすべてのパッケージの正確なバージョンとハッシュ情報を記載する必要があります。Requirements ブロックにハッシュが記載された「.uplugin」ファイルの例は前のセクションを参照してください。
厳格なハッシュ確認を無効にする方法
Python 依存関係のある独自のプラグインを作成する場合、シンプルにするため、開発中は厳格なハッシュ確認を無効にしてもよいでしょう。厳格なハッシュ確認を無効にするには、次の手順を実行します。
- [Project Settings (プロジェクト設定)] > [Plugins (プラグイン)] > [Python] を開きます。
- [Python Pip Install (Python Pip インストール)] の [Advanced Settings (詳細設定...)] を展開します。
- Pip Strict Hash Check のチェックを外します
