Skip to content

VScript in Mapbase

Jump to bottom
Blixibon edited this page Apr 7, 2021 · 48 revisions

VScript is a scripting layer which allows external scripts to be used as an extension of map logic. It was originally created by Valve for Left 4 Dead 2 and has existed in the majority of their games ever since.

Mapbase supports a custom implementation of VScript based off of the Alien Swarm SDK and the public Squirrel API. It was originally created by reductor with the goal of creating a legal, open-source version of VScript in Source 2013. Mapbase's implementation of VScript does not use any leaked code whatsoever.

Because a lot 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 the Valve Developer Community, and code created for the purpose of adding more capabilities in a Source 2013/Half-Life 2 setting. Overall, it's much different 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.

For more information on VScript itself, click here to see its article on the Valve Developer Community. See Using VScript as a HL2 mapper if you're coming to VScript as a HL2/Source 2013 mapper with no prior VScript experience.

Contents

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 are not yet available because many of them are game-specific and are not included in the Alien Swarm SDK.
  • Some singletons are not yet available for the same reason.
  • script_debug is not supported.
  • 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.

Tutorials

A few tutorials are available for using VScript in Mapbase.

Using VScript as a HL2 mapper

Documentation

List of L4D2 Script Functions

List of Portal 2 Script Functions

Half-Life Alyx Scripting API

A lot of the documentation for VScript on the VDC applies to Mapbase, but Mapbase has many changes which do not exist in Valve's games, so it has its own documentation as well.

However, because of the lack of automation and the amount of work needed to document it online, no full online documentation exists for Mapbase's VScript functions, constants, or classes. Instead, users could use the script_help command in-game. This command allows users to print documentation to the console for any functions, constants, or classes which involve the entered text. For example, you can type script_help collision to get all functions or constants with "collision" in their names or documentation text.

New Utilities

In addition to the original VScript inputs, Mapbase introduces a new RunScriptCodeQuotable input. This operates the same way as RunScriptCode, but double apostrophes ('') are converted to quotation marks ("), allowing code with strings to be run from Hammer and in-game ent_fire.

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: proper tutorial?)
  • 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, etc. (you can even get a struct for enemy memory information)
  • 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 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 "_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.

Msg("Helloooo!! VScript calling!\n")

vecTest <- Vector(5,23,41)
Msg("Here's a vector for your troubles: " + vecTest + "\n")

randTool <- "something"
switch (RandomInt(1,3))
{
    case 1:
        randTool = "carve";
        break;
    case 2:
        randTool = "Hammer";
        break;
    case 3:
        randTool = "Source";
        break;
}

Warning("Don't use " + randTool + "\n")

VScript in VBSP

  • Something Index
    • Something special
    • Something else
Clone this wiki locally