If using Addressable Assets (especially via a remote server), it is probable that you will face connection issues or other problems that cause Addressable Asset download operations to fail. Fortunately, the default Addressable Chunk Streamers include a mechanism that allows you to add custom error handling solutions. This mechanism gives you a chance to fix whatever problems caused the failed download so that they can automatically be re-attempted.
Note that you will need to write the error handling code that fixes the issues yourself; projects are too diverse to create a solution that works for everyone!
In order to add error handling to your project, you will need to create a new MonoBehaviour script that derives from the AddressableErrorRepairer class. You will need to add a using DeepSpaceLabs.SAM statement to access this class.
Do note that this class is only available when an Addressables Package is present in your Project.
Once you set your custom Error Repairer to inherit from AddressableErrorRepairer, you will see a red error line on your custom class name. Right click the class name and choose Show potential fixes -> Implement abstract class. This will automatically add the AttemptRepair method and other using statements needed by the method.
AttemptRepair is called automatically by any Chunk Streamer that derives from the base Addressable Base Chunk Streamer class after it has tried and failed to load one or more Assets a set number of times (set by you, the developer, via the inspector of the Chunk Streamer). The method takes in a list of AsyncOperationHandle objects associated with the failed downloads (one for each Asset), as well as an empty boolean list.
The boolean list should be filled by your method in order to tell the calling Chunk Streamer which failed operations were fixed, and which were not. As such, for each failed handle in the input list, you should add one boolean value. The order of the bool items must match the order of the failed handles.
If the issue related to one of the failed operation handles was able to fixed, you must add true to the list, which tells the Chunk Streamer to re-attempt downloading the Asset one more time.
In order to know why the operation failed (the download failed), you can use the static AddressableErrorRepairer.GetDownloadError method, passing in each failed AsyncOperationHandle. The error message should be one of the following, however if the error message is unavailable, the returned string will either be null or empty, so you should account for this.
Request aborted
Unable to write data
Malformed URL
Out of memory
No Internet Connection
Encountered invalid redirect (missing Location header?)
Cannot modify request at this time
Unsupported Protocol
Destination host has an erroneous SSL certificate
Unable to load SSL Cipher for verification
SSL CA certificate error
Unrecognized content-encoding
Request already transmitted
Invalid HTTP Method
Header name contains invalid characters
Header value contains invalid characters
Cannot override system-specified headers
Backend Initialization Error
Cannot resolve proxy
Cannot resolve destination host
Cannot connect to destination host
Access denied
Generic/unknown HTTP error
Unable to read data
Request timeout
Error during HTTP POST transmission
Unable to complete SSL connection
Redirect limit exceeded
Received no data in response
Destination host does not support SSL
Failed to transmit data
Failed to receive data
Login failed
SSL shutdown failed
Redirect limit is invalid
Not implemented
Data Processing Error, see Download Handler error
Unknown Error
The GetDownloadError method is provided by Unity and we cannot aid you in understanding the error messages it returns or how to fix them. We also cannot stop Unity from changing/renaming the download errors down the road, so you should investigate the Unity Addressables Documentation to ensure these error messages are still valid.
However, to aid you in writing an error repairer, the AddressableErrorRepairer.cs file contains a sample commented-out AttemptRepair method which has a switch statement that is configured with cases for every possible error message. If you do not know how to handle a particular error, or simply do not want to handle it, simply remove the case for that error. When the error pops up, the default case will trigger which will simply add false to errorsRepaired so that the error is marked as not repaired for the operation.
You can find AddressableErrorRepairer.cs in the Deep Space Labs/SAM/Scripts/AddressableDependent/RuntimeCode folder.
In some cases it may not be possible to repair errors. That's okay! The default Addressable Chunk Streamers have included support for loading fail-safe asset chunks (which can either be the lowest quality LOD Assets for a particular World Grouping or a Placeholder asset) whenever an Asset cannot be loaded for any reason. Please take a look at the Fail Safe Asset Chunks Section for more info!
Once you have created a custom Error Repairer and added it to a game object, you can assign it to the Addressable Chunk Streamer via the Error Repairer field in the inspector.