Left 4 Dead 2/Scripting

Left 4 Dead 2 VScripts are server-side scripts that are run in an in-game virtual machine. They are written in Squirrel, a compiled 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.

Global Scripts

Scripts can also be made to run on map load, based on game mode and optionally map name. These scripts are commonly used to create scripting and modify global Director options for mutations, but can also be used in custom maps.

Global scripts can have script hook functions added that get called from the game at certain events, like when players/objects take damage.

There are many utility functions and features readily available for these scripts, including a resource and building system, and custom panic wave spawning. Please see Valve's Expanded Mutation System tutorial for more information.

Other uses

All scripts can access functions for many features, including spawning entities either from precompiled lists or programmatically, spawning infected, a HUD system, storing data across levels and to disk, and much more.

Please see L4D2 Vscript Examples for more examples and ideas.

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

VScripts are loaded in different ways depending on what they are used for. They can alos be manually loaded with the console command script filename

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

The <map name>_finale.nut script is atumatically loaded when a finale map starts. The script is triggered 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 at map start

Uses the script set in the Entity Scripts KeyValue of the entity.

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.

Map Specific Scripts (only available in Scripted Mode)

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

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

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

Adding a script to the Entity Scripts KeyValue of a server-side entity loads the script as an Entity Script. The script is executed when the entity spawns, and loads into a unique script scope made up of an unique identifier followed by the entity name or class name.

A think function can be set with the thinkfunction KeyValue, the specified script function every 0.1 seconds. While it has the potential to become expensive, a programmer is able to limit the amount of code executed. Functions can also be manually called through the I/O system with the input RunScriptCode function_name(argument, ...).

Entity Scripts have a self reference to their owning entity handle, allowing the script easy access to control the entity through its class methods. There are also hook functions available depending on the entity class. Both methods and hooks are documented here.

Some entities have additional script functionality:

• point_script_use_target - Has both methods and hooks for controlling the button.
• logic_script - Can pass multiple entity names to the script as an array called EntityGroup.
• point_template
• env_entity_maker
• info_item_position

The script can be reloaded with console command ent_fire <name of entity> runscriptfile <relative vscript path>. This is useful for quick script reloading.

Scripted Mode

Adding a Mode Script will enable Scripted Mode for the game mode. This works on the base game modes included in the game as well.

Scripted Mode loads utility functions into the g_ModeScript scope, disables the hardcoded setting of 2 on the MaxSpecials Director Option, and enables game event callbacks and script hook functions.

Todo: Does enabling Scripted Mode have any other consequences?

Mode Scripts

Use script scope g_ModeScript

Map Scripts

Use script scope g_MapScript

Glossary

DirectorOptions

A table of named variables that override the AI Director behavior.

HScript

Todo: Seems to be another term for a script handle.

Script handle

An entity instance with accessors and mutators to the C++ entity object.

Script scope

The table where the variables, functions and classes of a VScript is placed.

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)

+ =