The Distance Based Pooling Chunk Manager is a special implementation of the Pooling Chunk Manager that measures the distance between the Cell that Players are in and the Streamable Grid Cells associated with Asset Chunk Sets stored in the internal pool in order to make pooling decisions. Basically, a World Cell's Asset Chunk Set is pooled so long as that World Cell's Streamable Grid Cell is within a certain distance to at least one Cell that a Player is currently in. Once the distance is greater (for all Player Cells), the Asset Chunk Set is removed from the pool and sent to the Chunk Streamer so that the chunks can be removed/unloaded from the scene.
The beauty of this design is that only Asset Chunks which have a reasonable chance to be reused soon are kept around.
You can add this component by selecting a game object and then selecting from the Top Menu Bar:
Component -> Deep Space Labs -> -> SAM -> Chunk Managers -> Distance Pooling Chunk Manager
or by selecting a game object and using the Add Component menu via its inspector:
Component -> Deep Space Labs -> -> SAM -> Chunk Managers -> Distance Pooling Chunk Manager
This Pooler works by automatically listening in to the Cell Player Is In Changed event of any Active Grid synced to a World belonging to one of the Pooler's LOD Group users. As such, Active Grids are required in order to use this Pooler. If not using Active Grids, you will need to create a custom Pooling Chunk Manager.
In addition, any Active Grids whose Player's you wish tracked by this Pooler need to have their Enable Cell Player Is In Changed Events option enabled. Of course, only the Active Grid Grouping matching the World Grouping of LOD Groups using this pooler need to have this option enabled.
The pooler can be used with multiple Players/Active Grids per LOD Group user. When multiple Players are present, the distance from each Player's Cell to the Streamable Grid Cell associated with each Asset Chunk Set in the pool is computed, and as long as the Asset Chunk Set is within the valid distance to at least one of the Players, it is kept in the pool.
A Cell is made up of three coordinates known as the Row, Column, and Layer. The distance between two Cells is calculated using the distance between each coordinate from each Cell. Each coordinate distance calculation function is dependent on whether the Axis associated with that coordinate (Rows for Row, Columns for Column, Layers for Layer) is setup to Repeat on the World.
When an Axis is set to not repeat, the formula is very simple: Math.Abs(EndlessGridCellOfPlayer.Coordinate - StreamableGridCellOfAssetChunkSet.Coordinate).
When an Axis is set to repeat, the formula calculates two possible values and returns the minimum of the two. These two values are:
Value 1 = Math.Abs(StreamableGridCellOfPlayer.Coordinate - StreamableGridCellOfAssetChunkSet.Coordinate)
Value 2 = Total Indexes On Axis - Math.Max(StreamableGridCellOfPlayer.Coordinate, StreamableGridCellOfAssetChunkSet.Coordinate) + Math.Min(StreamableGridCellOfPlayer.Coordinate, StreamableGridCellOfAssetChunkSet.Coordinate)
Note, the actual formulas are more efficient than described here.
Value 1 represents the straight line distance between the two Coordinates, while Value 2 is the distance from one Coordinate to the other in the opposite direction with the line wrapping around.
For example, imagine a Streamable Grid with 4 Rows. If the Player is in Row 1 and the Asset Chunk Set is associated with Row 4, we can say that Row 1 is 3 Rows away from Row 4 (Value 1). However, if the Streamable Grid is used with a World that uses Repeating Rows, the Row Axis starts repeating after Row 4, which means Row 1 will sit just 1 Row away from Row 4 (Value 2).
--Special Note--
When the LOD Group's Streamable Grid only uses two axes, the Layer value of all Cells will always be 1 and the Layer Coordinate Distance will always be 0. Because of this, we do not even bother calculating the Layer Coordinate distance and do not factor it in when computing the total Cell's distance.
Once all coordinate distances that are needed are calculated, the Distance Check Method determines how the coordinate distances are used to calculate the final Cell distances.
1) Chebyshev - The distance is the largest of the calculated coordinate distances.
2) Manhattan - The distance is the sum of the calculated coordinate distances.
The distance between Cells is always intended to represent the minimum number of cells you would need to traverse to get from one Cell to the other. The difference between the two methods is that Chebyshev is intended to allow for diagonal movement between Cells, while Manhattan does not. In order to choose the best method, it's important to take examine how Player Movement works in your game, as well as the makeup of the Cells using the Distance Pooling Chunk Manager. If it is very easy (i.e, it doesn't take a lot of time) for the Player to move between one Cell and a neighboring diagonal Cell, you should use the Chebyshev Distance Method. This will result in shorter distances being calculated which will cause more Asset Chunk Sets to fit the criteria needed to stay in the pool.
If the Player cannot easily move from one Cell into a neighboring diagonal Cell, the Manhattan method will likely result in more efficient pooling, as it will reduce the number of uneeded Asset Chunk Sets in the pool.
Once a Streamable Grid Cell that has chunk sets stored in the pool is determined to be out of distance from all Players, the cell is added to a special collection that marks the chunk sets for removal. However, this removal is not performed automatically. Instead, the Distance Pooling Chunk Manager checks if out of distance cells exists every X seconds (set in the inspector). If the Cells that the Players are in changes during this time, it is possible for these out of distance cells to fall back within the safe distance, in which case they are unmarked for removal.