This Chunk Streamer can be used to load and unload Addressable Scene Assets. It is incapable of single or double frame loading, as the method used to load the addressable scene assets (Addressables.LoadSceneAsync) cannot be used in this manner. When unloading Asset Chunks, the chunks are returned to their original scene (if they were moved upon being loaded), and that scene is unloaded via Addressables.UnloadSceneAsync for performant asset unloading.
--Special Note--
Addressable related content requires the Addressables package (any version) to be installed in your project, otherwise you will not be able to see/add addressable related components. Once added, you may need to restart Unity in order for this content to become available.
You can add this component manually by selecting a game object and then selecting from the Top Menu Bar:
Component -> Deep Space Labs -> -> SAM -> Chunk Streamers -> Addressable Scene Chunk Streamer
or by selecting a game object and using the Add Component menu via its inspector:
Component -> Deep Space Labs -> -> SAM -> Chunk Streamers -> Addressable Scene Chunk Streamer
Hover over the setting Label to see information about this setting.
You can enable the Prepend Extra User Data setting to tell the Streamer to try to prepend LOD Group specific string data to the final Asset Chunk Names for each LOD Group, in order to form complete and valid Addresses for each Addressable Scene Asset. The Prepend Data Key entered is used to look in the Extra Data Store of each LOD Group for an entry that uses the Key. If one is found, the value of the entry is prepended to all Asset Chunk Names for the LOD Group.
Prepended user data can be used to add folder paths or other literal strings in instances where you Asset Addresses include folder paths or additional characters before the Asset Names (folder paths are automatically added when dragging/dropping assets into an Addressable Group). You can hover over the setting Label to see more detail information.
Note that when using the Default Asset Creator's Make Scenes Addressable option, you have the option to set an Address Prepend String. Doing this is only necessary if you have multiple addressable assets using the same name. In this case, the prepended string can be the folder path where the assets are stored or some other identifier. Whatever string you use, you must also add an entry to the LOD Group's Extra Data section using the Addressable Path key and the same string as the value.
If you know that all of your Addressable Assets will be unique, you can skip using an Address Prepend String and adding the Extra Data entry to the LOD Group. Even if that LOD Group is used with an Addressable Scene Chunk Streamer that is set to Prepend Extra User Data, the Streamer will still be able to load the Asset Chunks, as it will simply prepend nothing when it does not find an Extra Data entry with the Key specified.
Interested In Extra User Data?
You can enable the Append Extra User Data setting to tell the Streamer to try to append LOD Group specific string data to the final Asset Chunk Names for each LOD Group, in order to form complete and valid Addresses for each Addressable Scene Asset. The Append Data Key entered is used to look in the Extra Data Store of each LOD Group for an entry that uses the Key. If one is found, the value of the entry is appended to all Asset Chunk Names for the LOD Group.
Appended user data can be used to add extra string data after the Asset Name. Typically this will just be the .unity file extension, however if you know that all Addressable Asset Chunks will utilize this extension, it can be more memory efficient to enable the Append File Extension setting instead, as this will reduce the amount of extra user data on Streamable Grid assets.
If, on the other hand, only a limited number of Asset Chunks use the extension in their Addresses, you will need to use appended extra user data. When doing so, include the extension as extra user data on the Streamable Grid associated with the Assets, using the same key as found in the Append Data Key field.
When the Streamer finds that an LOD Group has the user data, it appends it to the Asset Chunk name. If it finds that an LOD Group does not have user data, it appends nothing, so Asset Chunks that do not need the extension work just as well as chunks that do need it.
Note that using this method, you can also append unique string data for each LOD Group.
Interested In Extra User Data?
If all of your Addressable Scene Assets that the Streamer will load will contain the .unity file extension in their Addresses, you can enable this option and the .unity extension will be added to the end of each Asset Chunks name in order to form the Address used to load each asset.
If some Asset Chunks have the extension but others don't, you will need to disable this option and instead use the Append Extra User Data options described above.
Since working with internet based loading can be consist of packet loss and connection issues, the Addressable Scene Chunk Streamer contains some rudimentary error handling routines in cases where load operations fail. These routines proceed in the following order:
1) Try to re-download the failed Scene Asset X times, where X = Max Load Attempts - 1 (i.e., a value of 1 means no re-downloads will be attempted).
2) If those re-downloads fail, attempt to fix whatever issue is causing the failed downloads using a provided Error Repairer. Note, error repairing is an advanced technique and you must design the repairer yourself.
3) If the repairer fails (or a repairer is not provided) and Use Alt LOD Fail-Safe is enabled, the Streamer identifies the Streamable Grid the failed Chunk belongs to, then identifies the lowest quality LOD for that Grid and (if it is different than the failed Chunks LOD) attempts to load the equivalent Asset Chunk for that LOD.
4) If the Alt LOD Fail-Safe cannot or should not be loaded, and Use Placeholder Fail-Safe is enabled, a placeholder asset will be loaded. The placeholder asset should be placed on the users' computer so that loading it cannot fail.
5) If all of the previous steps fail to load an asset for the given Asset Chunk, a MissingAssetException is thrown by the Streamer.
Want To Know More About Custom Error Repairers?
If enabled, the Print Error To Console setting will cause an error to be printed to the console log any time an asset load fails. This includes any attempts to load the Original Asset, attempts to load an Alt LOD Fail-Safe Asset, or attempts to load a Placeholder Fail-Safe Asset.
The Exception Handler field allows you to provide a custom exception handler for handling different exceptions that may be thrown by Unity's Addressable Loading Systems. If not provided, the default behavior is to only catch and log Invalid Key Exceptions. If you would like to catch other exceptions and/or deal with them in a more advanced way than simply logging the exceptions, you can create a custom Exception Handler class (note, this class will not catch exceptions thrown by the Streamer itself!).
Want To Know More About Custom Exception Handlers?
In order for the Streamable Assets Manager to make use of Scene Assets, it's necessary for the Scenes to be in a specific format. This format consist of the following two criteria:
1) The Scene must contain exactly 1 root game object. This game object can have as many children, grandchildren, etc., as you want, but it must be the only root game object in the scene.
2) The root game object must be in a game object state (activated or deactivated) that matches the Root State setting for the LOD Group using the scene (found on the Streamable Grid/LOD Group/Primary Settings tab). Generally speaking, it is recommended to us a Deactivated state for the scene root objects, which ensures the objects are not seen by the player before the Asset Chunk is able to be positioned correctly (see the Root State sub-section from the LOD Group Settings Sectino of the Streamable Grids Chapter for more info).
The Invalid Scene Format Message Level setting controls how the Streamer should respond to Scene Assets that are not formatted in the manner described above. The options include displaying a warning in the Console Log (which the user will not see), an Error (which the user will likely see), or not displaying a message.
Hover over the settings' Labels to see information about these setting.