A script is a group of commands that allow you to achieve a task. Scripts can be used to:
- Improve control flexibility (e.g., multiple weapon binds)
- Execute multiple functions with one keystroke (e.g., demo recording)
- Facilitate config customization for multiple purposes (e.g., customizing keyboard commands for playing, vs. custom commands for demo playback)
Scripts are just plain text files that are saved with the
.cfg file extension in your q3ut4 folder.
You can execute scripts in three ways:
- "On-demand" by opening Console in the game and typing the exec command. For example:
/exec zoom.cfgwould run a script named
- Automatically at game launch by adding them to a special file named
- By writing a script that executes another script.
See Executables for more information.
There are many ways to organize how you script Urban Terror.
cfg files need to be located within your game path. This location varies by operating system.
By default, Urban Terror comes with three scripts.
q3config.cfg- This is your game settings file and generally should not be edited directly.
autoexec_example.cfg- Rename this to
autoexec.cfgand it will be executed every time the game launches. Settings saved in
autoexec.cfgwill be written to
q3config.cfgfor you, so rather than editing
q3config, edit this file instead. This can also be used to automatically execute other scripts (see Executables section).
server_example.cfg- Example server config. This helps with setting up a new game server, but we won't cover Running a server here.
Scripts should be saved in a separate
For example, you may have an untouched
autoexec.cfg with all of your customized settings and key binds, and then other
.cfg files for all other functions like a custom zoom script in
zoom.cfg and a gear selector in
gear.cfg. This is just one way to organize them. Use what's comfortable for you, but don't save your settings or scripts by editing
For a really impressive example, take a look at Config: Nexu's.
Before getting started, it is recommended that you use a text editor with syntax highlighting. This will help you, especially as a beginner, to understand the script and to fix errors in your code. For example, if you forget to put in a quotation mark to close off a value, a syntax highlighter will make the rest of your code all sorts of unexpected colors, tipping you off that something is wrong in the script. You don't want to waste time trying to figure out why your script doesn't work over a simple error like that!
You can use any plain text editor you like, but for a list of recommended editors, see Editors for Scripts.
As you write scripts, use
//comments to help annotate what your script does. It will help you remember what your scripts do and why you set them up the way you did. Comments are essential if you ever plan to share your scripts with other people—we need to know what it does without reading through every line of code!
Urban Terror will ignore anything that follows a pair of double-slashes (
//), EXCEPT for a semicolon (
;). See note below on Semicolons in comments.
Example of (
Semicolons in commentsEdit
Be careful about semicolons (
;) in comments as they will effectively end the comment, just like a new line would.
Hello world! Hello again, world!
…even though the second command came after a
Binding a key to perform a single action is the easiest place to start. We'll start by binding the 'x' key to select the shotgun/SPAS12. The syntax is:
Since we want to bind X to the SPAS12, we will substitute '
<key> and '
weapon 4' for
<value>. This will give us:
See List of Bindable Keys to see all possible keys you can bind.
We can also bind a key to execute multiple commands. Remember that Urban Terror executes commands in the order you've specified so we have to be careful. For example, we are going to bind a key to select the best choice between the SPAS12 (weapon 4) and the G36 (weapon 9). The syntax is:
You have to separate the commands with a semicolon (
;) so that Urban Terror recognizes where each command starts and stops. We're going to use the '
x' key again for <key>,
weapon 4 for <command 1>, and
weapon 9 for <command 2>.
This should give us:
When you hit X, the bind selects the first weapon (weapon 4) then immediately selects the second weapon (weapon 9). In effect, if you have both weapons in your inventory, it selects the last one in the sequence, the G36.
If you only have one of the weapons, it will only find and activate that weapon. This is why we want to make sure we write
weapon 4 first since given the choice between the two, we always want to end up with the G36.
You can string a whole bunch of commands together to be executed all at once. For example, this bind will remove all the clutter from your screen (e.g., icons, guns, etc), take a screenshot, and then return your HUD to the way it was.
Note that when using multiple commands, it is sometimes necessary to use the
wait command to pause the script a moment. If your script fails to work when issuing multiple command at once, try adding a
Wait will pause the script for a number of frames, not seconds. If you cap your FPS at 60, you can somewhat reliably
wait for 60 frames to equal one second, but as frame rates vary, so will actual
Instead of only selecting the best weapon, what if we want to toggle back and forth between two weapons like the UMP45 and the M4 or make it possible to zoom to 3x or 6x magnification? This requires a recursive script. By recursive, it means that you can cycle through the script an infinite number of times. The intent is to execute one string of commands when you hit the bound key, then re-bind the key to execute new string of commands the next time you use the key.
The process is as follows
Write commands for each 'step' in the scriptEdit
set- tells Urban Terror that you are defining a line of commands that will be grouped and executed under the name
<step name>- is the name of one iteration or step in your script. If you have a large number of steps, start numbering with
<step name>01. If you have 4 steps, then the highest number should be
<step name>04. For scripts with a small number of steps, you can use simple names if you like (instead of numbers), just make sure that you don't use the same name twice.
<commands>- is the command or set of commands you want to execute with the script. Multiple commands should be separated by a semicolon (
;) like we learned in the Multiple Binds section.
set- this tells the script to assign to
<function name>the string of commands defined in
vstr- is the name of the next variable in the sequence to be activated. In other words,
<step name>01, which then set
<step name>02. In your last step, make
<function>activate the first step all over again,
<step name>01.This will let your key cycle through all of the combinations you've written, then start all over from the beginning. You don't have to use a numerical sequence, but it might make it easier to keep track of. In any case, pick whatever you're comfortable with.
<ut_echo>- Any text that follows the
ut_echocommand (until a quote mark or semicolon) will be shown to you as an in-game message. Useful for reminding you of what your script just did!
Here's an example for a 3x - 6x zoom toggle:
Set up the functionEdit
This will access the two "steps,"
zoomtoggle02, that we have created in the previous example.
To start, we have set the function to run the first step. When that step runs, it sets the function to run the second step instead.
Bind a key to execute the functionEdit
The last step is to bind a key to execute your new script. We learned the syntax in the first section, Simple Binds. The final line in the zoom toggle looks like:
All this does is bind the key to execute the string of commands associated with
Here's what it looks like when it's all put together:
3x - 6x Zoom Toggle
Try this out and play around a little. You'll be writing your own scripts in no time.
Any command that can be set to either "on" or "off", can be switched with a toggle. For example, you can set Always Run to either on (
1) or off (
0), therefore you can create a toggle that lets you switch Always Run between on or off.
The syntax is:
Here are a couple of examples:
Look through your configuration for variables that take either a 0 or 1 value. Those are the "boolean" commands that can be set up on a toggle.
exec command can help you to keep your
autoxec.cfg clean and organized. Basically, you can create a new
.cfg file, write your script there, and then add an
exec command to
autoexec.cfg that will run your script. Having scripts in separate files allows you to share them with teammates and just generally keep things clean.
If your configuration is too large, the Quake III engine that Urban Terror runs on will have problems executing the whole thing. Separate configs set up as executables enable you to reduce the overall size of your primary autoexec. The syntax is:
Here are a couple of examples that could be used in an
You can also have config files/scripts in a separate folder. For example, if you put them in a folder called "cfg" then you would use
Here are just a few example of scripts that can be used in your in your config. You can find more examples in the Urban Terror Wiki Script & CFG Library.
Toggle Sprint, Run, Walk Bind
Toggle Crouch Bind
Why does my script not work?Edit
There are two possible errors. One of them happens when your script is too big. All scripts should stay under 16KB in size, to solve this problem break the script or scripts into smaller files which you can then execute by adding the following lines to your autoexec.cfg (where FileName is the name of your files):
If you have a lot of such sub scripts we advise you create a folder in which to store them, to keep your game directory fairly tidy. This can be done by creating a new folder with the name of your choice (we will name it "cfg" in our exemple) in your q3ut4 folder. Now place all your sub scripts into this folder, the
autoexec.cfg should NOT be placed in this folder. Now add the following lines to your
Another possible error is triggered when you have too many cvar strings active (i.e too many scripts). This error is usually accompanied by an error message similar to "overflow." The only way to solve this issue is to start hacking away at what you really don't need in your scripts.
Recent updates to the game (version 4.2) should limit these errors. While limitations still exist, the allowances have been greatly expanded and you are not likely to run into these problems.
seta, because there's an upper limit on the size of a
q3config.cfg that can be read in. Just use
set commands in your
autoexec.cfg and, to keep it tidy, exec configs for specific stuff from within
|Scripts & Configs|