Using the Component Manager, you have the incredibly powerful ability to both create and destroy Worlds at runtime. This gives you flexibility to load different Assets based on player input or other factors.
Destroyed Worlds are always tracked and saved with persistent data, so that upon loading of that data the Worlds that were previously destroyed can be removed from the scene. You can also create Persistent Worlds from Prototypes, which are automatically recreated when persistent data is loaded. Both of these factors allow you to switch between using different Worlds without having to worry about saving/loading the data needed to restore their state between persistent gaming sessions.
Worlds, like Active Grids, are complex components that have complex relationships with other components and Scriptable Assets, as well as a myriad of settings. It would be incredibly difficult to establish these relationships and configure these settings at runtime. Fortunately, using Prototypes, this is not necessary.
A World Prototype is simply any World component placed on a deactivated Game Object. You can configure the World Prototype just as you would any other World, assigning Streamable Grids, Chunk Managers, Chunk Streamers, and configuring its settings as normal. You can then create Worlds at runtime using the same settings and components/Scriptable Assets assigned to the Prototype.
You can assign as many Prototypes as you wish to each Component Manager, allowing you to pick and choose which Prototypes are used to create runtime Worlds in response to any criteria you wish.
World Prototypes are identified using their ID, so all World Prototypes in a scene must have unique IDs! When a runtime persistent World exist at time of saving, this ID is saved and used to reconstruct the World when the data is loaded. As such, the ID should remain the same for the lifetime of your Application.
You can remove Prototypes at any time, however if Runtime Worlds referencing the removed Prototype exists in persistent save data, they will be ignored (and not recreated) when that data is loaded.
Persistent Worlds are Worlds that persist between gaming sessions via Persistent Save Data. The Component Manager tracks the creation of Persistent Worlds and saves information on their IDs (as well as the IDs of the Prototypes that were used to create them), so that it can recreate them whenever that data is loaded. Each Persistent World also has data specific to it that is tracked and saved, ensuring the state of that World is consistent between gaming sessions.
Non Persistent Worlds, on the other hand, are not saved between gaming sessions. Whenever these Worlds are destroyed or unloaded (as the result of a scene unload operation, for example), they are gone for good.
--Special Note--
Worlds that are added to the scene in the Editor (and not used as Prototypes) by the developer are always Persistent. So long as you do not manually destroy them, they are always present when save data is loaded and data specific to them is always tracked and saved between gaming sessions.
You can use the CreatePersistentWorld and/or CreateNonPersistentWorld to create persistent or non persistent Worlds respectively. Both methods have the same signature and work the exact same way; the only difference is the persistence of the Worlds, as described above.
Besides the ID of the prototype to use to construct the World, the arguments of the creation methods directly correspond to data that is only configurable before the World has been initialized. It's necessary to pass this data to the method because the World is automatically initialized within the method, so once the method returns the World it will be too late to configure this data.
It should be noted that these arguments are optional; if you pass in null for any of them, the data is ignored. The only reason for passing in this data is if you need to configure the World differently than the prototype it is constructed from.
Create Non Persistent World API
The created world does not automatically start with any Active Grids synced to it, which means unless the World is making use of World Regions or you are manually passing in Cells for it to load, no World Cells on the World will be automatically loaded. You will likely need to sync an Active Grid to the World using ActiveGrid.TryMovePlayerToLocationOnNewWorld or ActiveGrid.TrySyncToNewWorldAroundPlayer before seeing loaded World Cells and Asset Chunks.
--Special Note--
If you want to assign a runtime created World to a runtime created Active Grid, you must create the World first then pass it in to the Active Grid creation method via the alternateWorldToSyncTo argument.
You can use the DestroyWorld or DestroyWorldAndWaitForChunksToBeRemoved method to destroy Worlds at runtime. Both methods have the same signature and work virtually the same; the only difference is that DestroyWorldAndWaitForChunksToBeRemoved allows you to receive a call back when all of the World Cell's (and their Asset Chunks) associated with the World have been removed from the scene. This is useful if you need to tie some action to the removal of the World's Assets.
When an inspector created Persistent World is destroyed, its ID is recorded and saved with persistent data. When that data is loaded, the World is automatically destroyed. This is not necessary when destroying a runtime created Persistent World; instead, the ID of the runtime World is simply removed from the internal tracking so that it is not written to persistent save data. This both reduces the amount of data needed to be saved and frees up the ID to be re-used.
--Special Note--
If you have a save file containing data related to an Inspector Created World and you remove that World from the scene within the Unity Editor, the next time you load the save file the data pertaining to the World is simply read in and discarded. This is useful if you have an already built game that you need to make changes to, as you can do so without worrying about exceptions being thrown, even though the save file contains data that is no longer used.