Character interaction component

The character interaction component is the part a character carries to use things. It is the class UCISCharacterInteractionComponent. It keeps track of the objects whose actors overlap its triggers, selects the one the character can use now, runs the hold when the player presses the use button, and runs the use itself. It reports each step through delegates that Blueprints can bind.

What it does

• It finds objects. A trigger component of the character, named in Trigger Components, overlaps a component of an object; the object is then tracked. Put one object component on an actor: the character tracks only the first one of an actor.
• It selects one object at a time. The object with the highest score among those the character can use now becomes the best object. The score comes from the tests of Tests to Determine Object for Use, described on Choosing the object.
• It runs the use. A press of the use button starts a hold for the object’s use time. When the hold ends, the object’s Action runs; a release or a second press can interrupt it, as the settings of the object say.
• It answers queries from Blueprints, such as whether an object can be used now, the hold’s progress and the phase of the current use.

The component starts only when the character is locally controlled, so a character that another player controls on this machine has no interaction of its own.

How it works

Triggers and tracking. InitInteractionTriggers replaces the triggers that the component listens to. The settings’ Trigger Components are the default set, bound when the component starts. An object is in reach for the component while one of the triggers overlaps a component of the object’s actor. An object with several components stays tracked while any of them is inside a trigger.

Data objects. For each tracked object, the component creates a data object: the character’s own view of that object. Its class is the object’s Data Object Class when Override Data Object Class is on; otherwise the character’s Data Object Class; otherwise UCISInteractionDataObject. A data object exists only on the machine of the player who controls the character, so its Blueprint events, such as a hint or an icon, run only for that player.

The object is visible to the character only when it is in reach, faces the character, is usable, nobody uses it, and it passes its Visible Conditions. An icon follows this rule. The best object, and the demo HUD’s prompt with it, also needs every Usable Condition to pass.

Best object. Every Update Current Use Object Interval seconds, the component looks for the best usable object and stores it. When the best object changes, OnBestObjectForUseChangedDelegate runs. The use button uses this stored object if it can still be used; otherwise it looks for a new one.

Cleanup. Every Time to Clear Invalid Objects Data seconds, the component removes the data of objects whose component or data object is no longer valid, and the data of objects that no longer overlap a trigger. An object that is in use stays tracked until its use ends.

The hold. TryUseObject starts the hold. It does nothing when the character already uses or holds an object, and when no usable object is selected. The hold lasts the object’s Override Object Use Time when that is on, otherwise the character’s Time to Use Object. A hold with a use time of 0 is complete at once. When the hold is complete and the object is still usable, OnStartUseObjectDelegate runs and the use starts. Until then, GetDelayedObjectProgress gives the hold’s progress from 0 to 1. The hold’s time counts only while the object is tracked and usable for the character; when that stops, the hold is cleared without a use.

Ending the hold. TryInterruptObjectUsing clears the hold, whatever the interruption type it receives. A running use is interrupted only when the object’s Object Interruption Type equals the type the call sends: Interrupt After Release Button or Interrupt After Second Press Button. Connect the release of the use button to TryInterruptObjectUsing, as Your own character does, so that letting go cancels a hold.

Delegates. OnDelayedObjectDataSet runs when a hold starts. OnClearDelayedObjectData runs whenever the hold data is removed: after a release or another interruption, when the object stops being usable, and also right after a completed hold has started its use. Use it to hide a hold progress bar. OnStartUseObjectDelegate runs when a use starts, and OnEndUseObjectDelegate when it ends. OnBestObjectForUseChangedDelegate runs when the best object changes. All five run only on the machine of the player who controls the character. The server and other players do not receive them for this character; use the object’s OnObjectStateChangedDelegate for something every machine must react to.

Multiplayer. The component replicates by default. Its current use is replicated, and the server checks the use requests of remote clients: the distance, the angle, the side, the usable flag, the Conditions and the length of the hold. A refused use is reported in the Output Log, as the Troubleshooting guide explains. The object’s state reaches other players only when the object’s actor replicates; see Object for multiplayer. The overview of the network settings is on the Multiplayer page.

Set it up

The steps are in the guide, so this page gives only the outline. Follow Your own character:

1. Add the component to your Character Blueprint, add a trigger, and set Trigger Components to that trigger (its steps 1 and 2).
2. Set Interaction Angle and Time to Use Object under the component’s settings (its step 3).
3. Connect the use button to TryUseObject and TryInterruptObjectUsing (its step 4), and test it (its step 5).

Use it

• Call TryUseObject when the use button is pressed, and TryInterruptObjectUsing with Interrupt After Release Button when it is released. Call TryInterruptObjectUsing with Interrupt After Second Press Button when a press should interrupt a running use. These are the calls the guide’s Event Graph makes.
• Ask the state with IsCanUseObject (is this object usable for this character now), GetCountOfUsableObjects, IsCharacterUseAnyObject, GetCurrentUsingObject, GetUsableInteractObject (picks the best usable object now) and GetDelayedObjectProgress (for a progress bar of the hold).
• GetActiveUsePhase gives the phase of the current use: Holding, Pending, Moving, Acting or Ending, and None when no use runs. IsHasDelayedObjectData tells whether a hold is pending.
• Bind the delegates in the Blueprint of the character to show a hint or a prompt when a use starts or ends. They run only on the machine that controls the character.
• In the editor (play in editor or standalone from the editor), the With Debug setting under Settings › Debug draws the view cone of the character and shows the names of the overlapped objects on the screen. It does nothing in a packaged game.

Key settings

Settings
Character Interaction Settings
Interaction Angle	45.0
Time to Use Object	0.0
Trigger Components	0 Array element
Tests to Determine Object for Use	1 Array element
Index [ 0 ]	CISUseObjectTest_ObjectPriority
Time to Clear Invalid Objects Data	90.0
Update Current Use Object Interval	0.1
Data Object Class	CISInteractionDataObject
Debug
With Debug

The settings of the character interaction component. The Character Interaction Settings struct holds the values that the component reads; the defaults show the values a new component starts with.

Setting	What it does	Default
Interaction Angle	The angle the character sees objects in. An object is usable when its point lies within half of this angle from the character’s forward direction.	45
Time to Use Object	How long the use button is held before the use starts. An object’s Override Object Use Time replaces it when that is on.	0
Trigger Components	The components of the character that find objects. An object is found only while one of them overlaps a component of the object.	Empty
Tests to Determine Object for Use	The tests that score the objects in reach. Their scores are added.	UCISUseObjectTest_ObjectPriority
Time to Clear Invalid Objects Data	The interval, in seconds, of the cleanup of the data of invalid or no longer overlapped objects.	90
Update Current Use Object Interval	The interval, in seconds, at which the component picks the best object for use.	0.1
Data Object Class	The data object that the character gives each tracked object, when the object does not override it.	UCISInteractionDataObject
With Debug (Settings › Debug)	In the editor, draws the view cone of the character and writes the names of the overlapped objects on the screen. It does nothing in a packaged game.	Off

Check that it works

• Walk up to BP_MySwitch from Quick start, or your own object, and face it. With the 0.25 s of Your own character, hold the use button: the switch changes state when the hold ends. Release before that: the use is cancelled.
• In the editor, turn on With Debug under Settings › Debug, play, and walk near the object. The character’s view cone is drawn, and the object’s name appears on the screen while the object is in reach. It does nothing in a packaged game.

Troubleshooting

• The use button does nothing. TryUseObject does nothing while the character already uses or holds an object, and when no usable object is selected. Follow the checks of Troubleshooting, which start with the use button and the trigger.
• The hold ends too soon or never ends. The hold lasts the object’s Override Object Use Time when that is on, otherwise Time to Use Object. A release that the project sends to TryInterruptObjectUsing always cancels a hold. The hold also cancels by itself when the object stops being usable for the character, for example when the character steps out of reach, turns away, or a Condition turns false.
• A running use is not interrupted by the button. The object’s Object Interruption Type must equal the type of the call. A press or a release of another type does not interrupt it.
• The warning Component '<name>' (<class>) not found on <actor> (class <class>). Select the component again in the settings. appears. A Trigger Components entry, or another component reference, names a component the actor does not have. An empty reference writes no warning. The warning appears once for each actor class and component name until the editor restarts. See Component references.
• The server refuses the use with BadAngle. The character does not face the object within half of Interaction Angle, or the object’s own angle, plus Angle Tolerance Degrees of the project’s network settings.
• The icon or the prompt does not show. The object must be in reach, face the character, be usable, nobody may use it, and pass its Visible Conditions. The prompt also needs every Usable Condition to pass. See Data objects.
• Other players do not see the object change. The object’s actor must replicate. See Object for multiplayer.