Class GameObjectUtil

Provides commonly used utility methods for working with Unity UnityEngine.GameObject hierarchies, covering object creation and ensuring, component management, hierarchy queries, world-space bounds aggregation, visibility and collider toggling, recursive layer assignment, and editor-safe destruction.

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

All methods are null-safe at the top level: passing a null GameObject returns a sensible default (null, false, UnityEngine.Vector3.zero, or a no-op) rather than throwing. Individual exceptions are documented per method.

Hierarchy traversal methods (e.g., FindChildRecursive(GameObject, string, bool), SetActiveRecursively(GameObject, bool, bool), SetLayerRecursively(GameObject, int), DestroyChildren(Transform, bool)) use an explicit stack-based depth-first traversal rather than recursion to avoid stack overflows on deeply nested hierarchies.

The Destroy(Object, bool) and DestroyChildren(Transform, bool) methods are edit-mode safe: when running inside the Unity Editor outside of Play Mode they use DestroyImmediate(Object, bool) instead of UnityEngine.Object.Destroy(UnityEngine.Object).

Methods

Clone(GameObject, Transform, bool)

Clones the specified source GameObject and optionally parents it to the provided parent transform.

Declaration
public static GameObject Clone(GameObject source, Transform parent = null, bool worldPositionStays = false)
Parameters
Type Name Description
GameObject source

The GameObject to clone. Must not be null.
Transform parent

Optional parent transform to which the cloned GameObject should be attached. If null, the clone will not be parented.
bool worldPositionStays

Determines whether the cloned GameObject should maintain its world position, rotation, and scale when parented. Defaults to false.
Returns
Type Description
GameObject

The cloned GameObject.

Clone<T>(T)

Creates a duplicate of the specified Unity object using source. Utilizes Unity's UnityEngine.Object.Instantiate(UnityEngine.Object).

Declaration
public static T Clone<T>(T source) where T : Object
Parameters
Type Name Description
T source

The Unity object to clone. Must not be null.
Returns
Type Description
T

A new instance of the Unity object identical to the source.
Type Parameters
Name Description
T

Clone<T>(T, Transform, bool)

Creates a duplicate of the specified source GameObject and optionally parents it under a specified parent. The duplication process maintains the state of the original GameObject unless otherwise specified.

Declaration
public static T Clone<T>(T source, Transform parent, bool worldPositionStays = false) where T : Component
Parameters
Type Name Description
T source

The source GameObject to clone. Must not be null.
Transform parent

Optional parent Transform to set for the cloned GameObject.
bool worldPositionStays

Determines whether the cloned GameObject retains its world position or inherits the position from the parent.
Returns
Type Description
T

The cloned GameObject.
Type Parameters
Name Description
T

Destroy(Object, bool)

Destroys a Unity UnityEngine.Object safely in both Play Mode and Edit Mode. In Play Mode, delegates to UnityEngine.Object.Destroy(UnityEngine.Object) (deferred to end-of-frame). In Edit Mode (Editor builds only), delegates to DestroyImmediate(Object, bool) so that the object is removed immediately. Silently ignores Unity "fake null" references.

Declaration
public static void Destroy(Object obj, bool allowDestroyingAssets = false)
Parameters
Type Name Description
Object obj

The Unity object to destroy. No-op when the reference is null or has already been destroyed.
bool allowDestroyingAssets

Passed to DestroyImmediate(Object, bool) in Edit Mode only. Set to true to allow destroying loaded asset objects. Has no effect in Play Mode. Defaults to false.

DestroyChildren(Transform, bool)

Destroys all direct children of parent by iterating backwards through the child list (to avoid index shift issues). No-op if parent is null.

Declaration
public static void DestroyChildren(Transform parent, bool immediate = false)
Parameters
Type Name Description
Transform parent

The UnityEngine.Transform whose children will be destroyed. Safe to pass as null.
bool immediate

When true, uses UnityEngine.Object.DestroyImmediate(UnityEngine.Object) in Edit Mode (so children are removed before the next Editor repaint). In Play Mode, deferred destruction is always used regardless of this flag. Defaults to false.

EnableColliders(GameObject, bool, bool)

Enables or disables the UnityEngine.Collider.enabled flag on every 3D UnityEngine.Collider and the Collider2D.enabled flag on every 2D UnityEngine.Collider2D in the hierarchy rooted at obj. Useful for temporarily disabling all physics interactions on a complex prefab. No-op if obj is null.

Declaration
public static void EnableColliders(GameObject obj, bool status, bool includeInactive = true)
Parameters
Type Name Description
GameObject obj

The root UnityEngine.GameObject of the hierarchy. Safe to pass as null.
bool status

true to enable all colliders; false to disable them.
bool includeInactive

Whether colliders on inactive GameObjects are also affected. Defaults to true.

EnsureGameObject(string, Transform, bool)

Ensures a GameObject with the specified name exists. If a parent is provided, checks for a direct child with that name; otherwise, creates a new GameObject.

Declaration
public static GameObject EnsureGameObject(string name, Transform parent = null, bool resetLocal = true)
Parameters
Type Name Description
string name

The name of the GameObject to find or create. Must not be null or empty.
Transform parent

Optional parent transform. Direct children of this transform are checked, if provided.
bool resetLocal

Indicates whether the local position, rotation, and scale should be reset to their defaults on creation.
Returns
Type Description
GameObject

The existing or newly created GameObject.

EnsureGameObjectWithComponent<T>(string, Transform, bool)

Ensures a GameObject with the specified name exists in the scene and that it has a component of type T attached to it. If the GameObject or the component does not exist, they will be created.

Declaration
public static T EnsureGameObjectWithComponent<T>(string name, Transform parent = null, bool resetLocal = true) where T : Component
Parameters
Type Name Description
string name

The name of the GameObject to find or create.
Transform parent

Optional parent transform. If provided, only direct children are considered, and a new GameObject will be parented to it if created.
bool resetLocal

If true, resets the local position, rotation, and scale of the GameObject if it is created.
Returns
Type Description
T

The component of type T attached to the existing or newly created GameObject.
Type Parameters
Name Description
T

The type of the component to ensure on the GameObject.

FindByPath(GameObject, string)

Finds a GameObject by a Transform.Find()-style path relative to the specified root.

Declaration
public static GameObject FindByPath(GameObject root, string path)
Parameters
Type Name Description
GameObject root

The root GameObject from which the path search begins. Must not be null.
string path

The path to the desired GameObject, using "/" as the separator. If empty or null, the root GameObject is returned.
Returns
Type Description
GameObject

The GameObject at the specified path if found; otherwise, null.

FindChildRecursive(GameObject, string, bool)

Recursively searches for a child GameObject with the specified childName starting from the given gameObject.

Declaration
public static GameObject FindChildRecursive(GameObject gameObject, string childName, bool includeInactive = true)
Parameters
Type Name Description
GameObject gameObject

The root GameObject to start the search from. Must not be null.
string childName

The name of the child GameObject to find. Must not be null or empty.
bool includeInactive

Determines whether inactive GameObjects should be included in the search.
Returns
Type Description
GameObject

The first matching child GameObject, or null if no match is found.

GetBoundingBox(GameObject, bool)

Calculates and returns a world-space axis-aligned bounding box (AABB) for the hierarchy rooted at obj. The method aggregates bounds from all colliders and renderers within the hierarchy. If no bounds are found, returns a default (empty) UnityEngine.Bounds.

Declaration
public static Bounds GetBoundingBox(GameObject obj, bool includeInactive = true)
Parameters
Type Name Description
GameObject obj

The root GameObject of the hierarchy for which the bounding box is calculated.
bool includeInactive

Indicates whether to include inactive children in the bounds calculation.
Returns
Type Description
Bounds

The calculated UnityEngine.Bounds representing the axis-aligned bounding box for the hierarchy. May be empty if no bounds are found.

GetCentroid(GameObject, bool)

Returns the world-space centroid of the hierarchy rooted at obj. When a bounding box can be computed from UnityEngine.Renderer or UnityEngine.Collider components, the centroid is the center of that box. When no bounds are available, falls back to obj.transform.position. Returns UnityEngine.Vector3.zero if obj is null.

Declaration
public static Vector3 GetCentroid(GameObject obj, bool includeInactive = true)
Parameters
Type Name Description
GameObject obj

The root UnityEngine.GameObject of the hierarchy. Safe to pass as null.
bool includeInactive

Whether inactive children are included when computing bounds. Defaults to true.
Returns
Type Description
Vector3

The world-space center of the aggregated bounds, or the object's world position if no bounds exist, or UnityEngine.Vector3.zero if obj is null.

GetChild(GameObject, string)

Retrieves the first direct child GameObject of the specified gameObject with the given childName. Returns null if no child with the specified name is found.

Declaration
public static GameObject GetChild(GameObject gameObject, string childName)
Parameters
Type Name Description
GameObject gameObject

The parent GameObject to search. Must not be null.
string childName

The name of the child GameObject to locate. Must not be null or empty.
Returns
Type Description
GameObject

The child GameObject with the specified name, or null if not found.

GetOrAddComponent<T>(GameObject)

Retrieves a component of type T from the specified obj or adds it to the GameObject if it does not exist.

Declaration
public static T GetOrAddComponent<T>(GameObject obj) where T : Component
Parameters
Type Name Description
GameObject obj

The GameObject from which to retrieve or add the component.
Returns
Type Description
T

The existing or newly added component of type T.
Type Parameters
Name Description
T

The type of Component to retrieve or add.

IsActiveInHierarchy(GameObject)

Returns true if obj is not null and its UnityEngine.GameObject.activeInHierarchy flag is true, meaning both the object itself and all of its ancestors are active.

Declaration
public static bool IsActiveInHierarchy(GameObject obj)
Parameters
Type Name Description
GameObject obj

The UnityEngine.GameObject to check. Safe to pass as null.
Returns
Type Description
bool

true if obj is non-null and active in the scene hierarchy; otherwise false.

IsActiveSelf(GameObject)

Returns true if obj is not null and its UnityEngine.GameObject.activeSelf flag is true. This reflects only the local activation state of the object itself and does not indicate whether any parent is deactivated; use IsActiveInHierarchy(GameObject) for a full hierarchy check.

Declaration
public static bool IsActiveSelf(GameObject obj)
Parameters
Type Name Description
GameObject obj

The UnityEngine.GameObject to check. Safe to pass as null.
Returns
Type Description
bool

true if obj is non-null and self-active; otherwise false.

SetActive(GameObject, bool)

Null-safe wrapper around SetActive(bool) that silently ignores null references. Prefer this over a direct obj?.SetActive() call when the reference may be a Unity-destroyed "fake null".

Declaration
public static void SetActive(GameObject obj, bool status)
Parameters
Type Name Description
GameObject obj

The UnityEngine.GameObject to activate or deactivate. Safe to pass as null.
bool status

true to activate the object; false to deactivate it.

SetActiveRecursively(GameObject, bool, bool)

Calls SetActive(bool) on every node in the hierarchy rooted at obj, using a stack-based depth-first traversal. Unlike calling SetActive only on the root (which hides the subtree but does not change child activeSelf values), this method individually marks every descendant, ensuring predictable state when you later re-parent or move objects.

Declaration
public static void SetActiveRecursively(GameObject obj, bool status, bool includeRoot = true)
Parameters
Type Name Description
GameObject obj

The root UnityEngine.GameObject of the hierarchy. Safe to pass as null.
bool status

true to activate every node; false to deactivate every node.
bool includeRoot

Whether the root object itself is also affected. Defaults to true. Pass false to apply the change only to children.

SetLayerRecursively(GameObject, int)

Assigns the specified Unity layer to every UnityEngine.GameObject in the hierarchy rooted at obj, including the root itself. Uses a stack-based depth-first traversal. No-op if obj is null.

Declaration
public static void SetLayerRecursively(GameObject obj, int layer)
Parameters
Type Name Description
GameObject obj

The root UnityEngine.GameObject of the hierarchy. Safe to pass as null.
int layer

The layer index to assign (0-31). Use NameToLayer(string) to convert a layer name to its index.

SetVisibility(GameObject, bool, bool)

Enables or disables the UnityEngine.Renderer.enabled flag on every UnityEngine.Renderer component found in the hierarchy rooted at obj. This controls whether each mesh/sprite is drawn without changing any activation state. No-op if obj is null.

Declaration
public static void SetVisibility(GameObject obj, bool status, bool includeInactive = true)
Parameters
Type Name Description
GameObject obj

The root UnityEngine.GameObject of the hierarchy. Safe to pass as null.
bool status

true to make all renderers visible; false to hide them.
bool includeInactive

Whether renderers on inactive GameObjects are also affected. Defaults to true.

TryGetBoundingBox(GameObject, out Bounds, bool)

Attempts to calculate a world-space axis-aligned bounding box (AABB) for the hierarchy rooted at the specified obj. Prefers bounds derived from Renderers; if none are found, falls back to bounds from 3D or 2D Colliders.

Declaration
public static bool TryGetBoundingBox(GameObject obj, out Bounds bounds, bool includeInactive = true)
Parameters
Type Name Description
GameObject obj

The root GameObject whose hierarchy will be analyzed. Must not be null.
Bounds bounds

Output parameter that will contain the calculated bounding box if the operation succeeds.
bool includeInactive

Indicates whether inactive children should be included in the calculation.
Returns
Type Description
bool

True if bounds were successfully computed from Renderers or Colliders; otherwise, false.

TryGetOrAddComponent<T>(GameObject, out T)

Attempts to retrieve a component of type T from the given obj. If the component is not found, it is added to the GameObject. Returns false if obj is null.

Declaration
public static bool TryGetOrAddComponent<T>(GameObject obj, out T component) where T : Component
Parameters
Type Name Description
GameObject obj

The GameObject from which to get or add the component.
T component

When this method returns, contains the existing or newly added component of type T, or null if obj is null.
Returns
Type Description
bool

True if the component was successfully retrieved or added; false if obj is null.
Type Parameters
Name Description
T

See Also