Class ComponentUtil

Provides utility methods for caching and managing Unity components, with a unified set of extension methods on both UnityEngine.GameObject and UnityEngine.Component.

Inheritance

object

ComponentUtil

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util

Assembly: ScyllaCore.dll

Syntax

public static class ComponentUtil

Remarks

This utility optimizes repeated UnityEngine.GameObject.GetComponent<T>() calls by maintaining an internal dictionary keyed by GameObject.GetInstanceID. On the first lookup for a GameObject, a ComponentUtil.CacheEntry is created and subsequent requests for any component type on that object are served from the cache without touching the Unity component system.

The cache is automatically pruned of destroyed-object entries whenever a scene is unloaded (via UnityEngine.SceneManagement.SceneManager.sceneUnloaded). You can also trigger pruning manually via Prune() or clear the entire cache via ClearCache().

All extension methods delegate their null-guard through the typed overloads, so passing a null component or GameObject always returns null / false rather than throwing an exception.

Properties

CacheSize

Gets the current number of GameObjects tracked in the component cache. This count includes entries for GameObjects that have since been destroyed; call Prune() to remove stale entries and obtain an accurate count.

Declaration

public static int CacheSize { get; }

Property Value

Type	Description
int

Methods

Add(Component, Type)

Adds a new component of the specified type to the Component's owning GameObject and stores it in the cache for future lookups. Returns null if component or type is null.

Declaration

public static Component Add(this Component component, Type type)

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject receives the new component. Safe to pass as null.
Type	type	The Type of component to add. Safe to pass as null.

Returns

Type	Description
Component	The newly added component, or null if either argument is null.

Add(GameObject, Type)

Adds a new component of the specified type to the GameObject and stores it in the cache. Always adds a new component; use Require(GameObject, Type) to get-or-add instead. Returns null if either argument is null.

Declaration

public static Component Add(this GameObject gameObject, Type type)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject that receives the new component. Safe to pass as null.
Type	type	The Type of component to add. Safe to pass as null.

Returns

Type	Description
Component	The newly added component, or null if either argument is null.

Add<T>(Component)

Adds a new component of type T to the Component's owning GameObject and stores it in the cache for future lookups. Returns null if component is null.

Declaration

public static T Add<T>(this Component component) where T : Component

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject receives the new component. Safe to pass as null.

Returns

Type	Description
T	The newly added component, or null if component is null.

Type Parameters

Name	Description
T	The type of component to add. Must derive from UnityEngine.Component.

Add<T>(GameObject)

Adds a new component of type T to the GameObject and stores it in the cache. Always adds a new component regardless of whether one already exists; use Require<T>(GameObject) to get-or-add instead. Returns null if gameObject is null.

Declaration

public static T Add<T>(this GameObject gameObject) where T : Component

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject that receives the new component. Safe to pass as null.

Returns

Type	Description
T	The newly added component, or null if gameObject is null.

Type Parameters

Name	Description
T	The type of component to add. Must derive from UnityEngine.Component.

ClearCache()

Clears the entire component cache, discarding all stored component references. After this call every Get<T>(GameObject) call will perform a fresh Unity component lookup. Use this in domain-reload scenarios or when you want to guarantee that removed components are never returned from stale cache entries.

Declaration

public static void ClearCache()

ClearCache(Component)

Removes the cache entry for the specified Component's owning GameObject, forcing the next lookup on that object to query the Unity component system directly. Has no effect if component is null or the owning GameObject has no entry in the cache.

Declaration

public static void ClearCache(Component component)

Parameters

Type	Name	Description
Component	component	The Component whose owning GameObject's cache entry to remove. Safe to pass as null.

ClearCache(GameObject)

Removes the cache entry for the specified GameObject, forcing the next lookup on it to query the Unity component system directly. Has no effect if gameObject is null or has no entry in the cache.

Declaration

public static void ClearCache(GameObject gameObject)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject whose cache entry to remove. Safe to pass as null.

Get(Component, Type)

Returns the first component of the specified type on the Component's owning GameObject, using the internal cache to avoid repeated Unity API calls. Returns null if component or type is null, or if the component type does not exist on the GameObject.

Declaration

public static Component Get(this Component component, Type type)

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject is searched. Safe to pass as null.
Type	type	The Type of component to retrieve. Safe to pass as null.

Returns

Type	Description
Component	The cached or freshly retrieved component, or null if not found.

Get(GameObject, Type)

Returns the first component of the specified type on the GameObject, using the internal cache to avoid repeated Unity API calls. On the first request for a given (GameObject, type) pair, calls GetComponent(Type) and stores the result; subsequent calls are served from the dictionary without any Unity overhead. Returns null if either argument is null, or if no matching component exists.

Declaration

public static Component Get(this GameObject gameObject, Type type)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to search. Safe to pass as null.
Type	type	The Type of component to retrieve. Safe to pass as null.

Returns

Type	Description
Component	The cached or freshly retrieved component, or null if not found.

Get<T>(Component)

Returns the first component of type T on the Component's owning GameObject, using the internal cache to avoid repeated Unity API calls. Returns null if component is null or if the component type does not exist on the GameObject.

Declaration

public static T Get<T>(this Component component) where T : Component

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject is searched. Safe to pass as null.

Returns

Type	Description
T	The cached or freshly retrieved component, or null if not found.

Type Parameters

Name	Description
T	The type of component to retrieve. Must derive from UnityEngine.Component.

Get<T>(GameObject)

Returns the first component of type T on the GameObject, using the internal cache to avoid repeated Unity API calls. Returns null if gameObject is null or if the component type does not exist on the object.

Declaration

public static T Get<T>(this GameObject gameObject) where T : Component

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to search. Safe to pass as null.

Returns

Type	Description
T	The cached or freshly retrieved component, or null if not found.

Type Parameters

Name	Description
T	The type of component to retrieve. Must derive from UnityEngine.Component.

Has<T>(Component)

Returns true if a component of type T exists on the Component's owning GameObject. Consults the cache but does not add the component to the cache on a cache miss; use Get<T>(Component) when you also need the component reference.

Declaration

public static bool Has<T>(this Component component) where T : Component

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject is checked. Returns false if null.

Returns

Type	Description
bool	true if the component type is present on the GameObject; otherwise false.

Type Parameters

Name	Description
T	The type of component to check for. Must derive from UnityEngine.Component.

Has<T>(GameObject)

Returns true if a component of type T exists on the GameObject. Checks the cache first; if the type is already cached, returns true without hitting the Unity component system. On a cache miss, falls back to a direct UnityEngine.GameObject.GetComponent<T>() call but does not populate the cache with the result.

Declaration

public static bool Has<T>(this GameObject gameObject) where T : Component

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to check. Returns false if null.

Returns

Type	Description
bool	true if the component type is present on the GameObject; otherwise false.

Type Parameters

Name	Description
T	The type of component to check for. Must derive from UnityEngine.Component.

Prune()

Removes all cache entries whose referenced UnityEngine.GameObject has been destroyed. This is an O(n) scan of the entire cache and is called automatically when a scene is unloaded. You can also call it manually after bulk GameObject destruction to reclaim memory before the next scene transition.

Declaration

public static void Prune()

Require(Component, Type)

Returns the component of the specified type on the Component's owning GameObject, adding it if it does not already exist. The result is cached for future lookups. Returns null if component or type is null.

Declaration

public static Component Require(this Component component, Type type)

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject is searched or modified. Safe to pass as null.
Type	type	The Type of component to get or add. Safe to pass as null.

Returns

Type	Description
Component	The existing or newly added component, or null if either argument is null.

Require(GameObject, Type)

Returns the component of the specified type on the GameObject, adding it if it does not already exist. Internally calls Get(GameObject, Type) first and falls back to Add(GameObject, Type) on a miss. The result is cached in both cases. Returns null if either argument is null.

Declaration

public static Component Require(this GameObject gameObject, Type type)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to search or modify. Safe to pass as null.
Type	type	The Type of component to get or add. Safe to pass as null.

Returns

Type	Description
Component	The existing or newly added component, or null if either argument is null.

Require<T>(Component)

Returns the component of type T on the Component's owning GameObject, adding it if it does not already exist. The result is cached for future lookups. Returns null if component is null.

Declaration

public static T Require<T>(this Component component) where T : Component

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject is searched or modified. Safe to pass as null.

Returns

Type	Description
T	The existing component if already present, the newly added component if it was missing, or null if component is null.

Type Parameters

Name	Description
T	The type of component to get or add. Must derive from UnityEngine.Component.

Require<T>(GameObject)

Returns the component of type T on the GameObject, adding it if it does not already exist. The result is cached for future lookups. Returns null if gameObject is null.

Declaration

public static T Require<T>(this GameObject gameObject) where T : Component

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to search or modify. Safe to pass as null.

Returns

Type	Description
T	The existing component if already present, the newly added component if it was missing, or null if gameObject is null.

Type Parameters

Name	Description
T	The type of component to get or add. Must derive from UnityEngine.Component.

TryGet<T>(Component, out T)

Attempts to retrieve a component of type T from the Component's owning GameObject, using the internal cache. Returns false and sets result to null when component is null or the component type is not present on the GameObject.

Declaration

public static bool TryGet<T>(this Component component, out T result) where T : Component

Parameters

Type	Name	Description
Component	component	The Component whose owning UnityEngine.GameObject is searched. Safe to pass as null.
T	result	When this method returns true, contains the found component. When this method returns false, contains null.

Returns

Type	Description
bool	true if the component was found; otherwise false.

Type Parameters

Name	Description
T	The type of component to retrieve. Must derive from UnityEngine.Component.

TryGet<T>(GameObject, out T)

Attempts to retrieve a component of type T from the GameObject, using the internal cache. Returns false and sets result to null when gameObject is null or the component type is not present on the object.

Declaration

public static bool TryGet<T>(this GameObject gameObject, out T result) where T : Component

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to search. Safe to pass as null.
T	result	When this method returns true, contains the found component. When this method returns false, contains null.

Returns

Type	Description
bool	true if the component was found; otherwise false.

Type Parameters

Name	Description
T	The type of component to retrieve. Must derive from UnityEngine.Component.