SYSTEMSINTERACTION OBJECT COMPONENT

Interaction object component

The interaction object component is the part an actor carries to be used by a character. It is the class UCISInteractionObjectComponent. It holds the object’s state, its usable flag and its sides, and each side lists the action that runs in each state. It also reports the use through delegates that Blueprints can bind. The character’s character interaction component finds the object and runs the use.

What it does

It makes an actor usable. Add the component to the actor. The character finds the actor while one of its trigger components overlaps a component of the actor.
It holds the object’s state, a gameplay tag such as CIS.Object.Door.Closed. The state decides which action a side runs.
It holds the object’s sides. A side is a range of directions around the object. Each side has its own move handler and its own list of actions, one entry for each state.
It holds the Usable flag, which a Blueprint can turn off, and it reports who uses the object at the moment.
It raises delegates for a change of state and for the start and the end of a use. A Blueprint binds them, and they run on the machines where the event happens.

How it works

State. The state is a FGameplayTag, which GetObjectState returns. On the server, the component sets Initial Object State when the actor begins play. SetObjectState changes the state and fires On Object State Changed Delegate. On the server it fires only when the new state differs from the current one.

Who may change the state. Call SetObjectState on the server. An object that the player does not control is a simulated proxy on each client, and it stays one while the client’s controller owns the actor during a use. On such a copy, SetObjectState changes only that copy, and the Output Log warns once. Only an actor that a client controls as an autonomous proxy, such as its own pawn, sends the call to the server. So put the code that changes the state behind an Is Server branch.

Replication. The state replicates. On the other machines, On Object State Changed Delegate fires when the replicated value arrives. An Action’s New State After Finish Action is set on every machine that runs the action, so there the delegate fires when the action finishes. If the replicated value arrives after that, it is the same, and it fires nothing. If it arrives first, the delegate fires for it and again when the action finishes, so make the code you bind safe to run twice with the same state. The component replicates by default, but only when its actor replicates. In Class Defaults, under Replication, turn on Replicates. A new Actor Blueprint has it off, and then other players never see the state.

Sides. A side is a range of yaw angles around the object, measured from its forward direction. A positive angle turns towards the object’s right. The side is the smaller arc between Interaction Angle Min and Interaction Angle Max. With Angle Side on, it is the rest of the circle. With both angles at 0 and Angle Side on, the object can be used from every direction, as Quick start sets it up.

When a character is in reach, its data object picks the first side the character stands in that has an action for the current state.

Actions and states. Each side lists its actions as entries. Each entry has a Required State Tag. The side’s action is the first entry whose tag equals the object’s state. An empty tag matches only an empty state. When no entry matches, the side is not offered to the character. A server refusal with ECISUseRejectReason::NoActionForState means the server’s copy of the object is in another state than the player’s.

When an action finishes, it sets its New State After Finish Action, if Set New State After Finish Action is on, which is the default. An interrupted action does not set it. Action Execution Type decides when the action starts: after the side’s move handler finishes, which is the default, or together with the move handler.

A use lasts until its action calls FinishAction. Max Use Duration ends a longer use as interrupted. The default, 0, means no limit. The limit is applied only on the machine that has authority over the character: a standalone game, a listen host or the server. A pure client does not time its own use.

Reach, distance and angle. The object can be used when the character is within Interaction Distance of the object. The distance is flat: it is measured in two dimensions from the object’s actor to the character’s feet. The default is 300.

The character must also face the object. Its forward direction must lie within half of the character’s Interaction Angle on either side of the direction to the point it faces. The default angle is 45. The object can replace the character’s angle with its own Override Character Interaction Angle, so 180 is a cone of 90° to each side. The point the character faces is the socket of Angle Detection Component, or the root of the object’s actor when that is empty.

The player’s machine checks the side and the angle exactly. The server checks the same things with the tolerances of the project’s network settings: Angle Tolerance Degrees, Distance Tolerance Absolute and Distance Tolerance Scale. That is why a use can pass the server when the character stands slightly outside the exact limits. The Troubleshooting guide lists the refusal reasons.

Usable flag and conditions. Usable is a replicated flag. Call Set Usable on the server, as with the state. On a client’s copy that the client does not control, it changes only that copy, and the Output Log warns once. Is Object Usable reads the flag. A use is refused as ECISUseRejectReason::NotUsable while the flag is off, and the character sees the object only while it is usable. A Blueprint can also write the flag directly. Do that only when Manage Owner Dormancy is off, as described below.

Visible Conditions decide whether the object is visible to the character, which can show an icon. Usable Conditions decide whether the character can use it. The demo HUD’s prompt shows only for an object the character can use. The server checks again the conditions that are set to validate on the server, before it accepts a use. The Conditions page explains the classes.

Use state. The use state, which Get Use State returns, names the user of the object, the execution id, the side index and the phase of the use. The server sets it. On a client it is the replicated value, which can lag behind a predicted use. IsObjectOccupied (C++) is true while a user is set or the object is in use.

Owner during a use. With Transfer Ownership During Use on, which is the default, the actor’s owner becomes the user’s controller for the length of the use. The server gives the previous owner back when the use ends.

Dormancy. With Manage Owner Dormancy on, the actor rests dormant while nobody uses it. The option works only on an actor that replicates, on the machine with authority (a dedicated server or a listen host). It does nothing in a standalone game. The actor starts dormant at begin play only when it is awake, so a dormancy that you set yourself is kept. The server wakes the actor for a use, and lets it rest again one second after the use ends. The object state, the usable flag and the in-use flag still reach every client.

The option is off by default. Turn it on only for an object whose Blueprint or C++ code replicates no variables, multicasts or other network functions of its own, whose Blueprints do not write Usable directly, and whose dormancy no other code sets. Object for multiplayer, step 6, has the same rule.

Settings on each machine. Interaction Settings (the FCISInteractionObjectSettings struct) is set in the Blueprint’s class defaults and is not replicated. Each machine reads its own copy of the sides. A change made at run time changes only the copy of the machine that makes it.

Events. The delegates run on these machines:

On Object State Changed Delegate (OnObjectStateChangedDelegate) runs on every machine, with the new state.
On Use Started Delegate (OnUseStartedDelegate) runs on each machine where the use runs: the user’s machine, the server, and the other clients that show the use. It runs after the character’s data object fires OnObjectUseStarted, and before the move handler starts.
On Action Started Delegate (OnActionStartedDelegate) runs only on the machines that run the Action, as its Net Execution Policy says. With Server Only it does not run on clients, and with Local Only or Local Predicted it does not run on the other clients. It runs after the data object fires OnObjectActionStarted, and before the action starts.
On Use Finished Delegate (OnUseFinishedDelegate) runs on the same machines and passes bInterrupted. It runs after the data object fires OnObjectUseFinished and after the object is released. It does not run when the object component itself is gone.

Debug drawing. The sides are drawn in the editor, in the level viewport for the selected actor and in the Blueprint editor’s preview, and in play that starts from the editor. A packaged game draws nothing. Each side’s cone has the length of Interaction Distance. Each side has Enable Debug, Debug Color and Line Thickness.

Set it up

The steps are in the guides, so this page gives only the outline. Follow these guides in order:

Add the component to the actor, set Initial Object State and add the first side with its actions, as Quick start does in its steps 1 to 5.
Add the second side with its own move handler and actions, as Two-sided door does in its steps 3 and 4.
Pass the state to the object’s animation in the state-changed event, as Two-sided door does in its step 5.
For a game with more than one player, turn on Replicates in Class Defaults, as Object for multiplayer does in its step 1.

Use it

Change the state on the server only: call Set Object State behind an Is Server branch. Object for multiplayer, step 5, has the branch.
Read the state with Get Object State, and the settings with Get Settings.
Turn the object off with Set Usable on the server, and on again with the same call. The server refuses a use while the object is off. Is Object Usable tells you the flag’s value.
Bind On Object State Changed Delegate to move the object’s parts, for example to set the pose of an Animation Blueprint. The event runs on every machine.
Bind On Use Started Delegate, On Action Started Delegate and On Use Finished Delegate for sounds and effects that every machine shows. The finished event tells whether the use was interrupted. On Action Started Delegate fires only where the Action runs, so for a sound on every machine use On Use Started Delegate, or give the Action All Machines.
Read Get Use State to see who uses the object, and at which side and phase.
The side and action lookups GetSideByIndex, FindSideIndex, GetActionIndexForSide and GetObjectActionForSideIndex are C++ functions. Blueprints do not call them.

Key settings

Settings
Interaction Settings
Interaction Sides	0 Array element
Interaction Distance	300.0
Angle Detection Component
Override Character Interaction Angle
Override Character Interaction Angle	0.0
Object Interruption Type	None
Override Object Use Time
Override Object Use Time	0.0
Visible Conditions	0 Array element
Usable Conditions	0 Array element
Override Data Object Class
Data Object Class	None
Object Priority	0
Transfer Ownership During Use
Manage Owner Dormancy
Max Use Duration	0.0
Initial Object State
Usable
Debug
With Debug in Game
With Debug in Editor
Debug Lines Depth Priority	0

The settings of the interaction object component. Its Interaction Settings struct holds the sides and the object's options, and the defaults are the values a new component starts with.

The Interaction Settings members are set in the class defaults only. Initial Object State, Usable and the debug settings can also be set on a placed actor. The table names the editor labels.

Setting	What it does	Default	Where it is set
Initial Object State	The state the object has when the actor begins play on the server.	Empty	Class defaults or a placed actor
Usable	Whether the object can be used at all. The server refuses a use while it is off.	On	Class defaults or a placed actor
Interaction Sides	The sides of the object. Each side has its angles, its move handler, its actions, its action execution type and its debug data.	Empty	Class defaults
Interaction Distance	The flat distance from the object’s actor to the character’s feet within which the object can be used.	300	Class defaults
Angle Detection Component	The component and socket the character faces. Empty: the root of the object’s actor.	Empty	Class defaults
Override Character Interaction Angle (checkbox)	When on, the value replaces the character’s Interaction Angle. The character faces the object within half of this angle.	Off, 0	Class defaults
Object Interruption Type	Which call interrupts a running use: none, `InterruptAfterReleaseButton` (the release of the use button) or `InterruptAfterSecondPressButton` (a second press). Your input has to call `TryInterruptObjectUsing` with that type, and the call interrupts only when the types match.	None	Class defaults
Override Object Use Time (checkbox)	When on, the value replaces the character’s Time to Use Object for this object.	Off, 0	Class defaults
Visible Conditions	The conditions that must pass for the character to see the object, with its icon.	Empty	Class defaults
Usable Conditions	The conditions that must pass for the character to use the object.	Empty	Class defaults
Override Data Object Class (checkbox)	When on, the Data Object Class below replaces the character’s data object class for this object.	Off	Class defaults
Data Object Class	The data object class the character uses for this object, when the override is on.	None	Class defaults
Object Priority	The score that the default choosing test adds for this object, from 0 to 10.	0	Class defaults
Transfer Ownership During Use	The user’s controller owns the actor during a use. The server gives the previous owner back at the end.	On	Class defaults
Manage Owner Dormancy	The actor rests dormant while nobody uses it. Turn it on only in the cases described above.	Off	Class defaults
Max Use Duration	The longest use in seconds. A longer use ends as interrupted. 0 means no limit.	0	Class defaults
With Debug in Game (Settings › Debug)	Draws the sides during play. It does nothing in a packaged game.	Off	Class defaults or a placed actor
With Debug in Editor (Settings › Debug)	Draws the sides of the selected actor in the level viewport.	On	Class defaults or a placed actor
Debug Lines Depth Priority (Settings › Debug)	The depth priority of the debug lines: 0 draws them with the world, 1 in front of it. The code name keeps an older spelling, `DebugLinesDephPriority`.	0	Class defaults or a placed actor
Enable Debug, Debug Color and Line Thickness (each side)	Show the side’s cone, and set its colour and line width. These are the members of `FCISInteractionObjectSideDebugData`.	On, Yellow, 2	Class defaults

Check that it works

Walk to the object from the side you set up and press the use button. The object’s action runs and the state changes, as Quick start shows.
Select the actor in the level viewport. With With Debug in Editor on, which is the default, the cone of each side is drawn.
Turn on With Debug in Game, play, and walk around the object. Each side’s cone is drawn in the play window. The cones disappear in a packaged game.

Troubleshooting

The character never finds the object. The character finds the actor only while one of its trigger components overlaps a component of the actor. The actor needs a component with collision that generates overlap events. See Quick start, “If something is off”.
The character is near the object but nothing happens. The current state has no action for the side. The side’s action is the first entry whose Required State Tag equals the state, and an empty tag matches only an empty state. Check Initial Object State and each entry’s tag.
The character uses the wrong side, or no side. The angles are measured from the object’s forward direction, and a positive angle turns towards its right. The character uses the first side it stands in that has an action for the current state. Check the angles of each side, and the state of the object.
The object cannot be used at all. Its Usable flag is off, or its Usable Conditions fail. The character does not see an object that is not usable.
A use is refused online. The server refuses a use for a reason such as BadSide, BadAngle or NoActionForState. The sides are not replicated, so every machine must build them from the same class defaults. See Troubleshooting, “Works alone, fails online”.
Other players do not see the state change. The actor does not replicate. Turn on Replicates in Class Defaults. See Object for multiplayer.
The warning SetObjectState on <actor> called on a client appears. A client called Set Object State on its copy of the object, so only that copy changed. Run the call on the server.
The door or lever swings back when its animation ends. The animation does not get the state. Pass the state to the animation in the state-changed event, as Two-sided door does in its step 5.
The debug cones do not show in a packaged game. The cones are drawn only in the editor and in play that starts from it. This is by design.