<p><spanstyle="font-family: 'Arial'">However, there are a few differences when it comes to characters that surround tokens. Double quotes work as you would expect:</span></p>
<p><spanstyle="font-family: 'Arial'">No processing is done to text inside double quotes. If you want to use variables or function return values, you shouldn't use double quotes. Within double quotes you may now use escape characters. As of now, this allows you to use \" in place of a double quote and \n in place of the newline character.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Courier'">echo "This token has two \"quotes\" and\na newline."</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">In addition to double quotes, you may now use curly braces to surround tokens. Curly braces have one unique feature: you may have line breaks within them:</span></p>
<p><spanstyle="font-family: 'Arial'">This is most useful with functions, loops, and if statements. As with double quotes, no processing is done inside curly braces. The final type of token is one surrounded by parentheses. These enclose math expressions that will be evaluated before the command is executed:</span></p>
<p><spanstyle="font-family: 'Arial'">See the section on the math evaluator for more information.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">Sometimes you will want to be able to combine tokens of different types into one token. For instance, it might be useful to include a math expression inside a string that will be displayed. You can use a comma (,) between two token to concatenate them:</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Courier'">echo "5 times 5 is ", (5*5), "."</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">GIB is fairly anal about malformed commands. Unmatched braces, parentheses, and double quotes will generate errors and halt execution of your program.</span></p>
<p><br>
</p>
<p><spanstyle="font-weight: bold; font-family: 'Times New Roman'; font-size: 16.000000pt">Variables</span></p>
<p><br>
</p>
<p><spanstyle="text-decoration: underline; font-family: 'Times New Roman'">Types</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">There are three types of variables in GIB: local, global, and console. Local variables are visible only to the current function and are destroyed when that function completes. Global variables are visible to all GIB functions and are never destroyed. Console variables are not strictly part of GIB but can be manipulated and used by it.</span></p>
<p><br>
</p>
<p><spanstyle="text-decoration: underline; font-family: 'Times New Roman'">Structure</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">Local and global variables differ from console variables in that they can be trees. For instance, the following would all be part of the same variable:</span></p>
<p><spanstyle="font-family: 'Arial'">If a variable is global, all branches of that variable are automatically global as well.</span></p>
<p><br>
</p>
<p><spanstyle="text-decoration: underline; font-family: 'Times New Roman'">Substitution</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">Any place outside quotes, the following patterns will be replaced with the value of the variable they specify:</span></p>
<p><spanstyle="font-family: 'Arial'">In the first example, the end of a variable name is considered to be the first non-alphanumeric, non-underline character, for instance:</span></p>
<p><spanstyle="font-family: 'Arial'">would be two different variables with a * between them</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">In the second example, everything within the braces ({ and }) is considered part of the variable name. Braces MUST be used when substituting branches of variables:</span></p>
<p><spanstyle="font-family: 'Arial'">This makes assignment dynamically to a branch less cumbersome, because periods in variable names won't automatically get swallowed. Variables can act as pointers to another variable by containing their name. You can then access the named variable indirectly through the pointer:</span></p>
<p><spanstyle="font-family: 'Arial'">Will give you characters 2 through 5 of the variable. Characters start at 0. If you try to access characters outside the length of the variable, it will be clipped to the end of the variable. A negative number counts backwards from the end of the variable, so -1 would mean the second from last character, -2 the third from the last, and so on. To specify the last character, use a colon but don't specify a second number. </span><spanstyle="text-position: ; color:#000000; font-family: 'Arial'; font-size: 12.000000pt">If you only want one character, you can omit the colon and second number. </span><spanstyle="font-family: 'Arial'">Consider these examples:</span></p>
<p><spanstyle="font-family: 'Arial'">where the variable i contains the name of the branch to assign to. Note that if the period after $i were considered to be part of the variable name, this wouldn't work. The number and level of branches is theoretically unlimited.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">When assigning to a variable that doesn't exist, it is automatically created as a local. If a local already exists, it is assigned to. If a global already exists, it is assigned to. If both a local and global exist with the same name, the local is assigned to. You should declare your globals in the main body of your GIB script with the following syntax:</span></p>
<p><spanstyle="font-family: 'Arial'">This ensures that the variable and all branches used later on will be persistent across different functions.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'">If you can't be certain that a variable you want to use as a local doesn't already exist as a global, you can use the following at the start of your functions:</span></p>
<p><spanstyle="font-family: 'Arial'">This will ensure that all further operations on that variable will use a local version. You will be sharing a namespace with any other loaded GIB scripts, so this is advised. On the other hand, it is bad practice to use common variable names such as i as globals. Consider created a single global variable with the name of your script and using branches of it to store global data.</span></p>
<p><br>
</p>
<p><spanstyle="font-weight: bold; font-family: 'Times New Roman'; font-size: 16.000000pt">Functions</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Functions are like aliases of the normal quake console, with several differences:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">- They execute in a new context</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">- They can take arguments</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">- They can return values</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">- They are normally not usable from the console.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">You declare a function as follows:</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">function name program</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">In general, you will want to write functions like this:</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">function test {</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">A function gets its own set of local variables whenever it is executed. Each instance of a function gets a unique set. When a function is executed, several local variables are set up for it. These are argc, the number of arguments the function was called with, and the numbers 0 through argc-1, each containing and argument. Argument 0 is the name of the function. Therefore, even a function called with no arguments will get an argc of 1. Consider the following example:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">You can use a "pointer" variable and argc to easily examine each argument passed to a function. The following function prints each argument passed to it on a separate line:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Functions can return a value to whatever called them at any time. The syntax for return is as follows:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">If you omit the value, the function will cease execution but will not return anything. Attempting to return a value where it isn't wanted (to a non-GIB buffer, or to a buffer that has not requested a return value, or at the top of the execution stack) will result in a warning, but execution will proceed as usual. In order to use the return value of a function, you must substitute it into your command using backticks (` `). This key is usually found above the tab key on most keyboards. It usually is the same key with ~ on it. Consider this example:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">The function within the backticks is run, and the return value is substituted in its place. This example would result in "Hello, world!" being printed. Some built-in GIB commands can return values; backticks can be used with these as well. Using backticks with something that does not result in a return value will cause an error.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Normally, GIB functions can only be called from other GIB functions. However, the export command can be used to make a GIB function available to the console:</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">function test {</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">The ideal GIB script will export several functions for use in binds or at the console and keep the rest unexported as support functions. This reduces namespace pollution.</span></p>
<p><br>
</p>
<p><spanstyle="font-weight: bold; font-family: 'Times New Roman'; font-size: 16.000000pt">Flow control</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Several GIB commands are available for controlling the flow of a GIB program:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">notes: While the condition statement evaluates to a non-zero number, the program will be continuously executed. You can use the break command at any time inside a loop to end the loop prematurely.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">notes: "for" iterates a local variable through each whitespace-separated token of a list. To achieve this, the internal command "__for" is used at the start of each iteration. Manual use of this command is highly discouraged.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">notes: </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">if</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt"> executes </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">program </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">when condition evaluates to a non-zero number (true). If the condition is false but else and a second program are present, it will be executed instead. </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">If-else</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt"> statements can be chained together. If </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">ifnot</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt"> is used instead of </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">if</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">, the first program will be executed if the statement is false and the second if the statement is true.</span></p>
<p><spanstyle="font-weight: bold; font-family: 'Times New Roman'; font-size: 16.000000pt">Math Evaluator</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">The math evaluator supports common arithmetic and logical operators and respects order of operations.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Operations will be performed starting at the top of the list and moving down. In addition to binary and unary operators, several functions are available:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">GIB provides rudimentary file access to the current game directory (the directory where the currently-loaded mod resides, determined by the console variable gamedir). All subdirectories of the current game directory are accessible, but attempts to escape higher into the file system via ".." will cause an access error.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Returns a list suitable for use in a for loop of all files in the current game directory that match </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">glob</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">. "*.cfg" and "file???.foo" are examples of globs. If the optional </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">subdir </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">argument is provided, that directory will be searched instead of the root game directory.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Threads are highly experimental at this point, and aren't true threads in that multitasking is not pre-emptive. Threads must issue the wait command to relinquish control to the console and other threads.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Callbacks are functions registered to be started in a thread when a certain event is triggered in the client or server. Currently, only a few events in qw-client can have callbacks associated with them, although more will be added.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Creates a new thread containing </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">program</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">. Returns a unique ID number that should be saved for looping threads.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Immediately ends the thread with the ID </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">id</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">As of the 0.5.2 release of QuakeForge, </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">qw-client provides several global variables and callbacks so that GIB can monitor player stats</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">. The "player" global tree variable is updated with information as follows:</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.armor.type</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">: The type </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">(green, yellow, red, none) of armor the player is wearing.</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.ammo</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">.(type)</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">: </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">Ammo of (type) that is a</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">v</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">a</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">ilable. </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">(type) can be shells, nails, rockets, or cells</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">.</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">weapon.(number): </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">1 i</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">f the weapon corresponding to (number</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">) is available, 0 otherwise.</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.key.</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">(</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">number)</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">: </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">1 if</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt"> the player has key or flag (number).</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt"> Number can be 1 or 2.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Several callbacks can be registered </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">that will get cal</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">led when one of these </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">stats changes</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">. Simply set the glo</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">bal variable to the name of the function to be called</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">:</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.health.callback: Passed the new health value as an argument</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.armor.callback: Passed the new armor value.</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">ammo.(type).callback: Passed the new am</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">mo value.</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.weapon.callback: Called when available weapons change.</span></p>
<p><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">player.key.callbac</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">k: Called when a</span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">ny key is gained or lost.</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Note that in the future these callbacks may get registered in a different way. These hooks are currently for t</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">esting purposes only.</span></p>
<p><br>
</p>
<p><spanstyle="font-weight: bold; font-family: 'Times New Roman'; font-size: 16.000000pt">Miscellaneous built-in functions</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Returns the program text of </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">function</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">.</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Returns a space-separated list of numbers between </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">start</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt"> and </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">end</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">. If a step size isn't specified, 1 is used. If end is less than start and a custom step size is specified, it must be negative. </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">step</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt"> cannot be 0 either. This command is best used with </span><spanstyle="font-family: 'Courier'; font-size: 12.000000pt">for</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt"> loops.</span></p>
<p><br>
</p>
<p><spanstyle="font-weight: bold; font-family: 'Times New Roman'; font-size: 16.000000pt">Using </span><spanstyle="font-weight: bold; font-family: 'Times New Roman'; font-size: 16.000000pt">GIB</span></p>
<p><br>
</p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">GIB code should be p</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">laced in a file with the extension</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt"></span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">.g</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">ib. </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">You can then load it like any other script with the exe</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">c command:</span></p>
<p><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">Scripts ending in .gib will be placed in a new buffer on the execution stack set to use the GIB interpreter rather than the normal quake console interpreter. Note that all other scripts a</span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">re simply copied into the current buffer. This means ANY script run from GIB will be considered a GIB script. Future versions of GIB will </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">allow you to force a command to be run </span><spanstyle="font-family: 'Arial'; font-size: 12.000000pt">in a standard console buffer.</span></p>
