Left 4 Dead 2/Scripting

Left 4 Dead 2 VScripts are server-side scripts that are run in an in-game scripting engine. They are written in Squirrel, a compilable scripting language similar to Lua.

Uses

Director Scripts

The most common use of VScripts in Left 4 Dead 2 is to influence the behavior of the AI Director. These scripts can range from simple adjustments of infected spawning and prohibiting boss infected, to custom events like onslaughts and gauntlets, and even complex staged panic events and fully custom finales. Most of the events in the official campaigns are mainly implemented this way.

Director Scripts work mainly by writing overriding values of the various variables used by the Director into a DirectorOptions table.

Only one Director Script can be running at a time. Executing a new one will terminate any previous running one and remove any values it set in DirectorOptions.

Entity Scripts

Another common use is to attach a script to an entity. The script provides easy access to read and modify many of the entity's properties, and even to write new KeyValues. This allows for controlling entities in ways that would be very complicated or impossible to with the entity I/O system in Hammer.

Any entity is capable of running a script, and has the ability to set a specified think function to run every 0.1 seconds, as well as executing script code as an entity output.

Some entities also have specialized functions for VScripts, with the most prominent being point_script_use_target, which allows for turning other entities into fully programmable timed buttons. Other examples are logic_script, that is designed specifically to run VScripts, as well as point_template and env_entity_maker.

Global Scripts

Scripts can also be made to run globally based on map and game mode. These scripts are commonly used to create scripting and modify global Director options for mutations.

Please see Valve's Expanded Mutation System tutorial for more information.

Script files

The scripts are loaded from text files with the file extensions .nut and .nuc, where .nuc denotes encryption of plain text .nut. Custom scripts are read from \left 4 dead 2\left4dead2\scripts\vscripts\, as well as \scripts\vscripts\ when packed into a .vpk file.

Location

Official .nuc script files are located in scripts/vscripts in multiple locations

Note:Browse and extract VPK files with third-party programs like GCFScape.

• left 4 dead 2\left4dead2\pak01_dir.vpk

• left 4 dead 2\left4dead2_dlc1\pak01_dir.vpk

April 22, 2010 The Passing update

• left 4 dead 2\left4dead2_dlc2\pak01_dir.vpk

October 5, 2010 The Sacrifice update

• left 4 dead 2\left4dead2_dlc3\pak01_dir.vpk

March 22, 2011 Cold Stream Beta / L4D1 Transition Project update

• left 4 dead 2\update\pak01_dir.vpk

This is where mutations were updated/replaced bi-weekly.

• left 4 dead 2\sdk_content\scripting\scripts\vscripts\

Plaintext versions of many of the scripts introduced in the EMS update.

Decrypting NUC files

.nuc files are ICE encrypted .nut files. The encryption key is SDhfi878. You can use VICE to decode them.

Packages with deciphered official scripts are also available.

Loading vscripts

Director Scripts

Using the info_director entity using the following inputs

BeginScript <script name>

Executes a generic Director script, for example for onslaught events or changing spawning behavior.

EndScript

Ends the running script and resets the Director options to the map specific values.

BeginScriptedPanicEvent <script name>

Begins a Scripted Panic event.

Note:Scripts used with BeginScriptedPanicEvent will not work if they are in a subdirectory, even though you can use subdirectories in other script contexts. They must reside under the vscripts folder, or they will simply act as a 1 stage 1 second delay.

Finale scripts

Automatically loads the <map name>_finale.nut script on map start. The script is executed when the trigger_finale is used, either manually by the player, or with the ForceFinaleStart input.

Todo: trigger_finale also has an option to specify a finale script, but it doesn't seem to work

All Director Scripts are placed in the script scope DirectorScript

Entity Scripts

Automatic loading

Uses the script set in the Entity Scripts KeyValue.

Manual loading

Using the RunScriptFile input.

Entity Scripts are placed in the script scope _<unique ID>_<entity name>

Global Scripts

Mode Specific Scripts

Will automatically run the script with the same name as the game mode. For example, running a map map <map name> mutation12 will automatically load the Realism Versus script, mutation12.nuc.

They are placed in the script scope g_ModeScript

Note:Adding a script for a mode will enable Scripted Mode on it. This works on the base modes as well, and will enable EMS game event callbacks and hooks.

Todo: Does this have any other consequences?

Map Specific Scripts

Per-map scripts can be created that run when the map is loaded in the specified game mode, using the syntax <map name>_<mode name>.nut, for example, c1m4_atrium_mutation12.nut.

They are placed in the script scope g_MapScript

Example scripts

Please see L4D2 Vscript Examples.

Scripting environment

Please see List of L4D2 Script Functions for built in classes and functions.

Todo: Add better description of the script scopes.

Table structure

DirectorScript = 			//Director scripts get loaded here.
{
	DirectorOptions 		//Active when a director script is, and during scripted events and finales(?).
	MapScript =  			//Reference to g_MapScript. Contains initial values.
	{
		BaseScriptedDOTable 	//Hardcoded DirectorOptions.
		ChallengeScript = 	//Reference to g_ModeScript. Contains initial values.
		{
			MutationState 	//Populated with the the mode and map names.
		}
		LocalScript =
		{
			DirectorOptions //Current DirectorOptions(?).
		}
	}
}
g_MapScript = 				//Map specific scripts get loaded here.
{
	MapOptions 			//Initial values for SessionOptions.
	MapState 			//Initial values for SessionState.
}
g_ModeScript = 				//Mode specific scripts get loaded here (Scripted mode only).
{
	DirectorOptions 		//Current Director options, outside scripted events.
	MutationState 			//Initial values for SessionState.
	MutationOptions 		//Initial values for SessionOptions.
}
g_rr
g_RoundState
SessionOptions 				//Global Director options (Scripted mode only).
SessionState  				//State variables for game modes (Scripted mode only).

Delegation

Some of the tables have delegation set up, so that if a key isn't present in it, any operation done to done to the value, including creating the slot, is done to its parent-table instead.

DirectorOptions

DirectorScript.DirectorOptions < g_MapScript.DirectorOptions < g_MapScript.LocalScript.DirectorOptions < g_ModeScript.DirectorOptions

Entity Scripts

It has been suggested that this article or section be merged with L4D2 Entity Scripts. (Discuss)

Uses script scope _<unique ID>_<entity name>

^[Todo]

• Any entity is capable of loading a script on map spawn.
• The vscript can be reloaded with console command ent_fire <name of entity> runscriptfile <relative vscript path>. This is useful for quick script reloading.
• Script functions can be called with entity inputs like RunScriptCode.
• Features thinkfunction, a keyvalue that calls a user-defined function every 0.1 seconds. While it has the potential to become expensive, a programmer is able to limit the amount of code executed. The shoot gallery in Dark Carnival relies on this.
• Some functions are specialized for certain entity classes, such as point_template and env_entity_maker.
• Also available is logic_script, an entity that registers multiple entities as an array EntityGroup.

Global Scripts

It has been suggested that this article or section be merged with L4D2 Global Scripts. (Discuss)

^[Todo]

Mode Scripts

Uses script scope g_ModeScript

Note:Adding a script for a mode will enable Scripted Mode on it. This works on the base modes as well, and will enable EMS game event callbacks and hooks.

Todo: Does this have any other consequences?

Map Scripts

Uses script scope g_MapScript

Director options

Please see L4D2 Director Scripts for a table of available options.

Third party tools

Todo: Add info about VSLib

See also

• L4D2 Vscript Examples
• List of L4D2 Script Functions
• Extended Mutation System
• L4D2 Level Design/Boss Prohibition
• Left 4 Dead 2 Tool Updates
• Mutation Gametype (L4D2)
• trigger_finale
• info_director
• logic_script
• vscripts

External links

Alternative Documentation

• 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) - Wikipedia Article on Squirrel
• Squirrel: The Programming Language - Documentation and Sample Code
• The AI Systems of Left 4 Dead by Michael Booth (PDF)
• "Creating a "Money"/Point System" - Swarm Armory

Deciphered Official Scripts

• Version 2.0.1.8 and all mutations
• Version 2.0.8.4 (August 16, 2011)

+ =