View source for Source 2013 MP/Scripting/VScript Examples

{{back|VScript}}
[[Category:VScript examples]]
[[Category:Scripting]]
This page contains examples of [[VScript]]s for games on the modern (2025) [[SDK 2013]] branch ({{tf2}}, {{css}}, {{dods}}, {{hl2dm}}, {{hldms}})

== Iterating Through Entities ==
With a<code>while</code>loop and a <tt>[[Left 4 Dead 2/Script Functions#CEntities|Entities]].FindByClassname()</tt> function, you can iterate through all entities of a matching classname, based on your arguments.

The first parameter of <tt>Entities.FindByClassname()</tt> is named 'previous' which accepts a script handle (if an entity inherits 'CBaseEntity' specifically), which verifies if the matching entity it finds has an entity index that's higher than the current one in the 'previous' argument. If it turns out to be not, then its ignored.
<source lang=js>
local entity = null
while (entity = Entities.FindByClassname(entity, "prop_physics"))
{
   printl(entity)
}</source>

Alternatively, entity iteration loops can also be written in an identical but more compact manner as shown here:
<source lang=js>
for (local entity; entity = Entities.FindByClassname(entity, "prop_physics");)
{
   printl(entity)
}</source>

== Iterating Through Players ==
It can be useful to iterate through players only. However, doing this with <tt>[[Left 4 Dead 2/Script Functions#CEntities|Entities]].FindByClassname()</tt> is inefficient as it needs to search every entity. A quirk can be utilised to efficiently iterate players. Each networked entity has an associated 'entity index', which ranges from 0 to [[Entity_limit|MAX_EDICTS]]. Usually these are unpredictable, however there is 2 groups of entities that have reserved entity indexes: [[worldspawn]] and players. [[Worldspawn]] is always reserved at entity index 0, and players are reserved from entity index 1 to [[Maxplayers|maxplayers]] + 1. Using this fact, players can be simply iterated like shown below:

{{note|The old way of iterating players was using <code>Constants.FServers.MAX_PLAYERS</code>. '''This is no longer recommended'''. Instead use MaxClients().tointeger() as shown below (only needs to be defined once in any file). MaxClients() only iterates the player limit set in the server rather than the maximum possible amount, which is more efficient, especially now that {{tf2}} supports 100 players, but most servers will only be 24/32!}}

<source lang=js>
::MaxPlayers <- MaxClients().tointeger()

for (local i = 1; i <= MaxPlayers ; i++)
{
    local player = PlayerInstanceFromIndex(i)
    if (player == null) continue
    printl(player)
}
</source>

== Iterating Through Player's Weapons ==
The maximum amount of weapons a player can hold under normal gameplay scenarios is 8. (As Engineer: primary, secondary, melee, construction PDA, destruction PDA, the toolbox, grappling hook and the 'passtime gun' when holding [[passtime_ball]])

<source lang=js>
::MAX_WEAPONS <- 8

for (local i = 0; i < MAX_WEAPONS; i++)
{
    local weapon = NetProps.GetPropEntityArray(player, "m_hMyWeapons", i)
    if (weapon == null)
        continue
    printl(weapon)
}
</source>

{{warning|{{tf2}} The <code>m_hMyWeapons</code> array looks like it might be sorted by slot numbers, but this is NOT always true. Items being removed (such as equipping a boots primary as demoman) will shift this array back by one. Weapons being stripped by other code or added via <code>Weapon_Equip</code> will also shift the array. Therefore, do not access <code>m_hMyWeapons</code> with hardcoded slot numbers.}}

== Spawning Entities ==

VScript offers four different ways to spawn entities, each with their own unique considerations.

=== Spawning an Entity ===

==== SpawnEntityFromTable ====

The simplest method.  Accepts a classname and a table of key-values. 

The following code will spawn a rocket projectile that does nothing. The rocket will be spawned from the host's eyes.

<source lang=js>
local player = GetListenServerHost()
local rocket = SpawnEntityFromTable("prop_dynamic_override", 
{
    // This is a table of keyvalues, which is the same way as keyvalues that are defined in Hammer
    // Key         Value
    origin       = player.EyePosition() + player.EyeAngles().Forward() * 32
    angles       = player.EyeAngles()
    teamnum      = player.GetTeam()
    model        = "models/weapons/w_missile.mdl"
})
rocket.SetMoveType(8, 0) // noclip
rocket.SetOwner(player) // make it not collide with owner
rocket.SetAbsVelocity(player.EyeAngles().Forward() * 250)
EntFireByHandle(rocket, "Kill", "", 5.0, null, null) // remove after 5 seconds
</source>

{{Important|For brush entities, the <code>mins</code> and <code>maxs</code> key-values must be set after the entity is spawned, either using <code>KeyValueFromString/KeyValueFromVector</code>, or the <code>SetSize</code> functions. 
 See the next example for spawning triggers.}}

==== CreateByClassname ====

In situations where you only need to spawn an entity temporarily, spawn a dummy entity for your script (e.g. attaching think functions), or you are spawning the entity in an already expensive function and are concerned about performance, <code>CreateByClassname</code> is more performant and generally recommended for these one-off situations.

The same example above using <code>CreateByClassname</code> instead:

<source lang=js>
local player = GetListenServerHost()

// certain models may not be precached and will crash the game with an error if not done here
// many models are already precached by the game and do not need this (e.g. player/weapon models)
PrecacheModel("models/weapons/w_missile.mdl")

local rocket = Entities.CreateByClassname( "prop_dynamic_override" )

rocket.SetOrigin( player.EyePosition() + (player.EyeAngles().Forward() * 32) )
rocket.SetAbsAngles(player.EyeAngles())
rocket.SetTeam(player.GetTeam())
rocket.SetModel("models/weapons/w_missile.mdl")
rocket.SetAbsVelocity(player.EyeAngles().Forward() * 250)

rocket.DispatchSpawn() // not strictly necessary for this example, but recommended
</source>

{{Todo|[[info_particle_system]] may not precache and play the particle effect using this method, needs to be confirmed.}}

=== Spawning multiple entities ===

If you need to spawn multiple entities at the same time to preserve parent hierarchy across multiple entities or for performance/efficiency reasons, there are two options.

==== point_script_template ====

[[point_script_template]] is the most robust method of spawning multiple entities.  It preserves parent hierarchy and has a callback function for when entities are spawned.  It is also more performant than <code>SpawnEntityGroupFromTable</code>.  A notable use case for this entity aside from parenting is spawning multiple brush entities at the same time or spawning brush entities alongside other entities, as the <code>PostSpawn</code> callback will allow you to set mins/maxs values easily after spawning.

<source lang=js>
local template = Entities.CreateByClassname("point_script_template")
template.DispatchSpawn()

template.ValidateScriptScope()
local template_scope = template.GetScriptScope()
// Required for the PostSpawn callback function to work
template_scope.__EntityMakerResult <- {}

// PostSpawn fires on the ForceSpawn input and will output a table of all spawned entities.
template_scope.PostSpawn <- function(entities)
{
    __DumpScope(0, entities)
}

template.AddTemplate("prop_dynamic",
{
    targetname = "heavy_model",
    model = "models/player/heavy.mdl",
    origin = Vector(247, -281, -123)
})

template.AddTemplate("prop_dynamic",
{
    targetname = "spy_model",
    parentname = "heavy_model",
    model = "models/player/spy.mdl",
    origin = Vector(247, -281, -123)
})

template.AcceptInput("ForceSpawn", "", null, null)
</source>

{{Note|By default, all targetnames must be unique for <code>OnPostSpawn</code> to work, as they are stored as keys in the <code>__EntityMakerResult</code> table, See [[Team_Fortress_2/Scripting/Script_Functions#CPointScriptTemplate|this page]] for a workaround.}}

==== SpawnEntityGroupFromTable ====

This function will also allow you to spawn multiple entities at once with proper parenting, however it does not have a convenient callback method for targeting the entities that have been spawned.

<source lang=js>
//spawn origins are right outside of mvm_bigrock spawn
SpawnEntityGroupFromTable({
    [0] = {
        func_rotating =
        {
            message = "hl1/ambience/labdrone2.wav",
            volume = 8,
            targetname = "crystal_spin",
            spawnflags = 65,
            solidbsp = 0, // mins/maxs values are not required for non-solid func_rotating
            rendermode = 10,
            rendercolor = "255 255 255",
            renderamt = 255,
            maxspeed = 48,
            fanfriction = 20,
            origin = Vector(278.900513, -2033.692993, 516.067200),
        }
    },
    [1] = {
        tf_glow =
        {
            targetname = "crystalglow",
            parentname = "crystal",
            target = "crystal",
            Mode = 2,
            origin = Vector(278.900513, -2033.692993, 516.067200),
            GlowColor = "0 78 255 255"
        }
    },
    [2] = {
        prop_dynamic =
        {
            targetname = "crystal",
            solid = 6,
            renderfx = 15,
            rendercolor = "255 255 255",
            renderamt = 255,
            physdamagescale = 1.0,
            parentname = "crystal_spin",
            modelscale = 1.3,
            model = "models/props_moonbase/moon_gravel_crystal_blue.mdl",
            MinAnimTime = 5,
            MaxAnimTime = 10,
            fadescale = 1.0,
            fademindist = -1.0,
            origin = Vector(278.900513, -2033.692993, 516.067200),
            angles = QAngle(45, 0, 0)
        }
    },
})
</source>

{{Note|If you intend to use this function to spawn brush entities that require a mins/maxs value to be set, a workaround is documented on the [[Team_Fortress_2/Scripting/Script_Functions#Globals|Script Functions]] page}}

== Spawning a Trigger ==
Triggers can be spawned like other entities, but they require more setup. This involves using <code>SetSize</code> to define the cuboid as 2 corners (relative to trigger's origin), then <code>SetSolid</code> to tell the engine to use the bounds as the collision. No other shape is possible. <code>mins</code> and <code>maxs</code> keyvalues are discarded in <code>SpawnEntityFromTable</code>, which is why <code>SetSize</code> is necessary afterwards.
=== AABB (non-rotated box) ===
Example of spawning a [[trigger_push]] that isn't rotated.
<source lang=js>
local trigger = SpawnEntityFromTable("trigger_push", 
{
    origin     = Vector(128, 500, 0)
    pushdir    = QAngle(0, 90, 0)
    speed      = 500
    spawnflags = 1 // allow players only
})
trigger.SetSize(Vector(-32, -32, 0), Vector(32, 32, 64))
trigger.SetSolid(2) // SOLID_BBOX
</source>
=== OBB (rotated box) ===
Example of spawning a [[trigger_push]] that is rotated. It is more expensive to calculate rotated triggers, so only use these if you really need to.
{{bug|hidetested=1|The origin of the trigger must be centered on its size, or collisions will be truncated for one side of the trigger}}

<source lang=js>
local trigger = SpawnEntityFromTable("trigger_push", 
{
    origin     = Vector(128, 500, 0)
    angles     = QAngle(0, 45, 0)
    pushdir    = QAngle(0, 90, 0)
    speed      = 500
    spawnflags = 1 // allow players only
})
trigger.SetSize(Vector(-16, -16, 0), Vector(32, 32, 64))
trigger.SetSolid(3) // SOLID_OBB
</source>
=== Visualizing triggers ===
This utility function allows you to see what a trigger looks like.
<source lang=js>
function DebugDrawTrigger(trigger, r, g, b, alpha, duration)
{
	local origin = trigger.GetOrigin()
	local mins = NetProps.GetPropVector(trigger, "m_Collision.m_vecMins")
	local maxs = NetProps.GetPropVector(trigger, "m_Collision.m_vecMaxs")
	if (trigger.GetSolid() == 2)
		DebugDrawBox(origin, mins, maxs, r, g, b, alpha, duration)
	else if (trigger.GetSolid() == 3)
		DebugDrawBoxAngles(origin, mins, maxs, trigger.GetAbsAngles(), Vector(r, g, b), alpha, duration)	
}
</source>

=== Map brush ===
It is also possible to spawn a brush entity that re-uses an existing [[bmodel]] in the map. Every brush entity has a special model name in the format <code>*N</code>, where N is a continuous number starting from 1 (1 is [[worldspawn]]).
There is no easy way to tell what these brushes look like, other than simply incrementing the number and inspecting it.
{{bug*|The game will crash if you specify a number beyond what the map has. Use <code>cl_precacheinfo modelprecache</code> to see the maximum number possible.}}
<source lang=js>
local brush = SpawnEntityFromTable("func_brush", 
{
    model      = "*4"
    origin     = Vector(128, 500, 0)
})
</source>
{{Note|Brushes that use special tool textures at compile-time (e.g. [[func_occluder]]) will not work using this method.}}

== Advanced Entity I/O Manipulation ==
The <code>EntityOutputs</code> class has a variety of useful functions for modifying entity I/O.  Notably, <code>GetNumElements</code> and <code>GetOutputTable</code> can be used to collect all of the entity's I/O in code for easier manipulation.

Example: Strip all outputs from a given entity.
<source lang=js>
function RemoveOutputAll(ent, output) 
{
    // store ent outputs in an array to operate on
    local outputs = []

    // iterate over all entity outputs
    // TODO: iirc there is a legitimate reason for iterating backwards but I don't remember why
    for (local i = EntityOutputs.GetNumElements(ent, output); i >= 0; i--) 
    {
        // store each output in a table
        local t = {}
        EntityOutputs.GetOutputTable(ent, output, t, i)
        
        // array of output tables
        outputs.append(t)
    }

    // iterate over all collected outputs and remove them.
    foreach (o in outputs) 
        foreach(_ in o) 
            EntityOutputs.RemoveOutput(ent, output, o.target, o.input, o.parameter)

    printf("Removed all '%s' outputs from %s\n", output, ent.tostring())
}

// Remove all OnStartTouchAll outputs from every trigger_multiple on the map
for (local trigger; trigger = Entities.FindByClassname(trigger, "trigger_multiple");)
    RemoveOutputAll(trigger, "OnStartTouchAll")
</source>

{{Note|see [[Team_Fortress_2/Scripting/Script_Functions#CScriptEntityOutputs|This note]] about <code>RemoveOutput</code>}}

== Spawning a Particle ==
There is various methods to spawn particles, and picking the right one depends on the use case.

=== DispatchParticleEffect ===
This is the simplest method. It spawns a particle at a given location and rotation. It is not possible to stop the particle nor parent it to any entity.
Useful for one-off effects such as explosions.

Do not use it for looping particle as they will persist forever.
<source lang=js>
DispatchParticleEffect("asplode_hoodoo", Vector(123, 400, 0), QAngle(0, 45, 0).Forward())
</source>

{{note|If using custom particles embedded in the map, they must be precached or they will show up as errors on dedicated servers. This can be done by running this function atleast once for a custom particle:
<source lang=js>
function PrecacheParticle(name)
{
    PrecacheEntityFromTable({ classname = "info_particle_system", effect_name = name })
}</source>}}

=== SpawnEntityFromTable ===
This spawns a [[info_particle_system]] entity. It can move and rotate arbitrarily, be parented to entities and stopped/started at any time.

The downsides are that it consumes an [[edict]] and adds networking overhead, and it does not use the parent's hitbox data for positioning (therefore particles such as player burning do not show up right).
<source lang=js>
local particle = SpawnEntityFromTable("info_particle_system",
{
	origin       = Vector(100, 900, 0)
	angles       = QAngle(0, 0, 0)
	effect_name  = "superrare_beams1"
	start_active = true // set to false if you don't want particle to start initially
})

// parent it to a player's head
particle.AcceptInput("SetParent", "!activator", GetListenServerHost(), null)
particle.AcceptInput("SetParentAttachment", "head", null, null)
// remove particle entity after a delay
EntFireByHandle(particle, "Kill", "", 5.0, null, null)
</source>

{{warning|Always ensure you are deleting the particle entity at some point to avoid leaking. If you are parenting the particle to an entity, the particle entity will delete itself automatically with the parent.}}

=== trigger_particle ===
{{tf2|2}} only!
This utilizes a [[trigger_particle]] entity. It spawns a particle at a given entity's location, optionally made to follow the entity. If following the entity, it can use the hitbox data for positioning (useful for particles like unusual taunts to show up correctly). Unlike [[info_particle_system]], this does not use an entity per particle. It only requires 1 singular edict for the <code>trigger_particle</code> itself. See [[trigger_particle]] page for a list of attachment modes.

Disadvantages of this method are that the spawned particle requires another entity to be present, and the spawned particle cannot be controlled directly, therefore looping particles will not stop until the entity is deleted. However particles can be stopped by firing the <code>DispatchEffect</code> input on the entity with <code>ParticleEffectStop</code> as the parameter. Note that this will stop all particles on the entity. Alternatively, spawn another entity like a [[prop_dynamic]] and bonemerge it to the entity, and attach particles to this instead. Killing the entity will stop the particles.

<source lang=js>
ParticleSpawner <- Entities.CreateByClassname("trigger_particle")
ParticleSpawner.KeyValueFromInt("spawnflags", 64)

function SpawnParticle(entity, name, attach_name, attach_type)
{
	NetProps.SetPropString(ParticleSpawner, "m_iszParticleName", name)
	NetProps.SetPropString(ParticleSpawner, "m_iszAttachmentName", attach_name)
	NetProps.SetPropInt(ParticleSpawner, "m_nAttachType", attach_type)
	ParticleSpawner.AcceptInput("StartTouch", "", entity, entity)
} 
</source>

<source lang=js>
// example usage:
local player = GetListenServerHost()
local particle_name = player.GetTeam() == 2 ? "spy_start_disguise_red" : "spy_start_disguise_blue"
SpawnParticle(player, particle_name, "", 1) // PATTACH_ABSORIGIN_FOLLOW
</source>

=== $keyvalues ===
If custom models are an option, particles can be [[Particles_on_models|embedded into the model]] instead via the [[$keyvalues]] block.
This approach is near identical to the [[trigger_particle]] one, except it does not require any code and is done automatically when the model is set.

== Creating a timer ==
This example covers two methods of creating code that runs after a delay, or on a repeated timer (such as every 0.5).

=== EntFire(ByHandle) ===
<code>EntFire</code> or <code>EntFireByHandle</code> can be used to create simple delays or timers. It runs a given input on an entity name or handle after a delay. By using CallScriptFunction, a EntFire can be chained to repeatedly run itself. The [[worldspawn]] entity always exists so its an easy one to target. Note that a delay of 0 will run at the end of the game tick.

<source lang=js>
function MyTimerFunction()
{
    printl("EntFire executed")

    // runs again in 0.5 seconds
	EntFire("worldspawn", "CallScriptFunction", "MyTimerFunction", 0.5)
}

// runs the timer after a second
EntFire("worldspawn", "CallScriptFunction", "MyTimerFunction", 1.0)
</source>

=== Think function === 
Another option is to use a think function using <code>AddThinkToEnt</code>. The game will execute this function depending on the delay returned from the function.
A limitation is that there can only be one think function per entity.

<source lang=js>
function MyThinkFunction()
{
    printl("Think executed")

    // runs again in 0.5 seconds
	return 0.5
}

local thinker = Entities.CreateByClassname("logic_relay")
AddThinkToEnt(thinker, "MyThinkFunction")
</source>

==== Conditional Think function ====
If you want a timer to be conditionally skipped depending on an input value, you can set the think to run every tick and use the <code>Time()</code> function to get the current server time, then use a cooldown value to decide when to run the think again if the condition fails.

<source lang=js>
local cooldown = 0.0
local random_value = RandomInt(0, 10)

function MyThinkWithCooldown()
{
    // skip cooldown if random_value is => 5
    if (random_value < 5 && cooldown > Time())
        return -1

    printf("Think executed, value is %d\n", random_value)

    // get a new random value
    random_value = RandomInt(0, 10)

    // random value is < 5, wait for 3 seconds
    cooldown = Time() + 3.0

    // actual think runs every tick
	return -1
}

local thinker = Entities.CreateByClassname("logic_relay")
AddThinkToEnt(thinker, "MyThinkWithCooldown")
</source>

== Listening for Events ==
In the game, many actions trigger events to notify other parts of the code. For instance, when a player dies or when an objective is captured, an event is fired. Each event can carry specific data, such as the index of an involved entity.

VScript allows you to capture these events, process the data, and execute code in response (this is called a 'callback'). You can find a list of game events on the [[Team_Fortress_2/Scripting/Game_Events|game events page]].

{{Expand|title={{tf2|2}}|
The code below demonstrates how to listen for the <code>post_inventory_application</code> event and apply uber protection for 2 seconds to the player that triggered this event. code>post_inventory_application</code is triggered when a player receives a new set of loadout items, such as when they touch a resupply locker/respawn cabinet, respawn or spawn in.

<source lang=js>
// This handles all the dirty work, just copy paste it into your code
function CollectEventsInScope(events)
{
	local events_id = UniqueString()
	getroottable()[events_id] <- events
	local events_table = getroottable()[events_id]
	foreach (name, callback in events) events_table[name] = callback.bindenv(this)
	local cleanup_user_func, cleanup_event = "OnGameEvent_scorestats_accumulated_update"
    if (cleanup_event in events) cleanup_user_func = events[cleanup_event].bindenv(this)
	events_table[cleanup_event] <- function(params)
	{
		if (cleanup_user_func) cleanup_user_func(params)
		delete getroottable()[events_id]
	} __CollectGameEventCallbacks(events_table)
}

CollectEventsInScope
({
	OnGameEvent_post_inventory_application = function(params) 
	{
		local player = GetPlayerFromUserID(params.userid)

		// add uber protection to the player for 2 seconds.
		player.AddCondEx(Constants.ETFCond.TF_COND_INVULNERABLE_USER_BUFF, 2.0, null)
	}
})
</source>
{{note|If you are collecting events with a preserved entity like [[info_target]] or in a persisting scope, do not delete the events table (in <code>scorestats_accumulated_update</code>). Otherwise, the event callbacks won't function after the 1st round.}}
{{deprecated|The old approach using <code>ClearGameEventCallbacks</code> for cleaning up events is now obsolete. '''Do not use it''', as it often caused conflicts with other scripts. The updated method shown above stores event callback functions in a table, which can be deleted to safely clean up the events without causing issues. 
Backwards compatibility: If you have plugin-like scripts (independent of the map), and have a problem with outdated maps using <code>ClearGameEventCallbacks</code> wiping your events, replace the <code>ClearGameEventCallbacks</code> function with this implementation:
{{ExpandBox|<source lang=js>
// Override ClearGameEventCallbacks to wipe events from the root table or from entities only
// This way, backwards compatibility is preserved with maps using this deprecated function
// Events that are namespaced and not tied to the entity (e.g. for script plugins) are preserved
function ClearGameEventCallbacks()
{
    local root = getroottable()
    foreach (callbacks in [GameEventCallbacks, ScriptEventCallbacks, ScriptHookCallbacks])
    {
        foreach (event_name, scopes in callbacks)
        {
            for (local i = scopes.len() - 1; i >= 0; i--)
            {
                local scope = scopes[i]
                if (scope == null || scope == root || "__vrefs" in scope)
                    scopes.remove(i)
            }
        }
    }
}
</source>}}
}}
}}
{{Expand|title={{css|2}}|
The code below demonstrates how to listen for the <code>round_start</code> event and <code>player_spawn</code> event. It prints the player's name and team when they spawn.
Note that the boilerplate code here is slightly different to the {{tf2}} one, as CS:S doesn't have a convenient cleanup event.

<source lang=js>
// This handles all the dirty work, just copy paste it into your code
function CollectEventsInScope(events)
{
	local events_id = UniqueString()
	getroottable()[events_id] <- events
	local events_table = getroottable()[events_id]
	local Instance = self
	foreach (name, callback in events) 
	{
		local callback_binded = callback.bindenv(this) 
		events_table[name] = @(params) Instance.IsValid() ? callback_binded(params) : delete getroottable()[events_id]
	}
	__CollectGameEventCallbacks(events_table)	
}

CollectEventsInScope
({
	OnGameEvent_round_start = function(params) 
	{ 
		printf("\tRound start\n")
	}
	OnGameEvent_player_spawn = function(params) 
	{
		local player = GetPlayerFromUserID(params.userid)
		printf("\tplayer_spawn '%s' on team '%d'\n", NetProps.GetPropString(player, "m_szNetname"), player.GetTeam())
	}
})
</source>}}
{{Expand|title={{dods|2}}|
The code below demonstrates how to listen for the <code>round_start</code> event and <code>player_spawn</code> event. It prints the player's name and team when they spawn.
Note that the boilerplate code here is slightly different to the {{tf2}} one, as DOD:S doesn't have a convenient cleanup event.

<source lang=js>
// This handles all the dirty work, just copy paste it into your code
function CollectEventsInScope(events)
{
	local events_id = UniqueString()
	getroottable()[events_id] <- events
	local events_table = getroottable()[events_id]
	local Instance = self
	foreach (name, callback in events) 
	{
		local callback_binded = callback.bindenv(this) 
		events_table[name] = @(params) Instance.IsValid() ? callback_binded(params) : delete getroottable()[events_id]
	}
	__CollectGameEventCallbacks(events_table)	
}

CollectEventsInScope
({
	OnGameEvent_dod_round_start = function(params) 
	{ 
		printf("\tRound start\n")
	}
	OnGameEvent_player_spawn = function(params) 
	{
		local player = GetPlayerFromUserID(params.userid)
		printf("\tplayer_spawn '%s' on team '%d'\n", NetProps.GetPropString(player, "m_szNetname"), player.GetTeam())
	}
})
</source>}}

{{tip|To see what events fire during the game, download [https://raw.githubusercontent.com/ficool2/vscript_tf/refs/heads/main/scripts/vscripts/showevents.nut this script] (right click and ''Save Page''), place it into your <code>tf/scripts/vscripts/</code> folder and run <code>script_execute showevents</code> in console.}}

{{warning|If you are porting game event code from {{tf2}} to another game or vice versa, make sure to update the <code>CollectEventsInScope</code> function with the matching one! It is slightly different and not doing this will cause unexpected issues such as events stacking up each round.}}

==Toggling HUD Elements==
Some HUD elements can be hidden away for players by using the appropriate <code>HudHideFlags</code> functions.
The available flags can be found on the [[Team Fortress 2/Scripting/Script Functions/Constants#FHideHUD|Constants]] page.
Since these are bit flags, elements to hide or show can be combined using the OR <code>|</code> operator.

Example usage:
<source lang=js>
player.AddHudHideFlags(
	Constants.FHideHUD.HIDEHUD_CROSSHAIR |
	Constants.FHideHUD.HIDEHUD_HEALTH |
	Constants.FHideHUD.HIDEHUD_WEAPONSELECTION
) // hides hud elements

player.RemoveHudHideFlags(player,
	Constants.FHideHUD.HIDEHUD_CROSSHAIR |
	Constants.FHideHUD.HIDEHUD_HEALTH |
	Constants.FHideHUD.HIDEHUD_WEAPONSELECTION
) // makes hud elements visible again

</source>
Line 2 would add bits to hide the crosshair, health, and disabling weapon switching from the player.
Line 3 would remove bits to show the crosshair, health, and re-enable weapon switching for the player.

== Fetching player name or Steam ID ==
Steam IDs are stored in SteamID3 format, e.g. <code>[U:1:53275741]</code>

<source lang=js>
::GetPlayerName <- function(player)
{
    return NetProps.GetPropString(player, "m_szNetname")
}

::GetPlayerSteamID <- function(player)
{
    return NetProps.GetPropString(player, "m_szNetworkIDString")
}
</source>

{{warning|The SteamID3 is not available until the player joins a team or says something in chat. If you need to retrieve the steam ID early, send the <code>player_activate</code> event in the <code>player_spawn</code> event when the 'team' parameter is 0. This will make the SteamID3 immediately available afterwards.
<source lang=js>
function OnGameEvent_player_spawn(params)
{
    local player = GetPlayerFromUserID(params.userid)
    if (player.GetTeam() == 0)
        SendGlobalGameEvent("player_activate", {userid = params.userid})
}
</source>}}

== Fetching and setting entity color ==

<source lang=js>
::SetEntityColor <- function(entity, r, g, b, a)
{
    local color = (r) | (g << 8) | (b << 16) | (a << 24)
    NetProps.SetPropInt(entity, "m_clrRender", color)
}

::GetEntityColor <- function(entity)
{
    local color = NetProps.GetPropInt(entity, "m_clrRender")
    return {
        r = color & 0xFF,
        g = (color >> 8) & 0xFF,
        b = (color >> 16) & 0xFF,
        a = (color >> 24) & 0xFF,
    }
}
</source>

== Think functions / reading player input ==
A think function is a function on an entity that runs repeatedly on a timer. How it works:
* Define a function with no parameters
* Specify the think function name using the <code>Script Think Function</code> or add it to the entity using <code>AddThinkToEnt</code>
* The return value of the function specifies the delay before running it again. By default, this is 0.1 seconds. The fastest possible delay is per-tick by returning -1. {{tf2}} runs at 66 ticks per second, so this is effectively a 0.015 interval. In {{css}}, servers may run at different tickrates so don't assume it's 66 by default.

The example below when executed will show a message when the player presses reload.
{{note|Always use a per-tick think function for reading input.}}

<source lang=js>
function PlayerThink()
{
	local buttons = NetProps.GetPropInt(self, "m_nButtons")
	if (buttons & Constants.FButtons.IN_RELOAD)
	{
		printl("Player is reloading")
	}
	
	return -1
}

local player = GetListenServerHost()
AddThinkToEnt(player, "PlayerThink")
</source>

{{note|Think functions must be in global scope or in the entity's scope for it to work. The example above would not work in a <code>logic_script</code> because the <code>PlayerThink</code> function would not exist outside of the assigned entity. To fix this, either
* Make <code>PlayerThink</code> global, e.g. rewrite as <code>::PlayerThink <- function()</code>
or
* Add <code>PlayerThink</code> to the entity's scope, e.g. <code>player.GetScriptScope().PlayerThink <- PlayerThink</code>
}}

It may be useful to only detect when a key is ''pressed'' (or released) rather than when it's being helded. This can be achieved by storing the last button state and comparing it against the new one.
The example below prints a message when the player left-clicks.

<source lang=js>
function PlayerThink()
{
	local buttons = NetProps.GetPropInt(self, "m_nButtons")
	local buttons_changed = buttons_last ^ buttons
	local buttons_pressed = buttons_changed & buttons
	local buttons_released = buttons_changed & (~buttons)
	
	if (buttons_pressed & Constants.FButtons.IN_ATTACK)
	{
		printl("Player pressed left-click")
	}
	
	buttons_last = buttons
	return -1
}

local player = GetListenServerHost()
player.ValidateScriptScope()
player.GetScriptScope().buttons_last <- 0
AddThinkToEnt(player, "PlayerThink")
</source>

=== Multiple thinks on a single entity ===

Entities can only have one think function applied to them at any given time, attempting to call `AddThinkToEnt` when one is already running will cause the original think to be replaced entirely.  As a workaround, you can assign a table to the entities scope and have the think function iterate over this table to call them, this will let you to dynamically add and remove functions as needed.  Use an array instead of a table if execution order is important.

The downside to this approach is that all thinks will run at the same interval, see the conditional timer example for making individual functions in the table execute at different times.

Another downside is the performance counter will not print a function name for anything inserted dynamically, as function names and their associated scope are read in the preprocessor step.  Always declare functions inside the table with the example syntax.  <code>funcname = function()</code> will not print the name either.  Otherwise, you will only see <code><lambda or free run script></code>

<source lang=js>
local player = GetListenServerHost()
player.ValidateScriptScope()
local player_scope = player.GetScriptScope()
player_scope.ThinkTable <- {
    function FirstThink()
    {
        printl("Think1")
    }
    function SecondThink()
    {
        printl("Think2")
    }
}
player_scope.PlayerThinks <- function() {
    foreach(name, func in player_scope)
        func.call(player_scope)
    return -1 // every function will run every tick
}
AddThinkToEnt(player, "PlayerThinks")
</source>

== Printing colored text from Hammer I/O ==

When attempting to print colored text in {{hammer}} using entity I/O, the escape characters used will not be saved correctly.  While {{hammerplusplus}} does support escape characters for newlines, the <code>\x07</code> sequence for colored text will crash the editor when loading the map.  To work around this, you can make a utility function to replace a random character with <code>\x07</code> at run-time.
{{Note|Does not support alpha, you will need to modify this function to replace the character with <code>\x08</code> instead of <code>\x07</code>.}}

<source lang=js>
//print colored text within hammer
::ClientPrintSafe <- function(player, text)
{
    //replace ^ with \x07 at run-time
    local escape = "^"

    //just use the normal print function if there's no escape character
    if (!startswith(text, escape)) 
    {
        ClientPrint(player, 3, text)
        return
    }
    
    //split text at the escape character
    local splittext = split(text, escape, true)
    
    //format into new string
    local formatted = ""
    foreach (i, t in splittext)
        formatted += format("\x07%s", t)
    
    //print formatted string
    ClientPrint(player, 3, formatted)
}
</source>

Example usage:
<source lang=js>
ClientPrintSafe(null, "^FF0000This text is red.^00FF00 This text is green")
</source>

== Getting the userid from a player handle ==
{{note|For games other than {{tf2}}, replace <code>[[tf_player_manager]]</code> with the manager classname for your game. E.g. [[cs_player_manager]] in {{css}} or [[dod_player_manager]] in {{dods}}.}}

<source lang=js>
::PlayerManager <- Entities.FindByClassname(null, "tf_player_manager")
::GetPlayerUserID <- function(player)
{
    return NetProps.GetPropIntArray(PlayerManager, "m_iUserID", player.entindex())
}
</source>

Alternatively, store off the userid from the <code>player_spawn</code> game event.

== Checking if point or box is inside a trigger / tracing triggers ==
This abuses a quirk where triggers can be set solid temporarily so traces "hit" them, and reverted afterwards.
The example below demonstrates this to detect if a point is inside a given trigger.

Example usage: <code>printl(IsPointInRespawnRoom(GetListenServerHost().EyePosition(), Entities.FindByName(null, "mycooltrigger")))</code>

<source lang=js>
function IsPointInTrigger(point, trigger)
{
	trigger.RemoveSolidFlags(4)  // FSOLID_NOT_SOLID
	local trace =
	{
		start = point
		end   = point
		mask  = 1
	}
	TraceLineEx(trace)
	trigger.AddSolidFlags(4)

	return trace.hit && trace.enthit == trigger
}
</source>

{{note|In {{tf2}}, tracing against [[func_respawnroom]]s also requires changing the trigger collision group to 0 before tracing, then reverting it to 25 afterwards.}}

== Finding changed netprops ==
It may be useful to see what netprops have changed after an event occurs on an entity. The following example shows the changed sendprops (networked changes) and datamaps (server-specific changes) after the local player is killed.

<source lang=js>
function DumpChangedProps(ent)
{
	local prev_sendprops = {}
	local prev_datamaps = {}
	local cur_sendprops = {}
	local cur_datamaps = {}
	
	NetProps.GetTable(ent, 0, prev_sendprops)
	NetProps.GetTable(ent, 1, prev_datamaps)
	
	ent.TakeDamage(999.9, 32, null)
	
	NetProps.GetTable(ent, 0, cur_sendprops)
	NetProps.GetTable(ent, 1, cur_datamaps)

	local recursive_compare
	recursive_compare = function(prev_table, cur_table, indent="")
	{
		foreach (k, v in cur_table)
		{
			local prev_v = prev_table[k]
			
			if (typeof(v) == "table")
			{
				printl(indent + "TABLE: " + k)
				recursive_compare(prev_table[k], v, indent + "\t")
			}
			else 
			{
				if (typeof(v) == "Vector" || typeof(v) == "QAngle")
				{
					if (v.x != prev_v.x || v.y != prev_v.y || v.z != prev_v.z)
						printl(indent + k + " changed: " + prev_v + " -> " + v)
				}
				else 
				{
					if (prev_v != v)
						printl(indent + k + " changed: " + prev_v + " -> " + v)
				}
			}
		}
	}
	
	recursive_compare(prev_sendprops, cur_sendprops)
	recursive_compare(prev_datamaps, cur_datamaps)
}

DumpChangedProps(GetListenServerHost())
</source>

== Moving a player into spectating state without death ==
Avoids death effects such as kill feed or screams from appearing if killed by conventional means, and the player still remains on the team.
{{todo|Doesn't work right in {{css}}}}

<source lang=js>
function ForceSpectate(player)
{
	NetProps.SetPropInt(player, "m_iObserverLastMode", 5)
	local team = player.GetTeam()
	NetProps.SetPropInt(player, "m_iTeamNum", 1)
	player.DispatchSpawn()
	NetProps.SetPropInt(player, "m_iTeamNum", team)
}
</source>

== Getting the players active soundscape ==
If you would like to determine if a player is in a certain area of the map (notably if they are inside a building or not), and the maps soundscapes are configured correctly, you can check the players active soundscape to get a rough idea of where they are without needing to manually place [[trigger_multiple]]s or using other tedious detection methods.  

Every soundscape has a unique index that can be found by typing <code>soundscape_dumpclient</code> in console.  Setting the <code>developer</code> console command to 1 will print the string name of your active soundscape whenever one is played.

<source lang=js>
::InSoundscapeIndex <- function( player, index )
{
    // uncomment to print soundscape indexes to console, enable "developer 1" to match with the name of the soundscape
    // printf( "Soundscape Index: %d \n", NetProps.GetPropInt( player, "m_Local.m_audio.soundscapeIndex" ) ) 
	return NetProps.GetPropInt( player, "m_Local.m_audio.soundscapeIndex" ) == index
}

// prints true for soundscape index 34 on a listen server (Sawmill.Outside in TF2)
for ( local soundscape; soundscape = Entities.FindByClassname( soundscape, "env_soundscape*" ); )
{
	EntityOutputs.AddOutput( soundscape, "OnPlay", "!self", "RunScriptCode", "printl( InSoundscapeIndex( GetListenServerHost(), 34 ) )", 0, -1 )
}
</source>

== Error telemetry ==
It may be difficult to debug script errors when testing on multiplayer servers. The following code when executed sets up error telemetry, where all script errors are sent to a specific player by their matching SteamID3.
Each script error will be printed to chat in red text, with full error information printed to console.

<source lang=js>
::TelemetrySteamID3 <- "[U:1:53275741]"

seterrorhandler(function(e)
{
	for (local player; player = Entities.FindByClassname(player, "player");)
	{
		if (NetProps.GetPropString(player, "m_szNetworkIDString") == TelemetrySteamID3)
		{
			local Chat = @(m) (printl(m), ClientPrint(player, 2, m))
			ClientPrint(player, 3, format("\x07FF0000AN ERROR HAS OCCURRED [%s].\nCheck console for details", e))
			
			Chat(format("\n====== TIMESTAMP: %g ======\nAN ERROR HAS OCCURRED [%s]", Time(), e))
			Chat("CALLSTACK")
			local s, l = 2
			while (s = getstackinfos(l++))
				Chat(format("*FUNCTION [%s()] %s line [%d]", s.func, s.src, s.line))
			Chat("LOCALS")
			if (s = getstackinfos(2))
			{
				foreach (n, v in s.locals) 
				{
					local t = type(v)
					t ==    "null" ? Chat(format("[%s] NULL"  , n))    :
					t == "integer" ? Chat(format("[%s] %d"    , n, v)) :
					t ==   "float" ? Chat(format("[%s] %.14g" , n, v)) :
					t ==  "string" ? Chat(format("[%s] \"%s\"", n, v)) :
									 Chat(format("[%s] %s %s" , n, t, v.tostring()))
				}
			}
			return
		}
	}
})
</source>