Mapbase/Scripting
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 toSetOrigin
.EntFire
can now take an optional caller at the end andEntFireByHandle
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 andplayer_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 thegame_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 aCAI_Squad
instance which exposes squad information. Squads can also be accessed through a newSquads
(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 withGetExpresser()
andCAI_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.