Skip to content

VScript in Mapbase

Jump to bottom
Blixibon edited this page May 25, 2020 · 48 revisions

NOTICE

This page is for the experimental VScript branch. These features are not yet available in the main build of Mapbase.

Mapbase supports a custom implementation of VScript based off of the Alien Swarm SDK and reductor's Squirrel integration. VScript is a scripting layer which allows external scripts to be used as an extension of map logic.

Mapbase's VScript is more limited and primitive compared to the VScript in Valve's games, as a lot of the original VScript code is inaccessible. Some common global methods and data types are not (yet) implemented, but since the Alien Swarm SDK includes entity script descriptions, most of the entity implementations are fully functional.

Mapbase's implementation of VScript does not use any leaked code whatsoever.

For more information on VScript itself, click here to see its article on the Valve Developer Community.

Contents

Known incompatibilities with Valve's VScript

List of L4D2 Script Functions

List of Portal 2 Script Functions

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

  • Most of the global functions are not yet available because many of them are game-specific and are not included in the Alien Swarm SDK.
    • Notable functions which are in Mapbase's implementation:
      • AddThinkToEnt
      • EntIndexToHScript
      • PrecacheEntityFromTable
      • SpawnEntityFromTable
  • Some singletons are not yet available.
    • Notable singletons which are in Mapbase's implementation:
      • Entities
      • Convars
  • It is currently not possible to use in-game documentation methods, such as script_help.
  • In the source code, the following IScriptVM functions are currently unsupported: ConnectDebugger, DisconnectDebugger, AddSearchPath, Frame, DumpState, SetOutputCallback, SetErrorCallback

Tutorials

A few tutorials are available for using VScript in Mapbase.

Documentation

A lot of the documentation for VScript on the VDC applies to Mapbase, but Mapbase also extends the VScript support in various ways, mostly to make it able to operate upon NPCs and other Source 2013/Half-Life 2 conventions.

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.

Other changes are documented below.

Global Functions

These are functions that can be accessed globally and without a class.

Signature Description
handle SpawnEntityFromKeyValues(string className, handle *keyValues) Spawns an entity with the keyvalues in a CScriptKeyValues handle.
handle GameOver(string message, float delay, float fadeTime, float loadTime, int r, int g, int b) Ends the game and reloads the last save.
bool MegaPhyscannonActive() Checks if supercharged gravity gun mode is enabled.

New VScript Classes

These are classes Mapbase exposes to VScript.

CBaseCombatCharacter

The base class shared by players and NPCs.

Signature Description
handle GetActiveWeapon() Get the character's active weapon entity.
handle GetWeapon(int index) Get a specific weapon in the character's inventory.
handle FindWeapon(string classname) Find a specific weapon in the character's inventory by its classname.
Vector ShootPosition() Get the character's shoot position.
void DropAllWeapons() Make the character drop all of its weapons.
void EquipWeapon() Make the character equip the specified weapon. If they don't already own the weapon, they will acquire it instantly.
int GetAmmoCount(string type) Get the ammo count of the specified ammo type.
void SetAmmoCount(string type, int count) Set the ammo count of the specified ammo type.
int GetRelationship(handle target) Get a character's relationship to a specific entity.
int GetRelationPriority(handle target) Get a character's relationship priority for a specific entity.
void SetRelationship(handle target, int disposition, int priority) Set a character's relationship with a specific entity.
handle GetVehicleEntity() Get the entity for a character's current vehicle if they're in one.
bool InViewCone(Vector target) Check if the specified position is in the character's viewcone.
bool EntInViewCone(handle target) Check if the specified entity is in the character's viewcone.
bool InAimCone(Vector target) Check if the specified position is in the character's aim cone.
bool EntInAimCone(handle target) Check if the specified entity is in the character's aim cone.
Vector BodyAngles() Get the body's angles.
Vector BodyDirection2D() Get the body's 2D direction.
Vector BodyDirection3D() Get the body's 3D direction.
Vector HeadDirection2D() Get the head's 2D direction.
Vector HeadDirection3D() Get the head's 3D direction.
Vector EyeDirection2D() Get the eyes' 2D direction.
Vector EyeDirection3D() Get the eyes' 3D direction.

CBaseCombatWeapon

The base class all equippable weapons derive from.

Signature Description
int Clip1() Get the weapon's current primary ammo.
int Clip2() Get the weapon's current secondary ammo.
void SetClip1() Set the weapon's current primary ammo.
void SetClip2() Set the weapon's current secondary ammo.
int GetMaxClip1() Get the weapon's maximum primary ammo.
int GetMaxClip2() Get the weapon's maximum secondary ammo.
int GetDefaultClip1() Get the weapon's default primary ammo.
int GetDefaultClip2() Get the weapon's default secondary ammo.
bool HasAnyAmmo() Check if the weapon currently has ammo or doesn't need ammo.
bool HasPrimaryAmmo() Check if the weapon currently has ammo or doesn't need primary ammo.
bool HasSecondaryAmmo() Check if the weapon currently has ammo or doesn't need secondary ammo.
bool UsesPrimaryAmmo() Check if the weapon uses primary ammo.
bool UsesSecondaryAmmo() Check if the weapon uses secondary ammo.
void GiveDefaultAmmo() Fill the weapon back up to default ammo.
bool UsesClipsForAmmo1() Check if the weapon uses clips for primary ammo.
bool UsesClipsForAmmo2() Check if the weapon uses clips for secondary ammo.
int GetPrimaryAmmoType() Get the weapon's primary ammo type.
int GetSecondaryAmmoType() Get the weapon's secondary ammo type.
int GetSubType() Get the weapon's subtype.
void SetSubType() Set the weapon's subtype.
int GetFireRate() Get the weapon's firing rate.
string GetWorldModel() Get the weapon's world model.
string GetViewModel() Get the weapon's view model.
float GetWeight() Get the weapon's weight.
bool CanBePickedUpByNPCs() Check if the weapon can be picked up by NPCs.

CAI_BaseNPC

The base class all NPCs derive from.

Signature Description
handle GetEnemy() Get the NPC's current enemy.
void SetEnemy(handle target) Set the NPC's current enemy.
Vector GetEnemyLKP() Get the last known position of the NPC's current enemy.
handle FindEnemyMemory() Get information about the NPC's current enemy.
string GetHintGroup() Get the name of the NPC's hint group.
int GetNPCState() Get the NPC's current state.
string GetHintGroup() Get the name of the NPC's hint group.
handle GetHintNode() Get the NPC's current AI hint.
int CapabilitiesGet() Get the capabilities the NPC currently possesses.
void CapabilitiesAdd(int capabilities) Add capabilities to the NPC.
void CapabilitiesRemove(int capabilities) Remove capabilities from the NPC.
void CapabilitiesClear() Clear capabilities for the NPC.
string GetActivity() Get the NPC's current activity.
int GetActivityID() Get the NPC's current activity ID.
void SetActivity(string activity) Set the NPC's current activity.
void SetActivityID(int activity) Set the NPC's current activity ID.
void ResetActivity() Reset the NPC's current activity.
string GetSchedule() Get the NPC's current schedule.
int GetScheduleID() Get the NPC's current schedule ID.
void SetSchedule(string schedule) Set the NPC's current schedule.
void SetScheduleID(int schedule) Set the NPC's current schedule ID.
string GetTask() Get the NPC's current task.
int GetTaskID() Get the NPC's current task ID.
void ClearSchedule(string reason) Clear the NPC's current schedule for the specified reason.
bool HasCondition(int condition) Get whether the NPC has a condition.
bool HasConditionID(int condition) Get whether the NPC has a condition ID.
void SetCondition(int condition) Set a condition on the NPC.
void SetConditionID(int condition) Set a condition on the NPC by ID.
void ClearCondition(int condition) Clear a condition on the NPC.
void ClearConditionID(int condition) Clear a condition on the NPC by ID.
bool IsMoving() Check if the NPC is moving.
handle GetExpresser() Get a handle for this NPC's expresser.
bool IsCommandable() Check if the NPC is commandable.
bool IsInPlayerSquad() Check if the NPC is in the player's squad.

Hooks

Signature Description
variable NPC_TranslateActivity() Translates a requested NPC activity to another activity. The requested activity is stored as a string in activity and as an integer in activity_id. Either an activity string or an activity ID can be returned. If either -1 or "ACT_INVALID" are returned, the activity will not be translated to anything different.
variable NPC_TranslateSchedule() Translates a requested NPC schedule to another schedule. The requested schedule is stored as a string in schedule and as an integer in schedule_id. Either a schedule name string or a schedule ID can be returned. If either -1 or "SCHED_NONE" are returned, the schedule will not be translated to anything different.

CAI_BaseActor

The base class for NPCs which act in complex choreo scenes.

Signature Description
void AddLookTarget(handle target, float importance, float duration, float ramp) Add a potential look target for this actor.
void AddLookTargetPos(Vector target, float importance, float duration, float ramp) Add a potential look target position for this actor.

CAI_Network

The global list of AI nodes. Can be accessed through a global AINetwork instance.

Signature Description
int NumNodes() Number of nodes in the level
Vector GetNodePosition(int nodeID) Get position of node using a generic human hull
Vector GetNodePositionWithHull(int nodeID, int hull) Get position of node using the specified hull
float GetNodeYaw(int nodeID) Get yaw of node
float NearestNodeToPoint(Vector position, bool checkVisibility) Get ID of nearest node
float NearestNodeToPointForNPC(handle npc, Vector position, bool checkVisibility) Get ID of nearest node
int GetNodeType() Get a node's type
handle GetNodeHint() Get a node's hint

CAI_Hint

An entity which gives contextual pointers for NPCs.

Signature Description
int GetHintType() Get the hint's type ID.
handle GetUser() Get the hint's current user.
string GetHintGroup() Get the name of the hint's group.
string GetHintActivity() Get the name of the hint activity.
bool IsDisabled() Check if the hint is disabled.
bool IsLocked() Check if the hint is locked.
int GetHintType() Get the hint's node ID.
float Yaw() Get the hint's yaw.
Vector GetDirection() Get the hint's direction.

CAI_Expresser

Expresser class for complex speech. Typically accessed through GetExpresser(). Not all NPCs/players have an expresser.

Signature Description
bool IsSpeaking() Check if the actor is speaking.
bool CanSpeak() Check if the actor can speak.
bool BlockSpeechUntil(float time) Block speech for a certain amount of time. This is stored in curtime.
void ForceNotSpeaking() If the actor is speaking, force the system to recognize them as not speaking.
void SpeakRawScene(string scene, float delay) Speak a raw, instanced VCD scene as though it were played through the Response System. Return whether the scene successfully plays.
void ScriptSpeakAutoGeneratedScene(string soundname, float delay) Speak an automatically generated, instanced VCD scene for this sound as though it were played through the Response System. Return whether the scene successfully plays.

AI_EnemyInfo_t

Accessor for information about an enemy. Typically accessed through FindEnemyMemory().

Signature Description
handle Enemy() Get the enemy.
void SetEnemy(handle target) Set the enemy.
Vector LastKnownLocation() Get the enemy's last known location.
void SetLastKnownLocation(Vector target) Set the enemy's last known location.
Vector LastSeenLocation() Get the enemy's last seen location.
void SetLastSeenLocation(Vector target) Set the enemy's last seen location.
float TimeLastSeen() Get the last time the enemy was seen.
void SetTimeLastSeen(float time) Set the last time the enemy was seen.
float TimeFirstSeen() Get the first time the enemy was seen.
void SetTimeFirstSeen(float time) Set the first time the enemy was seen.
float TimeLastReacquired() Get the last time the enemy was reaquired.
void SetTimeLastReacquired(float time) Set the last time the enemy was reaquired.
float TimeLastReceivedDamageFrom() Get the last time damage was received from this enemy.
void SetTimeLastReceivedDamageFrom(float time) Set the last time damage was received from this enemy.
float TimeAtFirstHand() Get the time at which the enemy was seen firsthand.
void SetTimeAtFirstHand(float time) Set the time at which the enemy was seen firsthand.
bool DangerMemory() Get the memory of danger position w/o enemy pointer.
void SetDangerMemory(bool value) Set the memory of danger position w/o enemy pointer.
bool EludedMe() Get whether the enemy is not at the last known location.
void SetEludedMe(bool value) Set whether the enemy is not at the last known location.
bool Unforgettable() Get whether the enemy is unfortgettable.
void SetUnforgettable(bool value) Set whether the enemy is unfortgettable.
bool MobbedMe() Get whether the enemy was part of a mob at some point.
void SetMobbedMe(bool value) Set whether the enemy was part of a mob at some point.

CGlobalState

Global state system. Can be accessed through a global Globals instance.

Signature Description
int GetIndex(string globalName) Gets the index of the specified global name. Returns -1 if it does not exist.
int AddGlobal(string globalName) Adds a new global with a specific map name and state. Returns its index.
int GetState(string globalName) Gets the state of the specified global.
void SetState(string globalName, int state) Sets the state of the specified global.
int GetCounter(string globalName) Gets the counter of the specified global.
void SetCounter(string globalName, int counter) Sets the counter of the specified global.
void AddToCounter(string globalName, int counter) Adds to the counter of the specified global.

CMapbaseSystem

All-purpose Mapbase system primarily used for map-specific files. Can be accessed through a global Mapbase instance.

Signature Description
void AddManifestFile(string fileName) Loads a manifest file.
void LoadSoundscriptFile(string fileName) Loads a custom soundscript file.
void LoadTalkerFile(string fileName) Loads a custom talker file.
void LoadActbusyFile(string fileName) Loads a custom actbusy file.

CLogicExternalData

An entity which loads keyvalues from an external data file.

Signature Description
handle GetKeyValues() Gets the external data expressed in CScriptKeyValues.
handle GetKeyValueBlock() Gets the current external data block expressed in CScriptKeyValues.
void SetKeyValues(handle keyvalues) Sets the external data from a CScriptKeyValues object.
void SetKeyValueBlock(handle keyvalues) Sets the current external data block from a CScriptKeyValues object.
void LoadFile() Loads external data from the external file.
void SaveFile() Saves the external data to the external file.

Modified VScript Classes

These are classes that were already exposed to VScript, but have new features or changes included with Mapbase.

CBaseEntity

Root class of all server-side entities.

Signature Description
bool IsVisible(Vector target) Check if the specified position can be visible to this entity.
bool IsEntVisible(handle target) Check if the specified entity can be visible to this entity.
bool IsVisibleWithMask(Vector target, int traceMask) Check if the specified position can be visible to this entity with a specific trace mask.
int Classify() Get Class_T class ID
int GetSpawnFlags() Get spawnflags
void AddSpawnFlags() Add spawnflag(s)
void RemoveSpawnFlags() Remove spawnflag(s)
void ClearSpawnFlags() Clear spawnflag(s)
bool HasSpawnFlags() Check if the entity has specific spawnflag(s) ticked
int GetEffects() Get effects
void AddEffects() Add effect(s)
void RemoveEffects() Remove effect(s)
void ClearEffects() Clear effect(s)
void SetEffects() Set effect(s)
void IsEffectActive() Check if an effect is active

Hooks

Signature Description
bool InputInputName() Called when the entity receives an input from the I/O system. This already existed in L4D2, but Mapbase adds a parameter value which contains the input's parameter.

CBasePlayer

The player entity.

Signature Description
handle GetExpresser() Get a handle for this player's expresser.

CScriptKeyValues

Wrapper class over KeyValues instance.

Signature Description
string GetName() Given a KeyValues object, return its name.
int GetInt() Given a KeyValues object, return its own associated integer value.
float GetFloat() Given a KeyValues object, return its own associated float value.
string GetString() Given a KeyValues object, return its own associated string value.
bool GetBool() Given a KeyValues object, return its own associated bool value.
void SetKeyInt(int value) Given a KeyValues object and a key name, set associated integer value.
void SetKeyFloat(float value) Given a KeyValues object and a key name, set associated float value.
void SetKeyBool(bool value) Given a KeyValues object and a key name, set associated bool value.
void SetKeyString(string value) Given a KeyValues object and a key name, set associated string value.
void SetName(string name) Given a KeyValues object, set its name.
void SetFloat(float value) Given a KeyValues object, set its own associated float value.
void SetBool(bool value) Given a KeyValues object, set its own associated bool value.
void SetString(string value) Given a KeyValues object, set its own associated string value.
  • Something Index
    • Something special
    • Something else
Clone this wiki locally