Extra Data is a store of data that can hold multiple key/value data pairs. Primarily, it is used in conjunction with Chunk Streamers to hold information needed to load the Asset Chunks associated with the Streamable Grid, however you can make use of it to store any data you wish.
Internally, the store of data is a simple dictionary that uses both a string Key and string Value, however you are free to story any type of data in the Value field so long as it can be successfully converted to/from a string (such as an int, float, etc).
LOD Extra Data is data that is stored only for a particular LOD. Using it, you can store different data for each LOD using the same key. When outside sources seek to get the data related to a specific key, it will receive different data for each LOD (assuming each LOD stores data for that key).
Global Extra Data is stored directly on the Streamable Grid and is not associated with a particular LOD, however it can be potentially used with all LOD's.
It's possible to store data under the same key, both in the Global Extra Data store and the LOD Extra Data store.
When an outside source seeks to retrieve data, it can do so in one of two ways:
1) By attempting to retrieve the data directly from the Streamable Grid's Global Extra Data. This method will bypass any data that might be stored in the LOD's Extra Data, even if they are storing data with the same key passed in by the outside source.
2) By attempting to retrieve the data via a specific LOD. This method is preferred as it will first look for the data (associated with the passed in key) in the LOD's Extra Data, and if it cannot find data for the key there, it will then look in the Global Extra Data.
Strategy 2 allows you to store data globally for all LODs, then provide LOD specific overrides by storing data using the same key in the LOD's Extra Data.
Storing Data is very straightforward; you simply need to enter a Key and a Value.
The Key Type field contains some common Keys that are used by the Default Chunk Streamer classes, however you can enter a custom key by choosing Custom for the Key Type and then entering the key in the field that appears.
Once you have entered text in the Data Field, simply press the Add Entry button to add the data to the store.
Next to the Data field is a Copy Folder button (hidden if the Key Type is set to File Extension). This button requires you to first select a folder in your Project Hierarchy, and performs some checks to ensure the selected folder is valid. The final Data string that is produced is set according to the Key Type, to match the format expected by Chunk Streamers that utilize that Key.
For example, the Resources Sub Folder Path key is intended to be used with Chunk Streamers that load Prefabs from the Resources Folder, in cases where your Prefabs are stored in a Sub Folder. If the folder selected is the Resources folder, or if it is not a sub folder within the Resources folder, an error is shown. If it is valid, the sub folder path is placed in the Data field.
To remove existing data, simply click the Remove Entry button that is in line with the Entry you wish to remove.
You can also modify the key or data of an entry after it has been added, just keep in mind that each entry must use a unique key.
There is no limit to the number of entries you can add.
--Upgrade Note--
Global & LOD Extra Data are a new feature, so your existing World Grids will not have these options!
In some cases, you may wish to configure the Extra Data at runtime based on different criteria, for instance based on the device that your game is being executed on. In these cases, you can absolutely set the Extra Data at runtime, however keep in mind that it is generally recommended to set this data before SAM has been initialized.
The reason for this is that the built in classes that make use of the extra data generally retrieve the data only once (when SAM is initialized). They then cache that data and reuse it, which is more performant than continuously retrieving the data and parsing it to the correct value type.
In order to set the extra data, you will need a reference to the Streamable Grid whose data you want to change. If you have a reference to your World, or can retrieve it via coding, you can use the World's GetStreamableGridOfGrouping_PreInitSafe method in order to retrieve the Streamable Grid for a specific World Grouping. Otherwise, you can create a public field on a script and drag and drop the Streamable Grid asset you wish to modify onto the field.
Once you have the Streamable Grid reference, you can update and entry or add a new entry to its Global Extra Data by using the SetGlobalExtraData_PreInitSafe method.
If instead you want to add an entry to a specific LOD Group's Extra Data, you can update and entry or add a new entry to it by first retrieving the LOD Group's data via the GetLODDetails method, then using the SetExtraData_PreInitSafe method.