ComponentManager Class

public Dictionary<int, ActiveGrid>.ValueCollection ActiveGridsInScene()

Can be used to iterate over the collection of ActiveGrids in the scene in a garbage free manner.

Returns

Dictionary<int, ActiveGrid>.ValueCollection
Internally the Active Grids in the scene are stored in a dictionary, with the Active Grids as values. This returns those values, which you can iterate over using a foreach statement.

public void ConvertOldSaveData(PersistentDataController persistentDataController, IPersistentStateManager persistentStateManager, List<string> oldDataKeys, List<OldActiveGridData> oldActiveGridData = null)

Use this to convert data that was saved via the Component Manager using a Persistent Data Controller to a format compatible with Persistent State Managers. This method will basically load the data and re-save it using the passed in Persistent State Manager, so the Persistent State Manager should be setup to save data just as if the Save method were being used. The data is only loaded for re-saving purposes, it will not be used by the Component Manager when it is initialized like the normal Load method. As such, you will still need to call the Load method once you have converted the data.

Under some scenarios it is possible for the conversion to fail, either in part or in total. When this happens, a DataConversionException will be thrown. It is recommended to place this method's invocation in a try/catch statement, catching the DataConversionException and handling it properly. If the exception is not thrown, it means the data was converted 100% successfully and you can delete the old data either manually or using the DeleteOldData method. Conversion failures may be fixable through modifications to your scene (common), or they may be due to corrupted save data (rare).

Please note that for runtime created Active Grids and Worlds, the protoype ID is now used to identify prototypes rather than the index of the prototype in the Prototype Array. Since the old save data will still be using the index, it's important to ensure the ordering of prototypes is the same now as it was when the data was saved, and that all prototypes that were in use at the time of saving are still in use, so that the prototypes can be matched correctly. In addition, the ID's of the prototypes must be configured so that all prototypes of a specific component type (World or Active Grid) use unique ID's (note, they do not need to be different than non prototypes that have been added to the scene in the Unity Editor, as these use a different pool of IDs).

Once conversion has been executed, you are free to re-order and remove prototypes, so long as you do not change the IDs and do not remove prototypes that are present in persistent data.

Parameters

Exceptions

public static void ConvertOldSaveData(string oldSaveData, IPersistentStateManager persistentStateManager, List<OldActiveGridData> oldActiveGridData = null)

Use this to convert old data saved using the Component Manager's GetSaveData method (no longer available) to a format compatible with Persistent State Managers. This method will basically load the data and re-save it using the passed in Persistent State Manager, so the Persistent State Manager should be setup to save data just as if the Save method were being used. The data is only loaded for re-saving purposes, it will not be used by the Component Manager when it is initialized like the normal Load method. As such, you will still need to call the Load method once you have converted the data.

Under some scenarios it is possible for the conversion to fail, either in part or in total. When this happens, a DataConversionException will be thrown. It is recommended to place this method's invocation in a try/catch statement, catching the DataConversionException and handling it properly. If the exception is not thrown, it means the data was converted 100% successfully and you can delete the old string data if you wish. Conversion failures may be fixable through modifications to your scene (common), or they may be due to corrupted save data (rare).

Please note that for runtime created Active Grids and Worlds, the protoype ID is now used to identify prototypes rather than the index of the prototype in the Prototype Array. Since the old save data will still be using the index, it's important to ensure the ordering of prototypes is the same now as it was when the data was saved, and that all prototypes that were in use at the time of saving are still in use, so that the prototypes can be matched correctly. In addition, the ID's of the prototypes must be configured so that all prototypes of a specific component type (World or Active Grid) use unique ID's (note, they do not need to be different than non prototypes that have been added to the scene in the Unity Editor, as these use a different pool of IDs).

Once conversion has been executed, you are free to re-order and remove prototypes, so long as you do not change the IDs and do not remove prototypes that are present in persistent data.

Parameters

Exceptions

public ActiveGrid CreateNonPersistentActiveGridUsingIPlayer(int IDOfPrototypeToConstructGridFrom, World alternateWorldToSyncTo = null, IPlayer alternatePlayerToAssociateWithGrid = null, PlayerMover playerMoverToAssociateWithGrid = null)

Creates and initializes a non-persistent Active Grid based on the prototype and the specified optional parameters. The grid data will not be saved with the component manager's save data.

When the Active Grid is initialized, the World the grid is synced to will also be initialized, as well as this Component Manager if it has not already been initialized.

Note, however, that you will need to manually enable World Updating on the Active Grid via the TrySetIfWorldShouldBeUpdated or TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate method. With World Updating disabled (the default state if one of those methods are not called), the Active Grid will not trigger the World to load/unload objects!

Parameters

Returns

ActiveGrid
The created and initialized non persistent Active Grid.

Exceptions

public ActiveGrid CreateNonPersistentActiveGridUsingTransform(int IDOfPrototypeToConstructGridFrom, World alternateWorldToSyncTo = null, Transform alternatePlayerToAssociateWithGrid = null, PlayerMover playerMoverToAssociateWithGrid = null)

Creates and initializes a non-persistent Active Grid based on the prototype and the specified optional parameters. The grid data will not be saved with the component manager's save data.

When the Active Grid is initialized, the World the grid is synced to will also be initialized, as well as this Component Manager if it has not already been initialized.

Note, however, that you will need to manually enable World Updating on the Active Grid via the TrySetIfWorldShouldBeUpdated or TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate method. With World Updating disabled (the default state if one of those methods are not called), the Active Grid will not trigger the World to load/unload objects!

Parameters

Returns

ActiveGrid
The created and initialized non persistent Active Grid.

Exceptions

public World CreateNonPersistentWorld(int IDOfPrototypeToConstructWorldFrom, string[][] alternateGroupNamesToUse = null, Vector3? alternateWorldOrigin = null, Cell? alternateOriginCell = null, List<int> worldRegionNumbersToAutoLoad = null, List<string> worldRegionNamesToAutoLoad = null)

Creates and initializes a non persistent World using the information from the prototype and optional parameters. The non persistent world will be saved with the component manager's save data, but only non persistent Active Grid's will be able to sync to it. Calling this method will initialize this Component Manager if it has not already been initialized.

Parameters

Returns

World
The created and initialized non persistent World.

Exceptions

ActiveGrid CreatePersistentActiveGrid(int IDOfPrototypeToConstructGridFrom, World alternatePersistentWorldToSyncTo = null)

Creates and initializes a persistent Active Grid based on the prototype and the specified optional parameters. The persistent grid data will be saved with the component manager's save data, and can only be synced with persistenet worlds.

When the Active Grid is initialized, the World the grid is synced to will also be initialized, as well as this Component Manager if it has not already been initialized.

Note, however, that you will need to manually enable World Updating on the Active Grid via the TrySetIfWorldShouldBeUpdated or TrySetIfWorldShouldBeUpdatedThenWaitForWorldUpdate method. With World Updating disabled, the Active Grid will not trigger the World to load/unload objects!

Notice that unlike with non persisten Active Grids, there is no option to provide an alternate player or player mover. This is because there is no way to save the alternate player and player mover with the grid's persistent data, therefore persistent grids are limited to having to use the player assigned to the prototype!

Parameters

Returns

ActiveGrid
The created and initialized persistent Active Grid.

Exceptions

public World CreatePersistentWorld(int IDOfPrototypeToConstructWorldFrom, string[][] alternateGroupNamesToUse = null, Vector3? alternateWorldOrigin = null, Cell? alternateOriginCell = null, List<int> worldRegionNumbersToAutoLoad = null, List<string> worldRegionNamesToAutoLoad = null)

Creates and initializes a persistent World using the information from the prototype and optional parameters. The persistent world will be saved with the component manager's save data, and both persistent and non persistent Active Grids can sync to it. Calling this method will initialize this Component Manager if it has not already been initialized.

Parameters

Returns

World
The created and initialized persistent World.

Exceptions

public void DeleteOldData(PersistentDataController persistentDataController, List<string> oldDataKeys)

Convenience method for deleting old data saved using a Persistent Data Controller. You can use this method after calling ConvertOldSaveData (PersistentDataController version) and having it complete 100% successfully (no DataConversionException thrown). That method will populate the oldDataKeys list with all of the keys associated with the old data. This method then just cycles through these keys and calls PersistentDataController.TryDeleteData for each one.

Parameters

public void DestroyActiveGrid(int IDOfActiveGridToDestroy)

Destroys the Active Grid with IDOfActiveGridToDestroy. All cell users associated with the Active Grid are removed from cells on the World the Active Grid is Currently synced to. If those cells have no more cell users after this removal, the cell chunks are removed from the scene.

This removal is performed over a series of frames for performance reasons, however this method destroys the Active Grid immediately and does not wait for the cell users (and associated cell chunks) to be removed from the world. If you need to wait for this process to complete (perhaps you only want to perform some action after the cell users/asset chunks have been removed), use DestroyActiveGridAndWaitForCellUsersToBeRemoved instead.

Parameters

Exceptions

Example:

            class DestroyActiveGridExample
            {
                ActiveGrid myActiveGrid;
                
                public void OnDestroyActiveGrid()
                {
                    //You should only have one component manager in the scene
                    ComponentManager componentManager = GameObject.FindObjectOfType<ComponentManager>();
                    
                    componentManager.DestroyActiveGrid(myActiveGrid.ID);
                }
            }
            

public IEnumerator<YieldInstruction> DestroyActiveGridAndWaitForCellUsersToBeRemoved(int IDOfActiveGridToDestroy)

Destroys the Active Grid with IDOfActiveGridToDestroy. All cell users associated with the Active Grid are removed from the cells on the World the Active Grid is Currently synced to. If those cells have no more cell users after this removal, the cell chunks are removed from the scene.

This removal is performed over a series of frames for performance reasons, and the Active Grid will only be destroyed after this removal process completes. This method should be used if you need to know when the cell users/objects are removed and want to wait for the process to complete. Use like any other coroutine.

Parameters

Exceptions

Example:

            class DestroyActiveGridExample
            {
                ActiveGrid myActiveGrid;
                
                //This method should have been called via StartCoroutine
                public IEnumerator OnDestroyActiveGrid()
                {
                    //You should only have one component manager in the scene
                    ComponentManager componentManager = GameObject.FindObjectOfType<ComponentManager>();
                    
                    yield return StartCoroutine(componentManager.DestroyActiveGridAndWaitForCellUsersToBeRemoved(myActiveGrid.ID));
                }
            }
            

Example:

            class DestroyActiveGridExample
            {
                ActiveGrid myActiveGrid;
                
                //This method should be started using StartCoroutine or iterated over manually in another coroutine
                public IEnumerator<YieldInstruction> OnDestroyActiveGrid()
                {
                    //You should only have one component manager in the scene
                    ComponentManager componentManager = GameObject.FindObjectOfType<ComponentManager>();
                    
                    IEnumerator<YieldInstruction> e = componentManager.DestroyActiveGridAndWaitForCellUsersToBeRemoved(myActiveGrid.ID);
                    while(e.MoveNext())
                        yield return e.Current;
                }
            }
            

public IEnumerator<YieldInstruction> DestroyActiveGridsAndWorldsAndUnloadWorldCells()

Can be used to destroy every initialized Active Grid and World in the scene. Before doing so, all World Cells associated with the Active Grids and Worlds are removed from the scene. This is useful for removing scene assets that have been loaded and kept in the scene, specifically when your Scene Chunk Streamer has the 'Keep Scenes Intact' option enabled.

When that option is enabled, the loaded scenes that contain Streamable Asset Chunks are kept in the scene, and these scenes will not be removed automatically when the scene containing the Component Manager and other Streamable Assets Manager game objects is unloaded. In these circumstances, it is necessary to manually remove the scene assets prior to unloading the main scene that contains the Component Manager and other game objects. You can use this method for that purpose.

Once this method is called, you should not interact with any Streamable Assets Manager objects, including this Component Manager. Therefore, if you wish to save data, you should do so before calling this method. The only correct use of this method is to call it, wait for it to complete, and then unload the main containing the Component Manager and other SAM game objects.

Returns

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

public void DestroyWorld(int IDOfWorldToDestroy)

Destroys the World with IDofWorldToDestroy. All World Cells and Asset Chunks associated with the World are removed from the scene.

This removal is performed over a series of frames for performance reasons, though the World's destruction will be reflected in the persistent data if you save during the process.

If you care about when the removal process completes (and thus when the World is actually destroyed) use DestroyWorldAndWaitForChunksToBeRemoved instead and provide a callback method.

Parameters

Exceptions

Example:

            class DestroyWorldExample
            {
                World myWorld;
                
                public void OnDestroyWorld()
                {
                    //You should only have one component manager in the scene
                    ComponentManager componentManager = GameObject.FindObjectOfType<ComponentManager>();
                    
                    componentManager.DestroyWorld(myWorld.ID);
                }
            }
            

public IEnumerator<YieldInstruction> DestroyWorldAndWaitForChunksToBeRemoved(int IDOfWorldToDestroy, Action<World> onCompletedCallback)

This method is virtually the same as DestroyWorld, except with this method you can pass in a System.Action which will be called just before the World has been destroyed (but after all World Cells and Asset Chunks associated with the World have been removed from the scene). Note that the World argument that is passed into your Action will be valid for only the frame that the action is called, because the actual World object is destroyed just after the action completes.

Parameters

Exceptions

public bool DoesOldDataExist(PersistentDataController persistentDataController)

Can be used to determine whether any persistent data saved using the Persistent Data Controller exist for this Component Manager. If such data exist, you should use ConvertOldSaveData to convert it to the format used by your Persistent State Manager, before calling the Component Manager's Load method.

This method should only be used at runtime (in game).

Parameters

Returns

bool
True if data exist, false otherwise.

Exceptions

public void Initialize()

Initializes the Component Manager over two frames. This in turn closes the window for loading persistent data and initializes all non prototype Active Grids/Worlds in the scene.

This should only be used if "Initialize On Awake" is unchecked in the inspector, and then only at the beginning of the game from another scripts Awake method. If the game has started (i.e., the update cycle is running), you should use InitializeGradually instead (for performance reasons).

This is meant to be used for debugging and testing mostly. For an actual game, it is recommended to use InitializeGradually as it offers better performance and can be used with a loading screen.

Progress Tracking is also only available when using InitializeGradually (using the InitializationProgress property).

public IEnumerator<YieldInstruction> InitializeGradually()

Initialzes the Component Manager over a series of frames. This coroutine exits only after all initial World Cells and Asset Chunks have been loaded, which allows you to display a loading screen or use some other device to hide the game world until it is fully loaded.

This should only be used if "Initialize On Awake" is unchecked in the inspector.

The progress of this method can be tracked via the InitializationProgress property, which should only be queried after the method starts executing. Once the Initialization process is completed, that property will always return 1f.

Because this method is more performant and progress can be tracked, we recommend it for a live game (non testing environment).

Returns

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

public void Load(IPersistentStateManager persistentStateManager)

Loads save data that was saved via the Save method. This method makes use of the IPersistentStateManager interface. You can use one of the provided implmentations of this interface or create your own implementation, as the interface provides maximum flexibility to control how your save system works.

VERY IMPORTANT: There is a limited window in which persistent data can be loaded via this method. This window will close immediately when CreatePersistentActiveGrid, CreateNonPersistentActiveGrid, CreatePersistentWorld, or CreateNonPersistentWorld are called for the first time. It will also close once the Component Manager has been initialized. You can delay initialization by unchecking "Initialize On Awake," but you will have to manually call Initialize or InitializeGradually.

Parameters

Exceptions

public void Save(IPersistentStateManager persistentStateManager)

Saves this component manager data, including the data of all persistent Active Grids and Worlds in the scene in a single frame.

While the Component Manager chooses which data is saved, the actual mechanism for saving is under the control of whatever Persistent State Manager you pass into this method.

It should go without saying, but this method can only be called after the Component Manager has been initialized.

Exceptions

public void SubscribeToActiveGridMovedEvents(World filterWorld, int filterWorldGrouping, Action<object, ActiveGridMovedEventArgs> methodToSubscribe)

Subscribe to Active Grid Moved Events, which is an event Active Grid's fire a Grouping on the Active Grid has its individual grid moved. Always make sure you call UnsubscribeToActiveGridMovedEvents at a later time when using this method! Usually, it's best to put the Subscribe in OnEnable and Unsubscribe in OnDisable.

While you can subscribe to this event directly via an Active Grid, doing so here is typically much easier as you can specify a World and/or World Grouping to listen to, and then have access to the events from all Active Grids that are synced to that World and/or Grouping.

Parameters

public void SubscribeToCellPlayerIsInChangedEvents(World filterWorld, int filterWorldGrouping, Action<object, CellPlayerIsInChangedEventArgs> methodToSubscribe)

Subscribe to Cell Player Is In Changed Events, which is an event Active Grid's fire when the cell the player is in changes. Always make sure you call UnsubscribeFromCellPlayerIsInChangedEvents at a later time when using this method! Usually, it's best to put the Subscribe in OnEnable and Unsubscribe in OnDisable.

While you can subscribe to this event directly via an Active Grid, doing so here is typically much easier as you can specify a World and/or World Grouping to listen to, and then have access to the events from all Active Grids that are synced to that World and/or Grouping.

Parameters

public bool TryGetActiveGridByID(int ID, out ActiveGrid activeGrid)

Tries to get the Active Grid specified by ID.

Parameters

Returns

bool
A bool indicating whether the ActiveGrid was found.

public bool TryGetWorldByID(int worldID, out World world)

Tries to get the World specified by worldID.

Parameters

Returns

bool
A bool indicating whether the World was found.

public void UnsubscribeToActiveGridMovedEvents(World filterWorld, int filterWorldGrouping, Action<object, ActiveGridMovedEventArgs> methodToUnsubscribe)

Unsubscribe from Active Grid Moved Events, which is an event Active Grid's fire when one of the grids on the Active Grid is moved. This method should be paired with a previous call to SubscribeToActiveGridMovedEvents! Usually, it's best to put the Subscribe in OnEnable and Unsubscribe in OnDisable.

Parameters

public void UnsubscribeToCellPlayerIsInChangedEvents(World filterWorld, int filterWorldGrouping, Action<object, CellPlayerIsInChangedEventArgs> methodToUnsubscribe)

Unsubscribe from Cell Player Is In Changed Events, which is an event Active Grid's fire when the cell the player is in changes. This method should be paired with a previous call to SubscribeFromCellPlayerIsInChangedEvents! Usually, it's best to put the Subscribe in OnEnable and Unsubscribe in OnDisable.

Parameters

public Dictionary<int, World>.ValueCollection WorldsInScene()

Can be used to iterate over the collection of Worlds in the scene in a garbage free manner.

Returns

Dictionary<int, World>.ValueCollection
Internally the Worlds in the scene are stored in a dictionary, with the Worlds as values. This returns those values, which you can iterate over using a foreach statement.