# UniTaskStateMachine [[日本語](https://github.com/k-okawa/UniTaskStateMachine/blob/master/README.ja.md)] [![openupm](https://camo.githubusercontent.com/a795ae93ace8e8d83973716c66cef77c919aa1a43066227611b126526a67c6b8/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f636f6d2e6c6974746c6562696766756e2e6164647265737361626c652d696d706f727465723f6c6162656c3d6f70656e75706d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d)](https://openupm.com/packages/com.littlebigfun.addressable-importer/) Since the return value is UniTask as shown below, you can use a state machine that supports asynchronous. ```c# public interface IState { void Init(BaseNode baseNode); UniTask OnEnter(CancellationToken ct = default); UniTask OnUpdate(CancellationToken ct = default); UniTask OnExit(CancellationToken ct = default); } ``` It has the following features. - The OnUpdate loop does not start until OnEnter finishes - Does not transition to the next state until OnExit finishes - OnUpdate is called every frame but not during await In addition, the state transition method corresponds to the following. - Transition when conditions are match - Transition to the next state by specifying the TransitionID - Ignored if the current state does not have the specified TransitionID This package also provide an Editor tool, so you can easily create states. ![image](https://user-images.githubusercontent.com/49301086/183348165-6042c870-ac33-479a-b5fa-af210f345352.png) ## Installation ### Dependency Using UniTask in the package, UniTask must be added in the project. [UniTask](https://github.com/Cysharp/UniTask) If you are using UniTask (UniRx.Async) before it was split from UniRx It can be used by defining the following in ProjectSettings / Player / OtherSettings / ScriptingDefineSymbol. ``` BG_USE_UNIRX_ASYNC ``` ### PackageManager #### Install via git url Open Window/Package Manager, and add package from git URL... ``` https://github.com/k-okawa/UniTaskStateMachine.git?path=Assets/Bg/UniTaskStateMachine ``` #### Install via OpenUPM ``` openupm add com.bg.unitaskstatemachine ``` ### UnityPackage You can download unity package in [release page](https://github.com/k-okawa/UniTaskStateMachine/releases). ## How to use ### 1.Add StateMachineBehaviour Component ![image](https://user-images.githubusercontent.com/49301086/143770544-d014aac1-e8a1-4c54-b1bf-d2945216f480.png) ### 2.Open GraphEditor GraphEditorOpen of StateMachineBehaviour added in 1 Or you can open the graph editor with Window / BG UniTaskStateMachine / StateMachineGraph. ![image](https://user-images.githubusercontent.com/49301086/183349573-556b2bfb-968c-40ef-91b9-acde45bf5f65.png) ### 3.How to add state #### 3-1.Add StateBehaviour Add a Component that inherits BaseStateComponent to the GameObject to which StateMachineBehaviour is attached. * Do not inherit the class that inherits BaseStateComponent. * Do not addBaseStateComponent directly. * Do not add same state component **Example** ```c# namespace Bg.UniTaskStateMachine.Tests.BasicSceneTest { public class StartState : BaseStateComponent { public override async UniTask OnEnter(CancellationToken ct = default) { } public override async UniTask OnUpdate(CancellationToken ct = default) { } public override async UniTask OnExit(CancellationToken ct = default) { } } } ``` ![image](https://user-images.githubusercontent.com/49301086/143770911-aa150949-1ece-4ea1-833d-1de973e09c0e.png) #### 3-2.Set the added StateBehaviour Right-click on the Graph editor and select Create State to add State. ![image](https://user-images.githubusercontent.com/49301086/183352350-6de6bec5-b304-4a1a-b668-049c6841a9eb.png) The added class name will be displayed and can be selected. ![image](https://user-images.githubusercontent.com/49301086/143771064-9915284a-fd38-4b00-b0f7-2a22c120c972.png) If None is selected, the state will be nothing. ### 4.How to add Transition You can add a Transition by right-clicking on the added State and selecting Make Transition. ![image](https://user-images.githubusercontent.com/49301086/143771406-b0e40166-fd07-4091-8e98-a5cac1ba83f2.png) You can use a function that is public in the Component of the GameObject to which StateMachineBehaviour is attached, has a return value of bool, and has no arguments, as a state transition condition. ![image](https://user-images.githubusercontent.com/49301086/143771235-8a12410e-21af-47d5-a7bb-bf1e9c03d1ae.png) You can reverse the condition by checking Is Negative. If you set MethodName to None, the transition will not always meet the conditions. It is also possible to forcibly execute the transition from the script by calling TriggerNextTransition described later. ![image](https://user-images.githubusercontent.com/49301086/143771269-6ffcd819-480a-4783-8f9f-ae28171c3036.png) ### 5.EntryState specification You must always specify the State to execute first. It can be set by right-clicking on the State and selecting Set as Entry. ![image](https://user-images.githubusercontent.com/49301086/143771406-b0e40166-fd07-4091-8e98-a5cac1ba83f2.png) ### TriggerNextTransition It is possible to translate state manually by transition id without specify condition method. Transition id is recommended upper camel case that can use in C# field name. After define transition id, you can generate transition id constant template code by GenerateTransitionIdConst button. ![image](https://user-images.githubusercontent.com/49301086/183354384-8c33ea1d-53a3-4bae-95f1-2011c0ddd660.png) Finally, call "StateMachine.TriggerNextTransition(string transitionId)" for manual state transition. It is able to call with string direct writing, but recommend with readonly string field in the generated template class. ## API Reference ### StateMachine It can be accessed from the StateMachine property of the StateMachineBehaviour. #### Properties ```c# // Entry state public BaseNode EntryNode; // Current state node public BaseNode CurrentNode { get; private set; } // current StateMachine state(STOP,START,PAUSE) public State CurrentState { get; private set; } = State.STOP; // Timing of OnUpdate public PlayerLoopTiming LoopTiming = PlayerLoopTiming.Update; ``` #### Methods ```c# ///

/// Start StateMachine ///

public async void Start(); ///

/// stop state machine completely ///

public void Stop(); /// pause current state /// public void Pause(); ///

/// resume current state ///

public void Resume(); ///

/// restart state machine from entry state ///

public async UniTask ReStart(CancellationToken ct = default); ///

/// force transition to next state ///

/// transition id named on graph editor public void TriggerNextTransition(string transitionId); ///

/// whether current state is equivalent ///

/// state type /// return true if current state is type argument public bool IsMatchCurrentStateType(Type type); ///

/// almost same with IsMatchCurrentStateType /// difference is variable length arguments ///

/// state types /// return true if current state match with any type arguments public bool IsMatchAnyCurrentStateType(params Type[] types); ``` ### BaseStateComponent #### Properties ```c# // Crrent node that has state and transition protected BaseNode baseNode; ``` #### Methods ```c# public virtual void Init(BaseNode baseNode); public virtual async UniTask OnEnter(CancellationToken ct = default); public virtual async UniTask OnUpdate(CancellationToken ct = default); public virtual async UniTask OnExit(CancellationToken ct = default); ``` ### BaseNode #### Properties ```c# public readonly string Id; public readonly StateMachine StateMachine; public bool IsUpdate { get; private set; } = true; ``` #### Methods ```c# ///

/// is match any condition ///

/// return true if node has any true conditions public bool IsMatchAnyCondition(); ///

/// is exist force transition ///

/// return true if node has any force transition public bool IsExistForceTransition(); ///

/// get condition ///

/// condition id (transition id named on graph editor) /// base condition public BaseCondition GetCondition(string id); ///

/// get transition ids that node has ///

public IEnumerable GetTransitionIds(); ``` ### BaseCondition #### Properties ```c# public BaseNode NextNode { get; } public Func ConditionCheckCallback { get; } public string TransitionId { get; } public bool IsNegative => isNegative; public bool IsForceTransition => isForceTransition; ```