MultiWorld  1.0.0
Setup and Checklist

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 UE4 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 4. 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.
    ProjectSettings-MultiWorldGameInstance.png
    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.
    ProjectSettings-MultiWorldGameViewportClient.png
    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 UE4 system calls.

Network replication

While the Main World is network-replicated as usual by UE4, 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 UE4 network replication implementation.

Split screen

Split screen is not supported.

Input Modes

Calls to the SetInputMode*() methods (SetInputModeGameOnly, SetInputModeUIOnly, SetInputModeGameAndUI, etc.) apply to the UE4 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 UE4 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:

WorldOutliner.png
Manually selecting a Secondary World in the World Outliner

UMG Widgets

In UE4, 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 4. 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.

bDuplicateOnLoad

If you want to load multiple instances of the same Secondary World, then you must enable the flag FMultiWorldLoadParameters::bDuplicateOnLoad on ALL related calls to UMultiWorldStatics::LoadWorld() / UMultiWorldStatics::LoadWorldAsync(), including the first call.