Class ResourceUtil

Provides utility methods for working with Unity's synchronous and asynchronous Resources API. Wraps common resource operations with warning logging, null-safety, typed instantiation helpers, and async/awaitable overloads.

Inheritance
object
ResourceUtil
Inherited Members
Namespace: Scylla.Core.Util
Assembly: ScyllaCore.dll
Syntax
public static class ResourceUtil
Remarks

Important: The Unity Resources system requires all assets to be placed inside a folder named Resources anywhere in the project's Assets tree. Paths passed to Load methods are relative to the Resources folder and must not include file extensions.

For production games, consider using Unity's Addressables system instead. The Resources system increases the initial load time and memory footprint because Unity scans all Resources folders at startup. Prefer ResourceUtil for small, always-needed assets (shaders, fonts, embedded configuration) and use Addressables for large or optionally-loaded content. Scylla provides ScyllaAddressables as an optional integration when the SCYLLA_HAS_ADDRESSABLES version define is active.

Existence checks via Exists(string) and Exists<T>(string) perform a full resource load internally. Prefer TryLoad<T>(string, out T) when you intend to use the asset immediately after checking, to avoid loading it twice.

Methods

Exists(string)

Determines whether any Unity UnityEngine.Object exists at the specified Resources path, regardless of type.

Declaration
public static bool Exists(string path)
Parameters
Type Name Description
string path

The path to the asset relative to any Resources folder in the project, without file extension.
Returns
Type Description
bool

true if an asset exists at the path; false otherwise.
Remarks

Performance note: This method performs a full synchronous resource load internally in order to verify existence. If you intend to use the asset after the check, prefer TryLoad<T>(string, out T) to avoid loading the asset twice. Do not call this in performance-critical code paths or on every frame.

Exists<T>(string)

Determines whether an asset of type T exists at the specified Resources path.

Declaration
public static bool Exists<T>(string path) where T : Object
Parameters
Type Name Description
string path

The path to the asset relative to any Resources folder in the project, without file extension.
Returns
Type Description
bool

true if an asset of type T exists at the path; false otherwise.
Type Parameters
Name Description
T

The type of Unity UnityEngine.Object to check for.
Remarks

Performance note: This method performs a full synchronous resource load internally. Prefer TryLoad<T>(string, out T) when you also need the loaded asset.

GetBuiltin<T>(string)

Retrieves a Unity built-in resource of type T from Unity's internal resource database. Built-in resources are bundled with the Unity engine (e.g., the default sprite, default UI materials, the built-in font).

Declaration
public static T GetBuiltin<T>(string path) where T : Object
Parameters
Type Name Description
string path

The Unity-internal path to the built-in resource. Common examples: "Sprites/Default" for the white sprite, "Font/Arial.ttf" for the default Arial font. These paths are Unity-internal and not filesystem paths.
Returns
Type Description
T

The built-in resource cast to T, or null if no matching built-in resource exists at the specified path.
Type Parameters
Name Description
T

The type of built-in Unity UnityEngine.Object to retrieve.

InstantiatePrefab(string)

Loads and instantiates a prefab from a Resources folder at the world origin with no parent. Equivalent to calling InstantiatePrefab(string, string, Transform) with a null name and null parent.

Declaration
public static GameObject InstantiatePrefab(string path)
Parameters
Type Name Description
string path

The path to the prefab asset relative to any Resources folder, without file extension.
Returns
Type Description
GameObject

The root UnityEngine.GameObject of the instantiated prefab, or null if the prefab could not be loaded from the given path.

InstantiatePrefab(string, string, Transform)

Loads and instantiates a prefab from a Resources folder, optionally overriding the instance name and parent transform. The instance is placed at the world origin (Vector3.zero, Quaternion.identity).

Declaration
public static GameObject InstantiatePrefab(string path, string name, Transform parent)
Parameters
Type Name Description
string path

The path to the prefab asset relative to any Resources folder, without file extension.
string name

The name to assign to the instantiated UnityEngine.GameObject. If null or empty, the prefab's original name is preserved.
Transform parent

The UnityEngine.Transform to parent the instantiated object to. Pass null to leave the object at the root of the scene hierarchy.
Returns
Type Description
GameObject

The root UnityEngine.GameObject of the instantiated prefab, or null if the prefab could not be loaded from the given path.

InstantiatePrefab(string, Transform)

Loads and instantiates a prefab from a Resources folder and attaches it to the specified parent UnityEngine.Transform.

Declaration
public static GameObject InstantiatePrefab(string path, Transform parent)
Parameters
Type Name Description
string path

The path to the prefab asset relative to any Resources folder, without file extension.
Transform parent

The UnityEngine.Transform to parent the instantiated object to. Pass null to leave the object at the root of the scene hierarchy.
Returns
Type Description
GameObject

The root UnityEngine.GameObject of the instantiated prefab, or null if the prefab could not be loaded from the given path.

InstantiatePrefab(string, Vector3, Quaternion, Transform)

Loads and instantiates a prefab from a Resources folder at a specified world position and rotation, optionally under a parent transform.

Declaration
public static GameObject InstantiatePrefab(string path, Vector3 position, Quaternion rotation, Transform parent = null)
Parameters
Type Name Description
string path

The path to the prefab asset relative to any Resources folder, without file extension.
Vector3 position

The world-space position at which to instantiate the prefab.
Quaternion rotation

The world-space rotation to apply to the instantiated prefab.
Transform parent

The UnityEngine.Transform to parent the instantiated object to. Defaults to null (scene root).
Returns
Type Description
GameObject

The root UnityEngine.GameObject of the instantiated prefab, or null if the prefab could not be loaded from the given path.

InstantiatePrefab<T>(string)

Loads and instantiates a prefab from a Resources folder at the world origin and returns the first component of type T found on the root UnityEngine.GameObject.

Declaration
public static T InstantiatePrefab<T>(string path) where T : Component
Parameters
Type Name Description
string path

The path to the prefab asset relative to any Resources folder, without file extension.
Returns
Type Description
T

The component of type T on the instantiated prefab's root, or null if the prefab could not be loaded or the component is not present on the root.
Type Parameters
Name Description
T

The UnityEngine.Component type to retrieve from the instantiated prefab's root GameObject.

InstantiatePrefab<T>(string, Transform)

Loads and instantiates a prefab from a Resources folder under a parent transform and returns the first component of type T found on the root UnityEngine.GameObject.

Declaration
public static T InstantiatePrefab<T>(string path, Transform parent) where T : Component
Parameters
Type Name Description
string path

The path to the prefab asset relative to any Resources folder, without file extension.
Transform parent

The UnityEngine.Transform to parent the instantiated object to. Pass null to leave the object at the root of the scene hierarchy.
Returns
Type Description
T

The component of type T on the instantiated prefab's root, or null if the prefab could not be loaded or the component is not present on the root.
Type Parameters
Name Description
T

The UnityEngine.Component type to retrieve from the instantiated prefab's root GameObject.

InstantiatePrefab<T>(string, Vector3, Quaternion, Transform)

Loads and instantiates a prefab from a Resources folder at a specified world position and rotation, and returns the first component of type T found on the root UnityEngine.GameObject.

Declaration
public static T InstantiatePrefab<T>(string path, Vector3 position, Quaternion rotation, Transform parent = null) where T : Component
Parameters
Type Name Description
string path

The path to the prefab asset relative to any Resources folder, without file extension.
Vector3 position

The world-space position at which to instantiate the prefab.
Quaternion rotation

The world-space rotation to apply to the instantiated prefab.
Transform parent

The UnityEngine.Transform to parent the instantiated object to. Defaults to null (scene root).
Returns
Type Description
T

The component of type T on the instantiated prefab's root, or null if the prefab could not be loaded or the component is not present on the root.
Type Parameters
Name Description
T

The UnityEngine.Component type to retrieve from the instantiated prefab's root GameObject.

LoadAll<T>(string)

Loads all assets of type T found at or below a Resources folder path. Useful for loading an entire category of assets (e.g., all AudioClips in a Resources/SFX folder) without enumerating paths individually.

Declaration
public static T[] LoadAll<T>(string path) where T : Object
Parameters
Type Name Description
string path

The directory path relative to any Resources folder. Pass an empty string or "" to load all assets of the given type from every Resources folder in the project. Sub-folder separators must use the forward-slash character /.
Returns
Type Description
T[]

An array containing all assets of type T found at the specified path. Returns an empty array if no matching assets exist - never returns null.
Type Parameters
Name Description
T

The type of Unity UnityEngine.Object to load.

LoadAsyncAwaitable<T>(string)

Asynchronously loads an asset of type T from a Resources folder using Unity 6's UnityEngine.Awaitable<T> API, which can be directly awaited in async methods.

Declaration
public static Awaitable<T> LoadAsyncAwaitable<T>(string path) where T : Object
Parameters
Type Name Description
string path

The path to the asset relative to any Resources folder in the project, without file extension.
Returns
Type Description
Awaitable<T>

An UnityEngine.Awaitable<T> that resolves to the loaded asset cast to T, or null if no asset of the given type exists at the specified path.
Type Parameters
Name Description
T

The type of Unity UnityEngine.Object to load.
Remarks

This method uses Unity's Awaitable system introduced in Unity 2023+. It is suitable for use inside async MonoBehaviour event functions (e.g., async void Awake()) or any async Awaitable method. For coroutine-based loading, use LoadAsync<T>(string) instead.

// async/await usage:
var texture = await ResourceUtil.LoadAsyncAwaitable<Texture2D>("Textures/MyTexture");
if (texture != null) { /* use texture */ }

LoadAsync<T>(string)

Begins an asynchronous load of an asset of type T from a Resources folder. Returns a UnityEngine.ResourceRequest that reports loading progress and provides the loaded asset once complete.

Declaration
public static ResourceRequest LoadAsync<T>(string path) where T : Object
Parameters
Type Name Description
string path

The path to the asset relative to any Resources folder in the project, without file extension.
Returns
Type Description
ResourceRequest

A UnityEngine.ResourceRequest that can be yielded in a coroutine or checked via its isDone property. After the request completes, access the loaded asset via request.asset cast to T. Returns null if no asset exists at the path (check after isDone).
Type Parameters
Name Description
T

The type of Unity UnityEngine.Object to load.
Remarks

Prefer LoadAsyncAwaitable<T>(string) when writing async/await code with Unity 6's Awaitable API.

// Coroutine usage:
var request = ResourceUtil.LoadAsync<Texture2D>("Textures/MyTexture");
yield return request;
var texture = request.asset as Texture2D;

LoadOptional<T>(string)

Loads an asset of type T from a Resources folder synchronously, suppressing any warning when the asset is not found. Use this overload when the absence of a resource is an expected and non-error condition.

Declaration
public static T LoadOptional<T>(string path) where T : Object
Parameters
Type Name Description
string path

The path to the asset relative to any Resources folder in the project, without file extension.
Returns
Type Description
T

The loaded asset cast to T, or null if no asset of the given type exists at the specified path.
Type Parameters
Name Description
T

The type of Unity UnityEngine.Object to load.
See Also

Load<T>(string)

Loads an asset of type T from a Resources folder synchronously. Emits a warning via Scylla's logging system if the asset cannot be found at the specified path, which aids debugging of missing-resource issues in the field.

Declaration
public static T Load<T>(string path) where T : Object
Parameters
Type Name Description
string path

The path to the asset relative to any Resources folder in the project, without file extension. For example, "Prefabs/Player" loads Assets/Resources/Prefabs/Player.prefab. Sub-folder separators must use the forward-slash character /.
Returns
Type Description
T

The loaded asset cast to T, or null if no asset of the given type exists at the specified path.
Type Parameters
Name Description
T

The type of Unity UnityEngine.Object to load (e.g., GameObject, Texture2D, AudioClip, ScriptableObject).
See Also

TryLoad<T>(string, out T)

Attempts to load an asset of type T from a Resources folder. This is the preferred pattern when you need both a null-check and the asset in a single allocation-free call.

Declaration
public static bool TryLoad<T>(string path, out T resource) where T : Object
Parameters
Type Name Description
string path

The path to the asset relative to any Resources folder, without file extension.
T resource

When this method returns true, contains the loaded asset cast to T. When this method returns false, contains null.
Returns
Type Description
bool

true if the asset was found and successfully loaded; false otherwise. No warning is emitted on failure.
Type Parameters
Name Description
T

The type of Unity UnityEngine.Object to load.
See Also

Unload(Object)

Unloads the specified asset from memory, freeing the GPU and CPU memory it occupied. Silently does nothing if asset is null.

Declaration
public static void Unload(Object asset)
Parameters
Type Name Description
Object asset

The asset to unload. Must be a non-instantiated asset (e.g., a Texture2D or AudioClip loaded from Resources). Attempting to unload an instantiated object may produce unexpected behaviour; use Destroy(Object, float) for scene instances instead.
Remarks

After calling this method, any remaining references to the asset in scene objects will become invalid (the asset slot shows as None (Type) in the Inspector). Ensure no live objects still reference the asset before unloading it.

UnloadUnused()

Triggers Unity's asynchronous unload pass, which scans all loaded assets and releases any that are no longer referenced by any active object in the scene. Equivalent to UnityEngine.Resources.UnloadUnusedAssets().

Declaration
public static AsyncOperation UnloadUnused()
Returns
Type Description
AsyncOperation

An UnityEngine.AsyncOperation that can be yielded in a coroutine to wait for the unload to complete. The operation's progress property reports unload progress from 0 to 1.
Remarks

This operation can be expensive on large scenes. Prefer calling it during scene transitions or explicit loading screens rather than during normal gameplay. Instantiated prefabs and their textures will not be unloaded; only assets that have no remaining live references are released.