Left 4 Dead 2/Scripting

From Valve Developer Community
< Left 4 Dead 2
Revision as of 12:13, 16 April 2014 by Rectus (talk | contribs) (Merged DirectorOptions into a new page.)
Jump to navigation Jump to search

SquirrelLeft 4 Dead 2 Left 4 Dead 2 vscripts are Squirrel language-based scripts that can be run in-game. For examples, please see L4D2 Vscript Examples.

Description

Left 4 Dead 2 vscripts are written in Squirrel, a compilable scripting language similar to Lua. The file extensions are .nut and .nuc, where .nuc denotes encryption of plain text .nut.

Usage

  • Director manipulation - onslaughts, CI wanderer options, complete emptiness/silence, prohibition of boss infected (tanks and witches), direction of mobs, specific spawning behavior, etc.
  • Finale - Custom sequences of events, Gauntlet and Scavenge Logic
  • Complex entity scripting - entity I/O, logic, arithmetic, loops, counters, timers, prop spawning, etc. (Example: Dark Carnival mini-games)
  • Game modes such as Mutations and Scavenge
  • Miscellaneous!

Location

Official .nuc script files are located in scripts/vscripts in multiple locations
Note.pngNote: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

  • Entities
    • 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.
  • info_director
    • Loads DirectorOptions such as onslaughts, panic events, infected limits, etc.
    • Custom DirectorOptions are used frequently to tweak director behavior that best suits the environment. c1_mall_ambient.nut is one such example.
    • Uses script scope DirectorScript
Note.pngNote:Scripts used with ScriptedPanicEvent 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.
  • Game Modes
    • Mode Specific Script
      • 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.
      • Uses script scope g_ModeScript
      • Note.pngNote: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 Script
      • Per-map scripts can be created that run when the map is loaded in the specified game mode.
      • The script naming syntax is <map name>_<mode name>.nut.
      • For example, c1m4_atrium_mutation12.nut.
      • Uses script scope g_MapScript
  • Finale
    • Loaded via trigger_finale, either automatically or pointing to a specific vscript.
    • Automatically loads <map name>_finale.nut script on finale start.
    • Scavenge, Custom, and Gauntlet finales are dependent on vscripts.
    • Uses script scope DirectorScript

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 < DirectorScript.MapScript.DirectorOptions < DirectorScript.MapScript.LocalScript.DirectorOptions < DirectorScript.MapScript.ChallengeScript.DirectorOptions

Director scripts

Main Article: L4D2 Director Scripts

Todo: Add a short description of director scripts.

Director options

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

Mode and map scripts

[Todo]

Third party tools

Todo: Add info about VSLib

See also

External links

Alternative Documentation
Deciphered Official Scripts
Squirrel+Left 4 Dead 2 = Pnkhrt-16px.png
Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Left_4_Dead_2/Scripting&oldid=180961"