{"id":92975,"date":"2021-11-29T16:50:54","date_gmt":"2021-11-29T16:50:54","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=92975"},"modified":"2021-11-29T16:50:54","modified_gmt":"2021-11-29T16:50:54","slug":"unity-state-machine-behaviours","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/featured\/unity-state-machine-behaviours\/","title":{"rendered":"Unity state machine behaviours"},"content":{"rendered":"

An animation in a Unity project is an opportunity to perform many additional actions on top of the animation itself. These actions can be anything the developer desires, including allowing specific user actions or changing variables to your needs. Some time back, Unity’s animation events<\/a> were demonstrated as a tool for accomplishing some of these goals. They’re great for performing functions at specific points in an animation but not as helpful if there’s something more general you want to do at any point in the animation. Enter Unity State Machine Behaviours, a class of script that works specifically with the Unity Animator system.<\/p>\n

Working alongside the Animator, State Machine Behaviours lets you define actions for entering, exiting, and updating various animation states. This means you can have code that runs specifically during an object’s idle state and another script that only executes during the same object’s walking state. Not only does this allow you to perform specific actions during certain states, but it’s also a great way to keep your code organized too. Another great benefit is the ability to reuse these scripts on other state machines, so you don’t have to worry about a script being tied to a single object. As usual, the best way to see the benefits is to see it all in action. Follow along to see how to use these scripts in a project, and by the end, you’ll have a Unity project with a character that performs different actions based on whether it’s in an idle or walking state.<\/p>\n

There are many unique assets in this project, so to focus on the code and how it works, a sample project has been created to give you a starting point if you choose to follow along. Additionally, there is a completed version with all the code included to view and modify as you see fit. Links for these projects are listed below. Open the Unity Hub app and click the Add button, find the folder containing the Unity project, and choose Select Folder<\/em>.<\/p>\n

Codeless project: https:\/\/github.com\/prof-smash\/SimpleTalk-StateMachines-Codeless<\/a><\/p>\n

Complete project: https:\/\/github.com\/prof-smash\/SimpleTalk-StateMachines-Complete<\/a><\/p>\n

Project overview<\/h2>\n

First, take a brief look at what’s included in the sample project. Upon opening the project, you should be greeted with a scene with a blue bot character standing on a plane. If you don’t see this, find the SampleScene <\/em>asset in your Assets <\/em>window and open it. This blue bot has an animator tied to it that allows playing idle and walking animations. As it walks, it will leave markers on the floor to indicate where it has been. The markers come from the prefab simply named Marker<\/em> in the Prefabs <\/em>folder.<\/p>\n

Additionally, some text displaying the number of walks the bot has taken is in the upper left corner of the screen. The exact location and appearance of the text may vary depending on your display, so feel free to adjust its position, color, and other properties in the Inspector<\/em>. Finally, though you can’t see it at the moment, a nav mesh has been set up, which defines the area the bot can walk. If you wish to see this nav mesh, click the Navigation <\/em>tab in the Inspector <\/em>area (if you don’t see this tab, go the top menu and choose Window->AI<\/em>->Navigation<\/em>), and you should see a blue area in the Scene<\/em> window that defines the nav mesh. All other assets in the Assets <\/em>window include the texture for the marker and animations for the bot.<\/p>\n

\"Image<\/p>\n

Figure 1: The project scene with the nav mesh shown<\/strong><\/p>\n

Those animations are brought together via the bot_anim_controller <\/em>asset in the Animations <\/em>folder. If you select this asset and open the Animator <\/em>window (found by going to Window->Animation->Animator<\/em>), you can see the animator immediately launches the bot into the idle state. If you can’t see this right away, you may need to navigate the Animator window using the Alt key plus mouse button to pan the view. The arrows pointing to and from the idle and walk states are transitions, with each given a condition that must be met for the transition to occur. In this case, two booleans named idle<\/em> and walk<\/em> are set to control when the bot is in the idle or walk state, respectively. These two states are where the scripts will be attached to give the bot unique behaviours based on the state.<\/p>\n

\"Image<\/p>\n

Figure 2: bot_anim_controller, showing animation states, transitions, and booleans<\/strong><\/p>\n

If you click on the idle state, you should see a button in the Inspector <\/em>window that says Add Behaviour<\/em>. Click this button, then click New Script, <\/em>then give the script the name IdleStateBehaviour<\/em>. The newly created script will be immediately added to the idle state, with the asset itself being placed in the Assets <\/em>folder. Repeat this process for the walk state, this time calling the script WalkStateBehaviour<\/em>.<\/p>\n

\"Image<\/p>\n

Figure 3: Adding a new state machine behaviour script<\/strong><\/p>\n

By using this specific button to create the script, Unity will know to make this a script that inherits from the StateMachineBehaviour <\/em>class, so we won’t have to worry about changing that. It also sets up a template for the state machine behaviour script that gives you all the methods you’ll need to code state behaviours. Double click the IdleStateBehaviour <\/em>script to open it in Visual Studio and set up the first state behaviour.<\/p>\n

IdleStateBehaviour code<\/h2>\n

As promised, the IdleStateBehaviour <\/em>script is inheriting from StateMachineBehaviour <\/em>from the start. Additionally, there are five methods, each with brief documentation of how they work. For this project, the focus will be placed on OnStateEnter<\/code>, OnStateUpdate<\/code>, and OnStateExit<\/code>. As the names imply, these methods perform code based on when the bot enters or exits its idle state and is currently in the idle state. But that’s not all! Like the traditional MonoBehaviour <\/em>scripts Unity users are used to, you can define variables that can be edited in the Unity editor right here in this script. These variables are a good place to start with the coding process. So, just above OnStateEnter<\/code>, enter the following:<\/p>\n

[Range(2.0f, 10.0f)]\r\npublic float waitTime = 5f;\r\npublic GameObject marker;\r\nprivate float timeTillMove = 5f;\r\nprivate Vector3 stopPosition;<\/pre>\n
The first two variables will be for you to decide in the editor, with waitTime<\/code> defining how much time there is between walks. Next is marker<\/em>, which will be what the bot places down upon leaving its position. Finally, timeTillMove<\/code> will be the actual timer that counts down between walks, with the time in question coming from waitTime<\/code>, and stopPosition<\/code> is the location the bot stops at, which will be used to place markers.<\/p>\n
Moving on to OnStateEnter<\/code>, you’ll notice that an Animator<\/code> is set in the method’s parameters. In fact, this is true of all the methods in the script. This will be helpful as it allows you easy access to the bot’s animator and the methods and data associated with it. Let’s put it to use along with some additional code:<\/p>\n
animator.SetBool(\"walk\", false);\r\nstopPosition = new Vector3(animator.transform.position.x, \r\n         0.01f, animator.transform.position.z);<\/pre>\n
Recall the booleans that control when transitions occur in the bot’s animator. When the bot is in its idle state, you wouldn’t want it to start walking in place. To prevent this, set the walk <\/em>bool in the animator to false the moment the bot enters its idle state. You’ll also go ahead and get its current position for leaving a marker later on when exiting the idle state. The Y value of stopPosition<\/code> will be set to 0.01 to allow the marker to be slightly above the floor so you can see it. Without this change, the marker will \u201cblend\u201d with the floor and stutter or even be impossible to see.<\/p>\n
Let’s move on to OnStateUpdate<\/code>, which will execute continuously so long as the bot is in its idle state. This method is perfect for counting down the seconds before moving again. To execute this, enter the following:<\/p>\n
timeTillMove -= Time.deltaTime;\r\nif (timeTillMove <= 0)\r\n{\r\n\ttimeTillMove = waitTime;\r\n\tanimator.SetBool(\"walk\", true);\r\n}<\/pre>\n
This code is pretty straightforward. The timeTillMove<\/code> variable is subtracted until it reaches zero, at which point the timer is reset using waitTime<\/code>,<\/em> and the walk<\/code> bool in the animator is set to true. Notice that the timer will not count down until this state is active again, so there’s no need to worry about it counting down too early.<\/p>\n
Finally, let’s implement the code for OnStateExit<\/code>. It consists of a single line that spawns the marker<\/code> object into the world at the position recorded in stopPosition<\/code>.<\/p>\n
Instantiate(marker, stopPosition, Quaternion.identity);<\/pre>\n
That’s all the code for IdleStateBehaviour<\/em>. Now it’s time to move on to the code for the bot’s walk state.<\/p>\n
WalkStateBehaviour code<\/h2>\n
Like the IdleStateBehaviour <\/em>script, this script will keep its focus on OnStateEnter<\/code>, OnStateUpdate<\/code>, <\/em>and OnStateExit<\/code>. However, the script as a whole will be slightly more involved than IdleStateBehaviour<\/code> as it will search for objects in the scene, find a random position for the bot, and update statistics. It will also utilize the UnityEngine.UI<\/code> and UnityEngine.AI namespaces<\/code>. With that in mind, let’s set up the using statements now.<\/p>\n
using UnityEngine.UI;\r\nusing UnityEngine.AI;<\/pre>\n
Like before, there are also a few variables to declare before getting into the meat of the code, with one of them being a value you’ll set in the editor.<\/p>\n
[Range(2.5f, 7f)]<\/p>\n
public float maximumWalkingDistance = 4f;<\/p>\n
private Text walkText;<\/p>\n
private NavMeshAgent agent;<\/p>\n
private int walks = 0;<\/p>\n
Of particular note, here are the walkText<\/code> and agent <\/em>variables. The walkText<\/code> variable will be given string data to display in the UI seen earlier in the scene. It will be updated with the values of walks<\/code> whenever the bot has finished taking its short walk. Meanwhile, the agent<\/code> variable will contain the Nav Mesh Agent <\/em>component on the bot object. As you’ll see later on, we get the agent by using GetComponent<\/code> whenever the bot enters the walk state. Why wouldn’t you just set agent<\/code> in the editor? This is because scripts inheriting from StateMachineBehaviour<\/code> do not allow you to pass in gameobject<\/code> data into the script before runtime, including their components. Because the state machine behaviour lives within the animator asset, as opposed to within the scene, we cannot link objects within the scene to the script. Thus, we work around that by using methods like GameObject<\/code>.Find<\/em> or reference the gameobject<\/code> (and thus its components) where the animator is attached.<\/p>\n
Next, the code for OnStateEnter<\/code>:<\/em><\/p>\n
animator.SetBool(“idle”, false);<\/p>\n
walkText = GameObject.Find(\"WalksText\").GetComponent<Text>();\r\nagent = animator.GetComponent<NavMeshAgent>();\r\nagent.destination = RandomPosition(animator.transform.position, \r\n             maximumWalkingDistance, -1);<\/pre>\n
First, we make sure the bot cannot accidentally go back to its idle animation while walking. Then you find the WalksText<\/code> object in the scene and tell the script to use that for walkText<\/code>. You then set up the NavMeshAgent<\/code>, including its destination. The destination is found using the RandomPosition<\/code>, a custom method for finding a random point in the Nav Mesh to walk. Now would be an excellent time to create the RandomPosition<\/code> method.<\/p>\n
Vector3 RandomPosition(Vector3 origin, float distance, int layerMask)\r\n{\r\n\tVector3 randomDirection = Random.insideUnitSphere * distance;\r\n\trandomDirection += origin;\r\n\tNavMeshHit navHit;\r\n\tNavMesh.SamplePosition(randomDirection, out navHit, distance, \r\n               layerMask);\r\n\treturn navHit.position;\r\n}<\/pre>\n
Returning to the pre-generated methods, OnStateUpdate<\/code> will be utilized to check how far away the bot is from its destination. If it has made it to its destination, then the bot will simply return to the idle state, and the process repeats.<\/p>\n
float dist = agent.remainingDistance;\r\n        if (dist != Mathf.Infinity && agent.pathStatus == \r\n              NavMeshPathStatus.PathComplete && \r\n               agent.remainingDistance <= 0.01f)\r\n{\r\n            animator.SetBool(\"idle\", true);\r\n}<\/pre>\n
After leaving this state and returning to the idle state, the number of walks taken is incremented by one. walkText<\/code> is <\/em>updated to reflect this change. That code will be going in OnStateExit<\/code>.<\/p>\n
walks++;\r\nwalkText.text = \"Walks Taken: \" + walks.ToString();<\/pre>\n
That ends all the code needed for this project. Be sure to save all scripts, then return to the Unity editor for some final tasks.<\/p>\n
Finishing up<\/h2>\n
There’s not much else that needs to be done to complete the project. If it’s not open already, make sure the Animator <\/em>window is open, and you have the bot_anim_controller <\/em>asset selected. Start by clicking on the idle <\/em>state. Set the time you want the bot to wait before starting its next walk and make sure the script knows where to find the Marker <\/em>prefab.<\/p>\n
\"Image<\/p>\n
Figure 4: Assigning the marker<\/strong><\/p>\n
Likewise, select the walk <\/em>state and set your maximum walking distance. If you only want the bot to take short walks, lower the walking distance. For the opposite, raise the Maximum Walking Distance<\/em>. Once you’ve made your decision, test out the project using the play button at the top. The bot should start going to random spots on the floor, leaving markers along the way, and counting how many walks it has taken. It will continue to do this until you stop running the project.<\/p>\n
\"Image<\/p>\n
Figure 5: The project in action<\/strong><\/p>\n
Conclusion<\/h2>\n
As stated before, the beauty of these scripts is that they can be assigned to any animation state. So you can have multiple objects use the code you’ve just written, even if they have different animators powering them. You just need to be mindful of items like animator booleans and any additional states within the animator. Additionally, these can also be used to give an object specific instructions in an organized, easy to access way. Whether it’s for a simple prototype or a large, complex project, state machine behaviours can be a valuable tool to help you achieve the goals of your Unity project.<\/p>\n
As stated before, the beauty of these scripts is that they can be assigned to any animation state. So you can have multiple objects use the code you’ve just written, even if they have different animators powering them. You just need to be mindful of items like animator booleans and any additional states within the animator. Additionally, these can also be used to give an object specific instructions in an organized, easy to access way. Whether it’s for a simple prototype or a large, complex project, state machine behaviours can be a valuable tool to help you achieve the goals of your Unity project.<\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
Video games would not be much fun without animation. In this article, Lance Talbert demonstrates Unity state machine behaviours to define code running during specific animation states.…<\/p>\n","protected":false},"author":317499,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143538,53],"tags":[5134],"coauthors":[52549],"class_list":["post-92975","post","type-post","status-publish","format-standard","hentry","category-dotnet-development","category-featured","tag-sql-prompt"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/92975","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/317499"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=92975"}],"version-history":[{"count":4,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/92975\/revisions"}],"predecessor-version":[{"id":92982,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/92975\/revisions\/92982"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=92975"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=92975"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=92975"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=92975"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}