VScript Fundamentals

This article aims to describe fundamental concepts and uses of VScript scripting.

^[Todo]

Tables and Script Scopes

The scripting environment consists of associative arrays, or tables, nested inside each other.

When a script is loaded, it is placed inside a table called 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.

Script Handles

Interaction with in-game entities is done through script handles, which are objects that reference a specific entity. The script handles contain accessor and and mutator methods to read and modify the entity properties. What methods are available depend on the game and entity type. See the scripting API reference for each game for more information.

All server-side entities currently in play can be searched and iterated through with the CEntities class object, Entities.

Entity Scripts

Adding a script to the vscripts (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 script scope made up of an unique identifier followed by the entity name or class name; _<unique ID>_<entity name>, placed in the root table.

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, ...).

An Entity Script has a self reference to their owning script handle, allowing the script easy access to control the entity through its class methods.

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

I/O system interaction

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

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 Output, since it will corrupt the map file. This means that strings cannot be passed with RunScriptCode.

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.

For the duration of the 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.

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

Glossary

Entity handle: An opaque entity reference of the C++ EHANDLE type. 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. Also known as HScript or HSCRIPT in the C++ code.
Script scope: The table where the variables, functions and classes of a VScript are placed.