Scripting Basics

A script is a group of commands that allow you to achieve a task. Scripts can be used to:

1. Improve control flexibility (e.g., multiple weapon binds)
2. Execute multiple functions with one keystroke (e.g., demo recording)
3. 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:

1. "On-demand" by opening Console in the game and typing the exec command. For example: /exec zoom.cfg would run a script named zoom.cfg
2. Automatically at game launch by adding them to a special file named autoexec.cfg.
3. By writing a script that executes another script.

See Executables for more information.

Script Organization

There are many ways to organize how you script Urban Terror.

Your cfg files need to be located within your game path. This location varies by operating system.

Script Files

By default, Urban Terror comes with three scripts.

1. q3config.cfg - This is your game settings file and generally should not be edited directly.
2. autoexec_example.cfg - Rename this to autoexec.cfg and it will be executed every time the game launches. Settings saved in autoexec.cfg will be written to q3config.cfg for you, so rather than editing q3config, edit this file instead. This can also be used to automatically execute other scripts (see Executables section).
3. 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 .cfg file from your q3config.cfg. The reason is that Urban Terror overwrites the q3config file every time you start a game or change settings and therefore will delete your scripts and comments. It is always better to make changes by adding them to autoexec.cfg or a separate .cfg file you will run manually later.

For example, you may have an untouched q3config.cfg, an 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 q3config.cfg!

For a really impressive example, take a look at Config: Nexu's.

Script editors

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.

Commenting

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 (//) double-slahses //Function Keys bind F1 "ui_selectteam" //Displays Team Select Interface bind F2 "ui_selectgear" //Displays Weapon & Gear Interface bind F3 "ui_radio" //Displays radio menu bind F3 "toggle cg_drawFPS" //Displays Frames per Second bind F4 "toggle cg_drawTimer" //Displays timer bind F5 "toggle cg_thirdperson" //Shows model in third person view bind F6 "toggle cg_drawhands" //Shows hands & weapon bind F11 "screenshot" //Takes screenshot

Semicolons in comments

Be careful about semicolons (;) in comments as they will effectively end the comment, just like a new line would.

For example

ut_echo "Hello world!" //Says "hello world," and; ut_echo "Hello again, world!"

…would output…

Hello world!
Hello again, world!

…even though the second command came after a // comment.

Basic Binds

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:

bind <key> "<value>"

Since we want to bind X to the SPAS12, we will substitute 'x' for <key> and 'weapon 4' for <value>. This will give us:

bind x "weapon 4" //Select SPAS12

See List of Bindable Keys to see all possible keys you can bind.

Multiple Binds

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:

bind <key> "<command 1>; <command 2>" //Comments go here

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:

bind x "weapon 4; weapon 9" //Select weapon Spas12, then G36

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.

bind F11 "cg_draw2d 0; cg_drawhands 0; wait 45; screenshot; toggle cg_draw2d; toggle cg_drawhands"

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 command. 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 wait time.

Recursive Scripts

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 script

set <step name>## "<commands>; set <function name> vstr <step name>##; ut_echo <status>"

• set - tells Urban Terror that you are defining a line of commands that will be grouped and executed under the name <step 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 <step name>.
• vstr - is the name of the next variable in the sequence to be activated. In other words, <function> activates <step name>01, which then set <function> to activate <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_echo command (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 zoomtoggle01 "cg_zoomfov 15; sensitivity 25; set nextzoomtoggle vstr zoomtoggle2; ut_echo 6x magnification" set zoomtoggle02 "cg_zoomfov 30; sensitivity 17; set nextzoomtoggle vstr zoomtoggle1; ut_echo 3x magnification"

Set up the function

This will access the two "steps," zoomtoggle01 and zoomtoggle02, that we have created in the previous example.

set nextzoomtoggle "vstr zoomtoggle01"

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 function

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:

bind x "vstr nextzoomtoggle"

All this does is bind the key to execute the string of commands associated with nextzoomtoggle.

Here's what it looks like when it's all put together:

3x - 6x Zoom Toggle // When x is pressed, zoom to 6x. When x is pressed again, zoom to 3x. //Steps set zoomtoggle01 "cg_zoomfov 15; sensitivity 25; set nextzoomtoggle vstr zoomtoggle2; ut_echo 6x magnification" set zoomtoggle02 "cg_zoomfov 30; sensitivity 17; set nextzoomtoggle vstr zoomtoggle1; ut_echo 3x magnification" //Function set nextzoomtoggle "vstr zoomtoggle01" //Key bind bind x "vstr nextzoomtoggle"

Try this out and play around a little. You'll be writing your own scripts in no time.

Toggle Settings

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:

bind [key] "toggle [setting name]"

Here are a couple of examples:

bind SHIFT "toggle cl_run" //Always run on/off bind F3 "toggle cg_drawFPS" //Displays Frames per Second bind F4 "toggle cg_drawTimer" //Displays timer bind F5 "toggle cg_thirdperson" //Shows model in third person view bind F6 "toggle cg_drawhands" //Shows hands & weapon

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.

Executables

Using the 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:

exec <filename>

Here are a couple of examples that could be used in an autoexec.cfg:

exec comm.cfg exec serverlist.cfg exec demo.cfg

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

exec cfg/comm.cfg

Examples

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 set mz_00 "set mz_f vstr mz_01; -button8; +speed; ut_echo SPEED: WALKING" set mz_01 "set mz_f vstr mz_02; -button8; -speed; ut_echo SPEED: RUNNING" set mz_02 "set mz_f vstr mz_00; +button8; -speed; ut_echo SPEED: SPRINTING" set mz_f "vstr mz_01" //sets run as default bind SHIFT "vstr mz_f" //bind for changing speed

Toggle Crouch Bind set sit "+movedown; set crouch vstr stand" set stand "-movedown; set crouch vstr sit" set crouch "vstr stand" //set default bind c "vstr crouch"

Why does my script not work?

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):

exec FileName_1.cfg exec FileName_2.cfg

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 autoexec.cfg:

exec cfg/FileName_1.cfg exec cfg/FileName_2.cfg

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.

set, seta, sets, and setu

set ID "some_value" //create a cvar named ID with value some_value, but doesn't save it in your q3config.cfg when used interactively seta ID "some_value" //create a cvar named ID with value some_value and flagged as 'archive' so it will write it to q3config.cfg sets SERVER_INFO_CVAR "some_value" //sets a predefined SERVER_INFO_CVAR (email, admin, os, etc.) to some_value to be displayed by server browsers setu USER_INFO_CVAR "some_value" //sets a predefined USER_INFO_CVAR to some_value

Don't use 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 autoexec.cfg.

This article is based on a document originally from urbanterror.info(view)