How to make guard NPCs using a state machine

Added: 2026-05-05

[00:00:00]So, let's say you want to create exciting NPCs to fill your game world, but dumping all your logic into one big file leads to chaotic code you'll never be able to debug.

[00:00:09]If you want NPCs that you can customize quickly, reuse all over your world, and debug easily, you're going to want a state machine.

[00:00:17]Hi, I'm Miller, a software engineer here at Roblox. Today, we're going to learn how to use a state machine library to make a guard NPC that patrols and gets alerted if you come too close. All the code I'm going to show today, plus the place file, you can download and follow along if you want to.

[00:00:34]So, let's have a look at the world we'll be working in today.

[00:00:36]>> [music] >> As you can see, I've already gone ahead and set up a castle, as well as a simple NPC. This guy just has a humanoid, nothing else, and no other code telling him what to do. I've also set up these four flags that we use as waypoints for the guard's patrol and tag them. And lastly, I've put a sword in the middle on a golden pedestal that we can try to grab before the guards attack us. So, let's get started by having a look at our code. Here, I've got our types file.

[00:01:01]We're going to check out the different kind of tables we're going to be using in our state machine. We're going to have a context table, which is going to be a [music] global blackboard for all the information our NPCs need. We're going to have state tables, which are the possible configurations of each NPC.

[00:01:14]Test functions, which are run by transitions to connect the states, and finally, an actual state machine, [music] which is all the transitions we have, our starting context, our starting state, and we give it a name. Now, this right here is the meat and potatoes of the state machine. This is the tick function. This takes in one of those state machine tables we just saw, and it's going to run the tick function, checking each transition coming out of the active state to see if we should take it or not.

[00:01:38]>> [music] >> If we take a transition, we're going to run an on exit and an on enter function on the state we're leaving and entering, respectively. And if we don't transition, we're going to run an on stay function. That's really all the code that actually matters for using the state machine. I've also provided a composition test thing that lets you combine all multiple test functions [music] to create a combination, like a boolean and, or, or not. And then also, a single module that you can access all of them from called simple state machine. All right, now we're going to create an NPC that I'll call the walker.

[00:02:08]This NPC is going to walk between flags one and two. So, here we've got the code for the walker. Uh if you have a look here at the top, we've got the types, which we've just imported from simple state machine. I've set up a transition test, and then what I've also done is set up the actual states. So, if we have a look at walk to flag one, now when the NPC is in this state, it's just going to make them walk towards flag one. We've got a second state called [music] walk from to flag two. It's going to make them walk towards flag two. Now, let's talk about what this state does. What happens is when the NPC enters the state, we're going to set context.targetflag to flag one. Context, that's a global blackboard. We can keep information about the NPC in there. Then, in the on stay function, which is run every tick, we're going to have the humanoid set its move to to the flag one's pivot position. Walk to flag two is going to be the exact same thing, just replacing flag one with flag two. Coming back to our original file, you can see I've set up transitions. If we're in walk to flag one, we check if we're near the target flag. That's flag one. If we are, we go to flag two, and I made a transition to do the opposite. I just load those things into the state machine, and I set up some context information. The script's going to need to know what our character is, what our humanoid is, and also which flag we should start going to. We're going to start by going to flag two. And then all I've got to do is set heartbeat to run the tick function I showed you earlier. Now, all I've got to do is drag our walker script to the guard, and we'll see what happens.

[00:03:38]As you can see, the guard's walking to flag two, and when he reaches there, he switches back to the first state, walk to flag one, and he goes back and forth.

[00:03:48]So, that's a start, but we can do better. You might have noticed in the last one that walk to flag Now, let's try that again. You might have noticed for the walker that the states walk to flag one and walk to flag two [music] are pretty similar. So, the first thing I'm going to do is create a more generic called walk to random flag.

[00:04:04]What this [music] state is going to do is it's going to pick the next flag to go to randomly. So, instead of just going between one and two, >> [music] >> we're going to go to one of the two flags on an adjacent corner. So, the walk to random flag, when we enter it, is going to have us set the next flag.

[00:04:19]So, we'll figure out which flag we should go to randomly. And then what we'll do is in the on stay, we'll do the exact same thing we saw earlier with humanoid move to to have the character walk towards the next flag. [music] When you take that logic and you add on to it a simple idle state that has the character hang around for a second after reaching a flag, we end up with the patroller. The patroller's going to have a lot of the same code, but we're going to switch around the transitions. We're going to go [music] from idling, waiting around for a second, to walking to the next random flag. We're going to have two tests for this one. We're going to have is near target flag, which checks if we're close enough to the flag, and we're also going to have is idle timer done, which tells us if we've been idling for long enough that it's time to go back to patrolling.

[00:05:03]Again, we're going to take all that and put it into a state machine. We're going to add some new values to our context.

[00:05:09]Now, we're going to have an idle start time, and we're going to have a current flag number, so we can track all four flags. Connect it to heartbeat, and we'll watch it go.

[00:05:30]As you can see, our NPC now chooses flags randomly, letting it explore the entire castle and keep it protected from all sides.

[00:05:38]That said, although this guard does patrol between all the flags, it doesn't really protect it. So, the next thing we're going to add is new states for the guard to attack us if we get too close to prevent us from stealing the sword.

[00:05:50]So, let's soup up our guard with the ability to attack. The first thing I'm going to do is [music] We're going to add in this attack state.

[00:05:58]What this attack state does is while we're in the state, we're going to record the last player we've seen, and we're going to chase them down. And when we get close by, we're going to attack them on a cool down. Having a look at the final version of our NPC, which I'm calling the defender, you can see that we've added a new transition test, is player nearby. Just like before, this takes in the context, and we can use it to determine if a transition should occur. This test checks to see if a player is within a range of the NPC. And if it is, it sets our context.targetplayer to that value and returns true, letting us know that it's time to attack.

[00:06:37]If we come down and have a look at our transitions, you'll see that I'm leveraging a feature of the state machine. If you see the first transition there, I'm providing two different start states, letting us essentially have two arrows pointing at the attack state. If you have a look at the transitions table, I've added a new transition from idle or walk to random flag to our attack state, and that's using our is player nearby test. Coming down to look at our defender state machine, the only thing that's changed [music] is that I've added in a target player value, which is set to nil until the transition is player nearby finds a player to attack. Now that the defender is ready, let's see how the guard acts when we add that script to it.

[00:07:20]Let's try getting close to the guard and see what happens.

[00:07:26]Now, let's see how state machine NPCs can make a scene really exciting by adding tons of guards. All right, I've got nine guards walking around the palace. Let's see if I can get in, get the sword, and get out without dying.

[00:07:38]Okay, I've already aggroed a couple of them. This is not good. Okay, let me try that again.

[00:07:47]All right, sneaking past while they're idle.

[00:07:50]I'm in.

[00:07:53]Oh, shoot. Got the sword. Take one down.

[00:07:57]Took two down. Oh, there's a lot more.

[00:07:59]I got them all.

[00:08:02]Victory! So, there you have it. A guard that patrols, alerts, and battles you when you get too close. Next time you're making an NPC, feel free to try out the state machine library, or design your own. You'll be surprised how active and engaging your NPCs can be with just a few states and transitions. That's all from me. I hope you learned something new.