This part is how a target is found, a simplified XML Path Language.

basic syntax: step/step/step...

for each step: axis::nodetest[predicate][predicate OR predicate]/othersteps...

Please note: powerful as the seems, there are many edge cases I have not covered yet. Report an issue if you face any.

nodetest

nodetest is like a path, use / to separate, // means any descendant

. means current object, .. means parent, * means any node.

nodetest always starts from the current object.

// `DirectChild` object under this object
[GetByXPath("/DirectChild")] public GameObject directChild;
// Search all children that starts with `StartsWith`,
// under which, search all children ends with `Child`
// and get all the direct children of that.
[GetByXPath("//StartsWith*//*Child/*")] public Transform[] searchChildren;

axis

axis redirect the target point

• ancestor::: all parents
• ancestor-or-self::: the object itself, and all it's parents.
• ancestor-inside-prefab::: all parents inside this prefab
• ancestor-or-self-inside-prefab::: the object itself, and all it's parents inside this prefab
• parent::: parent of the object
• parent-or-self::: the object itself, and it's parent
• parent-inside-prefab::: parent inside this prefab
• parent-or-self-inside-prefab::: this object itself, and it's parent inside this prefab
• scene::: root of the active scene
• prefab::: root of the current prefab
• resources::: Resources
• assets::: root folder Assets

// search all parents that starts with `Sub`
[GetByXPath("ancestor:://Sub*")] public Transform ancestorStartsWithSub;

// search object itself, and all it's parents, which contains `This`
[GetByXPath("ancestor-or-self::*This*")] public Transform[] parentsSelfWithThis;

// search current scene that ends with `Camera`
[GetByXPath("scene:://*Camera")] public Camera[] sceneCameras;

// get the first folder starts with `Issue`, and get all the prefabs
[GetByXPath("assets:://Issue*/*.prefab")] public GameObject[] prefabs;

attribute

attribute allows you to extract an attribute from a target, starting with a @ letter. Normally, {} means it can be directly executed on the target.

• @layer: Get the layer string name

• @{layer}: Get the layer mask (int)

• @{tag}: Get the tag value

• @{gameObject}: Get the gameObject (this is the default behavior)

• @{transform}: Get the transform

• @{rectTransform}: Get the RectTransform. This is just a shortcut ofGetComponent(RectTransform)

• @{activeSelf}/@{gameObject.activeSelf}

• @{GetComponent(MyScript)}/@{GetComponents(MyScript)[2]} Get a component from the target. You can continuously chain the calling like: @{GetComponents(MyComponent)[-1].MyFunction().someField['key']}.

  Please note: this is not an actual code executing, and with these limits:

  1. Parameters are not supported
  2. indexing for array/list is allowed
  3. indexing for dictionary only supports string key type, and single quote / double quote are the same

  GetComponent & GetComponents are a special function. You can pass type name. If you have multiple type with the same name, prefix it with some namespace is allowed: GetComponent(MyNameSpace.MyScript).

  Base class is allow allowed, but generic class is not supported.

• @{GetComponents()}: Get all components of the target

• @resource-path()

• @asset-path()

// 1.  search all the children which has `FunctionProvider` script, grab the first result
// 2.  call `GetTransforms()` as the results
// 3.  from the results, get first direct children named "ok"
[GetByXPath("//*@{GetComponent(FunctionProvider).GetTransforms()}/ok")] public GameObject[] getObjs;

// FunctionProvider.cs
public class FunctionProvider : MonoBehaviour
{
    // Example of returning some target
    public Transform[] GetTransforms() => transform.Cast<Transform>().ToArray();
}

filter

filter check if the results match the expected condition. There are two types of filter:

• index filter:

  either just use the index: child*[1] (second one), child*[last()]/child*[-1] (last one)

  or compared value: child*[index() > 3]

• value filter: use any attribute mentioned above, with >, != etc. for comparison. e.g. [@{gameObject.activeSelf}][@layer = "UI"]

using multiple filters means all conditions must be met. Otherwise, use the keyword OR: [@{GetComponent(Collider)} OR @{GetComponent(MyScript)}]

// find the first main camera in the scene
[GetByXPath("scene:://[@{tag} = MainCamera]")] public Camera mainCamera;

// find the prefabs with component "Hero"
[GetByXPath("assets:://Heros/*.prefab[@GetComponent(Hero)]")] public Camera mainCamera;