Runtime Components¶

The core actor components that make an actor interactive.

MovaIxComponent¶

class UMovaIxComponent : public UActorComponent¶

Main Component that makes any Actor interactive.

Add this Component to any Actor (Blueprint or C++) to give it full interactive capabilities:

ActionCycles, ActionGroups, ActionStates
Proximity detection
Hit response
Widget prompts

Networking:

Owning Actor must have bReplicates = true and a Net Role of ROLE_Authority on the server.
Actions executed on the server are replicated to all clients via ReplicatedActionStates.
Clients call Server_ExecuteAction() to request an Action. Server validates and runs it.
Transform replication for animated Components is handled by the Actor's own replication (set the Actor's bReplicateMovement = true, or use RepMovement on individual Components).

Public Functions

UMovaIxComponent()¶

bool CanExecuteGroup(const FName &GroupName) const¶

Execution gate checked before every Action Group runs.

False makes it a no-op.
Default: true.

Parameters:: GroupName -- Action Group about to run.

bool CanExecuteGroup_Implementation(const FName &GroupName) const¶

void CompleteAction(const FName &GroupName)¶

Marks the currently playing Action as completed and broadcasts OnActionCompleted.

Parameters:: GroupName -- Name of the Action Group to complete.

void DetectCycleIndex(const FName &CycleName)¶

Auto-detects a cycle's step from the Component's current pose.

No match leaves the current step unchanged.

Parameters:: CycleName -- Name of a cycle defined in the ActionCycles map.

bool ExecuteAction(const FName &ActionName, const FName &TargetName, bool bSimulateAction = false)¶

Attempts to execute a named Action by searching cycles then Groups.

Starts the first available cycle or Group if no name is provided.
On the server this runs locally and replicates to clients.
On a client this is a no-op, call Server_ExecuteAction() instead.

Parameters:

ActionName -- Identifier for a specific interaction (ex: "Toggle", "Open", "Press").
TargetName -- Optional Target name for targeted Actions.
bSimulateAction -- Skips running the Action and only simulates it, to populate data.

Returns:

True if a valid Action was found and initiated.

bool ExecuteActionCycle(const FName &CycleName)¶

Executes a specific sequence of Action Groups in order.

Parameters:: CycleName -- Name of a cycle defined in the ActionCycles map.
Returns:: True if a cycle exists and playback started.

bool ExecuteActionGroup(const FName &GroupName)¶

Triggers a Group of parallel animations and effects immediately.

Parameters:: GroupName -- Name of a Group defined in the ActionGroups map.
Returns:: True if a Group exists and playback started.

void ExecuteInteraction(const FMovaIxPoint &InteractivePoint, int32 ChoiceIndex = 0, bool bSimulateAction = false)¶

Executes the interaction logic associated with a specific choice index.

Use 0 for Primary Interaction (default), 1 for Secondary, etc.

Parameters:

InteractivePoint -- Concrete interaction point containing the Targets to trigger.
ChoiceIndex -- Index of the 'Choice' ('>' tag) to trigger from the point Targets.
bSimulateAction -- Skips running the Action and only simulates it, to populate data.

void ExecuteTags(const TArray<FName> &Tags, bool bSimulateAction = false)¶

Runs a list of raw interaction tag strings (ex: "!Open @Drawer1"), like a tagged interaction.

Each entry is parsed into an ad-hoc interaction point and dispatched via ExecuteInteraction.
On the server this runs locally and replicates.
On a client call Server_ExecuteTags() instead.

Parameters:

Tags -- Tag expressions to run, one interaction each.
bSimulateAction -- Skips running the Action and only simulates it, to populate data.

float GetActionConfirmTime(const FName &ActionName, const FName &TargetName) const¶

Returns the hold-to-confirm time for the Group an Action runs next.

For a cycle this is the Group at the current step.
0 = execute instantly (no hold required).

Parameters:

ActionName -- Base Action name (ex: "Toggle").
TargetName -- Optional Target token used to locate the per-Target runtime Group/cycle.

TArray<AActor*> GetCarriedActors(FName GroupName) const¶

Which Actors a running Group is currently carrying, per bCarryObjects.

Empty when the Group is unknown, not playing, or carried nothing.
Each Actor appears once even if several of its primitives were caught.

Parameters:: GroupName -- Group in the ActionGroups map.
Returns:: Distinct Actors currently attached to that Group's Targets.

int32 GetCarriedObjectCount(FName GroupName) const¶

How many objects a running Group is currently carrying, per bCarryObjects.

0 when the Group is unknown, not playing, or carried nothing.

Parameters:: GroupName -- Group in the ActionGroups map.
Returns:: Total carried objects across that Group's Actions.

FName GetComponentState(USceneComponent *Component) const¶

Returns the named resting State a Component currently sits in, or None.

Local first, then falls back to the Component's owning Actor's IC.

Parameters:: Component -- Component whose resting State is queried.

int32 GetCycleIndex(const FName &CycleName) const¶

Returns the current step index of a runtime cycle.

Parameters:: CycleName -- Name of a cycle defined in the ActionCycles map.
Returns:: CurrentIndex of the cycle, or -1 if it is missing.

FName GetNextActionVerb(const FName &ActionName, const FName &TargetName) const¶

Returns the verb to advertise for an Action: the next Group an ActionCycle will run.

For a "Toggle" cycle of [Open, Close] this returns "Open", then "Close", etc.
Falls back to ActionName itself when it is not a cycle.

Parameters:

ActionName -- Base Action name (ex: "Toggle").
TargetName -- Optional Target token used to locate the per-Target runtime cycle.

Returns:

Display verb for the next interaction.

bool IsActionInteractable(const FName &ActionName, const FName &TargetName) const¶

Whether the Group an Action runs next is currently triggerable, per its RepeatPolicy.

Resolves the same cycle-aware "next Group" as GetActionConfirmTime/GetNextActionVerb.
A missing Group (ex: an unresolved verb) returns true, since there is nothing to block.
Default prompt hides/greys a choice this returns false for.

Parameters:

ActionName -- Base Action name (ex: "Open").
TargetName -- Optional Target token used to locate the per-Target runtime Group/cycle.

bool IsActionInteractable(const FName &ActionName, const FName &TargetName, FText &OutBlockedReason) const¶

Same as IsActionInteractable, plus the reason in words when it returns false.

Reads either a Gate that fails (More.Gates) or the RepeatPolicy end-pose block. Whichever the resolved Group's own IsInteractable() reports first.
Not BlueprintCallable: FText* out-params are not Blueprint-friendly. C++ callers, ex: the default prompt's BuildPromptChoices, use this one. Blueprint keeps the bool-only version.

Parameters:

ActionName -- Base Action name (ex: "Open").
TargetName -- Optional Target token used to locate the per-Target runtime Group/cycle.
OutBlockedReason -- On a false return, the first reason it fails, in words. Untouched otherwise.

bool IsRemoteActorInReach(const AActor *RemoteActor) const¶

True when RemoteActor is close enough for this IC's remote ('^') signal to reach it.

RemoteMaxDistance <= 0 (the default) means unlimited => always true.
From Actor origin to Actor origin.

Parameters:: RemoteActor -- Candidate Target Actor. Null returns true, there is nothing to reject.
Returns:: True when the signal reaches it.

bool IsStateConditionMet(const FName &Condition)¶

Evaluates one State condition under the addressing grammar (see GRAMMAR.md).

":State": this IC's own CurrentStates.
"Address:State", ex: "@Lock:Off" or "%Lock@Bolt:Locked": the address's resolved Component rests in State.
":!State" negates the whole test.
A token with no ':' is treated as this IC's own State name.

Parameters:: Condition -- Condition token to evaluate.
Returns:: True when the condition is currently satisfied.

void SetActionGroupTime(const FName &GroupName, float Time)¶

Scrubs a Group to an absolute time in seconds (clamped to the Group's own duration).

Parameters:

GroupName -- Group in the ActionGroups map.
Time -- Seconds, 0..Group duration.

void SetComponentMovingState(USceneComponent *Component, const FName &StateName)¶

Records that Component is moving to StateName, as "~StateName".

Cleared once it settles.

Parameters:

Component -- Target being animated.
StateName -- Destination State, stored prefixed with '~'.

void SetCycleIndex(const FName &CycleName, int32 NewIndex)¶

Manually sets a runtime cycle's step index, clamped to a valid Group slot.

Fallback when DetectCycleIndex cannot infer the pose.

Parameters:

CycleName -- Name of a cycle defined in the ActionCycles map.
NewIndex -- Desired step, clamped to [0, Groups.Num()-1].

void StopGroupsOverlapping(const TArray<USceneComponent*> &ControlComps, bool bImmediate, const FName &ExcludeGroup)¶

Stops running Groups whose animated Components overlap ControlComps, smoothly or instantly.

Scopes a stop to one instance (ex: #Open:@Drawer1) without touching siblings @Drawer2 / @Drawer3.

Parameters:

ControlComps -- Components the control Action resolved to, empty stops nothing.
bImmediate -- True stops immediately, false coasts via RampOutTime, or eases via StopSpeedFactor.
ExcludeGroup -- Runtime Group key to skip, the control Group issuing the stop.

void StopRunningActions(bool bImmediate, const TSet<USceneComponent*> &Components)¶

Forcefully cancels all currently running animations and procedural effects.

Parameters:

bImmediate -- True stops immediately, false uses a smooth stop.
Components -- If defined, only stop Groups involving these Components.

inline const TSet<FName> &GetCurrentStates() const¶: Resting named State of every Target Component, the same names a Gate's ":State" tests.

const TArray<FMovaIxPoint> &GetInteractivePoints()¶

Returns the interactive points, recalculated if the object has moved.

Returns:: Array of interactive points.

inline FVector GetPointOffset() const¶

Actor-local offset applied to every interactive point.

What camera focus lifts toward (ex: eye level).

int32 GetTargetCount(const USceneComponent *Component)¶

Number of Actions, across every Group, whose resolved Target Components include Component.

Warms the runtime Actions the same way ExecuteAction does, resolving wildcards / tags / special names.
Ex: "!OpenLeft @DoorLeft" and "!OpenRight @Door*" both resolving to DoorLeft counts as 2.

inline bool HasAnyAction() const¶: True if this IC defines any interaction (an ActionGroup, Cycle, or State).

bool Hit(const FVector &HitLocation = FVector::ZeroVector, const FVector &HitDirection = FVector::ZeroVector, float HitStrength = 1.0f)¶

Hits or punches an Actor with InteractiveComponent.

Parameters:

HitLocation -- World coordinates where an impact occurred.
HitDirection -- World directional vector of an incoming force.
HitStrength -- How hard the hit is.

Returns:

True if a hit response was triggered.

void InvalidatePreparedData()¶

Rebuilds the runtime Action maps from the written ActionCycles / ActionGroups / ActionStates.

Call after writing those directly, ex: copying Actions onto a Blueprint template.

bool ShouldCollapse() const¶

Resolves whether this IC folds its points into one multi-choice query.

Collapse::Always or Never overrides the project's bCollapseInteractions setting.

void WarmAllInteractionChoices(const FName &OnlyGroupName = NAME_None)¶

Editor-only: warms ActionGroupsEx. => A Group has a runtime entry before it is drawn or Tested.

Parameters:: OnlyGroupName -- None warms every Group and Cycle key, a specific name warms only that one.

bool IsAuthority() const¶

Returns true if this Component is running with server authority.

Only the server should initiate new Actions, clients request via Server_ExecuteAction().

void Multicast_StartActionGroup(const FName &BaseName, const FName &BaseTarget, float ElapsedTime)¶

Multicast RPC fired by the server to start a Group on all clients.

Called automatically inside ExecuteActionGroup() on the authority.

Parameters:

BaseName -- Original Action name before target-key combination.
BaseTarget -- Original Target name before target-key combination.
ElapsedTime -- Server-side elapsed time at broadcast, normally 0.0.

void Multicast_StopActionGroup(const FName &GroupName, bool bImmediate)¶

Multicast RPC fired by the server to tell all clients to stop a Group.

Parameters:

GroupName -- Group to stop.
bImmediate -- Whether to snap or smooth-stop.

void OnRep_ActionStates()¶: Called on clients when ReplicatedActionStates changes.

void Server_ExecuteAction(const FName &ActionName, const FName &TargetName)¶

Called by a client to ask the server to execute an Action.

Result replicates to all connected clients.

Parameters:

ActionName -- Action identifier (ex: "Open", "Toggle").
TargetName -- Optional sub-Target name.

void Server_ExecuteInteraction(int32 ChoiceIndex, FName AnchorComponentName)¶

Client RPC: asks the server to run ExecuteInteraction() for a specific choice.

Result replicates to all connected clients.

Parameters:

ChoiceIndex -- Index of the Choice ('>' tag) to trigger.
AnchorComponentName -- FName of the SceneComponent that anchors the interaction point.

void Server_ExecuteTags(const TArray<FName> &Tags)¶

Client RPC: asks the server to run ExecuteTags(). => Resulting Actions replicate to all clients.

Parameters:: Tags -- Tag expressions to run (ex: "!Open @Drawer1").

void ApplySaveState(const struct FMovaIxActorSave &In)¶: Applies a saved snapshot: Component transforms/visibility, current States, cycle indices.

void CaptureSaveState(struct FMovaIxActorSave &Out) const¶: Captures a snapshot of this object's runtime State for SaveGame.

void RestoreCarriedObjects(const struct FMovaIxActorSave &In)¶

Re-attaches the objects a save recorded as carried, replacing whatever the reload's rescan found.

Parameters:: In -- Actor record being applied.

void ParseComponentTags(USceneComponent *Component, const TArray<FString> &Tokens, bool &bOutSkipRoot)¶

Parses a list of string tokens into the internal InteractivePoints cache.

Processes prefixes like '!', '>', and '+' to define Actions and flow.

Parameters:

Component -- Component these tokens belong to.
Tokens -- List of space-separated strings extracted from tags.
bOutSkipRoot -- True when a '=' prefix is found, meaning the Root fallback should be ignored.

FVector ResolvePointLocation(USceneComponent *Component, const FVector &LocalOffset) const¶

Returns the world location an interaction point should sit at.

An explicit Component-space offset from a "$X,Y,Z" tag always wins.
Otherwise the visual center when bAutoCenterPoints is on, else the pivot.

Parameters:

Component -- Component the point is anchored to.
LocalOffset -- Component-space offset, zero when the tag gave none.

Returns:

World location for the point.

TArray<USceneComponent*> ResolveTargetComponents(const FName &TargetName)¶

Resolves a Target name into zero or more SceneComponents.

Supports the full unified syntax:

"@Light" or "Light" -> Internal Components
"%Elevator" -> External Actors
"%Elevator|Cage" -> External Actor + sub-Component
"^Control|Screen" -> Remote + sub-Target.

Parameters:: TargetName -- Target spec in the unified syntax listed in this comment.

inline void SetInteractInstigator(AActor *Actor)¶

Sets the Actor currently interacting with this object. => A "#Actor" Target resolves to it.

Call this right before ExecuteInteraction/ExecuteAction (the player Component does this automatically).

Public Members

TMap<FName, FMovaIxActionCycle> ActionCycles¶: Map of interaction sequences that step over multiple Groups.

TMap<FName, FMovaIxActionGroup> ActionGroups¶: Map of parallel Action definitions.

TMap<FName, FMovaIxActionState> ActionStates¶: Library of reusable State snapshots for Keyframes.

FMovaIxProximity Proximity¶: Self-contained proximity config: shape + size + placement + Enter/Leave tags, driven from overlaps.

bool bAutoDetectCyclesOnBeginPlay = true¶

Auto-run DetectCycleIndex for every cycle at BeginPlay.

A door/lever/switch placed already in its end pose self-syncs its next interaction.

float RemoteMaxDistance = 0.0f¶

Max reach for this object's remote ('^') control, a signal to a farther Target Actor is ignored.

From this Actor to the remote Target Actor.
0 = unlimited (the default).

bool bAllowChildInteractions = true¶

Allows ICs on attached child Actors to be detected/triggered.

Set false on a parent (ex: a control panel) to suppress every IC on an attached descendant Actor.

EMovaIxCollapse Collapse = EMovaIxCollapse::FromSettings¶

Whether this interactable folds its several interaction points into one multi-choice query.

Helps aim-free selection: aim roughly at the Actor, then pick from a list.
A Component tagged "#unique" opts out => it stays its own aim-selected point.

FOnActionSignature OnActionCompleted¶: Called when an Action fully completes.

FOnActionRejectedSignature OnActionRejected¶

Called with a reason whenever ExecuteActionGroup refuses to run a Group instead of starting it.

Ex: a Gate that fails, a RepeatPolicy block, or the Group already busy.

FOnActionReplicatedSignature OnActionReplicated¶: Broadcast when a replicated Action State is received from the server.

FOnActionSignature OnActionStarted¶: Called when an Action or cycle starts execution.

FOnActionSignature OnActionStopped¶: Called when an Action was stopped or interrupted.

FOnActionTickSignature OnActionTick¶: Called every frame while an Action is playing.

FOnHitSignature OnHit¶: Called when a physical hit occurs.

FOnKeyframeSignature OnKeyframeReached¶: Called when a Keyframe is reached.

TMap<TPair<FName, FName>, uint8> LastSeenChangeCounters¶

Last ChangeCounter this client has already reacted to, keyed by (BaseName, BaseTarget).

Guards OnRep_ActionStates() against re-triggering a finished Group on every array-level OnRep.

bool bReplicateActions = true¶

Whether this Component should replicate its Action State to clients.

Set to false on purely cosmetic Actors that don't need synchronization.

TArray<FMovaIxReplicatedActionState> ReplicatedActionStates¶: Server-authoritative list of running Action States, replicated to all clients.

bool bTypeable = false¶

Marks this object as a typing surface (a keyboard / keypad).

Interactor can enter "Interaction Mode" on it, capturing the full keyboard.
KeyActionGroup is the Action Group run per key (ex: "Key").
KeyTargetPrefix + the key label names the Target Component (ex: prefix "Key_" + "A" -> "Key_A").

FName KeyActionGroup = TEXT("Key")¶: Action Group to run for each typed key (default "Key", matching the laptop's per-key dip+light Group).

TMap<FName, FName> KeyCommands¶

Optional command map for typing mode: key label -> a tag expression to run on this object.

A hit runs the mapped tag via ExecuteTags().
A miss falls back to the per-key Component path ("<KeyTargetPrefix><label>").

FString KeyTargetPrefix = TEXT("Key_")¶

Prefix of the per-key Component names.

Key label is appended (ex: "Key_" + "Return" -> "Key_Return").

Public Static Functions

static FString GetCycleStepLabel(const FName &Step)¶

Display label from a Cycle step, ex: "(Turn on)" at its start or end.

Prompt shows this instead of the resolved verb.

Parameters:: Step -- Cycle step, a plain Group name or a full Tag.
Returns:: Label text, brackets removed.

static FName GetCycleStepVerb(const FName &Step)¶

Verb a cycle step runs on this IC, for a plain Group name or a full Tag.

NAME_None when the step's verb is delegated elsewhere, ex: "!Open %Door^".
A "(Label)" at either end is ignored here, see GetCycleStepLabel.

static bool IsCycleStepTag(const FName &Step)¶: True when a cycle step is a Tag, not a plain Group name.

static FMovaIxPoint CollapseInteractivePoints(const TArray<FMovaIxPoint> &Points)¶

Merges several interaction points into one Choice-flow point for a collapsed multi-choice query.

Each source point's first Action becomes a Choice entry.
Its remaining Actions become Extensions => they run with that entry.

Parameters:: Points -- Source points to fold, ex: an Actor's per-drawer points.
Returns:: One merged point whose ActionTargets are the choices.

static UMovaIxComponent *FindInActor(AActor *Actor)¶

Finds the first InteractiveComponent inside an Actor.

Parameters:: Actor -- Actor to search in.
Returns:: InteractiveComponent if found, otherwise nullptr.

static TArray<USceneComponent*> FindTargetComponents(const AActor *OwningActor, const FName &EqualTarget)¶

Resolves an interaction Target token to Components on OwningActor (wildcards * ?, tag match, then name match).

Static: other systems, ex: Mova learnables, reuse the exact same matching the Action Targets use.

Protected Functions

virtual void BeginPlay() override¶

virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override¶

virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty> &OutLifetimeProps) const override¶: UActorComponent interface: registers replication of subobjects.

virtual void TickComponent(float DeltaTime, ELevelTick TickType, FActorComponentTickFunction *ThisTickFunction) override¶

Protected Attributes

TMap<FName, FMovaIxActionCycle> ActionCyclesEx¶: Internal processed copy of ActionCycles.

TMap<FName, FMovaIxActionGroup> ActionGroupsEx¶: Internal processed copy of ActionGroups.

TMap<FName, FMovaIxActionState> ActionStatesEx¶: Internal processed copy of ActionStates.

bool bAutoPointOnRoot = true¶

Auto-creates a detectable interaction point on the Actor Root when no tagged point produced one.

Set false for an IC that owns Actions but must not be focused via its Root (its tagged points still work).

bool bDetectable = true¶

Master detection switch: when false the IC produces no interaction points at all (tagged or auto Root). => Player cannot focus it.

Its ActionGroups still execute when invoked externally (ex: an elevator called only by remote buttons).

float HitRayLength = 1000.0f¶: Maximum raycast length for hit detection.

EMovaIxHitType HitType = EMovaIxHitType::Root¶: Controls how the Hit() function selects the affected Component.

bool bAutoCenterPoints = true¶

Aims interaction points at each Component's visual center instead of its pivot.

Only applies where no explicit "$X,Y,Z" tag offset was given, which always wins.
Components with no renderable geometry are left on their origin, having no center.

FVector PointOffset = FVector::ZeroVector¶

Actor-local offset added to every interactive point, applied after each point is placed.

An IC with Actions but no tagged Component gets a point on the Actor Root, using this offset.
Also useful as a whole-Actor nudge, ex: raising every point on a Character to eye level.
Actor space: does not follow a Component that rotates.

TArray<FMovaIxPoint> InteractivePoints¶: Points that the player can interact with.

TMap<TObjectPtr<USceneComponent>, FName> ComponentStates¶

Resting named State of each Target Component (one State per Target).

Feeds CurrentStates. Rebuilt whenever a Target settles on a Keyframe State.

TSet<FName> CurrentStates¶: Flat union of ComponentStates values, read by IsStateConditionMet() to evaluate Gates.

TMap<FName, FMovaIxSceneComponents> TargetComponents¶: All resolved Target Components: supports multiple (ex: many lights with same tag).

MovaIxGrabComponent¶

Full member listing and tunables: Grab API.

MovaIxInteractorComponent¶

Full member listing, triggering functions, and radial menu API: Interactor API.

MovaIxProximity¶

Enums

enum class EMovaIxProximityShape : uint8¶

Proximity-volume shape the IC uses to drive its proximity tags from overlaps.

Values:

enumerator None¶

No volume.

Only the interactor-driven proximity applies, when there is one.

enumerator Box¶: Auto-create a box collision on this Actor, sized and placed by the relative transform + extent.

enumerator Sphere¶: Auto-create a sphere collision on this Actor, sized and placed by the relative transform + radius.

enumerator Volume¶: Bind to every existing volume Actor tagged with VolumeTag. Several is fine.

struct FMovaIxProximity¶

#include <MovaIxProximity.h>

Full proximity config for one IC, driving the Enter/Leave tags directly from overlaps.

NO interaction points needed.
Only a pawn carrying a UMovaIxInteractorComponent triggers it.
Box / Sphere: the IC auto-creates a hidden collision on this Actor at the relative transform.
Volume: binds to every level volume Actor tagged with VolumeTag.

Public Members

TArray<FName> EnterTags¶

Tag expressions run when a player enters detection range, each like a tagged interaction. Empty = disabled.

Ex: "!Open @Drawer1" for an auto-door.

TArray<FName> LeaveTags¶: Tag expressions run when a player leaves detection range, each like a tagged interaction. Empty = disabled.

EMovaIxProximityShape Shape = EMovaIxProximityShape::None ¶: Auto-volume shape driving the Enter/Leave tags from overlaps.

FVector BoxExtent = FVector(200.0f, 200.0f, 100.0f)¶: Half-size of the auto Box.

float SphereRadius = 300.0f¶: Radius of the auto Sphere.

FVector RelativeLocation = FVector::ZeroVector¶: Location of the auto Box/Sphere, relative to the Actor pivot.

FRotator RelativeRotation = FRotator::ZeroRotator¶: Rotation of the auto Box, relative to the Actor pivot. A sphere ignores rotation.

FName VolumeTag¶

Actor tag for the level volumes to bind when Shape is Volume.

Every Actor with this tag binds.