NextBot NPC Creation

Nextbot is what the AI in Team Fortress 2 and Left 4 Dead use. This tutorial will go over the steps for a simple AI that will search for enemies (you) and chase them until they die or are too far away. It will also do some random other stuff when there are not any enemies.

Lets get started

First create the .lua file for your entity. The one I made for this tutorial is in "addons/Nextbot_tut/lua/entities" and is named "simple_nextbot.lua". Now open that file so you can start adding the code.

The code

The basic stuff we need for entities

Start off with defining the base entity to use and making it spawnable. Pretty much the same as any other entity so far. Here we set the model and define some variables we will use later.

AddCSLuaFile() ENT.Base = "base_nextbot" ENT.Spawnable = true function ENT:Initialize() self:SetModel( "models/hunter.mdl" ) self.LoseTargetDist = 2000 -- How far the enemy has to be before we lose them self.SearchRadius = 1000 -- How far to search for enemies end

Enemy related stuff

This adds some useful functions for enemy related stuff. An NPC/bot isn't complete if it can't target stuff, right? These include a function to check if there is still an enemy or if it got away and a function to search for enemies. I've added all sorts of comments so you know exactly what they do.

---------------------------------------------------- -- ENT:Get/SetEnemy() -- Simple functions used in keeping our enemy saved ---------------------------------------------------- function ENT:SetEnemy(ent) self.Enemy = ent end function ENT:GetEnemy() return self.Enemy end ---------------------------------------------------- -- ENT:HaveEnemy() -- Returns true if we have an enemy ---------------------------------------------------- function ENT:HaveEnemy() -- If our current enemy is valid if ( self:GetEnemy() and IsValid(self:GetEnemy()) ) then -- If the enemy is too far if ( self:GetRangeTo(self:GetEnemy():GetPos()) > self.LoseTargetDist ) then -- If the enemy is lost then call FindEnemy() to look for a new one -- FindEnemy() will return true if an enemy is found, making this function return true return self:FindEnemy() -- If the enemy is dead( we have to check if its a player before we use Alive() ) elseif ( self:GetEnemy():IsPlayer() and !self:GetEnemy():Alive() ) then return self:FindEnemy() -- Return false if the search finds nothing end -- The enemy is neither too far nor too dead so we can return true return true else -- The enemy isn't valid so lets look for a new one return self:FindEnemy() end end ---------------------------------------------------- -- ENT:FindEnemy() -- Returns true and sets our enemy if we find one ---------------------------------------------------- function ENT:FindEnemy() -- Search around us for entities -- This can be done any way you want eg. ents.FindInCone() to replicate eyesight local _ents = ents.FindInSphere( self:GetPos(), self.SearchRadius ) -- Here we loop through every entity the above search finds and see if it's the one we want for k,v in ipairs( _ents ) do if ( v:IsPlayer() ) then -- We found one so lets set it as our enemy and return true self:SetEnemy(v) return true end end -- We found nothing so we will set our enemy as nil (nothing) and return false self:SetEnemy(nil) return false end

Coroutines

Now that the bot can find enemies we need to get it to actually do something other then just having an enemy. This next part is where most of our AI will be set up. The function is a coroutine, or pretty much a giant looping section of code, except you can pause it for a period of time using coroutine.wait( time ). Coroutines allow you to do things in a timed order, letting you pause the function so we can make the bot face the player or play an animation. And since its all inside a while true loop, it will run for as long as the bot exists. So after your ai has finished running everything it can do, it will go back and do it again. Here is an example of a very simple bot.

function ENT:RunBehaviour() while ( true ) do -- Here is the loop, it will run forever self:StartActivity( ACT_WALK ) -- Walk animation self.loco:SetDesiredSpeed( 200 ) -- Walk speed self:MoveToPos( self:GetPos() + Vector( math.Rand( -1, 1 ), math.Rand( -1, 1 ), 0 ) * 400 ) -- Walk to a random place within about 400 units (yielding) self:StartActivity( ACT_IDLE ) -- Idle animation coroutine.wait(2) -- Pause for 2 seconds coroutine.yield() -- The function is done here, but will start back at the top of the loop and make the bot walk somewhere else end end

Pretty straight forward right? Walk to a random spot and sit idle for 2 seconds before walking to another random spot. As nice as this is its not what we want, up next is a much better AI.

The "brain" of our bot

As scary as this code may look to some, it is actually pretty simple:

Check if we have an enemy, if not it will look for one using the above HaveEnemy() function.
If there is an enemy then play some animations and run at the player.
If there are not any enemies, then walk to a random spot.
Stand idle for 2 seconds. Not that bad right? Have a look at the code, I've flooded it with comments so you should know what everything does

---------------------------------------------------- -- ENT:RunBehaviour() -- This is where the meat of our AI is ---------------------------------------------------- function ENT:RunBehaviour() -- This function is called when the entity is first spawned, it acts as a giant loop that will run as long as the NPC exists while ( true ) do -- Lets use the above mentioned functions to see if we have/can find a enemy if ( self:HaveEnemy() ) then -- Now that we have a enemy, the code in this block will run self.loco:FaceTowards(self:GetEnemy():GetPos()) -- Face our enemy self:PlaySequenceAndWait( "plant" ) -- Lets make a pose to show we found a enemy self:PlaySequenceAndWait( "hunter_angry" )-- Play an animation to show the enemy we are angry self:PlaySequenceAndWait( "unplant" ) -- Get out of the pose self:StartActivity( ACT_RUN ) -- Set the animation self.loco:SetDesiredSpeed( 450 ) -- Set the speed that we will be moving at. Don't worry, the animation will speed up/slow down to match self.loco:SetAcceleration(900) -- We are going to run at the enemy quickly, so we want to accelerate really fast self:ChaseEnemy( ) -- The new function like MoveToPos that will be looked at soon. self.loco:SetAcceleration(400) -- Set this back to its default since we are done chasing the enemy self:PlaySequenceAndWait( "charge_miss_slide" ) -- Lets play a fancy animation when we stop moving self:StartActivity( ACT_IDLE ) --We are done so go back to idle -- Now once the above function is finished doing what it needs to do, the code will loop back to the start -- unless you put stuff after the if statement. Then that will be run before it loops else -- Since we can't find an enemy, lets wander -- Its the same code used in Garry's test bot self:StartActivity( ACT_WALK ) -- Walk anmimation self.loco:SetDesiredSpeed( 200 ) -- Walk speed self:MoveToPos( self:GetPos() + Vector( math.Rand( -1, 1 ), math.Rand( -1, 1 ), 0 ) * 400 ) -- Walk to a random place within about 400 units (yielding) self:StartActivity( ACT_IDLE ) end -- At this point in the code the bot has stopped chasing the player or finished walking to a random spot -- Using this next function we are going to wait 2 seconds until we go ahead and repeat it coroutine.wait(2) end end

What is the ChaseEnemy() function?

After looking through the code you probably noticed a function that isn't anywhere in the wiki and not yet posted in this tutorial. ChaseEnemy() is what we will be looking at now, its pretty much identical to the MoveToPos function Garry made in the Nextbot base except for some useful changes:

It builds a path to follow leading directly to the set enemy.
Keep updating the path as the enemy and the bot moves around.
Stop chasing the enemy if we don't have one any more. Using the HaveEnemy() function. This is what it looks like:

---------------------------------------------------- -- ENT:ChaseEnemy() -- Works similarly to Garry's MoveToPos function -- except it will constantly follow the -- position of the enemy until there no longer -- is an enemy. ---------------------------------------------------- function ENT:ChaseEnemy( options ) local options = options or {} local path = Path( "Follow" ) path:SetMinLookAheadDistance( options.lookahead or 300 ) path:SetGoalTolerance( options.tolerance or 20 ) path:Compute( self, self:GetEnemy():GetPos() ) -- Compute the path towards the enemy's position if ( !path:IsValid() ) then return "failed" end while ( path:IsValid() and self:HaveEnemy() ) do if ( path:GetAge() > 0.1 ) then -- Since we are following the player we have to constantly remake the path path:Compute(self, self:GetEnemy():GetPos())-- Compute the path towards the enemy's position again end path:Update( self ) -- This function moves the bot along the path if ( options.draw ) then path:Draw() end -- If we're stuck then call the HandleStuck function and abandon if ( self.loco:IsStuck() ) then self:HandleStuck() return "stuck" end coroutine.yield() end return "ok" end

Have a look at Garry's function and then this one and see what was changed in more detail.

Almost done

Now that the bot is complete you will want to add it to the NPC spawn tab. Pretty easy, but here is the code used for this tutorial anyways:

list.Set( "NPC", "simple_nextbot", { Name = "Simple bot", Class = "simple_nextbot", Category = "Nextbot" })

When you use this just replace both "simple_nextbot" with the file name of the bot and the rest is pretty easy to figure out yourself.

Challenges

You now have a basic bot running around the map and that's pretty much it. Here are some things you can try on your own to spice it up:

Search for more then just players
Play sounds when its wandering around.
Only search for enemies that are in front of it, not all around.
Make it hide if the enemy is holding a shotgun.
Stop chasing the enemy when it's really close and do a melee attack.

The full code

AddCSLuaFile() ENT.Base = "base_nextbot" ENT.Spawnable = true function ENT:Initialize() self:SetModel( "models/player/gman_high.mdl" ) self.LoseTargetDist = 2000 -- How far the enemy has to be before we lose them self.SearchRadius = 1000 -- How far to search for enemies end ---------------------------------------------------- -- ENT:Get/SetEnemy() -- Simple functions used in keeping our enemy saved ---------------------------------------------------- function ENT:SetEnemy(ent) self.Enemy = ent end function ENT:GetEnemy() return self.Enemy end ---------------------------------------------------- -- ENT:HaveEnemy() -- Returns true if we have a enemy ---------------------------------------------------- function ENT:HaveEnemy() -- If our current enemy is valid if ( self:GetEnemy() and IsValid(self:GetEnemy()) ) then -- If the enemy is too far if ( self:GetRangeTo(self:GetEnemy():GetPos()) > self.LoseTargetDist ) then -- If the enemy is lost then call FindEnemy() to look for a new one -- FindEnemy() will return true if an enemy is found, making this function return true return self:FindEnemy() -- If the enemy is dead( we have to check if its a player before we use Alive() ) elseif ( self:GetEnemy():IsPlayer() and !self:GetEnemy():Alive() ) then return self:FindEnemy() -- Return false if the search finds nothing end -- The enemy is neither too far nor too dead so we can return true return true else -- The enemy isn't valid so lets look for a new one return self:FindEnemy() end end ---------------------------------------------------- -- ENT:FindEnemy() -- Returns true and sets our enemy if we find one ---------------------------------------------------- function ENT:FindEnemy() -- Search around us for entities -- This can be done any way you want eg. ents.FindInCone() to replicate eyesight local _ents = ents.FindInSphere( self:GetPos(), self.SearchRadius ) -- Here we loop through every entity the above search finds and see if it's the one we want for k,v in ipairs( _ents ) do if ( v:IsPlayer() ) then -- We found one so lets set it as our enemy and return true self:SetEnemy(v) return true end end -- We found nothing so we will set our enemy as nil (nothing) and return false self:SetEnemy(nil) return false end ---------------------------------------------------- -- ENT:RunBehaviour() -- This is where the meat of our AI is ---------------------------------------------------- function ENT:RunBehaviour() -- This function is called when the entity is first spawned. It acts as a giant loop that will run as long as the NPC exists while ( true ) do -- Lets use the above mentioned functions to see if we have/can find a enemy if ( self:HaveEnemy() ) then -- Now that we have an enemy, the code in this block will run self.loco:FaceTowards(self:GetEnemy():GetPos()) -- Face our enemy self:PlaySequenceAndWait( "plant" ) -- Lets make a pose to show we found a enemy self:PlaySequenceAndWait( "hunter_angry" )-- Play an animation to show the enemy we are angry self:PlaySequenceAndWait( "unplant" ) -- Get out of the pose self:StartActivity( ACT_RUN ) -- Set the animation self.loco:SetDesiredSpeed( 450 ) -- Set the speed that we will be moving at. Don't worry, the animation will speed up/slow down to match self.loco:SetAcceleration(900) -- We are going to run at the enemy quickly, so we want to accelerate really fast self:ChaseEnemy( ) -- The new function like MoveToPos. self.loco:SetAcceleration(400) -- Set this back to its default since we are done chasing the enemy self:PlaySequenceAndWait( "charge_miss_slide" ) -- Lets play a fancy animation when we stop moving self:StartActivity( ACT_IDLE ) --We are done so go back to idle -- Now once the above function is finished doing what it needs to do, the code will loop back to the start -- unless you put stuff after the if statement. Then that will be run before it loops else -- Since we can't find an enemy, lets wander -- Its the same code used in Garry's test bot self:StartActivity( ACT_WALK ) -- Walk anmimation self.loco:SetDesiredSpeed( 200 ) -- Walk speed self:MoveToPos( self:GetPos() + Vector( math.Rand( -1, 1 ), math.Rand( -1, 1 ), 0 ) * 400 ) -- Walk to a random place within about 400 units (yielding) self:StartActivity( ACT_IDLE ) end -- At this point in the code the bot has stopped chasing the player or finished walking to a random spot -- Using this next function we are going to wait 2 seconds until we go ahead and repeat it coroutine.wait(2) end end ---------------------------------------------------- -- ENT:ChaseEnemy() -- Works similarly to Garry's MoveToPos function -- except it will constantly follow the -- position of the enemy until there no longer -- is one. ---------------------------------------------------- function ENT:ChaseEnemy( options ) local options = options or {} local path = Path( "Follow" ) path:SetMinLookAheadDistance( options.lookahead or 300 ) path:SetGoalTolerance( options.tolerance or 20 ) path:Compute( self, self:GetEnemy():GetPos() ) -- Compute the path towards the enemies position if ( !path:IsValid() ) then return "failed" end while ( path:IsValid() and self:HaveEnemy() ) do if ( path:GetAge() > 0.1 ) then -- Since we are following the player we have to constantly remake the path path:Compute(self, self:GetEnemy():GetPos())-- Compute the path towards the enemy's position again end path:Update( self ) -- This function moves the bot along the path if ( options.draw ) then path:Draw() end -- If we're stuck, then call the HandleStuck function and abandon if ( self.loco:IsStuck() ) then self:HandleStuck() return "stuck" end coroutine.yield() end return "ok" end list.Set( "NPC", "simple_nextbot", { Name = "Simple bot", Class = "simple_nextbot", Category = "Nextbot" })

Useful Console Commands

Here are some useful console commands that can help you create and debug your NextBots.

Command	Description
nb_debug <values>	Allows you to debug various parts of nextbots. Values can be combined with a space. Possible values are: BEHAVIOR, LOOK_AT, PATH, ANIMATION, LOCOMOTION, VISION, HEARING, EVENTS, ERRORS

Further Examples

Here are some further examples to guide you.

Useful NextBot examples by raubana