Setup and Checklist

Table of Contents

• Setup and Checklist
  • Project setup
  • Network replication
  • Scene capture
  • Split screen
  • Input Modes
  • World Outliner
  • UMG Widgets
  • Audio management
  • Level Sequence

Setup and Checklist

Important notes and limitations that must be known to properly use the plugin.

Please read this document carefully. It explains how to configure the plugin and lists known technical limitations and specific behaviors.

An important part of the management of the active UWorld in UE5 is done by UGameViewportClient. Some of its behaviors can't be customized at the moment, and this causes some of the known limitations in the plugin.

Project setup

To integrate the MultiWorld plugin into a project, a simple preliminary setup is REQUIRED. MultiWorld needs to intercept some system calls of Unreal Engine 5. This can be quickly accomplished configuring few pre-made classes (provided with the plugin) in your Project Settings:

• override the Game Instance class: go to "Project Settings", "Project > Maps and Modes" section, search for the property "Game Instance Class" and set it to MultiWorldGameInstance.
  

  Set MultiWorldGameInstance as new Game Instance
• override the Game Viewport Client class: go to "Project Settings", "Engine > General Settings" section, search for the property "Game Viewport Client Class" and set it to MultiWorldGameViewportClient.
  

  Set MultiWorldGameViewportClient as new Game Viewport Client

If you're already using custom overrides of the above settings, you can:

• simply inherit your implementations from our classes (still guaranteeing the point below);
• follow ALL the instructions in UMultiWorldOverrides to provide the needed hooks into the required UE5 system calls.

Network replication

While the Main World is network-replicated as usual by UE5, Secondary Worlds exist only on the local clients and are not network-replicated.

In a multiplayer game, only the Player Controller in the local replicated Main World has a valid owning connection. So, if you need any networking service, you must do it through this particular instance. You can retrieve this object using one of the helper methods like UMultiWorldStatics::GetAllActorsOfClass() and UMultiWorldStatics::GetMainWorldHandle().

While you can manually configure the Main World to stop Ticking when in Background (see Active World), for multi-player games you MUST ensure that the Main World is configured to Tick also when in Background (this is already the default configuration). This is required by the UE5 network replication implementation.

Scene capture

Capturing renders from a ticking Background World is supported using the component class UMultiWorldSceneCaptureComponent2D and the actor class AMultiWorldSceneCapture2D. The render target they update can then be used in any World as usual.

The provided classes must be used in place of the standard USceneCaptureComponent2D and ASceneCapture2D classes, as the standard versions fail to capture the scene when in a Background World.

Capturing scenes from other worlds allows you to create a number of creative visual effects. You can quickly create a simple security camera effect or, with a proper portal implementation, to create astonishing seamless visual transitions between distinct UWorld instances.

Skylight and "Real Time Capture" option

The Skylight could not render correctly in the UMultiWorldSceneCaptureComponent2D component when the "Real Time Capture" option is enabled and the component is in a Background World. For details and the workaround see Skylight "Real Time Capture".

Split screen

Split screen is not supported.

Input Modes

Calls to the SetInputMode*() methods (SetInputModeGameOnly, SetInputModeUIOnly, SetInputModeGameAndUI, etc.) apply to the UE5 viewport and not to the UWorld, so they "leak" through worlds when you're switching the Active World.

If your Worlds require different Input Modes, a general solution is to restore the needed Input Mode each time a World is activated (see Being notified of World Switching).

World Outliner

MultiWorld plugin is compatible with the UE5 Editor World Outliner. This means that, while playing in editor, you can inspect actors living in any world, including any Secondary World. You must only pay attention to manually select the World you want to inspect, not relying on the Auto option:

Manually selecting a Secondary World in the World Outliner

UMG Widgets

In UE5, the scope of UMG Widgets is the viewport and not the UWorld. If the flag FMultiWorldLoadParameters::bAutoHandleWidgets is enabled when loading a Secondary World, the plugin will automatically handle the switching of widgets on screen, transparently bounding their visibility to the Active World : temporarily removing all the widgets when a World moves to background and restoring any previously existing widgets when a World moves in foreground (see Active World).

In case of issues, we suggest you to have your Level Blueprint implementing the IMultiWorldActorInterface interface, and create/remove your UMG HUD overriding the available methods. See Being notified of World Switching for further details.

If you need a different behavior, you can set FMultiWorldLoadParameters::bAutoHandleWidgets to false (see also UMultiWorldStatics::SetAutoHandleWidgetsForMainWorld()) and manage the widgets yourself.

Audio management

By default, each Secondary World has an independent and isolated Audio Device. This means that when the Active World changes, the player will not be able to hear sounds from other Worlds. You can disable this behavior setting FMultiWorldLoadParameters::bCreateDedicatedAudioDevice to false when loading the Secondary World. This will causes the Secondary World to use the same Audio Device as the Main World.

If you need to customize how the audio is managed between the Worlds, you can set FMultiWorldLoadParameters::bCreateDedicatedAudioDevice to false when loading the Secondary Worlds, and implement a custom strategy yourself using the available features of Unreal Engine 5. For example:

• implementing the IAudioModulation interface to inject a custom FSoundEffectSource that zeroes/copy the processed audio data as needed;
• createing a custom USoundClass to mute a sound, setting it to all active sounds that must be muted (and restoring the original sound classes when no longer needed).

See Being notified of World Switching to be notified when a World Switch occurs.

Level Sequence

A Level Sequence Actor explicitly references the UMAP level used by it. This is a problem when the same UMAP level is loaded in multiple Secondary Worlds. MultiWorld only supports Level Sequences bound to the first UMAP level instance loaded; Level Sequences on other UWorld instances of the same UMAP level will have undefined behavior (and must be avoided).