언리얼 엔진 5 문서가 에픽 디벨로퍼 커뮤니티로 이전되었습니다

리모트 컨트롤 퀵스타트

웹페이지에서 언리얼 에디터 원격 조작을 시작하는 방법을 단계별로 설명합니다.

Choose your operating system:

Windows

macOS

Linux

해당 페이지에서는 리모트 컨트롤 API를 시작하는 단계별 가이드를 제공합니다. 이 튜토리얼을 끝내면 웹 애플리케이션의 요청에 대응하도록 프로젝트를 설정하는 법을 습득하고, 스스로 요청을 만들 수 있을 것입니다.

전제 조건(Prerequisites):

  • 리모트 컨트롤 API 서버는 30010 포트에서 HTTP 요청을 수신합니다. 해당 포트가 비활성화된 상태일 경우, 프로젝트 세팅(Project Settings) 항목의 웹 리모트 컨트롤(Web Remote Control) 에서 리모트 컨트롤 HTTP 서버 포트(Remote Control HTTP Server Port) 를 변경할 수 있습니다.

  • 웹 클라이언트에서 HTTP 서버 엔드포인트로 JSON 페이로드를 요청하는 방법에 관한 기초 수준의 지식이 필요합니다.

  • 해당 페이지에서 단계를 설명할 때는 블루프린트 3인칭(Blueprint Third-Person) 템플릿의 프로젝트 설정을 사용합니다. 모든 프로젝트에서 대부분의 단계를 동일하게 진행합니다. 다만 프로젝트에서 템플릿과 동일한 스카이 관련 설정을 사용하지 않을 경우, 3 - 요청 보내기 단계에서 사용되는 특정 오브젝트 패스 및 요청이 제대로 작동하지 않을 수 있습니다.

언리얼 엔진 애플리케이션의 호스트 이름 및 포트를 개방된 인터넷에 실행하지 마세요. 실행하면 진행 중인 프로젝트 및 컴퓨터가 제3자의 악의적인 행동에 취약해질 수 있습니다.

웹 리모트 컨트롤 시스템은 근거리 통신망(LAN) 내부나 안전한 가상 사설 통신망(VPN)에서만 사용하세요.

1 - 프로젝트 설정하기

웹 리모트 컨트롤 요청을 만들기 전에 리모트 컨트롤(Remote Control) 플러그인을 설치해야 합니다.

단계

  1. 언리얼 에디터에서 웹 리모트 컨트롤을 사용하고 싶은 프로젝트를 실행하세요.

  2. 메인 메뉴에서 편집(Edit) > 플러그인(Plugins) 을 선택해 플러그인 창을 여세요.

  3. 플러그인 창에서 메시징(Messaging) 카테고리에 있는 리모트 컨트롤 API(Remote Control API) 플러그인을 찾으세요. 활성화됨(Enabled) 체크박스를 클릭하세요.

    리모트 컨트롤 API 플러그인 활성화

  4. 해당 플러그인이 베타 버전이라는 경고문이 등장하면 예(Yes) 를 눌러 확인하세요.

  5. 지금 재시작(Restart Now) 을 눌러 언리얼 에디터를 재시작하고 프로젝트를 다시 여세요.

    지금 재시작

최종 결과

언리얼 에디터에서 프로젝트를 재실행했다면 웹 리모트 컨트롤 서버를 시작할 준비가 된 것입니다.

2 - 서버 관리하기

웹 리모트 컨트롤 시스템은 언리얼 에디터 프로세스에서 실행 및 관리하는 웹 서버에 의존합니다. 서버는 보안을 위해 외부에서 작동할 때만 실행됩니다. 서버의 실행 시기를 조절하려면 간단한 몇 가지 콘솔 명령어를 사용하세요.

명령어

설명

WebControl.StartServer

웹 서버를 시작하고 30010 포트에서 오는 요청을 받아들이기 시작합니다.

WebControl.StopServer

웹 서버를 중단하여 처리 중인 언리얼 에디터 인스턴스로부터의 추가 요청을 막습니다.

WebControl.EnableServerOnStartup

주요 언리얼 에디터 창이나 ‘에디터에서 플레이(PIE)' 세션, 언리얼 에디터의 ‘-game' 모드 등 지원 중인 모드에 속한 언리얼 엔진에서 프로젝트를 열 때마다 웹 서버를 자동으로 시작합니다.

지금은 간단히 주요 에디터 창에서 서버를 시작해 봅시다.

단계

  1. 메인 메뉴에서 창(Window) > 개발자 툴(Developer Tools) > 출력 로그(Output Log) 를 선택하세요.

  2. Cmd 입력 창에서 WebControl.StartServer 콘솔 명령어를 입력하세요.

    서버 시작하기

  3. 서버를 실행 중이라는 메시지가 표시됩니다.

    웹 리모트 컨트롤 서버 시작

최종 결과

이제 서버를 실행하면 요청을 보낼 수 있습니다.

3 - 요청 보내기

가장 간단한 활용 사례를 통해 첫 요청을 만들어봅시다.

  • 테스트용 API 요청 및 응답에 할당된 툴을 사용하세요. 예를 들어 Insomnia 나 Postman 이 있습니다. 툴을 사용하면 요청에 맞는 JSON 페이로드를 구성하고 있는지를 편하게 확인할 수 있습니다. 웹 리모트 컨트롤 엔드포인트의 작동 방식과 엔드포인트의 응답 유형에 익숙해졌다면, 해당 엔드포인트를 자신의 웹 애플리케이션에 통합 호출하는 단계로 넘어가세요.

  • 일단 에디터를 열고 프로젝트를 실행 중인 컴퓨터에서 첫 요청을 만드는 것부터 시작하세요. 정상 작동 여부를 확인한 뒤, 여러분의 로컬 네트워크와 연결된 다른 컴퓨터 혹은 기기의 클라이언트에 요청하는 단계로 넘어가세요.

단계

  1. 웹 클라이언트 앱에서 다음 본문이 포함된 요청을 작성하세요. 

    {
    "objectPath" : "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.LightSource_0.LightComponent0",
    "access":"READ_ACCESS",
    "propertyName":"RelativeRotation"
}

    해당 요청 시 레벨의 주요 디렉셔널 라이트, 즉 월드 아웃라이너(World Outliner) 에 라이트 소스(Light Source) 라는 이름을 가진 액터에 존재하는 RelativeRotation 프로퍼티의 현재 값을 요구합니다.

  2. 다음 엔드포인트로 PUT 요청 형태의 메시지를 보내세요. 

    http://localhost:30010/remote/object/property

  3. 웹 클라이언트에서 상태 코드 및 요청한 정보를 포함한 응답을 볼 수 있습니다. 

    {
     {
             -6.48224
        }
    }

  1. 라이트 소스 액터를 선택하고 디테일 패널을 보면 응답에 등장한 값이 화면에 표시되는 값과 일치할 것입니다.

    디렉셔널 라이트 컴포넌트 트랜스폼

    이를 통해 웹 리모트 컨트롤 시스템에서 여러 오브젝트(여기서는 벡터)를 JSON 값으로 나누어 웹 애플리케이션과 교환하는 방법을 볼 수 있습니다.

  2. 다음은 라이트의 회전을 원격으로 변경합니다.

    이 프로퍼티는 엔진 소스 코드에서 `BlueprintReadOnly`로 정의됩니다. 

    /** 부모를 기준으로 한 컴포넌트의 회전 */
UPROPERTY(EditAnywhere, BlueprintReadOnly, ReplicatedUsing=OnRep_Transform, Category=Transform)
FRotator RelativeRotation;

    이 구문은 수치를 변경하려면 동일한 오브젝트에 의해 표시되는 BlueprintCallable 함수를 호출해야 한다는 뜻입니다. 해당 정의는 Engine/Source/Runtime/Engine/Classes/Components/SceneComponent.h 파일에서 찾을 수 있습니다. 

    /**
 * 부모를 기준으로 한 컴포넌트의 회전 설정
 * @param NewRotation       부모를 기준으로 한 컴포넌트의 신규 회전
 * @param SweepHitResult    Sweep의 값이 True일 때 충돌의 히트 결과
 * @param bSweep            목적지에 대한 Sweep 설정 여부(현재는 회전을 지원하지 않음)
 * @param bTeleport         피직스 스테이트 순간이동 여부(피직스 콜리전이 해당 오브젝트에 활성화된 상태일 경우).
 *                          true일 경우, 해당 오브젝트의 피직스 속도가 변경되지 않습니다(래그돌 파트는 위치 변경에 영향을 받지 않습니다).
 *                          false일 경우, 피직스 속도가 위치 변경에 기반하여 업데이트됩니다(래그돌 파트에 영향을 미칩니다).
 */
UFUNCTION(BlueprintCallable, Category="Utilities|Transformation", meta=(DisplayName="SetRelativeRotation", ScriptName="SetRelativeRotation", AdvancedDisplay="bSweep,SweepHitResult,bTeleport"))
void K2_SetRelativeRotation(FRotator NewRotation, bool bSweep, FHitResult& SweepHitResult, bool bTeleport);
void SetRelativeRotation(FRotator NewRotation, bool bSweep=false, FHitResult* OutSweepHitResult=nullptr, ETeleportType Teleport = ETeleportType::None);
void SetRelativeRotation(const FQuat& NewRotation, bool bSweep=false, FHitResult* OutSweepHitResult=nullptr, ETeleportType Teleport = ETeleportType::None);

  3. 다음 본문이 포함된 요청을 작성하세요. 

    {
    "objectPath" : "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.LightSource_0.LightComponent0",
    "functionName":"SetRelativeRotation",
    "parameters": {
        "NewRotation": {
            "Pitch":90,
            "Yaw":0,
            "Roll":0
        }
    },
    "generateTransaction":true
}

  4. 다음 엔드포인트로 PUT 요청 형태의 메시지를 보내세요. 

    http://localhost:30010/remote/object/call

    레벨에 있던 디렉셔널 라이트의 각도가 바뀌면서 씬에 있는 오브젝트가 어두워질 것입니다.

    디렉셔널 라이트 각도 변경

    이 시점에서 다시 돌아가 위의 2단계와 동일한 요청을 보낼 경우, 방금 설정한 값의 업데이트된 버전을 받게 됩니다.

  5. 원격으로 함수를 하나 더 호출하여 태양의 각도를 새로 고려하도록 하늘의 상태를 업데이트하겠습니다. 이 경우에는 BP_Sky_Sphere 클래스 내부의 블루프린트에서 정의된 함수를 호출할 것입니다.

    BP_SkySphere RefreshMaterial 함수
    클릭하면 이미지를 원래 크기로 볼 수 있습니다.

    이 함수는 SkySphereBlueprint 액터의 디테일 패널에서 머티리얼 새로고침(Refresh Material) 체크박스를 활성화할 때와 같은 효과를 발휘합니다.

  6. 해당 메시지를 위와 같은 엔드포인트에 보내세요. 

    {
    "objectPath" : "/Game/ThirdPersonBP/Maps/ThirdPersonExampleMap.ThirdPersonExampleMap:PersistentLevel.SkySphereBlueprint",
    "functionName":"RefreshMaterial",
    "generateTransaction":true
}

    여기서는 함수가 어떤 입력 파라미터도 요구하지 않으므로, 파라미터 프로퍼티 전체를 생략해도 됩니다.

    레벨에 배치된 하늘이 밤으로 변할 것입니다.

    스카이 머티리얼 업데이트

최종 결과

지금까지 단계를 진행하며 실행 중인 언리얼 엔진 프로젝트의 콘텐츠 정보를 웹 클라이언트에서 취득하는 법을 알아보았습니다. 또한 원격으로 프로젝트의 콘텐츠를 변경할 수도 있었습니다. 웹 클라이언트에서 보낸 요청을 통하여 에디터의 오브젝트에 의해 노출된 함수를 실행하는 식으로 하늘의 모습을 변경한 것입니다.

Lighting and sky changed by remote control

4 - 직접 해보기

지금까지 진행한 단계에 사용된 두 개의 동일한 엔드포인트로 프로젝트의 콘텐츠를 무궁무진하게 변경할 수 있습니다. 활용하는 방법은 아주 다양하므로, 더 자세한 정보 및 예제를 찾으려면 엔드포인트 레퍼런스 를 참조하세요.

웹 서버의 기본 주소는 127.0.0.1이며, 언리얼 엔진 세션을 실행하고 있는 컴퓨터로만 이용할 수 있습니다. 리모트 컨트롤 API를 통해 다른 장치로도 언리얼 세션을 이용하려면 DefaultEngine.ini 파일에서 *DefaultBindAddress**를 변경해 사용 중인 장치의 IP 주소로 바꾸세요. 

[HTTPServer.Listeners]
DefaultBindAddress=0.0.0.0
언리얼 엔진 문서의 미래를 함께 만들어주세요! 더 나은 서비스를 제공할 수 있도록 문서 사용에 대한 피드백을 주세요.
설문조사에 참여해 주세요
건너뛰기