Advanced Guide — Multi-Level Handoff
This guide configures the Orbit World and Ground World as separate Levels and uses PlanetX Level Handoff to carry the player's pose and movement state between them.
When finished, you will have:
- One Planet Asset
- One Orbit-only Level
- One Ground Level used for actual gameplay
- One Level Handoff Section
- A baked Section Proxy
- A baked Runtime Preview World
- A runtime planet visual
- A PlanetX Planet Actor in the Orbit World
- An Environment Manager
- An Orbit Transition Endpoint
- A Player Actor that travels Orbit → Ground → Orbit
Before using this advanced workflow, complete Start Here — Same World Quick Start. This guide assumes that the basic Planet Asset, Proxy Bake, Visual Build, PlanetX Mode, and transition concepts are already familiar.
#Before you begin
Level Handoff requires two separate Levels. This guide uses the following example names:
L_Orbit
L_Ground#L_Orbit
This Level displays the planet from space and lets the player approach it.
You will later place the following items in it:
L_Orbit
├─ PlanetX Planet
├─ PlanetX Environment Manager
├─ PlanetX Transition Endpoint
└─ Orbit Player / SpaceShip#L_Ground
This is the existing Unreal Engine Level used for actual surface gameplay.
Build its Landscape, Static Meshes, Foliage, and Gameplay Actors through your normal Unreal Engine workflow.
L_Ground
├─ Landscape
├─ Buildings
├─ Foliage
├─ Gameplay Actors
└─ Ground PlayerThe two Levels must be different, saved World Assets:
L_Orbit != L_GroundLevel Handoff does not allow Orbit World and Ground World to reference the same package.
#Phase checkpoints
This guide is intentionally detailed because Level Travel, Pawn lifetime, and possession remain game-owned. Treat the 34 steps as five phases and do not continue until the current phase passes.
| Phase | Steps | Required result before continuing |
|---|---|---|
| A. Author the External Section | 1-10 | Section is Level Handoff, Bake is Linked, Runtime Preview is linked and renderable, Planet Visual Build succeeds |
| B. Prepare both Worlds | 11-16 | Orbit Planet is aligned; exactly one Environment Manager and Orbit Endpoint exist; Orbit and Ground Players have the required Components |
| C. Travel Orbit → Ground | 17-25 | Surface Query hits the intended Section; Begin Level Handoff succeeds; the exact Ticket survives travel; completion returns a valid Ground arrival and Journey ID |
| D. Return Ground → Orbit | 27-30 | Begin Return Level Handoff succeeds; the Return Ticket survives travel; applying it completes the Journey |
| E. Validate the complete flow | 31-34 | Runtime Preview becomes renderable, Full Validate has no Error, and the complete Orbit → Ground → Orbit test succeeds |
Step 26 is an optional Travel Receiver alternative. Choose either the explicit completion path in Steps 22-25 or the Travel Receiver path; do not combine both during the first test.
#1. Prepare a Planet Asset
Create one Planet Asset by following Create Your First Planet Asset. Complete the following steps, then return here:
- Create the Planet Asset
- Set its Planet ID
- Set its Planet Radius
- Save the Planet Asset
You do not need to create a Section manually yet.
The first Proxy Bake from the Ground Level creates the required Section and Level Pair automatically.
#2. Open the Ground Level
Open L_Ground first:
L_GroundProxy Bake uses the currently open Ground Level as its source World. Take care not to Bake while L_Orbit is open by mistake.
The Ground Level must contain at least one supported Proxy Bake source, such as:
- Landscape
- Static Mesh
- Instanced Static Mesh
- Hierarchical Instanced Static Mesh
- Foliage
We recommend saving the Level before continuing. Stop PIE or Simulate if either is running.
#3. Open Proxy Bake Editor
With L_Ground open, use the Unreal Editor Tools menu, find the PlanetX section, and select Proxy Bake Editor. Use this single path for the first External Section.
First, confirm Target Planet Asset:
1 Target Planet Asset
└─ Planet AssetAssign the Planet Asset created in the previous step. There is no existing Section to select before the first Bake.
#4. Set Runtime Role to External Level
Expand 2 Runtime Role in Proxy Bake Editor and set Presentation to:
Presentation
└─ External LevelThe UI calls this option External Level; the Planet Asset stores the Section using the Level Handoff runtime role.
External Level follows this structure:
Orbit World
↓
PlanetX Runtime Preview
↓
The game performs World Travel
↓
Ground World#Confirm Ground World
Ground World automatically displays the currently open L_Ground:
Ground World
L_GroundThis is not a manually selected value. It is determined from the source World used by the current scan and Bake.
#Assign Planet World
Selecting External Level reveals Planet World. Assign the Orbit Level:
Planet World
L_OrbitThe final setup should read:
Presentation
External Level
Ground World
L_Ground
Planet World
L_OrbitYou do not need to change the Handoff Backend for this Quick Start.
The default contract is stored for an Open Level workflow, but the game Blueprint will perform the actual Open Level call later.
#5. Choose the Source Scope
Expand 3 Source Scope. For a typical first test, choose:
Source Scope
└─ Current LevelThe scopes are:
- Selected Actors — bakes only the currently selected Actors.
- Current Level — bakes Actors in the current Ground Level and is the simplest first test.
- Loaded Levels — also includes currently loaded Streaming Levels or Level Instances.
- Reviewed Set — reuses a previously reviewed source set.
Unless the project requires otherwise, choose this Bake Quality:
High (Recommended)#6. Scan the Ground sources
Select Scan Sources or press F5:
Scan SourcesPlanetX inspects the current Ground Level and discovers sources that can be converted into a Proxy.
#Review Source Review
You do not need to edit every discovered item. Check whether:
- An Actor you intended to use was not discovered
- A source is marked
Manual Review - A source is marked
Unsupported - No source is included in the Bake
- An unintended Actor is included
Supported Landscapes, Static Meshes, ISM/HISM, and Foliage are normally classified automatically.
If you manually change a source's Use or Role, select:
Apply Source ChangesNo apply step is needed if you made no changes.
#7. Run Proxy Bake
After Source Review, select BAKE IN EDITOR or press Ctrl+B:
BAKE IN EDITORThe Bake generates Ground geometry and the additional runtime data required by Level Handoff.
For the first Bake of a Planet Asset, PlanetX automatically creates:
Planet Asset
├─ Section
├─ Level Pair
├─ Proxy Bake Data
└─ Runtime Preview World#What is Runtime Preview World?
An External Level setup does not load the complete L_Ground into Orbit World.
Proxy Bake instead creates a Runtime Preview World containing only the visual representation. It provides a Ground-like appearance as the player approaches the planet.
It is not a copy of the gameplay Level and does not reproduce:
- GameMode
- PlayerStart
- Pawn
- Controller
- Gameplay Actor logic
- Gameplay collision
- Navigation
The two Worlds have different responsibilities:
Runtime Preview World
= Visual representation during transition
L_Ground
= Actual gameplay WorldThis distinction is essential when working with Level Handoff.
#8. Review the Bake result
After the Bake completes, return to Planet Asset Editor and select the new Section under Sections.
Confirm approximately the following state:
| Item | Expected state |
|---|---|
| Runtime Role | Level Handoff |
| Ground World | L_Ground |
| Planet / Orbit World | L_Orbit |
| Bake | Linked |
| Runtime Preview | Connected |
| Transition | Available |
In Proxy Bake Editor, use Open Results or Ctrl+Shift+O to inspect the latest result in the Content Browser.
If a result already exists for the Section, the button may read:
REBUILD IN EDITORThis bakes the existing Section again from the current Ground sources.
#9. Review the Section placement on the planet
Open Preview in Planet Asset Editor.
Unlike a Same World Section, a Level Handoff Section can be placed at any intended location on the planet surface. You can keep its automatically created placement for this first test.
Confirm that:
- The Section Proxy appears on the planet surface
- Its orientation is correct
- It does not overlap another Section
- There is no severe gap against the planet surface
Multiple Ground Levels can be connected to one Planet Asset as separate External Level Sections:
Planet
├─ Section_A → Ground_A
├─ Section_B → Ground_B
└─ Section_C → Ground_CThis Quick Start uses one Section only.
#10. Build the planet visuals
In Planet Asset Editor > Preview, assign the base surface Completion Material:
Preview
└─ Basic
└─ Planet
└─ Completion MaterialLeave Terrain, Padding, and other detailed settings at their defaults for the first pass. Confirm that:
- The entire planet surface renders correctly
- The baked Section appears on the planet
- There is no large empty region around the Section
- Geometry is not severely inverted
If the Preview looks correct, select:
Apply & BuildPlanetX applies the Preview settings to the Planet Asset and generates the final runtime planet visual. Save the Planet Asset after a successful build.
#11. Place the Planet Actor in Orbit World
Open L_Orbit:
L_OrbitSearch Place Actors for PlanetX Planet and place one Actor in the Level.
Under Planet Component, configure:
Planet Asset
→ The Planet Asset created earlier
Auto Register Runtime
EnabledA separate Planet Binding ID is not required for this single-Planet test.
#12. Align the Planet Actor
Open PlanetX Mode and confirm that the newly placed Planet Actor is the Active Planet under Scene.
Even when a Planet Asset contains no Same World Section, PlanetX can derive the alignment anchor from the first valid External Section's Ground Sync Mapping. A planet that uses only Level Handoff therefore does not require an artificial Same World Section.
Run Align in PlanetX Mode.
Align applies the required positional correction without arbitrarily changing the Planet Actor's rotation or scale.
Afterward, Validate should no longer report:
Planet Actor location is not aligned
to the canonical Section's baked Ground Sync Mapping.#13. Add an Environment Manager
Open the Environment Palette in PlanetX Mode. If the current Planet has no Manager, select:
Environment
└─ Add ManagerPlanetX creates an Environment Manager associated with the active Planet.
The Manager is part of the Planet's runtime infrastructure even when individual atmosphere or cloud features are disabled. Keep exactly one Environment Manager for each Planet.
#14. Add the Orbit Transition Endpoint
Open the Transition Palette. If the current Section has no Endpoint, it displays:
No Transition Endpoint for this Level.Select:
Add EndpointBecause L_Orbit is the Level Pair's Planet World, the Endpoint is created with:
Endpoint Role
OrbitPlanetX also associates the correct Planet ID, Section ID, Level Pair ID, Planet Actor, Planet Asset, and Environment Manager.
#Transition Cylinder
Keep the default enabled:
Auto Size Transition Cylinder To Section Bounds
EnabledPlanetX derives the transition region from the Section bounds. Inspect it through the cylinder visualization in the viewport.
The player's Viewpoint moves through the following presentation states while approaching the Section:
Orbit
↓
Transition
↓
Ground PresentationFor an External Level Section, the baked Runtime Preview World provides Ground Presentation. The actual L_Ground is entered later through an explicit Level Handoff call.
#15. Connect the Orbit Player to PlanetX
Open the Pawn or Character Blueprint used in Orbit. This guide calls it:
BP_OrbitPlayerAdd:
BP_OrbitPlayer
├─ Camera Component
├─ PlanetX Coordinate Component
└─ PlanetX Viewpoint Component#Coordinate Component
Configure:
Auto Register Runtime
Enabled
Representation Domain
Orbit
Reference Planet Actor
→ PlanetX Planet in L_Orbit
Reference Section Id
→ The Section baked earlierFor a Pawn placed in the Level, assign the Planet Actor directly in Details.
For a Pawn spawned at runtime, set the Planet Actor reference during BeginPlay and then call Refresh Coordinate Snapshot.
#Viewpoint Component
Keep:
Auto Register Runtime
Enabled
Can Drive Transition State
EnabledConfirm that the PlayerController actually uses BP_OrbitPlayer as its View Target and that the View Target has an active Camera Component.
PlanetX uses this Viewpoint to evaluate Transition Alpha and Runtime Preview loading and visibility.
#16. Prepare the Ground Player
Prepare the Pawn or Character used by L_Ground, for example:
BP_GroundPlayerA Planet Actor is not required in Ground World solely to restore the Level Handoff pose.
PlanetX can convert the Orbit Section coordinates into Ground World coordinates using the Ground Sync Mapping stored by Proxy Bake. The simplest setup is therefore:
L_Ground
└─ BP_GroundPlayerA separate Planet Actor may be required in Ground World if you also need:
- PlanetX Native Movement
- PlanetX radial gravity
- PlanetX Coordinate Query
- Ground-side PlanetX Environment
- A Ground Transition Endpoint
In that case, the Ground Planet Actor and Orbit Planet Actor remain separate Actor instances in separate Worlds.
#17. Store travel data in GameInstance
Open Level destroys the previous World and its Actors. Do not keep a Level Handoff Ticket only in a Level Actor.
Store it somewhere that survives into the next World. A project GameInstance is the simplest option.
Add the following variables to your existing custom GameInstance, or create a Blueprint GameInstance such as:
BP_PlanetXGameInstanceVariables:
Pending PlanetX Ticket
Type = PlanetX Level Handoff Ticket
Active PlanetX Journey Id
Type = Guid
Has Pending PlanetX Ticket
Type = BooleanAssign the class under:
Project Settings
└─ Maps & Modes
└─ Game Instance Class
└─ BP_PlanetXGameInstance#18. Query a landing point from Orbit
Create a landing input in BP_OrbitPlayer, for example:
IA_LandOn its Started event, query the planet surface:
IA_Land (Started)
↓
Get Game Instance Subsystem
Class = PlanetXSubsystem
↓
Make PlanetXSurfaceQueryInput
↓
Query Surface At World Ray Detailed#Surface Query Input
Connect:
Ray Origin World
= Current Camera World Location
Ray Direction World
= Current Camera Forward Vector
Max Distance Cm
= A value large enough to find the intended landing pointWhen more than one Planet exists, expose the advanced pins and specify:
Preferred Planet Id
Preferred Planet Binding IdYou can omit them for a simple single-Planet test.
#Check the query result
Inspect the return status from Query Surface At World Ray Detailed:
Switch on EPlanetXSurfaceQueryStatusContinue only when:
Status == HitBreak the Surface Result and require:
bCanEnterGround == trueThe final flow is:
Query Surface At World Ray Detailed
↓
Status == Hit?
↓ yes
Surface Result.bCanEnterGround?
↓ true
Prepare Level HandoffA Hit with bCanEnterGround == false means the ray found the planet surface, but that location is not within a Section that permits Ground entry.
#19. Prepare the Orbit → Ground Handoff
After a successful Surface Query, call this node on the same PlanetXSubsystem:
Begin Level HandoffConnect:
Begin Level Handoff
Source Actor
= Self
Surface Query
= Surface Query Result from the previous stepOn success, PlanetX captures:
- Planet, Section, and Level Pair
- Current Actor location
- Actor rotation relative to the Section
- Ground landing location
- Control Rotation
- Current velocity when available
- Location data required for the return to Orbit
- Target Ground World
The Level has not changed yet.
#20. Store the Handoff Ticket
Branch on the Return Value from Begin Level Handoff:
Begin Level Handoff
↓
BranchIf it is false, inspect Out Result.Error and do not open the Level.
If it is true, store the complete Out Ticket in the GameInstance:
Get Game Instance
↓
Cast to BP_PlanetXGameInstance
↓
Set Pending PlanetX Ticket
= Out Ticket
Set Has Pending PlanetX Ticket
= trueStore the complete struct rather than copying only selected values. The Ticket includes both the travel identity and destination World.
#21. Open the actual Ground Level
Break Out Ticket and read:
Target WorldFor this Quick Start, it should reference:
L_GroundIn the game Blueprint, call Open Level (by Object Reference) using the Ticket's Target World.
IA_Land
↓
Surface Query
↓
Begin Level Handoff
↓
Success?
↓
Store Ticket in GameInstance
↓
Break PlanetX Level Handoff Ticket
↓
Target World
↓
Open LevelThis Quick Start uses the standard Open Level workflow.
#22. Spawn and possess the Ground Player first
Configure the project's GameMode to create the Ground Player when L_Ground opens. For example:
Default Pawn Class
BP_GroundPlayerPlanetX does not perform:
Spawn Pawn
Possess Pawn
Choose PlayerStart
Choose GameModeBP_GroundPlayer should spawn and be controllable when you run the Ground Level without PlanetX.
#23. Apply the stored Ticket to the Ground Player
Apply the Ticket to BP_GroundPlayer after possession, such as from the Pawn's Event Possessed.
Read the Ticket from GameInstance:
Event Possessed
↓
Get Game Instance
↓
Cast to BP_PlanetXGameInstance
↓
Has Pending PlanetX Ticket?When true, obtain PlanetXSubsystem and call:
Complete Level HandoffConnect:
Ticket
= GameInstance.Pending PlanetX Ticket
Target Actor
= Self
Apply Control Rotation
= trueThe complete flow is:
Event Possessed
↓
Has Pending PlanetX Ticket?
↓ true
Complete Level Handoff
Ticket = Stored Ticket
Target Actor = SelfOn success, PlanetX applies the captured landing state to the current Ground Pawn.
#24. Store the Ground arrival result
Check the Return Value from Complete Level Handoff.
On success, store Out Result.JourneyId in GameInstance:
Complete Level Handoff
↓
Success?
↓ true
Break PlanetX Level Handoff Result
↓
Journey Id
↓
GameInstance.Active PlanetX Journey IdThen set:
Has Pending PlanetX Ticket
= falseOrbit → Ground travel is now complete, and the internal Journey state is:
Ground ActiveKeep the Journey Id; it is required to return from Ground to Orbit.
#25. Verify the Ground arrival pose
After a successful Handoff, the Ground Pawn should move away from its initial PlayerStart pose to the Ground location corresponding to the Section point chosen in Orbit.
PlanetX follows this relationship:
Section Local position captured in Orbit
↓
Ground Sync Mapping
↓
World position in L_GroundConfirm that:
- The Pawn arrives in the expected Ground region
- The Actor does not face an unrelated direction
- Camera orientation does not jump severely
- Velocity continues according to the intended policy
- Existing Ground gameplay works normally
This arrival-pose restoration works even when Ground World has no Planet Actor.
#26. Simpler arrival option: Travel Receiver
If the current World is guaranteed to have exactly one matching Pending Travel, you may use:
PlanetX Travel Receiver ComponentAdd it to the Ground Pawn and keep:
Auto Resume Pending Travel
Enabled
Apply Control Rotation
EnabledIf PlanetX Runtime is not ready immediately after the World opens, Travel Receiver retries for a limited period. The default timeout is:
15 secondsSuccess invokes:
On Travel ResumedFinal failure invokes:
On Travel Resume FailedAutomatic selection is permitted only when exactly one Pending Travel matches the current World:
| Pending count | Behavior |
|---|---|
| 0 | Treat as a normal spawn |
| 1 | Restore that travel |
| 2 or more | AmbiguousPendingTravel |
For multiple players or concurrent travel, use the explicit Ticket + Complete Level Handoff workflow described above.
#27. Prepare the Ground → Orbit return
Create a return input on the Ground Player, for example:
IA_ReturnOrbitRead the saved Journey ID from GameInstance:
IA_ReturnOrbit (Started)
↓
Get Game Instance
↓
Cast to BP_PlanetXGameInstance
↓
Get Active PlanetX Journey IdCall this PlanetXSubsystem node:
Begin Return Level HandoffConnect:
Journey Id
= Active PlanetX Journey Id
Source Actor
= Self
Resume Alpha
= 0The default Resume Alpha of 0 is suitable for this Quick Start.
Success produces a new Return Ticket, which is distinct from the original Orbit → Ground Ticket:
Orbit → Ground Ticket
!=
Ground → Orbit Ticket#28. Store the Return Ticket and open Orbit World
After Begin Return Level Handoff succeeds, store the Return Ticket in the same GameInstance variable:
Pending PlanetX Ticket
= Return Ticket
Has Pending PlanetX Ticket
= trueIts Target World should reference:
L_OrbitUse it to open the Level:
Begin Return Level Handoff
↓
Success?
↓
Store Return Ticket
↓
Break Ticket
↓
Target World = L_Orbit
↓
Open Level#29. Apply the return state in Orbit World
When L_Orbit opens again, BP_OrbitPlayer must be spawned and possessed.
Read the Pending Ticket from GameInstance and call Complete Level Handoff in the same way used on Ground:
BP_OrbitPlayer
Event Possessed
↓
GameInstance.Has Pending PlanetX Ticket?
↓ true
Complete Level Handoff
Ticket = GameInstance.Pending PlanetX Ticket
Target Actor = SelfOn success, clear:
Has Pending PlanetX Ticket
= falseThe complete Journey should progress through:
Orbit
↓
Pending Orbit To Ground
↓
Ground Active
↓
Pending Ground To Orbit
↓
Completed#30. If Orbit restoration runs before runtime registration
Immediately after Orbit World reopens, the Planet Actor may register with PlanetX Runtime at a slightly different time from Player creation.
A manual Complete Level Handoff call made too early can therefore fail temporarily.
For a single-player Quick Start, you may add PlanetX Travel Receiver Component to the Orbit Player:
BP_OrbitPlayer
└─ PlanetX Travel Receiver ComponentAuto Resume Pending Travel
Enabled
Apply Control Rotation
EnabledTravel Receiver retries for a limited time while waiting for Planet Runtime registration.
Do not also call manual Complete Level Handoff for the same arrival.
#31. Verify Runtime Preview behavior
Before traveling to the actual Ground Level, approach the planet in Orbit.
As the Viewpoint enters the Transition Endpoint region, PlanetX loads the External Level Section's Runtime Preview World as required.
The intended visual sequence is:
Far away
Section Proxy
↓ approach
Transition
Proxy / Morph / Runtime Preview transition
↓
Ground Presentation
Runtime Preview WorldThe game has not yet traveled to L_Ground. The following processes are independent:
[Visual transition]
Display Runtime Preview inside Orbit World
[Gameplay travel]
Begin Level Handoff
→ Game calls Open Level
→ L_GroundKeeping them separate makes Level Handoff issues much easier to diagnose.
#32. Validate before running
Return to Orbit World and open the Validate Palette in PlanetX Mode. You can also use Diagnostics in Planet Asset Editor.
For this Quick Start, the following conditions should have no errors:
- The correct Planet Asset is assigned to the Planet Actor
- The External Level Section is valid
- Orbit World and Ground World are different
- Ground Sync Mapping is valid
- Proxy Bake Data is connected
- Runtime Preview World is connected
- The Runtime Preview Bake revision is current
- Runtime Preview contains renderable content
- Exactly one Orbit Transition Endpoint exists for the Section
- Exactly one Environment Manager exists
- The Planet Actor is aligned to the canonical External Section mapping
Resolve Validation Errors before starting PIE.
#33. Test the complete flow
Start PIE from L_Orbit.
#Step 1: Verify Orbit
Confirm that:
- The planet renders correctly
- The Section Proxy is visible
- The Player can be controlled
- The Planet is registered with PlanetX Runtime
#Step 2: Approach the planet
Move toward the Section and confirm:
Orbit
→ Transition
→ Ground PresentationRuntime Preview should appear when required.
#Step 3: Use the landing input
Aim the camera at the Section and trigger IA_Land:
Surface Query Hit
→ Begin Level Handoff succeeds
→ Store Ticket
→ Open L_Ground#Step 4: Arrive on Ground
After the Ground Player is spawned and possessed:
Complete Level Handoff
→ Apply stored Ground pose
→ Journey = Ground Active#Step 5: Return to Orbit
Trigger IA_ReturnOrbit:
Begin Return Level Handoff
→ Create Return Ticket
→ Open L_Orbit
→ Apply Return Ticket
→ Journey Completed#34. Inspect PlanetX Runtime Palette
During PIE, use the Runtime Palette in PlanetX Mode to inspect:
- Planet registration
- Current Transition State
- Transition Alpha
- Section Context
- Runtime Preview state
- Ground Presentation readiness
When diagnosing Level Handoff, distinguish between:
Is this a Runtime Preview problem?and:
Is this an actual World Handoff problem?If Runtime Preview works but the pose is wrong after Open Level, investigate Handoff.
If Preview does not appear while approaching the planet even without travel, investigate Transition and Preview configuration first.
#If Level Handoff does not work
Review these items in order:
- Confirm Proxy Bake Presentation is External Level.
- Confirm Ground World and Planet World are different Levels.
- Confirm Planet World references the actual
L_Orbit. - Run Proxy Bake again so the result is current.
- Confirm Runtime Preview World is connected to the Section in the Planet Asset.
- Confirm the correct Planet Asset is assigned to the Planet Actor in Orbit World.
- Confirm you ran Align in PlanetX Mode.
- Confirm exactly one Orbit Transition Endpoint exists for the Section.
- Confirm exactly one Environment Manager exists.
- Confirm the Player View Target has an active Camera and PlanetX Viewpoint Component.
- Confirm Surface Query actually returns
Hit. - Confirm
Surface Result.bCanEnterGroundistrue. - Confirm
Begin Level Handoffreturnstrue. - On failure, inspect
Out Result.Error. - Confirm the complete Ticket survives World Travel after
Begin Level Handoff. - Confirm the Level opened by the game matches
Ticket.TargetWorld. - Confirm Complete runs after possession of the Ground Pawn.
- If multiple Pending Travels may exist, call
Complete Level Handoffwith the exact saved Ticket instead ofResume Pending Travel. - Confirm you stored the Ground arrival result's
JourneyIdbefore returning to Orbit. - Do not call
Return To Orbit Same Worldfor this workflow. External Level requiresBegin Return Level Handoff.
#Common errors
| Error | Meaning / what to check |
|---|---|
InvalidSurfaceQuery | Review the query result and Section state. |
InvalidLevelPair | Review Level Handoff settings, Orbit/Ground Worlds, and Can Enter Ground. |
TargetWorldMismatch | The game opened a Level other than the World required by the Ticket. |
TargetActorInvalid | Handoff is being applied to the wrong Actor after arrival. |
TargetPlanetBindingNotFound | The target Planet Actor is not registered yet during Orbit return, or its Binding is incorrect. |
ResolveFailed | The saved coordinate state could not be resolved in the Target World. |
ApplyFailed | Applying Actor Transform or Movement state failed. |
PendingTravelNotFound | No Pending Travel targets the current World. |
AmbiguousPendingTravel | More than one Pending Travel matches the current World. Use the exact Ticket. |
ActiveJourneyNotFound | Ground arrival was not completed, or Journey Id is invalid. |
JourneyNotGroundActive | Ground Handoff has not completed successfully. |
ArrivalTimedOut | Travel Receiver could not restore the arrival state before its timeout. |
#If Ground World also needs PlanetX features
Basic Level Handoff does not require a Ground World Planet Actor solely to restore the Ground pose.
Additional setup may be necessary when Ground also uses:
- PlanetX Native Movement
- Gravity toward the planet center
- Surface Frame movement
- PlanetX Coordinate Query
- Ground environment transitions
Place a PlanetX Planet Actor in L_Ground and assign the same Planet Asset. Configure the Ground Player's Coordinate Component to reference the Planet Actor in Ground World.
Gravity Settings belong to each Planet Component rather than the Planet Asset. Configure gravity independently on the Ground-side Planet Actor when using PlanetX gravity there.
This additional setup is not required for basic Level Handoff pose restoration.
#Complete
You have now configured the basic PlanetX Level Handoff workflow.
The authoring flow is:
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 + ViewpointRuntime travel is:
L_Orbit
↓
Surface Query
↓
Begin Level Handoff
↓
Store Ticket
↓
Game calls Open Level
↓
L_Ground
↓
Spawn / Possess Ground Pawn
↓
Complete Level Handoff
↓
Ground Active
↓
Begin Return Level Handoff
↓
Store Return Ticket
↓
Game calls Open Level
↓
L_Orbit
↓
Apply Return Ticket
↓
Journey CompletedThe visual transition shown while approaching Ground in Orbit World remains separate from World Travel:
Section Proxy
↓
Transition
↓
Runtime Preview WorldRuntime Preview World is not the actual Ground gameplay Level.
PlanetX connects the coordinates and state required between Orbit and Ground while leaving actual World Travel and Pawn lifetime under the existing Unreal Engine project's policy.