An Introduction to Squirrel

Overview

This is a relatively brief beginner's guide to the Squirrel language (v3.2) aimed at people with no programming experience interested in trying their hand at VScript. The only prerequisite knowledge you are expected to have is basic knowledge of the Source engine. While in theory this guide is not technically specific to any Source game in particular, it is for version 3.2 which is unique as TF2's version of Squirrel. L4D2, Portal, and other Source games run on older versions, so in practice this guide is directed at TF2 players. If you're following this guide for another Source game that's perfectly fine, just be aware that some features may not function, or they might behave differently in your game's version of Squirrel. You'll also need to store your .nut files in the appropriate place of whatever game you're using, rather than the tf/scripts/vscripts folder.

If you already have experience with C-like languages or programming in general I would recommend you visit the Squirrel Reference Manual for a more expedient learning experience more aimed at developers.

Getting Started

While it's possible to compile the Squirrel source code into binaries with which you can test your code outside of a Source game, simply launching a game and executing your script is much simpler and allows us to test game specific code, so that's what we'll do for the duration of the guide. For guides on VScript itself, the VDC has an excellent collection:

• VScript Fundamentals
• Entity Scripts
• Script Functions
• Constants
• VScript Examples

To get set up, navigate to your tf/ directory and add a scripts/vscripts folder if it doesn't already exist and create a file with any name with the extension .nut. You should have a location something like this: C:\Program Files (x86)\Steam\steamapps\common\Team Fortress 2\tf\scripts\vscripts\testing.nut

Go ahead and launch your favorite Source game which supports VScript and load into any map on a local server, then bind any key to "script_execute testing". For example: bind 5 "script_execute testing"

Tab out of your game, open your .nut file and type:

printl("Hello World!");

Save the file then go back in game and press your bind, you should see your text in console!

Variables

Every program in any programming language is comprised of a set of instructions called statements which manipulate data to produce a desired result. Programs store data into regions of memory as objects. Objects which we give an identifier (name) in our programs are called variables. You can think of statements as analogous to sentences in the language we speak to each other, each requires a specific set of items to be considered valid, and each is ended with a specific character. Sentences are mostly ended with periods, and statements always end with a semicolon.

Identifiers have a few considerations to keep in mind:

• They are case-sensitive, wep is not the same as WEP
• The first character must be alphabetical (a-z) or an underscore, afterwards they can have any combination of (a-z), (0-9), or underscores
• Underscores are the only special character allowed, nothing else

Valid Identifiers:

• INDEX
• _weapon
• weapon_sequence
• player123

Invalid Identifiers:

• starting-index
• 1_ring_to_rule_them_all
• BOLD&BRASH
• $IMBATMAN

In addition, identifiers cannot be the same name as a keyword, which are special identifiers reserved by the language for its use in the syntax. We'll go over most of these throughout the guide, so don't worry about memorizing them just yet.

Keywords

base	break	case	catch	class	clone
continue	const	default	delete	else	enum
extends	for	foreach	function	if	in
local	null	resume	return	switch	this
throw	try	typeof	while	yield	constructor
instanceof	true	false	static	__LINE__	__FILE__
rawcall

To define a variable with x as it's identifier, we use the local keyword:

local x;

We created our variable in this statement but we haven't given it a value, so currently the value for x is null, which is a special value representing the lack of a value. To give our variable an actual value we have two options; we can set it at the time of definition (which is called initialization), or we can assign it a value with the assignment (=) operator in a separate statement, or both!

local x;
local y = 10;

x = 5;
y = 0;

Here we define x and initialize y to 10, and then set x to 5 and y to 0 afterwards.

Comments

A comment is a human readable note which was inserted by a programmer to denote the what, how, or why behind code. Comments are ignored by the compiler and only serve to make the code easier to understand or use for programmers. Comments come in two flavors: single line and multi line comments. Single line comments go until they hit a new line character (\n). Multi line comments have a start and end token, anything between them is commented out.

To insert a single line comment, prefix it with // or #.

// I'm a comment that takes the whole line
local darth_variable = 404 # I'm an inline comment

To insert a multi line comment, use /* to start and */ to end.

/*I
      am
          a
      multi
  line
comment
*/
local foo = 2;

You can "nest" single line comments, but you can't do this with multi line comments

//////////////////////// okay
/* // okay */
/* /* not okay */ */

The compiler will end the multi line comment at the first end token (*/) it sees, so the second one is outside of any comments and results in a compile error.

Data Types

Data stored in variables can have a number of different types which determines what type of object it is and what you can do with it.

To get a variable's data type as a string (see below on strings), you can use the typeof operator.

local t = typeof 5; // "integer"

Integer

Represents a 32 bit whole number, meaning it can store any value from -2,147,483,648 to 2,147,483,647. You can specify the integer base as hexadecimal by prefixing with 0x or octal with 0. You can also specify ASCII char codes between single quotes ' which will be stored as their integer value.

local x = 12345;    // Decimal
local y = 0xFFFFFF; // Hexadecimal begins with 0x
local z = 050;      // Octal begins with 0
local c = 'a';      // Char code stored as 97

These are all integer literals, which are hard coded pieces of data within a program for a specific data type. Other types have literals as well which you'll see in the examples below.

---

Bool

Has two values: true and false.

local is_stuck     = false;
local should_round = true;

---

Float

Represents a 32 bit floating point number, meaning it can store any decimal value from 1.18e-38 to 3.4e38. Due to how floating point numbers are stored in memory, they have a limited amount of accuracy for a certain number of significant digits, for a 32 bit float it's usually around 6 or 7 digits. Any additional digits for the float value may result in rounding errors and precision loss. Keep this in mind when you're working with floats.

local float1 = 1.23456;  // 1.23456 (Regular float literal)
local float2 = 1.2e34;   // 1.2e34  (Scientific notation float literal)

// Precision loss
local float3 = 1.234567; // 1.23457
local float4 = 1234.567; // 1234.57
local float5 = 123456.7; // 123457
local float6 = 12345678999.0; // 1.23457e+10

You cannot have a leading floating point for float literals, they must start with at least one digit.

// Invalid
local float1 = .123;
local float2 = .12E5;

// Valid
local float3 = 0.123;
local float4 = 0.12E5;

---

String

Strings are a sequence of characters with any length between quotation marks ". Strings are immutable, meaning they cannot be modified and you must create a new string if you need to change the old one. Regular strings must begin and end on the same line, they cannot contain any new line characters (\n).

local str1 = "@!(&(*@!%&!(%!%(%&FJSGADFJKL@fadjsh141a=-"; // String
local str2 = "123"; // String with number characters, not an integer
local str3 = "a";   // String
local str4 = "";    // Empty string

local int1 = 'a';   // NOT a string
local int2 = '';    // Compile error

local name = "bar";
name = "barber";

Strings may also contain escape sequences, which are characters that denote something special should happen. Even though they have multiple characters in their definition, they count as one character when actually using the string. Here are the ones you're most likely to use:

• \t - Inserts a tab
• \n - Move to new line
• \\ - \ char
• \" - " char
• \' - ' char

local text  = "Hello there! Please enter your class:\t";    // Tab
local text2 = "What do you mean you don't \"have one\"?\n"; // " char and new line

There may come a time when you need a string that does not interpret escape sequences or that can span multiple lines, which is where verbatim strings come in handy. Verbatim strings begin with @" and end with a regular quote ".

local mystring = @"eenie
meenie
minie
moe";

You may also need to add quote characters within the verbatim string, to do so you double up each quotation "". The double quote will be replaced with a single quote by the compiler.

local mystring = @"eenie
""meenie""
minie
moe";

---

Null

Has one value: null, it represents the non-existence or lack of a value.

---

Table Array Function Generator Class Instance Thread Userdata go over literals typeof

Operators

! != || == && >= <= > <=> + += - -= / /= *

• = % %= ++ -- <- = &

^ | ~ >> << >>>  ?: <=> in instanceof typeof ,

-, ~, !, typeof , ++, -- highest /, *, % … +, - <<, >>, >>> <, <=, >, >=, instanceof ==, !=, <=> & ^ &&, in +=, =, -=, /=, *=, %= … , (comma operator) lowest

IntegerLiteral  ::= [1-9][0-9]* | '0x' [0-9A-Fa-f]+ | [.]+ | 0[0-7]+ FloatLiteral  ::= [0-9]+ '.' [0-9]+ FloatLiteral  ::= [0-9]+ '.' 'e'|'E' '+'|'-' [0-9]+ StringLiteral  ::= '"'[.]* '"' VerbatimStringLiteral ::= '@"'[.]* '"'

Control Flow

if/else if/else for foreach while do while switch break continue

Exceptions

try catch throw