Node Queries

Description

This feature is available under the Logic panel of the Asset Editor, and it allows users to execute a search for specific graph nodes in the given hierarchy. The search can be based on different matching criteria, such as Node Tags, partial name-matching, or type of nodes. The result of this search is then stored, and can be reused at any point in the logic. This means that users can also speed up certain logic commands by re-using the result of this search multiple times, avoiding the need to execute the exact same search repeatedly in different rules. Node Queries can be referenced in the following Actions: Set Visibility, Set Model, Set Material, Set Property, and Custom Code.

Creating, Editing and Deleting

Node Queries can be created through the Logic panel UI of the Asset Editor.

CreatingNodeQueries.gif

Users will need to click on the Queries Panel, and then click on the New Query button located at the bottom of the panel.

Once a Query has been created, its contents are always visible and available for editing.

To remove a Query from the list, simply click on the trashcan icon located beside the Query title.

The Query Examples rollout at the top of the Queries panel offers some basic guidance on how to use the Select and From query fields.

Properties

Title	This is the title of the Query, and it will be used to identify the Query in Actions where Queries may be used.
Filter Type	This option allows the user to filter the search by node type. The list includes all currently available node types that can appear in Scenes or Model Assets. Users can use multiple filters at a time. The default value is Empty, and it represents "All Filter Types", which means that the search will return any type of nodes that it finds matching the criteria specified in the other properties. Removing all filters will return to the "All Filter Types" option.
Select	In this box, the user must specify the matching criteria for the search, in terms of Node name or Node Tags. Name Search Entering any piece of text here not preceeded by a # sybmol will result in a text entry that will be used for partial name matching. The ? and * wildcards are also accepted in this context. A ? wildcard can be used to match any single characters. A * wildcard can be used to match any number of characters. For example, a search for Leg_? might yield results such as Leg_A, or Leg_B, but not results such as Leg_Left or Leg_Right. In those cases, a search for Leg_* will find those results as well. Tag Search To search for Nodes by Node Tag, the user must type in the tag names preceeded by the # symbol. The user must press the Enter key on the keyboard after every tag, in order to add it to the list. For example #Wood #Legs.
From	This entry box allows the user to specify where the search needs to be performed. By default, this box is Empty, which means that the search will be performed across all nodes inside the current hierarchy. Users can also choose to restrict the search across specific nodes inside the current Asset, by filtering them using several options: Query Choose to use the results from an existing Node Query. Node The user could choose specific nodes from the current Asset hierarchy, by selecting them from the dropdown list. It is also acceptable to enter part-name text searches, following the same rules as described above, under the the Select property. Tag Choose specific Node Tags from the dropdown list, or enter your own Node Tags to restrict the search only to those Nodes in the current Asset's Hierarchy that are tagged with these Node Tags.
Recursive Search Across References	This option allows the users to choose whether to perform a recursive search across all nested and referenced assets, or only within the current Asset's hierarchy. ON - Perform the search across the entire hierarchy, across all referenced assets and their children. OFF - Perform the search only within this current Asset's scene graph. Within this example hierarchy, a search performed inside the Current Asset for all mesh type nodes will yield the following results: Recursive Search = ON Result: ShadowPlane, Cushion, Pillows, Arms, Legs_Mesh, LampShade, LampSupport. Recursive Search = OFF Result: ShadowPlane

Usage Example

Let's have a look at an example where the users can configure different sofas and chairs, with the option to see different fabrics on these products. On one hand, the setup would involve logic rules on each individual 3D model, to set the mesh material to the incoming fabric option. Setting up these rules on dozens of models would be a tedious process to do manually, or require a developer to write a script in order to automate.

CLASSIC WORKFLOW

On the other hand, the logic for assigning the fabric material to the meshes could be done inside a single template 3D model, which then swaps out the meshes themselves. For this purpose we could use the name-based Node Query, and ensure that all nodes in the hierarchy follow a naming convention that would allow us to quickly identify the meshes that need the fabric material applied to them.

NODE QUERY WORKFLOW

For example, if we named all the mesh nodes that need to receive the fabric material with a prefix Fabric_, such as Fabric_Cushion, Fabric_Arms, Fabric_Back, etc, then we could use a Node Query inside the template 3D asset to search for all meshes that include Fabric_* in their name.

The result of this query can then be used inside an action that will set the material of these meshes to the incoming Fabric attribute.

This approach will make it much simpler to maintain and update the logic, without the need to add node-tags or logic inside each uploaded model. The only requirement is to remain consistent with the naming convention.