Left 4 Dead 2/Scripting

Left 4 Dead 2 vscripts are scripts that can be run in-game to perform various tasks and changes.

Stub

This article or section is a stub. You can help by expanding it.

Note:Information on vcripts is currently incomplete. Descriptions, accuracy, and information are subject to change.

Description

Left 4 Dead 2 vscripts are written in Squirrel, a compilable scripting language similar to Lua.

Some uses of vscripts include:

• Mini-games found in Dark Carnival - counters, timers, prop spawning
• Some Scavenge Logic
• Director manipulation - onslaughts, reserved wanderers, complete emptiness/silence, prohibition of boss infected (tanks and witches), direction of mobs
• Model manipulation - green diesel cans attached to survivors in Hard Rain
• Much more!

The file extensions of vscripts are .nut and .nuc, where .nut files are human readable using a text editor. Official .nuc script files are located in scripts/vscripts within pak01_dir.vpk (you can open this file with third party programs like GCFScape).

Some entities that accept vscripts as inputs or properties include info_director, logic_script, and trigger_finale.

Practicing the Squirrel language

Developers that would like to practice Squirrel can quickly set up an environment to do so. It can be as simple as opening up L4D2 and executing scripts from the console. One can also set up a light-weight squirrel interpretor from Windows Command Prompt:

Windows Command Prompt

1. Download and extract the Squirrel interpretor binary (Version 2.2, 32-Bit) to any folder. sq.exe is the interpretor. sq.exe can also be created by compiling from source code.
2. Any scripts within that folder are executed with the command sq filename.nut via Windows Command Prompt
   Tip:There are sample scripts included with the compiled binary. Try running something simple first, like the "Hello, World!" script. sq hello.nut
3. Optional: Set up a path to sq.exe within the Environment Variables in Windows. This allows convenient execution of .NUT scripts from any folder from the Command Prompt. Go to System Properties via the Control Panel, select the Advanced tab, and click the Environmental Variables button. Under System Variables select the Variable "Path" and click on the Edit button. Add the full path to sq.exe (for example, C:\Squirrel, where sq.exe is located in C:\Squirrel) to the other paths to the Variable Value. Restart the Command Prompt and sq filename.nut should be able to work from any folder.

Documentation and generic sample scripts can always be found at the official Squirrel Language site.

L4D2 Client

• info_director
  • Loads DirectorOptions such as onslaughts, panic events, infected limits, etc.
  • Can be loaded in console with ent_fire command ent_fire <targetname of info_director> BeginScript <name of script>
• logic_script
• Game Modes
  Todo: see if it also applies to coop, versus, etc.
  • Scavenge
    • A per-map script is loaded automatically during Scavenge Mode
    • Name the script <map name>_scavenge.nut.
    • For example, c1m4_atrium_scavenge.nut.
  • Mutators
    • Will automatically run the script with the same name as the game mode.
    • For example, running a map map <map name> realismversus will automatically load realismversus script.
• Events
  • Finale
    • "Script" KeyValue of trigger_finale does not need to be set up
    • Automatically loads <map name>_finale.nut script on finale trigger
    • Known to work in this fashion in Custom and Scavenge finale type (set up in trigger_finale)

Scripting samples

Warning:NEVER use the = operator when trying to influence the director. Use <-. The difference is semantics. If you use =, it will throw an error if the table slot isn't defined (like if a previous script didn't define it). <-, on the other hand, will create the variable if it does not exist. Some of these samples are only portions of a full script, so make sure that the variables are created beforehand.

Targeting entities with a director script

Add something like this in the script for your minifinale when your horde wave gets triggered:

{
EntFire( "church_bell_relay", "Trigger", 0 )
}

Then place a logic_relay with that name to send an output to your ambient_generic.

Triggering a panic event though a script

If you want to start a panic event through a script (not an onslaught) then use this:

DirectorOptions <-
{
A_CustomFinale1 = PANIC
A_CustomFinaleValue1 = 2
}

The number refers to the number of waves that you want in your minifinale. This is what was used at the ferry in the first map of Swamp Fever.

Handling a survivor

/***************************************
Get a handle on a specific survivor
- This is pretty hackish, I can't just say Entities.FindByName(null, "playername"), (YET) because
I don't know what it's expecting internally. And I can't "learn" it's name by saying survivior.GetName(),
because what that returns is just some a function ref, it's probably the C++ side wrapped in a closure, OPAQUE, bummer.
***************************************/

//Get Nick
Nick <- Entities.FindByModel(null,"models/survivors/survivor_gambler.mdl");
// Nick is class "player" (which must be related or superset of CBaseEntity)
Nick.SetHealth(0); // Ouch but he won't incap until hit again, even below zero
//or Super Nick!
Nick.SetHealth(50000); // Tank gonna get slapped to death.

Some General DirectorOptions

You can start a script with an input to the director "BeginScript" and then the name of the script in the parameters field. Place the script as a ".nut" file in your vscripts directory. To end the script, send an input to the director "EndScript".

Here are some examples:

DirectorOptions <-
{
ProhibitBosses = 1 (default is 0)
AlwaysAllowWanderers = 1 (default is 0)
MobMinSize = 10 (default)
MobMaxSize = 30 (default)
SustainPeakMinTime = 3 (default)
SustainPeakMaxTime = 5 (default)
IntensityRelaxThreshold = 0.9 (default)
RelaxMinInterval = 30 (default)
RelaxMaxInterval = 45 (default)
RelaxMaxFlowTravel = 3000 (default)
SpecialRespawnInterval = 45.0 (default)
NumReservedWanderers = 10 (default is 0)
}

You can play around with some of these numbers for specific events in your levels. For example, some of our scripts reduce the SpecialRespawnInterval to 30 seconds or we have some that reduce the RelaxMaxFlowTravel to 1000 so that the director won't stay relaxed if the survivors have continued far enough.

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
}
NavMesh.UnblockRescueVehicleNav()
Director.ResetMobTimer()

Dark Carnival Onslaught Script

Here's the onslaught script Valve used for the 4th map of Dark Carnival:

Msg("Initiating Onslaught\n");

DirectorOptions <-
{
// This turns off tanks and witches.
ProhibitBosses = false

//LockTempo = true
MobSpawnMinTime = 3
MobSpawnMaxTime = 7
MobMinSize = 30
MobMaxSize = 30
MobMaxPending = 30
SustainPeakMinTime = 5
SustainPeakMaxTime = 10
IntensityRelaxThreshold = 0.99
RelaxMinInterval = 1
RelaxMaxInterval = 5
RelaxMaxFlowTravel = 50
SpecialRespawnInterval = 1.0
PreferredMobDirection = SPAWN_IN_FRONT_OF_SURVIVORS
ZombieSpawnRange = 2000
}

Director.ResetMobTimer()

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: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

c1m4_atrium.nut (or <map_name>.nut)

This script is automatically loaded for the map c1m4_atrium in coop and single player mode.

Todo: specifically under what conditions?

c1m4_atrium_finale (or <map name>_finale) also relies on this script in certain cases.

Note:The description of the finale script was derived from the given c1m4_atrium_finale script comment: "// this is too late. Moved to c1m4_atrium.nut"

Msg(" atrium map script "+"\n")
 
// number of cans needed to escape.
 
if ( Director.IsSinglePlayerGame() )
{
                NumCansNeeded <- 8
}
else
{
                NumCansNeeded <- 13
}
 
 
DirectorOptions <-
{
               
CommonLimit = 15
 
}
 
NavMesh.UnblockRescueVehicleNav()
 
EntFire( "progress_display", "SetTotalItems", NumCansNeeded )
 
 
function GasCanPoured(){}

Other Possible Director Options

There are also other options that might work like the above. Some can be seen in console outputs in dev mode (for example, from <map name>_finale.nuc). They might work like the above scripts, but it appears that some may be affected by a local script that dynamically changes the variables. Here are some examples:

c1m4_atrium_finale (Scavenge Finale)

Note:This isn't the full list of variables that are output in the console as some are already known or repeated. The variables seem to change depending on multiple factors that include, but are not limited to, number of gas cans poured, number of times gas cans touched, and a timer. It may also be monitoring player status, somewhat like how the player is feeling in director_debug 1.

ShouldAllowMobsWithTank = true
ShouldAllowSpecialsWithTank = true
MinimumStageTime = 15
MobRechargeRate = 0.5
HordeEscapeCommonLimit = 15
MusicDynamicMobStopSize = 2
MusicDynamicMobSpawnSize = 8
BileMobSize = 15
PreferredSpecialDirection = 9 (In other examples, this was set as a string)
MusicDynamicMobScanStopSize = 2

A_CustomFinale[x]('x' seems to be any number, like up to 30) = 
A_CustomFinale1 = 3
A_CustomFinale2 = 0

A_CustomFinaleValue[x] = c1m4_delay

Tic-Tac-Toe mini-game

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

• Writing a Mini Game - Tic Tac Toe - Part One - Author's Website
• l4d2 - Vscript example - Tic-Tac-Toe - Video of early Prototype
• l4d2 - Vscript example - Tic-Tac-Toe - updated - Video of current version with "brutally misanthropic AI"

Overview of Squirrel in L4D2

The following are available in L4D2 by default.[2] Warning:NEVER use the = operator when trying to influence the director. Use <-. The difference is semantics. If you use =, it will throw an error if the table slot isn't defined (like if a previous script didn't define it). <-, on the other hand, will create the variable if it does not exist.

Variables

Todo: Add Variables

Classes

CDirector

Game Instance: Director

• Class Methods
  • GetFurthestSurvivorFlow
  • L4D1SurvivorGiveItem
  • ResetMobTimer
  • GetAveragedSurvivorSpeed
  • IsValid
  • IsSinglePlayerGame
  • GetAveragedSurvivorSpan
  • GetGameMode
  • IsPlayingOnConsole
  • HasAnySurvivorLeftSafeArea
  • PlayMegaMobWarningSounds
• Director Enumerations
  Note:These are (or some are) script specific, hence the duplicate values.
  • FINALE_CUSTOM_DELAY = 10
  • FINALE_CUSTOM_PANIC = 7
  • FINALE_CUSTOM_SCRIPTED = 9
  • FINALE_CUSTOM_TANK = 8
  • FINALE_FINAL_BOSS = 5
  • FINALE_GAUNTLET_1 = 0
  • FINALE_GAUNTLET_2 = 3
  • FINALE_GAUNTLET_BOSS = 15
  • FINALE_GAUNTLET_BOSS_INCOMING = 14
  • FINALE_GAUNTLET_ESCAPE = 16
  • FINALE_GAUNTLET_HORDE = 12
  • FINALE_GAUNTLET_HORDE_BONUSTIME = 13
  • FINALE_GAUNTLET_START = 11
  • FINALE_HALFTIME_BOSS = 2
  • FINALE_HORDE_ATTACK_1 = 1
  • FINALE_HORDE_ATTACK_2 = 4
  • FINALE_HORDE_ESCAPE = 6
  • SPAWN_ABOVE_SURVIVORS = 6
  • SPAWN_ANYWHERE = 0
  • SPAWN_BEHIND_SURVIVORS = 1
  • SPAWN_FAR_AWAY_FROM_SURVIVORS = 5
  • SPAWN_IN_FRONT_OF_SURVIVORS = 7
  • SPAWN_LARGE_VOLUME = 9
  • SPAWN_NEAR_IT_VICTIM = 2
  • SPAWN_NO_PREFERENCE = -1
  • SPAWN_SPECIALS_ANYWHERE = 4
  • SPAWN_SPECIALS_IN_FRONT_OF_SURVIVORS = 3
  • SPAWN_VERSUS_FINALE_DISTANCE = 8
  • ZOMBIE_TANK = 8
  • ZOMBIE_WITCH = 7

CEntities

Game Instance: Entities

• Class Methods
  • .FindByClassname
  • .FindByName
  • .FindByClassnameWithin
  • .FindByTarget
  • .FindByModel
  • .FindByClassnameNearest
  • .IsValid
  • .FindByNameWithin
  • .FindByNameNearest
  • .Next
  • .FindInSphere
  • .First

CBaseEntity

Game Instance: N/A

Note:There is a possibility that there is an instance that exists in-game. It hasn't been found yet.

• Class Methods
  • .ConnectOutput
  • .DisconnectOutput
  • .FirstMoveChild
  • .GetClassname
  • .GetForwardVector - returns Vector instance
  • .GetHealth
  • .GetMoveParent
  • .GetName
  • .GetOrigin
  • .GetPreTemplateName
  • .GetRootMoveParent
  • .GetScriptId
  • .GetScriptScope
  • .GetVelocity
  • .IsValid
  • .NextMovePeer
  • .SetForwardVector
  • .SetHealth
  • .SetOrigin
  • .SetVelocity("Vector instance")
  • .ValidateScriptScope
  • .__KeyValueFromInt
  • .__KeyValueFromString
  • .__KeyValueFromVector

CBaseAnimating

Extends CBaseEntity

• Class Methods
  • .__KeyValueFromInt
  • .__KeyValueFromString
  • .__KeyValueFromVector
  • .ConnectOutput
  • .DisconnectOutput
  • .FirstMoveChild
  • .GetClassname
  • .GetForwardVector - returns Vector instance
  • .GetMoveParent
  • .GetName
  • .GetOrigin
  • .GetPreTemplateName
  • .GetRootMoveParent
  • .GetScriptId
  • .GetScriptScope
  • .GetVelocity
  • .IsValid
  • .NextMovePeer
  • .SetForwardVector
  • .SetHealth
  • .SetOrigin
  • .SetVelocity("Vector instance")
  • .ValidateScriptScope

CNavMesh

Game Instance: NavMesh

• Class Methods
  • .IsValid
  • .UnblockRescueVehicleNav

CCallChainer

Game Instance: N/A

• Class Methods
  • .PostScriptExecute
  • .chains
  • .constructor
  • .prefix
  • .scope

CSimpleCallChainer

• Class Methods
  • .Call
  • .PostScriptExecute
  • .chain
  • .constructor
  • .exactMatch
  • .prefix
  • .scope

regxp

^[Todo] Game Instance:

• Class Methods

Vector

Game Instance: None

• Class Methods
  • .constructor
  • .Cross
  • .Dot
  • .Length
  • .Length2D
  • .Length2DSqr
  • .LengthSqr
  • .Norm
  • .ToKVString

Functions

Todo: Add Functions

Constants

Todo: Add Constants

See also

• L4D2 Level Design/Boss Prohibition
• Left 4 Dead 2 Tool Updates
• trigger_finale
• info_director
• logic_script

External links

• Director Scripts - .nuc files (Steam forums)
• It's the vscript'ing documentation FAQ! (Steam forums)
• Tutorial - Writing a Mini Game - Tic Tac Toe - Part One (Steam Forums)
  • Writing a Mini Game - Tic Tac Toe - Part One - Author's Website
  • l4d2 - Vscript example - Tic-Tac-Toe - Video of early Prototype
  • l4d2 - Vscript example - Tic-Tac-Toe - updated - Video of current version with "brutally misanthropic AI"
• Mutation scripts (Steam forums)
• Squirrel Binary for Windows
• Squirrel (programming language)
• Squirrel: The Programming Language - Documentation and Sample Code
• The AI Systems of Left 4 Dead by Michael Booth (PDF)