MultiWorld  1.0.0
Main Concepts

Main Concepts

The main concepts used by the plugin.

World Handle

A World Handle is a transient reference to an Unreal Engine 4 UWorld object. An UWorld object, accordingly to the UE4 documentation, "is the top level object representing a map or a sandbox in which Actors and Components will exist and be rendered".

A World Handle can reference the Main World or a Secondary World.

You can store a World Handle as a Blueprint variable, but you can't save it permanently because it's a run-time transient value managed by the plugin.

You can retrieve the World Handle of the UWorld you are operating in, calling UMultiWorldStatics::GetThisWorldHandle(). Technically it's the UWorld of the World Context Object implicitly passed by UE4 to the function.

GetThisWorldHandle.png
GetThisWorldHandle

Main World

The Main World is the "standard" UWorld loaded by Unreal Engine 4. The plugin doesn't manage it in any way. An UE4 game has a single Main World instance, created and managed by UE4 itself. This UWorld supports all the features provided by Unreal Engine 4, including network replication for multiplayer games.

You can retrieve the World Handle of the Main World using the method UMultiWorldStatics::GetMainWorldHandle().

GetMainWorldHandle.png
GetMainWorldHandle

You can change the level in the Main World using the standard UE4 OpenLevel() and similar methods.

The Main World can be configured to stop Ticking while in background (see Active World). If your game supports network-replication (i.e. is a multiplayer game), please read also Network replication.

Secondary Worlds

A Secondary World is any UWorld object created/loaded by the plugin. Any standard UE4 Level/UMAP can be used as-is as a Secondary World.. At run-time, Secondary Worlds are exclusively managed by the plugin. An important limitation of Secondary Worlds is that they exist only on the local clients and are not replicated.

You can create/load a new Secondary World with the method UMultiWorldStatics::LoadWorld() and destroy/unload it when no longer needed with UMultiWorldStatics::EndWorld(). Note that Secondary Worlds are never automatically destroyed, also when calling OpenLevel() on the Main World.

LoadWorld.png
LoadWorld
EndWorld.png
EndWorld

MultiWorld complies to the normal behavior of the standard UE4 Gameplay Framework, including the Game Mode and Game State systems.
When a Secondary World is loaded and initialized, the same process as the standard UE4 OpenLevel() is followed: the Game Mode of the loaded world is created, the configured Player Controller is instantiated, the Player Pawn is spawned and possessed, the configured Game State and Player State are created and configured, etc.
This means that each World has its own Game Mode, Player Controller, Player Pawn, Game State, Player State, etc. If you need to access the equivalent objects from another World, you can - for example - use one of the available helper methods like UMultiWorldStatics::GetAllActorsOfClass(). Only the Player Controller of the currently Active World is receiving the user inputs.

ULocalPlayer is unique in the game for each local physical player.

Secondary Worlds can be configured to Tick while in background (see Active World).

For more complex setups, you can also load worlds asynchronously using UMultiWorldManager::LoadWorldAsync().

Example-BindEventToOnAsyncLoadCompleted.png
Load World Async

By default, Secondary Worlds are automatically initialized when loaded (i.e. the UWorld, all the objects related to the Gameplay Framework and all the Actors in the map are initialized; the Game Mode is activated and all the needed BeginPlay() methods called; etc.). While this is REQUIRED to be able to activate the loaded World later, this takes time and consumes memory. If you want to postpone the initialization, you can disable this behavior setting FMultiWorldLoadParameters::bAutoInitializeWorld to false when loading a Secondary World. In this case, you MUST manually call UMultiWorldStatics::InitializeWorld() before ANY usage of the loaded World (other that calling UMultiWorldStatics::EndWorld()).

Active World

At any time, exactly and only one UWorld is "interacting with the user", meaning it's receiving the player's inputs and rendering to its viewport. This world is the Active World and all other worlds are Background Worlds.

You can make a Background World the Active World calling the method UMultiWorldStatics::SwitchWorld(). The player will be automatically transferred to the new UWorld. When done, new instances of Game Mode, Player Controller, Player Pawn, Game State, Player State, etc. will be active; see Secondary Worlds for more details.

SwitchWorld.png
SwitchWorld

While the Active World is always ticking (see UWorld::Tick() and Actor Ticking), Background Worlds can be configured as needed. You can configure if a World must tick while in background when loading it (see FMultiWorldLoadParameters::bStartWithTickEnabled) or at run-time (see UMultiWorldStatics::SetShouldTickWhenInBackground()). For multi-player games, read the notes at Network replication.

SetShouldTickWhenInBackground.png
SetShouldTickWhenInBackground

You can retrieve the World Handle of the Active World calling UMultiWorldStatics::GetActiveWorldHandle().

GetActiveWorldHandle.png
GetActiveWorldHandle

Being notified of World Switching

You can be notified when a World Switching occurs in different ways:

Actors management

An UE4 Actor exists only in a single UWorld.

If you need to spawn an actor in the same UWorld as you're operating in (see GetThisWorldHandle), then you can continue using the standard methods available in Unreal Engine 4: the SpawnActor() method for C++, and the Spawn Actor from Class node for Blueprints.

If instead you need to spawn an actor in a UWorld other that the one you're operating in (see GetThisWorldHandle), you can call UMultiWorldStatics::SpawnActorInWorld(). It's the same as the standard UE4 SpawnActor()/Spawn Actor from Class methods but accepts a World Handle that specifies in which World to spawn the new Actor.

SpawnActorInWorld.png
SpawnActorInWorld

If you need to transfer an actor between different UWorld instances, the plugin provides the method UMultiWorldStatics::TransferActorToWorld(). While the method UMultiWorldStatics::TransferActorToWorld() provides a convenient way to transfer an actor between different UWorld instances, and its implementation is generic enough to manage most common cases, particular actor setups or advanced uses could require a different and manual procedure. In this case, the suggested approach is to serialize the actor from the source World into a temporary buffer, destroy the actor and create a new instance in the destination World (e.g. using UMultiWorldStatics::SpawnActorInWorld()), finally restoring its state from the serialized data.

TransferActorToWorld.png
TransferActorToWorld