An Introduction to Squirrel: Difference between revisions

Latest revision as of 21:25, 22 January 2024

Overview[edit | edit source]

This is a relatively brief beginner's guide to the Squirrel language (v3.2) aimed at people with little to no programming experience. While this guide is intended to be used by people wanting to learn VScript for TF2, it doesn't cover anything regarding how to use VScript itself.

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 aimed at developers.

Getting Started[edit | edit source]

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 you to start tinkering with Squirrel quicker, 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. (Mine will be named testing.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!");

printl is a function that prints to the developer console, we'll go over what functions are and the syntax for it later in the guide, for now just follow along. After saving the file and pressing our script button in-game, you'll see Hello World! in console.

You just made your first program in VScript! To get started with the guide, choose a chapter in the table below. Make sure to tinker with the examples in the guide to see first hand how Squirrel works!

Good luck!

@@ Line 1: / Line 1: @@
-== Overview ==
+== [https://sigwiki.potato.tf/index.php?title=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 [https://developer.valvesoftware.com/wiki/VScript 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.
+This is a relatively brief beginner's guide to the Squirrel language (v3.2) aimed at people with little to no programming experience. While this guide is intended to be used by people wanting to learn VScript for TF2, it doesn't cover anything regarding how to use VScript itself.
-If you already have experience with C-like languages or programming in general I would recommend you visit the [http://squirrel-lang.org/squirreldoc/reference/index.html Squirrel Reference Manual] for a more expedient learning experience more aimed at developers.
+If you already have experience with C-like languages or programming in general I would recommend you visit the [http://squirrel-lang.org/squirreldoc/reference/index.html Squirrel Reference Manual] for a more expedient learning experience aimed at developers.
-== Getting Started ==
+== [https://sigwiki.potato.tf/index.php?title=An_Introduction_to_Squirrel 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:
+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 you to start tinkering with Squirrel quicker, so that's what we'll do for the duration of the guide. For guides on VScript itself, the VDC has an excellent collection:
 * [https://developer.valvesoftware.com/wiki/VScript_Fundamentals VScript Fundamentals]
 * [https://developer.valvesoftware.com/wiki/Entity_Scripts Entity Scripts]
@@ Line 13: / Line 13: @@
 * [https://developer.valvesoftware.com/wiki/Team_Fortress_2/Scripting/VScript_Examples/en 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.
+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. (Mine will be named testing.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".
+You should have a location something like this: <pre>C:\Program Files (x86)\Steam\steamapps\common\Team Fortress 2\tf\scripts\vscripts\testing.nut</pre>
-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!
+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 <code>"script_execute testing"</code>.
+For example: <code>bind 5 "script_execute testing"</code>
-== 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 a name (aka identifier) 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.
+Tab out of your game, open your .nut file and type:
-Identifiers have a few considerations to keep in mind:
+<syntaxhighlight lang="c#" line="1" start="1" style="font-weight:bold;>
-* '''They are case-sensitive, wep is not the same as WEP'''
+printl("Hello World!");
-* '''The first character must be alphabetical (a-z) or an underscore, afterwards they can have any combination of (a-z), (0-9), or underscores'''
+</syntaxhighlight>
-* '''Underscores are the only special character allowed, nothing else'''
+<code>'''printl'''</code> is a function that prints to the developer console, we'll go over what functions are and the syntax for it later in the guide, for now just follow along. After saving the file and pressing our script button in-game, you'll see <code>Hello World!</code> in console.
+You just made your first program in VScript! To get started with the guide, choose a chapter in the table below. Make sure to tinker with the examples in the guide to see first hand how Squirrel works!
+Good luck!
-'''Valid Identifiers:'''
-* INDEX
-* _weapon
-* weapon_sequence
-* player123
-'''Invalid Identifiers:'''
+<hr>
-* starting-index
-* 1_ring_to_rule_them_all
-* BOLD&BRASH
-* $IMBATMAN
-In addition, identifiers cannot be the same name as any keyword, which are reserved by the language for its use. We'll go over most of these throughout the guide, so don't worry about memorizing them.
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0;"
-{| class="wikitable" style="width:75%; margin:auto; text-align:center font-weight:bold; font-size:125%"
+|-
-|+Keywords
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|base
+{| class="wikitable mw-collapsible mw-collapsed" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|break
+! colspan="1" style="padding: 25px; background-color: #303030; color: white; border: 2px solid black" | Chapters
-|case
+|-
-|catch
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|class
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|clone
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Variables Variables]
+|}
 |-
-|continue
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|const
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|default
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Comments Comments]
-|delete
+|}
-|else
-|enum
 |-
-|extends
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|for
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|foreach
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Data_Types Data Types]
-|function
+|}
-|if
-|in
 |-
-|local
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|null
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|resume
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Operators Operators]
-|return
+|}
-|switch
-|this
 |-
-|throw
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|try
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|typeof
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Expressions Expressions]
-|while
+|}
-|yield
-|constructor
 |-
-|instanceof
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|true
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|false
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Intro_to_Functions Intro to Functions]
-|static
+|}
-|__LINE__
-|__FILE__
 |-
-|rawcall
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
-|
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
-|
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Intro_to_Objects Into to Objects]
-|
+|}
-|
+|-
-|
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Scopes Scopes]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Control_Flow Control Flow]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Exceptions Exceptions]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Enums Enums]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Arrays Arrays]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Tables Tables]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Functions Functions]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Generators Generators]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Delegation Delegation]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Weak_References Weak References]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Classes Classes]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Inheritance Inheritance]
+|}
+|-
+| colspan="1" style="padding: 0; margin: 0; width: 100%;" |
+{| class="wikitable" style="margin: 0 auto; width: 100%; padding: 0; border: none;"
+! colspan="1" style="border: 1px solid black; padding-right:64px; background-color: #606060; color: #111111; height: 35px;" | [https://sigwiki.potato.tf/index.php/Squirrel_Metamethods Metamethods]
+|}
+|}
 |}
-<div style="margin-top: 50px;">To define a variable with x as it's identifier, we use the <code>'''local'''</code> keyword:</div>
-<syntaxhighlight lang="c" line="1" start="1" style="font-weight:bold;">
-local x;
-</syntaxhighlight>
-We created our variable in this statement but we haven't given it a value, so currently the value for x is null by default (we'll go over what null is later in Data Types). To give our variable a 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 (<code>'''='''</code>) operator in a separate statement, or both!
-<syntaxhighlight lang="c" line="1" start="1" style="font-weight:bold;>
-local x;
-local y = 10;
-x = 5;
-y = 0;
-</syntaxhighlight>
-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 newline 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 <code>'''//'''</code> or <code>'''#'''</code>.
-<syntaxhighlight lang="c#" line="1" start="1" style="font-weight:bold;>
-// I'm a comment that takes the whole line
-local darth_variable = 404 # I'm an inline comment
-</syntaxhighlight>
-To insert a multi line comment, use <code>'''/*'''</code> to start and <code>'''*/'''</code> to end.
-<syntaxhighlight lang="c" line="1" start="1" style="font-weight:bold;>
-/*I
-      am
-          a
-      multi
-  line
-comment
-*/
-local foo = "bar";
-</syntaxhighlight>
-You can "nest" single line comments, but you can't do this with multi line comments
-<syntaxhighlight lang="c" line="1" start="1" style="font-weight:bold;>
-//////////////////////// okay
-/* // okay */
-/* /* not okay */ */
-</syntaxhighlight>
-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 ==
-<nowiki>
-integer, float, string, null, table, array, function, generator, class, instance, bool, thread and userdata.
-== Literals and 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 ::=  '@''"'[.]* '"'
-</nowiki>
-== [https://sigwiki.potato.tf/index.php?title=An_Introduction_to_Squirrel#Overview Expressions] ==
-== Intro to Functions ==
-== Intro to Objects ==
-== Scope ==
-== Control Flow ==
-if/else if/else
-for
-foreach
-while
-do while
-switch
-break
-continue
-== Exceptions ==
-try catch
-throw
-== Enums ==
-== Arrays ==
-== Tables ==
-== Functions ==
-== Generators ==
-== Delegation ==
-== Weak References ==
-== Classes ==
-== Inheritance ==
-== Metamethods ==

An Introduction to Squirrel: Difference between revisions

Latest revision as of 21:25, 22 January 2024

Overview[edit | edit source]

Getting Started[edit | edit source]

Navigation menu