Class AddressableSettings

Configures the behavior of Addressables operations performed by ScyllaAddressables. Controls timeout durations, retry attempts, diagnostic warnings, asset tracking, and failure-cleanup policy.

Inheritance
object
AddressableSettings
Inherited Members
Namespace: Scylla.Core.Util.Addressables
Assembly: ScyllaCore.dll
Syntax
public sealed class AddressableSettings
Remarks

Four pre-built preset instances are available as static properties for the most common scenarios:

  • Default - 30-second timeout, no retries. Suitable for most local Addressables assets.
  • LongTimeout - 120-second timeout, no retries. Suitable for large remote bundles.
  • WithRetries - 30-second timeout, 3 retries with 1-second delay. Suitable for unreliable network conditions.
  • RemoteContent - 120-second timeout, 3 retries with 2-second delay, warnings enabled. Suitable for DLC or remote asset bundle downloads.

Preset instances are shared and should not be mutated. Use Clone() to obtain a private copy before modifying individual properties, or construct a new instance with object-initializer syntax: 

var settings = new AddressableSettings
{
    TimeoutMilliseconds = 60000,
    RetryCount          = 2,
    TrackLoadedAssets   = true
};
settings.Validate(); // recommended before use

Call Validate() before passing a custom instance to an operation if settings are constructed at runtime from user input or configuration files. All ScyllaAddressables methods that accept settings call AddressableUtil.ResolveSettings internally, which substitutes Default when null is passed.

Constructors

AddressableSettings()

Initializes a new instance of AddressableSettings with all property values set to their documented defaults. Equivalent to using the Default preset, except this instance is mutable.

Declaration
public AddressableSettings()

AddressableSettings(AddressableSettings)

Initializes a new instance of AddressableSettings by copying all property values from other. Provides a convenient way to derive a modified configuration from an existing preset without altering the original. When other is null, the new instance is initialized with default values as if the no-argument constructor were called.

Declaration
public AddressableSettings(AddressableSettings other)
Parameters
Type Name Description
AddressableSettings other

The AddressableSettings instance whose values should be copied. May be null; in that case default values are used.

Fields

DEFAULT_RETRY_COUNT

The default number of retry attempts: 0 (no retries). Operations fail immediately on the first error unless a non-zero RetryCount is set.

Declaration
public const int DEFAULT_RETRY_COUNT = 0
Field Value
Type Description
int

DEFAULT_RETRY_DELAY_MS

The default delay between retry attempts: 1 000 milliseconds (1 second). Used by the WithRetries preset.

Declaration
public const int DEFAULT_RETRY_DELAY_MS = 1000
Field Value
Type Description
int

DEFAULT_TIMEOUT_MS

The default timeout for Addressables operations: 30 000 milliseconds (30 seconds). This is the value used by Default and WithRetries.

Declaration
public const int DEFAULT_TIMEOUT_MS = 30000
Field Value
Type Description
int

LONG_TIMEOUT_MS

The extended timeout used by the LongTimeout and RemoteContent presets: 120 000 milliseconds (120 seconds). Suitable for large remote bundle downloads where download speed may be slow.

Declaration
public const int LONG_TIMEOUT_MS = 120000
Field Value
Type Description
int

MAX_RETRY_COUNT

The maximum permitted value for RetryCount: 5. Validate() throws an AddressableException if this limit is exceeded.

Declaration
public const int MAX_RETRY_COUNT = 5
Field Value
Type Description
int

MAX_TIMEOUT_MS

The maximum permitted value for TimeoutMilliseconds: 600 000 milliseconds (10 minutes). Values above this limit are rejected by Validate().

Declaration
public const int MAX_TIMEOUT_MS = 600000
Field Value
Type Description
int

MIN_TIMEOUT_MS

The minimum permitted value for TimeoutMilliseconds: 1 000 milliseconds (1 second). Values below this limit are rejected by Validate().

Declaration
public const int MIN_TIMEOUT_MS = 1000
Field Value
Type Description
int

Properties

Default

Gets a shared settings preset with the default timeout (30 s) and no retries. Suitable for most local Addressables operations where assets are bundled with the application and network latency is not a concern. This preset is used automatically when null is passed as a settings argument.

Declaration
public static AddressableSettings Default { get; }
Property Value
Type Description
AddressableSettings
Remarks

Do not mutate this instance. Call Clone() first if you need a modified copy.

EnableWarnings

Gets or sets whether ScyllaAddressables should log warning messages when it detects common misuse patterns such as loading an asset that was never released. Disable in production builds where these logs are noisy and the behavior is known to be correct.

Declaration
public bool EnableWarnings { get; set; }
Property Value
Type Description
bool

true to emit warnings; false to suppress them. Defaults to true.

LongTimeout

Gets a shared settings preset with an extended timeout of 120 seconds and no retries. Appropriate for single large remote asset downloads on reliable connections where occasional slowness should not immediately fail the operation.

Declaration
public static AddressableSettings LongTimeout { get; }
Property Value
Type Description
AddressableSettings
Remarks

Do not mutate this instance. Call Clone() first if you need a modified copy.

ReleaseDependenciesOnFailure

Gets or sets whether assets that were successfully loaded during a batch operation should be automatically released if any asset in that same batch fails to load. When true, a partial batch failure results in a clean state - no partially loaded asset set is left in memory. When false, callers are responsible for releasing whatever was loaded before the failure.

Declaration
public bool ReleaseDependenciesOnFailure { get; set; }
Property Value
Type Description
bool

true to release successfully-loaded assets on batch failure; false to leave them loaded. Defaults to true.

RemoteContent

Gets a shared settings preset optimized for downloading remote content such as DLC packs or large asset bundles. Combines an extended 120-second timeout, 3 retry attempts with 2-second delays, and EnableWarnings enabled so that unreleased assets are logged during development.

Declaration
public static AddressableSettings RemoteContent { get; }
Property Value
Type Description
AddressableSettings
Remarks

Do not mutate this instance. Call Clone() first if you need a modified copy.

RetryCount

Gets or sets the number of times a failed operation should be automatically retried before returning a failure result. A value of 0 means the operation fails immediately on the first error. Must be in the range [0, MAX_RETRY_COUNT]; enforced by Validate().

Declaration
public int RetryCount { get; set; }
Property Value
Type Description
int

A non-negative integer. Defaults to DEFAULT_RETRY_COUNT (0).

RetryDelayMilliseconds

Gets or sets the number of milliseconds to wait between consecutive retry attempts when RetryCount is greater than zero. Must be non-negative; enforced by Validate(). Setting this to zero causes retries to occur back-to-back with no delay.

Declaration
public int RetryDelayMilliseconds { get; set; }
Property Value
Type Description
int

A non-negative integer millisecond count. Defaults to DEFAULT_RETRY_DELAY_MS (1 000 ms / 1 second).

TimeoutMilliseconds

Gets or sets the maximum duration in milliseconds that a single Addressables operation is allowed to run before it is considered timed out and fails with Timeout. Must be in the range [MIN_TIMEOUT_MS, MAX_TIMEOUT_MS]; enforced by Validate().

Declaration
public int TimeoutMilliseconds { get; set; }
Property Value
Type Description
int

An integer millisecond count. Defaults to DEFAULT_TIMEOUT_MS (30 000 ms / 30 seconds).

TrackLoadedAssets

Gets or sets whether ScyllaAddressables should maintain an internal registry of all loaded asset handles so that unreleased assets can be detected and reported. Enabling this has a small runtime overhead and is recommended only during development or QA builds.

Declaration
public bool TrackLoadedAssets { get; set; }
Property Value
Type Description
bool

true to enable tracking; false to disable it. Defaults to false to avoid the overhead in production.

WithRetries

Gets a shared settings preset with the default timeout (30 s), 3 retry attempts, and a 1-second delay between retries. Appropriate when the network is generally available but may experience transient drops that a short wait can recover from.

Declaration
public static AddressableSettings WithRetries { get; }
Property Value
Type Description
AddressableSettings
Remarks

Do not mutate this instance. Call Clone() first if you need a modified copy.

Methods

Clone()

Creates and returns a deep copy of this AddressableSettings instance with the same property values. Use this to derive a modifiable configuration from a shared preset without risking mutation of the original.

Declaration
public AddressableSettings Clone()
Returns
Type Description
AddressableSettings

A new AddressableSettings instance with all property values identical to this instance.

Validate()

Validates all property values and throws an AddressableException with error code InvalidSettings if any value is outside its permitted range. Call this before passing a programmatically constructed AddressableSettings to an operation when the values originate from user input or a configuration file.

Declaration
public void Validate()
Remarks

Validation rules:

Exceptions
Type Condition
AddressableException

Thrown with InvalidSettings when any property value violates the constraints described in the remarks. The exception message identifies the specific property and limit that was violated.

Extension Methods

See Also