Custom StateTree tasks

#unreal

See also: StateTree InstanceData

Basic C++ structure §

USTRUCT(DisplayName="DoTask")
struct EXAMPLE_API FSTT_DoTask : public FStateTreeTaskCommonBase
{
	GENERATED_BODY()
 
	using FInstanceDataType = FMyInstanceData;
 
	virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransitionResult& Transition) const override;
	
	virtual const UStruct* GetInstanceDataType() const override { return FInstanceDataType::StaticStruct(); }
};
 

Run status §

Tasks can return different run status values when entered and when ticking.

• Running: Returning this keeps the task active and allows it to tick
• Success: This will end the task with success. Note that this will immediately trigger the owning state to complete, regardless of the state of other tasks in the state.
• Failed: End the task with failure. This will also immediately trigger the owning state to complete.
• Stopped: Causes the state tree to stop

In Blueprint-based tasks, the task will be in Running state until you call Finish Task.

Task design §

Important: If your task returns any other status besides running this will cause the task to complete. This means the current state will trigger any complete/success/failure transitions - this will happen even if you have multiple tasks within a state. Only one needs to complete to trigger the transitions.

There are two common types of tasks you will have:

• Tasks which retrieve some data from somewhere so you can use it elsewhere in the state tree
• Tasks which perform some kind of actions

As a result of the behavior above, tasks which retrieve data should usually return Running even if technically they have finished retrieving data. This allows your other tasks/states which use this data to actually do something without exiting too early.

Similarly, tasks which perform actions should usually return a status value reflecting their actual result - success, failure or running if the task is not yet finished.

For blueprint based tasks, this means you should not call Finish Task unless you intend for the task to potentially trigger state transitions.

See also StateTree InstanceData

Gotchas §

If you use a task which completes as a Global Task, the entire state tree will stop immediately. This doesn’t produce any logs or any other information to warn you about it.