Advanced Console Scripting

This guide will explain the more advanced concepts of the console in DarkPlaces.
For information on more basic console use click here.
Note: In the examples, you will often see a trailing ”]”. This is the console prompt, where you type commands. Output isn't prefixed by such a bracket.

Aliases are fundamental in script creation. They are the key to simplification, and often the principal part of a script.

Aliases are “shortcuts” to commands. For example, if I am too lazy to type “chmap silvercity” every time I want to play on silvercity locally, all I have to do is set up an alias that way:

alias sc "chmap silvercity"

The quotes are not needed, but it is always better to use them, as multi-command aliases need them:

alias hi say hello; say how are you?
alias hi "say hello; say how are you?"

The first alias is a shortcut to “say hello”. When the alias is saved, you will say “how are you?”.
The second alias assigns “hi” to both commands. They are executed one after the other when I enter the new “hi” command.

There are a few special variables accessible only from inside an alias. There are 80 of them, that should be enough for anything.
These are $1 $2 $3 ... $79 which expand to the nth parameter, and $* which contains all the parameters.
You can also use, for example, $3- to expand to all the arguments after the 3rd, included.
For example:

]alias args "echo Hello, here are all your parameters: $*; echo And here is the first: $1; echo And all the parameters from the 4th: $4-"
]args One "Two hey don't typefrag" Three Four "Forty Two"
Hello, here are all your parameters: One Two hey don't typefrag Three Four Forty Two 
And here is the first: One 
And all the parameters from the 4th: Four Forty Two

As you can see, text contained in quotes is considered as one argument.

See Variable expansion below for more details on the use of variables.

First of all, what does “variable” mean? It is any cvar ¹⁾ plus the alias parameters.
Variable expansion lets you use content from variables in other commands. Here is an example session:

]set foo "Hello World!"
]echo $foo
Hello World!

As you can see, you just need a $ in front of the variable's name to get expansion. If you want to escape $²⁾, just use $$ (not \$).

]echo I'm going to show you how to expand a cvar.
I'm going to show you how to expand a cvar.
]echo Just type this to expand timelimit: $timelimit
Just type this to expand timelimit: 20
]echo Woops, I meant $$timelimit of course!
Woops, I meant $timelimit of course!

Sometimes you may want to use the longer syntax: ${variable} if your variable name contains spaces (this won't happen often) or if you need to do “double expansion”, that is interpret the content of a variable as another variable's name, and expand this again. Example:

]set levelOne "levelTwo"
]set levelTwo $message
]echo $levelOne
levelTwo
]echo $$levelOne
$levelOne
]echo ${$levelOne}
Thank you xsax! But our Xolar is in another castle!

The parser escapes the quotes and backslashes present in variables before expanding them, to avoid messups in aliases. Though this can sometimes be annoying. It can fortunately be bypassed using the ${var asis} syntax. Example:

]set bar "this is a fancy backslash: \ "
]echo $bar
this is a fancy backslash: \\ 
]echo ${bar asis}
this is a fancy backslash: \

Another example showing why this escaping makes aliases safer:

]alias foo "echo First parameter: ${1 asis}   Second parameter: ${2 asis}"
]alias bar "foo \"${1 asis}\" \"${2 asis}\""
]bar "One One" "Two Two"
First parameter: One One Second parameter: Two Two 
]bar "One \"One" "Two Two"
First parameter: One Second parameter: One"

Can anyone find a better/simpler example?

As you can see, the second time I called “bar” with an “infected” string, the alias messed up. It would have been safe without using “asis”.

There is a little issue concerning variable expansion in aliases that can fortunately be worked around. It happens when you try to set a new value to a cvar and then want to expand it.
Here is an example of the issue:

]set x OLD
]alias foo "set x NEW; echo $x"
]foo
OLD
]foo
NEW

As seen here, $x is expanded before the alias is executed. The only way to delay this expansion is to split the alias:

]set x OLD
]alias foo "set x NEW; foo2"
]alias foo2 "echo $x"
]foo
NEW

Since Nexuiz 2.4.2, the menu code can process RPN math. What's that RPN thing?
RPN stands for “Reverse Polish notation”. You can read more about this on Wikipedia: Reverse Polish notation

Thanks to this, you can do math in your scripts. I will only show the simplest of this.
The command to use the RPN calculator is “menu_cmd rpn” on nexuiz clients, “sv_cmd rpn” on servers (if you want to create scripts for your dedicated server)
Here is an example of its use:

]menu_cmd rpn 3 7 +
rpn: still on stack: 10
]
]set phi "1.6180339887"
]menu_cmd rpn phi phi * phi -
rpn: still on stack: 1.000000
]
]menu_cmd rpn 42 6 9 * eq
rpn: still on stack: 0

For a complete list of rpn commands, try menu_cmd help .

There, I calculated 3+7, phi²-phi, and checked if 6*9 = 42 (and it didn't... aww). For the last one, the answer is the FALSE boolean, 0. 1 is TRUE.
This won't do your math homework but it can be useful in scripts. The use I showed before isn't practical for these, as you can't store the answer in a cvar. Though, it is possible using a slightly more complicated syntax:

]set answer "Nah."
]menu_cmd rpn /answer 6 7 * def
]echo $answer
42

You can use this to increment variables for example:

]menu_cmd rpn /answer answer 1 + def
]echo $answer
43

Now this is one of the best things in scripting: there is a toolkit! It was inspired by assembler, and coded by Blub. It takes advantage of the RPN calculator to provide useful aliases like for loops, conditional expressions, and so on.
You can read more about it, and see an example of its use (though it is quite complicated) on the Alientrap forum

The only way to do that is to write it in a cfg file. See CFG for more info.

This method is used for the “if” command in blubscript.

]alias compare "menu_cmd rpn /result 42 $1 eq def; compare2"
]alias compare2 "answer_$result"
]alias answer_0 "echo You fail"
]alias answer_1 "echo You win"
]compare 13
You fail 
]compare 42
You win 
]compare blahblahblah
You fail

This is the example shown in the console

]alias kolorz echo ^$i $i
]for i 0 10 kolorz
.
. List of color codes
.

It simply increments i from 0 to 9 (not 10), and outputs ^i i, that is, the color code (^ + color number), a space, and the color number.
It works without the space too.

I'm not using the blubscript builtin loops as it blocks input and doesn't wait between iterations. Instead, I'll be using the defer command to use a large interval between calls. This will make me drop my weapon every minute.

alias start "set continue 1; defer 60 _weploop"
alias stop "set continue 0"
alias _weploop "test continue; jnz \"dropweapon; defer 60 _weploop\""

“start” starts the process, setting “continue” to 1; and starting the loop after 60 seconds (if I didn't use “defer 60 _weploop” in “start”, it would throw the weapon immediatly when I called “start”).
“stop” stops the process.
The _weploop alias checks if the “continue” cvar is 1 or 0. If it is 0, it doesn't call itself anymore and the loop stops. If it is 1, it drops the weapon, and calls himself again after another 60 seconds.