Data objects

A data object is the character’s own view of one interaction object. It is the class UCISInteractionDataObject. The character creates one for each object that comes into reach of its triggers, and it decides for that character which side of the object is used, whether the object is visible and usable, and how a use runs. At each step it raises a Blueprint event, so a Blueprint can show a hint or an icon for that one player. The data object is the place for what only the player sees; what every machine must see belongs to the interaction object component.

What it does

• It is the character’s view of one object. Each object the character tracks has its own data object.
• It chooses the side of the object that the character stands in. A side counts only when it has an Action for the object’s current state.
• It decides each tick whether the object is visible and whether it is usable for this character. The object’s Visible Conditions and Usable Conditions decide that, together with the reach, the facing and the object’s own usable flag.
• It raises Blueprint events at each stage: the start and the end of the overlap, each change of visibility and usability, the start and the end of a use, and the movement and the Action of the use.
• It exists only on the machine of the player who controls the character. Its events run only there, so a hint or an icon that the data object draws is seen only by that player.

How it works

Where it exists. The character’s interaction component starts only when the character is locally controlled. Its data objects are created by that component, so they exist only on the machine of the player who controls the character. The server and the other players have none for this character, and no data object event runs there.

Creation. A data object is created the first time the component of an object begins to overlap one of the character’s triggers. The character keeps one data object for each object component, and it initialises the new one at once, which runs OnInitialized. The class of the data object is the object’s Data Object Class when Override Data Object Class is on and that class is set; with the override on and no class, the character’s class is used. Otherwise it is the character’s Data Object Class, and otherwise UCISInteractionDataObject.

Lifetime. The character’s periodic clean-up removes the data object of an object that no longer overlaps its triggers, at the interval of Time to Clear Invalid Objects Data. It does not remove the data object during a use. The next overlap creates a new data object, which runs OnInitialized again, so a variable kept in a data object starts again from its default.

Overlap. OnOverlapped runs when the overlap starts, with bOverlap true, and when it ends, with bOverlap false. It runs only when the state changes.

Each tick. While the character is tracking an object, its data object runs on every tick. It chooses the side first. Then it sets its visibility from the Visible Conditions, and its usability from the Usable Conditions. The object is visible only when it is in reach, the character faces it, it is usable, nobody uses it, the character is not using any object, and every Visible Condition passes. The Usable Conditions are checked only while the object is visible. The reach is the flat distance of Interaction Distance. The facing is within half of the character’s Interaction Angle, or of the object’s own Override Character Interaction Angle when that is on.

Events on a change. OnVisibleChanged and OnUsableChanged run only when the value changes. The first tick sets both values, so both events run then. When the side changes, the object is first set to not visible and not usable, and the events run if the values were not already false.

One use. A use starts an execution that calls the data object’s events in this order:

1. OnObjectUseStarted, when the use starts.
2. OnMovementStarted, when the side’s move handler starts.
3. OnMovementEnded, when the movement step completes.
4. OnObjectActionStarted, when the Action of the side starts.
5. OnObjectUseFinished, when the use ends, with bInterrupted set when the use was interrupted.

This is the order with the default Action Execution Type, StartAfterFinishMoveHandler, in which the Action starts only after the movement step completes. With StartParallelWithMoveHandler the Action starts together with the movement, so OnObjectActionStarted comes before OnMovementEnded. Without a move handler, OnMovementStarted does not run and OnMovementEnded runs at once. Without an Action for the state, OnObjectActionStarted does not run, and the use ends without it. OnObjectActionStarted also does not run when the Action does not run on the player’s machine (Server Only), and OnMovementStarted does not run when the move handler does not.

A movement that still runs when the use ends finishes after OnObjectUseFinished, and its OnMovementEnded runs then. An interruption, from the input or from the server’s refusal of the use, ends the use with bInterrupted set. The refusal reasons are in Troubleshooting.

Removal. When the character drops the data of an object, for example when the object is destroyed, the data object interrupts its use and sets itself to not visible and not usable.

In Blueprints. Each event receives the character, the character’s interaction component and the object’s interaction object component. OnObjectActionStarted also receives the Action. The default implementations do nothing. The three references are also read-only properties of the data object: CachedInteractionObjectComponent, CachedInteractionCharacter and CachedCharacterInteractionComponent.

The demo data object. The demo character uses BP_CISDataObject as its data object. Its Event Graph binds the events, and OnInitialized assigns its On Best Object for Use Changed delegate. Its icon is described on Widgets and icons. During a use, the demo data object changes the character’s movement and collision, and only for BP_CISCharacter: when the use starts it disables the character’s movement and makes the capsule ignore the WorldDynamic and Pawn channels, and when the use finishes it enables the movement and sets those channels back to block. On overlap it turns on the icon widget of the object, and it sets the icon’s usable flag from whether this object is the character’s best object for use.

The plugin also ships BP_CISDataObjectExample, an example data object that drives the icon of BP_CISBaseInteractableActor. During a use it disables the player’s input, and it enables the input when the use finishes; it does not touch the movement or the collision.

Set it up

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

1. Make a Blueprint from BP_CISDataObject, add the events you need and set the data object’s behaviour, as Lever and locked door does in its step 3.
2. Give one object its data object with Override Data Object Class, as the same step does, or give the character its Data Object Class, as step 3 of Your own character does.

Use it

• Put what only the player should see in the events. A hint, an icon or a sound for that player belongs in OnObjectUseStarted, OnObjectActionStarted or OnObjectUseFinished, and each runs only on the player’s machine. OnObjectActionStarted runs only when the Action runs on the player’s machine, so not with Server Only.
• Show or hide an icon in OnVisibleChanged and OnUsableChanged. Both run on the first tick, and then only when the value changes.
• Read bInterrupted in OnObjectUseFinished to tell a finished use from an interrupted one.
• Use the object’s own events, such as On Object State Changed Delegate, for anything that every machine must see, and set the state on the server as the interaction object component describes.

Key settings

The data object has no settings of its own. The table names the settings that choose its class and decide which of its events run.

Setting	What it does	Default
Data Object Class (character)	The data object the character gives each tracked object, when the object does not override it.	UCISInteractionDataObject
Override Data Object Class (object)	When on, Data Object Class of the object replaces the character’s class for this object.	Off
Data Object Class (object)	The data object class for this object, used when the override is on.	None
Visible Conditions (object)	The conditions that must all pass before the object is visible to the character.	Empty
Usable Conditions (object)	The conditions that must all pass before the object is usable for the character. Checked only while the object is visible.	Empty

Check that it works

• In the demo, press E on the locked door from the front, as Lever and locked door shows. The hint DOOR IS LOCKED appears on the screen of that player, which is the event of the door’s data object.

Troubleshooting

• The event does not run on the server or for another player. The data object exists only on the machine of the player who controls the character. Put what every player must see in the object’s events, as the interaction object component describes.
• No event runs when the character walks up. The data object is created only when the object’s component begins to overlap one of the character’s triggers. Check the trigger and the overlapping component, as the first checks of Troubleshooting describe.
• OnVisibleChanged or OnUsableChanged runs once and then not again. Both run only when the value changes. Check the conditions and the reach, the facing and the usable flag that decide the value.
• The icon does not show with the default class. UCISInteractionDataObject draws nothing: its OnVisibleChanged event does nothing by default. Set Data Object Class to a Blueprint that draws the icon, as Troubleshooting describes for the demo’s icon.
• The hint shows for the wrong object, or not at all. Check Override Data Object Class and Data Object Class on that object, as Lever and locked door does in step 3.
• OnObjectUseFinished reports bInterrupted for a use that the player started. The input interrupted the use, or the server refused it. A refused use ends as interrupted, and the reason is in the Output Log, as Troubleshooting lists.