Table of Contents
Command Line Options 1
CubeScript 2
Useful variables 4
Console Commands 5
GUI Commands 8
Gameplay Commands 9
Server Configuration Commands 11
Editing 12
The HUD 14
Settings 14
Heightfield 14
Texture Blending 15
Defining Blended Textures 15
Blend Brushes 15
Adding a new Brush 15
Loading a Brush 15
Painting 16
Reverting Paints 16
Blending Hints and Tips 16
Entity 16
Entity Types 18
Lighting Commands 21
Map and Config 23
PVS Culling 29
Waypoints 30
Bots 31
Demo Recording 31
Movie Recording 32
Multiplayer Online 33
Network Code 33
Cheating 33
Command Line Options
-d This starts as a dedicated server. The default is a non-dedicated server with only a single client in graphical mode. Dedicated servers run in the shell only (no graphics), with increased priority yet use very little cpu time and memory, so you can run one in the background, or at the same time with a client if you want to host a game (which is usually better than using a listen server). Servers use the ports 28785 (UDP) and 28786 (UDP).
-dN If N=1, starts a listen server which allows it to simultaneously function as both a client and server. Note that a listen server is limited by your in-game frame rate, so you should use a dedicated server if your graphics card is slow or you have enabled frame rate limiting options such as "vsync". If N=2, it starts a dedicated server as for the "-d" command-line option.
-wN Sets the screen resolution width to N (default: 640).
-hN Sets the screen resolution height to N (default: 480).
-bN Sets the screen depth to N bits per pixel.
-zN Sets the z-buffer precision to N bits. This should be at least 24 or you may experience depth problems.
-aN Sets FSAA (Full Scene AntiAliasing) to N samples, i.e. -a4 is 4xFSAA -vN Sets v-sync to N (N=1 to enable or N=0 to disable). -sN Sets stencil buffer bits to N (N>=1 to enable or N=0 to disable).
-t Sets Sauerbaten to run windowed.
-f -fN When used alone, "-f" forces the renderpath to the old fixed function pipeline (no shaders), otherwise it sets the shader precision to N (lower = faster). 0 disables shaders, 1 uses the fastest/lowest precision the OpenGL driver offers (default), 2 uses the OpenGL driver's defaults, and 3 is the nicest/slowest precision. The effects of 1-3 will vary with different card/driver combos. However, 2 and 3 should be avoided unless you are experiencing trouble with the defaults, as they will only slow rendering down. 4 forces the engine to use the GLSL-only renderpath, which, depending on driver support, may run better or worse than the assembly shader path enabled by options 1-3; only use if the assembly shader paths are not working for your card, and you are reasonably certain the GLSL support is better.
-r -rS Executes the script commands S before any hardware initialization has taken place. If S is not specified, "init.cfg" will be loaded by default. The engine writes "init.cfg" out on exit with various hardware settings you have changed in-game (like screen width/height, FSAA, etc.), and this option allows those settings to be restored on a restart.
-qS Sets S to your home directory. If set, the engine will look for files in your home directory as well as the normal installation directory. However, all files will be written to your home directory, instead of the normal installation directory.
-kS Adds the mod directory S to the list of directories the engine will search in for files. Directories will be searched in the order listed on the command-line, and if not found, the engine looks in the installation directory.
-lS Loads map S on startup (default: base/metl4).
-xS Executes the script commands S on startup, note that this is done before the map loads, so if you wish them to be executed later, you should enclose them in a sleep statement. Example: -x"sleep 1000 [ connect localhost ]" -
uN Sets the server upstream bandwidth to N bytes per second. Only set this parameter if you know what you are doing, specifying a wrong value is worse than not specifying it at all.
-nN Sets the server description, for people pinging the server. usually does not need to be set if you have a descriptive domain name already, but if you set it, keep it short as it may otherwise be truncated (example: -n"Bobs Instagib Server").
-cN Sets the max number of clients to N. The default is 4. If you want to set it higher, be aware that bandwidth usage almost doubles with each extra client, so only do this if the server runs on a serious pipe (not your home DSL or Cable connection).
-iS Sets the server ip to S. This option is only useful for people running on machines with multiple network interfaces.
-jN Sets the server port to N. This option is only useful for people running on machines with multiple network interfaces. Note that both UDP ports N (game traffic) and N+1 (pings) must be available for this to work. If not specified, the default ports used are 28785 and 28786. Regardless of what ports are set, port 28784 must be available for pinging servers over a LAN to work.
-mS Sets the master server to use for either server (registering) and client (updating) to S. Be aware, this is the base url of the master server and has to end in a "/" and without a "http://" prefix (default: sauerbraten.org/masterserver/).
-pS Sets the server's administrative password to S.
-yS Locks the server so that password S must be provided to connect to it.
-oN Sets the openness of the server to N. N=1 disables mastermodes 2 (locked) and 3 (private), while N=0 (default) enables all mastermodes.
-gN Sets the maximum amount of bots a master can add to the server. Set to 0 to disable bots. The default is 8.
CubeScript
Cube's console language is similar to console languages of other games (e.g. Quake), but is a bit more powerful in that it is a full programming language.
What is similar to quake is the basic command structure: commands consist of the command itself, followed by any number of arguments seperated by whitespace. you can use "" to quote strings with whitespace in them (such as the actions in bind/alias), and whereever a command is required you can also use ; to sequence multiple commands in one.
What is new compared to quake is that you can evaluate aliases and expressions. You can substitute the value of an alias as an argument by prefixing it with a "$" sign, (example: echo The current value of x is $x). You can even substitute the values of console variables this way, i.e $fov gives the current fov. Some aliases are set automatically, for example $arg1 to $argN are set (as if by the "push" command) if you supply arguments when you execute an alias, and are popped when the alias finishes executing.
There are two alternatives to "" for quoting a string: ( ) and [ ]. They work in the same way as "", with the difference that they can be nested infinitely, and that they may contain linefeeds (useful for larger scripts). ( ) is different from [ ] in that it evaluates the commands contained in it _before_ it evaluates the surrounding command, and substitutes the results. ( ) bracketed strings are called expressions, and [ ] bracketed strings may be thought of as blocks.
An alternative to $x is @x, which uses an alias as a macro. The difference is that @x can be substituted inside [ ] or ( ) forms before they have ever been evaluated (at parse time), which makes them useful for composing strings or creating code on the fly. The @x form will be substituted using the value of x at the time the enclosing [] is evaluated. You can add more @ prefixes to move up more levels of [ ]s, so @@x will move up two levels of [ ]s and so on. Example: x = 0; if $cond [x = 1; [x = 2; echo @@x]] will echo 0, since it uses the value of x at two levels up.
The form @(body) is similar to @x, except that body contains commands executed at parse time. The result value after body executes is substituted in for @(body). You may use multiple @ prefixes as with the @x form. Example: @(result "Hello, World!") will substitute itself with Hello, World!
IMPORTANT NOTE: When dealing with array attributes (getting a piece of information from a set of values) it is important to know that most start at zero (0) and count upwards from there. This means that the first value is 0, the second is 1, the third is 2 and so forth. Please keep this in mind, especially when dealing with entity attributes, as zero is always considered to be the first/default value, not 1. Font Colors Use the text inside the quotes for the colors:
"^f0" green
"^f1" blue
"^f2" orange
"^f3" red
"^f4" grey
"^f5" purple
"^f6" dark orange
"^f7" white
So, echo "hello ^f6world" will print hello blue and world orange
Colors are reset for each [echo] or [say] or [sayteam]
you can also use ^f~ to cancel any color previously specified.
^fs saves a color, while ^fr restores the color previously specified. the amount of ^fr you use must match the ^fs used.
also, all color codes have to be quoted in order to work. ex: "^f0this ^f~is ^f5^fsa ^f4laaarge ^frsentence!"
The following commands are available for programming:
+ A B
- A B
* A B
div A B
mod A B
(add, substract, multiply, divide, modulo): these all work like the integer operators from other languages (example: x squared is echo(* $x $x) ).
= A B
< A B
> A B
strcmp A B
(equals, less than, greater than, string compare): comparison operators that return 1 for true and 0 for false.
! A
&& A B
|| A B
^ A B
(not, and, or, xor): Boolean operators. 0 is false, everything else is true. The AND and OR operators are implemented to shortcut.
strstr S N Searches the string S for the substring N and returns its starting position. This function is case sensitive, when N is not found it returns -1. (example: echo (strstr "for example this sentence" "this" ) - would return 12 ).
substr S A B Returns a part from the string S starting from A for B chars (example: echo (substr "grab this part here" 15 4 ) - would return "here" ).
strreplace S A B This searches the string S for substring A and replaces it with another substring B. (example: echo ( strreplace "this is serious" "serious" "fun" ) - would return "this is fun" ).
strlen S Returns the length of the string S (example: echo (strlen "long sentence") - would return 13 ).
min A B This results the lower number of the 2 Strings A and B
max A B This results the higher number of the 2 Strings A and B
rnd N Grabs a random number (integer) from 0 to N-1, and results it.
nummonsters N returns the number of monsters with tag N still alive (example curmonster1num = (nummonsters 1) )
if cond true false Executes the true or false part depending on whether cond is "0" or something else (example: if (< $x 10) [ echo "x is" $x ] [ echo "x is too big" ]).
loop I N body Evaluates body N times, and sets the alias I from 0 to N-1 for every iteration (example: loop i 10 [ echo $i ] ).
while cond body Evaluates body while cond evaluates to true. Note that cond here has to have [ ], otherwise it would only be evaluated once (example: i = 0; while [ (< $i 10) ] [ echo $i; i = (+ $i 1) ] ).
concat S... Concatenates all the arguments and returns the result
concatword S... Same as concat but without spaces between the elements.
format F V1..Vn Substitutes the V values into the format string F and returns the result. The format strings %1 through %9 are substituted with V1 through V9, respectively, and may be used multiple times. %% will generate a single % character (example: format "%1 bottles of %2 on the %3, %1 bottles of %2!" 99 beer wall ).
at S N Grabs the Nth word out of string S and returns the result (example: echo ( at "for example this sentence" 2 ) - would return "this" )
listlen L Returns the number of items in the list L (example: echo ( listlen "for example this sentence" ) - would return 4 )
listclients N Gives a list of all playernumbers if N is 1 if N is 0 it lists all players except you.
onrelease A Only executes A if the command is executed on the release of a key/button (must be in an action in a bind or an alias in a bind).
result V Normally the result of a [ ] block is the result of the last command in the block. If you want the result to be a particular variable or value, you can use e.g. "result $i" etc.
Useful variables
$editing This is true when in edit mode.
getalias V Returns the alias from the variable V.
getbind B geteditbind B getspecbind B Returns the game, edit or spectator bind B
getclientnum N getclientname N getclientteam N This returns the client number, name or team of the player N.
getname getteam getweapon getfps Tells your own Name Team Weapon or FPS
gettex Adds the current selected texture to the front of your texture list in Y+scroll Needs Allfaces set to 0 so it works.
gettexname Results the current Texture name
isconnected N If the Player N is online this is 1 (true)
isspectator N If the Player N is spectator this is 1 (true)
$numargs How many arguments have been passed
$triggerstate gives the state of the trigger (-1, 0, 1)
$consize gives the size, in lines, of the console
Console Commands