Issues¶
This page lists current limitations and the first checks to perform when Wormhole Portal does not behave as expected.
Current compatibility target
Version 1.0 is officially tested and supported on Unreal Engine 5.8, Win64, DirectX 12, and SM6. See Compatibility and Support before using another environment.
Known limitations¶
| Area | Current limitation |
|---|---|
| Supported release environment | Unreal Engine 5.8, Win64, DirectX 12, and SM6. Other environments are not declared supported. |
| Rendering views | Portal compositing supports one primary, perspective, non-stereo Game View. |
| Unsupported views | Scene Capture, Reflection Capture, Planar Reflection, orthographic, stereo/VR, split-screen, and other multi-view families do not composite the portal. |
| Movie Render Queue | The main deferred mono beauty output is supported. Custom passes, Virtual Texture passes, stereo, and multi-view outputs omit the composite. |
| Server targets | The renderer module is excluded from Server targets. Do not expect portal visuals on a dedicated server. |
| Portal scale | Both linked Portal Actors must use Actor Scale (1, 1, 1). Use metric or visual-scale APIs instead. |
| Transit primitives | Transit requires actor-owned, Movable, collision-enabled Primitive Components. Instanced Static Mesh Components are unsupported. |
| Physics transit | At least one non-instanced Static Mesh Component with a valid mesh, or supported Shape Component, must have Physics collision enabled and be simulating. |
| Voxel collision | Baking supports non-instanced Static Mesh Simple Collision plus Box, Sphere, and Capsule Components. Static Mesh elements may be Sphere, Box, Capsule, or Convex. |
| Portal traces | Public Blueprint APIs provide Line Trace By Channel operations. Object Type, Profile, and Sweep variants are not implemented. |
| Ray transform | Transform Ray Through Portal accepts a ray approaching the portal from outside toward its interior. |
| Trace exit offset | Portal Exit Offset prevents immediate self-hit but does not consume remaining distance. The offset gap is not collision-tested. |
| Audio | Portal audio supports one primary listener, one portal hop, and eligible active spatialized 3D Audio Components. |
| Lighting | Only Point and Spot Lights are transmitted. Directional Lights may be collected internally but are not transmitted. |
The portal is not visible¶
Check in order:
- The Portal Actor has a valid Linked Portal.
- Both endpoints use Actor Scale
(1, 1, 1). - The project is running Win64 with DirectX 12 and SM6, using a primary Perspective Game View.
- The view is not a Scene Capture, reflection, stereo/VR, or split-screen family.
- If Transition Length is greater than zero, wait for the asynchronous runtime fallback or bake a compatible LUT.
- Filter Output Log by
LogWormholeand inspect Renderer entries for theReason=...field. To include unsupported-view result changes, temporarily runLog LogWormhole VeryVerbosebefore reproducing the issue.
Typical renderer reasons include InvalidPairOrTransform, MetricInvalid,
MetricMismatch, UnsupportedScale, CaptureNotSubmitted,
MissingTextureReference, UnresolvedReferencedTexture, and
WrongTextureDimension.
Unsupported-view reasons include SceneCaptureOrReflection,
UnsupportedGameProjectionOrFeatureLevel, StereoView,
NotExactlyOneFamilyView, and NonPrimaryPlayerView.
The WPPortalTrace warning keeps appearing¶
Wormhole Portal requires a dedicated Trace Channel named WPPortalTrace. Use
Add Automatically in the startup notification when possible, then restart
the Editor.
| Problem | Resolution |
|---|---|
| Wrong channel type | Make sure WPPortalTrace is a Trace Channel, not an Object Channel. |
| Channel mismatch | Align Portal Trace Channel in plugin settings with the Game Trace Channel assigned by Unreal. |
| No free Game channel | Free an unused Game Trace Channel before retrying. |
| Read-only configuration | Check out or make Config/DefaultEngine.ini writable. |
| Manual setup | Create WPPortalTrace with Default Response: Ignore, align the plugin setting, and restart. |
Do not pass WPPortalTrace as the ordinary collision channel for a
portal-aware trace. It is reserved for internal portal detection.
LUT baking fails¶
Open Tools > Wormhole Portal > Bake All LUTs, then check:
- an Editor World and at least one Portal Actor exist;
- Generated LUT Asset Path is a valid Unreal Long Package Directory with
the case-sensitive prefix
/Game/; - the portal metric is valid;
- the requested
Transition Length / Portal Radiusrange is inside the chosen LUT domain; - source control permits generated packages to be checked out and saved; and
- the bake was not cancelled.
The code-default generated directory is:
/Game/WormholePortal/Generated/LUT
Installed-plugin paths such as /WormholePortal/... are not valid generated
LUT locations. A success notification begins with LUT ready:. A baked LUT is
optional while Allow Runtime LUT Fallback is enabled; Transition Length =
0 uses the analytic path and needs no LUT.
The LUT works in Editor but not in a packaged build¶
The Editor module attempts to synchronize Generated LUT Asset Path with
DirectoriesToAlwaysCook. If it reports that the project configuration could
not be updated:
- Check out or make the reported config file writable.
- Restart the Editor so startup synchronization runs again, or add the path manually under Project Settings > Packaging.
- Confirm the configured path appears in Additional Asset Directories to Cook.
The default entry is:
[/Script/UnrealEd.ProjectPackagingSettings]
+DirectoriesToAlwaysCook=(Path="/Game/WormholePortal/Generated/LUT")
For a custom path, use the validated /Game/... value exactly.
Runtime metric changes are rejected¶
Set Portal Radius, Set Throat Half Length, and Set Transition Length are
independent authoring/pre-BeginPlay setters. Calls after BeginPlay are rejected
to prevent the three physical values from drifting apart.
At runtime:
- call Initialize Physical Metric once with the complete
ρ,a, andTshape; - use Set Uniform Physical Metric Scale for a ratio-preserving physical resize; or
- use Set Portal Visual Scale for inexpensive render-only animation.
A later Initialize Physical Metric call is accepted only if it preserves
the original a/ρ and T/ρ ratios. Set Metric Parameters is a deprecated
alias and should not be used in new work.
Transit does not start¶
Open Tools > Wormhole Portal > Transit Manager and inspect the exact Actor status.
| Status | What to check |
|---|---|
Not Supported |
The Actor does not match Character, Projectile, Pawn, or Physics requirements. |
Needs Setup: Transit is disabled |
Enable Transit Enabled on its WPTransitComponent. |
Needs Setup: Transit settings are invalid |
Review the selected Transit Type and reported components. |
Needs Setup: No movable collision Primitive was found |
Add an actor-owned, Movable, collision-enabled Primitive that can overlap the portal trigger. |
Needs Setup: No supported Primitive is simulating Physics. |
For Physics transit, enable Physics collision and simulation on a supported non-instanced Static Mesh or Shape Component. |
Needs Setup: Bake Voxel Body for a supported Primitive |
Enable voxel collision and bake data for the indicated supported Primitive. |
Needs Setup: Bake Voxel Body for <asset/component names> |
Bake or repair voxel data for every name reported by Transit Manager. |
Runtime rejection details are Verbose and compiled only in non-Shipping builds.
Before reproducing, enter Log LogWormhole Verbose in the console or launch
with -LogCmds="LogWormhole Verbose".
[Transit][Rejected] TimestampSeconds=... RuntimeReason=EWPTransitFailReason::... ResolveReason=EWPTransitResolveFailReason::... FailedComponents=... Actor=... SourcePortal=... DestinationPortal=... TransitType=EWPTransitType::...
RuntimeReasonidentifies the transit lifecycle failure.ResolveReasonidentifies the setup resolver failure.FailedComponentsnames the components implicated by resolution.
DoesNotFitGate means the Actor's projected cross-section perpendicular to its
movement does not fit the source portal gate/core radius. Increase Portal
Radius or correct/reduce the Actor collision bounds; never scale the Portal
Actor.
Possible runtime reasons are listed in full in
Reference. With World Partition,
NotReady can mean the linked area has not finished streaming. Keep the Actor
outside the boundary until IsLinkedPortalAreaReady() returns true.
Voxel Body baking fails¶
Verify that:
- Use Voxel Collision is enabled on
WPTransitComponent. - Each participating Primitive is actor-owned and non-instanced.
- A Static Mesh is saved and has usable Simple Collision, or the component is a supported Box, Sphere, or Capsule Component.
- Static Mesh Simple Collision uses Sphere, Box, Capsule, or Convex elements.
- Voxel Size is greater than zero.
- Max Voxel Count is
1–512and is sufficient for each Primitive.
Max Voxel Count applies per baked Primitive, not once per Static Mesh or Actor. Tapered capsules, level sets, skinned triangle collision, instanced meshes, and other unsupported collision types cannot be baked.
The default generated Voxel directory is
/Game/WormholePortal/Generated/Voxels. A custom Voxel directory must be a
valid Long Package Directory under the case-sensitive /Game/ prefix.
Dynamic cubemap resolution is unexpected¶
Project configuration can override the plugin defaults. Inspect Lowest Visible Resolution, every Resolution Tier, and Inside SafeProxy Resolution under the plugin's Scene Capture settings.
At runtime, tier thresholds clamp to 0–100% and are stable-sorted. Resolutions
round up to an 8-pixel multiple in 8–2048, tiers cannot decrease below the
previous effective tier, and inside resolution cannot fall below the lowest
resolution. An empty tier list uses the lowest value outside the safe proxy.
There is no plugin-local memory-budget downgrade. Use stat WormholePortal to
observe cubemap memory; edit the resolution policy to reduce it.
Material clipping does not work¶
Material clipping is optional and does not modify arbitrary materials.
Check that Use Material Clip is enabled, the material uses the supplied
transit clip Material Function, the material and Project Settings use the same
Clip Base Index, and four consecutive Custom Primitive Data slots beginning
at that index are free. The default index is 28.
Portal audio is not heard¶
Portal audio needs an eligible active 3D Audio Component. Check that:
- spatialization and spatialized attenuation are enabled;
- the sound is not a UI/2D sound or Source Bus asset;
- the component is registered, playing, and not configured for multiple simultaneous instances;
- its attenuation range reaches the portal;
- the source is outside the portal sphere; and
- neither component nor owner has
WP.PortalAudio.Disabled.
Generated proxies are excluded from retransmission, so audio currently travels through one portal hop.
Portal lighting is not visible¶
Only Point and Spot Lights are transmitted. Check that the source is enabled,
affects the World, has nonzero intensity, reaches the entry aperture, is not
inside the portal, and is not tagged WP.PortalLight.Disabled. Both endpoints
must use unit scale and matching radii.
For source shadows, also enable Enable Portal Source Shadows, Cast Shadows, and Cast Dynamic Shadows. Directional and Rect Lights, asymmetric radii, lights inside a portal, GI, reflections, volumetrics, translucent shadows, and colored shadows are not transmitted.
Diagnostics to collect¶
Before requesting support, collect:
- Unreal Engine version and plugin version;
- target platform and whether the renderer is present;
- PIE, SIE, Standalone, packaged, or Movie Render Queue context;
- the smallest reproduction steps;
- Output Log entries filtered by
LogWormhole; - the full non-Shipping Verbose transit rejection line, when applicable;
- screenshots of the Portal Actor and relevant component/settings panels; and
stat WormholePortaloutput for rendering or capture problems.
Use the submission checklist on the Support page so a report can be reproduced without a second round of basic questions.