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:There is currently little information on vscripts. Descriptions 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:

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, as well.
2. Any scripts within that folder are executed with the command sq filename.nut via Windows Command Prompt
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.

Scripting samples

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.

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()

Dead Center Chapter 3 Special Infected Limit

Note:This appears to be incomplete. There is no noticeable increase in the "Special Max" as shown in the director debug panel (console command director_debug 1). It could be that map needs to be included in a mission file loaded by the client.

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

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)
• 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)