Scripting
Scripting is the use of configuration files (.cfg) to create new keybinds and aliases automating complex behaviors and console command sequences. Unlike hacking, scripting is built into Team Fortress 2 and is not banned by VAC (Valve Anti Cheat). Uses of scripting vary from simply binding a key to a command to self-referential loops and nested aliases that redefine one another. Any functionality that can be created with scripting can also be accomplished without, however scripting will allow these functionalities to be used even in fast-paced battle.
Contents
Dedicated Scripting Files
Team Fortress 2 automatically reads several game files and executes any scripts within them. Here is the list of those files:
- config.cfg - This is the default configuration file which is edited to reflect any in-game changes to keybinds or video settings. It is safe to edit this file, but it will change to reflect any modified keybinds on startup. This config will run every time the game starts up, before any other config.
- config_default.cfg - This contains a basic set of keybinds, and will be executed as a backup if config.cfg is not present.
- autoexec.cfg - This is the default config file for executing custom keybinds and aliases. This config will run every time the game starts up, after config.cfg.
- scout.cfg, soldier.cfg, pyro.cfg, etc. - Each class has a config file which automatically runs whenever a player switches to that class. Note that any settings set in one classes config file will be retained when switching classes unless explicitly rebound.
Editing Scripting Files
If on Windows, scripting files may be found in:
<Steam Folder>/SteamApps/common/team fortress 2/tf/cfg
If on a Mac, scripting files may be found in:
~/Library/Application Support/Steam/SteamApps/common/team fortress 2/tf/cfg
If on Linux, scripting files may be found in:
~/.local/share/Steam/SteamApps/common/Team\ Fortress\ 2/tf/cfg
Since the SteamPipe update, code can also be placed in
.../team fortress 2/tf/custom/yourfoldernamehere/cfg
Scripting Commands
The following is a list of commands which have no use apart from scripting; they do not influence gameplay directly.
Bind
The simplest command is the bind command. It will cause a certain key to execute a certain action, whether that action is a setting, a command, or a script.
bind [KEY] [COMMAND]
Quotes can be optionally placed around the key or the command.
bind [KEY] "[COMMAND 1]; [COMMAND 2]; [COMMAND 3]"
Quotes can be optionally placed around the key, but must be present around the commands.
Binds come in two forms:
bind "e" "Voicemenu 0 0"
This bind will make the player call for a Medic when they press E.
bind "w" "+forward"
This bind will make the player move forward while they have W held down.
Toggle
This command allows a setting to be toggled between two or more values.
toggle "sv_cheats 0 1"
Bindtoggle
This works identically to toggle, but binds it to a key.
bindtoggle o "sv_cheats 0 1"
Incrementvar
This allows for variables to be increased or decreased repeatedly by a set amount.
bind MWHEELUP "incrementvar fov_desired 75 90 1"
bind MWHEELDOWN "incrementvar fov_desired 75 90 -1"
This will cause the field of view to increase when scrolling up, and to decrease when scrolling down.
Note: Incrementvar will cause the value to wrap around if it gets too large or too small. In this example, once the field of view hits 90, it will drop down to 75, and vice-versa.
Alias
An alias allows multiple commands to be referenced by a single command. This is effectively shorthand, and it is most useful when a series of commands need to be called multiple times.
Note: Alias names cannot contain spaces. They may contain underscores, numbers, and symbols. Alias names are case-sensitive.
alias Call_For_Medic "Voicemenu 0 0"
bind "e" "Call_For_Medic"
This script functions the same with a simple bind, meaning that when the player presses E, they will call for a Medic.
alias "+Diagonal" "+moveleft; +back"
alias "-Diagonal" "-moveleft; -back"
bind "z" "+Diagonal"
This script allows the player to move diagonally. Here, pressing Z will cause the player to move diagonally backward and left.
Warning: The following code will not work!
bind "z" "+moveleft; +back"
Although pressing Z will cause the player to move backward and left, the game engine does not invert the +back command, and releasing Z will not cause the player to stop backing up.
Exec
This command will execute another file. This means that complex scripts can be stored in other files, so as not to clutter up more general files.
exec autoexec.cfg
This script will execute the player's autoexec script.
Echo
This command will cause text to be printed to the console. This is very useful for debugging.
echo Scripting is; echo very useful
This will print out Scripting is
and very useful
on two separate lines. This is because a newline is added to the end of any text passed to echo
. Spaces are only parsed if they are between words, or if the echoed text is between quotes, as in the next example:
echo " Scripting is very useful. "
The extra spaces will be printed out, since the sentence is denoted by quotation marks.
Note: It is not possible to print out the " character, as its meaning will be misinterpreted. However, you can print single quotes: that is, the ' character.
Note: Echo occasionally will misprint strings that are not delimited by quotation marks. As a general rule of thumb, it is better to enclose what you wish to print within quotation marks. It also makes it easier to read for humans.
Wait
This command will make the game wait a given number of frames before executing the next command.
Note: The amount of real time this corresponds to depends on the server's tickrate.
Warning: Wait commands are disabled on certain servers. This will cause certain scripts to fail, and may (in semi-rare cases) cause the game to crash. See Wait Testing for help to protect against this.
echo Why did the chicken cross the road?; wait 66; echo To get to the other side!
This script will wait 66 frames (1 second on most servers) before printing the punchline.
List of key names
Hover over a key to see its scripting name.
ESC
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
`
1
2
3
4
5
6
7
8
9
0
-
=
Delete
Tab ⇆
Q
W
E
R
T
Y
U
I
O
P
[
]
\
⇪ Caps
A
S
D
F
G
H
J
K
L
;
'
↵
⇧ Shift
Z
X
C
V
B
N
M
,
.
/
⇧ Shift
Ctrl
⊞
Alt
Spacebar
⊞
≣ Menu
Ctrl
PrtScn
ScrLk
Pause
Insert
Home
PgUp
Delete
End
PgDn
↑
←
↓
→
Num
/
*
-
7
8
9
+
4
5
6
1
2
3
↵
0
.
Mouse Button
Name of Keybind
Scroll Up
MWHEELUP
Scroll Down
MWHEELDOWN
Left Click
MOUSE1
Right Click
MOUSE2
Wheel Click
MOUSE3
Left Button Click (forward)
MOUSE4
Right Button Click (back)
MOUSE5
Useful commands
Disguising
The disguise
command takes two arguments, the first being the class and the second being the team.
- Class
- 1. Scout
- 2. Sniper
- 3. Soldier
- 4. Demoman
- 5. Medic
- 6. Heavy
- 7. Pyro
- 8. Spy
- 9. Engineer
- Team
- 1. BLU team
- 2. RED team
- -1. Opposite team
- -2. Same team
Thus, disguise 5 1
would disguise as a BLU Medic and disguise 7 -2
would disguise as a friendly Pyro.
Note: disguise 8 -2
(Friendly Spy) will cause the player to un-disguise.
Buildings
The build
and destroy
commands each take two arguments, the first being the building and the second being the building type. The second argument is only required if it is not 0
, and is currently only used to differentiate between teleporter entrances and exits.
The build
command will pull up the blueprint to place a building, with an exception of the Sapper, which is wielded.
build 0 0
will build a Dispenser (Engineer only)
build 1 0
will build a teleporter entrance (Engineer only)
build 1 1
will build a teleporter exit (Engineer only)
build 2 0
will build a Sentry Gun (Engineer only)
build 3 0
will build a Sapper (Spy only)
Similarly, the destroy
command will destroy buildings.
destroy 0 0
will destroy a Dispenser (Engineer only)
destroy 1 0
will destroy a teleporter entrance (Engineer only)
destroy 1 1
will destroy a teleporter exit (Engineer only)
destroy 2 0
will destroy a Sentry Gun (Engineer only)
Note: Sappers cannot be destroyed.
It is possible to use the old build
commands, which used only one argument.
build 0
will build a Dispenser (Engineer only)
build 1
will build a teleporter entrance (Engineer only)
build 2
will build a Sentry Gun (Engineer only)
build 3
will build a teleporter exit (Engineer only)
build 3
will build a Sapper (Spy only) [deprecated]
Voice Menu
The voicemenu
command takes two arguments, the menu number and the command number.
- 0 (
voice_menu_1
)- 0: MEDIC!
- 1: Thanks!
- 2: Go! Go! Go!
- 3: Move Up!
- 4: Go Left
- 5: Go Right
- 6: Yes
- 7: No
- 1 (
voice_menu_2
)- 0: Incoming
- 1: Spy!
- 2: Sentry Ahead!
- 3: Teleporter Here
- 4: Dispenser Here
- 5: Sentry Here
- 6: Activate Charge!
- 7: MEDIC: ÜberCharge Ready
- 2 (
voice_menu_3
)- 0: Help!
- 1: Battle Cry
- 2: Cheers
- 3: Jeers
- 4: Positive
- 5: Negative
- 6: Nice Shot
- 7: Good Job
Note: These numbers are one less than as they appear in-game.
Assorted
clear
will clear the console of any information.alias
will list all currently defined aliases.fov_desired (75-90)
will set the field of view.viewmodel_fov
will set the FOV for weapon models. It ranges by default from 54 to 70.r_drawviewmodel (0/1)
will show (1) or hide (0) weapon models.lastdisguise
will cause the player to re-disguise as their last disguise. (Spy only)load_itempreset [0, 1, 2, 3]
will load a particular loadout preset [A, B, C, D].say "message"
will send a message to public chat.say_team "message"
will send a message to team chat.+taunt
will cause the player to taunt.+use_action_slot_item
will cause the player to use their action slot item.volume (0-1)
will change the in-game volume.
Advanced Scripting Techniques
Toggles
It is possible to bind a key to toggle a command which would otherwise be a press and hold command.
bind w toggle
alias toggle "enable"
alias enable "alias toggle disable; +forward"
alias disable "alias toggle enable; -forward"
This script will cause a press of W to keep the player moving forward until W is pressed again.
Key combinations
It is possible to create a script where pressing one button while another is held down will change the action of the first button.
bind e call
alias call Call_For_Medic
alias Call_For_Medic "Voicemenu 0 0"
alias Call_For_Ubercharge "Voicemenu 1 6"
At this point, the script will mean that every time E is pressed, the player will call for a Medic. It also has an unused alias to call for an Ubercharge.
bind shift +toggleState
alias +toggleState "alias call Call_For_Ubercharge"
alias -toggleState "alias call Call_For_Medic
Now, pressing ⇧ Shift will redirect call
to ask for an ubercharge. Releasing ⇧ Shift will make call
point back at a Medic call.
When ⇧ Shift+E is pressed, the player will call for an Ubercharge, rather than for a Medic.
Wait-testing
Since the wait
command is integral to some scripts, it may be necessary to test to see if a server has disabled the command.
alias waitTester "alias waitTest waitPositive; wait; waitTest"
alias wait "alias waitTest waitNegative"
alias waitPositive "echo Wait is enabled on this server.; exec waitPositive.cfg"
alias waitNegative "echo Wait is DISABLED on this server!; exec waitNegative.cfg"
waitTester
This script relies on the fact that if the wait command is disabled on a server, the alias named wait
can be defined by the user. Thus, the script creates an alias named waitTest
which by default points to waitPositive
, but if wait
is not allowed (and can thus be defined by the user), will be redirected to waitNegative
.
Loops
Warning: Loops which run without a wait command will cause the TF2 client to hang. It is highly suggested to run a looping script only after a wait testing script.
It is generally considered bad form to have one alias point to itself, as although the loop can be broken out of, it cannot be reset. Therefore, looping scripts tend to include two parts to the loop: The part that waits, and the part that loops.
bind g "loopKey"
alias loopKey startLoop
alias startLoop "alias loopKey stopLoop; +attack; alias redirect loop; loop"
alias stopLoop "-attack; alias redirect; alias loopKey startLoop"
alias loop "+left; wait 33; -left; +right; wait 33; -right; redirect"
alias redirect loop
This script will start looping once G is pressed. It begins by firing, and then switches the player's view back and forth every 33 frames (half of a second on most servers). Pressing G would cause the next iteration of the loop to stop, also stopping the firing.
Commenting
As scripts get longer, the need for well-named aliases grows. However, it is not always sufficient to explain what an alias does simply by its name. Adding a pair of forward slashes (//) will turn the rest of the line into a comment–it will not execute any actions on the text.
voicemenu 1 6 //Activate Charge!
Since it is not obviously clear what the voice command is, a comment can explain it.
Noteworthy scripts
There are several notable scripts that have affected gameplay. Some of these are patched out, while others remain functional.
Patched scripts
Pistol scripts
Originally, the Pistol could be fired almost as fast as the human hand could press a key. Scripts were created to simulate this rapid pressing by holding down a single key.
August 13, 2009 Patch: The Pistol now fires at a fixed rate, not based on the speed of pressing the fire button.
Chargin' Targe turn scripts
Originally, the keyboard commands to turn left and right were not treated the same as the mouse commands. The Chargin' Targe was the first weapon to create a restriction on how quickly a player could turn, therefore Valve put a limit on mouse turn-speed, yet forgot to apply the same restriction to the keyboard command that resulted in the same action. Scripts were created to rebind the turning controls when a player charged, circumventing this restriction.
June 23, 2011 Patch: Fixed an exploit with the Chargin' Targe that allowed greater turning control than intended.
Air crouching scripts
Originally, players could crouch as many times as they liked in a single jump. By binding a script to crouch and uncrouch as rapidly as possible, the engine could be exploited to make it difficult to properly register shots on jumping targets.
March 6, 2009 Patch: Players can now only duck twice in the air.
Gloves of Running Urgently Scripts
The Gloves of Running Urgently used to drain 6 health per second while active. However, jumping preserved the speed bonus granted by this weapon and did not require the weapon to be active. Simple scripting allowed for the player to quickly switch to the gloves, jump, and then switch away.
June 27, 2012 Patch: Replaced the damage over time of the Gloves of Running Urgently with a time-delayed mini-crit de-buff.
Idling Scripts
Most servers seek to prevent players idling for drops. Players can try to outsmart these systems with scripts that simulate basic movement.
An Active Solution to an Idle Threat requires players to accept a pop-up notification in order to continue to get drops.
Current Scripts
Weapon Viewmodel Hiding Scripts
There are a large number of scripts which toggle the weapon viewmodel depending on which weapon slot is selected for a class. Players often make their viewmodels invisible to clear up the screen, but make items like melee weapons, PDAs, watches, and so forth visible because these models indicate important information. For example, the Spy relies heavily on his viewmodel to determine when he is cloaked, when his Cloak is disturbed, and when the Dead Ringer activates. Other classes use the melee animations to judge when their attacks will hit.
Sentry Jumping Scripts
Since the Engineer Update, Engineers have been able to pack up and carry their Sentry Guns. Simultaneously introduced in the update, the Wrangler allows Engineers to Sentry jump with their Sentry rockets. With extremely fast inputs, it was discovered that a player could Sentry jump and successfully pack up their Sentry before they were launched away.
While a human can repeat this feat, it is difficult. Some players made scripts which could reliably execute the commands in the right order at the right speed allowing them to make a Sentry jump while carrying their Sentry every time.
Note: The Rescue Ranger can circumvent this necessity, as it can pick up buildings at range for 130 metal.
Gunslinger Scripts
Since it can be troublesome to destroy then rebuild a Combat Mini-Sentry in the heat of battle through the PDA, some players have scripted the destruction and rebuilding of their Combat Mini-Sentry with the click of one or two mouse buttons. Such a script is especially useful when using the Frontier Justice, as the player gains practically instant access to revenge crits when needed.
Sensitivity and Control scripts
Some players prefer different mouse sensitivities and control schemes for some classes. For example, changing from the Medic, which doesn't require fine aiming, to the Sniper, which encourages high precision headshots, a player may wish to change their mouse sensitivity. These scripts alter control schemes and mouse settings on a per class, or even per weapon, basis.
Charge Dash Scripts
Since timing a charge and jump can be difficult, some players may use a quick script that binds the two actions to a button so that the charge dash will cover the maximum amount of distance possible. The player is still required to swing their melee weapon normally to end the charge though.
Quickscope Scripts
Many players find it difficult to scope in and fire straight after to get a quick headshot. There are scripts that will zoom in and fire just by clicking one mouse button. This does require players to aim outside of the scope, though.
Rocket Jump Scripts
In order to Rocket Jump to a maximum height or distance, it is required that the player jumps, crouches, and fires their rocket at roughly the same time. This can be easily scripted to occur with the press of a button.
Kill-bind Scripts
In certain circumstances is it beneficial for a class to be able to kill themselves. Although mostly only relevant in competitive play, there are occasional uses in public servers.