IWorldGroupingListener Interface

public interface IWorldGroupingListener

Provides an interface implementation for World Grouping Listener components and non component classes.

World Grouping Listeners can be assigned to a World Grouping in order to receive notification before or after the World Grouping is updated, and also before/after World Cells on the World Grouping are activated and/or deactivated. Previously, this behaviour was achieved via Cell Actions attached to the individual chunks of a cell, however this system was cumbersome as it required you to attach a component to each chunk game object.

The new system utilizes one or more components at the World Grouping level to perform actions on a collection of cells at a time. You can also utilize this system to keep track of what cells are currently active, by adding the cells from one of the 'Activated' methods and removing them from one of the 'Deactivated' methods to/from some internal collection.

The most useful situation I can think of for doing this when trying to add integration for 3rd party assets.

There are no cirucmstances I can think of where you would create a class that directly implements this interface. Normally, you will want to derive from either the WorldGroupingListener or WorldGroupingListenerNonComponent class, as these classes allow you to only override the listening methods (On...) that you need to, and the rest is taken care of (such as returning the correct value from the 'CallOn...' properties.

If for some reason you decide to implement this interface, you will need to provide an implementation for all of the listener methods, however if you don't want to actually use one or more of the methods, you can simply return the SimpleYieldBreakEquivalentEnumerator.Instance object in the implementation and then set the 'CallOn...' property for that method to return false. For any methods that you want called, you must return true for the associated 'CallOn...' property.

If a method you want to use does not need to utilize multiple frames, place the code you want executed as normal, then return SimpleYieldBreakEquivalentEnumerator.Instance. This will ensure no garbage is generated when the method is called.

Properties

Name Type Description
CallOnAfterAllCellsActivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnAfterAllCellsActivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnAfterAllCellsActivated called.

CallOnAfterAllCellsDeactivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnAfterAllCellsDeactivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnAfterAllCellsDeactivated called.

CallOnAfterCellsInBatchActivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnAfterCellsInBatchActivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnAfterCellsInBatchActivated called.

CallOnAfterCellsInBatchDeactivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnAfterCellsInBatchDeactivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnAfterCellsInBatchDeactivated called.

CallOnAfterGroupingUpdated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnAfterGroupingUpdated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnAfterGroupingUpdated called.

OnAfterGroupingUpdated is useful because it is called regardless of whether any cells have been activated or deactivated for the given World Grouping. Therefore, you can use it to perform logic that is not dependent on cells being specifically activated or deactivated. If your logic is dependent on activated or deactivated cells being present, use the OnAfterAllCellsActivated or OnAfterAllCellsDeactivated methods instead, utilizing the batchNumber and totalBatchesToExpect to find the last call to the method and performing the logic their, so it is only performed once.

Note the method is called regardless of the IgnoreLODTransitions properties value, so long as it is overriden.

CallOnBeforeAnyCellsActivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnBeforeAnyCellsActivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnBeforeAnyCellsActivated called.

CallOnBeforeAnyCellsDeactivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnBeforeAnyCellsDeactivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnBeforeAnyCellsDeactivated called.

CallOnBeforeCellsInBatchActivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnBeforeCellsInBatchActivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnBeforeCellsInBatchActivated called.

CallOnBeforeCellsInBatchDeactivated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnBeforeCellsInBatchDeactivated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnBeforeCellsInBatchDeactivated called.

CallOnBeforeGroupingUpdated bool

Returns a value indicating whether the World Grouping this IWorldGroupingListener is linked to should call the OnBeforeAnyCellUpdated method. Please note, when deriving from WorldGroupingListenerNonComponent or WorldGroupingListener, it is not necessary to worry about this property. All you need to do is override the method if you want it to be called. Reflection is used to set this property automatically to true when you override the method, or false if you don't override it.

However, if implementing this interface and not deriving from one of those classes, you will need to ensure this property returns the correct value depending on whether you want OnBeforeAnyCellUpdated called.

OnBeforeAnyCellUpdated is useful because it is called regardless of whether any cells will be activated or deactivated for the given World Grouping. Therefore, you can use it to perform logic that is not dependent on cells being specifically activated or deactivated. If your logic is dependent on activated or deactivated cells being present, use the OnBeforeAnyCellsActivated or OnBeforeAnyCellsDeactivated methods instead, utilizing the batchNumber and totalBatchesToExpect to find the last call to the method and performing the logic their, so it is only performed once.

Note the method is called regardless of the IgnoreLODTransitions properties value, so long as it is overriden.

IgnoreLODTransitions bool

Gets a value indicating whether the listener's methods will be called during LOD transitions. When an LOD transition occurs, technically a World Cell is deactivated (the old LOD) and a World Cell is activated (the new LOD), however generally it is better to think of these two World Cells as the same Cell that is just changing its Asset Chunks out. With that said, a lot of logic may be directed at the World Cell's Asset Chunks, and if that is the case with your WorldGroupingListener, you should set this property to return false, because the chunks will change during an LOD transition. The actuall WorldCell object instance will also change, so if you're storing these WorldCell objects in some way, you will also need to set this to false so that you can remove the old World Cells and add the new ones.\n\nIf, on the other hand, your WorldGroupingListeners only utilize data related to the World Cell's (such as position, Streamable Grid Indexes, etc.), this data will not change during an LOD Transition, so you can ignore them.

IsEnabled bool

Whether the listener is currently enabled. Its methods will only be called if it is enabled.

YieldBehaviorAfterMethodExecution ListenerYieldBehaviour

Gets a value that tells the World the Listener is being used with whether it should yield control (to the Unity Engine and other components your game might have), after fully executing one of its methods.

The options in the ListenerYieldBehaviour enumerator give you a great deal of control.

NeverYield can be chosen if you need to ensure that the next Listener to run runs immediately after this one finishes.

AlwaysYield, on the other hand, can be used to force the World to yield for at least a frame, which might be necessary to allow whatever code you've just run to "ferment".

Finally, YieldOrContinue can be used if you don't really care one way or the other whether the World yields control, as it will let the Execution Controller used by the World decide.

Methods

DetermineMethodCalls()

void DetermineMethodCalls()

This is called once automatically by each World Grouping using the Listener and can be used to calculate the values of the Call... properties (CallOnBeforeGroupingUpdated, CallOnBeforeAnyCellsDeactivated, etc.).

If your Listener does not precompute these values, you can implement this method to do nothing.

If you derive from WorldGroupingListener or WorldGroupingListenerNonComponent, this method is already implemented, so you do not need to worry about it.

If you do not derive from one of those two classes and need to precompute the values using this methods, keep in mind that if the Listener is being used with multiple World Groupings, this method will be called multiple times. You should have a system in place to ensure your precomputation logic only runs once.

Note that this method is called once by each World Grouping using the Listener, so it may be called multiple times in some cases. Usually, you should have some sort of safeguard in place to ensure the method determination logic only runs once.

OnAfterAllCellsActivated(ReadOnlyList<WorldCell>, int, int, bool, bool)

IEnumerator<YieldInstruction> OnAfterAllCellsActivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition, bool immediateMode)

This method is called after every cell on a World Grouping that the World has determined needs to be activated, have been activated for a given World Update (activation involves transitioning the cells to a visible state, adding them to any HierarchyOrganizers, and adding them to the internal collection of World Cells so that they become "part" of the Streamable World Grouping they were loaded for), for all cells that the World determined needed to be newly added, and also for cells which were added as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that.

Each of the OnCells...Activated methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL have its own chunks (game objects) present, and those chunks will be in an ACTIVATED state. 3) Each World Cell in the batch WILL have cell neighbors set, and the chunks of the cell neighbors will be in an ACTIVATED state. Please note, there is no gaurantee that a cell will have a neighbor, as if its on the edge of the world or next to an empty Streamable Grid Cell, there may be no World Cell to serve as its neighbor.

This method is well suited for neighbor related logic where you want a gaurantee that the cell neighbors will be present (if they exist) and accurate (all neighbors will be true neighbors, and not possibly LOD cells that are in the process of transitioning, or cells which will be deactivated; i.e., neighbors which will be nulled out or replaced in the future of this World Update). However, while it is called shortly after cells are activated, the timing is not as precise as OnAfterCellsInBatchActivated, since it is only called after all cells have been activated. Therefore, you should not place code that needs to be timed wiht the activation of a cell here.

In addition, you SHOULD USE this method for adding World Cells or World Cell related data from an internal collection such as a Dictionary.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch of cells which have been activated.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being activated as part of an LOD transition.

immediateMode bool

Whether the method is being called in immediate mode. Immediate mode simply means that the method is not being used as a coroutine. All yield statements are ignored in this mode and the entire code block will execute in a single frame. This mode is used only when the Component Manager in the scene has been Initialized in a non gradual manner, either via its "Initialize on Awake" method being enabled, or you (the user) calling Initialize in the Awake method of some script. In these instances, the World and its World Groupings are initialized and loaded within two frames (Awake and Start) so that the World Chunks appear before the first Update is called.

Typically you will not need to do any special code changes for immediate mode, however in case you do need to, you can query this value to determine if immediate mode is being used.

Returns

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

OnAfterAllCellsDeactivated(ReadOnlyList<WorldCell>, int, int, bool)

IEnumerator<YieldInstruction> OnAfterAllCellsDeactivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition)

This method is called after every cell on a World Grouping that the World has determined needs to be deactivated, has been deactivated for a given World Update (deactivation involves transitioning the cells to a non visible state, removing them from any HierarchyOrganizers, and removing them from the internal collection of World Cells so that they are no longer "part" of the Streamable World Grouping they were a part of), for all cells that the World determined needed to be removed completely, and also for cells which were removed as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that.

Each of the OnCells...Deactivated methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL NOT have its own chunks (game objects) present. 3) Each World Cell in the batch WILL NOT have cell neighbors.

Based on the gaurantees listed, hopefully you can see that this method is the most limited of the OnCells...Deactivated methods. No chunks or neighbors are present, so this method is only suitable if you need to perform non chunk related operations after all cells that are going to be deactivated have been deactivated in the current World Update.

In addition, you should not use this method for removing World Cells or World Cell related data from an internal collection such as a Dictionary, but instead use the OnBeforeAnyCellsDeactivated for this purpose.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch of cells which have been deactivated.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being deactivated as part of an LOD transition.

Returns

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

OnAfterCellsInBatchActivated(ReadOnlyList<WorldCell>, int, int, bool, bool)

IEnumerator<YieldInstruction> OnAfterCellsInBatchActivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition, bool immediateMode)

This method is called just after a batch of cells have been activated (activation involves transitioning the cells to a visible state, adding them to any HierarchyOrganizers, and adding them to the internal collection of World Cells so that they become "part" of the Streamable World Grouping they were loaded for), for all cells that the World determined needed to be newly added, and also for cells which were added as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that.

Each of the OnCells...Activated methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL have its own chunks (game objects) present, and those chunks will be in an ACTIVATED state. 3) Each World Cell in the batch WILL have cell neighbors set, and any non LOD related data of the neighbors can be considered accurate. However the state of the neighbor chunks is not predictable, and the neighbor may be replaced by different cells if the neighbor is undergoing an LOD transition (though do note, the neighbor is gauranteed to not be null in the future of the current World Update, since the deactivation of cells which need to be completely removed is performed prior to this method being called for the first time.

This method is well suited for non neighbor cell specific logic that you want to perform just after the activation of a cell, however do note that there is a small delay between the activation of a cell and this method being called, since all cells in a batch are activated together before this method is called for that batch. If you need more precise timing, you should set the World Grouping or LOD to not be activated automatically, and create a custom Cell Visual Transition Controller and perform that logic there, just after activating each cell.

In addition, you should not use this method for adding World Cells or World Cell related data from an internal collection such as a Dictionary, but instead use the OnAfterAllCellsActivated for this purpose.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch of cells which have just been activated.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being activated as part of an LOD transition.

immediateMode bool

Whether the method is being called in immediate mode. Immediate mode simply means that the method is not being used as a coroutine. All yield statements are ignored in this mode and the entire code block will execute in a single frame. This mode is used only when the Component Manager in the scene has been Initialized in a non gradual manner, either via its "Initialize on Awake" method being enabled, or you (the user) calling Initialize in the Awake method of some script. In these instances, the World and its World Groupings are initialized and loaded within two frames (Awake and Start) so that the World Chunks appear before the first Update is called.

Typically you will not need to do any special code changes for immediate mode, however in case you do need to, you can query this value to determine if immediate mode is being used.

Returns

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

OnAfterCellsInBatchDeactivated(ReadOnlyList<WorldCell>, int, int, bool)

IEnumerator<YieldInstruction> OnAfterCellsInBatchDeactivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition)

This method is called right after a batch of cells has been deactivated during the current World Update (deactivation involves transitioning the cells to a non visible state, removing them from any HierarchyOrganizers, and removing them from the internal collection of World Cells so that they are no longer "part" of the Streamable World Grouping they were a part of), for all cells that the World determined need to be removed completely, and also for cells which are being removed as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that.

Each of the OnCells...Removed methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL have its own chunks (game objects) present, and those chunks will be in an DEACTIVATED state. 3) Each World Cell in the batch WILL have cell neighbors, however the state of the neighbors cannot be predicted, since this method may be called before or after other cells that are to be removed have been deactivated. For example, one of its neighbors may be a cell that will be LOD transitioned, so while currently its neighbor is a cell with LOD 1, once all LOD transitions are processed, its new neighbor might be the same cell but of LOD 2. Or in another example, a neighbor may be not present currently, but after adding new cells, may become present. As such, it is not recommended to carry out any neighbor based logic here. Use the OnBeforeAnyCellsDeactivated method instead!

This method is well suited for situations where you need to perform non neigbor related cell specific actions right after a cell is deactivated. However, do note that there is a small delay between the deactivation of a cell and this method being called, since all cells in the batch are deactivated together before this method is called for them. If you need more precise timing, you should set the World Grouping or LOD to not be deactivated automatically, and create a custom Cell Visual Transition Controller and perform that logic there, just after you deactivate each cell.

In addition, you should not use this method for removing World Cells or World Cell related data from an internal collection such as a Dictionary, but instead use the OnBeforeAnyCellsDeactivated for this purpose.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch of cells which have just been deactivated.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being deactivated as part of an LOD transition.

Returns

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

OnAfterGroupingUpdated(World, int, bool)

IEnumerator<YieldInstruction> OnAfterGroupingUpdated(World world, int groupingIndex, bool immediateMode)

This method is called after a World Grouping has been updated, regardless of whether cells have actually been changed on the Grouping (because remember, all Groupings are updated during a Word update, regardless of whether there are changes on that grouping!).

Because this method is not dependent on activated or deactivated cells being present, it does not have any input WorldCell's, unlike the other methods. This also means that the method is only called once per World Grouping Listener per World Grouping update.

The method is also called when the Component Manager is initialized with two frame initialization (for example, if it's Initialize On Awake option is enabled) after the initial starting cell users are added/activated on a World Grouping. Again, this occurs regardless of whether that World Grouping actually has starting cells. In these instances, immediate mode will be true.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
world World

The world whose World Grouping has just been updated.

groupingIndex int

The index of the World Grouping associated with the cells which have been updated. This is useful if using the listener with multiple World Groupings.

immediateMode bool

Whether the method is being called in immediate mode. Immediate mode simply means that the method is not being used as a coroutine. All yield statements are ignored in this mode and the entire code block will execute in a single frame. This mode is used only when the Component Manager in the scene has been Initialized in a non gradual manner, either via its "Initialize on Awake" method being enabled, or you (the user) calling Initialize. In these instances, the World and its World Groupings are initialized and loaded within two frames (Awake and Start) so that the World Chunks appear before the first Update is called.

Typically you will not need to do any special code changes for immediate mode, however in case you do need to, you can query this value to determine if immediate mode is being used.

Returns

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

OnBeforeAnyCellsActivated(ReadOnlyList<WorldCell>, int, int, bool, bool)

IEnumerator<YieldInstruction> OnBeforeAnyCellsActivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition, bool immediateMode)

This method is called before any cells have been added/removed or activated/deactivated during the current World Update, for all cells that the World determines need to be newly added, and also for cells which are being added as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that.

Each of the OnCells...Activated methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL NOT have its own chunks (game objects) present. 3) Each World Cell in the batch WILL NOT have cell neighbors.

This method is ideal for situations where you need to perform non chunk, neigbor related, cell specific actions that are not time sensitive, since the actual activation of the cells will take place some frames after this method is called.

In addition, you should not use this method for adding World Cells or World Cell related data from an internal collection such as a Dictionary, but instead use the OnAfterAllCellsActivated for this purpose.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch cells which will be activated in a short time.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being activated as part of an LOD transition.

immediateMode bool

Whether the method is being called in immediate mode. Immediate mode simply means that the method is not being used as a coroutine. All yield statements are ignored in this mode and the entire code block will execute in a single frame. This mode is used only when the Component Manager in the scene has been Initialized in a non gradual manner, either via its "Initialize on Awake" method being enabled, or you (the user) calling Initialize in the Awake method of some script. In these instances, the World and its World Groupings are initialized and loaded within two frames (Awake and Start) so that the World Chunks appear before the first Update is called.

Typically you will not need to do any special code changes for immediate mode, however in case you do need to, you can query this value to determine if immediate mode is being used.

Returns

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

OnBeforeAnyCellsDeactivated(ReadOnlyList<WorldCell>, int, int, bool)

IEnumerator<YieldInstruction> OnBeforeAnyCellsDeactivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition)

This method is called before any cells have been added/removed or activated/deactivated during the current World Update, for all cells that the World determines need to be removed completely, and also for cells which are being removed as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that. This method is also called before duplicating a world, before the duplication process begins, with the input cells being the old cells which are about to be duplicated.

Each of the OnCells...Deactivated methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL have its own chunks (game objects) present, and those chunks will be in an ACTIVATED state. 3) Each World Cell in the batch WILL have cell neighbors, and the neighbors chunks will be in an ACTIVATED state.

This method is ideal for situations where you need to perform neigbor related cell specific actions that are not time sensitive, since the actual deactivation of the cells will take place some frames after this method is called.

In addition, you SHOULD USE this method for adding World Cells or World Cell related data from an internal collection such as a Dictionary.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch cells which will be deactivated in a short amount of time.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being deactivated as part of an LOD transition.

Returns

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

OnBeforeCellsInBatchActivated(ReadOnlyList<WorldCell>, int, int, bool, bool)

IEnumerator<YieldInstruction> OnBeforeCellsInBatchActivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition, bool immediateMode)

This method is called just before a batch of cells will be activated (activation involves transitioning the cells to a visible state, adding them to any HierarchyOrganizers, and adding them to the internal collection of World Cells so that they become "part" of the Streamable World Grouping they were loaded for), for all cells that the World determines need to be newly added, and also for cells which are added as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that.

Each of the OnCells...Activated methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL have its own chunks (game objects) present, and those chunks will be in an DEACTIVATED state. 3) Each World Cell in the batch WILL NOT have cell neighbors set.

This method is well suited for non neighbor cell specific logic that you want to perform just prior to the activation of a cell, however do note that there is a small delay between this method being called and the activation of a cell, since all cells in a batch are activated together. If you need more precise timing, you should set the World Grouping or LOD to not be activated automatically, and create a custom Cell Visual Transition Controller and perform that logic there, just before activating each cell.

In addition, you should not use this method for adding World Cells or World Cell related data from an internal collection such as a Dictionary, but instead use the OnAfterAllCellsActivated for this purpose.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch of cells which are just about to be activated.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being activated as part of an LOD transition.

immediateMode bool

Whether the method is being called in immediate mode. Immediate mode simply means that the method is not being used as a coroutine. All yield statements are ignored in this mode and the entire code block will execute in a single frame. This mode is used only when the Component Manager in the scene has been Initialized in a non gradual manner, either via its "Initialize on Awake" method being enabled, or you (the user) calling Initialize in the Awake method of some script. In these instances, the World and its World Groupings are initialized and loaded within two frames (Awake and Start) so that the World Chunks appear before the first Update is called.

Typically you will not need to do any special code changes for immediate mode, however in case you do need to, you can query this value to determine if immediate mode is being used.

Returns

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

OnBeforeCellsInBatchDeactivated(ReadOnlyList<WorldCell>, int, int, bool)

IEnumerator<YieldInstruction> OnBeforeCellsInBatchDeactivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition)

This method is called right before a batch of cells is set to be deactivated during the current World Update (deactivation involves transitioning the cells to a non visible state, removing them from any HierarchyOrganizers, and removing them from the internal collection of World Cells so that they are no longer "part" of the Streamable World Grouping they were a part of), for all cells that the World determines need to be removed completely, and also for cells which are being removed as part of an LOD Transition, so long as IgnoreLODTransitions returns false. See the IgnoreLODTransitions property for more details on that.

Each of the OnCells...Removed methods offers different guarantees in regards to the chunks, cell neighbors, and cell neigihbor chunks. You can pick and choose which of these methods you want to utilize based on what you need to do, and what gaurantees your logic depends on. This method offers the following gaurantees.

1) World Cell data is configured correctly. 2) Each World Cell in the batch WILL have its own chunks (game objects) present, and those chunks will be in an ACTIVATED state. 3) Each World Cell in the batch WILL have cell neighbors, however the state of the neighbors cannot be predicted, since this method may be called before or after other cells that are to be removed have been deactivated. For example, one of its neighbors may be a cell that will be LOD transitioned, so while currently its neighbor is a cell with LOD 1, once all LOD transitions are processed, its new neighbor might be the same cell but of LOD 2. Or in another example, a neighbor may be not present currently, but after adding new cells, may become present. As such, it is not recommended to carry out any neighbor based logic here. Use the OnBeforeAnyCellsDeactivated method instead!

This method is well suited for situations where you need to perform non neighbor related cell specific actions right before a cell is deactivated. However, do note that there is a small delay between this method being called and the deactivation of a cell, since all cells in the batch are deactivated together. If you need more precise timing, you should set the World Grouping or LOD to not be deactivated automatically, and create a custom Cell Visual Transition Controller and perform that logic there, just before you deactivate each cell.

In addition, you should not use this method for removing World Cells or World Cell related data from an internal collection such as a Dictionary, but instead use the OnBeforeAnyCellsDeactivated for this purpose.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
cells ReadOnlyList<WorldCell>

The batch cells which are just about to be deactivated.

batchNumber int

The batch number. Will be between 1 and totalBatchesToExpect. You can use the batch number to determine if the batch of cells is the first or last, and perform specific logic based on that. For instance, you may want to perform a method call that should only be performed after all cells have been processed by your World Grouping Listener.

totalBatchesToExpect int

The total batches to expect. Once the batchNumber is equal to this value, you know that you are on the final batch of cells. This method will not be called again after that, except for a new World Update.

cellsArePartOfLODTransition bool

Whether the current batch of cells are part being deactivated as part of an LOD transition.

Returns

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

OnBeforeGroupingUpdated(World, int, bool)

IEnumerator<YieldInstruction> OnBeforeGroupingUpdated(World world, int groupingIndex, bool immediateMode)

This method is called before a World Grouping is updated, regardless of whether cells will actually be changed on the Grouping (because remember, all Groupings are updated during a Word update, regardless of whether there are changes on that grouping!).

Because this method is not dependent on activated or deactivated cells being present, it does not have any input WorldCell's, unlike the other methods. This also means that the method is only called once per World Grouping Listener per World Grouping update.

The method is also called when the Component Manager is initialized with two frame initialization (for example, if it's Initialize On Awake option is enabled) before the initial starting cell users are added/activated on a World Grouping. Again, this occurs regardless of whether that World Grouping actually has starting cells. In these instances, immediate mode will be true.

In order for this method to be called by the World, you only need to override the method in your custom WorldGroupingListener class.

Parameters

Name Type Description
world World

The world whose World Grouping is about to be updated.

groupingIndex int

The index of the World Grouping associated with the cells which have been updated. This is useful if using the listener with multiple World Groupings.

immediateMode bool

Whether the method is being called in immediate mode. Immediate mode simply means that the method is not being used as a coroutine. All yield statements are ignored in this mode and the entire code block will execute in a single frame. This mode is used only when the Component Manager in the scene has been Initialized in a non gradual manner, either via its "Initialize on Awake" method being enabled, or you (the user) calling Initialize. In these instances, the World and its World Groupings are initialized and loaded within two frames (Awake and Start) so that the World Chunks appear before the first Update is called.

Typically you will not need to do any special code changes for immediate mode, however in case you do need to, you can query this value to determine if immediate mode is being used.

Returns

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

OnGroupingLinkEstablished(World, int)

void OnGroupingLinkEstablished(World world, int groupingIndex)

Called by the World when a World Grouping is linked to a World Grouping Listener.

This can be used to verify configuration settings or perform one time setup for the World and Grouping (rather than placing this setup code in the other On... methods which is less efficient).

Parameters

Name Type Description
world World

The World the Grouping belongs to.

groupingIndex int

The index of the grouping that was linked to the listener.

OnGroupingLinkRemoved(World, int)

void OnGroupingLinkRemoved(World world, int groupingIndex)

Called by the World when a World Grouping link to a World Grouping Listener is removed. This occurs when the World Grouping Listener is removed using the World's RemoveWorldGroupingListener method or if the World is destroyed.

This can be used to cleanup data that was created in the OnGroupingLinkEstablished method.

Parameters

Name Type Description
world World

The World the Grouping belongs to.

groupingIndex int

The index of the grouping which the link was removed for.

PrecomputeUseWithLODValues()

void PrecomputeUseWithLODValues()

Precomputes data used by the UseWithLOD method.

If you derive from WorldGroupingListener, this method will already have been implemented. To calculate additional data (for if you override UseWithLOD), use the PrecomputeUseWithLODValues_Extended method.

Note that this method is called once by each World Grouping using the Listener, so it may be called multiple times in some cases. Usually, you should have some sort of safeguard in place to ensure the precomputation logic only runs once.

UseWithLOD(int)

bool UseWithLOD(int LOD)

This method is queried before any of the methods that use cells are called, to determine if that method should be invoked for the current group of cells, given the active LOD of those cells (remember, all cells in a batch are always gauranteed to have the same active LOD).

When deriving from WorldGroupingListener this method is virtually implemented to return a value based on the LOD Filter configured in the Listener's inspector. You can override it to ignore the LOD Filter in favor of a custom system for determining per LOD use.

The value returned by this method is not cached. Each time one of the methods would be called, the method is called.

This gives you a great deal of freedom, as you can adjust which LODs the Listener is being used with on the fly at runtime.

However, if you know that the LODs that the Listener is being used will not change at runtime, and the computation used to determine if an LOD should be used by the Listener is expensive, you should cache the computed value for each LOD and use that when the method is called. Typically, should do this in Awake or AwakeExtended, so that the cached values can be used as early as Start.

The value is applied universally across all method calls that use cells (OnBeforeAnyCellsDeactivated, OnBeforeCellsInBatchDeactivated, etc.). If you use more than 1 of these methods and need to use different criteria for determining LOD use for each one, you should return true when UseWithLOD is called and instead filter each LOD within the actual methods that process the cells.

Parameters

Name Type Description
LOD int

The active LOD of the World Cells that one of the methods (OnBeforeAnyCellsDeactivated, OnBeforeCellsInBatchDeactivated, etc.) is about to be invoked for.

This value is 1 based, such that the first (highest quality) LOD is 1.

Returns

type
Return true if you want the method (OnBeforeAnyCellsDeactivated, OnBeforeCellsInBatchDeactivated, etc.) to be called for the World Cells of the LOD, or false otherwise.

Exceptions

Type Condition
Description