# ezQuake Manual: Scripting

Every game from Quake series has strong client-side scripting system. In modern QuakeWorld clients this has come even more far. In this client you can use (user) commands, (user) variables and macros in your scripts.

Note: Advanced users may wish to skip to Advanced scripting section of this manual.

## Basic scripting

### What is a script

Script is a piece of text your client understands. It means you can type that text into the console and after hitting `[Enter]` something happens. Example:
`/name superman`
That piece of text will change your nickname to superman and other players can see you as superman in the scoreboard, etc.

What have we used here:

- Forward slash - `/`
  This character tells your client that following text should be executed. Probably if you try to type only `name superman` in the console then the same thing will happen. That's because usualy (depends on your client settings) the client will first try to recognize if given text is a script. If this check is positive it will execute it and if the result is negative it will send that piece of text as a message to other players automatically.
- Variable - `name`
  Name is a variable. It contains your current nickname used in the game.
- string - `superman`
  That's the value we want to be saved into variable `name`.

Since it's pretty boring to type long scripts containing many lines of stuff manually into console everytime, we are able to store it in a file which can be loaded on our request. QuakeWorld scripts are usualy stored in files with extension `.cfg` (which is not necessary) somewhere in your Quake directory. For a start it's good idea to place your configs into ID1 subdirectory, so it can be e.g.:
`C:\Quake\ID1\myscript.cfg`
Such file is usually called "config" (abbrevation of "configuration file") or simply "script".

In your client you can execute your script with command
`/exec myscript.cfg`

It is common that there are two types of ".cfg" files used in QuakeWorld:

Configs
  Series of all variables assignments and key bindings. In those files players usually store their game configuration. You can save and load configs with commands `cfg_save` and `cfg_load` but this manual page is about something different:
Script
  List of some commands you want to be done instantly - e.g. change some keys bindings, change some of the graphic settings, create new advanced user commands.

This manual page will describe things you can use in your scripts.

### Commands

Among simple commands like `/quit` (which will shut down your client) there are commands with parameters. E.g.
`/demo_capture start 0:10 my.avi` will tell your client to start capturing new video file named "my.avi" and it will be 10 seconds long.

Note that there are special types of commands with characters `+` and `-` as a first character. If you bind command with `+` to a key then the command will be executed when the key is pressed and same command but with `-` will be executed when the key is released.

You can create your own commands using command
`alias new_command "command_definition"`
Where `command_definition` is usually a string enclosed in quotes and it's a sequence of commands, user created commands and variables assignments separated by semicolons (`;`). E.g.:
`alias redteam "team red; color 4 4; ready"`

### Variables

Variables contain game settings. E.g. `name` contains your nickname, `volume` contains sound volume, etc.
By typing
`/<variable_name>` in the console the client will show you what is current value of that variable. E.g.`/name` will tell you what is your current nickname.
By typing
`/<variable_name> <new_value>` you will change the value of given variable. E.g. `/volume 0` will mute all game sounds.

## Common scripts

### Weapon scripts

If you want to make your life as a QW player easier, you can start by using a weapon script. What a weapon script does is that it selects the wanted weapon, and if it doesn't exist, it chooses the best weapon available. When you've fired the weapon it switches to the Shotgun or the Axe (cannot be dropped in backpack) to ensure that the enemy does not get a valuable weapon if he manages to kill you.

Example: this command will first try to select rocket launcher, then super-nailgun, then super-shotgun and if you don't have even this weapon it will choose shotgun.
`/impulse "7 5 3 2"`

You can write all sorts of scripts, the only thing holding you back is your own imagination!

### Boomstick/Axe script

What about not giving away the powerful Rocket Launcher? When you get fragged by another player he will get the weapon which you had selected last. If you are clever you would manually change to a weaker weapon before he kills you but you can make a script which does that for you in the heat of the battle.

    alias +rl "impulse 7;+attack"
    alias -rl "-attack;impulse 1"
    bind mouse1 "+rl"

### Teamplay messages scripts

Nowadays macros (see below) are used to create intelligent communication messages with your team. This manual will explain you all scripting possibilities but won't tell you how should such config look. There's a teamplay messages config distributed along with ezQuake, you can find this and other configs in the confing dir in the CVS repository. Look for other popular teamplay-messages configs e.g. in forums.

## Advanced scripting

### User-created variables

You can create your own variables with command
`/set <variable_name> <value>`
and destroy them using
`/unset <variable_name>`
You can of course check what the variable value is by typing it's name
`/<variable_name>`
You can use the value of any variable using `$<variable_name>`, e.g.:
`/mp3_volume $volume` sets the sound volume of mp3 player to same level as the game volume, equals to
`/set mp3_volume $volume`

### Mathematical operations

This client allows you to use some basic mathematical operations on your variables using `set_calc` command: `set_calc <cvar> <command> <command arguments>
set_calc <cvar> <argument1> <operator> <argument2>`
valid commands: `strlen int substr set_substr pos`
valid operators: `+ - * / div %% and or xor`.
This feature was ported from QW262 QuakeWorld client.
For simple increasing and decreasing variables you can use command `/inc variable value`.

### User-created commands with parameters

Example:
`alias cool_zoom "fov %1;sensitivity %2;v_viewheight %3;crosshaircolor %5"; cool_zoom 30 3.2 -6 79`
ported by from QW262.

E.g.: zooming script:
`alias zoom "set_calc fov $fov * %1; set_calc sensitivity $sensitivity * %1"
bind "capslock" "zoom 0.5"`

### Macros

Macro is a special type of string that is replaced in your custom command with value given by state of the client or the game. It is very similar to accessing variable value by `$` character but you cannot change values of macros.

Example:
`/exec my_$matchstatus.cfg`
Will exec my_standby.cfg script when the server is in prewar mode or my_normal.cfg if you play a game.

Here is full list of macros available in the last build of the client when writing this manual page:
$ammo, $armor, $armortype, $bestammo, $bestweapon, $cells, $connectiontype, $date, $deathloc, $demoplayback, $droploc, $droptime, $health, $latency, $ledpoint, $ledstatus, $location, $matchname, $matchstatus, $matchtype, $mp3info, $nails, $need, $point, $pointatloc, $pointloc, $powerups, $qt, $rockets, $shells, $tf_skin, $time, $took, $tookatloc, $tookloc, $triggermatch, $weapon, $weaponnum, $weapons

Note that usage of many macros is very limited to prevent making the scripting possibilies not so powerful in gameplay. In Smackdown Ruleset you are able to use macros only in combination with "if", "say" and "say_team" commands.

### Conditions

You can use `if` construct in your scripts with following syntax:
`if <expr1> <operator> <expr2> <command1> [else <command2>]`
where expr1 and expr2 is a string where you usually use your own text, macros, and values of variables (see above, e.g. $volume). As an operator you can use one of the following: `==, =, !=, <>, >, <, >=, <=, isin, !isin` where `==` and `=` means "equals", `!=` and `<>` means "doesn't equal", `<, >, <=, >=` means "less than", "greater than", "less or equal", "greater of equal" and finally
`isin` means "expr1 is a substring of expr2" and `!isin` is a negation of this.
The [else ...] part is optional and if used command2 will be executed only when the main condition is false.

### Regexp matching

We support multiple params & regexp match for 'viewalias, unalias_re, toggle_re, cvar_reset_re'
Regexp match support for 'aliaslist, cvarlist, cmdlist, macrolist'.
Examples:

    unalias_re alias1 alias2 ^\.took(.+)$
    cvar_reset_re gl_part_.+
    toggle_re gl_part_.+
    cvarlist gl_

Last update: 31.12.1969 16:00 PST, made by JohnNy_cz