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:
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!"); then save the file. 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, which allows us to work with the stored data as we see fit. Objects which we give a name (aka identifier) in our programs are called variables.
We can create a variable like this: local x = 123; Let's break this down: local is a keyword used to define a variable, x is our variable name, and 123 is it's value. Altogether this line is called a statement. You can think of statements like sentences in a written language; they require a specific collection of words to be valid. The concept is exactly the same in programming languages. You'll learn all the different types of statements in Squirrel as we go along, the main thing to take away for now is how to create a variable and that instead of periods, statements in Squirrel end with a semicolon.
Identifiers
What we name our variables can be just about anything, but identifiers have a few rules for them to be valid:
- It cannot start with a number, but may have numbers after the first character.
- It may only have alphanumerical characters (a-z), (0-9), or underscores. Any other special characters are not allowed.
Identifiers are also case sensitive, so a variable named wep is not the same as one named WEP.
Valid Identifiers:
- _hello
- _123
- a456
- index
- weapon_sequence
Invalid Identifiers:
- 1x
- a-B
- $abc
- 1_a
- xyZ|