 |
MultiWorld 1.9.1
Manage multiple isolated UWorld instances simultaneously in Unreal Engine, transferring player and actors between worlds.
|
Loading...
Searching...
No Matches
|
MultiWorld 1.9.1
Manage multiple isolated UWorld instances simultaneously in Unreal Engine, transferring player and actors between worlds.
|
The main concepts used by the plugin.
A World Handle is a transient reference to an Unreal Engine 5 UWorld object. An UWorld object, accordingly to the Unreal Engine 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 Unreal Engine to the function.
The Main World is the "standard" UWorld loaded by Unreal Engine 5. The plugin doesn't manage it in any way. An UE5 game has a single Main World instance, created and managed by UE5 itself. This UWorld supports all the features provided by Unreal Engine 5, including network replication for multiplayer games.
You can retrieve the World Handle of the Main World using the method UMultiWorldStatics::GetMainWorldHandle().
You can change the level in the Main World using the standard UE5 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.
A Secondary World is any UWorld object created/loaded by the plugin. Any standard UE5 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 Load World node (or the C++ method UMultiWorldManager::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.
MultiWorld complies to the normal behavior of the standard UE5 Gameplay Framework, including the Game Mode and Game State systems.
When a Secondary World is loaded and initialized, the same process as the standard UE5 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 the Load World Async node or the C++ method UMultiWorldManager::LoadWorldAsync().
While the nodes and methods are similar, the Async versions load the maps and assets asynchronously; while the non-Async versions are blocking calls, that do most of their job in the game thread and complete their activity before the end of the current engine frame. Check their documentation for more details.
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()).
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.
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.
You can retrieve the World Handle of the Active World calling UMultiWorldStatics::GetActiveWorldHandle().
You can be notified when a World Switching occurs in different ways:
You can use a customizable visual transition effect when switching the Active World calling the method UMultiWorldSeamTransition::StartTransition() (instead of UMultiWorldStatics::SwitchWorld()).
It renders both the source and destination worlds in parallel, using a customizable Material to mix the rendered worlds as desired. Some ready-to-use materials are already provided with the plugin (e.g. MW_ST_CrossFading_M, MW_ST_WipeLeftToRight_M, etc.), but you can create your own effects following the provided documentation.
An UE5 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 5: 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 UE5 SpawnActor()/Spawn Actor from Class methods but accepts a World Handle that specifies in which World to spawn the new Actor.
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.
1.9.5