World Cells are the scene manifestations of Streamable Grid Cells. They have a physical location and Bounds within scene space and store the references to the Asset Chunks associated with the Streamable Grid Cell, as a well as a bunch of other information..
Every World Cell represents a specific Cell on a Streamable Grid. When using Endless repeating Axes, it is necessary to utilize a separate Cell Index in order to differentiate between multiple World Cells that are using the same Streamable Grid Cell Index.
The Endless Grid Cell is used for this purpose and is the primary means of identifying World Cells, as every World Cell will have a unique Endless Grid Cell Index.
Do note, if not using Endless Axes, the Endless Grid Cell value will always be equal to the Streamable Grid Cell value for any given World Cell..
You can access this value from a World Cell using the CellOnEndlessGrid property. Likewise, the Streamable Grid Cell can be accessed using the CellOnStreamableGrid property.
The World determines which World Cells need to be loaded by processing User Additions and Removals for specific Endless Grid Cells. A User in this sense is simply any entity that requires an Endless Grid Cell to be loaded. These Users may come from three sources:
1) World Regions which are configured via the World Designer Tool and loaded at runtime, either manually or using the World's Starting World Regions settings.
2 Active Grids which track Player objects and automatically add/remove Users from Worlds in response to the Players' positions changing.
3) Custom Scripts you setup to call the World's AddCellUsers and RemoveCellUsers methods.
Add and Remove User requests must specify a World Grouping and LOD in addition to the Endless Grid Cell. An Endless Grid Cell for a World Grouping may have multiple add/remove requests sent in at the same time, for the same LOD or different LODs. All requests are processed and tallied in order to produce a Change In Users count, for each LOD and Endless Grid Cell. This count is then used in the following ways:
1) If no World Cell is currently loaded for a given Endless Grid Cell, one is loaded in association with the highest quality LOD that has users.
2) If there are changes in the number of users for an Endless Grid Cell that already has a World Cell loaded, the changes are added to the current count of users for that Cell (tracked via the World Cell). If the World Cell's user count equals 0 for each LOD, it is unloaded. If the World Cell has gained users for a higher quality LOD, it transitions to that LOD. If it no longer has users for its current LOD but does have users for a lower quality LOD, it transitions to the highest quality LOD that still has users.
Note that the World will always try to load the highest quality LOD for a given Endless Grid Cell, so long as at least one user exist for it. This means that even if a Cell has 5 users for LOD 2 and only 1 user for LOD 1, LOD 1 will still be loaded.
We attach Asset Chunks to World Cells in order to form a link between them and store the Asset Chunks within the World Cells, and detach them from World Cells in order to break that link and remove them from the World Cells storage.
Attachment and Detachment is performed within Chunk Manager and Chunk Streamer components. If using one of the default versions of these components, you shouldn't need to worry about attachment and detachment, however if using a custom Chunk Manager or Chunk Streamer, you should continue reading.
In order to Attach an Asset Chunk to a World Cell, you will need to use the AttachChunkToCell method. This method requires you to pass in a value indicating whether the Asset Chunk has already been positioned correctly (which will help avoid an unecessary position set operation later), as well as the index of the Asset Chunk within the World Cell's Chunk Set (which should be a value between 1 and WorldCell.NumChunks). Note that this value will always be 1 if not using Multi-Chunking.
To detach an Asset Chunk from a World Cell, use the DetachChunksFromCell method. This will disassociate the World Cell from the Chunk as well as return a copy of the Chunks so that you can process it and/or remove or store it. This method also requires you to pass in the Index of the Asset Chunk within the World Cell's Chunk Set.
Once an Asset Chunk has been attached to a World Cell, you can access it at any time using the GetChunkBelongingToCell method, which takes a chunk index and returns the Asset Chunk at that index. The index must be a value between 1 and WorldCell.NumChunks.
This method returns a base System.object, so you will likely need to cast the object to a more specific type (such as GameObject) in order to make use of it properly.
Every World Cell holds a reference to its neighboring World Cells. These neighbors always include the West, North, East, and South neighbors (if they exist), and additionally include Top and Bottom neighbors when the World Cell is associated with a 3D Streamable Grid.
Do note, however, that depending on when in the life-cycle of the World Cell you access its neighbors, the neighbors may not exist or be set yet. You should refer to the Custom Grouping Listeners Section within the World Grouping Listeners Chapter for details on when neighbors are set, within each Sub-Section detailing the methods that can be overridden.
When an LOD Group that uses Unity Terrain as its Asset Chunk Type is used, the Streamable Assets Manager creates a special World Cell called WorldCellWithTerrain. This World Cell is derived from the WorldCell class and so contains all of the same functionality as a regular World Cell, however it also contains a reference to the Terrain component of the Asset Chunk, as well as some Terrain related methods.
When an LOD Group that uses Unity Terrain as its Asset Chunk Type is used, the Streamable Assets Manager creates a special World Cell called WorldCellWithTerrain. This World Cell is derived from the WorldCell class and so contains all of the same functionality as a regular World Cell, however it also contains a reference to the Terrain component of the Asset Chunk, as well as some Terrain related methods.
Note, the terrain related methods should generally not be accessed, as they are already called automatically by SAM. Only call these methods if you are using some sort of alternative terrain neighboring solution and you know what you are doing!