Team Fortress 2/Scripting/VScript Examples

This page contains examples of vscripts for Team Fortress 2.

Iterating through entities

With awhileloop and a Entities.FindByClassname() function, you can iterate through all entities of a matching classname, based on your arguments.

The first parameter of Entities.FindByClassname() is named 'previous' which accepts a script handle (of 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.

local ent = null
while( ent = Entities.FindByClassname(ent, "prop_physics") )
{
   printl(ent)
}

Spawning an entity

The following code shows to spawn an entity, specifically a rocket. The rocket will be spawned in front of the first available player.

// By ZooL_Smith

local ply = Entities.FindByClassname(null, "player")

local rocket = SpawnEntityFromTable("tf_projectile_rocket", 
{
    // This is a table of keyvalues, which is the same way as keyvalues that are defined in Hammer
    // Key         Value
    basevelocity = ply.GetForwardVector()*250,
    teamnumber   = ply.GetTeam(),
    origin       = ply.EyePosition()+ply.GetForwardVector()*32,
    angles       = ply.GetAngles()
})

rocket.SetOwner(ply) // make it not collide with owner and give proper kill credits

Swapping the !activator's team

Whenever a script's code gets executed by inputs (i.e. RunScriptCode/CallScriptFunction on an entity with an attached entity script), the activator and caller variables will be set to the handles of the input's !activator and !caller respectively, allowing you to access them in code.

We can use that to easily do something to players that walk in a specific trigger, for example.

As for swapping the !activator's team, we need to do both change their team based on which team they are, and then also change the their cosmetic items' team to the their's new team.

First we need to figure on which team the !activator is. For that, we can use the GetTeam() method on the !activator (activator.GetTeam()) to get the number index of their team. You can either use an if function to compare the returned value with the desired team index, or store it in a variable to use it later. The latter in this case may be better to reduce the length of the script. For reference: 0 is Unassigned (no team yet), 1 is Spectator, 2 is Red, 3 is Blu.

To change the !activator's team, we should use the ForceChangeTeam(Int : Team index, Bool : Kill player if game is in Highlander mode + remove their dominations) method on them via activator.ForceChangeTeam(...).

To change their cosmetic items' colour, we need to iterate over every tf_wearable entity, and then change its team via SetTeam(Int : Team index) if they are worn by the !activator.

• To iterate, we need to specify a null variable (e.g. local cosmetic = null), and then pass it into the following while loop:

local cosmetic = null // Assign the "cosmetic" variable to null, will be assigned new values when going over cosmetic items
while (cosmetic = [[List of TF2 Script Functions#CEntities|Entities]].FindByClassname(cosmetic, "tf_wearable"))
{
    // Do things to individual tf_wearables entities here, the "cosmetic" variable is set to the current tf_wearable entity we are iterating through
}

• To check if the cosmetic item belongs to the !activator, we can simply compare the value returned by the GetOwner() method when we use it on the tf_wearable (e.g. cosmetic.GetOwner()) against the !activator. Example code:

if (cosmetic.GetOwner() == activator)
{
    // Do things if the cosmetic's wearer is the !activator
}

• To change the cosmetic's team, we should use the SetTeam(Int : Team index) method on the cosmetic item entity.

Full code with comments:

function ActivatorSwapTeam() // Call this in map via RunScriptCode > ActivatorSwapTeam() or CallScriptFunction > ActivatorSwapTeam on a logic_script that has an Entity Script with this function
{
    // The following snippet checks if an !activator has been specified and if they are a player
    // If either question's answer is no, then don't execute the rest of the function
    if (activator == null || activator.IsPlayer() == false)
    {
        return
    }
    
    // The following snippet compares the !activator's team number (Ranging from 0 to 3) to the ones used by Unassigned (0) and Spectator (1)
    // If they match with either Unassigned or Spectator, we don't execute the rest of the function
    // Used to ignore any potentional spectator !activators
    if (activator.GetTeam() == 0 || activator.GetTeam() == 1)
    {
        return
    }
    
    // The following snippet specifies a local newTeam variable, and then we set it to a team number based off the !activator's current team number
    local newTeam = 0
    if (activator.GetTeam() == 2) // Checks if the !activator's team number is 2 (Red), and sets the newTeam variable to 3 (Blu)
    {   
        newTeam = 3
    } else { // If the !activator's team number is not 2 (Red), sets the newTeam variable to 2 (Blu) instead
        newTeam = 2
    }

    // The following snippet calls the ForceChangeTeam method on the !activator
    // First parameter: Team number to switch to
    // Second parameter: If false, the game will reset the player's dominations and nemesises, and kill them if mp_highlander is on
    activator.ForceChangeTeam(newTeam, true)
    
    // The following snippet will go over every cosmetic item currently present, and will change its colours to the appropriate team if they are the !activator's
    while (cosmetic = Entities.FindByClassname(cosmetic, "tf_wearable")) // Goes over every cosmetic item, executing code below
    {
        if (cosmetic.GetOwner() == activator) // Checks if the currently iterated cosmetic item's wearer is the !activator
        {
            cosmetic.SetTeam(newTeam) // Sets the team of the cosmetic item to the new team number that we stored in newTeam
        }
    }
}

Listening for events

Many actions in the game fire events to notify other parts of code that something has happened. For example, when a player dies or when an Engineer's building is sapped. Each event can also hold certain type of data, such as the index of an involved entity.

VScript can catch these events, parse the data and run some code when they happen. The list of available events can be found here: https://wiki.alliedmods.net/Team_Fortress_2_Events

Todo: Update to event listener callback when it's fixed, currently the logic_eventlistener workaround is used.

The following code shows how to listen for the player_hurt event, and then apply an attribute to the victim.

// run:
// script_execute hurt_event.nut

// Simple script that pushes players and apply an attribute when hurt
// From ZooL_Smith with love

local targetname = "event_player_hurt"
local listener = SpawnEntityFromTable("logic_eventlistener", 
{
	targetname = targetname,
	EventName = "player_hurt",
	IsEnabled = true,
	FetchEventData = true,
	OnEventFired = targetname+",RunScriptCode,player_hurt(),0,-1",
	// vscripts = "player_hurt.nut"
})

listener.ValidateScriptScope() // Generate a VScript scope
listener.GetScriptScope().player_hurt <- function() // Define a new function
{
	// "event_data" is the table that gets filled if "FetchEventData" is true
	// this table will be filled with the data from the event.
	// it is only available inside the entity's scope.
	
	local attacker = GetPlayerFromUserID(event_data.attacker)
	local victim = GetPlayerFromUserID(event_data.userid)
	
	local newvel = victim.GetVelocity()
	newvel.z = RandomFloat(10,10)*event_data.damageamount
	newvel.x += RandomFloat(-10,10)*event_data.damageamount
	newvel.y += RandomFloat(-10,10)*event_data.damageamount
	
	// attribute name, value, time
	victim.AddCustomAttribute("move speed penalty", 0.35, 1)
	victim.SetVelocity(newvel)
	
	local str = victim+" took "+event_data.damageamount+" damage"
	
	if(attacker)
		str += " from player "+attacker
	
	// 0 is server, other numbers are players
	Say(0, str, false)
}


// TESTING: Only have one, remove previous entity
if(::rawin("event_player_hurt"))
	EntFireByHandle(event_player_hurt, "Kill", "", 0, null, null)
::event_player_hurt <- listener

See also

• List of TF2 Script Functions