Mapbase/Scripting

Main article:  VScript

Mapbase supports a custom implementation of VScript based off of the Alien Swarm - SDK and the public Squirrel 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:

• List of Mapbase Script Functions
• List of Mapbase Script Constants
• Using VScript as a HL2 mapper
• 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.
• script_debug is not supported.
  Todo: Change if and when this is merged
• In the source code, the following IScriptVM functions are currently unsupported: ConnectDebugger, DisconnectDebugger, AddSearchPath, Frame, DumpState, SetOutputCallback, SetErrorCallback

The following differences are intentional:

• SetAngles now takes a `Vector` instead of a separate pitch, yaw, and roll, similar to SetOrigin.
• EntFire can now take an optional caller at the end and EntFireByHandle 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 CBaseCombatCharacter, which is one of the classes extensively exposed to VScript by Mapbase. More documentation can be given with the script_help 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 game_ui to detect what the player is pressing and player_speedmod 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 PlayerRunCommand hook has been added for controlling the player's movement and button commands as an alternative to the game_ui 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 GetSquad() function can return a CAI_Squad instance which exposes squad information. Squads can also be accessed through a new Squads (CAI_SquadManager) singleton.
• There are functions for reading, detecting, and controlling a NPC's schedules, conditions, and tasks. A NPC_TranslateSchedule hook exists for translating a NPC's current schedule.
• There are functions for reading, setting, and translating a NPC's activities. A NPC_TranslateActivity hook exists for translating a NPC's activity from one animation to another under certain conditions.
• A CAI_Expresser instance can be accessed with GetExpresser() and CAI_BaseActor 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 -scripting launch parameter. When this is enabled, VBSP will seek out a <mapname>_vbsp.nut file in the same directory as the VMF. To print documentation for VScript in VBSP, the -doc launch parameter could also be used.