Efficiently traverse hierarchy and append GameObject.

All methods are extension of GameObject, using Cute.Linq then you can use all extension methods.

using Cute.Linq;

var root = GameObject.Find("root");
var cube = Resources.Load("Prefabs/PrefabCube") as GameObject;

// add do attach parent, set same layer and fix localPosition/Scale/Rotation.
// added child is cloned and returns child object.
var clone = root.Add(cube);

// choose sibling position and allow append multiple objects.
var clones = root.AddAfterSelfRange(new[] { cube, cube, cube });

// destroy do check null.
root.Destroy();

Add method's child is cloned. It is useful for instantiate prefab scenario. If you want to move only child, you can use(MoveToLast, MoveToFirst, MoveToBeforeSelf, MoveToAfterSelf) and (MoveToLastRange, MoveToFirstRange, MoveToBeforeSelfRange, MoveToAfterSelfRange) instead of Add.

All traverse methods can find inactive object. If not found, return type is GameObject methods return null, return type is IEnumerable<GameObject> methods return empty sequence.

Descendants has descendIntoChildren overload, it stops traverse children when does not match condition.

Operate methods have four optional parameter. cloneType configure cloned child GameObject's localPosition/Scale/Rotation, default copies original local transform. setActive configure activates/deactivates child GameObject. If null, doesn't set specified value. specifiedName configure set name of child GameObject. If null, doesn't set specified value. setLayer configure set child GameObject's layer same with parent, default doesn't set layer.

There are TransformCloneType that used Add methods.

If target is RectTransform always use SetParent(parent, false) and ignores TransformCloneType

MoveTo methods similar with Add but don't clone target.

There are TransformMoveType that used MoveTo methods.

If target is RectTransform always use SetParent(parent, false) and ignores TransformMoveType

IEnumerable<GameObject> Extensions. If multiple GameObjects in the source collection have the same GameObject will be included multiple times in the result collection. To avoid this, use the Distinct(LINQ to Objects) method.

The concept of LINQ to GameObject is axis on tree.

Every traverse method returns IEnumerable<GameObject> and deferred exectuion. For example

origin.Ancestors();   // Container, Root
origin.Children();    // Sphere_A, Sphere_B, Group, Sphere_A, Sphere_B
origin.Descendants(); // Sphere_A, Sphere_B, Group, P1, Group, Sphere_B, P2, Sphere_A, Sphere_B
origin.BeforeSelf(); // C1, C2
origin.AfterSelf();  // C3, C4

You can chain query(LINQ to Objects) and use some specified methods(Destroy, OfComponent and others).

// destroy all filtered(tag == "foobar") objects
root.Descendants().Where(x => x.tag == "foobar").Destroy();

// destroy all cloned objects
origin.transform.root.gameObject
    .Descendants()
    .Where(x => x.name.EndsWith("(Clone)"))
    .Destroy();

// get FooScript under self childer objects and self
var fooScripts = root.ChildrenAndSelf().OfComponent<FooScript>();

Note: LINQ to GameObject is optimized for iteration, returns struct enumerable and struct enumerator instead of IEnumerable<GameObject>.

LINQ to GameObject is optimized heavily. Traverse methods returns hand optimized struct enumerator so it can avoid garbage when enumerate.

Some LINQ methods are optimized. First, FirstOrDefault, ToArray path through the optimized path.

LINQ to GameObject also provides ToArrayNonAlloc. It is like Physics.RaycastNonAlloc or void GetComponentsInChildren<T>(List<T> results) and reuse List<T>. You can reuse array for no garbage.

GameObject[] array = new GameObject[0];

// travese on every update but no allocate memory
void Update()
{
    var size = origin.Children().ToArrayNonAlloc(ref array);
    for (int i = 0; i < size; i++)
    {
        var element = array[i];
    }
}

ToArray and ToArrayNonAlloc have five overloads. (), (Func<GameObject, T> selector), (Func<GameObject, bool> filter), (Func<GameObject, bool> filter, Func<GameObject, T> selector), (Func<GameObject, TState> let, Func<TState, bool> filter, Func<TState, T> selector) for Optimize Where().Select().ToArray() pattern.

If you use simple iteration or use ForEach or ToArrayNonAlloc, LINQ to GameObject guarantees no gc allocate and performance is very fast.

If you use DescendantsAndSelf().OfComponent<T>(), it may possible to substitude GetComponentsInChildren<T> that is always fast than LINQ traverse(because LINQ traverse can not have native magics). So you can substitude native methods, use it. If you needs other query, use LINQ.

Descendants(AndSelf) returns single Component on each GameObject, GetComponentsInChildren returns multiple Component on each GameObject, so behaviour is different. LINQ to GameObject's Descendants is heavily optimized, internal iterator of ForEach and ToArray is specialize tuned.