Core concepts

The guides use a small set of names. This page says what each one does, so that the steps of the guides make sense. The API reference lists every member.

Character and object

A character that uses things carries a UCISCharacterInteractionComponent. It tracks the objects that overlap its triggers, picks the one the character may use, and runs the hold and the use when the player calls UCISCharacterInteractionComponent::TryUseObject. Its Trigger Components name the components that find objects: an object is found only while one of these triggers overlaps a component of the object. The component starts only on the machine that controls the character: the local player’s machine, or the server for an AI that is possessed before it begins play.

An object carries a UCISInteractionObjectComponent, added to any actor that can be used. The component holds the object’s sides, its state, its usable flag and, for each side, the MoveHandler and the Actions.

For each object that a character tracks, the plugin creates a data object: the character’s own view of that object. It works out which side the character uses, and on every tick it sets the object’s visibility. The object is visible only while it is in reach, faces the character, is usable and passes its Visible Conditions. Its usability follows the Usable Conditions. 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.

Sides

A side is one entry of Interaction Sides. It has a range of angles around the object, a MoveHandler and its Actions. The angles turn about the object’s vertical axis from its forward direction, and a positive angle turns towards its right. A side is the smaller arc between its two angles. With Angle Side on, the side is the rest of the circle. With both angles at 0 and Angle Side on, the object can be used from every direction.

A character can use an object only when all three of these hold:

• Interaction Distance (300 by default): the flat distance from the object’s actor to the character’s feet is at most this value. Height is ignored.
• The character stands within the side: the centre of the character lies inside the side’s arc.
• The character faces the object: the flat angle between its forward direction and the object’s point is at most half of Interaction Angle. Interaction Angle is 45 by default, so 22.5 degrees to each side. When Override Character Interaction Angle is on, the object’s own angle is used. The point is the socket of the object’s Angle Detection Component, or its root when none is set.

States

An object’s state is a gameplay tag, read with GetObjectState. The object starts in its Initial Object State, which the server sets when the game begins.

SetObjectState changes the state. On the server the change is stored and sent to every machine. On a client, the change stays on that machine and the Output Log warns once. OnObjectStateChangedDelegate runs on every machine when the state changes; on clients it runs when the replicated state arrives. Code that changes the state should run on the server, behind an Is Server branch, as the lever guide does.

A side has one Action entry for each state it can be used in. Each entry sets a Required State Tag, and a use runs the first entry whose tag equals the current state. An empty tag matches an empty state. When no entry matches, the object cannot be used in its current state, and a server refusal says NoActionForState.

Actions, MoveHandlers and Conditions

• An Action (UCISInteractionObjectAction) is what a use does, such as playing a montage, a sound, or picking up an item. Its StartInteractionObjectAction event runs when the Action starts. The use lasts until the Action calls FinishAction. Then, when Set New State After Finish Action is on (the default), the object takes New State After Finish Action, and the OnUseFinished event runs.
• A MoveHandler (UCISInteractionObjectMoveHandler) brings the character to the place where the Action happens, such as the front of a door. Its StartMovement event begins the move, and FinishMovement ends it.
• Action Execution Type on a side (ECISActionExecutionType) sets when the Action starts. StartAfterFinishMoveHandler, the default, starts it when the movement has finished. StartParallelWithMoveHandler starts it together with the movement.
• A Condition (UCISInteractionObjectCondition) is a check. Its CheckCondition returns true or false. Visible Conditions decide whether the object is visible to the character. Usable Conditions decide whether the character can use it now, and they are checked only while the object is visible.

Choosing the object

A character can have several objects in reach. It uses the one with the highest total score among the objects it can use at that moment. Each test in Tests to Determine Object for Use gives a score of at least 0, multiplied by its TestMultiplier, and the scores of all tests are added. The default test, UCISUseObjectTest_ObjectPriority, scores an object by its Object Priority, a whole number from 0 to 10. When the top totals are equal, which of those objects wins is not defined.

Phases of a use

A use runs in phases. GetActiveUsePhase reports the current one, and None means that no use runs.

Phase	Meaning
Holding	The use button is held for the use time of the object.
Pending	The request was sent; the server has not answered yet.
Moving	The MoveHandler brings the character to the object.
Acting	The Action runs.
Ending	The use is finishing (end or interruption).

Pending is set on a remote client for the moment its use request leaves. The use then runs at once, and the server’s answer follows.

Where the code runs

• The object component replicates only when its actor replicates. In Class Defaults, under Replication, turn on Replicates; a new Actor Blueprint has it off. The Object for multiplayer guide shows the step.
• The settings of an object are not replicated. Every machine reads its own copy, built from the same class defaults or Blueprint. The state, the usable flag and the use state are replicated.
• Net Execution Policy of an Action or a MoveHandler sets the machines it runs on during a use. The default, All Machines, runs it on every machine. Local Predicted runs it on the player’s machine and on the server, and whichever of the two completes the step first leads it. Server Only runs it on the server only. Local Only runs it on the player’s machine only.
• A data object exists only on the machine of the player who controls the character.
• The server checks the use requests of remote clients against the distance, the angle, the side, the usable flag, the Conditions and the hold time. This is controlled by the project setting Server Validation. A standalone game, a listen host’s own character and characters that the server runs are not checked.
• A Condition’s Server Validation sets whether the server also checks it. Default checks a Blueprint Condition and does not check a C++ one. Validate always checks it. Do Not Validate leaves the check to the player’s machine.
• By default, an Action or a MoveHandler written in Blueprint runs on a new copy for each use, and a C++ class keeps one copy per object. A Blueprint class that has its own RPCs or replicated properties keeps one copy per object as well.

The Multiplayer page covers these settings in full.

Next

• Quick start: a switch with two states, with no code.
• Two-sided door: a door with a walk to each side.
• Troubleshooting: what to check when an object does not respond.