VScript Fundamentals

Template:Otherlang2 This article aims to describe fundamental concepts, and common uses of VScript scripting. It will not go into all concepts related to the language itself, so things such as explaining what are variables or data types will be ignored.

Running Code

VScripts are loaded in a variety of ways, but there are 3 main notable approaches, with a few examples:

Source

• Console commands
  • script
  • - Runs the inputted text as code. Will all be treated as on one line.
  • script_execute
  • - The script identical to the given name will be executed, so it starts running.
• Hammer I/O system
  • RunScriptCode - Input
  • - Runs the given text as code in one line, but double quotation marks cannot be used as it will corrupt your VMF, so you can't pass strings. Otherwise is identical to scriptcommand.
  • RunScriptFile - Input
  • - Start running a script of the same given name. Identical to script_executecommand.
• Scripts named in a specific manner

Script Scopes

Source

The scripting environment consists of associative arrays, or tables, nested inside each other. Thus, when a script is loaded, it is placed inside a table (referred as its script scope), and any code inside the script is executed. All variables, functions and classes in the script persist in the script scope after the code has finished executing.

As they're just arrays / tables, you can iterate through them to view every data within the scopes. The provided function below (taken from ) will let you do this; Just put it into its own.nutscript file, then usescript_execute with it.

// This function is a slightly edited variant of the one in L4D2 (g_ModeScript.DeepPrintTable())
// so Valve did the most work here (Kerry specifically?)
// ++ NOTES ++
// Use these methods when using a specific value type as the first argument, else you get an iteration error!
// Functions - function.getinfos() method [Squirrel v3 and above only, so CS:GO wouldn't have this, but L4D2 would]
// Instances - instance.getclass() method

function DeepPrintTable( debugTable, prefix = "" )
{
	if (prefix == "")
	{
		printl("{")
		prefix = "   "
	}
	foreach (idx, val in debugTable)
	{
		if ( typeof(val) == "table" )
		{
			printl( prefix + idx + " = \n" + prefix + "{")
			DeepPrintTable( val, prefix + "   " )
			printl(prefix + "}")
		}
		else if ( typeof(val) == "string" )
			printl(prefix + idx + "\t= \"" + val + "\"")
		else
			printl(prefix + idx + "\t= " + val)
	}
	if (prefix == "   ")
		printl("}")
}
DeepPrintTable( getroottable() )

Script Handles

Interaction with in-game entities is done through script handles, which are custom objects that keep a reference specific entity, by using their entity index. These objects contain methods for getting / setting an entity's properties. Some entities belong to a certain "class", which comes with its own additional unique methods. All server-side entities currently in play can be fetched through methods available from theEntitiesinstance;inheriting theCEntitiesobject. (Examples below)

See the API reference of the respective game for your project to know all available methods.

Source

// Use Entities.FindByClassname to get all "prop_physic" entities
local ent = null
while( ent = Entities.FindByClassname(ent, "prop_physics") )
{
   printl(ent)
}

Entity Scripts

A common VScript feature is to augment the features of entities using Entity Scripts, which are the specified scripts in thevscriptskeyvalue, or ones that are created by other scripts in engine runtime. In Hammer, the I/O system provides inputs to run code for these entity scripts (theRunScriptCodeinput), while in other VScripts, CBaseEntity class's method functions.GetScriptScope()and.ValidateScriptScope()allows creations or manipulation of Entity Scripts at runtime.

Entity Scripts also get access to various features, such as "Input Hooks" or "Think Functions". This is only a quick introduction; See the main article for full info.

I/O system interaction

Firing Inputs

If available in the game API, scripts can use the EntFire() and DoEntFire() functions to fire outputs to map entities. More functions may be available depending on game.

If arguments for activator and caller are available in the functions, they take a script handle and can be used to fire an output to an entity using the "!self" or "!activator" keyword, even without having to know its name, as long as the handle is available.

Arbitrary VScript code can be run from the I/O system, using the RunScriptCode input available in all entities. The code will run in the calling entities script scope.

Warning:Never use double-quotation marks in any Hammer input, as it will corrupt the VMF. This means that strings cannot be passed with RunScriptCode.

Tip:TeamSpen210's Hammer Addons include a workaround for this - backticks ( ` ) are swapped to quotes during compile, allowing strings to be passed.

Example Squirrel code:

// Sets the health of the entity owning the script scope to 500.
DoEntFire( "!self", "SetHealth", "500", 0, self, self )

Connecting Outputs

Using the CBaseEntity::ConnectOutput(string output, string function) method, an entity Output can be connected to a function in the script scope of the entity.

For the duration of the function call, the variables activator and caller are set to the handles of the activating and calling entities, allowing for example for an easy way to find which player triggered something.

Bug:In , these variables are not set correctly.  [todo tested in ?]

Example Squirrel code:

// Lights a prop on fire when it's used by the player.
function IgniteSelf()
{
	DoEntFire( "!self", "Ignite", "", 0, self, self )
}

// Connects the OnPlayerUse output to the above function.
self.ConnectOutput( "OnPlayerUse", "IgniteSelf" )

Input Hooks

When an entity receives an input, the game code will attempt to call a script function of the format Input<Name of Input>() in the receiving Entity Script. If the function returns false, the input is prevented from firing. As with connected output functions, the variables activator and caller are set to the handles of the activating and calling entities.

Note:The input name is case sensitive, and uses the CamelCase format.

Note:Unlike for output functions, these are set correctly in .

Example Squirrel code:

// The script of a door or button. Intercepts the Unlock input,
// and doesn't allow the door/button to unlock until 5 inputs have been received.

UnlockCounter <- 5 // Counter local to the entity script scope.

// Called when the Unlock input is received.
function InputUnlock()
{
	UnlockCounter--

	if( UnlockCounter <= 0 )
	{
		return true // Allows the unlock
	}

	return false // Discards the input
}

Glossary

Entity handle

An opaque entity reference passing a C++ EHANDLE. Can only be compared with other handles or passed to API functions expecting them. Only used rarely.

Script handle

An entity instance with accessors and mutators to the C++ entity object. Represented as a HSCRIPT typedef in C++ code.

Script scope

Execution context of a script. A table where the variables, functions and classes of a VScript are placed.

API References

Squirrel

• List of L4D2 Script Functions
• List of Portal 2 Script Functions
• List of CS:GO Script Functions
• List of Reactive Drop Script Functions
• List of Nuclear Dawn Script Functions
• List of Contagion Script Functions

Lua

• Facepunch Wiki
• Dota 2 Scripting API
• Half:Life: Alyx Scripting API

See Also

• VScript
• Squirrel
• Left 4 Dead 2 Scripting
• Dota 2 Scripting
• Half-Life: Alyx Scripting