Interactor Responsibilities
UInteractionRuntimeInteractorComponent is the runtime object that turns world candidates into user-facing interaction state. It queries nearby target handles, chooses focus, builds visible surfaces, exposes paging and progress, and sends activation requests. The interactor is also the bridge between command input and prompt UI because the UI manager follows the local player interactor.
Focus Resolution
The interactor does not scan arbitrary actors. It asks UInteractionRuntimeWorldSubsystem for registered candidate handles, then evaluates each candidate against enabled state, range, point-of-interest behavior, command visibility, requirements, and view alignment. The current focused handle remains stable until a better candidate beats the configured margin and hold-time rules.
Visible Handles Versus Activatable Commands
A visible handle means the point is relevant enough to present. It does not guarantee that every command on that point can activate. A command may still be blocked by a requirement, a cooldown, busy state, route mismatch, disabled state, an invalid input phase, or authority validation. This is why UI should display runtime surface state instead of treating focus as permission to execute everything.
Surface Projection
A surface is the runtime command list for the current focus. It contains prompt entries, control entries, paging markers, progress state, route stage data, and payload references. Widget code should render the projected surface supplied by the interactor/UI layer rather than walking the target definition directly. Target definitions describe possible content; runtime surfaces describe what is currently valid for this interactor.
Activation Request Path
- The interactor has a focused handle and visible surface.
- The user input matches a command row, control entry, More marker, Back marker, hold phase, multi-tap phase, or cancellation control.
- The interactor requests activation for the selected surface or control entry.
- The authority path validates command identity, layout compatibility, requirements, cooldowns, busy state, route state, and snapshot tolerance.
- Execution actions run only after the command reaches the outcome they are configured to handle.
Paging
Large surfaces use command-row paging. RequestNextCommandPage and RequestPreviousCommandPage move through pages. More markers are presentation controls; they should not be treated as gameplay commands. If paging controls do not show, inspect the command surface size, marker rows, and input actions assigned to those marker rows.
Local Presentation State
Interactor-local variants and prompt presentation state are useful for local UI and owner-facing behavior. They should not replace target variant overrides for shared gameplay state. Use the target component when the target’s real state changes; use the interactor when the player-facing presentation changes for one interactor.
Debugging Checklist
- No focus: verify target registration, point id, point transform, range, view threshold, and enabled state.
- Focus without prompt: verify UI manager binding, widget class, projected surface entries, and prompt visibility policy.
- Prompt without activation: verify input action, command id, requirements, cooldown, busy state, route state, and authority.
- Wrong command: verify command row order, current page, More marker placement, and command ids.
For scoring details see Focus And Spatial Queries. For server validation and replication see Networking And Authority.
Input Phase Handling
Instant, hold, multi-tap, cancellation, More, and Back controls are all different user intents. The interactor tracks enough runtime state to send the correct request, but the target definition still needs the correct row kind, input pattern, input action, and command id. When an input does nothing, confirm the command row is on the current surface page and that the runtime surface entry maps to the input action being pressed.
Surface State Ownership
Widgets should not cache authored command definitions as the source of truth. The same authored command may be unavailable, hidden, on cooldown, in progress, or on a different page for this interactor. Cache visual row widgets if needed, but always update them from projected surface entries and control entries.
Interactor Debug Path
Debug the interactor from outside in: candidate handles, current focus, visible handles, current surface, current page, selected command entry, activation request, then server outcome. Stopping at the first missing layer tells you which owner to inspect next.