Appearance
Queries and duplicates
A descriptor describes what you register. A query describes which entries a consumer needs.
Registration descriptors
| Field | Meaning |
|---|---|
| Key | Optional FName lookup identity. None is not added to the key index. |
| Tags | Gameplay Tags copied onto this entry. |
| Priority | Higher values come first in priority sorting. Default 0. |
| Duplicate Policy | How 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.
| Policy | Collision behavior |
|---|---|
| Allow Many | Add another entry. |
| Reject | Return an invalid handle and preserve the existing entries. |
| Replace | Remove matching entries, then insert the new entry. Old handles become invalid. |
| Keep Highest Priority | Refuse 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
| Field | Behavior |
|---|---|
| Object Class | Class or interface; classes include subclasses unless Exact Type is enabled. |
| Required Interface | An additional interface requirement alongside the object class. Supports Blueprint implementations. |
| Struct Type | Type token for struct entries. Object Class takes precedence when both are set. |
| Key | Exact key filter. None in the full query means unrestricted. |
| Required Tags | All must match the same registration. Hierarchical by default. |
| Excluded Tags | Reject matching entries, also hierarchical by default. |
| Tag Query | Optional Gameplay Tag expression after indexed filtering. |
| Exact Type | Disable subclass/child-struct matching; not used for interface checks. |
| Exact Tag Match | Match explicit tag identities instead of parent/child matching. |
| Sort Mode | None, Priority Then Oldest, or Priority Then Newest. |
| Max Results | Limit 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.