GoQL Overview

Introduction

GoQL is an abbreviation for "GameObject Query Language". It is used to construct sets of GameObjects from the scene hierarchy.
The API takes a single query string as a parameter, and returns a set of GameObjects that match that query.

Structure

A GoQL query is composed using name filters, indexers, discriminators, descenders, and exclusions.
This sounds complicated, but the syntax is similar to directory paths and filenames.

Name Filters

The name of a GameObject can be specified directly. E.g.:

Head

will match all GameObjects that are named "Head".

A name filter can also use wildcards at the beginning, middle, or end of the name, e.g.:

GoQL Description
*Head All GameObjects that have names ending with "Head".
Head* All GameObjects that have names beginning with "Head".
*Head* All GameObjects that contain the string "Head" anywhere in their names.
H*d All GameObjects that begin with "H" and end with "d".

Note that a name filter will look for matching GameObjects in the current applicable set.
Initially, the current applicable set is global, and will contain all objects in the hierarchy.
This applicable set can be changed by using a descender.

Currently, middle wildcards have the following limitations:

  1. Only one middle wildcard is allowed in each applicable set, e.g.:
  • /H*d/C*d is supported, but
  • /H*d*Tail is not supported
  1. A middle wildcard can't be used together with either a beginning or ending wildcard in the same applicable set, e.g.:
  • /*d/C*d/T* is supported, but
  • /*d*T* is not supported

Descenders

A descender is defined by a slash character (/).

When GoQL reads this symbol, it will narrow the search down into the children of the current applicable set.
If it is the first character of the GoQL string, it will match all root objects in the scene.

A double asterisk (**) is a special descender, which matches all descendants of the applicable set.

Examples:

GoQL Description
/Head Any GameObjects named "Head" that are in the root of the hierarchy.
Head/ All immediate children of any GameObjects named "Head".

Indexers

An indexer will filter the current set using a numerical index which can be an individual index or a range of indexes.
E.g.:

GoQL Description
Head/[0] The first child of all GameObjects named "Head".
Head/[0,1,5] The children with specified indexes of all GameObjects named "Head", if they exist.
Head/[-1] The last child of all GameObjects named "Head".
Head/[3:5] The children of GameObjects named "Head" that have indexes betweeen 3 and 5 (exclusive).

Discriminators

A discriminator is used to filter the current set by checking for the existence of a particular component, material or shader, or if it is active or inactive.
Discriminators are specified using angle brackets and one of these codes:

  1. 't': component
  2. 'm': material
  3. 's': shader
  4. 'active': is the gameobject enabled?

Examples:

GoQL Description
Head<t:Collider> All GameObjects named "Head" which also have a Collider component.
Head<m:Glow> All GameObjects that are named "Head" and use materials named "Glow"
Head<s:Standard> All GameObjects that are named "Head" and are using "Standard" shader.
<active:false> All **GameObjects that are inactive.

Exclusions

An exclusion is defined by an exclamation point (!), and allows us to exclude certain GameObjects returned by the query.
The syntax differs slightly based on which GoQL element it is applied to as follows:

Element Syntax
Name filters Put ! before a name filter to exclude GameObjects that match the name filter, e.g.: !Foo.
Indexers Put ! inside the indexer, e.g..: /[0:10,!5].
Discriminators Put ! inside the discriminator, e.g.: <!t:MeshFilter>.

Examples:

GoQL Description
!Head* All GameObjects that do not have names beginning with "Head"
Hea*!*d All GameObjects which names begin with "Hea", but don't end with "d"
Hea*!Heat All GameObjects which names begin with "Hea", but are not "Heat"
Hea*!Heat!Head All GameObjects which names begin with "Hea", but are neither "Heat" nor "Head"
!H*d All GameObjects which names neither begin with "H" nor end with "d"
[0:3,!0,!1] All GameObjects, in which each is the 3rd child of another GameObject.
<t:Collider><!t:MeshFilter> All GameObjects which have Collider components, but don't have any MeshFilter component.

Other Examples

GoQL Description
/ All root GameObjects.
Quad* All GameObjects which have names beginning with "Quad".
Quad*/<t:AudioSource>[1] The second child with AudioSource of all GameObjects which have names beginning with "Quad".
<t:Transform, t:AudioSource> All GameObjects that have Transform and AudioSource components.
<t:Renderer>/*Audio*/[0:3] The first 3 children of all GameObjects which:
* have parent GameObjects with Renderer components.
* have "Audio" in their names
Cube/Quad/<t:AudioSource>[-1] From each GameObject named "Cube", select children that have names starting with "Quad", then select the last grandchild that has an AudioSource component.
<m:Skin> All GameObjects that use materials named "Skin".
/Env/**<t:MeshRenderer> All descendants of root GameObjects named "Env" that have MeshRenderer components.
/!*Head* Root GameObjects that don't have "Head" anywhere
/!*ead/!C* From root GameObjects that don't have names ending with "ead", select their children which don't start with "C"
/Head/!Cube/* From root GameObjects which names are "Head", select their children which are not named "Cube", then select their children.
/Head*!*Unit All root GameObjects which names start with "Head", but do not end with "Unit".

Quick Search Integration

When a project uses Quick Search package, or is using Unity 2021.2 or newer, then GoQL can also be used in the Quick Search window to look for GameObjects in the scene hierarchy.