Open full size

PlanetX를 다운로드해주셔서 감사합니다.

이 문서에서는 PlanetX의 설치부터 행성 생성, Ground Level 연결, Proxy Bake, 비주얼 편집, 그리고 Orbit과 Ground 사이의 전환까지 전반적인 사용 방법을 안내합니다.

처음 PlanetX를 사용하신다면 공식 첫 사용 경로인 여기서 시작 — Same World 빠른 시작부터 진행하세요.

#PlanetX란 무엇인가요?

PlanetX는 기존 Unreal Engine Level을 행성 표면의 일부로 활용할 수 있도록 도와주는 Unreal Engine 플러그인입니다.

평소처럼 제작한 Landscape와 Level을 행성의 특정 지역으로 등록하고, 멀리서 보았을 때는 하나의 행성처럼 표현하면서 가까이 접근하면 실제 Ground Level에서 플레이할 수 있도록 연결합니다.

이를 통해 기존 Level 제작 방식을 크게 변경하지 않고도 우주에서 바라보는 행성과 실제 지표면 플레이를 하나의 흐름으로 구성할 수 있습니다.

#무엇을 해결하나요?

Unreal Engine의 일반적인 Level과 Landscape는 평면 공간을 중심으로 제작됩니다. 때문에 우주에서 행성을 바라보다가 그대로 지표면까지 이동하는 게임을 만들려면 원거리 행성 표현, 실제 Ground Level, 좌표 변환과 전환 과정을 별도로 구현해야 합니다.

PlanetX는 기존 Ground Level을 그대로 활용하면서, 해당 영역을 행성 표면의 Section으로 연결합니다. Orbit에서는 가볍게 제작된 Proxy와 행성 표면을 보여주고, 플레이어가 지표면으로 접근하면 실제 Ground 콘텐츠로 자연스럽게 이어지도록 구성할 수 있습니다.

#기본 작업 흐름

1. Planet Asset 생성

   행성의 크기와 기본 설정을 지정합니다.

2. Ground Level 등록

   기존 Unreal Engine Level에서 행성 표면으로 사용할 영역을 Section으로 등록합니다.

3. Section Proxy Bake

   Ground Level을 Orbit에서 보여주기 위한 Proxy로 변환합니다.

4. 행성 비주얼 편집

   Planet Asset Editor > Preview에서 Section의 위치와 행성 표면, Material 등의 모습을 조정합니다.

5. Planet Actor 배치

   완성된 Planet Asset을 Level에 배치하여 행성을 표시합니다.

6. Orbit ↔ Ground 전환 확인

   플레이어 또는 카메라를 이동하며 Orbit 표현과 실제 Ground Level 사이의 전환을 테스트합니다.

다음 단계에서는 설치를 진행하거나, 바로 여기서 시작 — Same World 빠른 시작을 따라 PlanetX를 사용해볼 수 있습니다.

PlanetX는 기존 Unreal Engine Level을 행성의 일부로 연결하고, Orbit에서 바라보는 행성 표현부터 실제 Ground 플레이까지 하나의 흐름으로 구성할 수 있도록 다양한 제작 및 런타임 기능을 제공합니다.

#행성 좌표와 표면 기준

Open full size

PlanetX는 행성의 중심과 표면을 기준으로 위치와 방향을 계산할 수 있는 좌표 체계를 제공합니다.

이를 통해 행성 어디에 있더라도 표면의 위쪽 방향과 이동 방향을 일관되게 계산할 수 있으며, 기존 Unreal Engine의 World 좌표와 행성 좌표 사이를 변환할 수 있습니다.

이 좌표 체계는 Section 배치, Ground 연결, 플레이어 이동과 Orbit ↔ Ground 전환의 공통 기준으로 사용됩니다.

#Section과 Ground 연결

Section은 기존 Ground 콘텐츠를 행성 표면의 특정 지역과 연결하기 위한 단위입니다.

하나의 행성에 여러 Section을 배치할 수 있으며, 각 Section에는 실제 플레이에 사용할 Ground Level을 연결할 수 있습니다.

PlanetX는 프로젝트 구성에 따라 두 가지 방식의 전환을 지원합니다.

• Same World
  Orbit과 Ground 콘텐츠를 하나의 World 안에서 사용하며, 플레이어가 이동하는 동안 표현을 전환합니다.

• Level Handoff
  Orbit과 Ground를 서로 다른 Level로 구성하고, 전환 시 플레이어의 위치와 이동 상태를 이어받아 다른 Level로 이동합니다.

#Section Proxy Bake

Open full size

PlanetX는 기존 Ground Level의 모습을 Orbit에서도 확인할 수 있도록 Section Proxy를 생성할 수 있습니다.

Landscape, Static Mesh, Foliage 등 Ground를 구성하는 주요 요소를 분석하여 원거리에서 사용하기 적합한 형태로 Bake하고, 이를 행성 표면의 Section과 연결합니다.

이를 통해 실제 Ground Level 전체를 항상 표시하지 않고도 Orbit에서는 해당 지역의 모습을 행성 표면에서 확인할 수 있습니다.

#Orbit ↔ Ground 전환

PlanetX는 플레이어 또는 카메라가 행성에 접근하거나 지표면에서 다시 멀어지는 과정에서 Orbit 표현과 실제 Ground 콘텐츠 사이를 전환할 수 있습니다.

전환 과정에서는 행성 표면의 위치와 방향을 기준으로 플레이어의 위치, 회전과 이동 상태를 이어갈 수 있도록 처리합니다.

이를 통해 별도의 착륙 화면이나 완전히 분리된 이동 방식 없이, Orbit과 Ground를 하나의 이동 흐름으로 구성할 수 있습니다.

#행성 비주얼 제작

Open full size

PlanetX는 Section Proxy가 없는 영역까지 하나의 완성된 행성처럼 보이도록 행성 표면을 제작할 수 있는 기능을 제공합니다.

Planet Asset Editor의 Preview 탭에서 다음 요소를 편집하고 미리 확인할 수 있습니다.

• 행성의 기본 표면
• Section과 행성 표면 사이의 연결 영역
• Surface Material
• 대기와 구름
• 태양과 조명
• 우주 배경과 후처리 효과

편집한 결과는 최종 Runtime용 행성 비주얼로 생성하여 사용할 수 있습니다.

#환경 전환

Open full size

Orbit과 Ground에서는 필요한 환경 표현이 서로 다를 수 있습니다.

PlanetX는 행성의 대기, 구름, 조명과 기타 환경 효과를 관리하고, 플레이어가 Orbit과 Ground 사이를 이동할 때 현재 상태에 맞는 환경 표현을 적용할 수 있도록 지원합니다.

#검증과 디버깅

Open full size

PlanetX는 행성을 제작하는 과정에서 잘못된 설정이나 누락된 데이터를 쉽게 확인할 수 있도록 여러 검증 및 디버깅 기능을 제공합니다.

Planet Asset 설정, Section과 Ground 연결, Proxy Bake 결과, 행성 비주얼과 Runtime 전환 상태 등을 확인할 수 있으며, 문제가 발생했을 때 어느 단계에서 수정이 필요한지 파악할 수 있도록 도와줍니다.

PlanetX를 사용하기 전에 지원하는 Unreal Engine 버전과 플랫폼, Proxy Bake의 지원 범위를 확인해 주세요.

#호환성

PlanetX의 행성 제작, Proxy Bake, Planet Asset Editor의 Preview 탭 등의 제작 도구는 Unreal Editor에서 사용합니다.
완성된 게임에서는 필요한 Planet Asset과 Bake된 행성 및 Proxy 데이터를 Runtime에서 사용합니다.

#권장 시스템 사양

PlanetX는 Unreal Engine Editor 위에서 동작하므로 CPU와 GPU는 기본적으로 Unreal Engine 5.8의 권장 시스템 사양 이상을 권장합니다.

다만 Proxy Bake와 Planet Asset Editor의 Preview 탭에서는 큰 Level의 Geometry와 중간 생성 데이터를 메모리에 유지하는 작업이 발생할 수 있으므로, 일반적인 Unreal Engine 프로젝트보다 충분한 시스템 메모리를 확보하는 것을 권장합니다.

실제 필요한 메모리는 Source Level의 크기와 복잡도, Proxy Bake 대상 수, Landscape 해상도와 Visual 설정에 따라 달라질 수 있습니다.

#Proxy Bake 지원 범위

Proxy Bake는 Ground Level의 시각적인 모습을 Orbit에서 사용할 수 있는 Section Proxy로 변환합니다.

현재 다음과 같은 Unreal Engine 콘텐츠를 직접 지원합니다.

• Static Mesh
• Instanced Static Mesh (ISM)
• Hierarchical Instanced Static Mesh (HISM)
• Foliage
• Landscape

PCG로 생성된 Static Mesh나 Instance, Level Instance, Packed Level Actor, HLOD 등은 실제로 확인 가능한 콘텐츠가 위의 지원 형식으로 구성되어 있는 경우 조건부로 처리할 수 있습니다.

반면 다음과 같이 실행 중에 형태가 변하거나 별도의 표현 방식이 필요한 콘텐츠는 일반적인 Proxy Bake 대상으로 지원하지 않습니다.

• Spline Mesh
• Skeletal Mesh와 Cloth
• Dynamic / Procedural Mesh
• Groom
• Niagara와 기타 Effect
• Geometry Collection 등의 동적 Geometry

지원하지 않는 시각 요소가 발견되었을 때 PlanetX는 가능한 경우 이를 조용히 무시하지 않고 Bake 결과에 누락 항목으로 기록합니다.

Proxy Bake가 Completed With Warnings로 완료되었다면 Proxy 생성 자체는 성공했지만 일부 콘텐츠가 제외되었을 수 있으므로 결과와 경고 내용을 확인하는 것을 권장합니다.

#Runtime 표현의 범위

Orbit에서 사용하는 Proxy와 Runtime Preview는 실제 Ground Level을 복제한 것이 아니라 원거리 표현을 위한 시각 데이터입니다.

따라서 Runtime Preview 자체는 다음 기능을 제공하지 않습니다.

• Ground Level의 Gameplay Actor 복제
• Collision
• Navigation
• Ground Actor의 Tick 및 Gameplay Logic

실제 게임플레이는 원본 Ground 콘텐츠에서 수행하며, PlanetX는 Orbit 표현과 Ground 콘텐츠를 연결하는 역할을 담당합니다.

Level Handoff를 사용하는 경우에도 Level을 불러오는 방식이나 Pawn 생성과 같은 게임 고유의 흐름은 프로젝트에서 계속 관리합니다.

#Proxy Bake 크기 제한

대규모 Level의 Proxy Bake에서는 지나치게 큰 단일 결과물이 생성되지 않도록 출력 크기를 제한합니다.

• 개별 Proxy Bake 처리 조각의 중간 데이터는 일반적으로 128 MiB 이하를 목표로 합니다.
• 생성되는 개별 Package가 512 MiB를 초과하면 경고가 표시됩니다.
• 개별 Package가 1 GiB를 초과하면 해당 결과를 게시할 수 없습니다.

복잡한 대규모 Level에서는 Proxy의 Detail과 Bake 대상 범위를 적절하게 조정하는 것을 권장합니다.

이 문서는 공식 첫 사용 및 제품 검토 경로입니다. Unreal Engine의 기본 Open World Level 템플릿으로 시작해 Level을 GroundLevel로 저장하고, 이를 PlanetX의 Same World Section으로 연결한 뒤 실제 Ground 콘텐츠와의 런타임 전환을 확인합니다.

완료하면 다음과 같은 구성이 만들어집니다.

• Planet Asset 1개
• GroundLevel과 연결된 Same World Section 1개
• Bake된 Section Proxy
• Runtime용 행성 비주얼
• PlanetX Planet Actor
• Environment Manager
• Transition Endpoint
• Orbit ↔ Ground 전환에 참여하는 Player Actor

#시작하기 전에

다음 항목을 준비해 주세요.

• PlanetX가 설치되고 활성화된 Unreal Engine 5.8 프로젝트

미리 준비한 Ground Level은 필요하지 않습니다. 2단계에서 Unreal Engine의 기본 Open World 템플릿으로 새 Level을 만들고 GroundLevel로 저장합니다. 이 템플릿의 Landscape를 재현 가능한 Source로 사용하며, 런타임 전환 테스트에 필요한 Player Actor는 11단계에서 준비합니다.

동일한 결과를 재현하려면 다음 값을 그대로 사용하세요.

2단계에서 GroundLevel을 만들고 저장하기 전에는 Proxy Bake를 열지 마세요. Proxy Bake에는 Untitled 또는 /Temp Level이 아닌 저장된 Level을 사용해야 합니다.

또한 PIE 또는 Simulate가 실행 중이라면 먼저 종료하세요. Proxy Bake는 Editor의 Ground Source를 기준으로 작업하므로 PIE 중에는 실행하지 않습니다.

#1. Planet Asset 준비

Content Browser > Add > Miscellaneous > Planet Asset을 선택합니다. 이 문서에서는 Planet ID FirstPlanet, Planet Radius 100 km, 기본 Coordinate Convention을 사용하고 Asset을 PA_FirstPlanet으로 저장합니다. 각 설정의 개념 설명이 필요한 경우에만 첫 Planet Asset 만들기를 참고하세요.

Open full size

Section은 아직 직접 만들 필요가 없습니다.

처음 Proxy Bake를 실행하면 현재 Ground Level을 기준으로 필요한 Section과 Level Pair가 자동으로 생성됩니다.

#2. GroundLevel을 만들고 Proxy Bake 열기

File > New Level을 선택하고 Unreal Engine의 기본 Open World 템플릿을 연 뒤 즉시 GroundLevel로 저장합니다.

Open World 템플릿에는 World Partition Landscape가 포함되어 있으며, 이 빠른 시작에서는 동일한 결과를 재현하기 위한 Ground Source로 사용합니다. 이 흐름을 성공한 뒤에는 프로젝트의 실제 Gameplay Level에서도 같은 과정을 반복할 수 있습니다.

Proxy Bake를 열기 전에 Level 탭이 Untitled가 아니라 GroundLevel인지 확인하고 한 번 더 저장하세요.

첫 Bake에서는 Unreal Editor의 Tools 메뉴에서 PlanetX 영역을 찾고 Proxy Bake Editor를 선택합니다. 이 경로가 공식 첫 사용 경로입니다.

Open full size

Planet Asset Editor > Sections에서 Proxy Bake를 여는 방식은 기존 Section 작업 경로이며 Section이 이미 생성된 뒤에만 사용합니다.

Proxy Bake Editor가 열리면 먼저 상단의 Basic 모드를 사용하면 됩니다. 빠른 시작에서는 Advanced 설정을 변경할 필요가 없습니다.

#Target Planet Asset 지정

1 Target Planet Asset 영역에서 앞 단계에서 만든 Planet Asset을 선택합니다.

이미 Planet Asset Editor에서 Proxy Bake를 열었다면 자동으로 지정되어 있을 수 있습니다.

Planet Asset이 올바르게 지정되었는지 확인하세요.

#Runtime Role을 Same World로 설정

2 Runtime Role을 펼칩니다.

Presentation에서 다음 값을 선택합니다.

Same World

Same World는 Planet과 실제 Ground 콘텐츠가 같은 World 안에 존재하는 구성입니다.

이 모드에서는 현재 열려 있는 Ground Level이 자동으로 Ground World가 됩니다.

따라서 별도의 Planet World를 지정할 필요가 없습니다.

Ground World에 현재 작업 중인 Level이 표시되는지 확인하세요.

#Source Scope 선택

3 Source Scope에서 Proxy Bake가 어떤 Actor를 검색할지 선택합니다.

처음 사용하는 경우 일반적인 단일 Level이라면 다음 설정을 권장합니다.

Source Scope
└─ Current Level

각 옵션은 다음과 같이 사용할 수 있습니다.

• Selected Actors
  현재 선택한 Actor만 Bake하고 싶을 때 사용합니다.

• Current Level
  현재 Persistent Level의 Actor를 대상으로 합니다. 일반적인 첫 테스트에 적합합니다.

• Loaded Levels
  현재 Level과 함께 로드된 Streaming Level 및 Level Instance까지 포함할 때 사용합니다.

• Reviewed Set
  이전에 검토한 Source 목록을 그대로 다시 사용합니다. 반복적인 제작 작업을 위한 옵션이므로 처음에는 사용하지 않아도 됩니다.

그 아래의 Source Representation은 특별한 이유가 없다면 기본 설정을 유지해도 됩니다.

World Partition HLOD가 준비되어 있다면 Prefer HLOD가 유효한 HLOD를 우선 사용하고, 필요한 경우 원본 Actor를 사용합니다.

#Bake Quality 선택

Proxy Bake Editor 상단의 BAKE QUALITY에서 다음 값을 권장합니다.

High (Recommended)

빠른 테스트 시간을 줄이고 싶다면 Medium이나 Low를 사용할 수 있지만, 최종 결과를 확인할 때는 High 사용을 권장합니다.

#3. Ground Source 검색하기

설정이 끝났다면 Scan Sources를 클릭합니다.

단축키는 F5입니다.

Scan Sources

Scan은 현재 설정에 따라 Ground Level을 검색하고 Proxy Bake에 사용할 Source 목록과 Bake Plan을 구성합니다.

Scan이 완료되면 Source Review에서 발견된 Source를 확인합니다.

일반적인 Static Mesh, Landscape, ISM/HISM, Foliage 등의 지원 대상은 자동으로 적절한 역할이 지정됩니다.

#Source Review에서 확인할 것

처음에는 목록 전체를 하나씩 수정할 필요는 없습니다.

다음과 같은 문제가 표시되는지만 확인하세요.

• 사용하려던 Actor가 목록에 나타나지 않음
• Manual Review가 필요한 Source가 있음
• Unsupported Source가 있음
• Bake에 사용되는 Source가 하나도 없음

상태 줄이 녹색 SUCCESS이고, 의도한 Source가 하나 이상 활성화되어 있으며, Unsupported와 Manual Review가 모두 0이고 BAKE IN EDITOR가 활성화된 상태에서 진행합니다.

Open full size

생성되는 Section ID에는 고유한 접미사가 붙습니다. 예시 화면은 GroundLevel_143C3E3D를 사용하지만 사용자의 접미사는 달라도 정상입니다.

지원하지 않는 Source가 있다면 해당 항목을 제외하거나 문제를 수정한 뒤 다시 Scan할 수 있습니다.

Source Review에서 Use 또는 Role 값을 직접 변경했다면 반드시 다음 버튼을 한 번 클릭하세요.

Apply Source Changes

Source 변경 사항을 적용하지 않으면 Bake 버튼이 활성화되지 않습니다.

아무 Source도 수정하지 않았다면 별도로 누를 필요는 없습니다.

#World Partition을 사용하는 경우

World Partition Level에서는 Output Plan에 자동 크기 설정이 표시될 수 있습니다.

처음에는 Automatic World Partition Output Sizing을 활성화한 상태로 사용하는 것을 권장합니다.

Scan 결과를 기준으로 PlanetX가 필요한 출력 Partition 구성을 계산합니다.

#4. Section Proxy Bake 실행하기

Source 검토가 끝났다면 BAKE IN EDITOR를 클릭합니다.

단축키는 Ctrl+B입니다.

BAKE IN EDITOR

Bake가 진행되는 동안 Ground의 Geometry를 수집하고, Orbit에서 사용할 Section Proxy와 필요한 Runtime 데이터를 생성합니다.

처음 Bake하는 Planet Asset이라면 이 과정에서 현재 Ground Level에 대응하는 Section이 자동으로 생성되고 Planet Asset에 연결됩니다.

Bake가 끝날 때까지 기다리세요.

#Bake 결과 확인

정상적으로 완료되었다면 결과가 성공 상태로 표시됩니다.

일부 Source가 제외되었다면 Bake 자체는 성공하면서 경고가 함께 표시될 수 있습니다.

이 경우 결과의 Warning과 Omission을 확인하여 의도한 Ground 콘텐츠가 빠지지 않았는지 확인하세요.

필요하다면 Open Results를 클릭하거나 Ctrl+Shift+O를 눌러 생성된 Bake 결과를 Content Browser에서 확인할 수 있습니다.

#5. 생성된 Section 확인하기

Planet Asset Editor로 돌아가 Sections를 엽니다.

첫 Proxy Bake가 성공했다면 Section 목록에 새로운 항목이 하나 표시됩니다.

빠른 시작에서는 다음 상태를 확인하면 됩니다.

Section을 선택하면 오른쪽에서 연결된 Ground World와 Generated Resource 상태를 추가로 확인할 수 있습니다.

Same World Section은 Ground Level과 행성의 기준점을 연결하는 고정 Anchor로 사용됩니다.

따라서 기본 Same World Section의 Latitude, Longitude, Surface Yaw와 Scale은 직접 변경할 필요가 없습니다.

필요한 경우 Altitude만 조정하여 Ground와 행성 표면 사이의 높이 차이를 보정할 수 있습니다.

#6. 행성 비주얼 만들기

이제 Planet Asset Editor에서 Preview를 엽니다.

처음에는 Basic 모드를 사용하면 됩니다.

여기에서는 Bake된 Section Proxy와 나머지 행성 표면을 함께 확인할 수 있습니다.

#Completion Material 지정

행성에서 Section이 존재하지 않는 나머지 영역을 표시하려면 Completion Material을 지정합니다.

Preview
└─ Basic
   └─ Planet
      └─ Completion Material

이 튜토리얼에서는 Show Plugin Content를 활성화하고 포함된 MI_PlanetX_Earth Material Instance를 선택합니다.

/PlanetX/PlanetX/Materials/Samples/PlanetSurface/MI_PlanetX_Earth

처음에는 Terrain Height, Terrain Frequency, Padding Width 등의 값은 기본값으로 두어도 됩니다.

Preview에서 다음 사항만 확인합니다.

• 행성 전체가 정상적으로 표시되는지
• Bake한 Section Proxy가 행성 표면에 나타나는지
• Proxy 주변에 심각한 빈 공간이나 뒤집힌 Geometry가 없는지

Open full size

Preview 상단의 10000은 Viewport 카메라 속도이며 Planet Radius가 아닙니다.

#Runtime Visual 생성

Preview 결과에 문제가 없다면 Planet Visual Build 영역에서 다음 버튼을 클릭합니다.

Apply & Build

Apply & Build는 현재 Preview 설정을 Planet Asset에 적용하고, 필요한 Padding Material과 Runtime용 행성 Visual Asset을 생성합니다.

작업이 완료될 때까지 기다리세요. 성공하면 다음 메시지가 표시됩니다.

Planet Visual Build completed successfully.

작업이 끝나면 Planet Asset을 저장합니다.

#7. Ground Level에 PlanetX Planet 배치하기

다시 Ground Level로 돌아옵니다.

Place Actors에서 다음 Actor를 검색합니다.

PlanetX Planet

Level에 PlanetX Planet Actor를 하나 배치합니다.

Actor를 선택하고 Details에서 Planet Component를 찾은 뒤 Planet Asset에 앞에서 만든 Planet Asset을 지정합니다.

Open full size

다음 기본 설정은 그대로 유지합니다.

Auto Register Runtime
    Enabled

하나의 Planet Actor만 사용하는 빠른 시작에서는 별도의 Planet Binding ID를 설정할 필요가 없습니다.

#8. Planet Actor를 Ground Level에 정렬하기

Level Editor 왼쪽 위의 Modes 선택기에서 PlanetX Mode를 선택합니다.

PlanetX Mode 상단에는 다음 세 가지 Preview View가 있습니다.

• Planet
• Compare
• Level

먼저 Level을 선택합니다.

Preview View
└─ Level

Level View에서는 Planet Proxy를 숨기고 원본 Ground Level을 표시합니다.

#활성 Planet 확인

PlanetX Mode의 Scene 영역에서 방금 배치한 Planet Actor가 활성 Planet으로 선택되어 있는지 확인합니다.

Planet이 여러 개 있다면 방금 만든 Planet을 명시적으로 선택하세요.

#Same World Align 실행

Scene 영역의 오른쪽에 있는 Transform 모양의 Align 아이콘을 클릭합니다.

이 버튼은 Planet Actor를 현재 Same World Ground Level의 기준 위치에 맞춥니다.

Same World에서는 Ground Level을 행성의 North Pole 기준 Section으로 사용하므로 사용자가 Planet Actor의 위치를 직접 계산할 필요가 없습니다.

Align은 Planet Actor의 회전이나 Scale을 임의로 변경하지 않고, Ground와 행성 표면이 맞닿도록 위치를 조정합니다.

#Compare로 정렬 확인

정렬이 끝나면 상단 Preview View를 Compare로 변경합니다.

Compare

Compare에서는 다음 두 표현을 동시에 확인할 수 있습니다.

• 실제 Ground Level
• Bake된 Planet Section Proxy

두 표현이 같은 위치에 겹쳐 보이는지 확인하세요.

큰 위치 오차가 보인다면 다음 단계로 진행하기 전에 다음 항목을 다시 확인하는 것이 좋습니다.

• 올바른 Planet Asset이 Planet Actor에 지정되어 있는지
• Proxy Bake가 현재 Ground Level을 대상으로 만들어졌는지
• Same World Section의 Bake 상태가 Linked인지
• Section Altitude가 의도하지 않은 값으로 변경되지 않았는지

확인이 끝나면 Planet View로 전환하여 Orbit에서 보이는 행성 표현도 확인할 수 있습니다.

#9. Environment Manager 추가하기

PlanetX는 각 Planet에 하나의 Environment Manager를 사용합니다.

Environment Manager를 추가하고 연결하기 전에는 PlanetX가 이 Level에 대기, 구름과 우주 배경 환경을 아직 적용하지 않았기 때문에 행성이 어둡게 보일 수 있습니다. 이 상태를 Material 오류로 판단하지 말고 Environment Manager 설정을 먼저 완료하세요.

PlanetX Mode에서 Environment Palette를 엽니다.

단축키는 Alt+5입니다.

Environment Manager가 아직 없다면 다음 메시지가 표시됩니다.

Environment Manager is not assigned to this Planet.

Add Manager를 클릭합니다.

Add Manager

PlanetX가 현재 활성 Planet에 연결된 PlanetXEnvironmentManager를 Level에 생성합니다.

처음에는 별도의 Level Override를 설정하지 않아도 됩니다. Planet Asset에서 작성한 Environment 설정이 기본값으로 사용됩니다.

Manager를 추가한 직후 GroundLevel을 저장합니다. 대기나 구름이 이상하게 보인다면 먼저 Level을 저장한 뒤 Planet View를 다시 확인하세요. 저장하면 Environment가 다시 평가되기 전에 Manager와 Level Binding이 유지됩니다.

Manager가 생성되었다면 Validate를 눌러 현재 Planet과 올바르게 연결되었는지 확인합니다.

#10. Transition Endpoint 추가하기

PlanetX Mode에서 Transition Palette를 엽니다.

단축키는 Alt+4입니다.

현재 Level에 Endpoint가 없다면 다음 메시지가 표시됩니다.

No Transition Endpoint for this Level.

Add Endpoint를 클릭합니다.

Add Endpoint

PlanetX가 현재 활성 Planet과 Same World Section에 맞는 Transition Endpoint를 자동으로 생성합니다.

Endpoint에는 다음 정보가 자동으로 연결됩니다.

• 현재 Planet
• 현재 Section
• 현재 Level Pair
• 앞 단계에서 만든 Environment Manager

따라서 빠른 시작에서는 ID를 직접 입력할 필요가 없습니다.

#Transition 범위 확인

생성된 Endpoint는 Section의 크기를 기준으로 Transition Cylinder를 자동 설정합니다.

기본 설정인 다음 옵션은 그대로 유지하세요.

Auto Size Transition Cylinder to Section Bounds
    Enabled

Viewport에는 Transition 영역을 확인하기 위한 Debug Cylinder가 표시됩니다.

이 영역은 플레이어가 Orbit, Transition, Ground 중 어느 상태에 있는지 판단하는 기준으로 사용됩니다.

Endpoint의 위치나 크기를 처음부터 수동으로 조정할 필요는 없습니다.

Level을 저장합니다.

#11. Player Actor를 PlanetX에 연결하기

이제 실제로 움직일 Pawn 또는 Character를 설정합니다.

여기서는 현재 PlayerController가 View Target으로 사용하는 Actor를 수정해야 합니다. 이 튜토리얼에서는 Ground Level에 배치하고 Auto Possess Player 0으로 설정한 Pawn 또는 Character Instance를 사용합니다.

GroundLevel에 해당 Actor가 없다면 지금 Pawn 또는 Character를 배치하고 Auto Possess Player를 Player 0으로 설정한 뒤, 활성 Camera Component가 PlayerController의 View Target을 제공하는지 확인합니다.

해당 Actor의 Blueprint를 엽니다.

#Coordinate Component 추가

Components 패널에서 PlanetX Coordinate Component를 추가합니다.

Component를 추가한 뒤 Blueprint를 Compile하고 Ground Level로 돌아갑니다. Level에 배치한 Player Actor Instance를 선택하고 해당 Instance의 Component Details에서 PlanetX Reference를 다음과 같이 설정합니다.

Reference Planet Actor에는 이 Level에 배치한 PlanetX Planet Instance를 지정합니다.

그 다음 Reference Section Id에서 앞의 Proxy Bake가 생성한 Same World Section을 선택합니다.

처음 테스트에서는 Section을 자동 검색하게 두기보다 명시적으로 지정하는 것을 권장합니다.

Open full size

PIE가 시작되면 실제로 Possess된 Pawn이 여기서 설정한 Actor와 같은지 확인하세요. World Outliner에 별도의 DefaultPawn0가 생성되고 그 Pawn이 Possess된다면, 배치된 BP_Player가 조작된다고 가정하지 말고 실제 Pawn을 설정하거나 GameMode의 Default Pawn Class를 변경해야 합니다.

최종적으로 다음 관계가 되어야 합니다.

Player Actor
└─ PlanetX Coordinate Component
   ├─ Reference Planet Actor → 배치한 PlanetX Planet
   └─ Reference Section Id   → Bake로 생성된 Same World Section

Reference Planet Actor가 설정되어 있다면 Planet ID는 해당 Actor의 Planet Asset에서 자동으로 결정됩니다.

#Viewpoint Component 추가

같은 Actor에 PlanetX Viewpoint Component를 추가합니다.

다음 기본 설정은 그대로 유지합니다.

Auto Register Runtime
    Enabled

Can Drive Transition State
    Enabled

그리고 해당 Actor에 활성 Camera Component가 하나 이상 존재하는지 반드시 확인하세요.

PlanetX는 PIE에서 실제 PlayerController의 View Target과 활성 Camera를 기준으로 Orbit / Transition / Ground 상태를 계산합니다.

따라서 PlayerController가 다른 Actor를 View Target으로 사용하고 있다면 PlanetX Viewpoint Component도 실제 View Target Actor에 추가해야 합니다.

#Movement Component는 필요한 경우에만 추가

기존 Character Movement나 프로젝트 고유 이동 시스템을 사용하고 있다면 PlanetX Movement Component를 반드시 추가할 필요는 없습니다.

PlanetX Movement Component는 다음과 같은 기능이 필요한 경우에 추가하세요.

• 행성 중심 방향의 중력
• Surface Frame 기반 이동 입력
• 행성 표면 Up 방향 정렬
• PlanetX Movement Handoff

빠른 시작에서 단순히 Orbit ↔ Ground 전환을 확인하는 목적이라면 기존 이동 Component를 그대로 사용할 수 있습니다.

#12. 자동 Same World Entry 활성화하기

Same World에서 플레이어가 Transition 영역을 통과할 때 자동으로 Ground와 Orbit 좌표 사이를 이동하도록 설정합니다.

현재 PlanetX에서는 이 설정을 Blueprint에서 활성화할 수 있습니다.

Player Actor Blueprint의 Event BeginPlay에서 앞에서 추가한 PlanetX Coordinate Component를 사용하여 다음 두 함수를 호출합니다.

Event BeginPlay
    │
    ├─ Set Automatic Same World Entry Enabled
    │      Enabled = true
    │
    └─ Set Automatic Same World Return Enabled
           Enabled = true

두 함수 모두 PlanetX Coordinate Component의 함수입니다.

첫 번째 옵션은 플레이어가 Ground 영역으로 들어왔을 때 Orbit 좌표에서 실제 Ground 좌표로 이동하도록 합니다.

두 번째 옵션은 다시 Orbit 영역으로 나갈 때 Ground에서 Orbit 좌표로 복귀하도록 합니다.

빠른 시작에서는 Return Pose와 Movement Continuity의 기본 정책을 그대로 사용하면 됩니다.

기본적으로 Ground에서 이동한 결과를 유지하면서 Orbit 좌표로 이어지고, 필요한 경우 두 좌표 Frame 사이에서 이동 상태가 변환됩니다.

Blueprint를 Compile하고 저장합니다.

#13. 테스트 시작 위치 확인하기

Orbit → Ground 전환을 확인하려면 플레이어가 처음부터 Ground 영역 안에 있어서는 안 됩니다.

Transition Endpoint의 Debug Cylinder를 확인하고, 플레이어의 시작 위치를 Ground Transition 영역 바깥쪽에 배치하세요.

정확한 거리는 Section의 크기에 따라 달라지므로 고정된 숫자로 맞출 필요는 없습니다.

중요한 것은 플레이어 또는 카메라가 다음 순서로 이동할 수 있어야 한다는 점입니다.

Orbit
  ↓
Transition
  ↓
Ground

그리고 반대로 이동하면 다음 순서가 됩니다.

Ground
  ↓
Transition
  ↓
Orbit

기존 Character가 지상 이동만 가능해 Orbit 영역에서 Ground 쪽으로 이동할 수 없다면, 테스트용 Pawn이나 비행 가능한 이동 방식을 사용하세요.

PlanetX는 프로젝트의 Pawn 이동 방식을 대신 제공하지 않습니다.

#14. 실행 전 검증하기

모든 설정이 끝났다면 Save All을 실행합니다.

Planet Asset을 열고 Diagnostics에서 다음을 실행합니다.

Full Validate

또는 PlanetX Mode의 Validate Palette에서도 현재 World 구성을 확인할 수 있습니다.

단축키는 Alt+6입니다.

빠른 시작에서는 최소한 다음 항목에 Error가 없어야 합니다.

• Planet Actor가 존재하고 Planet Asset이 연결되어 있음
• Same World Section과 Level Pair가 유효함
• Proxy BakeData가 연결되어 있음
• Runtime에서 표시할 Proxy가 존재함
• Transition Endpoint가 정확히 하나 존재함
• Environment Manager가 정확히 하나 존재함
• Planet과 Ground의 Same World Align이 올바름

Open full size

Info 항목은 남아 있을 수 있습니다. 첫 검증 통과 기준은 Errors 0, Warnings 0입니다.

Validation Error가 있다면 PIE로 넘어가기 전에 먼저 해결하세요.

일부 중요한 설정 오류는 PlanetX가 PIE 시작을 차단할 수 있습니다.

#15. PIE에서 Orbit ↔ Ground 전환 확인하기

이제 Play를 눌러 PIE를 시작합니다.

PlanetX Mode의 Runtime Palette를 엽니다.

단축키는 Alt+2입니다.

Runtime Palette에서는 현재 Planet 등록 상태와 Transition 상태를 확인할 수 있습니다.

플레이어를 Ground 방향으로 이동시키면서 Transition 상태를 확인하세요.

정상적인 경우 상태가 다음과 같이 변합니다.

Orbit
→ Transition
→ Ground

Ground 상태에 도달하면 PlanetX가 Same World Section의 실제 Ground 위치로 플레이어 상태를 연결합니다.

다시 Ground에서 멀어지면 다음 순서로 복귀합니다.

Ground
→ Transition
→ Orbit

전환 과정에서 다음 항목을 확인하세요.

• Section Proxy와 실제 Ground가 크게 어긋나지 않는지
• 플레이어 위치가 갑자기 엉뚱한 장소로 이동하지 않는지
• 카메라 방향이 정상적으로 유지되는지
• Ground 진입 후 기존 Gameplay가 정상적으로 동작하는지
• Orbit으로 돌아갈 때 이동 흐름이 자연스럽게 이어지는지

아래 예시는 완성된 행성 비주얼이 표시된 상태로 GroundLevel이 실제 PIE에서 실행 중인 화면입니다. 이 이미지는 PIE 렌더링 결과를 확인하는 용도이며, 실제 Orbit, Transition, Ground 상태 순서는 앞에서 설명한 Runtime Palette에서 별도로 확인하세요.

Open full size

예시 화면의 노란색 Placement 안내는 배치 편집 대상으로 선택된 Actor가 없다는 뜻이며 Validation Error가 아닙니다.

#전환이 동작하지 않는다면

자동 전환이 발생하지 않는 경우 다음 항목을 순서대로 확인하세요.

1. PlanetX Planet에 올바른 Planet Asset이 지정되어 있는지 확인합니다.
2. PlanetX Mode의 Align을 실행했는지 확인합니다.
3. Environment Manager가 하나 존재하는지 확인합니다.
4. Transition Endpoint가 하나 존재하는지 확인합니다.
5. Player Actor의 Coordinate Component에 올바른 Reference Planet Actor와 Reference Section Id가 지정되어 있는지 확인합니다.
6. 실제 PlayerController의 View Target에 PlanetX Viewpoint Component가 있는지 확인합니다.
7. View Target에 활성 Camera Component가 있는지 확인합니다.
8. Blueprint에서 Automatic Same World Entry와 Automatic Same World Return을 활성화했는지 확인합니다.
9. Proxy Bake 결과가 오래된 상태라면 다시 Scan Sources → Bake를 실행합니다.
10. 비주얼이 오래된 상태라면 Planet Asset Editor > Preview에서 다시 Apply & Build를 실행합니다.
11. 마지막으로 Full Validate에서 남아 있는 Error를 확인합니다.

문제가 계속된다면 진단 도구와 Runtime 이동 문제 해결을 참고하세요.

#완료

여기까지 정상적으로 동작했다면 PlanetX의 가장 기본적인 제작 흐름을 한 번 완료한 것입니다.

Planet Asset
    ↓
Ground Level
    ↓
Proxy Bake
    ↓
Same World Section
    ↓
Planet Visual Build
    ↓
PlanetX Planet + Align
    ↓
Environment Manager
    ↓
Transition Endpoint
    ↓
Player Coordinate + Viewpoint
    ↓
Orbit ↔ Ground

다음 단계에서는 필요에 따라 Planet Asset Editor > Preview에서 행성의 표면과 환경을 더 세밀하게 편집하거나, 여러 Section을 추가하거나, 서로 다른 Level을 연결하는 External Level 방식을 구성할 수 있습니다.

PlanetX는 Fab을 통해 Unreal Engine에 설치할 수 있습니다.

#사전 조건

PlanetX를 설치하기 전에 다음 환경을 확인해 주세요.

• Unreal Engine 5.8
• GeometryProcessing 플러그인
• PCG 플러그인

PlanetX는 필요한 Unreal Engine 플러그인을 함께 활성화하도록 구성되어 있습니다.

#Fab에서 설치하기

1. Epic Games Launcher를 실행합니다.
2. Unreal Engine > Library로 이동합니다.
3. Fab Library에서 PlanetX를 찾습니다.
4. Install to Engine을 클릭합니다.
5. PlanetX를 사용할 Unreal Engine 5.8 설치를 선택합니다.
6. 설치가 완료되면 Unreal Editor를 실행합니다.

Fab Library에는 PlanetX가 지원하는 Unreal Engine 버전만 설치 대상으로 표시됩니다.

설치 후 프로젝트를 열고 Edit > Plugins에서 PlanetX가 활성화되어 있는지 확인하세요.
처음 활성화한 경우 Unreal Editor를 다시 시작해야 할 수 있습니다.

#수동 설치

Fab을 사용하지 않고 별도로 제공된 PlanetX 패키지를 설치해야 하는 경우에는 프로젝트의 Plugins 디렉터리에 직접 설치할 수 있습니다.

1. Unreal Editor를 종료합니다.

2. PlanetX 디렉터리를 다음 위치에 복사합니다.

   textCopy

   <Project>/Plugins/PlanetX

3. 프로젝트를 다시 엽니다.

4. 필요한 경우 Project Files를 재생성하고 프로젝트를 빌드합니다.

5. Edit > Plugins에서 PlanetX가 활성화되어 있는지 확인합니다.

수동 설치는 개발용 빌드나 별도로 제공된 패키지를 사용하는 경우를 위한 방법입니다. 일반적인 설치에는 Fab 사용을 권장합니다.

#설치 확인

설치가 완료되었다면 다음 항목을 확인할 수 있습니다.

• Content Browser > Add > Miscellaneous에서 Planet Asset을 생성할 수 있습니다.
• Editor 메뉴에서 PlanetX Proxy Bake Editor를 열 수 있습니다.
• Editor의 PlanetX Mode를 사용할 수 있습니다.

위 항목이 정상적으로 표시된다면 PlanetX 설치가 완료된 것입니다.

#Plugin Content 보기

PlanetX에는 일부 Unreal Engine Content Asset이 포함되어 있습니다.

PlanetX의 Plugin Content를 직접 확인해야 하는 경우 Content Browser의 설정에서 Show Plugin Content를 활성화하세요.

일반적인 PlanetX 사용에는 Plugin Content를 직접 수정할 필요가 없습니다.

#문서 열기

최신 PlanetX 문서는 온라인 문서 사이트에서 확인할 수 있습니다.

인터넷에 연결할 수 없는 환경에서는 설치된 PlanetX 플러그인의 다음 파일을 직접 열어 오프라인 문서를 사용할 수 있습니다.

PlanetX/Docs/index.html

문서를 연 뒤 여기서 시작 — Same World 빠른 시작부터 진행하세요. 이 문서가 공식 첫 사용 경로입니다.

Planet Asset은 PlanetX에서 하나의 행성을 정의하는 중심 Asset입니다.

행성의 크기와 좌표 기준을 저장하며, 이후 생성되는 Section, Proxy Bake 결과와 행성 비주얼이 모두 이 Planet Asset을 기준으로 연결됩니다.

#Planet Asset 생성하기

Content Browser > Add > Miscellaneous에서 Planet Asset을 선택합니다.

생성 창에서는 다음 세 가지 기본 정보를 설정합니다.

• Planet ID
• Planet Radius
• Coordinate Convention

처음 PlanetX를 사용한다면 Coordinate Convention은 기본값을 유지하고, Planet ID와 Planet Radius만 확인한 뒤 생성해도 충분합니다.

#Planet ID

Planet ID는 PlanetX가 행성을 구분하기 위해 사용하는 고유한 이름입니다.

예를 들어 지구와 화성을 각각 만든다면 다음처럼 지정할 수 있습니다.

Earth
Mars

Planet ID는 프로젝트 안의 다른 Planet Asset과 중복되지 않도록 지정하세요.

파일 이름이나 화면에 표시하기 위한 이름보다는, 프로젝트가 진행되는 동안 계속 유지할 안정적인 식별자로 정하는 것을 권장합니다.

예를 들어 다음과 같이 사용하는 것이 좋습니다.

Earth
Mars
Moon
MainPlanet

반대로 작업 단계에 따라 자주 바뀔 가능성이 있는 이름은 피하는 것이 좋습니다.

TestPlanet
NewPlanet
Planet_Final_Final2

여러 World에서 동일한 행성의 서로 다른 Runtime 인스턴스를 구분해야 하는 고급 구성에서는 별도의 Planet Binding을 사용할 수 있습니다.

처음 Planet Asset을 만드는 단계에서는 Planet Binding을 신경 쓰지 않아도 됩니다.

#Planet Radius

Planet Radius는 행성 중심에서 기본 표면까지의 거리를 의미합니다.

Planet Asset 생성 창에서는 km 단위로 입력합니다.

Same World 빠른 시작에서 사용할 첫 Planet은 다음과 같이 입력합니다.

Planet Radius
    100 km

PlanetX는 이 값을 기준으로 다음과 같은 요소를 계산합니다.

• 행성의 전체 크기
• Section의 행성 표면 배치
• Section Proxy의 곡면 변환
• 행성 비주얼 생성
• Orbit과 Ground 사이의 좌표 변환

따라서 Planet Radius는 단순히 화면에 보이는 행성 Mesh의 크기만 결정하는 값이 아닙니다.

실제 제작을 시작하기 전에 사용할 행성 크기를 먼저 정하는 것을 권장합니다.

#Coordinate Convention

Coordinate Convention은 PlanetX가 행성의 북쪽과 경도 방향을 Unreal Engine World에서 어느 방향으로 해석할지를 정의합니다.

쉽게 말하면 다음과 같은 질문에 대한 규칙입니다.

행성의 북극은 어느 방향인가?
경도 0°는 어느 방향인가?
행성의 동쪽은 어느 방향인가?

처음 PlanetX를 사용하는 경우에는 기본 Coordinate Convention을 그대로 사용하는 것을 권장합니다.

일반적인 PlanetX 작업에서는 이 설정을 직접 변경할 필요가 없습니다.

기존 프로젝트에서 이미 특정한 World 축 규칙을 사용하고 있거나, 다른 좌표 시스템과 PlanetX를 연동해야 하는 경우에만 Coordinate Convention을 변경하세요.

#Planet Asset 생성 완료하기

설정을 확인했다면 Planet Asset을 생성합니다.

처음 테스트에서는 예를 들어 다음과 같은 설정으로 시작할 수 있습니다.

Planet ID
    FirstPlanet

Planet Radius
    100 km

Coordinate Convention
    Default

생성이 완료되면 Content Browser에 새로운 Planet Asset이 나타납니다.

Planet Asset을 더블 클릭하면 Planet Asset Editor가 열립니다.

#Planet Asset Editor 확인하기

Planet Asset Editor는 PlanetX 행성을 제작하고 상태를 확인하는 중심 Editor입니다.

다음은 코드와 동일한 이름의 다섯 도킹 탭입니다. 기본 레이아웃에서는 중앙의 Preview와 오른쪽의 Configuration이 열립니다. 다른 탭이 닫혀 있으면 Window > Planet Asset에서 다시 여세요.

#Overview

현재 Planet Asset의 기본 상태와 주요 작업으로 이동할 수 있는 탭입니다.

처음 Asset을 열었다면 이곳에서 전체 상태를 확인할 수 있습니다.

#Sections

행성에 연결된 Ground 영역인 Section을 확인하고 관리하는 탭입니다.

처음 Planet Asset을 만들었을 때는 Section이 아직 없어도 정상입니다.

첫 Proxy Bake를 실행하면 Ground Level에 대응하는 Section이 생성되어 Planet Asset에 연결됩니다.

#Configuration

행성의 제작 및 동작에 사용되는 추가 설정을 확인하는 탭입니다.

처음 빠른 시작을 진행할 때는 대부분의 값을 기본값으로 유지해도 됩니다.

#Preview

Section Proxy와 나머지 행성 표면을 함께 보면서 행성의 비주얼을 제작하는 탭입니다.

Proxy Bake를 완료한 뒤 본격적으로 사용하게 됩니다.

#Diagnostics

Planet Asset과 연결된 Section, Proxy Bake 결과와 기타 설정에 문제가 없는지 검사하는 탭입니다.

문제가 발생했을 때 가장 먼저 확인하기 좋은 공간입니다.

#처음에는 무엇을 해야 하나요?

Planet Asset을 만든 직후에는 복잡한 설정을 모두 수정할 필요가 없습니다.

우선 다음 세 가지만 확인하세요.

1. Planet ID가 다른 Planet Asset과 중복되지 않는지 확인합니다.
2. Planet Radius가 만들고자 하는 행성 크기에 맞는지 확인합니다.
3. 특별한 좌표 규칙이 필요하지 않다면 Coordinate Convention은 기본값을 유지합니다.

Planet Asset을 저장하면 기본 준비가 완료됩니다.

Section을 직접 추가할 필요는 없습니다.

다음 단계에서 Ground Level을 대상으로 첫 Proxy Bake를 실행하면 PlanetX가 필요한 Section과 연결 정보를 생성합니다.

이 가이드에서는 Orbit World와 Ground World를 서로 다른 Level로 구성하고, PlanetX의 Level Handoff를 사용하여 두 World 사이에서 플레이어의 위치와 이동 상태를 이어가는 방법을 설명합니다.

완료하면 다음과 같은 구성이 만들어집니다.

• Planet Asset 1개
• Orbit 전용 Level 1개
• 실제 플레이에 사용할 Ground Level 1개
• Level Handoff Section 1개
• Bake된 Section Proxy
• Bake된 Runtime Preview World
• Runtime용 행성 비주얼
• Orbit World의 PlanetX Planet Actor
• Environment Manager
• Orbit Transition Endpoint
• Orbit → Ground → Orbit으로 이동하는 Player Actor

이 고급 워크플로를 사용하기 전에 여기서 시작 — Same World 빠른 시작을 완료하세요. 이 문서는 Planet Asset, Proxy Bake, Visual Build, PlanetX Mode와 기본 전환 개념을 이미 이해하고 있다고 가정합니다.

#시작하기 전에

Level Handoff에서는 서로 다른 두 개의 Level이 필요합니다.

이 가이드에서는 다음 이름을 예시로 사용합니다.

L_Orbit
L_Ground

#L_Orbit

우주에서 행성을 보여주고 플레이어가 행성으로 접근하는 Level입니다.

이 Level에는 이후 다음 요소를 배치합니다.

L_Orbit
├─ PlanetX Planet
├─ PlanetX Environment Manager
├─ PlanetX Transition Endpoint
└─ Orbit Player / SpaceShip

#L_Ground

실제로 지표면에서 플레이하는 기존 Unreal Engine Level입니다.

Landscape, Static Mesh, Foliage와 실제 Gameplay Actor 등을 평소 Unreal Engine Level을 제작하듯 구성하면 됩니다.

L_Ground
├─ Landscape
├─ Buildings
├─ Foliage
├─ Gameplay Actors
└─ Ground Player

두 Level은 반드시 저장된 서로 다른 World Asset이어야 합니다.

L_Orbit != L_Ground

Level Handoff는 Orbit World와 Ground World가 같은 Package를 가리키는 구성을 허용하지 않습니다.

#Phase 체크포인트

Level Travel, Pawn 수명과 Possess는 프로젝트가 관리하므로 이 문서는 의도적으로 상세합니다. 34단계를 다섯 Phase로 나누어 진행하고 현재 Phase의 결과를 통과하기 전에는 다음으로 넘어가지 마세요.

26단계는 선택 가능한 Travel Receiver 방식입니다. 첫 테스트에서는 22-25단계의 명시적 완료 방식과 Travel Receiver 중 하나만 선택하고 두 방식을 함께 사용하지 마세요.

#1. Planet Asset 준비

먼저 Planet Asset을 하나 만듭니다.

Planet Asset 생성 과정은 첫 Planet Asset 만들기 문서에서 자세히 설명합니다.

해당 문서를 따라 다음 단계까지만 완료한 뒤 이 페이지로 돌아오세요.

• Planet Asset 생성
• Planet ID 설정
• Planet Radius 설정
• Planet Asset 저장

Section은 아직 직접 만들 필요가 없습니다.

Ground Level에서 첫 Proxy Bake를 실행하면 PlanetX가 필요한 Section과 Level Pair를 자동으로 생성합니다.

#2. Ground Level 열기

먼저 L_Ground를 엽니다.

L_Ground

Proxy Bake는 현재 열려 있는 Ground Level을 Source World로 사용합니다.

따라서 실수로 L_Orbit을 연 상태에서 Bake하지 않도록 주의하세요.

Ground Level 안에 최소한 하나 이상의 Proxy Bake 대상이 있어야 합니다.

예를 들면 다음과 같습니다.

• Landscape
• Static Mesh
• Instanced Static Mesh
• Hierarchical Instanced Static Mesh
• Foliage

작업을 시작하기 전에 Level을 저장하는 것을 권장합니다.

PIE 또는 Simulate가 실행 중이라면 먼저 종료하세요.

#3. Proxy Bake Editor 열기

L_Ground가 열린 상태에서 Unreal Editor의 Tools 메뉴에서 PlanetX 영역을 찾고 Proxy Bake Editor를 선택합니다. 첫 External Section에서는 이 단일 경로만 사용합니다.

Proxy Bake Editor가 열리면 먼저 Target Planet Asset을 확인합니다.

1 Target Planet Asset
└─ Planet Asset

앞 단계에서 만든 Planet Asset을 지정하세요.

첫 Bake 전에는 선택할 기존 Section이 없습니다.

#4. Runtime Role을 External Level로 설정하기

Proxy Bake Editor에서 2 Runtime Role을 펼칩니다.

Presentation을 다음과 같이 설정합니다.

Presentation
└─ External Level

UI에서는 External Level이라고 표시되며, Planet Asset에는 이 Section이 Level Handoff 방식으로 저장됩니다.

External Level은 다음 구조를 의미합니다.

Orbit World
    ↓
PlanetX Runtime Preview
    ↓
게임이 World Travel 실행
    ↓
Ground World

#Ground World 확인

Ground World에는 현재 열려 있는 L_Ground가 자동으로 표시됩니다.

Ground World
    L_Ground

Ground World는 직접 선택하는 값이 아니라 현재 Scan/Bake 대상 Source World를 기준으로 결정됩니다.

#Planet World 지정

External Level을 선택하면 Planet World 항목이 표시됩니다.

여기에 앞에서 준비한 Orbit Level을 지정합니다.

Planet World
    L_Orbit

최종적으로 다음과 같아야 합니다.

Presentation
    External Level

Ground World
    L_Ground

Planet World
    L_Orbit

빠른 시작에서는 Handoff Backend를 별도로 변경할 필요가 없습니다.

현재 기본 계약은 Open Level을 기준으로 저장되지만, 실제 Open Level 실행 자체는 이후 게임 Blueprint에서 수행합니다.

#5. Source Scope 선택하기

3 Source Scope를 펼칩니다.

일반적인 첫 테스트에서는 다음 설정을 권장합니다.

Source Scope
└─ Current Level

각 Source Scope의 의미는 다음과 같습니다.

• Selected Actors — 현재 선택한 Actor만 Bake합니다.
• Current Level — 현재 Ground Level의 Actor를 Bake하며 첫 테스트에 가장 적합합니다.
• Loaded Levels — 현재 로드되어 있는 Streaming Level이나 Level Instance까지 포함합니다.
• Reviewed Set — 이전에 검토한 Source 집합을 다시 사용합니다.

처음에는 Current Level을 사용하는 것이 가장 단순합니다.

Bake Quality 역시 특별한 이유가 없다면 다음 값을 권장합니다.

High (Recommended)

#6. Ground Source 검색하기

설정이 끝났다면 Scan Sources를 클릭합니다.

단축키는 F5입니다.

Scan Sources

PlanetX가 현재 Ground Level을 조사하고 Proxy로 변환할 Source를 찾습니다.

Scan이 끝나면 Source Review에 발견된 항목이 나타납니다.

#Source Review 확인

처음에는 모든 항목을 수정할 필요는 없습니다.

다음 항목이 있는지만 확인하세요.

• 사용하려던 Actor가 검색되지 않음
• Manual Review 상태의 Source가 있음
• Unsupported Source가 있음
• Bake에 사용되는 Source가 하나도 없음
• 의도하지 않은 Actor가 Bake 대상으로 들어감

지원되는 Landscape, Static Mesh, ISM/HISM, Foliage 등은 일반적으로 자동으로 분류됩니다.

Source의 Use 또는 Role을 직접 변경했다면 반드시 다음 버튼을 클릭하세요.

Apply Source Changes

변경하지 않았다면 별도로 적용할 필요는 없습니다.

#7. Proxy Bake 실행하기

Source Review를 마쳤다면 다음 버튼을 클릭합니다.

BAKE IN EDITOR

단축키는 Ctrl+B입니다.

Bake에서는 Ground Level의 Geometry뿐 아니라 Level Handoff에서 사용할 여러 Runtime 데이터도 함께 생성됩니다.

처음 Bake하는 Planet Asset이라면 이 과정에서 다음 항목이 자동으로 만들어집니다.

Planet Asset
├─ Section
├─ Level Pair
├─ Proxy Bake Data
└─ Runtime Preview World

#Runtime Preview World란?

External Level에서는 실제 L_Ground를 Orbit World에 통째로 로드하지 않습니다.

대신 Proxy Bake가 시각 표현만 포함하는 Runtime Preview World를 별도로 생성합니다.

이 Preview는 행성에 가까이 접근할 때 Ground와 비슷한 모습을 보여주기 위한 것입니다.

다음과 같은 실제 Gameplay 기능을 복제하는 Level은 아닙니다.

• GameMode
• PlayerStart
• Pawn
• Controller
• Gameplay Actor Logic
• Collision Gameplay
• Navigation

즉 다음 두 World는 서로 다른 역할을 가집니다.

Runtime Preview World
    = 전환 중 보여주기 위한 시각 표현

L_Ground
    = 실제 Gameplay World

이 차이는 Level Handoff에서 매우 중요합니다.

#8. Bake 결과 확인하기

Bake가 완료되면 Planet Asset Editor로 돌아갑니다.

Sections에서 새 Section을 선택하세요.

빠른 시작에서는 대략 다음 상태를 확인하면 됩니다.

Proxy Bake Editor에서는 Open Results 또는 Ctrl+Shift+O를 사용하여 최신 Bake 결과를 Content Browser에서 확인할 수도 있습니다.

이미 동일한 Section에 Bake 결과가 존재한다면 버튼이 다음과 같이 표시될 수 있습니다.

REBUILD IN EDITOR

이는 기존 Section을 새 Ground Source 결과로 다시 Bake하는 동작입니다.

#9. 행성에서 Section 위치 확인하기

Planet Asset Editor의 Preview를 엽니다.

Level Handoff Section은 Same World Section과 달리 행성 표면의 원하는 위치에 배치할 수 있습니다.

처음 테스트에서는 자동으로 만들어진 위치를 그대로 사용해도 됩니다.

Preview에서 다음 항목을 확인하세요.

• Section Proxy가 행성 표면에 나타남
• Proxy의 방향이 정상임
• 다른 Section과 겹치지 않음
• 행성 표면과 심각한 Gap이 없음

여러 Ground Level을 하나의 Planet Asset에 연결하는 경우에는 각각 별도의 External Level Section으로 구성할 수 있습니다.

Planet
├─ Section_A → Ground_A
├─ Section_B → Ground_B
└─ Section_C → Ground_C

이번 빠른 시작에서는 Section 하나만 사용합니다.

#10. 행성 비주얼 만들기

Planet Asset Editor > Preview에서 행성의 기본 표면을 설정합니다.

Completion Material에 행성에서 사용할 Material을 지정하세요.

Preview
└─ Basic
   └─ Planet
      └─ Completion Material

처음에는 Terrain, Padding 등의 세부 설정은 기본값으로 두어도 됩니다.

Preview에서 다음 정도만 확인하면 충분합니다.

• 행성 전체 표면이 정상적으로 표시됨
• Bake한 Section이 행성 위에 표시됨
• Section 주변에 큰 빈 공간이 없음
• Geometry가 심하게 뒤집혀 있지 않음

문제가 없다면 Planet Visual Build에서 다음 버튼을 클릭합니다.

Apply & Build

PlanetX가 Preview 설정을 Planet Asset에 적용하고 Runtime에서 사용할 최종 행성 Visual을 생성합니다.

Build가 성공했다면 Planet Asset을 저장합니다.

#11. Orbit World에 Planet Actor 배치하기

이제 L_Orbit을 엽니다.

L_Orbit

Place Actors에서 다음 Actor를 검색합니다.

PlanetX Planet

Level에 PlanetX Planet Actor를 하나 배치합니다.

Actor를 선택한 뒤 Planet Component에서 다음 값을 설정합니다.

Planet Asset
    → 앞에서 만든 Planet Asset

Auto Register Runtime
    Enabled

하나의 Planet Actor만 사용하는 빠른 시작에서는 별도의 Planet Binding ID를 직접 지정할 필요는 없습니다.

#12. Planet Actor 정렬하기

Level Editor에서 PlanetX Mode를 엽니다.

Scene에서 방금 배치한 Planet Actor가 Active Planet인지 확인하세요.

Planet Asset에 Same World Section이 하나도 없더라도 PlanetX는 첫 번째 유효한 External Section의 Ground Sync Mapping을 기준으로 정렬 Anchor를 결정할 수 있습니다.

따라서 Level Handoff만 사용하는 Planet도 별도의 Same World Section을 만들 필요가 없습니다.

PlanetX Mode의 Align 버튼을 실행합니다.

Align은 Planet Actor의 Rotation이나 Scale을 임의로 변경하지 않고 필요한 위치 보정을 적용합니다.

완료 후 Validate에서 다음과 같은 정렬 오류가 없어야 합니다.

Planet Actor location is not aligned
to the canonical Section's baked Ground Sync Mapping.

#13. Environment Manager 추가하기

PlanetX Mode에서 Environment Palette를 엽니다.

현재 Planet에 Environment Manager가 없다면 Add Manager를 클릭합니다.

Environment
└─ Add Manager

PlanetX가 현재 활성 Planet에 연결된 Environment Manager를 생성합니다.

PlanetX는 개별 대기나 구름 기능을 사용하지 않더라도 Environment Manager를 Planet의 Runtime infrastructure로 사용하므로 빠른 시작에서도 하나를 배치합니다.

한 Planet에는 하나의 Environment Manager만 유지하세요.

#14. Orbit Transition Endpoint 추가하기

PlanetX Mode에서 Transition Palette를 엽니다.

현재 Section에 Endpoint가 없다면 다음 상태가 표시됩니다.

No Transition Endpoint for this Level.

Add Endpoint를 클릭합니다.

Add Endpoint

현재 L_Orbit은 Level Pair의 Planet World이므로 생성되는 Endpoint는 자동으로 다음 역할을 가집니다.

Endpoint Role
    Orbit

PlanetX는 다음 값도 현재 Section에 맞게 연결합니다.

• Planet ID
• Section ID
• Level Pair ID
• Planet Actor
• Planet Asset
• Environment Manager

#Transition Cylinder

기본 설정은 그대로 유지하는 것을 권장합니다.

Auto Size Transition Cylinder To Section Bounds
    Enabled

PlanetX는 Section의 크기를 기준으로 Transition 영역을 계산합니다.

Viewport에서 Cylinder Visualization을 통해 영역을 확인할 수 있습니다.

이 영역은 플레이어의 Viewpoint가 행성의 Section으로 접근하는 동안 다음 상태를 계산하는 데 사용됩니다.

Orbit
   ↓
Transition
   ↓
Ground Presentation

External Level에서는 마지막 단계에서 실제 L_Ground가 Orbit World에 나타나는 것이 아니라 Bake된 Runtime Preview World가 Ground Presentation 역할을 합니다.

실제 L_Ground로 넘어가는 것은 이후 별도의 Level Handoff 호출입니다.

#15. Orbit Player를 PlanetX에 연결하기

Orbit에서 사용할 Pawn 또는 Character Blueprint를 엽니다.

이 문서에서는 다음 이름을 예로 사용합니다.

BP_OrbitPlayer

다음 Component를 추가하세요.

BP_OrbitPlayer
├─ Camera Component
├─ PlanetX Coordinate Component
└─ PlanetX Viewpoint Component

#Coordinate Component

다음과 같이 설정합니다.

Auto Register Runtime
    Enabled

Representation Domain
    Orbit

Reference Planet Actor
    → L_Orbit의 PlanetX Planet

Reference Section Id
    → 앞에서 Bake한 Section

Level에 미리 배치된 Pawn이라면 Details에서 Planet Actor를 직접 지정할 수 있습니다.

런타임에 Spawn되는 Pawn이라면 BeginPlay에서 Planet Actor 참조를 설정한 뒤 Refresh Coordinate Snapshot을 호출하는 방식을 사용할 수 있습니다.

#Viewpoint Component

다음 기본 설정을 유지합니다.

Auto Register Runtime
    Enabled

Can Drive Transition State
    Enabled

PlayerController가 실제로 BP_OrbitPlayer를 ViewTarget으로 사용하고 있는지도 확인하세요.

또한 ViewTarget에 활성 Camera Component가 있어야 합니다.

이 Viewpoint를 기준으로 PlanetX가 Transition Alpha와 Runtime Preview의 Load/Visibility를 계산합니다.

#16. Ground Player 준비하기

이제 L_Ground에서 사용할 Pawn 또는 Character를 준비합니다.

예를 들어 다음과 같습니다.

BP_GroundPlayer

Level Handoff의 위치 복원 자체만을 위해 Ground World에 Planet Actor를 배치할 필요는 없습니다.

PlanetX는 Proxy Bake에서 저장한 Ground Sync Mapping을 사용하여 Orbit의 Section 좌표를 Ground World 좌표로 변환할 수 있습니다.

따라서 가장 단순한 구성은 다음과 같습니다.

L_Ground
└─ BP_GroundPlayer

다만 Ground에서도 다음 기능을 계속 사용할 예정이라면 Ground World에 별도의 Planet Actor 구성이 필요할 수 있습니다.

• PlanetX Native Movement
• PlanetX 방사형 중력
• PlanetX Coordinate Query
• Ground 측 PlanetX Environment
• Ground Transition Endpoint

이 경우에도 Ground World의 Planet Actor는 Orbit World의 Actor와 서로 다른 World 인스턴스입니다.

#17. Travel 정보를 보관할 GameInstance 준비하기

Open Level을 실행하면 기존 World와 그 안의 Actor들은 사라집니다.

따라서 Level Handoff Ticket은 Level Actor 안에만 저장하면 안 됩니다.

Ticket은 다음 World에서도 읽을 수 있는 곳에 저장해야 합니다.

가장 이해하기 쉬운 방법은 프로젝트의 GameInstance를 사용하는 것입니다.

이미 커스텀 GameInstance를 사용하고 있다면 기존 GameInstance에 아래 변수를 추가하면 됩니다.

없다면 Blueprint GameInstance를 하나 만듭니다.

예:

BP_PlanetXGameInstance

다음 변수를 추가합니다.

Pending PlanetX Ticket
    Type = PlanetX Level Handoff Ticket

Active PlanetX Journey Id
    Type = Guid

Has Pending PlanetX Ticket
    Type = Boolean

Project Settings에서 이 GameInstance를 사용하도록 설정합니다.

Project Settings
└─ Maps & Modes
   └─ Game Instance Class
      └─ BP_PlanetXGameInstance

#18. Orbit에서 착륙 지점 Query하기

이제 BP_OrbitPlayer에 착륙 입력을 하나 만듭니다.

예를 들어 Enhanced Input의 다음 Action을 사용한다고 가정합니다.

IA_Land

Started 이벤트에서 먼저 Planet 표면을 Query합니다.

Blueprint 흐름은 다음과 같습니다.

IA_Land (Started)
    ↓
Get Game Instance Subsystem
    Class = PlanetXSubsystem
    ↓
Make PlanetXSurfaceQueryInput
    ↓
Query Surface At World Ray Detailed

#Surface Query Input

다음과 같이 연결합니다.

Ray Origin World
    = 현재 Camera의 World Location

Ray Direction World
    = 현재 Camera의 Forward Vector

Max Distance Cm
    = 착륙 지점을 검색하기에 충분히 큰 값

Planet이 여러 개라면 숨겨진 핀을 표시하여 다음 값도 지정하는 것을 권장합니다.

Preferred Planet Id
Preferred Planet Binding Id

간단한 하나의 Planet 테스트에서는 생략할 수 있습니다.

#Query 결과 확인

Query Surface At World Ray Detailed의 반환 Status를 확인합니다.

Switch on EPlanetXSurfaceQueryStatus

다음 상태에서만 계속 진행합니다.

Status == Hit

그 다음 Surface Result를 Break하고 다음 값을 확인합니다.

bCanEnterGround == true

최종 흐름은 다음과 같습니다.

Query Surface At World Ray Detailed
    ↓
Status == Hit?
    ↓ yes
Surface Result.bCanEnterGround?
    ↓ true
Level Handoff 준비

Hit이지만 bCanEnterGround == false라면 행성 표면은 찾았지만 해당 위치가 Ground 진입 가능한 Section이 아닙니다.

#19. Orbit → Ground Handoff 준비하기

Surface Query가 성공했다면 같은 PlanetXSubsystem에서 다음 노드를 호출합니다.

Begin Level Handoff

연결은 다음과 같습니다.

Begin Level Handoff

Source Actor
    = Self

Surface Query
    = 앞에서 얻은 Surface Query Result

Begin Level Handoff가 성공하면 PlanetX는 현재 이동의 다음 정보를 보관합니다.

• Planet
• Section
• Level Pair
• 현재 Actor 위치
• Section을 기준으로 한 Actor 회전
• Ground 착륙 위치
• Control Rotation
• 가능한 경우 현재 이동 속도
• Orbit 복귀에 필요한 위치 정보
• Target Ground World

하지만 아직 Level은 변경되지 않습니다.

#20. Handoff Ticket 저장하기

Begin Level Handoff의 Return Value를 Branch로 확인합니다.

Begin Level Handoff
    ↓
Branch

false이면 Out Result.Error를 확인하고 Open Level을 실행하지 마세요.

true라면 Out Ticket 전체를 앞에서 만든 GameInstance에 저장합니다.

Get Game Instance
    ↓
Cast to BP_PlanetXGameInstance
    ↓
Set Pending PlanetX Ticket
    = Out Ticket

Set Has Pending PlanetX Ticket
    = true

Ticket에서 필요한 값만 따로 복사하지 말고 구조체 전체를 저장하는 것을 권장합니다.

Ticket에는 해당 Travel을 식별하는 정보와 목적 World가 함께 들어 있습니다.

#21. 실제 Ground Level 열기

저장한 Out Ticket을 Break합니다.

다음 값을 찾습니다.

Target World

빠른 시작에서는 이 값이 다음 World를 가리켜야 합니다.

L_Ground

게임 Blueprint에서 **Open Level (by Object Reference)**를 호출하고 Ticket의 Target World를 전달합니다.

전체 흐름은 다음과 같습니다.

IA_Land
    ↓
Surface Query
    ↓
Begin Level Handoff
    ↓
Success?
    ↓
Ticket을 GameInstance에 저장
    ↓
Break PlanetX Level Handoff Ticket
    ↓
Target World
    ↓
Open Level

빠른 시작에서는 일반적인 Open Level 방식만 사용합니다.

#22. Ground World에서 Player를 먼저 Spawn하고 Possess하기

L_Ground가 열리면 프로젝트의 기존 GameMode가 Ground Player를 생성하도록 구성합니다.

예:

Default Pawn Class
    BP_GroundPlayer

PlanetX는 다음 작업을 대신하지 않습니다.

Spawn Pawn
Possess Pawn
PlayerStart 선택
GameMode 선택

따라서 Ground Level을 PlanetX 없이 실행했을 때도 BP_GroundPlayer가 정상적으로 생성되고 조작 가능한 상태여야 합니다.

#23. Ground Player에 저장한 Ticket 적용하기

BP_GroundPlayer에서 Possess가 완료된 시점에 저장한 Ticket을 적용합니다.

Blueprint에서는 Pawn의 Event Possessed와 같은 시점을 사용할 수 있습니다.

먼저 GameInstance에서 Ticket을 읽습니다.

Event Possessed
    ↓
Get Game Instance
    ↓
Cast to BP_PlanetXGameInstance
    ↓
Has Pending PlanetX Ticket?

true인 경우 다음 노드를 호출합니다.

Get Game Instance Subsystem
    Class = PlanetXSubsystem
    ↓
Complete Level Handoff

연결은 다음과 같습니다.

Ticket
    = GameInstance.Pending PlanetX Ticket

Target Actor
    = Self

Apply Control Rotation
    = true

최종 흐름은 다음과 같습니다.

Event Possessed
    ↓
Has Pending PlanetX Ticket?
    ↓ true
Complete Level Handoff
    Ticket       = 저장한 Ticket
    Target Actor = Self

성공하면 PlanetX가 현재 Ground Pawn에 저장된 착륙 상태를 적용합니다.

#24. Ground 도착 결과 저장하기

Complete Level Handoff의 Return Value를 확인합니다.

성공한 경우 Out Result.JourneyId를 GameInstance에 저장하세요.

Complete Level Handoff
    ↓
Success?
    ↓ true
Break PlanetX Level Handoff Result
    ↓
Journey Id
    ↓
GameInstance.Active PlanetX Journey Id

그리고 다음 값을 변경합니다.

Has Pending PlanetX Ticket
    = false

이제 Orbit → Ground 이동이 완료된 상태입니다.

PlanetX 내부 Journey 상태는 다음과 같이 됩니다.

Ground Active

Journey Id는 나중에 Ground에서 Orbit으로 돌아갈 때 사용하므로 잃어버리지 마세요.

#25. Ground 도착 위치 확인하기

정상적으로 Handoff가 완료되었다면 Ground Pawn은 단순히 PlayerStart 위치에 머무르지 않고, Orbit에서 선택한 Section 위치에 대응하는 Ground 위치로 이동합니다.

PlanetX는 대략 다음 관계를 사용합니다.

Orbit에서 캡처한 Section Local 위치
        ↓
Ground Sync Mapping
        ↓
L_Ground의 World 위치

따라서 다음 항목을 확인하세요.

• 예상한 Ground 영역에 도착함
• Actor가 엉뚱한 방향을 바라보지 않음
• Camera 방향이 크게 튀지 않음
• 이동 속도가 의도대로 이어짐
• 기존 Ground Gameplay가 정상 동작함

Ground World에 Planet Actor가 없어도 이 착륙 위치 복원은 가능합니다.

#26. 더 간단한 도착 방식: Travel Receiver

현재 World에 일치하는 Pending Travel이 항상 정확히 하나라는 것이 보장된다면 저장한 Ticket을 직접 적용하는 대신 다음 Component를 사용할 수도 있습니다.

PlanetX Travel Receiver Component

Ground Pawn에 Component를 추가하고 다음 값을 유지합니다.

Auto Resume Pending Travel
    Enabled

Apply Control Rotation
    Enabled

Travel Receiver는 World가 열린 직후 PlanetX Runtime 준비가 아직 끝나지 않은 경우 일정 시간 동안 자동으로 재시도합니다.

기본 Retry Timeout은 다음과 같습니다.

15 seconds

성공하면 다음 Event가 호출됩니다.

On Travel Resumed

최종 실패하면 다음 Event가 호출됩니다.

On Travel Resume Failed

다만 Receiver는 현재 World와 일치하는 Pending이 정확히 하나일 때만 자동으로 선택합니다.

여러 플레이어 또는 여러 Travel을 동시에 처리할 가능성이 있다면 앞에서 설명한 정확한 Ticket + Complete Level Handoff 방식을 권장합니다.

#27. Ground → Orbit 복귀 준비하기

이번에는 Ground Player에서 Orbit으로 돌아가는 입력을 만듭니다.

예:

IA_ReturnOrbit

GameInstance에서 앞에서 저장한 Journey ID를 가져옵니다.

IA_ReturnOrbit (Started)
    ↓
Get Game Instance
    ↓
Cast to BP_PlanetXGameInstance
    ↓
Get Active PlanetX Journey Id

그 다음 PlanetXSubsystem의 다음 노드를 호출합니다.

Begin Return Level Handoff

연결은 다음과 같습니다.

Journey Id
    = Active PlanetX Journey Id

Source Actor
    = Self

Resume Alpha
    = 0

Resume Alpha는 빠른 시작에서는 기본값 0을 사용하면 됩니다.

성공하면 새로운 Return Ticket이 생성됩니다.

이 Ticket은 Orbit → Ground 때 사용했던 Ticket과 다른 Ticket입니다.

Orbit → Ground Ticket
    !=
Ground → Orbit Ticket

#28. Return Ticket 저장하고 Orbit World 열기

Begin Return Level Handoff가 성공하면 Return Ticket을 GameInstance의 동일한 Pending Ticket 변수에 저장합니다.

Pending PlanetX Ticket
    = Return Ticket

Has Pending PlanetX Ticket
    = true

Return Ticket을 Break하면 Target World가 다음 Level을 가리켜야 합니다.

L_Orbit

그 값을 이용해 다시 Open Level을 실행합니다.

Begin Return Level Handoff
    ↓
Success?
    ↓
Return Ticket 저장
    ↓
Break Ticket
    ↓
Target World = L_Orbit
    ↓
Open Level

#29. Orbit World에서 복귀 상태 적용하기

L_Orbit이 다시 열리면 BP_OrbitPlayer가 생성되고 Possess되어야 합니다.

이때 Ground에서 사용한 것과 같은 방식으로 GameInstance의 Pending Ticket을 읽어 Complete Level Handoff를 호출할 수 있습니다.

BP_OrbitPlayer
Event Possessed
    ↓
GameInstance.Has Pending PlanetX Ticket?
    ↓ true
Complete Level Handoff
    Ticket       = GameInstance.Pending PlanetX Ticket
    Target Actor = Self

성공하면 다음 값을 정리합니다.

Has Pending PlanetX Ticket
    = false

Orbit 복귀가 완료되면 해당 Journey도 완료됩니다.

정상적인 전체 Journey는 다음 순서입니다.

Orbit
    ↓
Pending Orbit To Ground
    ↓
Ground Active
    ↓
Pending Ground To Orbit
    ↓
Completed

#30. Orbit 도착 시 Runtime 등록 순서 때문에 실패한다면

Orbit World가 다시 열린 직후에는 Planet Actor가 PlanetX Runtime에 등록되는 시점과 Player가 생성되는 시점이 완전히 같지 않을 수 있습니다.

이 경우 수동 Complete Level Handoff가 너무 일찍 호출되면 일시적으로 복원이 실패할 수 있습니다.

단일 Player 빠른 시작에서는 Orbit Player에 PlanetX Travel Receiver Component를 추가하여 복귀 적용을 맡기는 방법도 사용할 수 있습니다.

BP_OrbitPlayer
└─ PlanetX Travel Receiver Component

Auto Resume Pending Travel
    Enabled

Apply Control Rotation
    Enabled

Travel Receiver는 Planet Runtime 등록이 아직 끝나지 않은 경우 제한된 시간 동안 다시 시도합니다.

단, 이 방법을 사용한다면 같은 도착 과정에서 수동 Complete Level Handoff를 동시에 호출하지 마세요.

#31. Runtime Preview 동작 확인하기

실제 Ground Level로 Travel하기 전에 Orbit에서 Planet에 접근해 보세요.

Viewpoint가 Transition Endpoint 영역에 들어오면 External Level Section의 Runtime Preview World가 필요에 따라 로드됩니다.

정상적인 표현 흐름은 다음과 같습니다.

멀리 있음
    Section Proxy

        ↓ 접근

Transition
    Proxy / Morph / Runtime Preview 전환

        ↓

Ground Presentation
    Runtime Preview World

이 상태에서도 아직 실제 L_Ground로 World Travel한 것은 아닙니다.

즉 다음 두 과정은 독립적입니다.

[시각적 전환]
Orbit World 안에서 Runtime Preview 표시

[Gameplay Travel]
Begin Level Handoff
→ 게임의 Open Level
→ L_Ground

이 구분을 이해하면 Level Handoff를 디버깅하기 훨씬 쉽습니다.

#32. 실행 전 Validate하기

Orbit World로 돌아가 PlanetX Mode의 Validate Palette를 엽니다.

Planet Asset Editor의 Diagnostics에서도 검증할 수 있습니다.

빠른 시작에서는 최소한 다음 항목에 Error가 없어야 합니다.

• Planet Actor에 올바른 Planet Asset이 지정됨
• External Level Section이 유효함
• Orbit World와 Ground World가 서로 다름
• Ground Sync Mapping이 유효함
• Proxy Bake Data가 연결됨
• Runtime Preview World가 연결됨
• Runtime Preview Bake revision이 최신 상태임
• Runtime Preview에 renderable content가 존재함
• Orbit Transition Endpoint가 Section에 정확히 하나 존재함
• Environment Manager가 정확히 하나 존재함
• Planet Actor가 canonical External Section mapping에 맞게 Align되어 있음

Validation Error가 있다면 PIE를 실행하기 전에 해결하세요.

#33. 전체 흐름 테스트하기

이제 L_Orbit에서 PIE를 시작합니다.

#1단계: Orbit 확인

먼저 다음을 확인합니다.

• 행성이 정상적으로 표시됨
• Section Proxy가 보임
• Player를 조작할 수 있음
• PlanetX Runtime에 Planet이 등록됨

#2단계: 행성에 접근

Section 방향으로 접근하면서 다음을 확인합니다.

Orbit
→ Transition
→ Ground Presentation

Runtime Preview가 필요한 시점에 정상적으로 나타나는지 확인합니다.

#3단계: 착륙 입력

Section을 향해 카메라를 두고 IA_Land를 실행합니다.

다음 순서가 발생해야 합니다.

Surface Query Hit
→ Begin Level Handoff 성공
→ Ticket 저장
→ L_Ground Open

#4단계: Ground 도착

Ground Player가 Spawn되고 Possess된 후 다음이 발생해야 합니다.

Complete Level Handoff
→ 저장된 Ground Pose 적용
→ Journey = Ground Active

#5단계: Orbit 복귀

IA_ReturnOrbit을 실행합니다.

Begin Return Level Handoff
→ Return Ticket 생성
→ L_Orbit Open
→ Return Ticket 적용
→ Journey Completed

#34. PlanetX Runtime Palette에서 확인하기

PIE 중 PlanetX Mode의 Runtime Palette를 사용하면 현재 Runtime 상태를 확인하는 데 도움이 됩니다.

Orbit World에서는 특히 다음 항목을 확인하세요.

• Planet 등록 상태
• 현재 Transition State
• Transition Alpha
• Section Context
• Runtime Preview 상태
• Ground Presentation 준비 상태

Level Handoff 문제를 찾을 때는 먼저 다음 둘을 구분하세요.

Runtime Preview 문제인가?

또는

실제 World Handoff 문제인가?

Runtime Preview가 정상인데 Open Level 후 위치가 틀리다면 Handoff 쪽 문제입니다.

반대로 Travel하지 않아도 행성 접근 과정에서 Preview가 나타나지 않는다면 Transition/Preview 설정을 먼저 확인해야 합니다.

#Level Handoff가 동작하지 않는다면

다음 항목을 순서대로 확인하세요.

1. Proxy Bake의 Presentation이 External Level인지 확인합니다.

2. Ground World와 Planet World가 서로 다른 Level인지 확인합니다.

3. Planet World가 실제 L_Orbit을 가리키는지 확인합니다.

4. Proxy Bake를 최신 상태로 다시 실행했는지 확인합니다.

5. Planet Asset의 해당 Section에 Runtime Preview World가 연결되어 있는지 확인합니다.

6. Orbit World의 Planet Actor에 올바른 Planet Asset이 지정되어 있는지 확인합니다.

7. PlanetX Mode에서 Align을 실행했는지 확인합니다.

8. Orbit Section에 정확히 하나의 Orbit Transition Endpoint가 있는지 확인합니다.

9. Environment Manager가 정확히 하나 존재하는지 확인합니다.

10. Player ViewTarget에 활성 Camera와 PlanetX Viewpoint Component가 있는지 확인합니다.

11. Surface Query 결과가 실제로 Hit인지 확인합니다.

12. Surface Result.bCanEnterGround가 true인지 확인합니다.

13. Begin Level Handoff가 true를 반환하는지 확인합니다.

14. 실패한다면 Out Result.Error를 확인합니다.

15. Begin Level Handoff 이후 Ticket 전체를 World Travel을 넘어서 보관하고 있는지 확인합니다.

16. 실제 Open Level 대상이 Ticket.TargetWorld와 같은지 확인합니다.

17. Ground Pawn이 Spawn된 뒤 Possess가 완료된 상태에서 Complete를 실행하는지 확인합니다.

18. 여러 Pending Travel이 있을 수 있다면 Resume Pending Travel 대신 저장한 정확한 Ticket으로 Complete Level Handoff를 호출합니다.

19. Ground → Orbit 복귀 전에 Ground 도착 결과의 JourneyId를 저장했는지 확인합니다.

20. Return용으로 Return To Orbit Same World를 호출하고 있지 않은지 확인합니다. External Level에서는 Begin Return Level Handoff를 사용해야 합니다.

#자주 발생하는 오류

#Ground World에서도 PlanetX 기능을 사용하려면

기본 Level Handoff에서는 Ground pose 복원만을 위해 Ground World에 Planet Actor가 필요하지 않습니다.

하지만 Ground에서도 PlanetX 기능을 계속 사용할 계획이라면 추가 구성이 필요할 수 있습니다.

예를 들어 다음 기능입니다.

• PlanetX Native Movement
• 행성 중심 방향 중력
• Surface Frame 이동
• PlanetX Coordinate Query
• Ground 환경 전환

이 경우 L_Ground에도 PlanetX Planet Actor를 배치하고 같은 Planet Asset을 지정합니다.

Ground Player의 Coordinate Component에는 해당 Ground World의 Planet Actor를 참조하도록 설정하세요.

또한 Planet Component의 Gravity Settings는 Planet Asset이 아니라 각 Planet Actor가 소유하므로 Ground World에서 PlanetX 중력을 사용할 경우 Ground 쪽 Planet Actor의 중력 설정도 별도로 구성해야 합니다.

이 추가 구성은 기본적인 Level Handoff pose 복원을 위한 필수 조건은 아닙니다.

#완료

여기까지 정상적으로 동작했다면 PlanetX의 기본 Level Handoff 흐름을 구성한 것입니다.

전체 제작 흐름은 다음과 같습니다.

Planet Asset
    ↓
L_Ground
    ↓
Proxy Bake
    │
    ├─ Section
    ├─ Level Pair
    ├─ Section Proxy
    └─ Runtime Preview World
    ↓
Planet Visual Build
    ↓
L_Orbit
    ↓
PlanetX Planet
    ↓
Align
    ↓
Environment Manager
    ↓
Orbit Transition Endpoint
    ↓
Orbit Player + Viewpoint

실제 Runtime Travel은 다음과 같습니다.

L_Orbit
    ↓
Surface Query
    ↓
Begin Level Handoff
    ↓
Ticket 저장
    ↓
게임이 Open Level
    ↓
L_Ground
    ↓
Ground Pawn Spawn / Possess
    ↓
Complete Level Handoff
    ↓
Ground Active
    ↓
Begin Return Level Handoff
    ↓
Return Ticket 저장
    ↓
게임이 Open Level
    ↓
L_Orbit
    ↓
Return Ticket 적용
    ↓
Journey Completed

그리고 Orbit World에서 Ground에 접근할 때 보이는 시각적 전환은 실제 World Travel과 별도로 다음과 같이 동작합니다.

Section Proxy
    ↓
Transition
    ↓
Runtime Preview World

Runtime Preview World는 실제 Ground Gameplay Level이 아닙니다.

PlanetX는 Orbit과 Ground 사이에서 필요한 좌표와 상태를 연결하고, 실제 World Travel과 Pawn 생명주기는 기존 Unreal Engine 프로젝트의 정책을 그대로 사용할 수 있도록 분리합니다.

UPlanetXPlanetAsset은 행성의 물리·좌표·Section·Level Pair·Proxy Bake·생성 비주얼·환경 제작 상태를 연결하는 Primary Data Asset입니다.

#세 가지 핵심 ID

Level Pair ID는 Section과 Orbit/Ground/Runtime Preview World 묶음을 찾는 키입니다. Journey ID와 Capture ID는 Travel 한 번의 수명 주기를 식별합니다.

#Asset이 소유하는 계약

Planet Asset에는 Radius, Coordinate Convention, Sections, Level Pairs, Completion/Padding 설정, Environment 설정, Surface Preset, Proxy Bake 링크와 revision 상태가 들어 있습니다. 생성된 Payload나 Material은 Asset이 직접 제작하지 않고 Editor workflow가 게시하고 링크합니다.

IsProxyBakeStale, IsVisualBuildStale, IsVisualPreviewStale은 현재 authoring revision과 마지막 성공 결과를 비교합니다. stale 결과는 자동 삭제 신호가 아니라 재검증·재생성이 필요하다는 신호입니다.

#여러 World와 여러 인스턴스

같은 Planet Asset이 Orbit World와 Ground World에 사용될 수 있습니다. 동일 Planet ID의 Planet Actor가 한 World에 여러 개면 자동 선택은 모호해질 수 있으므로 API의 AdvancedDisplay에 있는 Planet Binding ID를 전달하세요.

#변경 원칙

ID 변경은 저장 좌표, Level Pair, Bake 링크, Travel route에 영향을 줍니다. 표시 이름 변경과 달리 migration으로 취급하고 Full Validate와 재 Bake를 수행하세요.

Section은 행성 표면의 지리적 구역, 로컬 Frame, 시각 프록시, 전환 경계를 묶는 단위입니다. Level Pair는 해당 Section이 어느 World에서 어떻게 표현되는지 정의합니다.

#Section placement

FPlanetXSectionPlacement은 표면상의 위치, tangent 방향, 크기와 배치 Transform을 결정합니다. Canonical north-pole anchor로 선택된 Same World Section은 자동 배치가 제한될 수 있습니다. 편집기는 Visual, coordinate-containment, transition rectangle을 하나의 bounds contract로 검증합니다.

Section ID를 명시하면 저장, Capture, Sequencer가 같은 Frame을 재현합니다. ID가 None일 때 자동 Section resolve는 현재 Planet Local 위치와 Asset 배열 순서를 사용하므로 영속 데이터에는 권장하지 않습니다.

#Runtime role

• Same World: Orbit World와 Ground World package가 같아야 합니다.
• External Level / Level Handoff: Orbit과 Ground가 서로 달라야 하고 Runtime Preview World가 필요합니다.

Level Handoff Section은 GroundSyncMapping과 유효한 TransitionPolicy를 가져야 합니다. Proxy Bake가 성공하면 SourceRef, BakeData, mapping, preview와 transition resource 링크가 갱신됩니다.

#Ground proxy visibility

Section별 Ground proxy visibility는 Orbit, Ground, transition 시 원본 Actor와 프록시 중 무엇이 보일지 결정합니다. PlanetX Mode의 Planet/Compare/Level view는 runtime 계약을 변경하지 않고 편집 중 표현만 비교합니다.

#검증 체크리스트

1. Section ID와 Level Pair ID가 비어 있지 않은가?
2. Runtime role과 World package 관계가 맞는가?
3. GroundSyncMapping이 유효한가?
4. Proxy Bake와 생성 비주얼이 현재 revision인가?
5. transition bounds가 containment bounds 안에 있는가?

PlanetX는 World 좌표 하나에 모든 의미를 넣지 않고 목적이 다른 좌표 Frame을 명시적으로 구분합니다.

#좌표 종류

FPlanetXCoordinateConvention은 North Pole과 경도 축을 정의합니다. Geo의 altitude는 Planet Radius를 기준으로 한 cm 값입니다.

#Coordinate Component의 권위

UPlanetXCoordinateComponent.CoordinateMode이 Unreal이면 Owner World Transform이 원본이고 PlanetX snapshot은 캡처됩니다. PlanetX 모드에서는 FPlanetXTransform이 원본이며 Apply가 World Transform을 만듭니다. Capture와 Apply는 명시적 작업입니다.

Reference resolve 우선순위는 Reference Planet Actor, Reference Planet ID 순입니다. Section ID를 지정하면 해당 Frame이 authoritative합니다.

#벡터 변환

위치는 점 변환이고 이동 입력은 벡터 변환입니다. ConvertCoordinateVectorToWorld에서 Surface Frame을 사용하면 X/Y/Z를 East/North/Up으로 해석할 수 있습니다. 지표 이동은 bProjectToSurfaceTangent를 켜 Up 성분을 제거할 수 있습니다.

#실패 처리

Transform과 Query 함수는 bool만 보지 말고 FPlanetXTransformResolveResult 또는 상세 Status를 확인하세요. 잘못된 버전, 미등록 Planet, 모호한 Binding, 지원하지 않는 Planet scale, 유효하지 않은 Section이 구분됩니다.

PlanetX는 Actor가 어느 표현에 속하는지와 World Partition에서 어떻게 로드되는지를 별도 정책으로 취급합니다.

#Representation Domain

EPlanetXRepresentationDomain은 Actor의 기본 표현 영역을 나타냅니다.

• Ground Actor는 원본 Level 표현에 속합니다.
• Orbit Actor는 Planet/Compare 편집 view와 Orbit/Transition 런타임 표현에 속합니다.
• 전역 presentation Actor는 별도 visibility 규칙을 가질 수 있습니다.

PlanetX Mode의 Planet, Compare, Level view는 이 Domain을 이용해 원본과 프록시를 비교합니다.

#Actor Spatial Loading Policy

EPlanetXActorSpatialLoadingPolicy는 Actor의 World Partition spatial-loading 설정을 누가 관리하는지 정의합니다.

• PlanetXManaged: Orbit Actor를 non-spatial 상태로 유지해 Orbit 표현에서 계속 사용할 수 있게 합니다.
• ActorManaged: Actor의 Is Spatially Loaded 설정을 프로젝트가 직접 관리합니다.

이 정책은 Data Layer membership이나 Streaming Source를 자동 구성하지 않습니다. 해당 시스템은 프로젝트가 계속 소유합니다.

#정책 적용

ShouldForceOwnerAlwaysLoaded로 현재 정책의 결과를 확인하고 ApplySpatialLoadingPolicyToOwner로 Owner에 적용합니다. 적용 함수는 Editor에서도 호출할 수 있습니다. 적용 후 Actor, World Partition과 Data Layer 설정을 프로젝트 기준으로 다시 확인하세요.

#Visibility와 residency 구분

보이지 않는 것과 로드되지 않은 것은 다릅니다. Planet proxy visibility, Section proxy residency, Runtime Preview residency는 별도 상태입니다. Runtime Monitor에서 등록 여부, realized component 수, renderable 상태를 함께 확인해야 합니다.

PlanetX 전환은 표시 Alpha만 바꾸는 효과가 아니라 Section, runtime context, Actor pose와 travel state를 연결하는 수명 주기입니다.

#전환 참여 요소

• APlanetXTransitionEndpoint: Section과 endpoint 역할, cylinder 설정, 참가 Actor 정책
• UPlanetXViewpointComponent: 관찰 위치와 transition presentation 기준
• UPlanetXTransitionMorphComponent: flat/curved mesh 전환 표현
• UPlanetXPlanetProxyComponent: Section proxy와 residency
• UPlanetXSubsystem: query, capture, Same World/Level Handoff facade

FPlanetXTransitionCylinderSettings은 표면 거리와 고도 offset으로 상태와 Alpha를 평가합니다.

#Same World

같은 World 안에서 Orbit Actor가 Ground pose로 이동합니다. 자동 진입은 Coordinate Component의 Spatial Entry policy가 켜진 참가 Actor에만 적용됩니다. 반환 정책은 captured pose 또는 현재 Section-relative pose 중 선택할 수 있습니다.

#Level Handoff

서로 다른 World 사이에서는 BeginLevelHandoff 또는 PrepareTravel이 Ticket을 만들고, 게임 코드가 OpenLevel과 Pawn 정책을 소유합니다. 도착 World에서 ResumePendingTravel 또는 정확한 Ticket을 사용하는 CompleteLevelHandoff가 pose를 적용합니다.

Ticket generation이 오래됐거나 현재 World에 matching pending travel이 여러 개면 적용하지 않습니다. Journey ID는 왕복 상태를 이어주며 완료된 Journey도 진단을 위해 조회할 수 있습니다.

#이동 연속성

Movement Handoff는 linear/angular velocity를 coordinate frame에 맞춰 캡처하고 적용합니다. Consume, Cancel과 rollback 결과를 확인해 중복 적용을 막으세요.

Planet Asset을 더블 클릭하면 전용 Editor가 열립니다. Editor에는 Asset 계약을 다루는 다섯 개의 도킹 가능한 탭이 있습니다.

#탭

기본 레이아웃에서는 중앙의 Preview와 오른쪽의 Configuration이 열립니다. Overview, Sections, Diagnostics는 명령을 실행하기 전까지 닫혀 있을 수 있습니다. 탭이 보이지 않으면 Window > Planet Asset에서 다시 여세요.

Configuration에서는 EnvironmentSettings가 숨겨집니다. 환경 프로필의 단일 제작 표면은 Preview > Advanced > Environment입니다.

#주요 명령

• Open Preview: Alt+P
• Sections: Alt+T
• Open Proxy Bake: Alt+B
• Refresh: F5
• Validate: Shift+F
• Section 검색: Ctrl+F
• 선택 Section Focus: F
• 선택 Section 삭제: Delete

Sections 필터는 All, Same World, External Level, Needs Bake, Needs Transition, Invalid를 제공합니다. Runtime role 변경은 필요한 World와 Proxy Bake 계약을 만족해야 합니다.

#삭제와 보존

Delete Selected Section은 Planet Asset에서 Section과 Level Pair를 제거하지만 참조하던 Source World, Proxy BakeData, Runtime Preview asset을 삭제하지 않습니다. 생성 자산 정리는 별도 확인 작업으로 수행하세요.

#권장 흐름

새 Planet Asset에서는 상태 요약이 필요할 때 Overview를 열고, 저장된 Ground Level에서 Proxy Bake를 엽니다. Section을 먼저 만들거나 선택하지 마세요. 첫 번째 성공한 Proxy Bake가 Section과 Level Pair를 생성합니다. Bake가 끝난 뒤 Sections에서 Linked 상태를 확인하고 Preview에서 비주얼을 조정한 다음 Diagnostics에서 Full Validate를 통과시킵니다.

기존 Planet Asset에서는 Sections에서 작업할 Section을 선택한 뒤 해당 Section의 Proxy Bake 진입점을 사용합니다. Section 선택으로 시작하는 흐름은 기존 Section 작업뿐입니다.

PlanetX Mode는 현재 World의 Planet Actor, Section, 참가 Actor, 환경과 전환을 한 화면에서 연결해 보는 Level Editor mode입니다.

#Palette

F5의 Refresh Preview는 scene index를 새로 만들고 PIE 전 Completion/Padding preview를 갱신합니다.

#Preview view

• Planet: 활성 Planet proxy를 표시하고 Source Level Actor를 숨깁니다.
• Compare: Planet proxy와 Source Level Actor를 함께 표시합니다.
• Level: Planet proxy를 숨기고 원본 Level Actor를 표시합니다.

이 선택은 편집 시 visibility preview이며 저장된 runtime role을 바꾸지 않습니다.

#Scene Tree와 선택

Scene Tree는 Planet, Section, Endpoint, Environment, 참가 Actor 연결을 표시합니다. 같은 Planet에 중복 Endpoint나 Environment Manager가 있거나 Section placement/topology가 잘못되면 경고가 표시됩니다.

Placement 도구로 Actor를 이동할 때 Coordinate Component의 Reference Planet/Section과 representation domain을 먼저 확인하세요. 저장 가능한 위치는 명시 Section ID를 권장합니다.

#PIE 사용

PIE에서는 Runtime palette로 Planet registration, Section state, Runtime Preview와 Transition 결과를 관찰합니다. Source World를 바꾸는 Proxy Bake 작업은 PIE 중 실행하지 마세요.

Proxy Bake Editor는 Ground World의 시각 소스를 수집해 Orbit proxy, partition payload, Runtime Preview와 transition resource를 게시합니다.

#현재 상태에 맞는 진입 경로 선택

Asset 상태에 따라 다음 경로 중 하나를 사용합니다.

처음 사용하는 사용자는 여기서 시작 — Same World 빠른 시작을 따라 첫 번째 경로만 사용하세요.

#첫 Bake 작업 순서

1. Ground Level을 열고 저장합니다.
2. Tools 메뉴의 PlanetX 영역에서 Proxy Bake Editor를 엽니다.
3. Target Planet Asset을 지정하고 Presentation을 Same World, Source Scope를 Current Level로 설정합니다.
4. Scan Sources(F5)를 실행하고 활성 Source가 하나 이상이며 NEW OUTPUT인지 확인합니다.
5. Source Role, Omission과 Output Plan을 검토합니다. Use 또는 Role을 수정했다면 Apply Source Changes를 실행합니다.
6. BAKE IN EDITOR(Ctrl+B)를 실행합니다. 성공 결과는 Bake complete.로 시작하며 Section과 Level Pair를 자동으로 생성합니다.

#기존 Section 작업 순서

1. Planet Asset Editor > Sections를 엽니다.
2. 다시 Bake할 Section을 선택합니다.
3. Open Proxy Bake를 선택합니다.
4. Scan Sources(F5)로 Source와 Bake Plan을 갱신합니다.
5. 변경 사항을 검토하고 표시되는 REBUILD IN EDITOR 또는 BAKE IN EDITOR를 실행합니다.

진행 중 취소는 Esc, 결과 선택은 Ctrl+Shift+O입니다.

PIE 중에는 Source Level 변경이 필요한 작업을 시작할 수 없습니다. 외부 Worker가 활성 상태이면 해당 Source World를 직접 열지 말고 Editor에서 취소만 요청하세요.

#성공 체크포인트

#External Bake Monitor

External Bake 확인 창에서 Open Bake Monitor in browser를 활성화하면 Stage, 진행률, ETA, 리소스 사용량, 경고와 제한된 로그 tail을 로컬 브라우저에서 볼 수 있습니다. Monitor는 관찰 도구이므로 서비스 또는 브라우저를 열지 못하더라도 External Bake는 계속되며 결과도 달라지지 않습니다.

Loopback Monitor 서비스는 PlanetXEditor 모듈에 포함되어 활성 Editor 또는 Direct Worker 프로세스 내부에서 실행됩니다. PlanetX는 별도의 Monitor 실행 파일을 설치하거나 실행하지 않습니다. 서비스는 로컬 연결만 허용하며 세션별 token으로 브라우저 페이지를 인증합니다. 전체 Monitor URL을 공유하거나 게시하지 마세요.

External Bake가 진행되는 동안에는 Direct Worker가 Monitor를 호스팅합니다. Worker가 종료되면 해당 서비스도 종료되므로 기존 탭의 연결이 끊길 수 있습니다. Unreal Editor가 다시 실행된 뒤 Open External Bake Monitor를 사용하면 최신 durable result를 다시 호스팅할 수 있습니다. 새 서비스는 Job artifact에서 상태를 복원하며 이전 브라우저 탭을 자동으로 이전하지는 않습니다.

브라우저 탭을 닫아도 Bake는 취소되지 않습니다. 안전한 checkpoint에서 취소를 요청하려면 Monitor의 Cancel Bake 또는 Editor의 취소 기능을 사용하세요. 취소를 요청해도 부분 결과는 게시되지 않습니다.

#지원 소스

PCG managed resource와 HLOD는 discovery 단계에서 저장·검증 상태를 확인합니다. HLOD가 검증되지 않으면 원본 소스를 보수적으로 사용합니다.

#역할과 태그

Editor는 Auto, ProxyGeometry, LandscapeProxy, InstanceBatch, Discard, ManualReview, Unsupported 역할을 표시합니다. Source group은 Actor, Folder, Data Layer, Level/Level Instance 단위로 볼 수 있습니다.

C++ 태그 API는 BakeSource, NoBake, Preview, Generated를 제공합니다. 명시적 제외는 omission을 숨기는 수단이 아니라 의도된 소스 정책으로 사용하세요.

#결과 판정

Succeeded는 omission 없는 성공입니다. CompletedWithWarnings는 게시 성공이지만 SourceOmissions를 검토해야 합니다. package가 512 MiB를 넘으면 경고하고 1 GiB를 넘으면 게시를 거부합니다.

PlanetX 검증은 오류 문구만 나열하지 않고 finding의 Severity, Impact, blocking scope, 자동 수정 가능 여부와 resolution action을 제공합니다.

#Quick와 Full Validate

Quick Validate는 Asset 구조와 즉시 확인 가능한 계약을 검사합니다. Full Validate는 World, Proxy Bake link, Runtime Preview, 생성 결과까지 더 깊게 확인하고 구조화된 로그를 남깁니다.

Diagnostics 탭의 주요 동작:

• Quick Validate
• Full Validate
• Review Sections
• Open Proxy Bake
• Show Section
• Open Details

#Validate palette

PlanetX Mode의 Validate palette는 현재 World와 연결 Asset을 함께 검사합니다. Fix All Safe는 결과가 결정적이고 추가 선택이 필요 없는 Warning만 수정합니다. 파괴적 작업이나 사용자 결정을 요구하는 finding은 자동으로 바꾸지 않습니다.

#자주 보는 finding

• Planet ID/Section ID 누락 또는 중복
• 잘못된 Radius나 Coordinate Convention
• Same World와 External Level의 World package 관계 오류
• GroundSyncMapping 또는 TransitionPolicy 누락
• stale Proxy Bake/Generated Visual/Generated Material
• 변경된 Source Material
• unresolved Reference Planet/Section
• World Partition runtime load policy 불일치

#로그와 지원 자료

Full Validate 결과는 LogPlanetXValidation에 안정적인 Surface/Operation/Subject 형태로 기록됩니다. Visual Edit 문제는 PlanetX.VisualEdit.Dump, proxy 표현은 PlanetX.ProxyStats.Dump로 추가 상태를 확인하세요.

런타임 통합의 공개 facade는 Game Instance Subsystem인 UPlanetXSubsystem입니다. World별 registry와 서비스는 내부 구현이며 gameplay 코드는 facade와 공개 Component를 사용합니다.

#Planet 등록

APlanetXPlanetActor에는 Planet, Proxy, Transition Morph, Atmosphere, Volumetric Cloud Component가 기본으로 포함됩니다. Planet Component에 Planet Asset을 지정하고 bAutoRegisterRuntime을 사용하거나 RegisterToPlanetXRuntime을 호출합니다.

같은 Planet ID를 가진 Actor가 여러 개면 Planet Binding ID를 저장하고 query에 전달하세요. 단일 인스턴스만 가정한 자동 resolve는 여러 Actor 환경에서 모호할 수 있습니다.

#참가 Actor

필요에 따라 다음 Component를 추가합니다.

• Coordinate: Planet/Section reference, 표준 pose, vector 변환, Spatial Entry policy
• Movement: planet gravity, input/force/impulse, surface snap과 alignment
• Viewpoint: transition 관찰 기준
• Travel Receiver: Level Handoff 도착 후 pending travel 재개
• Transition Endpoint: Section 진입/이탈 조건과 presentation

#Begin Play 순서

Planet Actor가 먼저 등록되고 참가 Actor가 runtime context를 resolve할 수 있어야 합니다. Streaming으로 순서가 늦어질 수 있으면 RefreshRuntimeRegistration, RefreshRuntimeContext 또는 Travel Receiver의 retry 정책을 사용합니다.

#Package 전 확인

Planet Asset Full Validate, current Proxy Bake, current Generated Visual/Material, Runtime Preview World와 Cook asset bundle을 확인합니다. Editor Preview가 보인다는 사실만으로 runtime payload가 Cook됐다고 판단하지 마세요.

좌표 API는 Actor pose 변환과 행성 표면 탐색을 분리합니다. UPlanetXSubsystem은 World context를 받는 Blueprint facade이며 Coordinate Component는 Owner에 바인딩된 편의 API를 제공합니다.

#Transform Capture와 Resolve

• CapturePlanetXTransform: World Transform을 PlanetX 표준 pose로 캡처
• CaptureActorPlanetXTransform: Actor Transform을 캡처
• ResolvePlanetXTransform: 표준 pose를 현재 World Transform으로 계산
• ApplyPlanetXTransformToActor: 계산과 Actor 적용
• ResolveCoordinateFrame: Planet 또는 Section frame을 World로 resolve

반환 bool과 함께 FPlanetXTransformResolveResult를 확인합니다. Planet ID와 Binding, Section ID가 현재 World registry와 일치해야 합니다.

#표면 Query

FPlanetXSurfaceQueryInput에는 ray origin/direction과 선택 조건이 들어갑니다. QuerySurfaceAtWorldRayDetailed은 Hit/Miss 외에 InvalidInput과 RuntimeUnavailable을 구분하므로 gameplay 분기에 권장됩니다.

Geo 또는 FPlanetXTransform에서도 표면을 조회할 수 있습니다. 결과 FPlanetXSurfaceQueryResult에는 Planet, Section, hit 위치, normal과 좌표 정보가 포함됩니다.

#착지와 Section

BuildLandingTransform은 query 결과로 surface-aligned 착지 pose를 만듭니다. GetSectionTransform, GetSectionDesc, GetSectionRuntimeState는 Section 계약과 현재 상태를 조회합니다.

#Component 벡터 API

Surface Up/Down/East/North, tangent projection, Surface/Planet/Section Local ↔ World vector 변환을 제공합니다. 위치와 벡터를 혼동하지 말고, 지표 입력에는 tangent projection 여부를 명시하세요.

UPlanetXMovementComponent는 Coordinate Component가 resolve한 runtime context를 사용해 행성 기준 이동을 적용합니다.

#설정

Movement Component의 UpdatedComponent가 유효해야 합니다. Reference Coordinate Component와 Planet gravity 설정을 확인하고 ValidateMovementConfiguration으로 오류 메시지를 받습니다.

FPlanetXNativeMovementSettings은 가속, 감속, 속도와 ballistic 동작을 정의합니다. FPlanetXGravitySettings은 행성 중심 방향의 가속을 정의하고 Planet Component의 GetGravityAccelerationAtWorldLocation으로 조회할 수 있습니다.

#입력과 물리

Surface Frame 입력은 East/North/Up입니다. 지상 이동은 tangent projection을 켜고 점프·비행은 Up 성분 정책을 명시합니다.

#Runtime state

GetMovementRuntimeState에는 현재 velocity, gravity, resolve/failure 상태가 담깁니다. Game Instance facade의 단일·전체 state query는 디버그 UI와 telemetry에 사용할 수 있습니다.

#Handoff

World나 Movement Component를 교체할 때 velocity를 직접 복사하지 말고 Movement Handoff API를 사용하세요. frame continuity policy가 linear/angular velocity를 새 표면 frame에 맞춰 해석합니다.

Same World 이동은 Orbit과 Ground가 같은 World package에 있을 때 Actor를 Section의 Ground pose로 옮기고 다시 Orbit pose로 반환합니다.

#계약

Level Pair의 OrbitWorld와 GroundWorld가 같은 package여야 합니다. Section의 GroundSyncMapping, transition bounds와 Surface Query가 유효해야 합니다. 이동할 Actor는 현재 World에서 resolve 가능한 Planet/Section context를 가져야 합니다.

#명시 호출

1. Ray 또는 Geo query로 FPlanetXSurfaceQueryResult를 얻습니다.
2. EnterGroundSameWorld(WorldContext, Actor, SurfaceQuery)를 호출합니다.
3. Ground gameplay를 수행합니다.
4. ReturnToOrbitSameWorld(WorldContext, Actor)를 호출합니다.

진입 시 Journey와 capture가 만들어지고 Actor에 연결됩니다. 반환은 Actor에 연결된 정확한 Journey를 사용합니다.

#자동 Spatial Entry

Coordinate Component에서 automatic same-world entry/return을 켤 수 있습니다. Runtime은 viewpoint/participant가 transition 경계를 넘는지 평가하고 안전한 시점에 pose를 적용합니다.

Return Pose Policy는 캡처한 Orbit pose 또는 현재 Ground Section-relative pose에서 복원하는 방식을 선택합니다. 현재 pose 기반 반환은 Ground에서 움직인 결과를 Orbit Section frame에 이어야 할 때 사용합니다.

#실패 처리

Surface Query가 다른 Section/Planet이거나 Actor의 context가 모호하면 실패합니다. 자동 반환은 Orbit 표현이 준비될 때까지 기다릴 수 있습니다. GetTransitionJourney와 managed actor state로 상태를 확인하세요.

Level Handoff는 서로 다른 World package 사이에서 PlanetX pose와 Journey 상태를 전달합니다. 게임 코드는 레벨 로딩과 Pawn 생성 정책을 계속 소유합니다.

#권장 흐름

PrepareTravel은 Source Actor, Surface Query, 명시적인 FPlanetXTravelRoute에서 Ticket을 만듭니다.

FPlanetXLevelHandoffTicket Ticket;
FPlanetXLevelHandoffResult Result;
const bool bPrepared = PlanetXSubsystem->PrepareTravel(
    WorldContext, SourceActor, SurfaceQuery, TargetRoute, Ticket, Result);

성공하면 게임이 Ticket.TargetWorld로 이동합니다. 도착 후 한 개의 matching pending ticket만 존재할 때 ResumePendingTravel을 사용하거나, 저장한 Ticket으로 CompleteLevelHandoff를 호출합니다.

#왕복

고급 API는 BeginLevelHandoff → CompleteLevelHandoff → BeginReturnLevelHandoff(JourneyId) → CompleteLevelHandoff 흐름을 제공합니다. PrepareTravel은 명시 route를 사용해 Ground에서 Orbit으로 직접 돌아갈 수도 있습니다.

#안전 규칙

• matching pending travel이 없으면 PendingTravelNotFound
• 여러 개면 AmbiguousPendingTravel
• 오래된 Ticket generation은 StaleGeneration
• target Planet Binding을 아직 찾지 못하면 Travel Receiver가 timeout 안에서 retry 가능
• Level Handoff Ground pose는 capture에 저장된 Ground mapping이 authoritative

ResumePendingTravel은 latest ticket을 추측하지 않습니다. 멀티 Travel을 허용하는 프로젝트는 Ticket이나 Journey를 gameplay save state에 함께 관리하세요.

#취소와 진단

미사용 Ticket은 CancelLevelHandoff로 취소합니다. Capture, Journey와 Result error를 로그에 함께 남기고 GetActiveTransitionJourneys로 누수를 확인하세요.

Runtime Preview는 External Level Section의 Ground 표현을 Orbit/Transition World에서 보여주는 gameplay-independent 렌더 host입니다.

#로딩 수명 주기

APlanetXRuntimePreviewActor의 residency state는 Idle, LoadingRoot, LoadingPayloads, LoadingResources, Realizing, WaitingForRender, Resident, Failed 순으로 진행될 수 있습니다.

Game Instance facade는 다음을 제공합니다.

• LoadRuntimePreview
• SetRuntimePreviewVisible
• UnloadRuntimePreview
• GetRuntimePreviewStatus

직접 Actor를 사용할 때는 AssignPreviewBakeData, LoadPreviewFromBakeData, SetPreviewVisible, UnloadPreview와 renderable/component count query를 사용합니다.

#표현 범위

Runtime Preview는 Proxy Static Mesh, baked ISM/HISM/Foliage instance batch를 하나의 root 아래에 만듭니다. gameplay Actor 복제, collision, navigation, tick 기반 동작은 의도적으로 포함하지 않습니다.

Loaded와 Renderable은 다릅니다. Resident라도 필요한 render resource가 아직 준비되지 않으면 presentation 전환을 기다려야 합니다.

#Runtime Budget

Project Settings의 PlanetX Runtime은 Follow Engine Scalability 또는 고정 profile 정책을 선택합니다. Proxy Bake Quality는 게시 revision의 immutable geometry 품질이고 Runtime Budget은 프레임당 realization·residency 작업량이므로 서로 독립적입니다.

#관찰

Stat PlanetXMemory, Stat PlanetXResources, Stat PlanetXProxy, Stat PlanetXRuntime으로 memory, resource count, render, runtime service 비용을 확인합니다. PlanetX.MemoryBudgetMB와 자동 material MID budget warning도 함께 검토하세요.

APlanetXEnvironmentManager는 Planet Asset의 환경 프로필과 현재 World의 Atmosphere, Cloud, Sun, Post Process, Space Background binding을 연결합니다.

#Binding 모드

PlanetX Managed 모드는 필요한 Component를 PlanetX profile에 맞춰 제어합니다. Use Existing Level 모드는 기존 SkyAtmosphere나 Volumetric Cloud를 유지하므로 Planet Asset profile과 수동으로 일치시켜야 합니다.

Managed Planet Actor가 있으면 Radius와 environment authoring 설정을 resolve합니다. Existing Sun Light가 없으면 저장된 Sun direction을 사용하지만 validation warning이 남을 수 있습니다.

#초기화와 전환

• ValidateEnvironmentBinding: 필수 binding과 material/profile 조건 검사
• CaptureEnvironmentStateFromBindings: 현재 Level 값을 state로 캡처
• ApplyEnvironmentState: 저장 state 적용
• ApplyInitialRuntimeSpace: 시작 Orbit/Ground 표현 적용
• SetEnvironmentTransition(From, To, Alpha): 두 공간 사이 보간

Orbit cloud/atmosphere render quality와 tracing override는 Apply/Restore 쌍으로 사용합니다. restore를 생략하면 기존 Level 품질 값이 남지 않을 수 있습니다.

#자주 발생하는 경고

• Existing cloud/atmosphere 미지정
• PlanetX cloud와 existing Ground cloud 불일치
• MPC 미지정
• Planet Radius 또는 terminator softness가 0 이하
• Cloud shadow override에 Sun/Cloud source 누락
• Space Background material domain/blend/shading/Is Sky 설정 오류

환경 전환 문제는 binding validation부터 해결한 뒤 presentation Alpha를 조사하세요.

Planet Asset Editor의 Preview 탭은 전용 미리보기 World에서 Planet visual contract를 제작합니다. Basic은 자주 쓰는 항목, Advanced는 생성·환경 세부 설정을 제공합니다.

#Basic

Basic의 Planet, Sections, Environment 영역에서 다음을 빠르게 조정합니다.

• Atmosphere 활성화와 Radius 기반/Manual 높이
• Volumetric Clouds와 layer 높이
• 태양과 cloud shadow
• Post Process, convolution bloom, lens flare
• Section 선택과 preview

#Advanced

Advanced에서는 Planet Completion, Section Proxy Padding, material build와 Environment profile 전체를 편집합니다. 변경은 preview session에 적용되고 성공한 build가 Planet Asset revision과 연결됩니다.

#Preview 원칙

Preview는 제작 환경이며 Runtime World 자체가 아닙니다. Runtime Preview는 Proxy Bake가 게시한 payload를 읽는 별도 경로입니다. Preview에서 좋아 보이더라도 Diagnostics의 stale 상태와 Runtime Preview readiness를 확인해야 합니다.

#조작과 진단

Preview viewport는 행성 반지름에 맞춰 카메라 속도와 framing을 조정합니다. 실패한 Padding Material Preview는 실패 Section 수를 표시하며 PlanetX.VisualEdit.Dump에서 상세 원인을 확인할 수 있습니다.

변경 전후에는 저장하고, Section geometry와 Material source가 바뀌면 Completion/Padding과 Proxy Bake의 stale 상태를 모두 검토하세요.

Completion은 Section 사이에서 보이지 않는 행성 표면을 생성하고, Padding은 Section proxy 경계가 구형 행성 표현과 자연스럽게 이어지도록 보강합니다.

#Completion

Surface Completion 설정은 생성 topology, cutout, terrain noise와 surface material을 제어합니다. 생성기는 동일 입력에 대해 결정적인 결과를 만들고 polygon, boundary, mesh attribute를 검증합니다.

Terrain Region은 행성 표면의 특정 구역에 noise parameter를 적용합니다. 큰 noise나 잘못된 cutout이 proxy 아래로 침범하지 않는지 Preview에서 확인하세요.

#Padding

Proxy Padding은 Section boundary loop를 선택하고 adaptive subdivision과 projection으로 연결 geometry를 만듭니다. Transition strip과 shared seam은 경계의 위치·normal·material provenance를 유지합니다.

성능 budget에는 boundary edge, generated vertex, index, compact binding, MID 수의 warning/hard 기준이 있습니다. Warning은 결과를 게시할 수 있지만 runtime 비용을 검토해야 함을 뜻합니다.

#Material build

Padding Material Build는 source material layout을 수집하고 필요한 texture/material asset을 생성합니다. Source Material asset path가 같더라도 내용이 바뀌면 Editor validation이 stale 상태를 찾습니다. Package 전에 다시 build하세요.

#실패 시 확인

• Section bounds와 boundary loop 유효성
• Proxy Bake revision과 generated visual geometry hash
• Source Material layout과 slot remap
• projection tolerance와 Planet Radius
• performance budget warning

PlanetX 재질 경로는 원본 Section material, Proxy Bake가 게시한 material identity, Completion/Padding용 생성 material을 구분합니다.

#Surface Preset

UPlanetXSurfacePreset은 Completion과 행성 표면의 재사용 가능한 스타일을 담는 Primary Data Asset입니다. Preset을 Planet Asset의 Active Surface Preset으로 지정하면 authoring 설정이 해당 선택을 참조합니다.

Preset은 material, terrain/noise 성격과 시각 파라미터를 공유하는 데 사용하고 Planet ID나 Section geometry 같은 구조 계약을 대신하지 않습니다.

#Proxy material

UPlanetXPlanetProxyComponent의 Planet Material Override는 행성 sphere 표현을 교체합니다. Section proxy material은 BakeData의 canonical slot과 remap을 따라야 합니다. 임의로 slot 순서를 바꾸면 boundary와 padding material provenance가 어긋날 수 있습니다.

#자동 Padding material

Runtime binder는 generated visual의 binding descriptor와 Source Material identity를 확인한 뒤 MID를 준비합니다. geometry revision, slot, texture set이 일치하지 않으면 error material 또는 경고가 사용될 수 있습니다.

#권장 사항

• Source Material을 변경한 뒤 Full Validate 실행
• stale Generated Material을 package 전에 rebuild
• Material slot 순서를 Bake와 Visual build 사이에서 유지
• Sky material은 지표 Proxy Bake 소스로 사용하지 않음
• 동적 재질은 결정적으로 캡처 가능한 파라미터만 사용

환경 프로필은 Planet Asset Editor > Preview > Advanced > Environment에서 제작합니다. Atmosphere, Clouds, Sun, Post Process, Space Background가 하나의 FPlanetXEnvironmentAuthoringSettings에 저장됩니다.

#Atmosphere와 Clouds

Atmosphere 높이는 Planet Radius 비율로 자동 계산하거나 수동 km 값으로 지정할 수 있습니다. Rayleigh, Mie, absorption, aerial perspective와 ground albedo를 조정합니다.

Clouds는 layer bottom/height, lighting, atmosphere interaction, shadow parameter를 가집니다. 기존 Level cloud를 사용할 때 PlanetX cloud와 설정이 다르면 Orbit/Ground 전환에서 불일치가 생길 수 있습니다.

#Sun과 Post Process

Sun profile은 atmosphere sun light, cloud shadow, shadow extent와 품질을 정의합니다. Post Process에서는 planet profile, convolution bloom, lens flare를 제어합니다. Project Settings의 PlanetX Rendering도 lens flare 기본 console variable을 적용합니다.

#Space Background

Space Background material은 Surface domain, Opaque, Unlit, Is Sky 설정을 권장합니다. Planet Asset Defaults를 source로 선택하면 연결된 Managed Planet Actor와 Planet Asset이 필요합니다.

#Runtime 연결

레벨의 APlanetXEnvironmentManager에 Planet Actor, Sun, Atmosphere, Volumetric Cloud와 MPC를 연결합니다. ValidateEnvironmentBinding으로 누락·불일치를 확인한 뒤 ApplyInitialRuntimeSpace 또는 SetEnvironmentTransition을 사용합니다.

이 카테고리는 현재 PlanetX 코드에서 사용자가 조정할 수 있는 설정을 소유 객체와 작업 화면별로 정리합니다. 설정 이름은 Unreal Editor의 Details 패널 또는 C++ 속성 이름과 대응하며, 기본값은 새 객체를 만들었을 때의 코드 기본값입니다.

#어디에서 무엇을 설정하나요?

#설정과 생성 데이터 구분

PlanetX의 reflected 구조체에는 사용자가 선택하는 설정뿐 아니라 Bake 결과, Runtime Capture, 쿼리 입력과 진단 데이터도 포함됩니다.

• 사용자 설정은 이 카테고리에서 기본값, 단위, 효과를 설명합니다.
• 조건부 설정은 선행 토글이나 Mode가 활성화될 때만 사용됩니다. 표의 조건을 함께 확인하세요.
• 생성 데이터는 Proxy Bake 또는 Visual Build가 작성합니다. Details에 표시되더라도 수동 편집하지 않는 것이 원칙입니다.
• 요청·결과 구조체는 함수 호출마다 전달되는 값이며 저장형 프로젝트 설정이 아닙니다. 해당 필드는 공개 API 레퍼런스에서 설명합니다.

#기본값을 변경하기 전 확인할 점

1. Planet ID, Radius, Coordinate Convention은 Planet Asset 생성 시 확정되는 계약입니다. 기존 Asset에서 직접 바꾸는 설정이 아닙니다.
2. Proxy Bake Quality와 Runtime Budget은 서로 독립적입니다. 품질을 바꾸면 생성 결과가 달라질 수 있지만 Runtime Budget 변경은 이미 Bake된 Asset을 다시 만들지 않습니다.
3. Override 토글이 꺼져 있으면 Component는 Project Settings 또는 Planet Asset의 값을 사용합니다.
4. Proxy Bake, Section 배치, Visual 설정을 바꾼 뒤에는 표시되는 Stale 상태를 확인하고 필요한 Bake 또는 Apply & Build를 다시 실행하세요.
5. 최종 패키징 전에는 Planet Asset의 Full Validate와 현재 World의 Validate를 모두 실행하세요.

#공개 코드 기준

이 레퍼런스는 PlanetX 1.0에 포함된 다음 공개 헤더를 기준으로 작성되었습니다.

Source/PlanetX/Public/PlanetX

Public 헤더에 존재한다는 이유만으로 모든 데이터 구조체가 일반 사용자 설정이 되는 것은 아닙니다. 이 문서는 Editor에서 조정 가능한 값, Project Config 값, 공개 작업 옵션을 설정 범위로 다루고, 파이프라인이 생성하는 payload와 capture는 별도로 표시합니다.

거리와 크기는 별도 표기가 없으면 Unreal Unit인 cm입니다.

#생성 시 확정되는 Planet 계약

#Authoring Geometry Settings

#Surface Completion Settings

Section이 덮지 않는 행성 표면을 생성하는 설정입니다.

#Proxy Padding Settings

#Padding Performance Budget

Warning 값은 경고를 만들고 Hard 값은 과도한 Build를 차단하는 상한입니다. Hard 값은 대응 Warning 값보다 작게 두지 마세요.

#Transition Distance Settings

모든 값은 0 이상이어야 합니다. 실제 Runtime의 Section 로드/표시 Alpha는 Level Pair의 TransitionPolicy가 소유합니다.

#Preview와 Build Settings

#Section Settings

Section 목록은 Planet Asset Editor와 Proxy Bake가 관리합니다.

Same World Section은 North Pole Anchor 계약 때문에 위도, 경도, Yaw, Scale이 잠깁니다. Altitude만 Ground 접촉 높이 보정에 사용할 수 있습니다. Bounds, RegionSet, SourceRef, ProxyBakeData와 각 사각형/Hash는 Scan/Bake가 생성하는 데이터이므로 수동 편집하지 마세요.

#Level Pair와 Transition Policy

#Surface Preset

ActiveSurfacePreset을 Planet Asset에 지정한 뒤에도 실제 Build 입력이 의도한 값인지 Preview에서 확인하고 Apply & Build를 실행하세요.

#Planet Asset의 설정 묶음 이름

Details/API에서 AuthoringGeometrySettings, SurfaceCompletionSettings, ProxyPaddingSettings, TransitionDistanceSettings, ShapeEditorSettings가 위 표의 각 설정 묶음을 소유합니다. ProxyPaddingSettings.PerformanceBudget은 Padding Warning/Hard 상한 묶음입니다.

Basic/Advanced 전환 상태, Bake Quality, 요청한 Source Representation은 Editor 사용자 설정에 저장됩니다.

#1 Target Planet Asset

Planet Asset이나 Source World가 바뀌면 기존 Scan Plan은 stale 상태가 됩니다. 새 대상에 대해 다시 Scan Sources를 실행하세요.

#2 Runtime Role

Level Handoff의 backend 계약 기본값은 OpenLevel입니다. PlanetX는 상태를 capture/resume하지만 실제 Open Level, Pawn 생성, Possess 흐름은 게임이 수행합니다.

#3 Source Scope

Selected Actors, Reviewed Set 또는 Tag Filter처럼 정확한 membership이 필요한 계약에서는 Prefer HLOD를 요청해도 effective 정책이 Original Actors로 바뀔 수 있습니다. UI의 Source Representation summary에서 requested/effective 결과를 확인하세요.

#Source Review

Use나 Role을 변경한 뒤에는 Apply Source Changes로 Plan에 반영하세요. WPO/displacement, private material dependency, unsupported deformation 같은 안전성 경고는 단순 경고가 아니라 명시적인 제외 또는 수정이 필요한 차단 조건일 수 있습니다.

#Bake Quality

Quality는 생성 결과에 기록되는 immutable authoring preset입니다.

High도 무제한 원본 LOD를 뜻하지 않습니다. 가장 거친 유효 LOD의 triangle count에 배수를 적용한 범위에서 가장 정밀한 LOD를 선택해 기하 증가를 제한합니다.

#Advanced Projection과 Output Plan

Output path, Target Section, Bake ID, Source/Partition/Geometry summary는 계산 결과입니다. 출력 대상이 기존 Asset과 충돌하면 Editor가 명시적인 overwrite/rebuild 확인을 요구합니다.

#Advanced Execution Budget

더 높은 값이 항상 빠른 것은 아닙니다. Scan 뒤 표시되는 top contributor와 remediation을 확인하고, 메모리 부족 시 Worker/Queued/GT Finalize보다 먼저 Auto Memory Budget과 Partition Plan을 점검하세요.

#공개 고급 옵션: FPlanetXProxyBakePartitionDesc

이 구조체는 Transition Morph나 공개 C++ 경로의 projection 계약입니다. 일반 Proxy Bake UI에서는 Target Asset과 Plan으로부터 생성됩니다.

#공개 고급 옵션: FPlanetXProxyBakeOptions

Editor의 품질 preset과 source classification이 일반 사용자 경로에서 이 값을 해결합니다. 직접 API를 구성하는 도구만 명시적으로 설정하세요.

FPlanetXProjectionResult, material remap, heightfield, mesh page, partition output과 instance batch 구조체는 결과 payload입니다. 속성이 reflected되어 있어도 사용자 설정으로 편집하지 마세요.

#Planet Component

UPlanetXPlanetComponent는 APlanetXPlanetActor의 Runtime 등록과 행성 중력 기준을 소유합니다.

#Coordinate Component

SpatialEntryPolicy는 아래 Same World 자동 진입/복귀 설정 묶음입니다.

#Spatial Entry Policy

#PlanetX Transform

TransformSource=PlanetXTransform일 때 아래 값이 authoritative 입력입니다.

#Movement Component

UPlanetXMovementComponent는 PlanetX native 이동을 사용할 때 추가합니다. 기존 Character Movement만 사용할 프로젝트에는 필수가 아닙니다.

NativeMovementSettings와 SurfaceAlignmentSettings는 아래 두 하위 표의 설정 묶음입니다.

#Native Movement Settings

#Surface Alignment Settings

공개 Surface Snap 요청의 TargetAltitudeCm은 목표 표면 고도이고 bSweep은 그 위치로 이동할 때 충돌 Sweep을 사용할지 결정합니다.

#Viewpoint Component

실제 PlayerController View Target과 활성 Camera가 있는 Actor에 두세요.

#Travel Receiver Component

Level Handoff 뒤 새 World의 Actor가 pending capture를 복원하는 설정입니다.

#Transition Endpoint

PlanetX Mode의 Add Endpoint가 ID와 Actor 참조를 채우는 것이 가장 안전합니다.

#Movement Handoff 호출 옵션

이 값들은 Component Details의 저장 설정이 아니라 Capture/Apply 호출마다 전달하는 공개 옵션입니다.

UPlanetXSubsystem::MaxCaptureStackDepth의 클래스 기본값은 8입니다. 이는 중첩 Transition Capture의 안전 상한인 고급 기본값이며 일반 Project Settings 항목은 아닙니다.

Runtime Budget Override는 진단이나 특정 Actor의 명시적 요구가 있을 때만 사용하고, 일반적으로는 Project Settings 정책을 따르세요.

#Planet Proxy Component

#표시와 생성

#Section Proxy Layer Descriptor

이 배열은 일반적으로 Planet Asset과 Bake 결과로부터 생성됩니다. 수동으로 구성하는 고급 경로에서만 편집하세요.

#Section Proxy Runtime Budget Override

bOverrideSectionProxyRuntimeBudget=false이면 Project Runtime Budget을 사용합니다.

#Surface Correction Override

#Debug Overlay

DebugOverlaySettings가 아래 시각화 값 묶음을 소유합니다.

#Transition Morph Component

#Source와 Morph Geometry

#GPU WPO Morph

#GPU Render Pass Policy

이 옵션은 PlanetX가 소유한 Transition Morph render Component에만 적용됩니다.

#Morph Performance와 Visibility

#Runtime Preview Actor

External Level Proxy Bake가 생성하는 Preview World의 Actor입니다. 직접 배치한 Gameplay Actor가 아니며, PreviewBakeData 링크는 생성 파이프라인이 관리합니다.

Runtime Preview에는 GameMode, Pawn, Controller, Gameplay Actor Logic, Navigation과 Ground Gameplay Collision을 복제하지 마세요. 실제 Gameplay는 Ground World의 책임입니다.

Planet Asset의 EnvironmentSettings는 행성 전체에서 재사용하는 저작 Profile이고, Level의 PlanetX Environment Manager는 이 Profile을 적용하거나 해당 Level만 Override합니다. 거리 비율은 canonical Planet Radius에 대한 비율이며, Km가 붙은 값은 km입니다.

#Planet Asset: Atmosphere Profile

#Planet Asset: Cloud Profile

#Planet Asset: Sun과 Cloud Shadow Profile

#Planet Asset: Post Process와 Space Background

#Environment Manager: Domain과 Profile Source

Resolved Profile과 Resolved Height 값은 읽기 전용 결과입니다. CloudShadow 역시 Sun Profile에서 계산되는 Runtime cache이므로 직접 수정하지 않습니다.

#Environment Manager: Runtime과 Binding

#Orbit Cloud Lighting과 Existing Cloud Sync

Sync 이름은 사용 중인 Material parameter와 대소문자까지 일치해야 합니다.

#Orbit Render Quality와 Ground Presentation

GroundEnvironmentPresentation이 아래 Ground presentation 설정 묶음을 소유합니다.

#Orbit Cloud Tracing

#Material Parameter Collection

EnvironmentParameterCollection에 사용할 MPC를 지정합니다. MpcParameters는 PlanetX가 쓰는 parameter 이름 매핑입니다.

이름을 변경했다면 MPC와 모든 소비 Material도 함께 변경하세요. Parameter가 없으면 해당 값은 Material에 전달되지 않습니다.

#파생 Cloud Shadow Runtime Cache

Manager의 CloudShadow는 편집 원본이 아니라 SunProfileOverride 또는 Asset Sun Profile에서 계산되는 cache입니다. 내부 Mode 기본값은 PlanetXManagedOverride이고, bEnableOrbitCloudShadow=true, bRestoreSourceLightWhenGroundActive=true입니다. DesiredOrbitLightShadow는 Orbit Material Approximation용, DirectionalLightOverrideShadow는 Orbit Directional Light용, GroundDirectionalLightOverrideShadow는 Ground용 상태이며, bUseSeparateGroundDirectionalLightOverride=false일 때 Ground도 Orbit Override를 공유합니다. 이 cache를 직접 고치지 말고 위 Sun/Cloud Shadow Profile을 편집하세요.

PlanetX의 Project Settings는 Edit > Project Settings > Plugins 아래에 있습니다. 두 설정 객체는 DefaultEngine.ini 계열 Config에 저장됩니다.

#PlanetX Runtime

RuntimeBudgetPolicy는 Bake된 Section Proxy, Transition Morph, Runtime Preview가 한 Frame과 한 streaming request에서 처리할 작업량을 정합니다. Proxy Bake Quality와는 독립적이므로 이 값을 바꿔도 Bake Asset이 다시 생성되지 않습니다.

#Resolved Budget 값

Engine Quality Level 0은 Low, 1은 Medium, 2는 High, 3 이상은 Epic으로 매핑됩니다.

#Actor별 Override 우선순위

다음 Override가 켜져 있으면 해당 Actor/Component가 Project Profile보다 우선합니다.

1. Planet Proxy Component의 bOverrideSectionProxyRuntimeBudget
2. Transition Morph Component의 bOverrideTransitionRuntimeBudget
3. Runtime Preview Actor의 bOverrideRuntimeBudget

Override는 문제 진단이나 특정 Actor가 반드시 다른 처리량을 가져야 할 때만 사용하세요. 너무 큰 값은 Game Thread spike와 streaming burst를 만들 수 있고, 너무 작은 값은 Section이 완전히 나타날 때까지 여러 Frame이 더 필요하게 만듭니다.

#PlanetX Rendering

이 값은 Project Setting 우선순위로 Console Variable에 적용됩니다. 일반 Scalability 변경으로 조용히 낮아지지는 않지만, command line이나 더 높은 우선순위의 Runtime Override는 여전히 우선할 수 있습니다.

행성별 EnvironmentSettings.PostProcess.bEnableLensFlare와 LensFlareIntensity도 함께 적용됩니다. Project에서 Lens Flare가 꺼져 있으면 행성별 토글만 켜도 렌더러 기능이 활성화되지 않습니다.

#성능 조정 순서

1. Project의 Follow Engine Scalability를 유지한 상태로 목표 플랫폼 Scalability에서 측정합니다.
2. Runtime diagnostics에서 payload, dependency, component, instance 중 어느 상한이 병목인지 확인합니다.
3. 전체 프로젝트가 일관되게 더 작은/큰 budget을 필요로 할 때만 고정 Profile을 선택합니다.
4. 한 Actor만 예외여야 할 때 Component Override를 사용합니다.
5. Proxy 품질이나 triangle 수가 문제라면 Runtime Budget이 아니라 Proxy Bake Quality와 Source Scope를 조정하고 다시 Bake합니다.

#Config 검토

Project Settings를 바꾸면 소스 관리에 포함될 Config/DefaultEngine.ini 변경을 확인하세요. 사용자별 Saved/Config 값만 바뀌고 기본 Config에 반영되지 않으면 팀원과 패키징 빌드가 같은 값을 사용하지 않을 수 있습니다.

PlanetX gameplay 통합에는 PlanetX 런타임 모듈을 사용합니다. Blueprint의 주요 facade는 UPlanetXSubsystem이며 Actor와 Component가 등록, 좌표, 이동, 전환, 환경과 도착 처리를 담당합니다.

이 레퍼런스는 PlanetX 1.0에 포함된 Source/PlanetX/Public/PlanetX 아래의 공개 헤더를 기준으로 작성했습니다.

#API 지원 등급

타입이 공개 헤더에 있다는 사실만으로 지원 등급이 정해지는 것은 아닙니다. 생성 Mesh 중간 데이터, Bake pass, 내부 Runtime Service와 직렬화 payload를 게임 코드의 계약으로 사용하지 마세요.

#주요 타입

#모듈과 Subsystem 접근

게임 모듈의 Build.cs에 런타임 모듈을 추가합니다.

PublicDependencyModuleNames.AddRange(new[] { "PlanetX" });

C++에서는 유효한 Game Instance에서 Subsystem을 얻습니다.

#include "PlanetX/Subsystems/PlanetXSubsystem.h"

UPlanetXSubsystem* PlanetX = GameInstance->GetSubsystem<UPlanetXSubsystem>();

Blueprint에서는 Game Instance Subsystem 노드를 사용합니다. World가 없거나 종료 중일 때 World Context 함수를 호출하지 마세요.

#공통 실패 규칙

• bool 반환값은 작업 완료 여부를 나타냅니다. 함수가 진단 출력을 별도로 보장하지 않는 한 false 뒤에는 출력 parameter를 사용하지 않습니다.
• Enum을 반환하는 Query는 성공 상태일 때만 출력값을 사용합니다.
• None ID, 유효하지 않은 Object 참조, 만료된 Handle과 non-success 오류 Enum을 정상적인 실패 상태로 처리합니다.
• 후보가 여러 개일 수 있으면 Planet, Binding, Section과 Level Pair ID를 명시합니다.
• 등록 또는 Streaming 상태가 바뀌면 Runtime Context를 갱신합니다.

Blueprint 표시명과 C++ Symbol은 다를 수 있습니다. 이 레퍼런스의 이름과 include 경로는 C++ 선언을 기준으로 합니다.

헤더: PlanetX/Subsystems/PlanetXSubsystem.h

UPlanetXSubsystem은 지원되는 런타임 API의 Game Instance Subsystem facade입니다. World Context parameter가 있는 함수는 모두 유효한 game world가 필요합니다. 안정 API 중 CancelLevelHandoff만 예외이며 Ticket만 받습니다.

#안정 Surface Query

bool이 false이거나 Detailed Status가 성공이 아니면 Hit 출력을 사용하지 마세요.

#안정 좌표 API

이 함수들의 Blueprint Category는 PlanetX|Coordinates입니다.

#안정 Travel API

PlanetX는 Handoff 상태를 준비하고 복원하지만 Open Level 호출, 대상 Actor Spawn, Possess 또는 GameMode 선택은 하지 않습니다. 이 과정은 게임 코드가 담당합니다.

#Advanced Travel과 상태 조회

• Travel: PrepareTravel, ResumePendingTravel, BeginReturnLevelHandoff, ResolveLevelHandoffEntryTransform
• 저장 상태: GetStoredLevelHandoffCapture, GetTransitionJourney, GetActiveTransitionJourneys
• Runtime 상태: GetActorRuntimeContext, GetMovementRuntimeState, GetMovementRuntimeStates
• Transition 상태: GetTransitionRuntimeResult, GetTransitionRuntimeResults, GetTransitionManagedActorState
• Transition 계산과 Sync: EvaluateTransitionCylinderState, CaptureTransitionActorSyncPose, ApplyTransitionActorSyncPose

PrepareTravel은 FPlanetXTravelRoute를 받습니다. Planet Actor 후보가 정확히 하나일 때만 자동 선택합니다. 명시적인 index 0은 유효하며, PlanetActorIndex와 PlanetBindingId를 모두 지정하면 같은 후보를 가리켜야 합니다.

#Advanced Data, Preview와 Diagnostics

• Section과 Level Pair: GetSectionTransform, GetSectionDesc, GetSectionRuntimeState, GetLevelPair, GetLevelPairForSection
• Coordinate Frame: ResolveCoordinateFrame
• Runtime Preview: LoadRuntimePreview, SetRuntimePreviewVisible, UnloadRuntimePreview, GetRuntimePreviewStatus
• Validation: ValidatePlanetAsset
• Diagnostics: DiagnoseProxySync, ResolvePlanetAlignmentForSection, DiagnoseSectionPlanetOverlapFromBounds
• 일시적 Debug Draw: DrawPlanetDebug, DrawSectionDebug, DrawActorContextDebug, DrawCaptureStackDebug

Debug Draw 함수는 성공값을 반환하지 않습니다. Validation 함수 실행 성공과 issue가 없는 결과는 서로 다른 조건입니다.

#APlanetXPlanetActor

헤더: PlanetX/Actors/PlanetXPlanetActor.h

RegisterToPlanetXRuntime은 등록 성공 여부를 반환하고 UnregisterFromPlanetXRuntime은 void입니다. 두 함수의 Blueprint Category는 PlanetX|Planet입니다.

Actor는 Root, PlanetComponent, PlanetProxyComponent, TransitionMorphComponent, SkyAtmosphereComponent, VolumetricCloudComponent를 Blueprint Read Only Reference로 제공합니다. Planet Asset은 Planet Component에 지정하고 Planet ID와 Binding ID가 모호하지 않도록 관리하세요.

#APlanetXTransitionEndpoint

헤더: PlanetX/Actors/PlanetXTransitionEndpoint.h

이 Actor에는 Blueprint-callable 함수가 없습니다. Reflection Property가 제작 계약을 구성합니다.

ID는 resolve된 Planet Asset에 실제로 존재하는 Section과 Level Pair와 일치해야 합니다. Ground Endpoint에는 Planet Asset이 필요하며, Orbit Endpoint는 가능한 경우 Planet Actor에서 추론합니다.

#APlanetXEnvironmentManager

헤더: PlanetX/Actors/PlanetXEnvironmentManager.h

주요 Environment Command 중 bool을 반환하는 함수는 ValidateEnvironmentBinding뿐입니다. void 변경 함수를 호출하기 전에 검증하고 보고된 Binding 문제를 먼저 해결하세요.

Override Apply와 Restore를 한 쌍으로 관리하세요. void Command는 성공 결과를 제공하지 않으므로 먼저 Binding을 검증하고, 제공되는 경우 대응하는 Active State Query를 확인합니다.

#APlanetXRuntimePreviewActor

헤더: PlanetX/Preview/PlanetXRuntimePreviewActor.h

일반적인 Runtime 사용에서는 직접 Spawn하기보다 UPlanetXSubsystem::LoadRuntimePreview를 권장합니다.

Loaded와 Renderable은 서로 다른 상태입니다. Runtime Budget에 따라 Realized Component 수가 Renderable Component 수보다 작을 수 있습니다.

#UPlanetXCoordinateComponent

헤더: PlanetX/Components/PlanetXCoordinateComponent.h

Coordinate Component는 표준 PlanetX pose를 저장하고 Owner가 사용할 Planet, Binding, Section과 Coordinate Frame을 resolve합니다. Reference를 설정하고 Planet Actor가 등록됐는지 확인한 뒤, 관련 등록이나 Streaming 상태가 바뀌면 RefreshRuntimeContext를 호출하세요.

#안정 좌표 상태와 정책

Editor-callable helper인 RefreshCoordinateSnapshot, PullFromWorld, PushToWorld, CaptureOwnerTransformToPlanetX, ApplyPlanetXTransformToOwner는 저장 pose와 Owner Transform을 명시적으로 동기화합니다.

#안정 Surface Frame과 Vector

이 표의 함수는 모두 bool을 반환합니다. false 뒤에는 출력을 사용하지 마세요.

#Advanced 조회와 Spatial Loading

RefreshReferenceDetails, GetResolvedPlanetComponent, GetCachedRuntimeContext, GetRepresentationDomain은 resolve된 Reference와 Context를 제공합니다. 현재 Spatial Loading 정책에는 GetActorSpatialLoadingPolicy, ShouldForceOwnerAlwaysLoaded, ApplySpatialLoadingPolicyToOwner를 사용합니다. Data Layer와 Streaming Source는 프로젝트가 관리합니다.

#UPlanetXMovementComponent

헤더: PlanetX/Components/PlanetXMovementComponent.h

Owner에 Coordinate Component와 commit된 Runtime Context가 필요합니다.

안정 함수는 모두 bool을 반환합니다. GetMovementRuntimeState와 GetCommittedRuntimeContext는 승인된 Advanced 상태 조회입니다. Representation이 바뀌는 동안 다른 Movement Component나 Physics Body가 속도를 소유한다면 Movement Handoff를 사용하세요.

#UPlanetXPlanetComponent

헤더: PlanetX/Components/PlanetXPlanetComponent.h

등록하려면 유효한 World, Planet Asset과 Identity가 필요합니다. 여러 Component가 같은 Planet ID를 사용한다면 Binding ID로 대상을 명확하게 구분하세요.

#UPlanetXPlanetProxyComponent

헤더: PlanetX/Components/PlanetXPlanetProxyComponent.h

#Planet 전체 표현

• Source 설정·조회: SetPlanetAsset, GetPlanetAsset, SetPlanetMaterialOverride, GetPlanetMaterialOverride, SetPlanetSphereMeshOverride, GetPlanetSphereMeshOverride
• 표현 Rebuild·제거: RefreshProxy, RebuildPlanetProxy, RebuildSectionProxiesFromPlanetAsset, ClearSectionProxies
• Visibility: SetPlanetProxyVisible, SetSectionProxiesVisible, SetSectionProxyMorphAlpha, GetSectionProxyMorphAlpha
• 상태 조회: GetPlanetSphereComponent, GetSectionProxyResidencyState, GetSectionProxyRealizedComponentCount

RebuildSectionProxiesFromPlanetAsset은 생성 수를 반환합니다. 이 그룹의 나머지 Rebuild, Clear와 Visibility Command는 void이므로 결과가 중요하다면 Residency와 Count를 확인하세요.

#Section과 Layer 표현

Count를 반환하는 변경 함수에서 0은 일치해 변경된 Entry가 없다는 뜻입니다. Boolean 변경 함수는 요청 작업의 성공 여부를 반환합니다.

Debug 표현에는 SetDebugOverlaySettings, GetDebugOverlaySettings, SetDebugOverlaysVisible를 사용합니다.

#UPlanetXTransitionMorphComponent

헤더: PlanetX/Components/PlanetXTransitionMorphComponent.h

Build와 Apply Command는 void입니다. Compatibility와 Renderability Query로 실제 선택된 표현 경로를 확인하세요.

#Viewpoint와 Travel Receiver

UPlanetXViewpointComponent는 PlanetX/Components/PlanetXViewpointComponent.h에 선언됩니다. GetTransitionFrame과 MapViewDirectionToMovement는 bool을 반환하며 성공했을 때만 출력을 사용합니다.

UPlanetXTravelReceiverComponent는 PlanetX/Components/PlanetXTravelReceiverComponent.h에 선언됩니다. Blueprint-callable 함수는 없습니다. bAutoResumePendingTravel, bApplyControlRotation, ArrivalRetryTimeoutSeconds를 설정하고 bLastResumeSucceeded, LastResumeError, State를 확인하거나 OnTravelResumed, OnTravelResumeFailed에 Bind합니다. 이 Component는 Level Open, Spawn, Possess 또는 GameMode 선택을 담당하지 않습니다.

#UPlanetXPlanetAsset

헤더: PlanetX/Assets/PlanetXPlanetAsset.h

#Identity와 Revision 조회

모두 Blueprint Pure 조회입니다. Revision이 0이면 대응하는 출력이 아직 한 번도 성공적으로 게시되지 않았다는 뜻일 수 있습니다.

#Visual Authoring 변경

아래 함수는 별도 표시가 없으면 PlanetX|Visual Blueprint Category에 속하며 bool을 반환합니다.

MarkVisualPreviewBuildSucceeded는 PlanetX|Revision Category의 void Blueprint-callable 함수입니다. Preview Build가 성공한 뒤에만 호출하세요. Revision과 Staleness 추적을 일관되게 유지하려면 직접 Field를 바꾸기보다 이 함수와 Planet Asset Editor를 사용합니다.

#UPlanetXSurfacePreset

헤더: PlanetX/Visual/Assets/PlanetXSurfacePreset.h

이 Blueprint Type에는 Blueprint-callable 함수가 없습니다. 편집 가능한 Field는 PresetId, DisplayName, PresetType, CompletionSettings, PaddingSettings, BaseSurfaceMaterial, OptionalBiomeMask, OptionalHeightMask입니다. PresetId를 안정적으로 유지하고 참조한 Material과 Texture가 Cook에 포함되는지 확인하세요.

#Project Settings

UPlanetXRuntimeDeveloperSettings는 PlanetX/Settings/PlanetXRuntimeDeveloperSettings.h에 선언됩니다. Project-wide Config Field는 RuntimeBudgetPolicy이며 기본값은 EPlanetXRuntimeBudgetPolicy::FollowEngineScalability입니다.

UPlanetXRenderingDeveloperSettings는 PlanetX/Settings/PlanetXRenderingDeveloperSettings.h에 선언됩니다. Config Field는 기본값이 true인 bEnableLensFlares와 기본값이 3이고 유효 범위가 0~3인 LensFlareQuality입니다. ApplyConsoleVariables는 C++ Member이며 Blueprint 함수가 아닙니다.

헤더: PlanetX/Blueprint/PlanetXMovementHandoffLibrary.h

클래스: UPlanetXMovementHandoffLibrary

Blueprint Category: PlanetX|Movement Handoff

이 Library는 versioned Movement Snapshot을 저장하고 FPlanetXMovementHandoffHandle을 반환합니다. 이후 호출에서 이 Handle을 resolve, apply, consume 또는 cancel합니다. 공개 함수 10개는 모두 bool과 FPlanetXMovementHandoffResult를 제공하므로 출력 사용 전에 두 결과를 함께 확인하세요.

#Capture

FPlanetXMovementHandoffCaptureRequest는 Source·Target Coordinate Frame, Source·Target Actor Space State와 Snapshot Lifetime을 지정합니다.

#Resolve와 Apply

Apply Option은 연속성, Source 비활성화, Target 활성화, Component Velocity 갱신, 성공 시 Consume과 Same Actor 강제를 제어합니다. Switch가 실패했다면 Component 활성 상태나 Velocity가 의도대로 바뀌었다고 가정하지 말고 Result와 실제 Component를 확인하세요.

#조회와 종료

Actor로 상태를 검색하지 말고 반환된 Handle을 사용하세요. Handle이 invalid, expired, consumed, cancelled 상태이거나 저장된 generation과 일치하지 않으면 실패할 수 있습니다. 전환 직전에 캡처하고, 대상 Frame을 사용할 수 있게 된 뒤 resolve·apply하며, 성공적으로 적용한 뒤에만 consume하세요.

#모듈 설정

게임 모듈의 Build.cs에 PlanetX 런타임 모듈을 추가합니다.

PublicDependencyModuleNames.AddRange(new[] { "PlanetX" });

각 타입을 소유하는 헤더를 Include하세요. 자주 사용하는 진입점은 다음과 같습니다.

• PlanetX/Core/PlanetXTypes.h
• PlanetX/Coordinates/PlanetXTransform.h
• PlanetX/Coordinates/PlanetXCoordinateUtils.h
• PlanetX/Movement/PlanetXMovementTypes.h
• PlanetX/Movement/Handoff/PlanetXMovementHandoffTypes.h
• PlanetX/Travel/PlanetXLevelPair.h
• PlanetX/Transition/PlanetXTransitionTypes.h
• PlanetX/Validation/PlanetXValidation.h

#안정 Transform 계약

FPlanetXTransform은 DataVersion, PlanetId, PlanetBindingId, PlanetFixedPositionCm, PlanetFixedRotation, Scale3D Reflection Field를 가진 Blueprint Type입니다. Position 단위는 cm입니다. UPlanetXSubsystem 또는 UPlanetXCoordinateComponent로 Resolve·Capture하고, World Transform을 Representation과 무관한 저장 Pose로 취급하지 마세요.

#안정 Movement Handoff 타입

안정 Handoff 계약은 다음을 포함합니다.

• FPlanetXMovementHandoffHandle: SnapshotId, Generation
• FPlanetXMovementHandoffCaptureRequest: Source·Target Frame, Source·Target Actor Space State, LifetimeSeconds
• FPlanetXMovementHandoffApplyOptions: Continuity, Activation, Velocity Update, Consume와 Same Actor 정책
• FPlanetXMovementHandoffSnapshot: Version, Handle, Source Identity와 Frame, Movement State, Capture Time, Lifetime, State
• FPlanetXMovementHandoffResult: bSucceeded, Error, Handle, DiagnosticContext

안정 Reflection Enum에는 EPlanetXTransformSource, EPlanetXMovementHandoffState, EPlanetXMovementContinuityPolicy, EPlanetXMovementVectorSpace가 있습니다. 실제 배포하는 Plugin Version의 헤더를 기준으로 Compile·Serialize하고 숫자 값이나 Layout을 추정하지 마세요.

#Travel Route 선택

FPlanetXTravelRoute는 PlanetX/Transition/PlanetXTransitionTypes.h에 선언되며 World, PlanetId, SectionId, PlanetActorIndex, PlanetBindingId를 포함합니다. PlanetActorIndex 기본값은 INDEX_NONE입니다. 후보가 정확히 하나일 때만 자동 선택하며 0은 첫 번째 deterministic 후보를 명시적으로 선택합니다. 두 Selector를 함께 지정하면 Index와 Binding ID가 같은 후보를 가리켜야 합니다.

#Coordinate와 Validation Helper

FPlanetXCoordinateUtils는 지원 Coordinate 표현 사이의 순수 C++ 변환을 제공합니다. Runtime Registry가 필요한 변환은 UPlanetXSubsystem을 사용하세요. cm 단위, 유한한 값과 정규화된 방향 가정을 지키고 성공값을 항상 확인합니다.

PlanetXValidation은 C++ Tool을 위한 구조화된 Validation을 제공합니다. Severity, Code, Subject와 Remediation Text를 유지하세요. Validation은 Asset을 암묵적으로 Repair하거나 Save하지 않습니다.

#제외되는 구현 표면

생성 Mesh 데이터, Boundary Reconstruction 중간체, Bake Pass, 내부 Runtime Service와 Shard·Serialization Payload는 선언이 공개되어 있다는 이유만으로 안정 Game Save 또는 Network 계약이 되지 않습니다.

#플러그인이 로드되지 않음

PlanetX.uplugin과 프로젝트의 EngineAssociation을 확인합니다. 현재 기준은 UE 5.8이며 Runtime과 Editor 두 모듈이 있습니다. GeometryProcessing과 PCG 플러그인이 활성화되고 대상 플랫폼 toolchain이 설치되어야 합니다.

Editor 로그에서 module load 실패의 첫 오류를 확인하세요. 이후 compile 오류는 연쇄 결과일 수 있습니다.

#Planet Asset 생성 항목이 없음

• PlanetXEditor 모듈이 로드됐는지 확인
• Content Browser의 올바른 Add 메뉴 사용
• 프로젝트가 Editor target으로 빌드됐는지 확인
• Plugin 활성화 후 Editor 재시작

#Actor가 Planet을 resolve하지 못함

Coordinate Component에서 Reference Planet Actor가 유효하면 Planet ID보다 우선합니다. 해당 Actor의 Planet Component에 Planet Asset이 지정됐는지, runtime 등록이 성공했는지 확인하세요.

여러 Actor가 같은 Planet ID를 쓰면 Planet Binding ID를 명시합니다. Section 드롭다운은 Content Browser 전체가 아니라 현재 World에 배치된 Planet의 enabled Section에서 만들어집니다.

#World Partition 경고

EPlanetXActorSpatialLoadingPolicy::PlanetXManaged는 Orbit Actor를 non-spatial 상태로 유지합니다. ActorManaged를 선택하면 Is Spatially Loaded를 프로젝트가 직접 관리해야 합니다. Data Layer와 Streaming Source는 자동 변경되지 않습니다. 실제 적용 상태는 GetActorSpatialLoadingPolicy, ShouldForceOwnerAlwaysLoaded, ApplySpatialLoadingPolicyToOwner로 확인하세요.

#Scan Sources가 비활성

대상 Planet Asset, Section과 Source World가 유효한지 확인합니다. PIE를 종료하고 외부 Worker가 다른 작업을 소유하지 않는지 확인하세요. External Level Section을 다른 Level에서 열었다면 Editor가 필요한 Level 이동을 요청할 수 있습니다.

#CompletedWithWarnings

BakeData의 SourceOmissions를 확인합니다. Reason, PassId, Actor/Component path, class와 Detail이 저장됩니다.

대표 원인:

• Spline Mesh deformation
• 지원하지 않는 Component class
• Cloth/deformable
• Missing mesh 또는 LOD
• projection range 초과
• unsupported material 또는 sky material
• nondeterministic dynamic source
• 저장되지 않은 PCG managed resource

의도된 제외라면 Source 정책이나 NoBake tag를 명시하고, 보이는 콘텐츠가 빠졌다면 지원되는 Static Mesh/Instance/Landscape 형태로 바꿉니다.

#Bake가 stale

Planet Asset 구조, Section placement, Source World content, Source Material, quality나 visual generation 입력이 바뀌면 revision이 stale이 됩니다. Scan과 plan 재계산 후 다시 Bake하고 Full Validate를 실행합니다.

#External Bake Monitor가 열리지 않음

브라우저 Monitor는 선택 기능이며 Bake를 소유하지 않습니다. 로컬 서비스나 시스템 브라우저를 열지 못해도 External Bake는 계속되므로 Editor 상태와 Unreal 로그에서 진행 상황을 확인하세요. 전체 Monitor URL에는 로컬 세션 token이 포함되므로 복사하거나 공유하지 마세요.

Bake가 진행되는 동안에는 Direct Worker가 Monitor를 호스팅합니다. Worker가 종료되면 서비스도 끝나므로 완료 후 기존 탭에 Disconnected가 표시될 수 있습니다. Unreal Editor로 돌아가거나 다시 실행한 뒤 Open External Bake Monitor를 선택하면 최신 durable result를 다시 호스팅할 수 있습니다. 이전 탭은 자동으로 이전되지 않습니다.

#큰 package

512 MiB 초과 package는 warning, 1 GiB 초과는 publication failure입니다. 큰 indivisible source를 분리하고 partition/shard 결과와 instance aggregation을 검토하세요. source spool 128 MiB 목표는 최종 uasset 크기가 아님을 유의합니다.

#RuntimeUnavailable

Planet Actor 등록, Planet Asset, 현재 World와 World Runtime 서비스가 준비되지 않은 상태입니다. Begin Play/streaming 순서를 확인하고 Planet Component의 RefreshRuntimeRegistration과 참가 Actor의 RefreshRuntimeContext를 사용합니다.

#표면 Query가 실패

Detailed query status로 InvalidInput, RuntimeUnavailable, Miss를 구분합니다. Ray direction이 0이 아닌지, Planet/Binding filter가 현재 World에 존재하는지, Section bounds와 BakeData가 유효한지 확인하세요.

#ResumePendingTravel 실패

동시 Travel에서는 Ticket/Journey identity를 gameplay 상태에 저장하고 무인자 resume에 의존하지 마세요.

#잘못된 위치 또는 회전

Level Handoff Ground 위치는 capture에 저장된 SectionLocalToGroundWorld mapping이 authoritative합니다. Source/Target Planet Actor Transform을 임의로 맞춰 덮어쓰지 마세요. DiagnoseProxySync와 ResolvePlanetAlignmentForSection으로 mapping을 검사합니다.

#속도 손실

Movement Component나 Physics Body를 교체했다면 Movement Handoff snapshot을 Capture/Apply하고 결과가 consumed됐는지 확인합니다.

PlanetX는 Editor UI, Blueprint query, console stat과 dump 명령을 제공합니다.

#실시간 Stat

Stat PlanetXMemory
Stat PlanetXResources
Stat PlanetXProxy
Stat PlanetXProxyDetail
Stat PlanetXRuntime

Memory는 runtime resource와 budget을, Resources는 수량을, Proxy는 렌더 coverage를, Runtime은 service 비용을 보여줍니다. 통계 World는 PIE/Game World와 선택된 Preview World 우선순위에 따라 결정됩니다.

#Dump 명령

PlanetX.ProxyStats.LogIntervalSeconds는 반복 proxy log 주기를, PlanetX.MemoryBudgetMB는 진단용 memory budget을 조정합니다.

#Blueprint 진단

UPlanetXSubsystem에서 Actor runtime context, movement state, transition result, managed actor state, Section runtime state와 Journey를 조회할 수 있습니다. DrawPlanetDebug, DrawSectionDebug, DrawActorContextDebug, DrawCaptureStackDebug는 개발 build의 공간 상태 확인에 사용합니다.

#지원 자료 수집

문제를 재현한 World, Planet/Binding/Section ID, Asset validation result, Proxy Bake revision과 omission, Travel Result error, 관련 Stat/Dump를 함께 기록하세요. 경로에 민감 정보가 있을 수 있으므로 외부 공유 전 redaction을 확인합니다.

PlanetX 1.0.1이 이제 Fab에 공개되었습니다. 이번 유지보수 릴리스는 Browser Monitor 복구, PlanetX Mode Transform 편집, presentation 제어를 개선합니다.

• 공개일: 2026년 8월 23일

#수정 사항

• 외부 Browser Monitor: 브라우저 acknowledgement가 없더라도 Monitor endpoint나 외부 Bake가 실패한 것처럼 처리되지 않습니다. 브라우저 실행은 best-effort이며 endpoint는 복구를 위해 계속 사용할 수 있습니다.
• PlanetX Mode Transform Gizmo: 일반 Actor와 다중 선택은 Unreal Engine Native Transform Gizmo로 fallback됩니다. PlanetX 전용 Gizmo는 Coordinate Component가 있는 Actor 하나를 선택한 경우에만 사용합니다.
• Global Presentation: UPlanetXCoordinateComponent에 Presentation Scope가 추가되었습니다. Actor가 Ground, Orbit, Transition에서 계속 보여야 하면 Global로 설정하세요. 이는 presentation 전용이며 Representation Domain, coordinate, Proxy Bake 대상 여부, physical-frame 소유권은 바꾸지 않습니다.

#호환성 참고

• 기존 콘텐츠는 기본값 Domain Only를 유지하며 기존 presentation 동작을 보존합니다.
• 세 상태에서 authored presentation을 의도적으로 유지해야 하는 Actor에만 Global을 사용하세요.
• Global은 Representation Domain 양방향 변환이 아닙니다. Ground와 Orbit은 계속 coordinate와 loading 계약입니다.

#배포 조건

PlanetX는 Fab을 통해 배포되며, 취득과 사용 조건은 Fab End User License Agreement를 따릅니다.

여기 기재된 고지는 Fab End User License Agreement를 대체하거나 변경하지 않으며, PlanetX에 별도의 이용 조건을 추가하지 않습니다.

#개발 지원 프로그램 고지

이 제품은 KRAFTON JUNGLE GameTech Lab의 개발자 지원 프로그램인 Epic Project에 참여하며 본인(당사)이 독자적으로 개발한 결과물입니다. 이 제품에 대한 모든 권리와 권원, 이익은 전적으로 본인(당사)에게 귀속됩니다. Krafton, Inc.는 이 제품의 개발과 배포에 관여하지 않았으며, 명시적이거나 묵시적인 일체의 진술과 보증을 부인하고, 이 제품의 사용으로 발생하는 어떠한 결과에 대해서도 책임을 지지 않습니다.

위 고지의 원문은 다음과 같습니다.

#Solar System Scope 행성 표면과 우주 배경 텍스처

PlanetX의 샘플 행성 표면 텍스처와 우주 배경 텍스처는 Solar System Scope / INOVE가 제공하는 텍스처 데이터를 포함하거나 이를 기반으로 제작되었습니다. 이 텍스처를 참조하는 Unreal Engine Material과 Material Instance도 같은 범위에 포함됩니다.

#포함 위치

텍스처 에셋은 모두 Content/PlanetX/Textures/Samples/Solar_System_Scope 아래에 있습니다.

위 텍스처를 참조하는 샘플 행성 Material Instance와 우주 배경 Material도 이 고지의 적용 대상입니다.

#변경 사항

• 원본 행성 표면 텍스처와 우주 배경 텍스처를 Unreal Engine 콘텐츠 에셋 형식으로 임포트하고 변환했습니다.
• 변환한 텍스처를 샘플 행성 Material, 우주 배경 Material과 관련 Texture, Material, Material Instance 에셋에 통합했습니다.
• Unreal Engine의 임포트, 압축, 밉맵, 샘플링, Material 설정에 따라 원본 텍스처와 다르게 표현될 수 있습니다.

#적용 범위

CC BY 4.0은 위에 명시한 행성 표면 텍스처와 우주 배경 텍스처, 그리고 이를 사용하는 콘텐츠에만 적용되며, PlanetX의 소스 코드나 그 밖의 자체 제작 에셋에는 적용되지 않습니다.

이 고지의 어떤 내용도 Solar System Scope 파생 콘텐츠에 대해 CC BY 4.0이 부여하는 권리를 제한하지 않습니다.

Solar System Scope와 INOVE는 PlanetX를 보증하거나 후원하지 않으며, 공식적으로 지원하지 않습니다.

#그 밖의 구성 요소

위에 명시한 행성 표면 텍스처와 우주 배경 텍스처 외에 PlanetX가 사용하는 외부 저작물은 없습니다. 그 밖의 소스 코드, Material, Mesh, 아이콘, 문서, Proxy Bake Monitor 웹 리소스는 모두 LabX가 직접 제작했습니다. 문서 사이트는 외부 스크립트, 폰트, 스타일시트를 내려받지 않으며 네트워크 연결 없이 동작합니다.