L4D2 Vscript Examples

From Valve Developer Community
Jump to: navigation, search

Left 4 Dead 2 The following are example vscripts for Left 4 Dead 2.

Iterating through entities

With awhileloop and a Entities.FindByClassname() function, you can iterate through all entities of a matching classname, based on your arguments.

The first parameter of Entities.FindByClassname() is named 'previous' which accepts a script handle (of an entity inherits 'CBaseEntity' specifically), which verifies if the matching entity it finds has an entity index that's higher than the current one in the 'previous' argument. If it turns out to be not, then its ignored.

local ent = null
while( ent = Entities.FindByClassname(ent, "prop_physics") )

Fetching a specific survivor

With usage of the method.FindByModel()from Entities class, this script uses it to fetch only a specific survivor. Models is one of the unique features all survivors possess, so we can use it to find just a specific survivor.

All survivors have unique model path names, which is attained with the.GetModelName()method, belonging to the CBaseEntity class. As players are also entities (the nameplayeris their classname), iterate through all of them with aEntities.FindByClassname() function, thenprintl()their model names in console.

/* Should return something like this in console
local player = null
while( player = Entities.FindByClassname(player, "player") )
   printl( player.GetModelName() )

So then, this would be what fetching Zoey looks like:

// Although things like Sourcemod can allow more than 1 Zoeys, for the sake of the example, let's assume there's only can be one Zoey at all times.
local zoey = Entities.FindByModel(null, "models/survivors/survivor_teenangst.mdl")

Find survivors closest to entity

This builds off multiple scripts. Refer to the author's website for a explanation and complete code. [1]

IncludeScript("survivorclosest.nut", this);

ent <- Entities.FindByName(null, "entname");

printl("Found entity "+ent);

FindSurvivors()  // make sure this script isn't called right away or they won't be found yet

who <- FindSurvivorClosestToEnt(ent); // returns entity reference to survivor
if (who){
   printl(who+" is closest to "+ent.GetName()+" at "+who.GetOrigin());
   // do something here
   printl("Nothing found");

/* or, if you want the name returned (the key into the
 survivors table), add a true value as a second param */

who <- FindSurvivorClosestToEnt(ent, 1); // returns entity reference to survivor
if (who){
   printl(who+" is closest to "+ent.GetName()+" at "+survivors[who].GetOrigin());
   // do something here
   printl("Nothing found");

"Hovering Chopper Support" example

[2] If you want to parent a func_tracktrain to something, so it moves relative, you don't parent the path, you parent the func_tracktrain itsef to the item, and the path will move relative to this. So here's what this does.

  • You make your track as normal, your "train" heli, whatever.
  • Place an info_target in the center of your path with a name ex: chopper_follow
  • Then you parent that func_tracktrain to the target (chopper_follow).
  • Pass that target as the first entitygroup to this script.
  • Then what happens is that the script computes the average position of the survivors ever 1/10 of a second, moves the info_target there (chopper_follow), and the path_track will follow.
  • Have your track the height you want, relative to the info_target.
Note.png Note: There are a couple caveats, you'll need to call FindSurvivors() after a delay of map load, or it won't work. They won't be loaded yet, a logic_auto output onmapspawn with a delay of 10 seconds should do it.

Changing the skybox on map load

[3] Save the file to your scripts/vscripts folder as whichskybox.nut

Add a logic_script entity to your map, turn off smartedit and add a "vscripts" key with a value of whichskybox.nut

Obviously you would have to adjust fog and lighting entities as well for it to not look terrible.

Skyboxes <- [

worldspawn <- Entities.FindByClassname (null, "worldspawn");
local i = RandomInt(0,Skyboxes.len()-1);
printl("Skybox is "+Skyboxes[i]);
printl( worldspawn.__KeyValueFromString("skyname",Skyboxes[i]) );

Changing witch movement type on map load

Note.png Note: A better example of this, using a single script file, can be found here

This was based off of the code found here: [4] Save the two files to your scripts/vscripts folder as daywitch.nut and nightwitch.nut

Add two logic_script entities to your map. Give "Name" a value of daywitchscript, turn off smartedit and add a "vscripts" key with a value of daywitch.nut.

Repeat for the other with a "Name" value of nightwitchscript, turn off smartedit again and add a "vscripts" key with a value of nightwitch.nut.

There are two scripts involved here, one for day witches and one for night. These scripts run on map load and select the numerical equivialant of Midnight (0) or Morning (2) found in worldspawn. I seperated the scripts so entity logic can tie into them. More on that later.


Skyboxes <- [

worldspawn <- Entities.FindByClassname (null, "worldspawn");
local i = RandomInt(0,Skyboxes.len()-1);
printl("Skybox is "+Skyboxes[i]);
printl( worldspawn.__KeyValueFromString("timeofday",Skyboxes[i]) );


Skyboxes <- [

worldspawn <- Entities.FindByClassname (null, "worldspawn");
local i = RandomInt(0,Skyboxes.len()-1);
printl("Skybox is "+Skyboxes[i]);
printl( worldspawn.__KeyValueFromString("timeofday",Skyboxes[i]) );

This is the line of entity logic I used in my test map to achieve random day or night witches. Note I start the logic_auto with a delay of 10 seconds so the AI can get ready. It doesn't seem to work if I don't, as noted in the "Hovering Chopper Support Example" above.

Class: logic_auto
My output named: OnMapSpawn
Targets entities named: daynightwitchcase
Via this input: PickRandomShuffle
Delay: 10.00

Class: logic_case
My output named: OnCase01
Targets entities named: daywitchscripttemplate
Via this input: ForceSpawn
Delay: 0.00

My output named: OnCase02
Targets entities named: nightwitchscripttemplate
Via this input: ForceSpawn
Delay: 0.00

Class: point_template
Name: daywitchscripttemplate
Template 1: daywitchscript

Class: point_template
Name: nightwitchscripttemplate
Template 1: nightwitchscript

Class: logic_script
Name: daywitchscript
vscripts: daywitch.nut

Class: logic_script
Name: nightwitchscript
vscripts: nightwitch.nut

Compile your map with this logic in place, and both named scripts in the scripts/vscripts folder in your main game directory and you should see witches respond and behave differently, depending on which script the game chose randomly.

Prohibiting tank and witch spawns

Left4Dead 2 no longer relies on the mission.txt file to prohibit Tanks and Witches on maps. This is now done with a script file that you should place in your left4dead2/scripts/vscripts folder (you may need to add the vscripts subfolder yourself). Add the following to a text file:

DirectorOptions <-
  ProhibitBosses = true

Save the textfile with the extention .nut in the vscripts folder. In your map, place a logic_auto entity and add an output. The output should target the AI Director entity and make it fire the script by using the BeginScript action. In the parameter field, you set the name of your script (without the .nut extention)

Some scavenge gamemode DirectorOptions (for coop/versus finales with scavenge)

For a finale that is using scavenge as the gameplay (such as in the Mall Atrium finale), you'll need a separate scavenge script. Here's c1m4's (name the script "[the name of the map]_scavenge.nut"):

DirectorOptions <-
PreferredMobDirection = SPAWN_LARGE_VOLUME
PreferredSpecialDirection = SPAWN_LARGE_VOLUME
ShouldConstrainLargeVolumeSpawn = false
MobSpawnMinTime = 45
MobSpawnMaxTime = 90
CommonLimit = 15
ZombieSpawnRange = 3000

Maximum number of simultaneous specials

The following script not only limits the number of specials (using MaxSpecials), but also limits the number of specific specials allowed simultaneously and increases the maximum number of common infected:

Note.png Note: Developers should keep in mind that in-game and network performance may suffer as more infected are introduced to the player at the same time.
Msg("Preparing to own the Survivors");
local Dopts = DirectorScript.DirectorOptions; // get a reference to the options
Dopts.MaxSpecials <- 20;
Dopts.BoomerLimit <- 5;
Dopts.SmokerLimit <- 5;
Dopts.HunterLimit <- 5;
Dopts.ChargerLimit <- 5;
Dopts.SpitterLimit <- 5;
Dopts.JockeyLimit <- 5;
Dopts.CommonLimit <- 120;
Dopts.SpecialRespawnInterval <- 1.0;

Dead center chapter 3 special infected limit

For multiple SI spawns like in the 3rd chapter of Dead Center:

BoomerLimit = 0
SmokerLimit = 3
HunterLimit = 1
ChargerLimit = 2

You can also limit Spitters and Jockeys with

SpitterLimit = 0
JockeyLimit = 0


In many cases in official maps, a vscript is loaded on map load to initialize some variables or the actual state of the director. This script is loaded via entity logic_auto where an output is fired to the director. There appears to be no specific reason to name the script after the name of the map other than keeping a logical progression in naming convention. Refer to c1m4_atrium.vmf, c1m4_atrium_finale.nut, and c1m4_delay.nut for more details on how the scavenge finale is implemented.

Msg(" atrium map script "+"\n")

// number of cans needed to escape.

if ( Director.IsSinglePlayerGame() )
                NumCansNeeded <- 8
                NumCansNeeded <- 13

DirectorOptions <-

CommonLimit = 15



EntFire( "progress_display", "SetTotalItems", NumCansNeeded )

function GasCanPoured(){}

Tic-Tac-Toe mini-game

This example uses and vscripts to manipulate entities "registered" to a logic_script entity.[5]

Pushing a player around


author: http://leeland.net
Allows you to add a velocity vector to any player via trigger.
Call it from a trigger with something like
OnStartTouch !activator runscriptcode OurPushPlayer(0,0,400)

A note on values, 4096 is the maximum velocity, values below 250 don't move the player at all.
Z Values around 700 will incap, 1000 or so will prove fatal


function OurPushPlayer(x,y,z) {
   local addv = Vector(x,y,z); // 4096 max velocity, anything higher is clamped
   local v = self.GetVelocity()

// slip in a reference to our function in the global table so we can access from all objects,
// *technique to use sparingly! Your function could overwrite another. Name uniquely to try and avoid conflicts*
::OurPushPlayer <- OurPushPlayer;
Note.png Note: Negative Z values do not work. A player cannot be pounded into the ground.


Timers can use the Time() function to get the server uptime, and use it to count how many seconds has elapsed from certain time.

// Create a timer to disable commons after 2 minutes of playing the level

timer_done <- false; //A boolean to ensure we only run the timer once
function Update()
   if(!timer_done && Time() >= 120)
      DirectorScript.DirectorOptions.CommonLimit <- 0;
      timer_done = true;

You can also make a repeating timer:

// Create a timer to increase common limit by 1 every 5 minutes

last_set <- 0;
function Update()
   if(Time() >= last_set + 300)
       //Here is where you put all the things you do after the timer runs out
       DirectorScript.DirectorOptions.CommonLimit += 1;
       last_set = Time(); //Keep this so the timer works properly

Here's an example using both methods:

//After 1 minute, kill Rochelle, and after every 30 seconds, fill up nick's health

timer_done <- false; //Note that this is only for the timer running once
last_set <- 0;
function Update()
   if(!timer_done && Time() >= 60)
      timer_done = true;
   if(Time() >= last_set + 30)
      last_set = Time();

Bumping up special infected

[7] This script essentially increases both hunter limit and health for an epic "Boss Battle".

  • Someone on the forums wanted to up the limits on Hunters and increase their health. Unfortunately SendToConsole() respects cheats (which is kind of silly as scripts are server side), so here's a script that does that. Just call it from logic_script, setting it's Think function to "Think".
  • The script code be easily modified to for any SI (or commons). Also you could extend it to give SI random amounts of health (some stronger, some weaker).
  • This example will issue a beginscript "hunterb.nut" on the director when the "boss" hunters are dispatched. This example will spawn a tank. Though you could call any script, including the built-in ones.
  • Press the button to start the "boss" hunter attack. In a real map, you'd want to disable the button so it can only be triggered once.
author: Lee Pumphret
Msg("HUNTERS v3");

BossHunterCount <- 6; // how many you want
FoundBossHunters <- 0
UseBossHunters <- 0;
HunterHealth <- 1250
OurHunters <- []   // keep track of our bumped up hunters

OurLastSeen <- null  // track the last we've seen so we don't have to traverse the entire entity list

function Think(){
   if (UseBossHunters){
      local z
      while (z = Entities.FindByModel(OurLastSeen,"models/infected/hunter.mdl")){
         if (FoundBossHunters++ < BossHunterCount){
             OurHunters.push(z); // save a reference to our guys
             printl("Hunter #"+FoundBossHunters+" "+z.GetClassname() + " health:"+z.GetHealth());
         }else {
            //printl("Hunter cap hit, disabling");
            UseBossHunters = 0  // turns ourselves off
            DirectorScript.DirectorOptions.HunterLimit = 0
         OurLastSeen = z

   if (OurHunters){
      DeadHunters <- 0;
      foreach (hunter in OurHunters){
         //printl("looking at hunter " + hunter + " health is "+hunter.GetHealth());
         if (!hunter.IsValid() || (hunter.GetHealth() <= 1)){ /* dead hunter has 1 health, why? */



      if (DeadHunters == BossHunterCount){
         Msg("Boss Hunters dead...");
         OurHunters = [];
         // EntFire your sound here...
         EntFire("director","beginscript", "hunters_b.nut") // or scriptname.nuc if it's a nuc




function StartBossHunters(){
   Msg("Activating Boss Hunters")
   UseBossHunters = 1
   FoundBossHunters = 0
   local Dopts = DirectorScript.DirectorOptions // get a reference to the options
   Dopts.BoomerLimit <- 0
   Dopts.SmokerLimit <- 0
   Dopts.HunterLimit <- BossHunterCount
   Dopts.ChargerLimit <- 0
   Dopts.SpitterLimit <- 0
   Dopts.JockeyLimit <- 0
   Dopts.DominatorLimit <- BossHunterCount
   Dopts.MaxSpecials <- BossHunterCount
   EntFire("spawn_hunter","spawnzombie", "hunter") // or scriptname.nuc if it's a nuc

function StopBossHunters(){
   Msg("Deactivating Boss Hunters")
   UseBossHunters = 0
   local Dopts = DirectorScript.DirectorOptions // get a reference to the options
   Dopts.BoomerLimit <- 1
   Dopts.SmokerLimit <- 1
   Dopts.HunterLimit <- 1
   Dopts.ChargerLimit <- 1
   Dopts.SpitterLimit <- 1
   Dopts.JockeyLimit <- 1
   Dopts.DominatorLimit <- 3
   Dopts.MaxSpecials <- 4


Full details and code are found at the author's website, leeland.net.

Making an entity orient itself toward a player

// Locks on to the nearest survivor and points the entity running this at them.
// By: Rectus

target <- null;

// Set the think function of the entity to 'PointEntity' for it to keep doing it.
function PointEntity()
	// Finds the closest survivor if we don't have a target yet.
	if(!target || !target.IsValid())
		local bestTarget = null;
		local player = null;

		while(player = Entities.FindByClassname(player, "player"))
				if(!bestTarget || (player.GetOrigin() - self.GetOrigin()).Length() <
					(bestTarget.GetOrigin() - self.GetOrigin()).Length())
					bestTarget = player;

			target = bestTarget;

		self.SetForwardVector(target.GetOrigin() - self.GetOrigin());

Handling Weapons/Items

These are available weapon entity names, to be used in the following (or any) scripts.

  • weapon_adrenaline
  • weapon_defibrillator
  • weapon_pain_pills
  • weapon_first_aid_kit
  • weapon_molotov
  • weapon_pipe_bomb
  • weapon_vomitjar
  • weapon_pistol
  • weapon_pistol_magnum
  • weapon_rifle
  • weapon_rifle_ak47
  • weapon_rifle_desert
  • weapon_rifle_m60
  • weapon_rifle_sg552
  • weapon_shotgun_chrome
  • weapon_pumpshotgun
  • weapon_autoshotgun
  • weapon_shotgun_spas
  • weapon_smg
  • weapon_smg_mp5
  • weapon_smg_silenced
  • weapon_sniper_awp
  • weapon_sniper_military
  • weapon_sniper_scout
  • weapon_hunting_rifle
  • weapon_upgradepack_explosive
  • weapon_upgradepack_incendiary
  • upgrade_item //Lasers
  • weapon_grenade_launcher
  • weapon_chainsaw
  • ammo //ammo piles

Melee weapons seem to only work for "DefaultItems"

  • baseball_bat
  • cricket_bat
  • crowbar
  • electric_guitar
  • fireaxe
  • frying_pan
  • golfclub
  • katana
  • knife
  • knife
  • machete
  • pitchfork
  • shovel
  • tonfa

Removing Weapons/Items

This script removes adrenaline and defibrillator spawns, along with all melee weapons. Generally you want to replace weapons; Deleted weapon spawn means nothing would spawn in its place.

Msg("Removing unwanted weapons.\n");
DirectorOptions <-
  	weaponsToRemove =
	//	<Weapon script name>	= 0
		weapon_adrenaline 		= 0
		weapon_defibrillator 	= 0

		weapon_melee 			= 0 //ALL melee weapons
		//Individual melee weapons need to be deleted via modelname.
		//If you're building your own map, edit the missionfile to not allow certain melee weapons instead.

 	function AllowWeaponSpawn( classname )
 		if ( classname in weaponsToRemove )
 			return false;
 		return true;
 	// This applies for survivor bots only
 	function ShouldAvoidItem( classname )
 		if ( ( classname != "weapon_melee" ) && ( classname in weaponsToRemove ) )
 			return true;
 		return false;
function OnGameEvent_round_start_post_nav( params )
	//Remove weapon_*_spawn entities, with * being an entity name in "weaponsToRemove"
	EntFire( "weapon_spawn", "Kill" );
 	foreach( wep, val in DirectorOptions.weaponsToRemove )
 		EntFire( wep + "_spawn", "Kill" );

The hook functionAllowWeaponSpawncan't remove specific melee weapons, mounted / machine guns or carryable objects. Fortunately, it isn't too hard to make our own method. Using the existing OnGameEvent_round_start_post_nav function hook, we can use it to run a function that deletes weapons by its model name.

// Deletes weapons based on model name, meant for melee and carryables as 'AllowWeaponSpawn' DirectorOptions hook doesn't support doing so.
// You can use 'script __RunGameEventCallbacks("round_start_post_nav", {})' to force the game event callback to run after its registered
function OnGameEvent_round_start_post_nav( params )
	// Keep our model path names here; Can be fetched with the .GetModelName() method for CBaseEntity
	//// For melees, it doesn't remove ones already in a player's inventory, as those are "predicted_viewmodel" entities using the v_* prefix models.
	local ItemstoRemove_ModelPaths =
		// ** Melees **
		"models/weapons/melee/w_bat.mdl", // Baseball Bat
		"models/w_models/weapons/w_knife_t.mdl", // CS:S Knife

		// ** Mounted Guns **
		"models/w_models/weapons/w_minigun.mdl", // 'prop_minigun_l4d1'; Rapid firing gatling minigun found in maps like No Mercy
		"models/w_models/weapons/50cal.mdl", // 'prop_mounted_machine_gun' / 'prop_minigun'; The minigun found in Swamp Fever - Plantation

		// ** Carryable Props **
		"models/props_junk/explosive_box001.mdl", // Fireworks crate
	// automatically grab each index in the array
	foreach( modelpath in ItemstoRemove_ModelPaths )
		local weapon_ent = null
		while( weapon_ent = Entities.FindByModel(weapon_ent, modelpath) )

		/* Function above is same as doing this:
		while( weapon_ent = Entities.FindByModel(weapon_ent, modelpath) )

Replacing Weapons/Items

Msg("Replacing unwanted weapons");
DirectorOptions <-
 	weaponsToConvert =
	// "To Replace"		=	"Replace with *_spawn"
		weapon_smg		=	"weapon_smg_mp5_spawn"
		weapon_rifle	=	"weapon_rifle_sg552_spawn"

 	function ConvertWeaponSpawn( classname )
 		if ( classname in weaponsToConvert )
 			return weaponsToConvert[classname];
		return 0;

Default Weapons

This script makes Survivors spawn with predefined items in their inventory.

DirectorOptions <-
 	DefaultItems =
		//Using two "weapon_pistol" makes you spawn holding two pistols.

 	function GetDefaultItem( idx )
 		if ( idx < DefaultItems.len() )
 			return DefaultItems[idx];
 		return 0;

Map/Gamemode Specific Director Options

It is possible to make one single script for all maps of a campaign, which will automatically change a few settings if a specific map or gamemode is loaded.
Here's how to change director option based on map names:

if ( Director.GetMapName() == "MAP_NAME_1" || Director.GetMapName() == "MAP_NAME_2" || Director.GetMapName() == "MAP_NAME_3" )
	DirectorOptions.GasCansOnBacks <- true;

Here's how to change director option based on base gamemode:

if ( Director.GetGameModeBase() == "survival" || Director.GetGameModeBase() == "scavenge" || Director.GetGameModeBase() == "holdout" )
    DirectorOptions.GasCansOnBacks <- false;

The two above lines in the same script will enable the "Hard Rain" cans on the defined maps "MAP_NAME_1, MAP_NAME_2, and MAP_NAME_3. These cans will be disabled on those maps if played in Survival, Scavenge, Holdout and any game modes based on those.

See also




External links

Alternative Documentation