View source for Mapbase/Scripting

{{Main|VScript}}
Mapbase supports a custom implementation of VScript based off of the {{astools|1.bold}} and the public {{sq|4.1}} API. It was created by a Mapbase contributor (reductor) to serve as a legal, open-source version of VScript in Source 2013. Mapbase's implementation of VScript does not use any leaked code whatsoever.

Because most of the original VScript code is inaccessible, Mapbase's VScript is composed of code and script descriptions from the Alien Swarm SDK, code inspired by VScript documentation from other games, and code created for the purpose of adding more capabilities in a Source 2013/Half-Life 2 setting. Overall, it has many differences from the VScript in Valve's games and it diverges a lot from what VScript was originally meant to be capable of. More information on what's different in Mapbase's VScript can be found below.

= Documentation =
Please see the following articles for VScript documentation in Mapbase:
* [[Mapbase/Scripting/Script Functions|List of Mapbase Script Functions]]
* [[Mapbase/Scripting/Script Functions/Constants|List of Mapbase Script Constants]]
* [[Mapbase/Scripting/Using VScript as a HL2 mapper|Using VScript as a HL2 mapper]]
* [[Mapbase/Scripting/Tutorials|Mapbase VScript Tutorials]]

= Known incompatibilities with Valve's VScript =

Some features from Valve's games are not available in Mapbase's implementation of VScript, although some may be available in the future.

* Some of the global functions and singletons are not yet available because many of them are game-specific and are not included in the Alien Swarm SDK.
* In the source code, the following <code>IScriptVM</code> functions are currently unsupported: <code>ConnectDebugger</code>, <code>DisconnectDebugger</code>, <code>AddSearchPath</code>, <code>Frame</code>, <code>DumpState</code>, <code>SetOutputCallback</code>, <code>SetErrorCallback</code>

The following differences are intentional:

* <code>SetAngles</code> now takes a `Vector` instead of a separate pitch, yaw, and roll, similar to <code>SetOrigin</code>.
* <code>EntFire</code> can now take an optional caller at the end and <code>EntFireByHandle</code> no longer requires all parameters.

= Players, NPCs, and Weapons =

Mapbase exposes player, NPC, and weapon classes/functions primarily used in Half-Life 2. They allow VScript to know and do more about the current state of entities which would be highly prominent in mods using Mapbase.

Players and NPCs share a single class called {{ent|CBaseCombatCharacter}}, which is one of the classes extensively exposed to VScript by Mapbase. More documentation can be given with the <code>script_help</code> command, but it contains several functions for reading weapon-related data, including the amount of ammo a NPC or player currently has. Weapons themselves have also been exposed with most of the functions regularly used in the code.

In spite of the overlap, players and NPCs have been given their own exclusive functions as well. Not all of them are listed here, but here's a basic overview of what can now be done:

=== Players (CBasePlayer) ===

* There are now functions for monitoring and controlling the player's "button mask", or which binds the player is holding down. This is used by <code>game_ui</code> to detect what the player is pressing and <code>player_speedmod</code> suppresses abilities by selectively preventing certain buttons from being added to the button mask. ''(Both features can also be used through these new VScript functions)''
* There are now functions for detecting HEV suit properties, like the amount of armor, aux power, flashlight battery, etc. are available and whether certain suit features are being used.
* In HL2's HEV suit, support for custom suit devices has been added. {{todo|Tutorial for this?}}
* A <code>PlayerRunCommand</code> hook has been added for controlling the player's movement and button commands as an alternative to the <code>game_ui</code> entity.

=== NPCs (CAI_BaseNPC) ===

* Functions and classes exist for enemy-related operations, including getting a handle for the current enemy, getting the enemy's last known position, getting enemy memory information, etc.
* Functions exist for NPC squads and a <code>GetSquad()</code> function can return a <code>CAI_Squad</code> instance which exposes squad information. Squads can also be accessed through a new <code>Squads</code> (<code>CAI_SquadManager</code>) singleton.
* There are functions for reading, detecting, and controlling a NPC's schedules, conditions, and tasks. A <code>NPC_TranslateSchedule</code> hook exists for translating a NPC's current schedule.
* There are functions for reading, setting, and translating a NPC's activities. A <code>NPC_TranslateActivity</code> hook exists for translating a NPC's activity from one animation to another under certain conditions.
* A <code>CAI_Expresser</code> instance can be accessed with <code>GetExpresser()</code> and <code>CAI_BaseActor</code> is exposed with a few actor-related functions. These are mostly useful for NPC speech and choreography.

= VScript in VBSP =
As of Mapbase v6.0, VBSP is capable of supporting a VScript VM which can read from and write to a compiling map. As of writing, this is a work-in-progress feature and its abilities are mostly limited to operating upon entities.

VScript in VBSP can be enabled with the <code>-scripting</code> launch parameter. When this is enabled, VBSP will seek out a <code><mapname>_vbsp.nut</code> file in the same directory as the VMF. To print documentation for VScript in VBSP, the <code>-doc</code> launch parameter could also be used.