public abstract class WorldGroupingListener : MonoBehaviour, IWorldGroupingListener
Provides a base implementation for components that wish to implement the
IWorldGroupingListener interface.
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 Asset 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.
The most useful situation I can think of for doing this when trying to add integration
for 3rd party assets.
If a method you want to use does not need to utilize multiple frames, override the
method and place the
code you want executed as normal, then return
SimpleYieldBreakEquivalentEnumerator.Instance. This will ensure no garbage is generated
when the method is called.
| Name | Type | Description |
|---|---|---|
| CallOnAfterAllCellsActivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnAfterAllCellsActivated method. Please note, when deriving from 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. |
| CallOnAfterAllCellsDeactivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnAfterAllCellsDeactivated method. Please note, when deriving from 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. |
| CallOnAfterCellsInBatchActivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnAfterCellsInBatchActivated method. Please note, when deriving from 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. |
| CallOnAfterCellsInBatchDeactivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnAfterCellsInBatchDeactivated method. Please note, when deriving from 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. |
| CallOnAfterGroupingUpdated | bool |
Returns a value indicating whether the World Grouping this WorldGroupingListener is
linked to should call the
OnAfterGroupingUpdated method. Please note, it is not necessary to
worry about this property. All you need to do is override the OnAfterGroupingUpdated
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.
|
| CallOnBeforeAnyCellsActivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnBeforeAnyCellsActivated method. Please note, when deriving from 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. |
| CallOnBeforeAnyCellsDeactivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnBeforeAnyCellsDeactivated method. Please note, when deriving from 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. |
| CallOnBeforeCellsInBatchActivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnBeforeCellsInBatchActivated method. Please note, when deriving from 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. |
| CallOnBeforeCellsInBatchDeactivated | bool |
Returns a value indicating whether the World Grouping this World Grouping Listener is linked to should call the OnBeforeCellsInBatchDeactivated method. Please note, when deriving from 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. |
| CallOnBeforeGroupingUpdated | bool |
Returns a value indicating whether the World Grouping this WorldGroupingListener is
linked to should call the
OnBeforeGroupingUpdated method. Please note, it is not necessary to
worry about this property. All you need to do is override the OnBeforeGroupingUpdated
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.
|
| 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 Asset 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.
|
public void DetermineMethodCalls()
Computes the values of the the Call... properties (CallOnBeforeGroupingUpdated, CallOnBeforeAnyCellsDeactivated, etc.) based on whether each method corresponding to each property has been overriden in your derived class.
public virtual 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 activated,
and also for cells which were activated 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 Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present, and those
Asset Chunks will be in an ACTIVATED state.
3) Each World Cell in the batch WILL have cell neighbors set, and the Asset 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 Grouping Update).
In addition, you SHOULD USE this method for adding World Cells or World Cell related
data to 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.
| 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 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.
|
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual 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 deactivated completely,
and also for cells which were deactivated 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 Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present.
3) Each World Cell in the batch WILL NOT have cell neighbors assigned.
Based on the gaurantees listed, hopefully you can see that this method is the most
limited of the OnCells...Deactivated methods. No
Asset 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 order for this method to be called by the World, you only need to override the
method in your custom
WorldGroupingListener class.
| 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 being deactivated as part of an LOD transition. |
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual 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 activated,
and also for cells which were activated 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 Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present, and those
Asset Chunks will be in an ACTIVATED state.
3) Each World Cell in the batch WILL have cell neighbors assigned, and any non LOD
related data of the neighbors can be considered
accurate. However the state of the neighbor Asset 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 situations where you need to perform non neighbor related
cell specific actions right after a Cell is activated.
Do note, however, that there will likely be a delay between the actual activation
of the batch of Cell's Asset Chunks and this method being called. I
f you need very precise timing, you should disable Auto Activate Chunks When Adding Cells and create a custom
Cell Visual Transition Controller
where you perform the necessary logic just after you activate and make the Cell's
Asset Chunks Visible.
In order for this method to be called by the World, you only need to override the
method in your custom
WorldGroupingListener class.
| 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 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.
|
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual 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 deactivated completely, and also
for cells which are being
deactivated 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
Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present, and those
Asset Chunks will be in an DEACTIVATED state.
3) Each World Cell in the batch WILL have cell neighbors assigned, 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 will likely be a small delay between this method being
called and the actual deactivation of the batch of Cell's Asset Chunks.
If you need very precise timing, you should disable Auto Deactivate Chunks When Removing Cells and create a custom
Cell Visual Transition Controller
where you perform the necessary logic just before you make the Cell's Asset Chunks
Invisible and deactivate them.
In order for this method to be called by the World, you only need to override the
method in your custom
WorldGroupingListener class.
| 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 being deactivated as part of an LOD transition. |
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual 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.
| 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.
|
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual IEnumerator<YieldInstruction> OnBeforeAnyCellsActivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition, bool immediateMode)
This method is called before any cells have been activated during the current World
Grouping Update,
for all cells that the World determines need to be newly activated, and also for cells
which are being
activated 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 Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present.
3) Each World Cell in the batch WILL NOT have cell neighbors assigned.
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 order for this method to be called by the World, you only need to override the
method in your custom
WorldGroupingListener class.
| Name | Type | Description |
|---|---|---|
| cells | ReadOnlyList<WorldCell> |
The batch of 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 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.
|
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual IEnumerator<YieldInstruction> OnBeforeAnyCellsDeactivated(ReadOnlyList<WorldCell> cells, int batchNumber, int totalBatchesToExpect, bool cellsArePartOfLODTransition)
This method is called before any cells have been deactivated during the current World
Grouping Update,
for all cells that the World determines need to be removed/deactivated completely,
and also for cells which are being
removed/deactivated 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 Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present, and those
Asset Chunks will be in an ACTIVATED state.
3) Each World Cell in the batch WILL have cell neighbors assigned, and the neighbors
Asset 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 removing 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.
| Name | Type | Description |
|---|---|---|
| cells | ReadOnlyList<WorldCell> |
The batch of 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 being deactivated as part of an LOD transition. |
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual 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 activated,
and also for cells which are activated 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 Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present, and those
Asset Chunks will be in a DEACTIVATED state.
3) Each World Cell in the batch WILL NOT have cell neighbors assigned.
This method is well suited for situations where you need to perform non neighbor related
cell specific actions right before a Cell is activated. Do note,
however, that there will likely be a delay between this method being called and the
actual activation of the batch of Cell's Asset Chunks. If you need very
precise timing, you should disable Auto Activate Chunks When Adding Cells and create a custom
Cell Visual Transition Controller
where you perform the necessary logic just before you activate and make the Cell's
Asset Chunks Visible.
In order for this method to be called by the World, you only need to override the
method in your custom
WorldGroupingListener class.
| 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 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.
|
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual 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 deactivated completely, and also
for cells which are being
deactivated 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
Asset Chunks, cell neighbors, and cell
neigihbor Asset 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 Asset Chunks present, and those
Asset Chunks will be in an ACTIVATED state.
3) Each World Cell in the batch WILL have cell neighbors assigned, 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!
Situations where you need to perform non neighbor related cell specific actions right
before a Cell is deactivated. However, do note that there
will likely be a small delay between this method being called and the actual deactivation
of the batch of Cell's Asset Chunks. If you need very
precise timing, you should disable Auto Deactivate Chunks When Removing Cells and
create a custom
Cell Visual Transition Controller where you
perform the necessary logic just before you make the Cell's Asset Chunks Invisible.
In order for this method to be called by the World, you only need to override the
method in your custom
WorldGroupingListener class.
| Name | Type | Description |
|---|---|---|
| cells | ReadOnlyList<WorldCell> |
The batch of 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 being deactivated as part of an LOD transition. |
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
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.
| Name | Type | Description |
|---|---|---|
| world | World |
The world whose World Grouping is about to be updated. |
| groupingIndex | int |
The index of the World Grouping that will be 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.
|
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public virtual 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.
By default the method does nothing; override to implement logic that only needs to
run once for the Grouping.
| Name | Type | Description |
|---|---|---|
| world | World |
The World the Grouping belongs to. |
| groupingIndex | int |
The index of the grouping that was linked to the listener. |
public virtual 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.
By default the method does nothing; override to implement logic that only needs to
run once for the Grouping.
| Name | Type | Description |
|---|---|---|
| world | World |
The World the Grouping belongs to. |
| groupingIndex | int |
The index of the grouping which the link was removed for. |
public void PrecomputeUseWithLODValues()
Precomputes data used by the
UseWithLOD method, based on the LOD Filter.
You cannot override this method, as the WorldGroupingListener requires that the LOD
Filter based criteria be setup.
However, if you have overriden the UseWithLOD method and need to precompute other
data unrelated to the LOD Filter, you can
override the
PrecomputeUseWithLODValues_Extended
method instead, which is called automatically by this method.
protected virtual void PrecomputeUseWithLODValues_Extended()
Can be overriden to precompute additional data for use with a custom implementation
of the
UseWithLOD method.
Remeber that the LOD Filter based criteria is always configured and can be queried
using
base.UseWithLOD, even if you override the UseWithLOD method. This allows you to add
additional criteria
on top of the existing LOD Filter based criteria.
This method is gauranteed to only be called once, so you do not need to provide safeguards
to ensure your
logic only runs once.
protected virtual void Start()
This is implemented solely so that the Listener will have the enabled toggle exposed
in the inspector.
You can override this method if you need to run code in Start.
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).
It 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, or
to add additional criteria on top of the LOD Filter (in which case, you can use base.UseWithLOD
to get the default value the method would have returned if only using the LOD Filter).
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 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.
| 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.
|
type
Return true if you want the method (OnBeforeAnyCellsDeactivated, OnBeforeCellsInBatchDeactivated,
etc.) to be called for the World Cells of the LOD, or false otherwise.
| Type | Condition |
|---|---|
| Description |