The Public API for the Active Grid class primarily revolves around performing three task:
1) Enabling/Disabling some of the same settings found in the Active Grid inspector, such as whether the World should be updated or the Loading Blueprint used by a particular Grouping.
2) Configuring some settings (such as the Player being used) before the Active Grid has been initialized.
3) Moving the Player and changing the World the Active Grid is synced to.
Many methods from the Active Grid class, especially the enumerator based ones, begin with the word Try. This keyword indicates that the method will fail to run if the Active Grid is busy, which basically just means that another Try method is currently running.
This is because these methods completely change crucial aspects of the Active Grid and the World it is synced to, and attempting to execute more than one of them at the same time would be impossible.
In order to avoid exceptions when using these methods, you must query the IsBusy property of the Active Grid before calling them. Only when this property returns false is it safe for you to call one of them! After calling the method, IsBusy will return true until the method finishes executing.
You can enable or disable World Updates for every Grouping or a single Grouping using various methods. Enabling or disabling World Updates will register or de-register the Active Grid as a user of a Grouping's Active Cells, which will typically result in new World Cells being loaded or old World Cells being removed from the World the next time it updates itself.
If you do not care when the loading or unloading of these World Cells (and their Asset Chunks) occurs, we recommend using one of the simple TrySetIfWorldShouldBeUpdated methods. On the other hand, if you do wish to know when the World will incorporate the registration or de-registration of the Grouping(s), and subsequent loading/unloading of World Cells, you can use one of the TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate methods instead.
These are enumerator based methods that will only finish executing once the World has added or removed the Active Grid Grouping(s) Active Cells and added/removed World Cells as a result.
--Special Note--
Active Grids created at runtime via the Component Manager always start with Update World disabled. This means you must use one of the TrySetIfWorldShouldBeUpdated methods to enable world updates, otherwise the Active Grid will not have any effect on the World!
Moving the Player in a normal game is a relatively simple process. In a streaming environment, complications arise because the location where you want to move the player to needs to be pre-loaded before moving the player to it, and then once moved the old area (that is usually no longer needed) needs to be removed.
This process is made simpler using the Active Grid's TryMovePlayerToLocation method, which automatically pre-loads the area where the player is going to be moved to, performs the move, and then removes the old area.
You can even perform a movement operation in combination with syncing to a new World using the TryMovePlayerToLocationOnNewWorld method.
When you are using a very large world and the location you want to move the player to is very far from the origin, you can use the TryMovePlayerAndChangeOriginCellOfWorld to avoid floating point issues. The drawback of this method is that new location and old location may overlap briefly, which would be very noticeable to the Player. As such, this method is only recommended to be used with a loading screen or some other technique that obscures the world.
While Active Grids can only be synced to a single World at a time, you are free to change which World that is at any point. This allows you to build Worlds separately (a Jungle World, a Volcano World, etc.) and then switch between them as the player naturally moves between them (using TrySyncToNewWorldAroundPlayer), or using some sort of teleportation effect (using TryMovePlayerToLocationOnNewWorld).
You can also fully desync from a World without syncing to a new one, using the TryDesyncFromCurrentWorld method.
There are several methods that allow you to configure certain data via scripting, however they need to be called before the Component Manager has been initialized.
--PreInitialize_SetWorld--
Allows you to set the World the Active Grid starts synced to.
This World may be overridden if persistent save data is loaded for the Active Grid, since normally you would want the Active Grid to start synced to whatever World it was synced to when the persistent data was saved, however there is an option (overwriteWorldFromPersistentData) that disables this override behavior.
Normally, this method would be used only if the Active Grid and World were not persistent (since non persistent components are not saved with persistent save data).
--PreInitialize_SetPlayer--
Allows you to set the Player tracked by the Active Grid, which can either be a Transform or IPlayer instance.
The Position of the Player may be overridden if persistent save data is loaded for the Active Grid, since normally you would want the Player to start at whatever position it was at when the persistent data was saved, however there is an option (overrideIgnorePlayerPositionInPersistentData) that disables this override behavior.
When true, the value you pass in for ignorePlayerPositionInPersistentData will determine whether positional data in the persistent save data is ignored. If true, the current Position of the passed in Transform or IPlayer object is used; if false, the Position will be changed to whatever position is stored in the persistent data (if such data exist and is loaded).
Normally, this method would be used only if the Player is created at runtime (and thus cannot be set via the inspector).
--PreInitialize_SetLoadingBlueprint(ByID, ByIndex, or ByName)--
Allows you set the Loading Blueprint used by a particular Grouping using either its ID, Name, or Index in the Repository.
This Blueprint may be overridden if persistent save data is loaded for the Active Grid, since normally you would want the Active Grid to start with the Blueprint it was using when the persistent data was saved, however there is an option (overwriteLoadingBlueprintFromPersistentData) that disables this override behavior.
Normally, this method would be used only if the Blueprint cannot be determined and set in the editor/inspector. If you need to set the Blueprint for multiple Groupings, you will need to call the method multiple times.
Many of the Active Grid's methods have a return type of IEnumerator
1) Simply include yield return statements within the method's body where the returned object is either null or an instance of a YieldInstruction.
The compiler will auto generate a state machine class, which will be used to iterate the method's logic. The drawback of this technique is every time the method is called, a new instance of the auto generated class is created, resulting in garbage generation throughout the lifetime of the game.
2) Implement one of the reusable enumerator classes found within the API.
This strategy is harder to implement as you will need to implement the state machine logic yourself, as well as perform some other code related task necessary to use the reusable enumerators. It is recommended for experienced coders only!
If you elect to go with option 2, you can find detailed information on how to use the Reusable Enumerator classes in the Yield Enumerator Section within the Secondary Non Components Chapter.
For a full list of the members available for the Active Grid class, please refer to the online Public API. You can click the Open API For Section Content In Browser button at the top of this window to open it in your browser.