언리얼 엔진(UE) Python 스크립트 플러그인 을 사용하는 많은 플러그인은 Python 패키지 인덱스 (PyPI)를 통해 제공되는 것과 같은 Python 코드 패키지에 의존합니다. 언리얼 에디터의 Python 환경 및 경로에서는 언리얼 에디터 Python 환경에서 Python 스크립트 및 라이브러리를 사용할 수 있게 만드는 방법에 대해 설명합니다. 이러한 방법 외에도 언리얼 에디터는 플러그인 및 플러그인의 Python 종속성을 패키징하여 임베디드 언리얼 에디터 Python 환경에서 이용할 수 있도록 해주는 두 가지 방법을 지원합니다.
/Content/Python의 특별 서브 디렉터리
활성화된 각 플러그인에 대해 언리얼 에디터는 자동으로 다음과 같은 플러그인 종속성에 대한 경로를 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 설치 종속성
언리얼 에디터에서는 PIP 를 사용하여 실행 시 또는 특별한 언리얼 빌드 툴(Unreal Build Tool, UBT) 모드를 통해 활성화된 플러그인의 모든 Python 종속성을 다운로드하고 설치할 수 있습니다. 이 기능을 사용하려면 설치된 종속성이 필요한 각 .uplugin 디스크립터 파일에 PythonRequirements 를 추가해야 합니다.
PIP로는 바이너리 패키지(wheel)만 설치할 수 있습니다.
PIP 인스톨러 세팅
PIP 인스톨러에 대한 프로젝트별 세팅은 프로젝트 세팅(Project Settings) 의 플러그인(Plugins) - Python 섹션에 있습니다.
| 파라미터 | 설명 |
|---|---|
| 시작 시 PIP 설치 실행(Run Pip Install on Startup) | 에디터 시작 시 PIP 인스톨러가 실행됩니다. |
| 고급 - PIP 엄격한 해시 검사(Advanced - Pip Strict Hash Checking) | 모든 에픽 지원 플러그인에 PIP 엄격한 해시 검사를 사용하여 유효한 패키지만 설치합니다. 신뢰할 수 없는 인덱스 URL 오버라이드를 제공하는 경우(공급망 공격)에 특히 중요한 옵션입니다. 엄격한 해시 검사를 위해서는 모든 패키지의 버전이 고정되어 있고 해시가 나열되어 있어야 합니다. Python 종속성이 있는 자체 플러그인을 생성하는 경우, 개발 중 간소화를 위해 이 옵션을 비활성화하는 것이 좋을 수 있습니다. 이 옵션을 비활성화하면 모든 패키지가 이미 설치되어 있지 않는 한 Python 종속성이 있는 플러그인이 제대로 실행되지 않을 수도 있습니다. |
| 고급 - 오프라인 전용(Advanced - Offline Only) | 오프라인 전용 모드는 PIP 설치 툴을 실행하여 모든 종속성을 사용할 수 있는지 확인하지만 종속성이 아직 설치되지 않은 경우 로그 메시지가 표시되며 실패합니다. |
| 고급 - 인덱스 URL 오버라이드(Advanced - Override Index URL) | 지정된 인덱스 URL만 강제로 사용합니다. 필요한 모든 패키지와 버전이 로컬 devpi 또는 비슷한 패키지 인덱스 캐시 서버에 캐시될 수도 있는 제한적인 방화벽 시나리오에 특히 유용한 옵션입니다. 이 세팅은 플러그인 디스크립터에 지정된 모든 ExtraIndexUrls를 오버라이드하므로(아래의 PIP 설치 플러그인 디스크립터 환경설정 참조) 모든 인덱스의 모든 패키지가 캐시되어야 합니다. |
시작 시 PIP 설치 비활성화하기
Python 종속성이 이미 설치되어 있는 것이 확실하거나, 특정 커맨드릿 또는 에디터 인스턴스에 필요하지 않은 경우, 에디터 시작 시 PIP 설치 실행을 두 가지 방법으로 비활성화할 수 있습니다. 첫 번째는 위에서 언급한 것처럼 시작 시 PIP 설치 실행 세팅의 체크를 해제하여 인스톨러를 비활성화하는 것입니다. 두 번째는 명령줄 플래그 -DisablePipInstall 을 사용하여 PIP 설치를 비활성화하는 것입니다.
언리얼 빌드 툴(UBT)로 PIP 설치 실행하기
플러그인 개발자와 고급 사용자에게는 언리얼 빌드 툴(UBT)을 사용하여 PIP 인스톨러를 테스트하는 것이 유용할 수 있습니다. 명령줄에서 -Mode=PipInstall UBT 플래그를 사용하여 PIP 인스톨러를 실행할 수 있습니다. 다음 예시는 사용자가 UE 루트 디렉터리에서 실행 중이라는 가정하에 EngineTest 프로젝트에 대한 PIP 설치를 보여줍니다.
Command Line
Engine\Build\BatchFiles\RunUBT.bat EngineTestEditor Win64 Development -Project=..\..\EngineTest\EngineTest.uproject -Mode=PipInstall
오프라인 설치
PIP 설치 툴을 사용하려면 인터넷 연결을 통해 Python 패키지 인덱스에서 Python 패키지를 다운로드해야 합니다. 제한적인 방화벽 규칙 등의 이유로 온라인 설치를 할 수 없는 경우, 인터넷이 연결된 다른 컴퓨터에서 모든 필수 종속성을 다운로드한 다음, 다운로드한 패키지를 타깃 머신의 PIP 설치 site-packages 디렉터리에 복사하면 됩니다.
-
인터넷이 연결된 컴퓨터에서 같은 에디터 프로젝트나 PIP 설치 UBT 모드를 실행하고 패키지 종속성 다운로드를 허용합니다.
-
site-packages폴더(패키지 설치 위치 참조)를 zip 파일로 압축합니다. -
타깃 머신에 이 zip 파일을 복사하고 해당 프로젝트
site-packages디렉터리(패키지 설치 위치 참조)에 압축을 풉니다.
패키지 설치 위치
모든 Python 종속성은 다음 위치에 설치됩니다.
-
Windows:
<ProjectDir>/Intermediate/PipInstall/Lib/site-packages -
Linux/MacOS:
<ProjectDir>/Intermediate/PipInstall/lib/python3.11/site-packages
PIP 설치 플러그인 디스크립터 환경설정
플러그인 디스크립터 파일의 PythonRequirements 에는 플랫폼당 하나의 오브젝트에 대한 JSON 배열이 포함되어 있습니다. 각 JSON 오브젝트는 다음을 지정합니다.
-
Platform(All, Linux, Mac 또는 Win64) -
PIP
requirements.txt줄 포맷의Requirements줄 배열
각 오브젝트에는 선택적으로 다른 패키지 인덱스에 대한 추가 URL 목록이 포함된 ExtraIndexUrls 배열이 포함될 수도 있으며, 이때 PyPI는 항상 포함됩니다.
UE는 일반 PIP 요구 사항의 줄 지정자를 대부분 지원하지만, --force index-url 같은 명령 플래그는 무시합니다.
아래는 엔진 PythonFoundationPackages.uplugin 파일에서 주석과 함께 발췌한 구문으로, PythonRequirements 필드를 사용하여 numpy 1.24.4, scipy 1.11.0 및 torch 2.1.0 을 설치하는 방법을 보여줍니다. torch 요구 사항이 각 플랫폼에 대해 설정되어 있어 Windows/Linux 플랫폼에서 CUDA가 활성화된 패키지 버전을 설치할 수 있습니다.
엄격한 해시 검사가 활성화된 경우, 각 요구 사항 줄에는 모든 지원되는 wheel에 대한 해시가 포함되어야 합니다.
PythonFoundationPackages.uplugin
{
"FriendlyName": "Python Foundation Packages",
...
"PythonRequirements":
[
{
// 'All' 아래에 나열된 요구 사항은 모든 플랫폼에 설치됩니다.
"Platform": "All", // "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 기반 torch에는 wheel 검색을 위한 추가 인덱스가 필요합니다.
"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"
]
}
]
}