ActiveGrid Class

public sealed partial class ActiveGrid : MonoBehaviour, IIdentifiable, IWorldUser

The Active Grid is the collection of cells which are currently "active" in the scene, as determined by your players position in the scene. Like the World, the Active Grid can have 1 or more Groupings, each with their own grid, which form a direct connection with the World Groupings on the World the Active Grid is synced to.

>Note, however, it is not necessary to have an equal number of Groupings on the Active Grid and World.

If the Active Grid has less groupings, then some groupings from the World will never be loaded (unless they are loaded via other Active Grids or World Regions).

If the Active Grid has more groupings, then the cells from the additional groupings will be updated but won't actually result in World Cells being loaded. It should be noted that since the Active Grid is actually made up of 1 or more grids, "Active Grids" may be a more accurate name for the class.

The behavior described above allows the Active Grid to be used with different Worlds with different numbering of Groupings. Syncing to a new World can result in some Groupings that were not being used previously to start being used, and vice versa.

Typically, active cells are passed to the World so that it can choose to load any associated World Cells, however it is possible to have active cells that are not passed to the World (by disabling Update World on the Grouping), though the use cases for that are limited.

An Active Grid should only be disabled (or the game object the component is on disabled) if it is being used as a prototype to create Active Grids at runtime. Do not disable an Active Grid with the intention of enabling/using it at a later time, as this will not work properly. Instead, you should create the Active Grid via the Component Manager's CreateNonPersistentActiveGrid method when it is needed, and destroy it via the DestroyActiveGrid or DestroyActiveGridAndWaitForCellUsersToBeRemoved methods when it is no longer needed.

Properties

Name	Type	Description
ActiveGroupings	int	Gets the number of active groupings, which is dependent upon the number of groupings on the World the Active Grid is currently synced to. If you want to know the number of groupings that are configured on the Active Grid (via the inspector), use ConfiguredGroupings property instead.
ConfiguredGroupings	int	Gets the number of groupings configured on the Active Grid via the inspector. This may be different than the number of ActiveGroupings, which is dependent upon the World the Active Grid is currently synced to.
CreatedAtRuntime	bool	Gets a value indicating whether the Active Grid was created at runtime. If false, it means the Active Grid was added in the inspector by the dev (not as a prototype).
ID	int	Gets the identification number of the Active Grid.
IsActiveGridPersistent	bool	Gets a value indicating whether the Active Grid is persistent between game sessions. Note, non prototype Active Grids added in the editor are always persistent.
IsBusy	bool	Gets a value indicating whether the Current Active Grid is busy. "Busy" simply means a multi frame action (aka, a coroutine method) is currently being executed (such as the method TryMovePlayerToLocation).
IsInitialized	bool	Gets a value indicating whether the Active Grid has been initialized. The Grid is initialized automatically by the Component Manager when it is initialized.
LoadingBlueprintRepository	LoadingBlueprintRepository	Gets the Loading Blueprint Repository assigned to this Active Grid.
Player	IPlayer	Gets the Current Player associated with the Active Grid.
PlayerMover	PlayerMover	Gets the Current Player Mover associated with the Active Grid.
PlayerReadyToBeMoved		During an Active Grid operation where the player needs to be moved and true was passed in for waitForCommandBeforeMovingPlayer, this can be used to determine whether the player is ready to be moved. This will be true if the area the player is being moved to has successfully been loaded. This is most useful when trying to sync other actions/events to the player being moved (such as a portal effect or transport sound). To use it effectively, you'd call StartCoroutine(any Active Grid Method that moves the player, such as TryMovePlayerToLocation). When you are ready for the player to be moved, you query this property to make sure the area to move the player to has been loaded. Once this returns true, you play your effect/sound and call the same Active Grid's InitiatePendingMove method at the appropriate time during that effect/sound. The player will be moved either in the same frame or a couple of frames after, depending on whether a Player Mover component is linked to the Active Grid. In the case of the latter, the player should not notice the delay.
WorldSyncedTo	World	Gets the Current World the Active Grid is synced to.

Methods

AllowGridToRecenterWorldWhenSynced()

public void AllowGridToRecenterWorldWhenSynced()

Allows the grid to recenter the World it is synced to by triggering an Origin Cell changes in the World.

This only has an effect when the grid is synced to a World with 'Allow Active Grid Re-Centering' enabled.

AreActiveGridMovedEventsEnabledForGrouping(int)

public bool AreActiveGridMovedEventsEnabledForGrouping(int groupingIndex)

Queries whether a particular World Grouping will fire events whenever the active grid on that grouping moves.

Parameters

Name	Type	Description
groupingIndex	int	The grouping to query.

Returns

bool
True if events are enabled, false otherwise.

ArePlayerCellChangeEventsEnabledForGrouping(int)

public bool ArePlayerCellChangeEventsEnabledForGrouping(int groupingIndex)

Queries whether a particular World Grouping will fire events whenever the cell the player is in changes on that grouping.

Parameters

Name	Type	Description
groupingIndex	int	The grouping to query.

Returns

bool
True if events are enabled, false otherwise.

GetDistanceFromInnerAreaOfGrid(Cell, [int])

public int GetDistanceFromInnerAreaOfGrid(Cell cellOnEndlessGrid, int groupingIndex = 1)

Gets the distance that a cell is from the inner area of the active World Grouping specified (if no grouping is specified, uses Grouping 1).

You can use this info for a variety of purposes, for instance you could modify loaded terrains to use a lower resolution at runtime if they are farther from the grids center (although it would be better to use a loading blueprint that makes use of LODs for this purpose).

Parameters

Name	Type	Description
cellOnEndlessGrid	Cell	The cell whose distance from the inner area you want. It should be one based and a cell on your Worlds Endless Grid.
groupingIndex	int	The index of the World Grouping whose inner area you want to check the input cells distance against (optional).

Returns

int
0 will be returned if the cell is part of the inner area, otherwise the distance is based on a ring design, i.e., if the cell is in the first "ring" around the inner area, the distance will be 1, second ring distance = 2, and so on.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the method is called before the Active Grid has been initialized.

GetDistanceFromInnerAreaOfGrid(WorldCell)

public int GetDistanceFromInnerAreaOfGrid(WorldCell worldCell)

Gets the distance that a World Cell is from the inner area of the active grid associated with the same grouping as the World Cell. This effectively tells you what ring the cell is in when using an outer ring grid or how far the cell is from cell the player is standing on when using a sectioned grid.

You can use this info for a variety of purposes, for instance you could modify loaded terrains to use a lower resolution at runtime if they are farther from the grids center.

Parameters

Name	Type	Description
worldCell	WorldCell	The World Cell whose distance from center you want.

Returns

int
0 will be returned if the cell is part of the inner grid, 1 if the cell is in the first ring around the inner grid, and so on.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the method is called before the Active Grid has been initialized.

GetLoadingBlueprintOfGrouping(int)

public LoadingBlueprint GetLoadingBlueprintOfGrouping(int groupingIndex)

Gets the Loading Blueprint associated with a specific World Grouping.

Parameters

Name	Type	Description
groupingIndex	int	The World Grouping whose Loading Blueprint you are trying to get.

Returns

LoadingBlueprint
The loading blueprint associated with the World Grouping.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the method is called before the Active Grid has been initialized.

GetRegisteredActiveCells(int, ICollection<LODCell>, bool)

public void GetRegisteredActiveCells(int groupingIndex, ICollection<LODCell> cells, bool clearCollectionIfNotEmpty)

Fills the input cells collection with all currently registered active LOD Cells associated with the input World Grouping. These are the Cells the Grouping has registered itself as a user of with the World.

Parameters

Name	Type	Description
groupingIndex	int	The index of the World Grouping whose active cells you want to get.
cells	ICollection<LODCell>	A container for storing the currently active cells. The container can be a lists, hashset, or any other collection that implements ICollection<LODCell>
clearCollectionIfNotEmpty	bool	Whether the cells collection should be cleared if it is not already empty, before adding the active cells.

HasCellsRegistered(int)

public bool HasCellsRegistered(int groupingIndex)

Gets a value indicating whether Active Grid Grouping specified is currently registered as a user of a set of Cells. In most cases, so long as IsUpdatingWorld returns true, this should also return true, however there are situations where temporarily the Grouping may not be registered as a user of any Cells, even though IsUpdatingWorld returns true.

To be registered as a user of a set of Cells simply means that the Grouping has notified the World that those Cells are in use. This may or may not result in equivalent World Cells being loaded, depending on if there are other users of the same Cells but of a higher quality LOD.

To be honest, it's not clear how this information might be useful to you, but it's there if you need it.

Parameters

Name	Type	Description
groupingIndex	int	The index of the World Grouping you are inquiring about. The World Grouping corresponds to a World Grouping on the World this Active Grid is synced to.

Returns

bool
True if the cell users are loaded for the World Grouping specified, false otherwise.

InitiatePendingMove()

public void InitiatePendingMove()

Tells a pending move operation that it is okay to proceed. This is used in conjunction with passing in true for the waitForCommandBeforeMovingPlayer parameter of the TryMovePlayerToLocation and TryMovePlayerToLocationOnNewWorld methods.

This allows you to gain greater control over when the move operation is executed, which is useful in many situations, such as situations where you need to perform some logic before the player can be moved successfully.

In order to use this strategy correctly, you should query the PlayerReadyToBeMoved property and wait for it to return true. Once it returns true, indicating that the player is ready to be moved, you should perform whatever logic you need to in order to ensure the player move operation is successful. Once that logic is performed, call this method and the Active Grid will then care out the actual move operation, using the PlayerMover (if assigned), or directly setting the IPlayer.Position property (if no PlayerMover is assigned).

IsAutoTrackingEnabled(int)

public bool IsAutoTrackingEnabled(int groupingIndex)

Gets a value indicating whether the Player's position is being automatically tracked in order to update the grid of Cells used by the specified grouping on this Active Grid. With Auto Tracking disabled, the Cells for the grouping will be set based on the initial position of the player, but will never be updated afterwards. Therefore, it is rare that you would want to disable Auto Tracking!

Note that in order for actual World Cell's and Asset Chunks to be loaded, 'Update World' must also be enabled for the grouping specified.

Parameters

Name	Type	Description
groupingIndex	int	The index of the World Grouping you are inquiring about. The World Grouping corresponds to a World Grouping on the Streamable Grid this Active Grid is synced to.

Returns

bool
True if auto tracking is enabled, false otherwise.

IsUpdatingWorld(int)

public bool IsUpdatingWorld(int groupingIndex)

Gets a value indicating whether the World the Active Grid is sycned to will be updated based on the current grid of Cells on the grouping specified. In order for the World to load World Cells, which in turn loads Asset Chunks, updating must be enabled. Therefore, this method is mostly useful if you are not seeing Asset Chunks loaded in your scene and you're not sure why. This value may be false (and thus no Asset Chunks loaded on this grouping of the World) if you have created the Active Grid at runtime and not called one of the TrySetIfWorldShouldBeUpdated methods, or if you have called one of the TrySetIfWorldShouldBeUpdated methods and passed in false.

Parameters

Name	Type	Description
groupingIndex	int	The index of the World Grouping you are inquiring about. The World Grouping corresponds to a World Grouping on the World this Active Grid is synced to.

Returns

bool
True if the World is being updated about the active grid cells for the layer, false otherwise.

PreInitialize_SetLoadingBlueprintByID(int, int, bool)

public void PreInitialize_SetLoadingBlueprintByID(int groupingIndex, int loadingBlueprintID, bool overwriteLoadingBlueprintFromPersistentData)

Changes the Loading Blueprint used by Active World Grouping indicated, allowing for the initial blueprint to be different than what it normally is. This method is recommended over the other PreInitialize_SetLoadingBlueprint... methods as the ID is more consistent (names can be changed and the Blueprint Index may change as a result of Blueprints being removed, but the ID will remain the same forever unlesss the Blueprint itself is removed).

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location.

This must be called before the Active Grid has been initialized.

Parameters

Name	Type	Description
groupingIndex	int	The index of the active World Grouping to change.
loadingBlueprintID	int	The ID of the Loading Blueprint. This can be seen in the Loading Blueprint Repository Inspector, in the parentheses after the Blueprint Type.
overwriteLoadingBlueprintFromPersistentData	bool	Should the new loading blueprint you indicated overwrite the loading blueprint found in persistent data for this Active World Grouping (if any exist)?

Exceptions

Type	Condition
InitializedSAMObjectException	Thrown when this method is called after the Active has been initialized.
InvalidOperationException	Thrown if the ID does not correspond to a valid blueprint in the repository.

PreInitialize_SetLoadingBlueprintByIndex(int, int, bool)

public void PreInitialize_SetLoadingBlueprintByIndex(int groupingIndex, int loadingBlueprintIndex, bool overwriteLoadingBlueprintFromPersistentData)

Changes the Loading Blueprint used by Active World Grouping indicated, allowing for the initial blueprint to be different than what it normally is.

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location.

This must be called before the Active Grid has been initialized.

Parameters

Name	Type	Description
groupingIndex	int	The index of the active World Grouping to change.
loadingBlueprintIndex	int	The index of the new loading blueprint to use. You can find this index by looking at the inspector of the Loading Blueprint Repository connected to this Active Grid (the only you assigned in this Active Grid's inspector). The index is found to the left of each loading blueprint name.
overwriteLoadingBlueprintFromPersistentData	bool	Should the new loading blueprint you indicated overwrite the loading blueprint found in persistent data for this Active World Grouping (if any exist)?

Exceptions

Type	Condition
InitializedSAMObjectException	Thrown when this method is called after the Active has been initialized.
IndexOutOfRangeException	Thrown if the index is not valid (less than 1 or greater than the number of blueprints in the respository)
NullReferenceException	Thrown if the index points to a null blueprint, which should never happen. If it does, please contact me!!

PreInitialize_SetLoadingBlueprintByName(int, string, bool)

public void PreInitialize_SetLoadingBlueprintByName(int groupingIndex, string loadingBlueprintName, bool overwriteLoadingBlueprintFromPersistentData)

Changes the Loading Blueprint used by the Active World Grouping indicated, allowing for the initial blueprint to be different than what it normally is.

The main use of this will be to implement custom loading rather than making use of the automatic IPersistentDataController class, if you need to save different data in different places (on the server, on a file on the users system, etc.). Note, if all your data is stored in the same place, you are better off using a custom class that derives from IPersistentDataController, and then set it up to save data to that location.

This must be called before the Active Grid has been initialized.

Parameters

Name	Type	Description
groupingIndex	int	The index of the active World Grouping to change.
loadingBlueprintName	string	The name of the new loading blueprint to use. This must match one of the Loading Blueprints in the Loading Blueprint Repository connected to this Active Grid via the Active Grid's inspector.
overwriteLoadingBlueprintFromPersistentData	bool	Should the new loading blueprint you indicated overwrite the loading blueprint found in persistent data for this Active World Grouping (if any exist)?

Exceptions

Type	Condition
InitializedSAMObjectException	Thrown when this method is called after the Active Grid has been initialized.
InvalidNameException	Thrown if the name does not correspond to a valid loading blueprint on the repository.

PreInitialize_SetPlayer(Transform, PlayerMover, bool, [bool])

public void PreInitialize_SetPlayer(Transform newPlayer, PlayerMover newPlayerMover, bool overrideIgnorePlayerPositionInPersistentData, bool ignorePlayerPositionInPersistentData = false)

Parameters

Name	Type	Description
newPlayer	Transform	The player transform to set.
newPlayerMover	PlayerMover	The player mover object associated with the player. This is only used with origin resetting to avoid physics issues when moving the player, therefore it can be left null if no special handling needs to take place when modifying the player position. Note that even if you have a Player Mover assigned via the Active Grid inspector, it will be overriden with this value, even if the value is null.
overrideIgnorePlayerPositionInPersistentData	bool	By default, the Player's position (which is always saved with SAM save data when the Player is linked to a persistent Active Grid) is loaded in with SAM's save data and used to position the Player. The Active Grid has an option that you can set in its Inspector called "Ignore Player Position In Persistent Data" which counters this behaviour, in situations where it would be problematic to let SAM set the Player Position. If you want to override this Inspector value, you can pass in true for this option, and then provide a new value for ignorePlayerPositionInPersistentData. Keep in mind that this new value will only be used for the current session. It is not saved with SAM's persistent save data. This should not be problematic as you will need to set the player manually using this method for each new gaming session, so you can override it each time you do so.
ignorePlayerPositionInPersistentData	bool	If overrideIgnorePlayerPositionInPersistentData is true, this value is used to determine whether the Player's positional data stored in SAM's persistent save data will be ignored. The value you set is used only for this session, so for each new session where you call this method, you should pass in the same value. See the info for overrideIgnorePlayerPositionInPersistentData for more information.

Exceptions

Type	Condition
InitializedSAMObjectException	Thrown when this method is called after the Active has been initialized.
InvalidOperationException	Thrown when null is passed in for newPlayer.

PreInitialize_SetPlayer(IPlayer, PlayerMover, bool, [bool])

public void PreInitialize_SetPlayer(IPlayer newPlayer, PlayerMover newPlayerMover, bool overrideIgnorePlayerPositionInPersistentData, bool ignorePlayerPositionInPersistentData = false)

Sets the player that the Active Grid will track in order to perform shifts (both normal shifts and origin resetting). You must call this method before the Active Grid is initialized. While the Player's positional data will be saved with SAM's save data (so long as this Active Grid is persistent), the actualy Player object will not, as there is no way to save the reference. As such, you need to call this method each session.

With this method, you can pass in a class deriving from CustomPlayer, or any other class that implements the IPlayer interface. These types can be used in systems where the Player is not associated with the traditional Transform component. These types of players are especially useful when you want to use doubles to track player position data.

Parameters

Name	Type	Description
newPlayer	IPlayer	The player to set.
newPlayerMover	PlayerMover	The player mover object associated with the player. This is only used with origin resetting to avoid physics issues when moving the player, therefore it can be left null if no special handling needs to take place when modifying the player position. Note that even if you have a Player Mover assigned via the Active Grid inspector, it will be overriden with this value, even if the value is null.
overrideIgnorePlayerPositionInPersistentData	bool	By default, the Player's position (which is always saved with SAM save data when the Player is linked to a persistent Active Grid) is loaded in with SAM's save data and used to position the Player. The Active Grid has an option that you can set in its Inspector called "Ignore Player Position In Persistent Data" which counters this behaviour, in situations where it would be problematic to let SAM set the Player Position. If you want to override this Inspector value, you can pass in true for this option, and then provide a new value for ignorePlayerPositionInPersistentData. Keep in mind that this new value will only be used for the current session. It is not saved with SAM's persistent save data. This should not be problematic as you will need to set the player manually using this method for each new gaming session, so you can override it each time you do so.
ignorePlayerPositionInPersistentData	bool	If overrideIgnorePlayerPositionInPersistentData is true, this value is used to determine whether the Player's positional data stored in SAM's persistent save data will be ignored. The value you set is used only for this session, so for each new session where you call this method, you should pass in the same value. See the info for overrideIgnorePlayerPositionInPersistentData for more information.

Exceptions

Type	Condition
InitializedSAMObjectException	Thrown when this method is called after the Active has been initialized.
InvalidOperationException	Thrown when null is passed in for newPlayer.

PreInitialize_SetWorld(World, bool)

public void PreInitialize_SetWorld(World world, bool overwriteWorldFromPersistentData)

Sets the initial World for the Active Grid to use. This must be called before the Active Grid has been initialized, and if the Active Grid is persistent, the world must also be persistent.

Note, this will not fire the ActiveGridSyncedToNewWorld event.

Parameters

Name	Type	Description
world	World	The world for the Active Grid to use.
overwriteWorldFromPersistentData	bool	If true, the passed in World will be used regardless of whether persistent data exist for the Active Grid. If false, the passed in world will be used if a) no persistent data exist for the Active Grid, or b) persistent data exist, but no world was found in the data (happens when active grid was synced to a non persistent world when data was saved).

Exceptions

Type	Condition
InitializedSAMObjectException	Thrown when this method is called after the Active has been initialized.
InvalidOperationException	Thrown when the Active Grid has already been initialized.

ProhibitGridFromFromRecenteringWorldWhenSynced()

public void ProhibitGridFromFromRecenteringWorldWhenSynced()

Stops this Active Grid from being able to trigger World Re-Centering in any Worlds it is synced to.

SetAutoTracking(bool)

public void SetAutoTracking(bool autoTracking)

Sets Auto Tracking (true means enabled, false means disabled) for all Groupings on the Active Grid (note, tracking only takes place when the grid is synced to a World). Auto Tracking enables the tracking of the player to determine if they cross the inner area boundary of one or more Groupings on the Active Grid.

When the player crosses the boundary for a Grouping the cells of the Active Grid on that Grouping are dynamically updated based on the position of the player. In addition, when 'Update World' is enabled on a Grouping, the Active Grid updates the same Grouping on the World it is synced to so that it can update its World Cells appropriately, which effectively enables dynamic loading and world updates.

Parameters

Name	Type	Description
autoTracking	bool	Pass in true to enable auto tracking, or false to disable it.

SetAutoTracking(bool, int)

public void SetAutoTracking(bool autoTracking, int groupingIndex)

Sets Auto Tracking (true means enabled, false means disabled) for a single Groupings on the Active Grid (note, tracking only takes place when the grid is synced to a World). Auto Tracking enables the tracking of the player to determine if they cross the inner area boundary of the Groupings on the Active Grid.

When the player crosses the boundary for the Grouping, the cells of the Active Grid on that Grouping are dynamically updated based on the position of the player. In addition, when 'Update World' is enabled on the Grouping, the Active Grid updates the same Grouping on the World it is synced to so that it can update its World Cells appropriately, which effectively enables dynamic loading and world updates.

Parameters

Name	Type	Description
autoTracking	bool	Pass in true to enable auto tracking, or false to disable it.
groupingIndex	int	The index of the grouping whose auto tracking should be enabled or disabled.

TryChangeLoadingBlueprintByID(int, int, bool)

public IEnumerator<YieldInstruction> TryChangeLoadingBlueprintByID(int loadingBlueprintID, int groupingIndex, bool refreshWorld)

Tries to change the Loading Blueprint of the indicated active World Grouping (change persist between sessions if the Active Grid is persistent) and optionally refreshes the World the Active Grid is synced to so it will be made up entirely of the Asset Chunks associated with the new loading blueprint (if there is overlap between the blueprints, some chunks may remain after the refresh).

This method will throw an exception if the Active Grid is already busy, so you should query the IsBusy property to make sure it is not before calling this method.

Parameters

Name	Type	Description
loadingBlueprintID	int	The ID of the Loading Blueprint. This can be seen in the Loading Blueprint Repository Inspector, in the parentheses after the Blueprint Type.
groupingIndex	int	The grouping whose loading blueprint will be changed.
refreshWorld	bool	If true, the objects associated with the previous blueprint are completely unloaded, and the objects related to the new blueprint are loaded. If false, the objects will be refreshed the next time the player crosses a loading boundary or during a world origin reset. If no world is synced to the Active Grid, this option will do nothing. When true, this method will finish executing only after the world has been updated to reflect the new blueprint, so it's useful to make use of this when you want to display a loading screen or otherwise pause the game to wait for the world to update.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
UninitializedSAMObjectException	Thrown when the method is called before the Active Grid has been initialized.
InvalidOperationException	Thrown when the method is called when IsBusy is already true or if the ID does not correspond to a valid Blueprint in the Repository.
NullReferenceException	Thrown if the index points to a null blueprint, which should never happen. If it does, please contact me!!

TryChangeLoadingBlueprintByIndex(int, int, bool)

public IEnumerator<YieldInstruction> TryChangeLoadingBlueprintByIndex(int loadingBlueprintIndex, int groupingIndex, bool refreshWorld)

Tries to change the Loading Blueprint of the indicated active World Grouping (change persist between sessions if the Active Grid is persistent) and optionally refreshes the World the Active Grid is synced to so it will be made up entirely of the objects associated with the new loading blueprint (if there is overlap between the blueprints, some objects may remain after the refresh).

This method will throw an exception if the Active Grid is already busy, so you should query the IsBusy property to make sure it is not before calling this method.

Parameters

Name	Type	Description
loadingBlueprintIndex	int	The index of the new loading blueprint. This index must correspond to a valid blueprint on the Loading Blueprint Repository connected to this Active Grid.
groupingIndex	int	The grouping whose loading blueprint will be changed.
refreshWorld	bool	If true, the objects associated with the previous blueprint are completely unloaded, and the objects related to the new blueprint are loaded. If false, the objects will be refreshed the next time the player crosses a loading boundary or during a world origin reset. If no world is synced to the Active Grid, this option will do nothing. When true, this method will finish executing only after the world has been updated to reflect the new blueprint, so it's useful to make use of this when you want to display a loading screen or otherwise pause the game to wait for the world to update.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
UninitializedSAMObjectException	Thrown when the method is called before the Active Grid has been initialized.
InvalidOperationException	Thrown when the method is called when IsBusy is already true.
IndexOutOfRangeException	Thrown if the index is not valid (less than 1 or greater than the number of blueprints in the respository)
NullReferenceException	Thrown if the index points to a null blueprint, which should never happen. If it does, please contact me!!

TryChangeLoadingBlueprintByName(string, int, bool)

public IEnumerator<YieldInstruction> TryChangeLoadingBlueprintByName(string loadingBlueprintName, int groupingIndex, bool refreshWorld)

Tries to change the Loading Blueprint of the indicated active World Grouping (change persist between sessions if the Active Grid is persistent) and optionally refreshes the World so it will be made up entirely of the objects associated with the new loading blueprint (if there is overlap between the blueprints, some objects may remain after the refresh).

This method will throw an exception if the Active Grid is already busy, so you should query the IsBusy property to make sure it is not before calling this method.

Parameters

Name	Type	Description
loadingBlueprintName	string	The name of the new loading blueprint. This name must correspond to a valid blueprint on the Loading Blueprint Repository connected to this Active Grid.
groupingIndex	int	The grouping whose loading blueprint will be changed.
refreshWorld	bool	If true, the objects associated with the previous blueprint are completely unloaded, and the objects related to the new blueprint are loaded. If false, the objects will be refreshed the next time the player crosses a loading boundary or during a world origin reset. When true, this method will finish executing only after the world has been updated with the new blueprint, so it's useful to make use of this when you want to display a loading screen or otherwise pause the game to wait for the world to update.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
UninitializedSAMObjectException	Thrown when the method is called before the Active Grid has been initialized.
InvalidOperationException	Thrown when the method is called when IsBusy is already true.
InvalidNameException	Thrown if the name does not correspond to a valid loading blueprint on the repository.

TryChangeLoadingBlueprintsByID(int[], int[], bool)

public IEnumerator<YieldInstruction> TryChangeLoadingBlueprintsByID(int[] loadingBlueprintIDs, int[] groupingIndexes, bool refreshWorld)

Tries to change the Loading Blueprint of the active World Groupings identified in the groupingIndexes array. This method is effectively the same as TryChangeLoadingBlueprintByID, except it allows you to change the loading blueprint of multiple World Groupings at once.

It is recommended to use this method over the other TryChangeLoadingBlueprints methods, because the ID is more consistent than the Blueprint Names or Indexes (names can be modified and Indexes decremented when other Blueprints are removed). The ID will remain the same forever unless the Blueprint is removed from the Repository.

This method will throw an exception if the Active Grid is already busy, so you should query the IsBusy property to make sure it is not before calling this method.

Parameters

Name	Type	Description
loadingBlueprintIDs	int[]	The IDs of the Loading Blueprints. These can be seen in the Loading Blueprint Repository Inspector, in the parentheses after the Blueprint Type.
groupingIndexes	int[]	An array of grouping indexes whose loading blueprints will be changed.
refreshWorld	bool	If true, the objects associated with the previous blueprints are completely unloaded, and the objects related to the new blueprints are loaded. If false, the objects will be refreshed the next time the player crosses a loading boundary or during a world origin reset. If no world is synced to the Active Grid, this option will do nothing. When true, this method will finish executing only after the world has been updated with the new blueprint, so it's useful to make use of this when you want to display a loading screen or otherwise pause the game to wait for the world to update.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
UninitializedSAMObjectException	Thrown when the method is called before the Active Grid has been initialized.
InvalidOperationException	Thrown when the method is called when IsBusy is already true or if one of the ID's do not correspond to a valid Blueprint.
NullReferenceException	Thrown if the index points to a null blueprint, which should never happen. If it does, please contact me!!

TryChangeLoadingBlueprintsByIndex(int[], int[], bool)

public IEnumerator<YieldInstruction> TryChangeLoadingBlueprintsByIndex(int[] loadingBlueprintIndexes, int[] groupingIndexes, bool refreshWorld)

Parameters

Name	Type	Description
loadingBlueprintIndexes	int[]	The indexes of the new loading blueprints. These indexes must correspond to a valid blueprint on the Loading Blueprint Repository connected to this Active Grid, and the length of the array must be the same as the groupingIndexes array (The loading blueprint index at array index 0 of loadingBlueprintIndexes is used for the World Grouping identified by array index 0 of groupingIndexes).
groupingIndexes	int[]	An array of grouping indexes whose loading blueprints will be changed.
refreshWorld	bool	If true, the objects associated with the previous blueprints are completely unloaded, and the objects related to the new blueprints are loaded. If false, the objects will be refreshed the next time the player crosses a loading boundary or during a world origin reset. If no world is synced to the Active Grid, this option will do nothing. When true, this method will finish executing only after the world has been updated with the new blueprint, so it's useful to make use of this when you want to display a loading screen or otherwise pause the game to wait for the world to update.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
UninitializedSAMObjectException	Thrown when the method is called before the Active Grid has been initialized.
InvalidOperationException	Thrown when the method is called when IsBusy is already true.
IndexOutOfRangeException	Thrown if the index is not valid (less than 1 or greater than the number of blueprints in the respository)
NullReferenceException	Thrown if the index points to a null blueprint, which should never happen. If it does, please contact me!!

TryChangeLoadingBlueprintsByName(string[], int[], bool)

public IEnumerator<YieldInstruction> TryChangeLoadingBlueprintsByName(string[] loadingBlueprintNames, int[] groupingIndexes, bool refreshWorld)

Parameters

Name	Type	Description
loadingBlueprintNames	string[]	The names of the new loading blueprints. These names must correspond to a valid blueprint on the Loading Blueprint Repository connected to this Active Grid, and the length of the array must be the same as the groupingIndexes array (The loading blueprint name at array index 0 of loadingBlueprintIndexes is used for the World Grouping identified by array index 0 of groupingIndexes).
groupingIndexes	int[]	An array of grouping indexes whose loading blueprints will be changed.
refreshWorld	bool	If true, the objects associated with the previous blueprints are completely unloaded, and the objects related to the new blueprints are loaded. If false, the objects will be refreshed the next time the player crosses a loading boundary or during a world origin reset. If no world is synced to the Active Grid, this option will do nothing. When true, this method will finish executing only after the world has been updated with the new blueprint, so it's useful to make use of this when you want to display a loading screen or otherwise pause the game to wait for the world to update.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
UninitializedSAMObjectException	Thrown when the method is called before the Active Grid has been initialized.
InvalidOperationException	Thrown when the method is called when IsBusy is already true.
InvalidNameException	Thrown if ones of the names does not correspond to a valid Blueprint.
NullReferenceException	Thrown if the index points to a null blueprint, which should never happen. If it does, please contact me!!

TryChangeOriginCellOfWorld(Cell, Vector3Double, [bool], [double], [bool])

public IEnumerator<YieldInstruction> TryChangeOriginCellOfWorld(Cell newOriginCell, Vector3Double playerPositionAfterChange, bool setPlayerYPositionBasedOnTerrain = false, double playerYOffset = 1f, bool positionRelativeToOriginCell = false)

Tries to change the Origin Cell of the synced to World to the passed in newOriginCell while moving the player to a new location in the World. Unlike the World's ChangeOriginCell method, this method offers more options for how the Player will be moved, allowing you to position the player exactly as you want once the Origin Cell change is complete.

However, the process of doing this is not as seamless as the normal Origin Cell change process, as the current cells associated with the player's current position are removed at the same time as new cells at the new position are added; as such, it's very likely the player will notice what's going on. As such, this method should only be used with some kind of obfuscation technique to hide what's happening in the game world from the player. At the very least, you should usually disable the player's movement while the method is executing (to keep them from falling through the world when the old cells are removed), however this is up to you.

It should be noted that when the World's Origin Change Strategy is set to Duplicate World, the method will only complete execution after the old World Cells (and Asset Chunks) that used the previous Origin Cell are removed. This is necessary to ensure the player is not re-activated while lingering Assets are left in the scene, however it may throw off the timing of the Player being moved. If this is a concern for you, you should switch to using a World Shifter to perform the Origin Cell change.

The main purpose of this method is to allow you to change the player's position within the game world while simultaneously updating the Origin Cell of the world, in a manner that avoids asset chunks being moved outside of the valid floating point range, which may cause issues for your game. It's useful in situations where you can obfuscate the game world, for instance imagine a Skyrim like fast travel system where a loading screen is displayed when fast travel is used. If you need a method that doesnt invovle obfuscating the game world, you will need to use a combination of a manual World Cell Origin change via the World's ChangeOriginCell method, followed by a call to this Active Grid's TryMovePlayerToLocation. This technique will take longer and the player and game world may temporarily travel outside the valid floating point range, but unfortunately it is the only way to execute an Origin Cell change and player movement in game, without obfuscating the game world. Do note, if using the Duplicate World origin change strategy, you will need to make sure to choose a new Origin Cell that doesn't result in overlap between the new world cells (using the new Origin Cell) and the old world cells (which are only removed after the new world is constructed).

Do note that this method will trigger a normal Origin Cell Change on the World, which has the following consequences:

1) If a World Shifter is being used by the World and it is set to shift the Player's position, it will do so as normal. Any movement performed by this method will take place after, so the final position of the player will be correctly set to whatever you set here (assuming overridePostChangePlayerPosition is true).

2) Any IWorldUsers registered with the World will be notified of the Origin Cell Change, and their appropriate callback methods will be invoked as a result. This includes any Active Grids registered with the World, including the one you call the TryChangeOriginCellOfWorld method with. When overridePostChangePlayerPosition is true, however, the Active Grid will not move the player within its Origin Cell Changed callback methods, even when Move Player After Origin Cell Change is enabled, as doing so would be redundant.

With that said, it is very likely to be impossible to keep the player from noticeing the processing of the Origin Cell change, and as such it usually is a good idea to obscure the world in some way while the origin update is in progress, with a loading screen or some kind of visual effect. There are also options to manually move the player with this method, however this move will be carried out through a simple IPlayer.Position set operation rather than using the Player Mover (if attached), and will be performed after the player position is shifted during the Origin Cell Change operation.

In situations where you are not using a loading screen, it may make more sense to utilize the TryMovePlayerToLocation method instead, as there is less disruption to the currently loaded World Cells, and so the player should not notice the world being updated during the move process. Note, however, if you are using an exceptionally large world, moving the player to a location very far from the origin may not be possible due to floating point issues, in which case this Origin Cell change method will need to be used instead.

Parameters

Name	Type	Description
newOriginCell	Cell	The Endless Grid Cell which will become the Origin Cell of the World the Active Grid is currently synced to. Note, this can be a cell with indexes outside the range of the Streamable Grid this Active Grid is synced to if using an endless world.
playerPositionAfterChange	Vector3Double	If movePlayerAfterChange is true, the player will be moved to this location. The location can either be an absolute position in the scene, or a position relative to the new Origin Cell. You can control which behaviour is used using the positionRelativeToOriginCell argument.
setPlayerYPositionBasedOnTerrain	bool	If movePlayerAfterChange and setPlayerYPositionBasedOnTerrain are true, the player's y location will be set based on the terrain whose bounds the player is within (i.e, the y location in playerPositionAfterChange will be ignored). Note that this value will apply to any future automatic movements of the player by the Active Grid, such as when a world shift occurs.
playerYOffset	double	If movePlayerAfterChange and setPlayerYPositionBasedOnTerrain are true, you can pass in an offset value which will be added to the player's calculated position (based on the terrain). This is necessary since setting the player's y position to the calculated position would likely cause the player to overlap the terrain, which is not ideal. Note that this value applies to any future automatic movement of the player by the Active Grid, such as when a world shift occurs.
positionRelativeToOriginCell	bool	Is the playerPositionAfterChange relative to scene space (false) or the new Origin Cell (true). If setPlayerYPositionBasedOnTerrain is false, this also dictates whether the y value of playerPositionAfterChange is relative to the WorldSyncedTo or Origin Cell. If the position is relative to the Origin Cell, then the final position the player will be moved to is playerPositionAfterChange + OriginCell.position. If the position is relative to scene space, then playerPositionAfterChange is the position the player will be moved to. Note, if the Origin Cell's position is x = 0, y = 0, and z = 0, then the player's position after the change will be the same regardless of this value.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
InvalidOperationException	Thrown when a WorldSyncedTo is not associated with the grid, when the Active Grid has not been initialized yet, when this method is called while the Active Grid is busy executing a multi frame action (check IsBusy before calling ActiveGrid methods that begin with "Try"), when setPlayerYPositionBasedOnTerrain is true but the Current WorldSyncedTo does not use Unity Terrain or chunks are not enabled on the Active Grid, or when a player is not associated with the grid but movePlayerAfterChange is true.

InvalidOperationException

Thrown when a WorldSyncedTo is not associated with the grid, when the Active Grid has not been initialized yet, when this method is called while the Active Grid is busy executing a multi frame action (check IsBusy before calling ActiveGrid methods that begin with "Try"), when setPlayerYPositionBasedOnTerrain is true but the Current WorldSyncedTo does not use Unity Terrain or chunks are not enabled on the Active Grid, or when a player is not associated with the grid but movePlayerAfterChange is true.

TryDesyncFromCurrentWorld()

public IEnumerator<YieldInstruction> TryDesyncFromCurrentWorld()

Tries to de-sync the Active Grid from the World it is Currently synced to.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
InvalidOperationException	Thrown when this method is called before the grid has been initialized or while the Active Grid is busy executing a multi frame action. Check IsBusy before calling ActiveGrid methods that begin with "Try".

TryMovePlayerToLocation(Vector3Double, bool, bool, [bool], [double])

public IEnumerator<YieldInstruction> TryMovePlayerToLocation(Vector3Double location, bool waitForCommandBeforeMovingPlayer, bool waitForOldObjectsToBeRemoved, bool setPlayerYPositionBasedOnTerrain = false, double playerYOffset = 1f)

Tries to move the player associated with this Active Grid to the location specified.

This method fully loads the cells (and objects if necessary) around the target location before moving the player (this occurs over several frames).

Once loaded, if waitForCommandBeforeMovingPlayer is true, this method will yield until InitiatePendingMove is called. If false, this method will move the player immediately after the objects at the new location are loaded.

If waitForCommandBeforeMovingPlayer is true, you can query the PlayerReadyToBeMoved property to make sure the Active Grid has loaded the new area before calling InitiatePendingMove (otherwise, there is no guarantee the player will be moved immediately after calling InitiatePendingMove).

Depending on the PlayerMover used by this Active Grid, the actual move operation may also take several frames.

This method, like all Try methods in this API, will throw an exception when a coroutine operation is Currently being executed by this Active Grid. The best way to account for this possibility is to simply check to make sure the Active Grid is not busy before calling this move method, which you can do by checking the Active Grid's IsBusy property.

Parameters

Name	Type	Description
location	Vector3Double	The location to move the player to.
waitForCommandBeforeMovingPlayer	bool	If true, the new area that the player will be moved to will be loaded, but the actual move operation will be delayed until the InitiatePendingMove method is called. If false, the move will be performed immediately after the new area is loaded.
waitForOldObjectsToBeRemoved	bool	If true, the coroutine will not exit/yield break until the pre move objects that are no longer needed are removed. This is mostly useful if displaying a loading screen and you only want to remove the loading screen when the WorldSyncedTo is completely up to date, or if you think the old objects might intersect with the new ones, which would look quite bad to the player if seen.
setPlayerYPositionBasedOnTerrain	bool	If true, the y value in location will be ignored and the y position to move the player to will be calculated based on the height of the terrain at the location to move the player to. Only set this to true if you know the Active Grid is synced to a WorldSyncedTo that is using Terrains. If there is no terrain at the location, the location's y value will be used. Note that this value applies to any future automatic movement of the player by the Active Grid, such as when a world shift occurs.
playerYOffset	double	When setPlayerYPositionBasedOnTerrain is true, this value can be used to ensure the player does not overlap the terrain. A value of 1, for instance, will place the player 1 unit above the terrain's height. You will need to experiment to find the best value, as it will depend largely upon the shape and height of your player's collider. Note that this value applies to any future automatic movement of the player by the Active Grid, such as when a world shift occurs.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
InvalidOperationException	Thrown when no player or WorldSyncedTo is associated with the grid, when the Active Grid has not been initialized yet, or when this method is called while the Active Grid is busy executing a multi frame action (check IsBusy before calling ActiveGrid methods that begin with "Try"), or when setPlayerYPositionBasedOnTerrain is true but the Current WorldSyncedTo does not use Unity Terrain or chunks are not enabled on the Active Grid.

InvalidOperationException

Thrown when no player or WorldSyncedTo is associated with the grid, when the Active Grid has not been initialized yet, or when this method is called while the Active Grid is busy executing a multi frame action (check IsBusy before calling ActiveGrid methods that begin with "Try"), or when setPlayerYPositionBasedOnTerrain is true but the Current WorldSyncedTo does not use Unity Terrain or chunks are not enabled on the Active Grid.

TryMovePlayerToLocationOnNewWorld(Vector3Double, World, bool, bool, bool, [bool], [double], [int])

public IEnumerator<YieldInstruction> TryMovePlayerToLocationOnNewWorld(Vector3Double location, World newWorldToSyncTo, bool waitForCommandBeforeMovingPlayer, bool allowGridToRecenterWorld, bool waitForOldObjectsToBeRemoved, bool setPlayerYPositionBasedOnTerrain = false, double playerYOffset = 1f, int groupingWithTerrainToAlignPlayerTo = 1)

Tries to move the player associated with this Active Grid to the location specified on the new World, and if the move is successful, syncs the Active Grid to this new World.

This method fully loads the cells (and objects if necessary) around the target location before moving the player (this occurs over several frames).

Once loaded, if waitForCommandBeforeMovingPlayer is true, this method will yield until InitiatePendingMove is called. If false, this method will move the player immediately after the objects at the new location are loaded.

If waitForCommandBeforeMovingPlayer is true, you can query the PlayerReadyToBeMoved property to make sure the Active Grid has loaded the new area before calling InitiatePendingMove (otherwise, there is no guarantee the player will be moved immediately after calling InitiatePendingMove).

Depending on the PlayerMover used by this Active Grid, the actual move operation may also take several frames.

This method, like all Try methods in this API, will throw an exception when a coroutine operation is currently being executed by this Active Grid. The best way to account for this possibility is to simply check to make sure the Active Grid is not busy before calling this method, which you can do by checking the Active Grid's IsBusy property.

Parameters

Name	Type	Description
location	Vector3Double	The location to move the player to.
newWorldToSyncTo	World	The new World to sync to.
waitForCommandBeforeMovingPlayer	bool	If true, the new area that the player will be moved to will be loaded, but the actual move operation will be delayed until the InitiatePendingMove method is called. If false, the move will be performed immediately after the new area is loaded.
allowGridToRecenterWorld	bool	If true, the grid will be permitted to force the World To re-center itself when the player crosses the re-centering boundary (assuming 'Allow Active Grid Re-Centering' is enabled on the World).
waitForOldObjectsToBeRemoved	bool	If true, the coroutine will not exit/yield break until the pre sync/move objects that are no longer needed are removed. This is mostly useful if displaying a loading screen and you only want to remove the loading screen when the WorldSyncedTo is completely up to date, or if you think the old objects might intersect with the new ones, which would look quite bad to the player if seen.
setPlayerYPositionBasedOnTerrain	bool	If true, the y value in location will be ignored and the y position to move the player to will be calculated based on the height of the terrain at the location to move the player to. Only set this to true if you know the newWorldToSyncTo uses Terrain. If there is no terrain at the location, the location's y value will be used. Note that this value applies to any future automatic movement of the player by the Active Grid, such as when a world shift occurs.
playerYOffset	double	When setPlayerYPositionBasedOnTerrain is true, this value can be used to ensure the player does not overlap the terrain. A value of 1, for instance, will place the player 1 unit above the terrain's height. You will need to experiment to find the best value, as it will depend largely upon the shape and height of your player's collider. Note that this value applies to any future automatic movement of the player by the Active Grid, such as when a world shift occurs.
groupingWithTerrainToAlignPlayerTo	int	The World Grouping on the new world that contains the terrain to align the player to. This is usually the base World Grouping (Layer 1)

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
InvalidOperationException	Thrown when no player is associated with the grid, when the Active Grid has not been initialized yet, or when this method is called while the Active Grid is busy executing a multi frame action (check IsBusy before calling ActiveGrid methods that begin with "Try"), or when setPlayerYPositionBasedOnTerrain is true but the new WorldSyncedTo to sync to does not use Unity Terrain or chunks are not enabled on the Active Grid.

InvalidOperationException

Thrown when no player is associated with the grid, when the Active Grid has not been initialized yet, or when this method is called while the Active Grid is busy executing a multi frame action (check IsBusy before calling ActiveGrid methods that begin with "Try"), or when setPlayerYPositionBasedOnTerrain is true but the new WorldSyncedTo to sync to does not use Unity Terrain or chunks are not enabled on the Active Grid.

TrySetIfWorldShouldBeUpdated(bool)

public void TrySetIfWorldShouldBeUpdated(bool worldShouldBeUpdated)

Attempts to set the "Update World" property of all Groupings on the Active Grid. Pass in true if you want all Groupings to update the World the Active Grid is synced to, or false if you do not want them to update the World.

With world upates enabled, the Active Grid will update the World on which cells are loaded for each Active World Grouping. It does this when the Active Grid is initially initilized (by sending the list of cells that are initially loaded on the World Grouping based on the player's initial position), and also when the collection of cells tracked by the Active Grid are updated dynamically as a result of the player moving across the current inner area boundary of each Active World Grouping (however, this only occurs if 'Enable Auto Tracking' is enabled for each layer).

The inner area boundary is calculated using the Loading Blueprint used by the Active World Grouping, as well as the dimensions of the cells on the same World Grouping on the World the Active Grid is sycned to (more specifically, the Streamable Grid of the World Grouping).

This method will likely result in World Cells on the WorldSyncedTo to be loaded or unloaded, however using this by itself will not allow you to track when that happens. This method will also not allow for the player to be aligned to a Terrain when worldShouldBeUpdated. If you need player alignment to be performed, or need to know when the World Cells are loaded/unloaded as a result of Update World being set, you should use the TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate method instead.

Note that it's possible that the Active Grid has more groupings than the World it is synced to. In this case, all groupings on the Active Grouping are updated, even if the grouping does not have a corresponding grouping on the World. In this way, if the Active Grid becomes synced to a World with a new matching grouping, the value you set will be applied to it.

Parameters

Name	Type	Description
worldShouldBeUpdated	bool	Whether the world should be updated for all Groupings of the Active Grid.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the Active Grid has not been initialized or if the method is called while the Active Grid is already busy. You should always check if the Active Grid is busy before calling any method that begins with Try!

TrySetIfWorldShouldBeUpdated(bool, int)

public void TrySetIfWorldShouldBeUpdated(bool worldShouldBeUpdated, int groupingIndex)

Parameters

Name	Type	Description
worldShouldBeUpdated	bool	Whether the world should be updated for the Grouping of the Active Grid.
groupingIndex	int	The index of the Grouping on the Active Grid whose "Update World" property will be set.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the Active Grid has not been initialized or if the method is called while the Active Grid is already busy. You should always check if the Active Grid is busy before calling any method that begins with Try!

TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate(bool)

public IEnumerator<YieldInstruction> TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate(bool worldShouldBeUpdated)

Attempts to set the "Update World" property of all Groupings on the Active Grid. Pass in true if you want all Groupings to update the World the Active Grid is synced to, or false if you do not want them to update the World.

With world upates enabled, the Active Grid will update the World on which cells are loaded for each Active World Grouping. It does this immediately (by sending the list of cells that are currently 'loaded' on the Layer), and also when the collection of cells tracked by the Active Grid are updated dynamically as a result of the player moving across the current inner area boundary of each Active World Grouping (however, this only occurs if 'Enable Auto Tracking' is enabled for each layer).

The inner area boundary is calculated using the Loading Blueprint used by the Active World Grouping, as well as the dimensions of the cells on the same World Grouping on the World the Active Grid is sycned to (more specifically, the Streamable Grid of the World Grouping).

This method is the same as TrySetIfWorldShouldBeUpdated, except that the method will wait for the World the Active Grid is synced to to complete a full update. This ensures that the World Cells on the WorldSyncedTo associated with the cells of the Active Grid are either loaded (when worldShouldBeUpdated is true) or unloaded (when worldShouldBeUpdated is false). This allows you to wait for the game world to either be loaded (and in a playable state) or unloaded before continuing with some other action (such as removing a loading screen).

In addition, when worldShouldBeUpdated is true and Align Player To Terrain is enabled in the inspector of this Active Grid, after waiting for a world update, the method will align the player to the Terrain. This is not done with the normal TrySetIfWorldShouldBeUpdated method, so if you need the player to be aligned to the Terrain, you must use this coroutine method, regardless of whether you care about waiting for a World update.

Parameters

Name	Type	Description
worldShouldBeUpdated	bool	Whether the world should be updated for all Groupings of the Active Grid.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the Active Grid has not been initialized or if the method is called while the Active Grid is already busy. You should always check if the Active Grid is busy before calling any method that begins with Try!

TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate(bool, int)

public IEnumerator<YieldInstruction> TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate(bool worldShouldBeUpdated, int groupingIndex)

Attempts to set the "Update World" property of a single Grouping on the Active Grid. Pass in true if you want the Grouping to update the World the Active Grid is synced to, or false if you do not want it to update the World.

With world upates enabled, the Active Grid will update the World on which cells are loaded for the Active World Grouping. It does this immediately (by sending the list of cells that are currently 'loaded' on the Grouping), and also when the collection of cells tracked by the Active Grid are updated dynamically as a result of the player moving across the current inner area boundary of the Active World Grouping (however, this only occurs if 'Enable Auto Tracking' is enabled for the Grouping).

The inner area boundary is calculated using the Loading Blueprint used by the Active World Grouping, as well as the dimensions of the cells on the same World Grouping on the World the Active Grid is sycned to (more specifically, the Streamable Grid of the World Grouping).

This method is the same as TrySetIfWorldShouldBeUpdated, except that the method will wait for the World the Active Grid is synced to to complete a full update. This ensures that the World Cells on the WorldSyncedTo associated with the cells of the Active Grid are either loaded (when worldShouldBeUpdated is true) or unloaded (when worldShouldBeUpdated is false). This allows you to wait for the game world to either be loaded (and in a playable state) or unloaded before continuing with some other action (such as removing a loading screen).

In addition, when worldShouldBeUpdated is true, Align Player To Terrain is enabled in the inspector of this Active Grid, and the World Grouping passed in is the same layer assigned to the 'World Grouping With Terrain To Align Player To' field, after waiting for a world update, the method will align the player to the Terrain. This is not done with the normal TrySetIfWorldShouldBeUpdated method, so if you need the player to be aligned to the Terrain, you must use this coroutine method, regardless of whether you care about waiting for a World update.

Parameters

Name	Type	Description
worldShouldBeUpdated	bool	Whether the world should be updated for the Grouping of the Active Grid.
groupingIndex	int	The index of the Grouping on the Active Grid whose "Update World" property will be set.

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the Active Grid has not been initialized or if the method is called while the Active Grid is already busy. You should always check if the Active Grid is busy before calling any method that begins with Try!

TrySyncToNewWorldAroundPlayer(World, bool, bool, [bool], [double], [bool], [int])

public IEnumerator<YieldInstruction> TrySyncToNewWorldAroundPlayer(World newWorldToSyncTo, bool allowGridToRecenterWorld, bool waitForOldObjectsToBeRemoved, bool setPlayerYPositionBasedOnTerrain = false, double playerYOffset = 1f, bool waitForCommandBeforeMovingPlayer = false, int groupingWithTerrainToAlignPlayerTo = 1)

Tries to sync to the new WorldSyncedTo at the player's Current position.

This method fully loads the cells (and objects if necessary) of the new WorldSyncedTo, and then removes the cells (and objects) of the old WorldSyncedTo.

This method, like all Try methods in this API, will throw an exception when a coroutine operation is Currently being executed by this Active Grid. The best way to account for this possibility is to simply check to make sure the Active Grid is not busy before calling this method, which you can do by checking the Active Grid's IsBusy property.

Parameters

Name	Type	Description
newWorldToSyncTo	World	The new World to sync to.
allowGridToRecenterWorld	bool	If true, the grid will be permitted to force the World To re-center itself when the player crosses the re-centering boundary (assuming 'Allow Active Grid Re-Centering' is enabled on the World).
waitForOldObjectsToBeRemoved	bool	If true, the coroutine will not exit/yield break until the pre sync objects that are no longer needed are removed. This is mostly useful if displaying a loading screen and you only want to remove the loading screen when the scene is completely up to date. This is especially useful for this method because it's almost guaranteed that the new objects will intersect the old objects, which if seen by the player, would look quite bad.
setPlayerYPositionBasedOnTerrain	bool	If true, once the new WorldSyncedTo is loaded, the y position of the player will be adjusted to that of the terrain the player is on (plus the playerYOffset). If a Player Mover exist on the Active Grid, it will be used to move the player. Note that this value applies to any future automatic movement of the player by the Active Grid, such as when a world shift occurs.
playerYOffset	double	When setPlayerYPositionBasedOnTerrain is true, this value can be used to ensure the player does not overlap the terrain. A value of 1, for instance, will place the player 1 unit above the terrain's height. You will need to experiment to find the best value, as it will depend largely upon the shape and height of your player's collider. Note that this value applies to any future automatic movement of the player by the Active Grid, such as when a world shift occurs.
waitForCommandBeforeMovingPlayer	bool	This variable only applies when setPlayerYPositionBasedOnTerrain is true, otherwise the player will not be moved at all and this variable will not be useful. When setPlayerYPositionBasedOnTerrain, this controls whether the method should wait for a manual move command before changing the player's y position. This move command is supplied via the InitiatePendingMove method, which you will call. If waitForCommandBeforeMovingPlayer is true, you should query the PlayerReadyToBeMoved property to make sure the Active Grid has loaded the new area before calling InitiatePendingMove (otherwise, there is no guarantee the player will be moved immediately after calling InitiatePendingMove).
groupingWithTerrainToAlignPlayerTo	int	The World Grouping on the new world that contains the terrain to align the player to. This is usually the base World Grouping (Grouping 1)

Returns

IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine. See the YieldInstruction page for more info.

Exceptions

RequiredComponentNotFoundException

Thrown when a Player Transform has not been supplied to the Active Grid.

InvalidOperationException

Thrown when no player is associated with the grid, when the Active Grid has not been initialized yet, when this method is called while the Active Grid is busy executing a multi frame action (check IsBusy before calling ActiveGrid methods that begin with "Try"), or when setPlayerYPositionBasedOnTerrain is true but the new WorldSyncedTo to sync to does not use Unity Terrain or chunks are not enabled on the Active Grid.

Events

ActiveGridMoved

Subscriber Syntax: void MethodName(object sender, ActiveGridMovedEventArgs parameterName)

An event that can be subscribed to in order to receive notifications when the Active Grid moves during runtime. This may occur as the result of a grid shift or player move to a new location on the Current world. Note that syncing to a new world will not trigger this event, as the Active Grid is rebuilt rather than moved.

This event is most useful when needing to perform some action as the grid is moved, such as updating an LOD system. You should filter out the event using the World Grouping property to only perform actions when the grid moves on whatever layers you care about. You can also disable this event from firing for one or more Groupings by disabling the 'Enable Grid Moved Events' option in the inspector.

The World Grouping property is only accurate for the lifetime of your subscribed method, after this the value may change.

The event utilizes ActiveGridMovedEventArgs and subscribers must have a signature of void MethodName(object sender, ActiveGridMovedEventArgs paramaterName).

This event can also be subscribed to at the Component Manager Level, which removes the limitation of needing to subscribe to a specific Active Grid. Via the Component Manager, you can set up a subscriber such that it is called under any of the following circumstances:

1) When any Active Grid in the scene fires the event for any World Grouping.
2) When any Active Grid in the scene fires the event for a particular World Grouping.
3) When any Active Grid synced with a particular World fires the event for any World Grouping.
4) When any Active Grid synced with a particular World fires the event for a particular World Grouping.

Use the SubscribeToActiveGridMovedEvents and UnsubscribeToActiveGridMovedEvents methods for this purpose.

CellPlayerIsInChanged

Subscriber Syntax: void MethodName(object sender, CellPlayerIsInChangedEventArgs parameterName)

An event that can be subscribed to in order to receive notifications when the cell the player is in changes. Please keep the following points in mind:

1) This event will fire upon initialization of the Active Grid or when the Active Grid syncs to a new World, because the initial cell the player is in usually needs to be known by listeners interested in monitoring whether the cell the player is in changes.

2) Please note, any reference values stored in this event are immedidately nulled out after all listeners have been notified of the event, therefore, if you wish to reference the objects after your listener method has been called, you will need to save a reference to the object(s) yourself. In addition, any non reference values cannot be considered accurate after your listener method has completed, so again, store the values if you wish to save them.

3) Since an Active Grid can be synced to a world with multiple World Groupings, the cell that changes is tied to a specific grouping, which can be retrieved from the WorldGroupingIndex property on the event args object. Multiple events can be fired in a single frame, one for each grouping that is set to fire the event.

4) The cell in question is the Endless Grid Cell the player is in, which can change, among other reasons, as the result of a world shift. In this case, the StreamableGridCellPlayerIsIn and WorldCellPlayerIsIn will remain the same as before the event was fired. In other situations, the WorldCell will change but StreamableGridCellPlayerIsIn will remain the same (if the player is transported to different Endless Grid Cell that is associated with the same Streamable Grid Cell as the previous Endless Grid Cell the player was on).

5) When the Active Grid becomes desynced from a World, this event fires with the CausedByDesync property set to true, WorldCellPlayerIsIn set to null, and EndlessGridCellPlayerIsIn/StreamableGridCellPlayerIsIn values invalid. You should think of the Cell the player is in under these circumstances to be null.

If this event is fired as a result of the Player being synced to an entirely new world, another CellPlayerIsInChangedEventArgs will be triggered with the World set to the new world and WorldCellPlayerIsIn, EndlessGridCellPlayerIsIn, and StreamableGridCellPlayerIsIn will be set and/or valid.

6) The WorldCellPlayerIsIn property will also return null if a World Cell cannot be retrieved from the World for a given cell. This can occur if that cell on the World is not active, either because the component manager has not been initialized or had time to fully load the world objects, that cell is simply empty, or this Active Grid and any other World users are not "using" that cell (which can occur, for instance, if the Active Grid's Monitor Inner Area Boundaries option is disabled). In any case, EndlessGridCellPlayerIsIn and StreamableGridCellPlayerIsIn will still be valid.

7) The event args are reused for each event, so once a new event fires the WorldCellPlayerIsIn, EndlessGridCellPlayerIsIn, StreamableGridCellPlayerIsIn, WorldGroupingIndex, and ReasonForNullWorldCell values will no longer be accurate for the previous event (though some values may be the same, depending upon the situation which caused the new event to fire).

8) Depending upon your loading blueprint, a change in the cell the player is may not result in a change in the world (in situations where your inner area is not a single cell). You should not rely on this event to tell you when the world has been updated, as even in situations where the world will be updated, there is no guarantee that the update will be complete before this event fires.

9) The event utilizes CellPlayerIsInChangedEventArgs and subscribers must have a signature of void MethodName(object sender, CellPlayerIsInChangedEventArgs paramaterName).

This event can also be subscribed to at the Component Manager Level, which removes the limitation of needing to subscribe to a specific Active Grid. Via the Component Manager, you can set up a subscriber such that it is called under any of the following circumstances:

1) When any Active Grid in the scene fires the event for any World Grouping.
2) When any Active Grid in the scene fires the event for a particular World Grouping.
3) When any Active Grid synced with a particular World fires the event for any World Grouping.
4) When any Active Grid synced with a particular World fires the event for a particular World Grouping.

Use the SubscribeToCellPlayerIsInChangedEvents and UnsubscribeToCellPlayerIsInChangedEvents methods for this purpose.

PlayerMovedByGrid

Subscriber Syntax: void MethodName(object sender, PlayerMovedByGridEventArgs parameterName)

An event that can be subscribed to in order to receive notifications when the player is moved by the Active Grid. This is most useful when trying to sync an action to the player being moved during one of the Active Grids move methods.

Please note, the Player object stored in this event is immedidately nulled out after all listeners have been notified of the event, therefore, if you wish to reference the object after your listener method has been called, you will need to save a reference to the object yourself.

Also note, the event is not fired upon Component Manager initialization for Active Grids, even though the location of the player may change due to save data or an attempt to align the player with a terrain. It is only called during runtime after initialization.

The event utilizes PlayerMovedByGridEventArgs and subscribers must have a signature of void MethodName(object sender, PlayerMovedByGridEventArgs paramaterName).

WorldSyncedToChanged

Subscriber Syntax: void MethodName(object sender, WorldSyncedToChangedEventArgs parameterName)

An event that can be subscribed to in order to receive notifications when the World the Active Grid is synced to changes. This occurs when the Active Grid is first initialized and a valid World is present, or when manually changing the World via the API. When the sync occurs as a result of using the TryMovePlayerToLocationOnNewWorld method, the sync "occurs" when the player is moved, otherwise the sync occurs just before the coroutine that triggered the sync exits.

This event can also be fired when desyncing from a World and not syncing to a different world, in which case the NewWorld property will be null. In this case, you should not use the GetWorldCellPlayerIsStartingIn and GetEndlessGridCellPlayerIsStartingIn, as they will not be valid and will likely throw exceptions.

In addition to containing references to the old and new World, it also contains the starting World Cells for the player, for each layer on the new world (use the GetWorldCellPlayerIsStartingIn method to retreive the cells. Using this in conjuction with the CellPlayerIsInChanged event will allow you to fully track which cell the player is in for one or all layers. Do note, however, that the World Cells may be null in some instances, and you should account for this by checking for null. You can use the Endless Grid Cell values instead when a World Cell is null.

In addition, the args contain the GetEndlessGridCellPlayerIsStartingIn method for retrieving the Endless Grid cell that the player is in. This can be used if the World Cell value is null, which can occur in some situations and should be accounted for. Using the Endless Grid Cell, you can query the World for useful information, such as the bounds of the cell.

Please note, any reference values stored in this event are immedidately nulled out after all listeners have been notified of the event, therefore, if you wish to reference the objects after your listener method has been called, you will need to save a reference to the object(s) yourself. In addition, non reference values should be considered invalid after the listeners have been notified.

The event utilizes WorldSyncedToChangedEventArgs and subscribers must have a signature of void MethodName(object sender, WorldSyncedToChangedEventArgs paramaterName). The sender is the Active Grid which is firing the event, so you are free to cast the sender to an ActiveGrid object if you need the reference for some reason.