Actions

An Action is the part of a use that does the work on an object: it plays a sound, plays a montage on the character and on the object, or picks up an item. It is a class derived from UCISInteractionObjectAction. Each side of an interaction object lists one Action for each state the object can be in, and the use runs the Action of the object’s current state. The sides and their lists belong to the interaction object component.

What it does

• It does the work of a use on the object. The use starts it, and it ends the use when its code calls FinishAction. Until then the use does not end.
• It can set the object’s next state when it finishes. The next use then runs the Action that the new state selects.
• It runs on the machines that its Net Execution Policy names: every machine, the server only, the player’s machine only, or the player’s machine and the server.
• It has two Blueprint events: StartInteractionObjectAction, where its work begins, and OnUseFinished, which runs when the Action finishes, before the use ends.

How it works

Choosing the Action. Each side holds a list of entries. An entry has a Required State Tag and an Action. The side runs 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.

Start. The Action starts in the Acting phase of the use. With the default Action Execution Type of a side, StartAfterFinishMoveHandler, it starts when the side’s move handler finishes. With StartParallelWithMoveHandler, it starts together with the movement. See Move handlers.

Finish. FinishAction ends the Action, but only once the Action has started: a call before that does nothing. When the Action finishes, the plugin does two things on each machine that runs it. If the use was not interrupted and Set New State After Finish Action is on, it sets New State After Finish Action. Then it calls OnUseFinished, and the use ends. OnUseFinished runs when the Action finishes, also when it is interrupted, and before the use ends. On the leading machine the use ends right after it; a machine that does not lead the step ends its use when the leader’s end arrives. The state change is the plugin’s own, so it makes no warning in the log, and it reaches every machine that runs the Action.

Interruption. A use ends as interrupted, for example when the server rejects it, or when the input interrupts a use whose object has the matching Object Interruption Type. The use can also end as interrupted when the character or the object is gone. An interrupted Action sets no new state, and its OnUseFinished gets bWasInterrupted set to true. The Action can tell that the server rejected the use with WasRejectedByServer.

Where it runs. The Net Execution Policy decides the machines, and each machine that runs the Action follows the step leader of the use:

• All Machines, the default: every machine runs its own copy. The player’s machine leads the step, and the other machines run theirs when its phase arrives.
• Local Predicted: the player’s machine and the server both run it. Whichever completes the step first leads.
• Server Only: the server runs it, and no other machine does.
• Local Only: only the player’s machine runs it.

Prediction. With All Machines and Local Predicted, the player’s machine starts the Action before the server answers the use. IsLocallyPredicted is true on the client that runs the Action, which includes Local Only. With Server Only, no client runs the Action. A use that the server rejects ends as interrupted, as described above.

Instancing. Instancing Policy decides whether one object serves every use. SharedPerObject keeps the variables of the Action between uses. InstancedPerExecution makes a copy for each use on each machine, and the copy is released when the use ends. Default picks by the class: SharedPerObject for a C++ class and InstancedPerExecution for a Blueprint class. A class with its own RPCs or replicated properties always runs as SharedPerObject.

The state on other machines. The new state reaches every machine. The object’s state-changed delegate fires on each machine, and on a client when the replicated state arrives. See Interaction object component.

The demo Actions. The plugin ships these Actions:

• BP_PlaySoundAction plays its Sound where the object is. The demo sets Sound on each object.
• BP_InteractionObjectActionPlayMontage plays Montage On Character on the character and Montage On Object on the component named by Mesh Component On Object, at Play Rate.
• BP_InteractionObjectActionPickUp holds the pick-up montages in Pick Up Montages. The pick-up object of the demo destroys itself when its state becomes CIS.PickObject.Picked.
• BP_CodeLockAction runs only on the machine of the player who uses the code lock, because its Net Execution Policy is Local Only. It gives that player’s controller the input of the lock, and it calls Finish Action when the lock signals that the use is finished.
• BP_CISNullObjectAction, in the plugin’s general Blueprints folder, calls Finish Action at once and does nothing else.

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 UCISInteractionObjectAction, write its graph and set its values, as Your own Action does in its steps 1 to 4.
2. Put the Action in a side’s list, with the state it runs in as its Required State Tag, and set its New State After Finish Action, as Your own Action does in its step 5.
3. For a game with more than one player, choose the machines with Net Execution Policy and turn on Replicates on the actor, as Object for multiplayer does in its steps 1 and 3.

Use it

• Override StartInteractionObjectAction and call Finish Action when the work is done. The use does not end before that call.
• Set the next state with New State After Finish Action on the entry, not in the graph. The plugin sets it only when the use was not interrupted.
• Use OnUseFinished for clean-up only. It runs when the Action finishes, also when the use is interrupted, and bWasInterrupted tells which.
• Choose Net Execution Policy by who must see the Action. All Machines suits an effect that everyone sees, Server Only suits what must happen once, and Local Only suits what only one player should see.
• Ask the Action where it runs with Is Executing on Server, Is Locally Predicted, Is Simulated Execution and Was Rejected by Server. Get Execution Context returns the whole context.

Key settings

Settings
New State After Finish Action
Execution
Instancing Policy	Default
Net Execution Policy	All Machines
Replication
With Replication

The settings of an Action class: its state settings, its execution settings and its replication setting.

Setting	What it does	Default
Set New State After Finish Action	Whether the object takes New State After Finish Action when the Action finishes without an interruption.	On
New State After Finish Action	The state the object takes when the Action finishes, if the setting above is on.	Empty
Net Execution Policy	The machines the Action runs on: All Machines, Local Predicted, Server Only or Local Only.	All Machines
Instancing Policy	Whether one Action object serves every use (Shared Per Object) or a copy is made for each use (Instanced Per Execution). Default picks by the class.	Default
With Replication	Whether the Action’s own RPCs and replicated variables work over the network. Off: they run on the local machine only.	On

Check that it works

• Walk up to the demo switch from Quick start and press E. The switch clicks and changes state.
• With your own Action from Your own Action, the click plays at the switch, and the state changes when Finish Action runs.
• In a game with more than one player, both players hear the Action when it runs on every machine, as Object for multiplayer step 7 checks.

Troubleshooting

• The use never ends. The graph does not reach Finish Action, or it calls it before the Action has started, when the call does nothing. A use lasts until the Action finishes. Check that the event StartInteractionObjectAction reaches Finish Action.
• The state does not change. Set New State After Finish Action is off on the entry, or the use was interrupted, and an interrupted Action sets no state. Check bWasInterrupted in OnUseFinished.
• A sound or an effect is seen on one machine only. Its Net Execution Policy is Local Only, Server Only or Local Predicted, which run it on fewer machines. Set All Machines to show it everywhere.
• The Action keeps the values of the last use, or it loses them. Check Instancing Policy. A copy per use loses its variables after each use, and a shared object keeps them.
• The editor warns that the class runs as SharedPerObject. The Blueprint has its own RPCs or replicated properties, so the plugin does not copy it per use. Move the network code out of the Action, or accept that the object is shared.
• A use is refused online. The server writes the reason as ECISUseRejectReason::<reason>. NoActionForState means no entry of the side matches the object’s state. The other reasons are in the table under “Works alone, fails online” on Troubleshooting.