Namespace Serenity.Global.Infrastructure.Utils

Classes

AudioMixerDependencyCache

Static cache for AudioMixer and AudioMixerGroup assets that keeps Addressables handles alive to prevent Unity from unloading these critical dependencies during the application lifecycle. This solves the issue where AudioMixerGroup references inside ScriptableObjects become "fake-null" when Addressables handles are released.

UnityAddressableUtils

Direct API to load ALL from Addressables (no filtering, no caching).
Prefer the unified API: LoadAllFromAnyBlocking<T>(string).

Every public entry point is gated by SerenityAssetLoadingModeProvider:

In ResourcesOnly mode the methods short-circuit and return an empty list without touching the Addressables API. A one-time verbose log explains the no-op so a caller that genuinely needed Addressables sees the divergence.
In Addressables-using modes the behaviour is unchanged; the blocking variant additionally throws NotSupportedException on WebGL because WaitForCompletion cannot be serviced there.

UnityAssetUtils

Utility class for Unity asset loading operations including Addressables management, audio clip caching, and asset warm-up functionality.

Threading contract: every Addressables call in this class runs on the Unity main thread. Addressables mutates unsynchronized internal state (notably AddressablesImpl.m_resultToHandle and the global operation-callback node cache) from its completion callbacks, and WaitForCompletion drives those callbacks by pumping the ResourceManager on the calling thread. A single Addressables call made from a thread-pool thread — a Release in a continuation, or in a cancellation callback — corrupts that state and surfaces as an IndexOutOfRangeException or NullReferenceException raised (and swallowed) inside Addressables' own callback dispatch.

This is why every await below uses ConfigureAwait(true): the continuation must resume through the captured Unity SynchronizationContext. Addressables completes its Task with RunContinuationsAsynchronously, so ConfigureAwait(false) does not merely *allow* a pool thread — it guarantees one. For the same reason no cancellation callback releases a handle: those callbacks run on whichever thread requested cancellation. Handles are released on the post-await path instead, which costs nothing because Addressables cannot abort an in-flight load anyway.

Every public entry point is gated by SerenityAssetLoadingModeProvider:

AddressablesWithResourcesFallback (default) keeps the committed behaviour: Addressables first, Resources fallback.
AddressablesOnly skips every Resources fallback path.
ResourcesOnly never touches the Addressables API — no LoadAssetAsync, no LoadAssetsAsync, no LoadResourceLocationsAsync, no WaitForCompletion.

In ResourcesOnly mode the synchronous WebGL guard is moot: no sync Addressables call is reachable. The guard remains on the Addressables-using branches so that any AddressablesOnly / AddressablesWithResourcesFallback caller that hits sync code on WebGL still throws NotSupportedException with an actionable message.

UnityAudioMixerGroupUtils

Utility class for AudioMixerGroup operations

UnityHierarchyUtils

Helpers for navigating and querying the Unity scene hierarchy

UnityMainThread

Unity MonoBehaviour singleton for managing cross-thread operations and main thread dispatching.
Provides thread-safe methods to execute actions and functions on Unity's main thread from background threads, with automatic bootstrap initialization and concurrent queue-based operation management.

UnityObjectUtils

Small, generalized helpers for Unity object identity checks and component lookup, factored out of the per-service copies that used to hand-roll them (e.g. the destroyed-object-aware null check that used to live only in UnityAssetPrefetcherService).

UnityParserUtils

Helpers to parse objects to specific Unity types with error handling

UnityResourceUtils

Direct API to load ALL from Resources (no filtering, no async, no caching).
Prefer the unified API: LoadAllFromAnyBlocking<T>(string)

UnityServiceHost

The "create a GameObject, name it, add the hosting component" boilerplate repeated by every Unity service factory (see UnityTimerServiceFactory, UnitySoundMixerServiceFactory, UnityLocalizationServiceFactory, and the rest). Deliberately does NOT call Object.DontDestroyOnLoad — factories differ on whether the service GameObject should survive a scene load, so that call stays at each call site rather than being folded in here.