Skip to content
2.0Product documentation

Queries and duplicates ​

A descriptor describes what you register. A query describes which entries a consumer needs.

Registration descriptors ​

FieldMeaning
KeyOptional FName lookup identity. None is not added to the key index.
TagsGameplay Tags copied onto this entry.
PriorityHigher values come first in priority sorting. Default 0.
Duplicate PolicyHow collisions with an existing identity are handled.

A raw descriptor defaults to Allow Many. Participant component descriptors default to Replace. Choose deliberately when sharing keys across actors.

Duplicate identity ​

A non-empty key collides with every entry under that key in the same registry, across both objects and structs. The key is not implicitly namespaced by class.

With an empty key, object collisions refer to the same UObject instance. Struct collisions refer to the same struct type; payload values are not compared. Different actors with empty keys do not collide with one another.

PolicyCollision behavior
Allow ManyAdd another entry.
RejectReturn an invalid handle and preserve the existing entries.
ReplaceRemove matching entries, then insert the new entry. Old handles become invalid.
Keep Highest PriorityRefuse the new entry if any match has equal or greater priority; otherwise replace all matches.

SHARED KEYS

If every interactable uses Interact, use Allow Many to keep them all registered. Replace keeps only the latest registration under that shared key.

Query fields ​

FieldBehavior
Object ClassClass or interface; classes include subclasses unless Exact Type is enabled.
Required InterfaceAn additional interface requirement alongside the object class. Supports Blueprint implementations.
Struct TypeType token for struct entries. Object Class takes precedence when both are set.
KeyExact key filter. None in the full query means unrestricted.
Required TagsAll must match the same registration. Hierarchical by default.
Excluded TagsReject matching entries, also hierarchical by default.
Tag QueryOptional Gameplay Tag expression after indexed filtering.
Exact TypeDisable subclass/child-struct matching; not used for interface checks.
Exact Tag MatchMatch explicit tag identities instead of parent/child matching.
Sort ModeNone, Priority Then Oldest, or Priority Then Newest.
Max ResultsLimit after sorting; 0 means unlimited.

A registered Interaction.Open tag satisfies a requirement for Interaction unless exact matching is enabled. Tags from two registrations of one object are not combined to satisfy one query.

Objects versus registrations ​

Find All returns registration results, including separate entries for the same object. Find Objects returns unique live objects and applies the result limit after deduplication. Count Matches counts registrations including structs; Count Objects counts unique objects and excludes structs. Count/existence helpers ignore Max Results.

The shortcut by Key helpers treat an empty key as no match. by Tag helpers treat an invalid tag as no match. This differs from an unrestricted field in the full query.

Sorting and performance ​

Priority modes sort descending by priority; registration age breaks ties. None uses candidate index order, which should not be treated as a stable gameplay ordering contract. Actor queries add spatial rules; nearest and line traces have special ordering.

The registry indexes type, key, tag, and object identity. It selects a narrow candidate bucket when possible, then checks remaining filters. An unfiltered query can scan live entries. Use meaningful filters and profile frequent queries against your real population; no fixed performance guarantee is implied.

Multiple products. One knowledge base.