Complete public documentation for the current English session
Version 1.0 · Last reviewed 2026-08-23Overview and Requirements
Welcome to the PlanetX Documentation!
Thank you for downloading PlanetX.
This documentation introduces the complete PlanetX workflow, from installation and planet creation to connecting a Ground Level, baking a Proxy, authoring visuals, and transitioning between Orbit and Ground.
PlanetX is an Unreal Engine plugin that helps you use an existing Unreal Engine Level as part of a planet's surface.
You can register a Landscape and Level created through your usual workflow as a particular region of a planet. From a distance, that region appears as part of a complete planet; as the player approaches, PlanetX connects it to the actual Ground Level where gameplay takes place.
This lets you create a continuous experience between a planet viewed from space and gameplay on its surface without substantially changing how you build Levels.
Standard Unreal Engine Levels and Landscapes are primarily authored in flat space. A game in which the player views a planet from space and travels all the way to its surface would otherwise need separate implementations for the distant planet, the real Ground Level, coordinate conversion, and the transition between them.
PlanetX lets you keep your existing Ground Level and associate it with a Section on the planet. In Orbit, the player sees an efficient Proxy and the planet surface. As the player approaches, that representation can transition naturally into the actual Ground content.
PlanetX provides authoring and runtime features that connect existing Unreal Engine Levels to a planet and create a continuous experience from the Orbit representation to actual Ground gameplay.
PlanetX provides a coordinate system that calculates positions and directions relative to the planet's center and surface.
This makes it possible to determine a consistent surface-up direction and movement orientation anywhere on the planet, and to convert between standard Unreal Engine World coordinates and planet coordinates.
Sections, Ground connections, player movement, and Orbit ↔ Ground transitions all use this coordinate system as a shared frame of reference.
PlanetX can generate a Section Proxy so that an existing Ground Level remains recognizable from Orbit.
It analyzes the main visual elements that make up the Ground area—including Landscapes, Static Meshes, and Foliage—and bakes them into a representation suitable for distant viewing. The result is then associated with the corresponding Section on the planet.
This allows the region to remain visible on the planet in Orbit without keeping the complete Ground Level rendered at all times.
As a player or camera approaches the planet or moves away from its surface, PlanetX can transition between the Orbit representation and the actual Ground content.
During the transition, PlanetX uses the planet surface frame to carry the player's position, rotation, and movement state between the two representations.
This makes it possible to create one continuous travel experience without requiring a separate landing screen or a completely unrelated movement model.
Orbit and Ground may require different environment presentations.
PlanetX manages the planet's atmosphere, clouds, lighting, and related effects, and can apply the appropriate presentation while the player moves between Orbit and Ground.
PlanetX includes validation and debugging tools that make it easier to find missing data or incorrect settings while authoring a planet.
You can inspect the Planet Asset, Section-to-Ground connections, Proxy Bake results, planet visuals, and runtime transition state. When a problem occurs, these tools help identify which stage of the workflow requires attention.
Overview and Requirements
Compatibility and Limitations
Before using PlanetX, please review the supported Unreal Engine version and platforms, as well as the scope and limitations of Proxy Bake.
Planet authoring, Proxy Bake, the Planet Asset Editor Preview tab, and other authoring tools are used in Unreal Editor.
The packaged game uses the required Planet Assets together with the baked planet and Proxy data at runtime.
Because PlanetX runs on top of Unreal Engine Editor, we recommend a CPU and GPU that meet or exceed the recommended specifications for Unreal Engine 5.8.
Proxy Bake and the Planet Asset Editor Preview tab may hold geometry from large Levels and intermediate generated data in memory. We therefore recommend providing more system memory than a typical Unreal Engine project may require.
Component
Minimum
Recommended
CPU
Unreal Engine 5.8 recommended specification
Unreal Engine 5.8 recommended specification or better
GPU
Unreal Engine 5.8 recommended specification
Unreal Engine 5.8 recommended specification or better
System memory
32 GB RAM
64 GB RAM or more
Actual memory requirements depend on the size and complexity of the source Level, the number of Proxy Bake sources, Landscape resolution, and visual settings.
Proxy Bake converts the visual appearance of a Ground Level into a Section Proxy suitable for use from Orbit.
The following Unreal Engine content types are supported directly:
Static Mesh
Instanced Static Mesh (ISM)
Hierarchical Instanced Static Mesh (HISM)
Foliage
Landscape
PCG-generated Static Meshes or instances, Level Instances, Packed Level Actors, and HLODs may be processed conditionally when their inspectable content is composed of the supported types listed above.
Content that changes shape at runtime or requires a separate representation is not supported as a standard Proxy Bake source. Examples include:
Spline Meshes
Skeletal Meshes and Cloth
Dynamic or Procedural Meshes
Grooms
Niagara and other effects
Dynamic geometry such as Geometry Collections
When PlanetX encounters an unsupported visual element, it records the omission in the Bake results whenever possible rather than silently ignoring it.
If Proxy Bake finishes as Completed With Warnings, the Proxy itself was generated successfully, but some content may have been excluded. Please review the result and its warnings.
For large Levels, Proxy Bake limits output size to avoid creating an excessively large single result.
Intermediate data for an individual Proxy Bake processing chunk generally targets 128 MiB or less.
A warning is reported when an individual generated package exceeds 512 MiB.
An individual package that exceeds 1 GiB cannot be published.
For complex, large-scale Levels, adjust Proxy detail and the Bake source scope as appropriate.
Setup and First Project
Start Here — Same World Quick Start
This is the official first-use and product-review path. It starts from Unreal Engine's built-in Open World Level template, saves that Level as GroundLevel, connects it to PlanetX as a Same World Section, and verifies the runtime transition into the actual Ground content.
When finished, you will have:
One Planet Asset
One Same World Section connected to GroundLevel
A baked Section Proxy
A runtime planet visual
A PlanetX Planet Actor
An Environment Manager
A Transition Endpoint
A Player Actor that participates in the Orbit ↔ Ground transition
An Unreal Engine 5.8 project with PlanetX installed and enabled
You do not need a prepared Ground Level. Step 2 creates a new Level from Unreal Engine's built-in Open World template and saves it as GroundLevel. The Open World template supplies the reproducible Landscape source used by this guide. Step 11 then prepares the Player Actor used for the runtime transition test.
Use these exact values for the reproducible path:
Setting
Value
Ground Level
GroundLevel, created from the Open World template
Planet ID
FirstPlanet
Planet Radius
100 km
Planet Asset
PA_FirstPlanet
Do not open Proxy Bake until Step 2 has created and saved GroundLevel. Proxy Bake must use a saved Level rather than an Untitled or /Temp Level.
If PIE or Simulate is running, stop it first. Proxy Bake works from Editor Ground sources and must not run during PIE.
Choose Content Browser > Add > Miscellaneous > Planet Asset. For this guide, use Planet ID FirstPlanet, Planet Radius 100 km, the default Coordinate Convention, and save the Asset as PA_FirstPlanet. See Create Your First Planet Asset only if you need the setting concepts explained in more detail.
You do not need to create a Section manually yet.
The first Proxy Bake automatically creates the required Section and Level Pair for the current Ground Level.
Choose File > New Level, select Unreal Engine's built-in Open World template, and save it immediately as GroundLevel.
The Open World template supplies a World Partition Landscape and is the reproducible Ground source used by this Quick Start. After this workflow succeeds, you can repeat it with your own gameplay Level.
Before opening Proxy Bake, confirm that the Level tab shows GroundLevel rather than Untitled and save once more.
For a first Bake, use the Unreal Editor Tools menu, find the PlanetX section, and select Proxy Bake Editor. This is the canonical first-use path.
Opening Proxy Bake from Planet Asset Editor > Sections is the existing-Section workflow and should be used only after a Section has already been created.
Start in Basic mode at the top of Proxy Bake Editor. This Quick Start does not require changes to Advanced settings.
Expand 2 Runtime Role and choose the following Presentation value:
text
Same World
Same World means that the Planet and actual Ground content coexist in one World.
The currently open Ground Level automatically becomes the Ground World, so no separate Planet World is required. Confirm that Ground World shows the Level you are editing.
You do not need to edit every item for a first pass. Check only whether:
An Actor you intended to use is missing
A source requires Manual Review
A source is marked Unsupported
No source is selected for the Bake
Continue when the status line is green and shows SUCCESS, at least one intended source is enabled, Unsupported and Manual Review are both 0, and BAKE IN EDITOR is enabled.
Generated Section identifiers include a unique suffix. The example uses GroundLevel_143C3E3D; your suffix can differ.
If an unsupported source appears, exclude it or correct the issue and scan again.
If you manually changed a source's Use or Role, select:
text
Apply Source Changes
The Bake button remains unavailable until those changes are applied. If you did not change any source, no additional apply step is required.
After the first successful Proxy Bake, one new entry should appear. For this Quick Start, confirm the following state:
Item
Expected state
Runtime Role
Same World
Ground World
GroundLevel
Bake
Linked
Transition
Ready
Select the Section to review its connected Ground World and Generated Resource state.
A Same World Section acts as a fixed anchor between the Ground Level and the planet reference frame. You normally do not need to change the default Section's Latitude, Longitude, Surface Yaw, or Scale.
If needed, adjust Altitude only to correct a vertical offset between the Ground and planet surface.
Select the transform-shaped Align icon on the right side of the Scene area.
Align positions the Planet Actor against the reference point of the current Same World Ground Level.
Same World uses the Ground Level as the Section at the planet's north-pole reference, so you do not need to calculate the Planet Actor location manually.
Align corrects the location required for the Ground and planet surface to meet without arbitrarily changing the Actor's rotation or scale.
PlanetX uses one Environment Manager for each Planet.
Until an Environment Manager is added and connected, the planet can appear dark because PlanetX has not applied the atmosphere, cloud, and space-background environment to that Level yet. Treat that dark view as an incomplete setup rather than a material failure.
Open the Environment Palette in PlanetX Mode, or press Alt+5.
If no Environment Manager is assigned, the Palette displays:
text
Environment Manager is not assigned to this Planet.
Select:
text
Add Manager
PlanetX creates a PlanetXEnvironmentManager associated with the active Planet.
You do not need a Level Override for the first test. The Environment settings authored in the Planet Asset are used by default.
Save GroundLevel immediately after adding the Manager. If the atmosphere or clouds look incorrect, save the Level first and then check the Planet view again. Saving persists the Manager and its Level bindings before the environment is evaluated again.
After creation, select Validate and confirm that the Manager is connected to the current Planet.
The Endpoint sizes its Transition Cylinder from the Section bounds. Keep the default enabled:
text
Auto Size Transition Cylinder to Section Bounds
Enabled
A debug cylinder in the viewport shows the transition region.
PlanetX uses this region to determine whether the player is in Orbit, Transition, or Ground. You do not need to position or resize the Endpoint manually for the first test.
Next, configure the Pawn or Character that will move through the transition.
Modify the Actor currently used as the PlayerController's View Target. For this tutorial, use the Pawn or Character instance placed in the Ground Level with Auto Possess Player 0.
If GroundLevel does not already contain that Actor, place the Pawn or Character now, set Auto Possess Player to Player 0, and confirm that its active Camera Component supplies the PlayerController's View Target.
Add PlanetX Coordinate Component in the Components panel.
Compile the Blueprint after adding the Component, then return to the Ground Level and select the placed Player Actor instance. In that instance's Component Details, configure PlanetX Reference:
Set Reference Planet Actor to the PlanetX Planet instance placed in this Level.
Set Reference Section Id to the Same World Section created by Proxy Bake.
For an initial test, explicitly selecting the Section is preferable to automatic discovery.
When PIE starts, confirm that the possessed Pawn is the same Actor configured here. If the World Outliner creates and possesses a separate DefaultPawn0, configure that actual Pawn or change the GameMode's Default Pawn Class instead of assuming the placed BP_Player is controlled.
The final relationship should be:
text
Player Actor
└─ PlanetX Coordinate Component
├─ Reference Planet Actor → Placed PlanetX Planet
└─ Reference Section Id → Same World Section created by the Bake
When Reference Planet Actor is set, Planet ID is resolved from that Actor's Planet Asset.
Add PlanetX Viewpoint Component to the same Actor and keep these defaults:
text
Auto Register Runtime
Enabled
Can Drive Transition State
Enabled
Make sure the Actor has at least one active Camera Component.
During PIE, PlanetX evaluates Orbit, Transition, and Ground from the actual PlayerController View Target and its active Camera. If the PlayerController uses another Actor as its View Target, add the PlanetX Viewpoint Component to that Actor instead.
Configure PlanetX to move the player automatically between Orbit and Ground coordinates when crossing the transition region.
In the Player Actor Blueprint's Event BeginPlay, call these functions on the PlanetX Coordinate Component:
text
Event BeginPlay
│
├─ Set Automatic Same World Entry Enabled
│ Enabled = true
│
└─ Set Automatic Same World Return Enabled
Enabled = true
Both functions belong to PlanetX Coordinate Component.
The first moves the player from Orbit coordinates to the actual Ground coordinates when entering the Ground region. The second returns the player from Ground to Orbit coordinates when leaving it.
Keep the default Return Pose and Movement Continuity policies for this Quick Start. By default, the movement performed on Ground continues into the Orbit pose, and movement state is converted between coordinate frames when necessary.
Open the Runtime Palette in PlanetX Mode, or press Alt+2. It shows the current Planet registration and transition state.
Move the player toward the Ground and observe the transition. A correct setup progresses through:
text
Orbit
→ Transition
→ Ground
Upon reaching Ground, PlanetX connects the player state to the actual Ground position for the Same World Section.
Moving away from Ground should return through:
text
Ground
→ Transition
→ Orbit
During the transition, confirm that:
The Section Proxy and actual Ground do not have a large offset
The player does not jump to an unrelated location
Camera orientation remains correct
Existing gameplay works after entering Ground
Movement continues naturally when returning to Orbit
The following example shows GroundLevel running in PIE with the completed planet visual. This image confirms the rendered PIE result; use the Runtime Palette described above to verify the actual Orbit, Transition, and Ground state sequence.
The yellow Placement prompt in this example only indicates that no Actor is selected for placement editing; it is not a Validation Error.
You can now refine the surface and environment in Planet Asset Editor > Preview, add more Sections, or configure the External Level workflow to connect separate Levels.
Setup and First Project
Installation
PlanetX can be installed for Unreal Engine through Fab.
A Planet Asset is the central Asset that defines a planet in PlanetX.
It stores the planet's size and coordinate reference. Sections, Proxy Bake results, and planet visuals created later are all associated with this Asset.
Choose Planet Asset from Content Browser > Add > Miscellaneous.
The creation dialog asks for three initial values:
Planet ID
Planet Radius
Coordinate Convention
If this is your first time using PlanetX, you can leave Coordinate Convention at its default and create the Asset after confirming only the Planet ID and Planet Radius.
Coordinate Convention defines how PlanetX interprets the planet's north and longitude directions in Unreal Engine World space.
In practical terms, it answers the following questions:
text
Which direction is the planet's north pole?
Which direction is longitude 0°?
Which direction is east on the planet?
For your first PlanetX project, we recommend keeping the default Coordinate Convention.
Most PlanetX workflows do not require this setting to be changed.
Change it only when an existing project already follows a specific World-axis convention or when PlanetX must interoperate with another coordinate system.
The Planet Asset Editor is the central editor for authoring a PlanetX planet and reviewing its state.
It provides five dockable tabs with these exact UI names. The default layout opens Preview in the main area and Configuration on the right. If another tab is closed, reopen it from Window > Planet Asset.
You do not need to change every advanced setting immediately after creating the Asset.
For now, confirm these three items:
The Planet ID does not duplicate another Planet Asset.
The Planet Radius matches the intended planet size.
Unless your project requires a special coordinate rule, Coordinate Convention remains at its default.
Save the Planet Asset to complete the initial setup.
You do not need to add a Section manually.
In the next step, run the first Proxy Bake against a Ground Level. PlanetX will create the required Section and connection data.
Setup and First Project
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.
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.
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:
text
1 Target Planet Asset
└─ Planet Asset
Assign the Planet Asset created in the previous step. There is no existing Section to select before the first Bake.
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:
text
Runtime Preview World
= Visual representation during transition
L_Ground
= Actual gameplay World
This distinction is essential when working with Level Handoff.
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:
In Planet Asset Editor > Preview, assign the base surface Completion Material:
text
Preview
└─ Basic
└─ Planet
└─ Completion Material
Leave 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:
text
Apply & Build
PlanetX applies the Preview settings to the Planet Asset and generates the final runtime planet visual. Save the Planet Asset after a successful build.
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:
text
Planet Actor location is not aligned
to the canonical Section's baked Ground Sync Mapping.
Open the Environment Palette in PlanetX Mode. If the current Planet has no Manager, select:
text
Environment
└─ Add Manager
PlanetX 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.
Auto Size Transition Cylinder To Section Bounds
Enabled
PlanetX 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:
text
Orbit
↓
Transition
↓
Ground Presentation
For 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.
Auto Register Runtime
Enabled
Representation Domain
Orbit
Reference Planet Actor
→ PlanetX Planet in L_Orbit
Reference Section Id
→ The Section baked earlier
For 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.
Prepare the Pawn or Character used by L_Ground, for example:
text
BP_GroundPlayer
A 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:
text
L_Ground
└─ BP_GroundPlayer
A 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.
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 point
When more than one Planet exists, expose the advanced pins and specify:
text
Preferred Planet Id
Preferred Planet Binding Id
You can omit them for a simple single-Planet test.
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:
text
Section Local position captured in Orbit
↓
Ground Sync Mapping
↓
World position in L_Ground
Confirm 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.
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.
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 Completed
The visual transition shown while approaching Ground in Orbit World remains separate from World Travel:
text
Section Proxy
↓
Transition
↓
Runtime Preview World
Runtime 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.
Data Model and Core Concepts
Planet Assets and Identities
UPlanetXPlanetAsset is a Primary Data Asset connecting a planet's physical, coordinate, Section, Level Pair, Proxy Bake, generated-visual, and environment-authoring contracts.
A Planet Asset stores Radius, Coordinate Convention, Sections, Level Pairs, Completion and Padding settings, Environment settings, Surface Preset, Proxy Bake links, and revision state. Generated payloads and materials are published by editor workflows and linked to the asset.
IsProxyBakeStale, IsVisualBuildStale, and IsVisualPreviewStale compare the current authoring revision with the most recent successful output. A stale result requests validation and regeneration; it is not an instruction to delete assets automatically.
The same Planet Asset can appear in Orbit and Ground worlds. If several Planet Actors with one Planet ID exist in a world, automatic selection can be ambiguous. Supply the Planet Binding ID exposed in advanced API inputs.
Changing an ID affects saved coordinates, Level Pairs, bake links, and travel routes. Treat it as a migration rather than a display-name edit, then run Full Validate and bake again.
Data Model and Core Concepts
Sections and Level Pairs
A Section combines a geographic surface region, local frame, visual proxy, and transition boundary. A Level Pair defines the worlds in which that Section is presented.
FPlanetXSectionPlacement determines surface location, tangent orientation, size, and placement transform. A Same World Section selected as the canonical north-pole anchor can restrict automatic placement. The editor validates visual, coordinate-containment, and transition rectangles through one bounds contract.
An explicit Section ID lets saved data, captures, and Sequencer resolve the same frame. Automatic Section resolution uses the current Planet Local position and asset array order, so it is intended for editing and one-off queries rather than persistent identity.
Same World requires Orbit and Ground to use the same World package.
External Level / Level Handoff requires distinct Orbit and Ground worlds plus a Runtime Preview World.
A Level Handoff Section needs a valid GroundSyncMapping and TransitionPolicy. Successful Proxy Bake publication refreshes the SourceRef, BakeData, mapping, preview, and transition-resource links.
Per-Section Ground proxy visibility determines whether source actors or proxies are shown in Orbit, Ground, and transition states. PlanetX Mode's Planet, Compare, and Level views only compare editor presentation; they do not change the runtime contract.
When UPlanetXCoordinateComponent.CoordinateMode is Unreal, the owner's World Transform is authoritative and the PlanetX snapshot is captured from it. In PlanetX mode, FPlanetXTransform is authoritative and Apply produces the World Transform. Capture and Apply are explicit operations.
Reference resolution prefers Reference Planet Actor, then Reference Planet ID. An explicit Section ID makes that Section frame authoritative.
Positions use point conversion; movement input uses vector conversion. With Surface Frame in ConvertCoordinateVectorToWorld, X/Y/Z represent East/North/Up. Surface movement can enable bProjectToSurfaceTangent to remove the Up component.
Do not inspect only the boolean return value. Read FPlanetXTransformResolveResult or the detailed query status to distinguish invalid versions, unregistered planets, ambiguous bindings, unsupported planet scale, and invalid Sections.
Data Model and Core Concepts
Representation and Runtime Load
PlanetX treats presentation ownership and World Partition loading as separate policies.
Use ShouldForceOwnerAlwaysLoaded to inspect the effective result and ApplySpatialLoadingPolicyToOwner to apply it. The apply function can also run in the editor. Verify the resulting Actor, World Partition, and Data Layer configuration against project policy.
Hidden and unloaded are different states. Planet proxy visibility, Section proxy residency, and Runtime Preview residency are tracked separately. Use Runtime Monitor to inspect registration, realized component count, and renderability together.
Data Model and Core Concepts
Transition Model
A PlanetX transition is a lifecycle connecting Section state, runtime context, actor pose, and travel state—not only a visual alpha.
The Orbit actor moves to a Ground pose within one World. Automatic entry applies only to actors whose Coordinate Component enables the Spatial Entry policy. Return policy can use the captured pose or the current Section-relative pose.
For different Worlds, BeginLevelHandoff or PrepareTravel creates a ticket. Game code remains responsible for OpenLevel and pawn policy. In the destination World, ResumePendingTravel or CompleteLevelHandoff with an exact ticket applies the pose.
An old ticket generation or multiple matching pending travels is rejected rather than guessed. Journey ID links the round trip, and completed journeys remain queryable for diagnostics.
Movement Handoff captures and reapplies linear and angular velocity in the intended coordinate frame. Inspect Consume, Cancel, and rollback results to prevent duplicate application.
Editor Workflows
Planet Asset Editor
Double-click a Planet Asset to open its dedicated editor. The editor provides five dockable tabs for the asset contract.
The default layout opens Preview in the main area and Configuration on the right. Overview, Sections, and Diagnostics may be closed until a command opens them. If a tab is not visible, reopen it from Window > Planet Asset.
Configuration intentionally hides EnvironmentSettings. The single authoring surface for the environment profile is Preview > Advanced > Environment.
Section filters include All, Same World, External Level, Needs Bake, Needs Transition, and Invalid. Changing runtime role must satisfy the required World and Proxy Bake contract.
Delete Selected Section removes the Section and Level Pair from the Planet Asset. It does not delete referenced source Worlds, Proxy BakeData, or Runtime Preview assets. Clean generated assets through a separate, reviewed operation.
For a new Planet Asset, open Overview when you need the status summary, then open Proxy Bake from the saved Ground Level. Do not create or select a Section first; the first successful Proxy Bake creates the Section and Level Pair. Return to Sections to verify Linked after the Bake, adjust visuals in Preview, and pass Full Validate in Diagnostics.
For an existing Planet Asset, open Sections, select the Section that needs work, and use its Proxy Bake entry. This is the only flow that begins by selecting a Section.
Editor Workflows
PlanetX Mode
PlanetX Mode is a Level Editor mode that presents Planet Actors, Sections, participants, environment, and transitions in the current World.
Scene Tree displays Planet, Section, Endpoint, Environment, and participant associations. It warns about duplicate Endpoints or Environment Managers and invalid Section placement or topology.
Before moving an actor with Placement tools, verify the Coordinate Component's Reference Planet/Section and representation domain. Use an explicit Section ID for persistent placement.
In PIE, use Runtime to observe planet registration, Section state, Runtime Preview, and transition results. Do not run Proxy Bake operations that change the source World while PIE is active.
Editor Workflows
Proxy Bake Editor
Proxy Bake Editor collects visual sources from a Ground World and publishes orbit proxies, partition payloads, Runtime Preview data, and transition resources.
Run Scan Sources (F5) to refresh sources and the Bake plan.
Review changes and run REBUILD IN EDITOR or BAKE IN EDITOR as shown.
Use Esc to request cancellation and Ctrl+Shift+O to select results.
Operations that need to change the Source Level cannot start during PIE. While an external worker is active, do not open its Source World directly; request cancellation through the editor.
Enable Open Bake Monitor in browser in the External Bake confirmation to open a local browser view of stages, progress, ETA, resource usage, warnings, and bounded log tails. The Monitor is an observer: if its service or browser cannot open, External Bake continues and its result is unchanged.
The loopback Monitor service is part of the PlanetXEditor module and runs inside the active Editor or direct Worker process. PlanetX does not install or launch a separate Monitor executable. The service accepts local connections only and authorizes its browser page with a per-session token. Do not share or publish the complete Monitor URL.
The direct Worker hosts the Monitor during an active External Bake. When the Worker exits, that service ends and an existing tab can disconnect. After Unreal Editor restarts, use Open External Bake Monitor to host the latest durable result again. The new service reconstructs state from the Job artifacts; the previous browser tab is not migrated automatically.
Closing the tab never cancels the Bake. Use Cancel Bake in the Monitor or the Editor cancellation action to request cancellation at a safe checkpoint. A cancellation request does not publish partial output.
The editor exposes Auto, ProxyGeometry, LandscapeProxy, InstanceBatch, Discard, ManualReview, and Unsupported roles. Sources can be grouped by Actor, Folder, Data Layer, or Level/Level Instance.
The C++ tag API provides BakeSource, NoBake, Preview, and Generated tags. Use explicit exclusion as an intentional source policy, not as a way to conceal omissions.
Succeeded means publication completed without omissions. CompletedWithWarnings means publication succeeded but SourceOmissions require review. Packages over 512 MiB produce warnings; publication is rejected over 1 GiB.
Editor Workflows
Validation and Diagnostics
PlanetX validation reports more than an error string. A finding carries severity, impact, blocking scope, automatic-fix eligibility, and a resolution action.
Quick Validate checks the asset structure and immediately available contracts. Full Validate also inspects Worlds, Proxy Bake links, Runtime Preview, and generated output, and writes structured logs.
The Validate palette in PlanetX Mode checks the current World and connected assets together. Fix All Safe changes only warnings whose result is deterministic and needs no additional choice. Destructive actions and findings requiring a user decision are never auto-fixed.
Full Validate writes stable Surface/Operation/Subject records through LogPlanetXValidation. For visual authoring issues, use PlanetX.VisualEdit.Dump; for proxy presentation, use PlanetX.ProxyStats.Dump.
Runtime Integration
Runtime Integration
The public runtime facade is UPlanetXSubsystem, a Game Instance Subsystem. World-specific registries and services are implementation details; gameplay code uses the facade and public components.
APlanetXPlanetActor includes Planet, Proxy, Transition Morph, Atmosphere, and Volumetric Cloud components. Assign a Planet Asset on the Planet Component and use bAutoRegisterRuntime, or call RegisterToPlanetXRuntime.
When several actors share one Planet ID, retain the Planet Binding ID and pass it to queries. Automatic resolution that assumes a single instance can become ambiguous.
The Planet Actor must register before participants can resolve runtime context. If streaming can delay that order, use RefreshRuntimeRegistration, RefreshRuntimeContext, or the Travel Receiver retry policy.
Check Full Validate, current Proxy Bake, current Generated Visual and Material output, Runtime Preview Worlds, and cooked asset bundles. A working editor preview does not prove that runtime payloads are cooked.
Runtime Integration
Coordinates and Surface Queries
Coordinate APIs separate actor-pose conversion from planet-surface discovery. UPlanetXSubsystem is the Blueprint facade taking a World context; the Coordinate Component provides owner-bound conveniences.
FPlanetXSurfaceQueryInput contains ray origin, direction, and selection criteria. Prefer QuerySurfaceAtWorldRayDetailed for gameplay branches because it distinguishes InvalidInput and RuntimeUnavailable from a geometric miss.
Queries can also start from Geo coordinates or FPlanetXTransform. FPlanetXSurfaceQueryResult carries Planet, Section, hit position, normal, and coordinate information.
BuildLandingTransform creates a surface-aligned landing pose. GetSectionTransform, GetSectionDesc, and GetSectionRuntimeState expose the Section contract and current state.
The Coordinate Component exposes Surface Up/Down/East/North, tangent projection, and Surface/Planet/Section Local to World vector conversion. Do not confuse points with vectors, and choose tangent projection explicitly for surface input.
Runtime Integration
Movement and Gravity
UPlanetXMovementComponent applies planet-relative movement using runtime context resolved by the Coordinate Component.
The Movement Component needs a valid UpdatedComponent. Verify the reference Coordinate Component and planet-gravity settings, then use ValidateMovementConfiguration for a specific error message.
FPlanetXNativeMovementSettings defines acceleration, deceleration, speed, and ballistic behavior. FPlanetXGravitySettings defines acceleration toward the planet center; Planet Component exposes GetGravityAccelerationAtWorldLocation.
GetMovementRuntimeState contains current velocity, gravity, and resolve or failure state. The single and aggregate queries on the Game Instance facade are suitable for debug UI and telemetry.
When changing Worlds or Movement Components, use Movement Handoff instead of copying velocity directly. The frame-continuity policy interprets linear and angular velocity in the destination surface frame.
Runtime Integration
Same World Travel
Same World travel moves an actor from Orbit to a Section's Ground pose, then returns it to Orbit when both presentations use one World package.
The Level Pair must use the same package for OrbitWorld and GroundWorld. GroundSyncMapping, transition bounds, and the Surface Query must be valid. The traveling actor needs a resolvable Planet and Section context in the current World.
The Coordinate Component can enable automatic Same World entry and return. Runtime evaluates the transition boundary for registered participants and applies the pose when the presentation is ready.
Return Pose Policy chooses between the captured Orbit pose and a pose reconstructed from the actor's current Ground Section-relative transform. Use the latter when Ground movement must carry back into the Orbit Section frame.
The request fails when the Surface Query targets another Planet or Section or actor context is ambiguous. Automatic return can wait for Orbit presentation readiness. Inspect the Transition Journey and managed-actor state.
Runtime Integration
Level Handoff Travel
Level Handoff transfers a PlanetX pose and Journey state between different World packages. Game code continues to own level loading and pawn creation policy.
On success, game code travels to Ticket.TargetWorld. At arrival, use ResumePendingTravel only when exactly one pending ticket matches, or call CompleteLevelHandoff with the stored ticket.
The advanced flow is BeginLevelHandoff → CompleteLevelHandoff → BeginReturnLevelHandoff(JourneyId) → CompleteLevelHandoff. PrepareTravel can also use an explicit route for direct Ground-to-Orbit travel.
No matching pending travel reports PendingTravelNotFound.
Multiple matches report AmbiguousPendingTravel.
An older ticket generation reports StaleGeneration.
A missing target Planet Binding can be retried by Travel Receiver within its timeout.
The Ground mapping stored in the capture is authoritative for the Level Handoff Ground pose.
ResumePendingTravel never guesses the latest ticket. Projects allowing concurrent travel should keep Ticket or Journey identity in gameplay save state.
Cancel unused tickets with CancelLevelHandoff. Log Capture, Journey, and Result error together, and use GetActiveTransitionJourneys to find leaked journeys.
Runtime Integration
Runtime Preview and Budget
Runtime Preview is a gameplay-independent render host used to present an External Level Section's Ground content in Orbit or Transition worlds.
APlanetXRuntimePreviewActor can move through Idle, LoadingRoot, LoadingPayloads, LoadingResources, Realizing, WaitingForRender, Resident, and Failed residency states.
The Game Instance facade provides:
LoadRuntimePreview
SetRuntimePreviewVisible
UnloadRuntimePreview
GetRuntimePreviewStatus
When controlling an actor directly, use AssignPreviewBakeData, LoadPreviewFromBakeData, SetPreviewVisible, UnloadPreview, and the renderable and component-count queries.
Runtime Preview realizes proxy Static Meshes and baked ISM/HISM/Foliage instance batches under one root. It intentionally excludes gameplay-actor duplication, collision, navigation, and tick-based behavior.
Loaded and Renderable are different. A Resident preview can still require render-resource readiness before presentation switches.
PlanetX Runtime project settings select Follow Engine Scalability or a fixed profile. Proxy Bake Quality is immutable geometry quality for a published revision; Runtime Budget controls per-frame realization and residency work. They are independent.
Use Stat PlanetXMemory, Stat PlanetXResources, Stat PlanetXProxy, and Stat PlanetXRuntime to inspect memory, resources, rendering, and runtime-service cost. Also review PlanetX.MemoryBudgetMB and automatic-material MID budget warnings.
Runtime Integration
Environment Runtime
APlanetXEnvironmentManager connects a Planet Asset environment profile to Atmosphere, Cloud, Sun, Post Process, and Space Background bindings in the current World.
PlanetX Managed mode controls required components from the PlanetX profile. Use Existing Level preserves existing SkyAtmosphere or Volumetric Cloud components, so the project must match them manually to the Planet Asset profile.
A managed Planet Actor supplies Radius and environment-authoring settings. Without an Existing Sun Light, the stored Sun direction remains usable but validation can report a warning.
ValidateEnvironmentBinding checks bindings and material/profile conditions.
CaptureEnvironmentStateFromBindings captures current Level values.
ApplyEnvironmentState applies the stored state.
ApplyInitialRuntimeSpace establishes the initial Orbit or Ground presentation.
SetEnvironmentTransition(From, To, Alpha) interpolates between spaces.
Orbit cloud and atmosphere render-quality and tracing overrides have matching Apply and Restore operations. Always restore overrides when returning ownership to the Level.
Mismatch between PlanetX and existing Ground cloud
Missing MPC
Non-positive Planet Radius or terminator softness
Missing Sun or Cloud source for a cloud-shadow override
Incorrect Space Background material domain, blend, shading, or Is Sky
Resolve binding validation before investigating presentation alpha.
Visual Authoring
Preview Tab
The Preview tab in the Planet Asset Editor authors the planet visual contract in a dedicated preview World. Basic exposes frequent controls; Advanced exposes generation and environment details.
Advanced contains Planet Completion, Section Proxy Padding, material build, and the complete Environment profile. Changes apply to a preview session, and a successful build links its revision to the Planet Asset.
Preview is an authoring environment, not the runtime World. Runtime Preview follows a separate path that consumes published Proxy Bake payloads. Even when Preview looks correct, check stale status and Runtime Preview readiness in Diagnostics.
The viewport adjusts camera speed and framing for the planet radius. A failed Padding Material Preview reports the failed Section count; use PlanetX.VisualEdit.Dump for details.
Save before and after edits. When Section geometry or material sources change, review the stale state of both Completion/Padding and Proxy Bake.
Visual Authoring
Completion and Padding
Completion generates planet surface not covered by Sections. Padding reinforces Section proxy boundaries so they connect naturally to the spherical presentation.
Surface Completion settings control generated topology, cutouts, terrain noise, and surface materials. Generators are deterministic for identical input and validate polygons, boundaries, and mesh attributes.
Terrain Regions apply noise parameters to selected surface areas. Use Preview to ensure strong noise or an incorrect cutout does not intrude beneath a proxy.
Proxy Padding selects Section boundary loops and creates connecting geometry through adaptive subdivision and projection. Transition strips and shared seams preserve position, normal, and material provenance across the boundary.
Performance budgets contain warning and hard thresholds for boundary edges, generated vertices, indices, compact bindings, and MID counts. A warning can still publish output, but requires runtime-cost review.
Padding Material Build collects source material layouts and generates the necessary texture and material assets. Editor validation can detect changed source material state even when the asset path is unchanged. Rebuild before packaging.
UPlanetXSurfacePreset is a Primary Data Asset for reusable Completion and planet-surface styling. Assigning it as the Planet Asset's Active Surface Preset lets authoring settings reference that selection.
Use a preset to share materials, terrain or noise character, and visual parameters. It does not replace structural contracts such as Planet ID or Section geometry.
Planet Material Override on UPlanetXPlanetProxyComponent replaces the planet-sphere presentation. Section proxy materials must follow the canonical slots and remaps in BakeData. Reordering slots independently can break boundary and padding material provenance.
The runtime binder checks generated-visual binding descriptors and Source Material identity before preparing MIDs. A mismatched geometry revision, slot, or texture set can produce an error material or warning.
Run Full Validate after changing a Source Material.
Rebuild stale Generated Material before packaging.
Preserve material-slot order across bake and visual build.
Do not use sky materials as ground Proxy Bake sources.
Limit dynamic materials to parameters that can be captured deterministically.
Visual Authoring
Environment Authoring
Author the environment profile in Planet Asset Editor > Preview > Advanced > Environment. Atmosphere, Clouds, Sun, Post Process, and Space Background are stored in one FPlanetXEnvironmentAuthoringSettings contract.
Atmosphere height can scale from Planet Radius or use a manual kilometer value. The profile exposes Rayleigh, Mie, absorption, aerial perspective, and ground albedo controls.
Clouds define layer bottom and height, lighting, atmosphere interaction, and shadow parameters. If an existing Level cloud does not match the PlanetX profile, Orbit and Ground presentation can diverge during transition.
The Sun profile defines atmosphere sunlight, cloud shadows, shadow extent, and quality. Post Process controls the planet profile, convolution bloom, and lens flare. PlanetX Rendering project settings also apply default lens-flare console variables.
A Space Background material should use the Surface domain, Opaque blend mode, Unlit shading, and Is Sky. When Planet Asset Defaults is the profile source, a managed Planet Actor and Planet Asset must be bound.
Connect the Planet Actor, Sun, Atmosphere, Volumetric Cloud, and MPC to APlanetXEnvironmentManager. Run ValidateEnvironmentBinding before using ApplyInitialRuntimeSpace or SetEnvironmentTransition.
Configuration Reference
Configuration Reference Guide
This category documents the settings that users can adjust in the current PlanetX codebase, grouped by their owning object and editor workflow. Names correspond to labels in Unreal Editor's Details panels or to their C++ property names. A default is the code default for a newly created object.
PlanetX reflected structures include user choices as well as bake output, runtime captures, query inputs, and diagnostic records.
User settings are documented here with their defaults, units, and effects.
Conditional settings are used only when a preceding toggle or mode enables them. Check the stated condition in each table.
Generated data is written by Proxy Bake or Visual Build. It should not be edited manually even when it is visible in Details.
Request and result structures are values supplied to individual function calls, not persistent project settings. Their fields are covered by the Public API Reference.
This reference is based on the public headers shipped with PlanetX 1.0 under:
text
Source/PlanetX/Public/PlanetX
A type appearing in a public header is not, by itself, a general user setting. This reference covers editor-adjustable values, project configuration, and public operation options; pipeline-generated payloads and captures are identified separately.
Configuration Reference
Planet Asset and Visual Settings
Distances and sizes are in Unreal Units (centimeters) unless noted otherwise.
The unique FName that identifies the planet across the project and at runtime. It is immutable after creation.
Radius
The planet radius. The creation UI may accept kilometers, but the Asset stores centimeters and requires at least 1 cm. Radius participates in the bake and visual-build contract and is not intended for direct changes after creation.
Coordinate Convention
Defines the North Pole and longitude axes, longitude direction, Source X/Y/Z mapping, and UnrealUnitToCm. The defaults are Up/Forward/Right, counterclockwise longitude, X=East, Y=North, Z=Up, and 1 uu=1 cm. It is immutable after creation.
Latitude, longitude, and altitude of the Section center.
Placement.YawDeg
0°
Section rotation relative to its Surface Frame.
Placement.Scale
1.0, greater than 0
Uniform Section scale.
Placement.LocalExtentCm
(100,000,100,000)
Section-local X/Y half extent.
Placement.bLockToSurface
true
Locks the center to the planet-surface contract.
SurfaceCorrectionSettings.Mode
Disabled
Chooses Disabled, bake-vertex-derived Automatic, or direct-offset Manual.
SurfaceClearanceCm
1.0, at least 0
Additional outward clearance after Automatic moves the lowest baked vertex to the surface.
ManualOffsetCm
0, at least 0
Outward offset applied by Manual mode.
LevelPairId
None
Level Pair referenced by the Section.
bEnabled
true
A disabled Section is excluded from runtime presentation and travel targets.
The Same World north-pole anchor contract locks latitude, longitude, yaw, and scale. Only Altitude remains available for Ground contact-height correction. Bounds, RegionSet, SourceRef, ProxyBakeData, rectangles, and hashes are Scan/Bake output and should not be edited manually.
In Details and the API, AuthoringGeometrySettings, SurfaceCompletionSettings, ProxyPaddingSettings, TransitionDistanceSettings, and ShapeEditorSettings own the corresponding groups above. ProxyPaddingSettings.PerformanceBudget owns the Padding Warning/Hard limits.
Configuration Reference
Proxy Bake Settings
Basic/Advanced view state, Bake Quality, and the requested Source Representation are stored as editor-user settings.
Same World keeps Planet and Ground in one World package and changes presentation. External Level is the UI name for code-level LevelHandoff; it uses a separate Ground World and a visual-only Runtime Preview World.
Ground World
Current Source World
Read-only value resolved from the World being scanned and baked.
Planet World
None
Shown only for External Level. Select the Orbit World that owns the destination Planet Actor on return from Ground. It must be a saved World distinct from Ground World.
The default Level Handoff backend contract is OpenLevel. PlanetX captures and resumes state, but the game remains responsible for Open Level, Pawn creation, and possession.
Scans only Actors currently selected in the Outliner or viewport. Appropriate for deliberate partial bakes.
Current Level
Selected
Scans Actors owned by the current persistent Level and excludes streaming Levels.
Loaded Levels
Scans the current Level, loaded streaming Levels, and Level Instances.
Reviewed Set
Reuses stable source membership explicitly reviewed in the current plan. Complete a Scan with another scope first.
Source Representation: Prefer HLOD
Selected
Prefers validated World Partition HLOD and falls back to original Actors when the source contract requires it.
Source Representation: Original Actors
Uses original Actors and Components only. This is useful for HLOD comparison or fidelity diagnosis.
Include all tags
Empty
Includes only sources whose Actor has every comma-separated tag. Empty means no include filter.
Exclude any tag
Empty
Excludes a source when its Actor has any listed tag.
Contracts that require exact membership—Selected Actors, Reviewed Set, or tag filtering—may resolve an effective Original Actors policy even when Prefer HLOD was requested. Check the requested/effective summary in the UI.
Includes or excludes the source from the current bake.
Role: Auto
Uses the role selected by Scan classification.
ProxyGeometry
Builds ordinary geometry, such as Static Mesh content, into proxy meshes.
LandscapeProxy
Uses the Landscape-specific capture and material path.
InstanceBatch
Publishes repeated ISM/HISM/Foliage instances as batch output.
Discard
Intentionally omits the source from output.
ManualReview
Scan could not establish safety automatically. Review the reason, then repair or exclude it.
Unsupported
The current pipeline cannot publish the source safely. Leaving it enabled blocks Bake.
Group Scope
Applies review changes by Actor, Folder, Data Layer, or Level/Level Instance.
After changing Use or Role, choose Apply Source Changes to rebuild the plan. Safety findings for WPO/displacement, private material dependencies, or unsupported deformation can be blocking decisions rather than informational warnings.
Quality is an immutable authoring preset recorded in the generated revision.
Preset
Static Mesh triangle budget
Projection scale / max segments
Landscape spacing / resolution
Low
1× coarsest LOD
4.0 / 8
800 cm / 17–129
Medium
2× coarsest LOD
2.0 / 12
600 cm / 25–193
High (Recommended)
4× coarsest LOD
1.0 / 16
400 cm / 33–257
High does not mean an unbounded source LOD. It selects the finest valid LOD within a multiple of the coarsest valid LOD's triangle count, keeping geometry growth bounded.
Output partition dimensions. They are disabled while World Partition auto-sizing is active.
Planet Radius
Target Asset value, read-only
Radius in centimeters used by AEQD projection, curvature classification, and subdivision.
Source Grid
false
Uses source Landscape vertex resolution instead of the low proxy grid. It can substantially increase output and processing cost.
Surface Datum World Z: Auto
On
Uses the minimum World Z of participating source bounds as altitude zero and the Ground Sync datum.
Surface Datum World Z
Plan value, cm
Manual world-space Z treated as altitude zero when Auto is off. Changing it requires plan recalculation.
Auto-size World Partition Output
true for WP
Derives PlanetX output-shard dimensions from source bounds and work density. It does not mirror World Partition cells one-to-one.
Recalculate
Recomputes the automatic grid from the latest Scan.
Output path, Target Section, Bake ID, and Source/Partition/Geometry summaries are resolved results. If the target conflicts with an existing asset, the editor requires explicit overwrite or rebuild consent.
Resolves a safe RAM budget from currently available physical memory. Recommended for ordinary work.
Safe
Selected
Keeps 4 GiB of physical memory unavailable to Proxy Bake.
High Utilization
Keeps only 1 GiB free. Select it explicitly for a dedicated bake run; commit and finalization guards remain active.
Manual GiB
Disabled under Auto, 0.5–1024
Total manual memory budget used when Auto is off.
Workers
0, 0–64
Geometry worker limit. Zero lets the memory governor choose concurrency.
Queued
8, 1–128
Maximum number of bounded work packets waiting concurrently.
GT Finalize
4, 1–32
Maximum Game Thread publication/finalization backlog.
Worker Geometry
true
Runs value-only geometry on worker tasks while UObject reads and publication stay on the Game Thread.
Higher values are not always faster. After Scan, review the top contributor and remediation text. For memory pressure, inspect Auto Memory Budget and the partition plan before increasing worker, queue, or finalization limits.
This structure is the projection contract used by Transition Morph and public C++ paths. The ordinary editor workflow generates it from the target Asset and plan.
The editor quality preset and source classifier resolve these values in the normal user workflow. Set them directly only in a tool that calls the public API.
Setting
Default
Purpose
LODIndex
0, at least 0
Explicit Static Mesh source LOD. Do not mix it with editor quality selection unintentionally.
bSkipHiddenComponents
true
Omits hidden Components.
bWarnOnNonUniformScale
true
Reports non-uniformly scaled sources.
bSkipNoBakeTaggedActors
true
Omits Actors carrying the PlanetX NoBake tag.
bRequireBakeSourceTagForSingleLevel
false
Requires the BakeSource tag even for a single-Level bake.
bFailOnAeqdRangeExceeded
true
Fails outside the safe AEQD projection range. Keeping the default avoids silently publishing distorted output.
bClipTrianglesToPartitionRadius
false
Clips triangles at the partition radius. Use only for output intentionally different from canonical ownership.
LandscapeProxyMaterial
None
Fallback when the source Landscape material cannot be used by a Static Mesh proxy.
SubdivisionWorldStep
275 cm, at least 0
Base world-space subdivision interval.
AdaptiveSubdivisionMaxProjectedEdgeDeviationCm
5 cm, at least 0
Allowed curved-projection edge deviation.
MaxSubdivisionDivisionsPerTriangle
24, at least 1
Subdivision limit for one source triangle.
MaxOutputTrianglesPerBakeJob
5,000,000, at least 1
Final triangle safety limit for one bake job.
FPlanetXProjectionResult, material remaps, heightfields, mesh pages, partition output, and instance-batch structures are generated payloads. They are not user settings even where their properties are reflected.
UPlanetXPlanetComponent owns runtime registration and the planet's gravity model on APlanetXPlanetActor.
Setting
Default
Purpose
PlanetAsset
None
UPlanetXPlanetAsset represented by this Actor. It supplies runtime identity, Sections, coordinates, and visual contracts.
PlanetBindingId
None
Distinguishes multiple Actors with the same Planet ID in one World. Empty uses the owning Actor name. Assign a stable value when travel tickets must survive Actor renames.
bAutoRegisterRuntime
true
Registers with the runtime registry at Begin Play. If disabled, call the public registration API yourself.
bRefreshRuntimeRegistrationOnTransformChange
true
Refreshes the registered transform when the Planet Actor transform changes.
GravitySettings.bEnabled
true
Enables gravity queries for this planet.
GravitySettings.Model
ConstantSurface
ConstantSurface maintains surface acceleration; InverseSquare scales it by inverse square of distance from the center.
SpatialEntryPolicy is the group containing the Same World automatic entry and return settings below.
Setting
Default
Purpose
bAutoRegisterRuntime
true
Automatically registers the owner as a PlanetX runtime participant.
RepresentationDomain
Ground
Default representation domain. Ground belongs to the source Level; Orbit appears in Planet/Compare and runtime Orbit/Transition presentation.
ActorSpatialLoadingPolicy
PlanetXManaged
PlanetXManaged keeps an Orbit Actor non-spatial/always loaded. ActorManaged leaves Is Spatially Loaded to the developer. This option does not manage Data Layers or Streaming Sources.
ReferencePlanetActor
None
Planet Actor used as the coordinate reference. It must own a valid Planet Asset and takes precedence over ReferencePlanetId.
ReferencePlanetId
None
ID used when no Planet Actor is assigned. Its options come from Planet Assets on Planet Components placed in the current World.
ReferenceSectionId
None
Enabled Section ID from the resolved Planet Asset. Specify it for reproducible save, capture, and Sequencer paths.
bAutoResolveSectionFromWorld
true
When Section ID is None, selects the first Section containing the current Planet-local position in Asset array order. This is an editor/convenience query, not a persistent identity.
bSyncFromOwnerTransformInEditor
true
Refreshes coordinate snapshots when the root transform changes in the editor. Authoritative runtime state belongs to the World Runtime Subsystem.
TransformSource
WorldTransform
WorldTransform captures the PlanetX pose from the owner. PlanetXTransform generates World Transform from the stored canonical pose. Switching the source does not silently overwrite both values.
Place it on the Actor that is the actual PlayerController View Target and owns the active Camera.
Setting
Default
Purpose
bAutoRegisterRuntime
true
Registers with the Viewpoint registry automatically.
bCanDriveTransitionState
true
Allows this Viewpoint to drive Orbit/Transition/Ground evaluation. Disable it on observational Viewpoints when several are present.
PresentationCompensationMode
Automatic
Automatic resolves a suitable movable child, Disabled turns compensation off, and ExplicitComponent moves only the selected Component. Actor roots are never moved for compensation.
TransitionPresentationComponent
None
Movable child Scene Component that receives presentation compensation in Explicit mode.
These are per-call public Capture/Apply options, not persistent Component Details settings.
Setting
Default
Purpose
SourceCoordinateFrame / TargetCoordinateFrame
None
Select a Planet or Section frame and its identity.
SourceSpaceState / TargetSpaceState
None
Orbit, Transition, or Ground before and after handoff.
LifetimeSeconds
0 s
Snapshot lifetime. Zero can mean immediate expiry; provide a positive value appropriate to the call contract.
ContinuityPolicy
RebaseBetweenFrames
Determines how velocity and angular velocity move from source to target frame.
bDeactivateSource
true
Deactivates the source Movement Component after success.
bActivateTarget
true
Activates the target Movement Component.
bUpdateComponentVelocity
true
Writes converted velocity to the target Component.
bConsumeOnSuccess
true
Consumes the Snapshot so it cannot be applied again.
bRequireSameActor
true
Requires source and target Movement Components to belong to the same Actor.
The class default for UPlanetXSubsystem::MaxCaptureStackDepth is 8. It is an advanced safeguard for nested transition captures, not an ordinary Project Settings entry.
Configuration Reference
Proxy, Morph, and Preview Settings
Use runtime-budget overrides only for diagnostics or an explicit per-Actor requirement; ordinary content should follow Project Settings.
External Level Proxy Bake creates this Actor in the Preview World. It is not a gameplay Actor, and the generation pipeline owns its PreviewBakeData link.
Setting
Default
Purpose
PreviewBakeData
None
Visual-only Bake Data loaded when the Preview World streams in.
bOverrideRuntimeBudget
false
Uses this Preview Actor's values instead of Project Runtime Budget.
MaximumPayloadsPerRequest
8, at least 1
Child payload limit for one request.
MaximumDependenciesPerRequest
64, at least 1
Dependency limit for one streamable batch.
MaximumComponentsPerFrame
2, at least 1
Component creation limit per frame.
MaximumInstancesPerFrame
512, at least 1
Instance realization limit per frame.
RealizationTimeBudgetMs
2.0 ms, at least 0.1
Frame-time limit for Preview realization.
Do not duplicate GameMode, Pawn, Controller, gameplay Actor logic, navigation, or Ground gameplay collision into Runtime Preview. Those remain the responsibility of the actual Ground World.
Configuration Reference
Environment Settings
EnvironmentSettings on the Planet Asset is a reusable planet-wide authoring profile. A Level's PlanetX Environment Manager applies that profile or supplies a Level-only override. Ratios are relative to the canonical Planet Radius; names ending in Km use kilometers.
PlanetXManaged creates and controls PlanetX cloud presentation; UseExistingLevel adopts an existing Level cloud.
CloudProfileSource
PlanetAssetDefaults
Uses the Asset Cloud Profile or a LevelOverride.
CloudProfileOverride
Profile defaults
Complete Cloud Profile editable only for a Level Override.
GroundCloudSource
SamePlanetXCloud
Uses the same PlanetX cloud on Ground or selects ExistingLevelCloud.
AtmosphereMode
PlanetXManaged
Manages PlanetX atmosphere or uses the existing Level atmosphere.
AtmosphereProfileSource
PlanetAssetDefaults
Selects the Asset Atmosphere or a Level Override.
AtmosphereProfileOverride
Profile defaults
Complete Atmosphere Profile editable only for a Level Override.
SunProfileSource
PlanetAssetDefaults
Selects Asset Sun/Cloud Shadow or a Level Override.
SunProfileOverride
Profile defaults
Complete Sun/Shadow Profile editable only for a Level Override.
SpaceBackgroundMode
PlanetXManaged
Manages the PlanetX background or leaves existing Level presentation in place.
SpaceBackgroundProfileSource
PlanetAssetDefaults
Selects the Asset Background or a Level Override.
SpaceBackgroundProfileOverride
Profile defaults
Complete Background Profile editable only for a Level Override.
Resolved Profiles and resolved heights are read-only results. CloudShadow is also a runtime cache derived from the Sun Profile and must not be edited directly.
Applies the current profile during editor construction.
InitialRuntimeSpace
Auto
Leaves startup space to transition state or forces Orbit/Ground. Ground is useful for a Level that begins directly in Ground gameplay without a Transition Endpoint.
bUpdateEveryTick
true
Updates sun, bindings, and transition-dependent environment each tick. Follow the external-runtime-driver contract when another service owns updates.
ManagedPlanetActor
None
Supplies environment center, radius, and the Planet Asset profile.
The Manager's CloudShadow is a cache resolved from SunProfileOverride or the Asset Sun Profile, not an authoring source. Its internal Mode defaults to PlanetXManagedOverride, with bEnableOrbitCloudShadow=true and bRestoreSourceLightWhenGroundActive=true. DesiredOrbitLightShadow serves Orbit Material Approximation, DirectionalLightOverrideShadow serves the Orbit Directional Light, and GroundDirectionalLightOverrideShadow serves Ground. When bUseSeparateGroundDirectionalLightOverride=false, Ground shares the Orbit override. Edit the Sun/Cloud Shadow Profile above instead of this cache.
Configuration Reference
Project and Performance Settings
PlanetX Project Settings are available under Edit > Project Settings > Plugins. Both settings objects are stored in the DefaultEngine.ini configuration hierarchy.
RuntimeBudgetPolicy controls how much work baked Section Proxies, Transition Morph, and Runtime Preview may perform in one frame and one streaming request. It is independent from Proxy Bake Quality, so changing it does not regenerate baked assets.
Policy
Behavior
Follow Engine Scalability
Default. Follows Unreal's current single Quality Level. When scalability groups are mixed, it conservatively uses the lowest level.
Low
Fixes the smallest runtime streaming/realization budget.
Medium
Fixes the intermediate budget.
High
Fixes the default PlanetX product budget.
Epic
Fixes the largest bounded budget. Cinematic scalability also resolves to the Epic profile.
The following overrides take precedence over the project profile for their owning Actor or Component:
bOverrideSectionProxyRuntimeBudget on Planet Proxy Component
bOverrideTransitionRuntimeBudget on Transition Morph Component
bOverrideRuntimeBudget on Runtime Preview Actor
Use an override only for diagnosis or when one Actor genuinely requires different throughput. Values that are too high can create Game Thread spikes and streaming bursts; values that are too low spread Section realization over more frames.
Enables Unreal's image-based lens-flare feature for PlanetX presentation.
LensFlareQuality
3, 0–3
Maps to r.LensFlareQuality: 0=Off, 1=Low, 2=High, and 3=Very High.
PlanetX applies these as Project Setting console-variable values. Ordinary scalability changes do not silently lower them, although command-line and higher-priority runtime overrides can still win.
The per-planet EnvironmentSettings.PostProcess.bEnableLensFlare and LensFlareIntensity settings also apply. Enabling only the per-planet switch cannot activate the renderer feature when lens flare is disabled at project level.
Keep Follow Engine Scalability and measure at the target platform's scalability level.
Use runtime diagnostics to identify whether payload, dependency, component, or instance throughput is the actual limit.
Select a fixed project profile only when the whole project consistently needs a smaller or larger budget.
Use a Component override when only one Actor is exceptional.
If proxy quality or triangle count is the problem, change Proxy Bake Quality or Source Scope and bake again; Runtime Budget is not a mesh-quality control.
After changing Project Settings, review the resulting Config/DefaultEngine.ini change for source control. If only a user-local Saved/Config value changes, teammates and packaged builds may not receive the same setting.
Public API Reference
Public API Overview
PlanetX gameplay integrations use the PlanetX runtime module. The primary Blueprint facade is UPlanetXSubsystem; actors and components provide registration, coordinate, movement, transition, environment, and arrival behavior.
This reference is based on the public headers shipped with PlanetX 1.0 under Source/PlanetX/Public/PlanetX.
Supported gameplay integration surface. Signatures, reflected shape, documented behavior, and failure or consume contracts are protected.
Advanced and Diagnostics API
Supported specialist surface. Breaking changes require deprecation and migration guidance.
Authoring and Editor API
Supported for editor workflows; cooked-runtime support is not implied.
Internal or Test-only API
No external compatibility guarantee.
The presence of a type in a public header does not by itself assign it to a support tier. Avoid treating generated-mesh intermediates, bake passes, runtime services, or serialized implementation payloads as game-facing contracts.
A bool return reports whether the operation completed. Do not consume output parameters after false unless that function explicitly documents diagnostic output.
For enum-returning queries, accept output only for a success status.
Treat None IDs, invalid object references, expired handles, and non-success error enums as normal failure states.
Pass explicit Planet, Binding, Section, and Level Pair IDs when more than one candidate can exist.
Refresh runtime context after registration or streaming changes.
Blueprint display names can differ from C++ symbols. The names and include paths in this reference use the C++ declarations.
Public API Reference
UPlanetXSubsystem
Header: PlanetX/Subsystems/PlanetXSubsystem.h
UPlanetXSubsystem is the Game Instance Subsystem facade for the supported runtime API. Every function with a World Context parameter requires a valid game world. CancelLevelHandoff is the stable exception and accepts only a ticket.
Enters Ground in the current World using a request Actor and successful surface query.
ReturnToOrbitSameWorld
Returns the request Actor through its active Same World journey.
BeginLevelHandoff
Creates an FPlanetXLevelHandoffTicket and result from a source Actor and surface query.
ResolveLevelHandoffTicket
Resolves a ticket into the destination World transform without applying it.
CompleteLevelHandoff
Applies a ticket to the target Actor; bApplyControlRotation defaults to true.
CancelLevelHandoff
Cancels a ticket. This function has no World Context parameter.
PlanetX prepares and restores handoff state but does not call Open Level, spawn the destination Actor, possess a pawn, or choose a GameMode. Game code owns those steps.
Transition math and sync: EvaluateTransitionCylinderState, CaptureTransitionActorSyncPose, ApplyTransitionActorSyncPose
PrepareTravel accepts FPlanetXTravelRoute. PlanetX selects automatically only when exactly one Planet Actor candidate exists. An explicit index of 0 is valid; if both PlanetActorIndex and PlanetBindingId are supplied, both must identify the same candidate.
Diagnostic drawing functions do not return a success value. Validation execution success and a validation result with no issues are separate conditions.
RegisterToPlanetXRuntime returns whether registration succeeded. UnregisterFromPlanetXRuntime returns void. Both are in the PlanetX|Planet Blueprint category.
The actor exposes Blueprint-read-only references to Root, PlanetComponent, PlanetProxyComponent, TransitionMorphComponent, SkyAtmosphereComponent, and VolumetricCloudComponent. Assign the Planet Asset through the Planet Component and keep Planet and Binding IDs unambiguous.
This actor has no Blueprint-callable functions. Its reflected properties define the authoring contract:
Properties
Purpose
PlanetId, SectionId, LevelPairId, EndpointRole
Identifies the endpoint and whether it represents Orbit or Ground.
PlanetAsset, PlanetActor, EnvironmentManagerActor
Links policy data and participating actors. PlanetActor applies to Orbit endpoints.
CoordinateComponent
Holds the endpoint's canonical reference and pose.
TransitionCylinder
Defines the transition region.
bAutoSizeTransitionCylinderToSectionBounds
Derives the cylinder from Section bounds when enabled.
RuntimeAlphaUpdateThreshold
Limits small runtime alpha updates.
IDs must match a real Section and Level Pair in the resolved Planet Asset. Ground endpoints require the Planet Asset; Orbit endpoints can infer it from the Planet Actor when available.
ValidateEnvironmentBinding is the only main environment command that returns bool. Use it before the void mutation functions and resolve reported binding problems first.
Apply and restore overrides as matched operations. A void command does not provide a success result; validate bindings and inspect the matching active-state query where one exists.
The Coordinate Component stores a canonical PlanetX pose and resolves the Planet, Binding, Section, and coordinate frame used by its owner. Configure a reference, make sure the Planet Actor is registered, and call RefreshRuntimeContext after relevant streaming or registration changes.
The editor-callable helpers RefreshCoordinateSnapshot, PullFromWorld, PushToWorld, CaptureOwnerTransformToPlanetX, and ApplyPlanetXTransformToOwner synchronize the stored pose and the owner transform explicitly.
RefreshReferenceDetails, GetResolvedPlanetComponent, GetCachedRuntimeContext, and GetRepresentationDomain expose the resolved reference and context. GetActorSpatialLoadingPolicy, ShouldForceOwnerAlwaysLoaded, and ApplySpatialLoadingPolicyToOwner implement the current spatial-loading policy. Data Layers and Streaming Sources remain project-owned.
The owner requires a Coordinate Component and a committed runtime context.
Stable function
Contract
AddPlanetXInputVector
Adds input in a selected vector space. Defaults to SurfaceFrame with tangent projection enabled.
SetPlanetXVelocity
Sets velocity in the selected vector space; the default is World.
GetPlanetXVelocity
Converts current velocity to the requested vector space.
AddPlanetXForce
Adds force; the default space is World, and bAccelerationChange defaults to false.
AddPlanetXImpulse
Adds impulse; the default space is World, and bVelocityChange defaults to false.
SnapToPlanetSurface
Uses FPlanetXSurfaceSnapSettings to move to the resolved surface.
AlignUpToPlanetSurface
Uses FPlanetXSurfaceAlignmentSettings to align the owner.
ValidateMovementConfiguration
Writes an error message when configuration is invalid.
Every stable function returns bool. GetMovementRuntimeState and GetCommittedRuntimeContext are the approved advanced state reads. When another Movement Component or a physics body owns velocity across a representation change, use Movement Handoff.
Registration requires a valid World, Planet Asset, and identity. When several components share a Planet ID, use the Binding ID for deterministic lookup.
Set or read sources with SetPlanetAsset, GetPlanetAsset, SetPlanetMaterialOverride, GetPlanetMaterialOverride, SetPlanetSphereMeshOverride, and GetPlanetSphereMeshOverride.
Rebuild or clear presentation with RefreshProxy, RebuildPlanetProxy, RebuildSectionProxiesFromPlanetAsset, and ClearSectionProxies.
Control visibility with SetPlanetProxyVisible, SetSectionProxiesVisible, SetSectionProxyMorphAlpha, and GetSectionProxyMorphAlpha.
Inspect presentation with GetPlanetSphereComponent, GetSectionProxyResidencyState, and GetSectionProxyRealizedComponentCount.
RebuildSectionProxiesFromPlanetAsset returns the number created. The other rebuild, clear, and visibility commands in this group return void; inspect residency and counts afterward when the result matters.
Count-returning mutations use the affected-entry count; 0 means no matching entry was changed. Boolean mutations report whether their requested operation succeeded.
Debug presentation uses SetDebugOverlaySettings, GetDebugOverlaySettings, and SetDebugOverlaysVisible.
UPlanetXViewpointComponent is declared in PlanetX/Components/PlanetXViewpointComponent.h. GetTransitionFrame and MapViewDirectionToMovement return bool; use their outputs only after success.
UPlanetXTravelReceiverComponent is declared in PlanetX/Components/PlanetXTravelReceiverComponent.h. It has no Blueprint-callable functions. Configure bAutoResumePendingTravel, bApplyControlRotation, and ArrivalRetryTimeoutSeconds; inspect bLastResumeSucceeded, LastResumeError, and State, or bind OnTravelResumed and OnTravelResumeFailed. The component does not own level opening, spawning, possession, or GameMode selection.
Updates correction settings or re-links authoritative Bake Data.
MarkVisualPreviewBuildSucceeded is a void Blueprint-callable function in PlanetX|Revision; call it only after a successful preview build. Prefer these methods and the Planet Asset Editor over direct mutation so revision and staleness tracking remains coherent.
This Blueprint type has no Blueprint-callable functions. Its editable fields are PresetId, DisplayName, PresetType, CompletionSettings, PaddingSettings, BaseSurfaceMaterial, OptionalBiomeMask, and OptionalHeightMask. Keep PresetId stable and make sure referenced materials and textures are included in the cook.
UPlanetXRuntimeDeveloperSettings is declared in PlanetX/Settings/PlanetXRuntimeDeveloperSettings.h. Its project-wide config field is RuntimeBudgetPolicy, which defaults to EPlanetXRuntimeBudgetPolicy::FollowEngineScalability.
UPlanetXRenderingDeveloperSettings is declared in PlanetX/Settings/PlanetXRenderingDeveloperSettings.h. Its config fields are bEnableLensFlares, defaulting to true, and LensFlareQuality, defaulting to 3 with a valid range of 0 through 3. ApplyConsoleVariables is a C++ member, not a Blueprint function.
The library stores a versioned movement snapshot and returns an FPlanetXMovementHandoffHandle. Later calls resolve, apply, consume, or cancel that handle. All ten public operations return bool and also write FPlanetXMovementHandoffResult; inspect both before using outputs.
Resolves a handle to destination World linear and angular velocity using EPlanetXMovementContinuityPolicy.
ApplyMovementComponentHandoff
Applies a handle to a destination UMovementComponent using FPlanetXMovementHandoffApplyOptions.
ApplyPhysicsBodyHandoff
Applies a handle to a destination physics body.
SwitchMovementComponentsWithHandoff
Captures the source, switches component activity according to the options, and applies to the target.
Apply options control continuity, source deactivation, target activation, component-velocity update, consume-on-success, and same-Actor enforcement. A failed switch is not permission to assume component activity or velocity changed as intended; inspect the result and current components.
Reads the snapshot identified by a handle without consuming it.
ConsumeMovementHandoff
Marks a pending handle consumed.
CancelMovementHandoff
Marks a pending handle cancelled.
Use the returned handle rather than looking up state by Actor. A handle can fail because it is invalid, expired, consumed, cancelled, or no longer matches the stored generation. Capture immediately before the transition, resolve and apply after the destination frame is available, and consume only after successful application.
FPlanetXTransform is a Blueprint type with these reflected fields: DataVersion, PlanetId, PlanetBindingId, PlanetFixedPositionCm, PlanetFixedRotation, and Scale3D. Position is stored in centimeters. Use UPlanetXSubsystem or UPlanetXCoordinateComponent to resolve and capture it; do not treat a World transform as a representation-independent saved pose.
Stable reflected enums include EPlanetXTransformSource, EPlanetXMovementHandoffState, EPlanetXMovementContinuityPolicy, and EPlanetXMovementVectorSpace. Compile and serialize against the headers from the plugin version you ship; do not invent numeric values or layouts.
FPlanetXTravelRoute is declared in PlanetX/Transition/PlanetXTransitionTypes.h and contains World, PlanetId, SectionId, PlanetActorIndex, and PlanetBindingId. PlanetActorIndex defaults to INDEX_NONE. Automatic selection is allowed only when exactly one candidate exists; 0 explicitly selects the first deterministic candidate. If both selectors are set, the index and Binding ID must agree.
FPlanetXCoordinateUtils provides pure C++ conversions among supported coordinate representations. Use UPlanetXSubsystem when a conversion requires the runtime registry. Preserve centimeter units, finite values, and normalized direction assumptions, and check every success result.
PlanetXValidation provides structured validation for C++ tools. Preserve severity, code, subject, and remediation text. Validation does not implicitly repair or save assets.
Generated-mesh data, boundary reconstruction intermediates, bake passes, internal runtime services, and shard or serialization payloads are not stable game save or network contracts merely because a declaration is publicly visible.
Check PlanetX.uplugin and the project's EngineAssociation. The current baseline is UE 5.8 with Runtime and Editor modules. GeometryProcessing and PCG must be enabled, and the target-platform toolchain must be installed.
Inspect the first module-load error in the Editor log. Later compile failures can be cascading results.
A valid Reference Planet Actor on the Coordinate Component takes priority over Planet ID. Confirm that its Planet Component has a Planet Asset and registered successfully at runtime.
When multiple actors share one Planet ID, provide Planet Binding ID. The Section dropdown is populated from enabled Sections on planets placed in the current World, not from every asset in the Content Browser.
EPlanetXActorSpatialLoadingPolicy::PlanetXManaged keeps Orbit actors non-spatial. With ActorManaged, the project owns Is Spatially Loaded. Data Layers and Streaming Sources are not modified automatically. Use GetActorSpatialLoadingPolicy, ShouldForceOwnerAlwaysLoaded, and ApplySpatialLoadingPolicyToOwner when diagnosing the effective setting.
Confirm a valid Planet Asset, Section, and Source World. Stop PIE and ensure another external worker does not own the operation. If an External Level Section is opened from a different Level, the editor can request a move to the required Level.
Inspect SourceOmissions on BakeData. Each record stores Reason, PassId, actor and component path, class, and detail.
Typical reasons include:
Spline Mesh deformation
Unsupported component class
Cloth or deformable content
Missing mesh or LOD
Projection range exceeded
Unsupported or sky material
Nondeterministic dynamic source
Unavailable saved PCG managed resource
For intentional exclusion, author an explicit source policy or NoBake tag. For missing visible content, convert it to a supported Static Mesh, Instance, or Landscape source.
Changes to Planet Asset structure, Section placement, Source World content, Source Material, quality, or visual-generation input can make the revision stale. Scan, recalculate the plan, bake again, and run Full Validate.
The browser Monitor is optional and does not own the Bake. If its local service or system browser cannot open, External Bake continues; use the Editor status and Unreal log for progress. Do not copy or share a complete Monitor URL because it contains a local session token.
The direct Worker hosts the Monitor while the Bake is active. Its service ends when the Worker exits, so an existing tab may show Disconnected after completion. Restart or return to Unreal Editor and select Open External Bake Monitor to host the latest durable result again. The previous tab is not migrated automatically.
Packages over 512 MiB warn; publication fails over 1 GiB. Split large indivisible sources and review partition, shard, and instance-aggregation output. The 128 MiB source-spool target is not the final uasset size.
The Planet Actor, Planet Asset, current World, or World runtime service is not ready. Check Begin Play and streaming order. Use RefreshRuntimeRegistration on the Planet Component and RefreshRuntimeContext on participants.
Use the detailed status to distinguish InvalidInput, RuntimeUnavailable, and Miss. Verify a nonzero ray direction, a Planet and Binding present in the current World, and valid Section bounds and BakeData.
The SectionLocalToGroundWorld mapping stored in the capture is authoritative for a Level Handoff Ground pose. Do not overwrite it by manually aligning Source and Target Planet Actor transforms. Use DiagnoseProxySync and ResolvePlanetAlignmentForSection.
Stat PlanetXMemory
Stat PlanetXResources
Stat PlanetXProxy
Stat PlanetXProxyDetail
Stat PlanetXRuntime
Memory reports runtime resources and budget; Resources reports counts; Proxy reports render coverage; Runtime reports service cost. The diagnostic World is selected by PIE/Game and preferred Preview World priority.
UPlanetXSubsystem can query actor runtime context, movement state, transition result, managed-actor state, Section runtime state, and Journeys. DrawPlanetDebug, DrawSectionDebug, DrawActorContextDebug, and DrawCaptureStackDebug visualize spatial state in development builds.
Record the reproduction World, Planet/Binding/Section IDs, asset validation, Proxy Bake revision and omissions, Travel Result error, and relevant Stat or Dump output. Review path data for sensitive information before external sharing.
Release Notes
PlanetX 1.0.1
PlanetX 1.0.1 is now available on Fab. This maintenance release improves Browser Monitor recovery, PlanetX Mode transform editing, and presentation control.
External Browser Monitor: a missing browser acknowledgement no longer makes the Monitor endpoint or an external bake appear to have failed. Browser launch is best-effort and the endpoint remains available for recovery.
PlanetX Mode transform gizmo: ordinary Actors and multi-selection now fall back to Unreal Engine's native transform gizmo. PlanetX keeps its specialized gizmo for one selected Actor with a Coordinate Component.
Global presentation:UPlanetXCoordinateComponent now exposes Presentation Scope. Set it to Global when an Actor must remain visible in Ground, Orbit, and Transition. This is presentation-only; its Representation Domain, coordinates, Proxy Bake eligibility, and physical-frame ownership do not change.
This product was independently developed by me(us) while participating in the Epic Project, a developer-support program of the KRAFTON JUNGLE GameTech Lab. All rights, title, and interest in and to the product are exclusively vested in me(us). Krafton, Inc. was not involved in its development and distribution and disclaims all representations and warranties, express or implied, and assumes no responsibility or liability for any consequences arising from the use of this product.
#Solar System Scope planet surface and space background textures
The PlanetX sample planet surface textures and the space background texture contain or are derived from texture data provided by Solar System Scope / INOVE. The Unreal Engine Materials and Material Instances that reference those textures fall under the same scope.
Imported and converted the source planet surface textures and space background texture into Unreal Engine content asset format.
Incorporated the converted textures into sample planet Materials, the space background Material, and their related Texture, Material, and Material Instance assets.
Unreal Engine import, compression, mipmap, sampling, and Material settings may alter the presentation of the original textures.
CC BY 4.0 applies only to the planet surface textures, the space background texture, and the content that uses them as identified above. It does not apply to the PlanetX source code or to any other original PlanetX asset.
Nothing in this notice is intended to restrict any rights granted under CC BY 4.0 with respect to the Solar System Scope-derived content.
Solar System Scope and INOVE do not endorse, sponsor, or officially support PlanetX.
Apart from the planet surface textures and the space background texture identified above, PlanetX uses no third-party works. All other source code, Materials, Meshes, icons, documentation, and Proxy Bake Monitor web resources were authored by LabX. The documentation site loads no external scripts, fonts, or stylesheets and works without a network connection.