Difference between revisions of "Configuration Reference Guide"

Latest revision as of 15:53, 22 June 2008

Take some time to read the rest of this document, as it describes options and commands that may be crucial to a successful experience with Sandbox.

You may want to look at the default configuration file "defaults.cfg" located in the "config" directory. Should you wish to change any settings before you start, create a file name "config.cfg" and set them there. Alternatively, if you would like to override settings (now, and in the future), use the file named "autoexec.cfg".

Binding keys, as well as performance and gameplay related settings are documented below, these commands can be used in both the console and configuration scripts. In addition, you can also press "ESC" to go into the menu, which will provide you with an interface for navigating some (not all) of the commands. Running Sandbox

   * For Windows: Install, edit, then run CLICK_ME_TO_START.bat.
   * For Linux: gunzip, chmod +x sandbox_unix and then ./sandbox_unix.  
   Needs a decent and compliant OpenGL implementation.

Sandbox derives its simplicity from some rather brute force rendering methods, and as such it needs a beefy machine to get good visual quality. It runs best with vertical sync (vsync) set to OFF and at high refresh rates (otherwise, you may get excessive LOD/FPS variance). Command Line Options

-d

This starts Sandbox as a dedicatated 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).

-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 Sandbox 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.

-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.

-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: NOTE NO MASTER SERVER SETUP YET).

-pS

Sets the server's administrative password to S.

-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. Console Commands

bind K A

editbind K A

Binds key K to commands A (see console language below for what you can put in A). To find out what key names and their default bindings are, look at data/keymap.cfg, then add bind commands to your autoexec.cfg. Editbind works much the same way, except now the key is only available in edit mode (if no editbind is defined for a certain key, it will use the normal binding).

alias N A

Binds name N to commands A, after which you can use N as a shortcut for A. You may re-bind N as often as you like, call it recursively etc. You may use N = A as a shortcut for alias.

push N A

Pushes the old value of name N onto its stack, and then aliases N to A.

pop N

Pops the old value of name N off its stack, then aliases N to that value.

quit

Quits without asking.

forward

backward

left

right

Move you in said direction (default key: up down left right, w s a d).

jump

Triggers a jump (default key: space, right mouse).

zoom N

Zooms in if N is -1, zooms out if N is 1, and turns off zoom if N is 0.

taunt

Plays your player model's taunt animation.

floatspeed N

Sets the speed at which your character floats in edit mode or spectator mode (default: 100).

invmouse B

Toggles mouse between regular and inverted (flight sim) mode (default: 0 (uninverted)).

sensitivity S

Sets mouse sensitivity (default: 3). The feel of which should be a similar number to Quake.

sensitivityscale S

Scales the effect of an increase or decrease in the sensitivity value. The larger the value, the smaller the difference between sensitivity values (default: 1).

maxfps N

Sets the max number of FPS (Frames per Second). Useful if you have a recent machine that can run the engine at close to 1000FPS, or if you want to test. If you set maxfps to exactly or a simple ratio of your monitor's refresh rate, you may experience tearing. Be aware that maxfps is not a replacement for vsync (default: 200).

fov N

Sets your FOV to 10..150.

zoomfov N

Sets your zoomed-in FOV to N.

zoominvel N

Sets the number of milliseconds over which zoom-in happens. Zoom-in is instant if N is 0. (default: 250)

zoomoutvel N

Sets the number of milliseconds over which zoom-out happens. Zoom-out is instant if N is 0. (default: 100)

zoomsens S

Sets mouse sensitivity when zoomed-in (default: 1).

zoomautosens B

Toggles whether mouse sensitivity should be automatically scaled to match the zoomed-in FOV relative to FOV. This overrides "zoomsens" if enabled. (default: 1)

hudgun N

Sets hudguns either on (1) or off (0).

hudgunsway N

Sets hudgun sway either on (1) or off (0).

grass N

Sets grass 0..1 generated by autograss textures to be drawn (default: 1).

grassdist N

Sets the maximum distance 0..10000 at which grass is drawn (default: 500).

grassanimdist N

Sets the maximum distance 0..10000 at which grass is animated (default: 500). This setting should be a last resort if your intention is to increase performance.

shaderdetail N

This sets the level of detail shaders should use, for N=3 is highest, and N=0 is lowest. Lower settings will give speedups on slower hardware.

maxtexsize N

This sets the maximum allow size of a texture in texture memory. If any texture's width or height is greater than N, the texture will be scaled down to be no more than NxN. This variable is not saved, and is reset on each run with the 3D card's texture size limit, so set this in your "autoexec.cfg" if you want to override it. Set this to a small value like 128 if your card has very little texture memory (i.e. 32 MB or less).

mintexcompresssize N

Any texture whose width or height is greater than or equal to N will be compressed using S3 texture compression, if available on your card. The default is set to 1024, so set this lower if your card supports S3TC and you have very little texture memory (i.e. 64 MB or less).

loddistance N

Sets the distance at which world vertex array blocks are rendered at a higher LOD (level of detail). The lower this value, the more geometry popup you will see, but the faster it may render. Every system has a different optimal value, experiment. This variable only has an effect for large scale maps where the level designer has turned on LOD using the "lodsize" variable.

watersubdiv N

Determines the subdivision of the water surface in maps, which can greatly affect fps on slow machines. Must be a power of 2: 4 is the default, 8 is recommended for people on slow machines, 2 is nice for fast machines, and 1 is quite OTT. See the edit reference for more information on how to add the water material to your levels.

waterlod N

Sets the precision level of the water LOD (Level of Detail) from 0..3, where 0 is the lowest and 3 is the highest setting (default: 1).

waterreflect B

Enables or disables water reflections (default: 1).

waterenvmap B

Enables or disables water environment-mapping (cheaper fake reflections). By default, this is used when "waterreflect" is turned off.

waterrefract B

Enables or disables water refractions. (default: 1).

waterfade B

Enables or disables soft fading of water edges. This option only works if "waterrefract" is enabled. (default: 1).

waterfallrefract B

Enables or disables refractive waterfalls. (default: 0).

waterfallenv B

Enables or disables environment-mapped waterfall reflections. (default: 1).

reflectdist N

Sets the maximum distance geometry/objects can be at to be in a reflection from 0..10000 (default: 2000).

reflectsize N

Sets the resolution of reflected surfaces (where the dimensions would measure 2^N x 2^N), from 6..10 (default: 8). Lowering this value results in a grainier image, whereas increasing it results in a finer and mroe detailed image. This too should be used to fine tune the speed of reflection rendering.

maxreflect N

Sets the maximum number of reflection surfaces that can be visible at once from 1..8 (default: 1). Any surfaces exceeding this limit will not be given reflections on their surfaces.

reflectmms B

Toggles whether map models are rendered in reflections (default: 1).

envmapsize N

Sets the resolution of generated environment maps to 2^Nx2^N (default: 7).

maxparticledistance N

The maximimum visibility distance for particle effects from 256..4096 (default: 512).

particlesize N

The size of default particle effects from 20..500 (default: 100).

emitfps N

The rate at which paricles can be emitted from 1..200 fps (default: 60).

flarelights B

Enables or disables automatic lens flares for all lights (default: 0). Requires very careful placement of lights to be effective, and most maps are not currently designed with this in mind. Therefore it is recomended that lens flares instead be placed manually by using particles entities.

flarecutoff N

The maximum visiblity distance of a lens flare source from 0..10000 (default: 1000). Note that visibility also depends on the viewers angle to the flare source.

flaresize N

The size of the lens flare effect from 20..500 (default: 100).

setfullscreenshader [N [P]]

Sets your favourite fullscreen shader. Active permanently once set. Use without N argument to turn it off. Certain shaders like bloom require you to specify a P for the intensity. Current example shaders: bw, invert, gbr, sobel, bloom

screenshot

Writes out "screenshotN.bmp", where N is the number of milliseconds since the game was launched (default key: F12).

musicvol N

soundvol N

Sets the music/sound volume from 0..255.

soundbufferlen N

Sets the sound buffer length in bytes, tweak this if you experience stuttering or lagging sound (default: 512).

gamma N

Sets the hardware gamma value to N percent (default: 100). May not work if your card/driver doesn't support it.

hidestats B

Toggles display of fps/rendering stats on the HUD (default: 1).

hidehud B

Toggles the entire hud display, which includes rendering stats, ammo, and echoed text (default: 0).

maxroll N

Sets the maximum value your display will roll on strafing from 0..20 (default: 3)

crosshairsize N

Sets the size of your crosshair, 0 being off (default: 3).

crosshairfx B

Toggles crosshair effects (default: 1). When on, the crosshair will go grey when the weapon is reloading, orange when health <= 50, or red when <=25.

exec S

Executes all commands in config file S.

history N

Executes the Nth command in the command line history. For example, binding "history 0" to a key allows you to quickly repeat the last command typed in (useful for placing many identical entities etc.)

keymap K N A

Sets up the keymap for key code K with name N and default action A. You should never have to use this command manually, use "bind" instead. GUI Commands

gui2d B

Sets whether menus should be shown in 2D, or 3D if disabled (default 0).

menudistance D

Sets the distance at which the menu is created in front of the player (default 40).

menuautoclose D

Sets the distance at which the menu is automatically closed when the player moves away from it (default 120).

guiautotab H

Sets the height of the gui before tabs are automatically generated.

cleargui

Hides the menu.

showgui N

Displays the menu with name N previously defined, and allows the user to pick and manipulate items with the cursor. Pressing ESC will cancel the menu.

newgui S

Creates a new menu with name S. All the following 'gui' menuitem commands will apply to this menu. See "data/menus.cfg" for defaults.

guilist '[' ... ']'

Defines a menu item that is a group of menu items. The layout of each nested group will alternate - the top level (newgui) is laid out vertically, the first guilist will be laid out horizontally, the second guilist vertically, etc. This allows tables and lists to be created. The layout direction also influences the display of items such as sliders, bars, progress bars, and struts.

guititle S

Creates a menu item with horizontally centered title S.

guibutton [S] A [I]

Creates a menu button with the name S and icon I, which will execute A when selected. If you only specify one parameter, then it will be used for both. The icon used will be I if supplied, otherwise a blue-button if A contains showgui, otherwise it is a green button. Clicking a button will close the menu.

guiimage P A S [O]

Creates a menu image tile from the path P, which will execute A when selected. Clicking the image will close the menu. Uses image scale S and O=1 if an overlay is required.

guitext S

Creates a menu consisting of the text line S and an information icon.

guibar

Creates a vertical/horizontal menu bar. The orientation depends on the layout direction.

guislider V [MIN MAX A]

Creates a vertical/horizontal menu slider that is bound to a variable V. The min/max bounds of the slider will be as defined by the data model of the variable unless explicitly specified. An action A can also be specified for every slider change. The orientation of the slider depends on the layout direction.

guicheckbox N V [ON OFF A]

Creates a menu checkbox with a label N that is bound to a variable V. The default value are 0/1 unless supplied by ON/OFF. An action A can also be specified for every checkbox change.

guiradio N V VAL [A]

Creates a menu radio button with a label N that is bound to a variable V. The radio button is only ticked when the variable has value VAL, and presing the button will update the variable to the value VAL. An action A can also be specified for every radio button change.

guitab S

Creates a new menu tab with title S. Note: has no effect if used within a guilist.

guifield A N [O [U]]

Creates a field which accepts editable input, the value of which is taken from and updated to (upon change) the alias A, and can have at most N characters. If specified, O is executed when the user presses enter. If U is also specified, it will execute it every every frame (unless it is currently being edited) to allow updating the field. Note that all fields that share the same A alias, also share the same edit info, if the user moves outside the field the changes are not committed, if they select another field, changes will be lost. 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 subtituted 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!

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: echo x squared is (* $x $x)).

= A B

< A B

> A B

strcmp A B

(equals, lessthan, greaterthan, stringcompare): 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.

if cond true false

Executes the true or false part depending on wether 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

listlen L

Returns the number of items in the list L

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.

Variables that are only really useful when used as value:

$editing

This is true when in edit mode.