Difference between revisions of "TeaScript Syntax"

From PGE Wiki
Jump to navigation Jump to search
m
m
(44 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
[[Category:TeaScript.vbs]]
 
[[Category:TeaScript.vbs]]
WIP documentation of TeaScript. Feel free to add any information necessary below.
+
==Data Types and Variables==
 +
 
 +
===User Variables===
 +
User variables can be access in the variable menu or by pressing ctrl+i. All of these variables must be created using this interface.  
 +
 
 +
====Doubles & Strings====
 +
By clicking the <code>Add</code> button in the variable interface you create a user variable.  
  
==Data Types and Variables==
+
You may also select if the variable is a local or global <code>user variable</code>. Local <code>user variables</code> can only exist in a single level and the value is reset every time the level begins. Global variables save the value per level and remembers the value even after quitting the game.
Teascript only offers two data types. These are doubles and strings.  
 
  
===Double===
+
'''Variable Naming Standard'''
Doubles are represented as numbers. This includes whole and decimal numbers.
 
(IEEE 64-bit 8-bytes,-1.79769313486232×10308 to -4.94065645841247×10-324 for negative values,4.94065645841247×10-324 to 1.79769313486232×10308 for positive values) variables.
 
  
Double variables can be accessed with the following methods:
+
*Names are not case sensitive.
 +
*Names must not contain spaces.
 +
*Names must be made using a combination of letters and numbers only.
 +
*Names must start with a letter
  
<syntaxhighlight lang="vb">
+
<code>User variables</code> work in an unusual way compared to other scripting languages. A <code>user variable</code> has two sides, a <code>double</code> and a <code>string</code>. There are different methods to access each side<syntaxhighlight lang="vb" start="1">
 +
' By creating a variable called "myVar" in the interface you can...
 +
' === Access doubles
 
'Local
 
'Local
 
val(myVar) or v(myVar)
 
val(myVar) or v(myVar)
Line 18: Line 26:
 
gval(myVar) or gv(myVar)
 
gval(myVar) or gv(myVar)
  
'Local Concatenation in TXTCreate and Messages
+
'Local Concatenation in TXTCreate and Event Messages
 
&val(myVar)
 
&val(myVar)
  
'Global Concatenation in TXTCreate and Messages
+
'Global Concatenation in TXTCreate and Event Messages
 
&gval(myVar)
 
&gval(myVar)
</syntaxhighlight>
 
 
===String===
 
Strings are represented as text. You can create a string by surrounding text with quotation marks. "Example"
 
  
<syntaxhighlight lang="vb">
+
' === Access strings
 
'Local
 
'Local
 
str(myVar)
 
str(myVar)
Line 35: Line 39:
 
gstr(myVar)
 
gstr(myVar)
  
'Local Concatenation in TXTCreate and Messages
+
'Local Concatenation in TXTCreate and Event Messages
 
$val(myVar)
 
$val(myVar)
  
'Global Concatenation in TXTCreate and Messages
+
'Global Concatenation in TXTCreate and Event Messages
 
$gvl(myVar)
 
$gvl(myVar)
 +
 +
</syntaxhighlight><br /><syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
 +
v(myVar) = 5
 +
str(myVar) = "Hello"
 +
 +
v(myVar) = v(myVar) + 2
 +
str(myVar) =  str(myVar) & " World"
 +
 +
' v(myVar) now has the value of 7
 +
' str(myVar) now has the value of "Hello World"
 +
' Notice how a user variable simultaneously hold a double and a string at the same time. The double side does not interfere with the string side and vice versa.
 +
</syntaxhighlight>Note how a <code>user variable</code> simultaneously can hold a <code>double</code> and a <code>string</code>.
 +
 +
====Arrays====
 +
By clicking <code>Add</code> while holding shift in the variable interface you create a <code>user array</code>. Currently, <code>user arrays</code> can only contain <code>double</code> values. <code>User arrays</code> must first be initialized using the redim <code>function</code> before usage.<syntaxhighlight lang="vb">
 +
' By creating an array called "myArr" in the interface you can...
 +
' Initialize the array using redim
 +
' Read documentation on redim for more information
 +
call redim(0, myArr, ARRAY_LENGHT)
 +
' Access value of an array at an index
 +
array(myArr(index))
 +
</syntaxhighlight><syntaxhighlight lang="vb">
 +
' === Example
 +
call redim(0, myArr, 3)
 +
array(myArr(1)) = 5
 +
array(myArr(2)) = 7
 +
array(myArr(3)) = array(myArr(1)) + array(myArr(2))
 +
' The array now has the following values of [5, 7, 12]
 
</syntaxhighlight>
 
</syntaxhighlight>
===Other===
 
TeaScript.vbs also lists SMBX Event, Layers, and Scripts as pseudo data types. This data cannot be stored in a variable. This data is used by typing the name of the object without quotation marks in appropriate functions.
 
  
===Usage===
+
===Dim Variables===
Variables can be manipulated in the following ways.
+
<code>Dim variables</code> are a different way of creating and interacting with variables compared to user variables. A <code>dim variable</code> can only have a single type of data that must be defined on creation. Variable naming standards are the same as <code>user variables</code>, except you may not use the same name of other existing <code>functions</code> and <code>keywords</code>. If a <code>dim variable</code> is initialized without a value, it defaults to 0 or "" depending on the type. <syntaxhighlight lang="vb">
 +
' You can initialize a variable
 +
dim varName as type
  
All variables must be created using the variable interface (found using ctrl+i in the editor)
+
' You can initialize a variable with a defined value
*Local variables are created in the level editor mode and only exist in the level it was created. Local variables reset every time the level start.
+
dim varName as type = value
*Global variables are created in the world editor mode and exist throughout the entire episode. Global variables are saved even after level-death or when you quit the episode.
 
<syntaxhighlight lang="vb">
 
'To set and get the value of a variable
 
'(myVar1 and myVar2 are local variables)
 
  
v(myVar1) = 1
+
'Once initialized you just write the variable name to access it
v(myVar2) = v(myVar1) + 1
+
varName
v(myVar1) = 5
+
</syntaxhighlight><syntaxhighlight lang="vb" line="1">
'myVar1 is 5 and myVar is 2
+
' === Example
 +
dim myInt as integer
 +
dim myLng as long
 +
dim myDbl as double = 5
 +
dim myStr as string = "Hello"
  
str(myVar1) = "Hello"
+
myInt = myDbl*2
str(myVar1) = str(myVar1)&", how are you?"
+
myLng = myDbl*5
'myVar is "Hello, how are you?"
+
myStr = myStr & " World"
</syntaxhighlight>
 
  
 +
'myInt has the value of 10
 +
'myLng has the value of 25
 +
'myDbl has the value of 5
 +
'myStr has the value of "Hello World"
 +
</syntaxhighlight><br />
 
==Expressions==
 
==Expressions==
===Mathematical Symbols===
+
An expression is a line of code that evaluates to an answer. Something as simple as <code>1 + 1</code> is an expression. Teascript offers different tools to create diverse expressions that suit what you specifically need.
 +
 
 +
===Operators===
 +
 
 +
====Mathematical Operators====
 
{| class="wikitable" style="width: 100%;"
 
{| class="wikitable" style="width: 100%;"
! colspan="3" style="font-size:large; background-color:#9b59b6; color:#ffffff;" | Mathematical Symbols
+
! colspan="3" style="font-size:large; background-color:#9b59b6; color:#ffffff;" |Mathematical Symbols
 
|-
 
|-
! style="font-weight:bold; font-size:medium; background-color:#efefef;width:8%;" | Symbol
+
! style="font-weight:bold; font-size:medium; background-color:#efefef;width:8%;" |Symbol
! style="text-align: center; font-weight:bold; font-size:medium; background-color:#efefef;width:25%;" | Name
+
! style="text-align: center; font-weight:bold; font-size:medium; background-color:#efefef;width:25%;" |Name
! style="font-weight:bold; font-size:medium; background-color:#efefef;" | Example
+
! style="font-weight:bold; font-size:medium; background-color:#efefef;" |Example
 
|-
 
|-
 
| +
 
| +
| style="text-align: center;" | Addition
+
| style="text-align: center;" |Addition
| <syntaxhighlight lang="vb">12 + 3 + 5 'returns 19</syntaxhighlight>
+
|<syntaxhighlight lang="vb">
 +
12 + 2 + 3 'returns 17
 +
</syntaxhighlight>
 
|-
 
|-
 
| style="background-color:#efefef;" | -
 
| style="background-color:#efefef;" | -
| style="text-align: center; background-color:#efefef;" | Subtraction
+
| style="text-align: center; background-color:#efefef;" |Subtraction
| style="background-color:#efefef;" | <syntaxhighlight lang="vb">12 - 3 - 5 'returns 4</syntaxhighlight>
+
| style="background-color:#efefef;" |<syntaxhighlight lang="vb">
 +
12 - 2 - 3 'returns 7
 +
</syntaxhighlight>
 
|-
 
|-
| *
+
|*
| style="text-align: center;" | Multiplication
+
| style="text-align: center;" |Multiplication
| <syntaxhighlight lang="vb">12*2*5 'returns 120</syntaxhighlight>
+
|<syntaxhighlight lang="vb">
 +
12*2*5 'returns 120
 +
</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | /
+
| style="background-color:#efefef;" |/
| style="text-align: center; background-color:#efefef;" | Division
+
| style="text-align: center; background-color:#efefef;" |Division
| style="background-color:#efefef;" | <syntaxhighlight lang="vb">'Note that division by 0 will crash SMBX
+
| style="background-color:#efefef;" |<syntaxhighlight lang="vb">
12/2/5 'returns 1.2</syntaxhighlight>
+
'Note that division by 0 will crash SMBX  
 +
12/2/5 'returns 1.2
 +
</syntaxhighlight>
 
|-
 
|-
| \
+
|\
| style="text-align: center;" | Division with no remainder
+
| style="text-align: center;" |Division with no remainder
| <syntaxhighlight lang="vb">'Note that division by 0 will crash SMBX
+
|<syntaxhighlight lang="vb">
12\2\5 'returns 1.2</syntaxhighlight>
+
'Note that division by 0 will crash SMBX
 +
12\2\5 'returns 1
 +
</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | ^
+
| style="background-color:#efefef;" |^
| style="text-align: center; background-color:#efefef;" | Power
+
| style="text-align: center; background-color:#efefef;" |Power
| style="background-color:#efefef;" | <syntaxhighlight lang="vb">'Note that 0^0 will return 1
+
| style="background-color:#efefef;" |<syntaxhighlight lang="vb">'Note that 0^0 will return 1
 
12^2 'returns 144</syntaxhighlight>
 
12^2 'returns 144</syntaxhighlight>
 
|-
 
|-
| mod
+
|mod
| style="text-align: center;" | Modulus
+
| style="text-align: center;" |Modulus
| <syntaxhighlight lang="vb">12 mod 5 'returns 2</syntaxhighlight>
+
|<syntaxhighlight lang="vb">'Note that modulating by 0 will crash SMBX
 +
12 mod 5 'returns 2</syntaxhighlight>
 +
|-
 +
| style="background-color:#efefef;" |&
 +
| style="text-align: center; background-color:#efefef;" |Concatenation
 +
| style="background-color:#efefef;" |<syntaxhighlight lang="vb">"ABC" & ";" & "123" 'returns "ABC;123"</syntaxhighlight>
 +
|-
 +
|( )
 +
| style="text-align: center;" |Parenthesis
 +
|<syntaxhighlight lang="vb">12*(2 + 5) 'returns 84</syntaxhighlight>
 +
|}
 +
 
 +
====Comparing Operators====
 +
Note that all <code>comparative operators</code> require both sides use the same data type. You can compare numbers with other numbers and strings with other strings, but you cannot compare numbers with strings.
 +
{| class="wikitable" style="width: 100%;"
 +
! colspan="3" style="font-size:large; background-color:#9b59b6; color:#ffffff;" |Comparitive Operators
 +
|-
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |Symbol
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |Name
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |Description
 +
|-
 +
| rowspan="2" |=
 +
| rowspan="2" |Equal
 +
|'''Numbers''' Returns -1 if both sides are equal, otherwise 0
 +
|-
 +
|'''Strings''' Returns -1 if both sides are equal, otherwise 0
 +
|-
 +
| rowspan="2" style="background-color:#efefef;" |<>
 +
| rowspan="2" style="background-color:#efefef;" |Not equal
 +
| style="background-color:#efefef;" |'''Numbers''' Returns -1 if both sides are not equal, otherwise 0
 +
|-
 +
| style="background-color:#efefef;" |'''Strings''' Returns -1 if both sides are not equal, otherwise 0
 +
|-
 +
| rowspan="2" |>
 +
| rowspan="2" |Grater than
 +
|'''Numbers''' Returns -1 if the value on the left is larger, otherwise 0
 +
|-
 +
|'''Strings''' Unknown pattern
 +
|-
 +
| rowspan="2" style="background-color:#efefef;" |<
 +
| rowspan="2" style="background-color:#efefef;" |Less than
 +
| style="background-color:#efefef;" |'''Numbers''' Returns -1 if the value on the left is smaller, otherwise 0
 +
|-
 +
| style="background-color:#efefef;" |'''Strings''' Unknown pattern
 +
|-
 +
| rowspan="2" |>=
 +
| rowspan="2" |Greater than or equal
 +
|'''Numbers''' Returns -1 if the value on the left is larger or equal, otherwise 0
 +
|-
 +
|'''Strings''' Unknown pattern
 +
|-
 +
| rowspan="2" style="background-color:#efefef;" |<=
 +
| rowspan="2" style="background-color:#efefef;" |Less than or equal
 +
| style="background-color:#efefef;" |'''Numbers''' Returns -1 if the value on the left is smaller or equal, otherwise 0
 +
|-
 +
| style="background-color:#efefef;" |'''Strings''' Unknown pattern
 
|-
 
|-
| style="background-color:#efefef;" | &
+
| rowspan="2" style="background-color:#efefef;" |like
| style="text-align: center; background-color:#efefef;" | Concatenation
+
| rowspan="2" style="background-color:#efefef;" |Like
| style="background-color:#efefef;" | <syntaxhighlight lang="vb">"ABC"&";"&"123" 'returns "ABC;123"</syntaxhighlight>
+
| style="background-color:#efefef;" |'''Numbers''' Not compatible, crashes the game
 
|-
 
|-
| ( )
+
| style="background-color:#efefef;" |'''Strings''' https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/operators/like-operator
| style="text-align: center;" | Parenthesis
 
| <syntaxhighlight lang="vb">12*(2 + 5) 'returns 84</syntaxhighlight>
 
 
|}
 
|}
  
===Mathematical Functions===
+
====Logical Operators====
These are the mathmatical function provided.
+
<code>Logical operators</code> only work on numbers. They are commonly used with -1 and 0 to represent true and false respectively. Other numbers can be used but it may yield different patterns.
<br>Parameters with ''#param'' mean that the parameter is a double.
 
<br>Parameters with ''"param"'' mean that the parameter is a string.
 
  
 
{| class="wikitable" style="width: 100%;"
 
{| class="wikitable" style="width: 100%;"
! colspan="3" style="font-size:large; background-color:#9b59b6; color:#ffffff;" | Functions
+
! colspan="9" style="font-size:large; background-color:#9b59b6; color:#ffffff;" |Logical Operators
 +
|-
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |P
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |Q
 +
| style="font-size:medium; background-color:#efefef;" |
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |not P
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |P and Q
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |P or Q
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |P xor Q
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |P eqv Q
 +
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |P imp Q
 +
|-
 +
|0
 +
|0
 +
|
 +
| -1
 +
|0
 +
|0
 +
|0
 +
| -1
 +
| -1
 +
|-
 +
| style="background-color:#efefef;" |0
 +
| style="background-color:#efefef;" | -1
 +
| style="background-color:#efefef;" |
 +
| style="background-color:#efefef;" | -1
 +
| style="background-color:#efefef;" |0
 +
| style="background-color:#efefef;" | -1
 +
| style="background-color:#efefef;" | -1
 +
| style="background-color:#efefef;" |0
 +
| style="background-color:#efefef;" | -1
 +
|-
 +
| -1
 +
|0
 +
|
 +
|0
 +
|0
 +
| -1
 +
| -1
 +
|0
 +
|0
 
|-
 
|-
! style="font-weight:bold; font-size:medium; background-color:#efefef;width:32%;" | Name and Parameters
+
| style="background-color:#efefef;" | -1
! style="text-align: center; font-weight:bold; font-size:medium; background-color:#efefef;width:8%;" | Return Type
+
| style="background-color:#efefef;" | -1
! style="font-weight:bold; font-size:medium; background-color:#efefef;width:60%;" | Description and Example
+
| style="background-color:#efefef;" |
 +
| style="background-color:#efefef;" |0
 +
| style="background-color:#efefef;" | -1
 +
| style="background-color:#efefef;" | -1
 +
| style="background-color:#efefef;" |0
 +
| style="background-color:#efefef;" | -1
 +
| style="background-color:#efefef;" | -1
 +
|}<br />
 +
===Special Values===
 +
These special values behave like numbers.
 +
{| class="wikitable" style="width: 50%;"
 +
! colspan="2" style="font-size:large; background-color:#9b59b6; color:#ffffff;" |Special Values
 
|-
 
|-
| '''abs'''(#num)
+
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |Name
| style="text-align: center;" | Double
+
| style="font-weight:bold; font-size:medium; background-color:#efefef;" |Value
| Returns the absolute value of a number
+
|-
 +
|pi
 +
|3.141592654
 +
|-
 +
| style="background-color:#efefef;" |e
 +
| style="background-color:#efefef;" |2.71828182
 +
|-
 +
|rnd
 +
|A random number between 0 and 1. The value changes every time the variable is accessed.
 +
|}
 +
 
 +
===Built-in Functions===
 +
<code>Functions</code> are powerful tools that allow you to simplify and expand the flexibility of your scripts. To access a <code>function</code>, you write the function name and in parenthesis write the parameters separated by commas. You can put <code>functions</code> inside an <code>expression</code> just as it were a regular number or string.
 +
 
 +
For a list of <code>custom functions</code> created by the community check [[Custom Extra Scripts (TeaScript)|here]].<syntaxhighlight>
 +
myFunc(param1, param2, ..., paramN)
 +
</syntaxhighlight><syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
dim x as integer = -5
 +
dim y as integer
 +
y = abs(x) + 1 
 +
' x returns -5; y returns 6
 +
' Note how the abs() function is used
 +
</syntaxhighlight>These are the the mathematical <code>functions</code> provided in TeaScript.
 +
 
 +
Parameters can be <u>numbers,</u> ''strings'', and '''arrays'''.
 +
 
 +
{| class="wikitable" style="width: 100%;"
 +
! colspan="3" style="font-size:large; background-color:#9b59b6; color:#ffffff;" |Functions
 +
|-
 +
! style="font-weight:bold; font-size:medium; background-color:#efefef;width:32%;" |Name and Parameters
 +
! style="text-align: center; font-weight:bold; font-size:medium; background-color:#efefef;width:8%;" |Return Type
 +
! style="font-weight:bold; font-size:medium; background-color:#efefef;width:60%;" |Description and Example
 +
|-
 +
|'''abs'''(<u>x</u>)
 +
| style="text-align: center;" |Number
 +
|Returns the absolute value of a number
 
<syntaxhighlight lang="vb">abs(-3) 'returns 3</syntaxhighlight>
 
<syntaxhighlight lang="vb">abs(-3) 'returns 3</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''exp'''(#num)
+
| style="background-color:#efefef;" |'''exp'''(<u>x</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center; background-color:#efefef;" |Number
| style="background-color:#efefef;" | Returns the number to the power of the ''e'' constant
+
| style="background-color:#efefef;" |Returns the number to the power of the ''e'' constant
 
<syntaxhighlight lang="vb">exp(5) 'returns e^5</syntaxhighlight>
 
<syntaxhighlight lang="vb">exp(5) 'returns e^5</syntaxhighlight>
 
|-
 
|-
| '''log'''(#num)
+
|'''log'''(<u>x</u>)
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| Returns the log of the number with a base of ''e''
+
|Returns the log of the number with a base of ''e''
 
<syntaxhighlight lang="vb">log(e) 'returns 1</syntaxhighlight>
 
<syntaxhighlight lang="vb">log(e) 'returns 1</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''sgn'''(#num)
+
| style="background-color:#efefef;" |'''sgn'''(<u>x</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center; background-color:#efefef;" |Number
| style="background-color:#efefef;" | Returns the sign of the number (1, -1, or 0)
+
| style="background-color:#efefef;" |Returns the sign of the number (1, -1, or 0)
<syntaxhighlight lang="vb">sgn(10) 'returns 1
+
<syntaxhighlight lang="vb">sgn(10) 'returns 1
sgn(0) 'returns 0</syntaxhighlight>
+
sgn(0)   'returns 0
 +
sgn(-10) 'returns -1</syntaxhighlight>
 
|-
 
|-
| '''int'''(#num)
+
|'''int'''(<u>x</u>)
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| Returns the number rounded up. Similar to the common ceiling function
+
|Returns the number rounded up. Similar to the common ceiling function
 
<syntaxhighlight lang="vb">int(2.1) 'returns 3</syntaxhighlight>
 
<syntaxhighlight lang="vb">int(2.1) 'returns 3</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''fix'''(#num)
+
| style="background-color:#efefef;" |'''fix'''(<u>x</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center; background-color:#efefef;" |Number
| style="background-color:#efefef;" | Returns the number rounded down. Similar to the common floor function
+
| style="background-color:#efefef;" |Returns the number rounded down. Similar to the common floor function
<syntaxhighlight lang="vb">int(2.9) 'returns 2</syntaxhighlight>
+
<syntaxhighlight lang="vb">fix(2.9) 'returns 2</syntaxhighlight>
 
|-
 
|-
| '''sqr'''(#num)
+
|'''sqr'''(<u>x</u>)
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| Returns the square root of a number
+
|Returns the square root of a number
 
<syntaxhighlight lang="vb">sqr(9) 'returns 3</syntaxhighlight>
 
<syntaxhighlight lang="vb">sqr(9) 'returns 3</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''sin'''(#num)
+
| style="background-color:#efefef;" |'''sin'''(<u>x</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center; background-color:#efefef;" |Number
| style="background-color:#efefef;" | Returns the sine of the number. Uses radians
+
| style="background-color:#efefef;" |Returns the sine of the number. Uses radians
 
<syntaxhighlight lang="vb">sin(pi) 'returns 0</syntaxhighlight>
 
<syntaxhighlight lang="vb">sin(pi) 'returns 0</syntaxhighlight>
 
|-
 
|-
| '''cos'''(#num)
+
|'''cos'''(<u>x</u>)
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| Returns the cosine of the number. Uses radians
+
|Returns the cosine of the number. Uses radians
 
<syntaxhighlight lang="vb">cos(pi) 'returns 1</syntaxhighlight>
 
<syntaxhighlight lang="vb">cos(pi) 'returns 1</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''tan'''(#num)
+
| style="background-color:#efefef;" |'''tan'''(<u>x</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center; background-color:#efefef;" |Number
| style="background-color:#efefef;" | Returns the tangent of the number Uses radians
+
| style="background-color:#efefef;" |Returns the tangent of the number Uses radians
 
<syntaxhighlight lang="vb">tan(pi/4) 'returns 1</syntaxhighlight>
 
<syntaxhighlight lang="vb">tan(pi/4) 'returns 1</syntaxhighlight>
 
|-
 
|-
| '''atn'''(#num)
+
|'''atn'''(<u>x</u>)
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| Returns the inverse tangent of the number. Uses radians
+
|Returns the inverse tangent of the number. Uses radians
 
<syntaxhighlight lang="vb">atn(1) 'returns pi/4</syntaxhighlight>
 
<syntaxhighlight lang="vb">atn(1) 'returns pi/4</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''getangle'''(#x, #y)
+
| style="background-color:#efefef;" |'''getangle'''(<u>x</u>, <u>y</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center; background-color:#efefef;" |Number
| style="background-color:#efefef;" | Returns the angle (from 0 to 1) formed between the triangle. Similar to the common atan2 function.
+
| style="background-color:#efefef;" |Returns the angle (from 0 to 1) formed between the triangle. Similar to the common atan2 function.
 
<syntaxhighlight lang="vb">getangle(1, 0)  'returns 0
 
<syntaxhighlight lang="vb">getangle(1, 0)  'returns 0
 
getangle(1, 1)  'returns .125
 
getangle(1, 1)  'returns .125
Line 191: Line 382:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
|-
 
|-
| '''rgba'''(#red, #green, #blue, #alpha)
+
|'''rgba'''(<u>red</u>, <u>green</u>, <u>blue</u>, <u>alpha</u>)
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| Returns an SMBX color value. Parameters must be between 0 and 255
+
|Returns an SMBX color value. Parameters must be between 0 and 255
 
<syntaxhighlight lang="vb">rgba(255, 255, 255, 255) 'returns -1</syntaxhighlight>
 
<syntaxhighlight lang="vb">rgba(255, 255, 255, 255) 'returns -1</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''round'''(#num, #decimal_place)
+
| style="background-color:#efefef;" |'''round'''(<u>x</u>, <u>decimal place</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center; background-color:#efefef;" |Number
| style="background-color:#efefef;" | Returns the number rounded
+
| style="background-color:#efefef;" |Returns the number rounded<syntaxhighlight lang="vb">
<br>'''decimal_place''' The decimal place rounded to
+
round(1.3456, 2) 'returns 1.35
<syntaxhighlight lang="vb"> round(1.3456, 2) 'returns 1.35</syntaxhighlight>
+
</syntaxhighlight>
 
|-
 
|-
| '''len'''("txt")
+
|'''len'''(''txt'')
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| Returns the length of the text
+
|Returns the length of the text
 
<syntaxhighlight lang="vb"> len("ABC") 'returns 3</syntaxhighlight>
 
<syntaxhighlight lang="vb"> len("ABC") 'returns 3</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''left'''("txt", #len)
+
| style="background-color:#efefef;" |'''left'''(''txt'', <u>len</u>)
| style="text-align: center; background-color:#efefef;" | String
+
| style="text-align: center; background-color:#efefef;" |String
| style="background-color:#efefef;" | Returns the text cropped starting with the length provided. The crop begins from the start
+
| style="background-color:#efefef;" |Returns the text cropped from the string inputted. The crop begins from the start and ends with the length specified.<syntaxhighlight lang="vb">
 +
left("Hello", 2) ' Returns "He"
 +
</syntaxhighlight>
 
|-
 
|-
| '''right'''("txt", #len)
+
|'''right'''(''txt'', <u>len</u>)
| style="text-align: center;" | String
+
| style="text-align: center;" |String
| Returns the text cropped starting with the length provided. The crop finished with the end
+
|Returns the text cropped from the string inputted. The crop ends from the end and begins with the length specified.<syntaxhighlight lang="vb">
 +
right("Hello", 3) ' Returns "llo"
 +
</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''mid'''("txt", #len)
+
| style="background-color:#efefef;" |'''mid'''(''txt'', <u>start</u>, <u>len</u>)
| style="text-align: center; background-color:#efefef;" | String
+
| style="text-align: center; background-color:#efefef;" |String
| style="background-color:#efefef;" | Returns the text cropped starting with the length provided. The crop begins with the number provided.
+
| style="background-color:#efefef;" |Returns the text cropped at the specified start and has the specified length provided. <syntaxhighlight lang="vb">
 +
mid("Hello", 2, 3) ' Returns "ell"
 +
</syntaxhighlight>
 
|-
 
|-
| '''replace'''("txt", "search", "replacement", #start, #count, #case_insensitive)
+
| style="background-color:#efefef;" |'''asc'''(''char'')
| style="text-align: center;" | String
+
| style="text-align: center; background-color:#efefef;" |Number
| Replaces a part of the text with a new one.
+
| style="background-color:#efefef;" |Returns the ANSI code. It will use the first character if more than one is passed<syntaxhighlight lang="vb">
<br>'''start''' Where in the txt should the search start
+
asc("A")  ' Returns 65
<br>'''count''' The number of replacements. Set to -1 to disable
+
</syntaxhighlight>
<br>'''case_insensitive''' Set to 1 to make the search case-insensitive, otherwise use 0
 
 
|-
 
|-
| style="background-color:#efefef;" | '''asc'''("character")
+
|'''chr'''(<u>code</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center;" |String
| style="background-color:#efefef;" | Returns the ANSI code. It will use the first character if more than one is passed
+
|Returns a string using the ANSI code. Accepts 0-255<syntaxhighlight>
 +
chr(65)  ' Returns "A"
 +
</syntaxhighlight>
 
|-
 
|-
| '''chr'''(#code)
+
| style="background-color:#efefef;" |'''ascw'''(''char'')
| style="text-align: center;" | String
+
| style="text-align: center; background-color:#efefef;" |Number
| Returns a string using the ANSI code. Accepts 0-255
+
| style="background-color:#efefef;" |Returns the unicode code. It will use the first character if more than one is passed<syntaxhighlight lang="vb">
 +
ascw("A")  ' Returns 65
 +
</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''ascw'''("character")
+
|'''chrw'''(<u>code</u>)
| style="text-align: center; background-color:#efefef;" | Double
+
| style="text-align: center;" |String
| style="background-color:#efefef;" | Returns the unicode code. It will use the first character if more than one is passed
+
|Returns a string using the unicode code. Accepts 0-65535<syntaxhighlight lang="vb">
 +
chrw(65) ' Returns "A"
 +
</syntaxhighlight>
 
|-
 
|-
| '''chrw'''(#code)
+
| style="background-color:#efefef;" |'''cstr'''(<u>num</u>)
| style="text-align: center;" | String
+
| style="text-align: center; background-color:#efefef;" |String
| Returns a string using the unicode code. Accepts 0-65535
+
| style="background-color:#efefef;" |Converts the number to a string<syntaxhighlight lang="vb">
 +
cstr(1)  ' Returns "1"
 +
</syntaxhighlight>
 
|-
 
|-
| style="background-color:#efefef;" | '''cstr'''(#num)
+
|'''cdbl'''(''txt'')
| style="text-align: center; background-color:#efefef;" | String
+
| style="text-align: center;" |Number
| style="background-color:#efefef;" | Converts the number to a string
+
|Converts the string into a number<syntaxhighlight lang="vb">
|-
+
cdbl("1") ' Returns 1
| '''cdbl'''("txt")
+
</syntaxhighlight>
| style="text-align: center;" | Double
 
| Converts the string into a number
 
 
|-
 
|-
| '''instr'''(#start, "string1", "string2")
+
|'''instr'''(<u>start</u>, ''txt'', ''search'')
| style="text-align: center;" | Double
+
| style="text-align: center;" |Number
| To return the point of the first appearance of a given string in another string.
+
|To return the point of the first appearance of a given string in another string.
  
 
<br>'''start''' To specify the start point of the search
 
<br>'''start''' To specify the start point of the search
<br>'''string1''' The original string
+
<br>'''txt''' The original string
<br>'''string2''' The string to be searched
+
<br>'''search''' The string to be searched<syntaxhighlight lang="vb">
 +
instr(1, "abcde", "b") ' Returns 2
 +
</syntaxhighlight>
 +
|-
 +
|'''ubound'''('''array''')
 +
| style="text-align: center;" |Number
 +
|Returns the length of the array<syntaxhighlight lang="vb">
 +
call redim(0, myArr, 3)
 +
ubound(myArr) ' Returns 3
 +
</syntaxhighlight><br />
 
|}
 
|}
  
===Special Values===
+
==Control Flow==
These special values behave like numbers.
+
When a <code>script</code> is run in TeaScript it will start reading the <code>script</code> from top to bottom, left to right. It will read and execute the code in that order. the following is a list of ways to customize and manipulate what code gets executed in your <code>scripts</code>.
{| class="wikitable" style="width: 50%;"
+
 
! colspan="2" style="font-size:large; background-color:#9b59b6; color:#ffffff;" | Special Values
+
===Declarations===
|-
+
A <code>declaration</code> is when you set a value to a variable. This applies to <code>user variables</code>, <code>dim variables</code>, and other values.<syntaxhighlight lang="vb">
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | Name
+
' Basic form of a declaration
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | Value
+
' The variable is written in the left
|-
+
' The value you want set is written in the right
| pi
+
variable = value
| 3.141592654
+
</syntaxhighlight><syntaxhighlight lang="vb" line="1">
|-
+
' === Examples
| style="background-color:#efefef;" | e
+
v(myVar) = 5
| style="background-color:#efefef;" | 2.71828182
+
dim x as integer
|-
+
dim y as double = 10
| rnd
+
sysval(score) = 0
| A random number between 0 and 1
+
x = v(myVar) + 10
|}
+
NPC(1).xsp = 0
 +
</syntaxhighlight>
 +
 
 +
===Conditions===
 +
<code>Conditions</code> represent true and false.  In Teascript, -1 and 0 represents true and false. Any number that is not 0 may also represent true, but use -1 and 0 for consistency reasons.<syntaxhighlight lang="vb" line="1">
 +
' === Examples
 +
 
 +
-1  ' Represents True
 +
0   ' Represents False
 +
5  ' Represents True (because non-zero numbers represent true)
  
===Comparing and Logical Operators===
+
dim w as integer = -1
 +
dim x as integer = 5
 +
dim y as integer = 5
 +
dim z as integer = 0
  
{| class="wikitable" style="width: 50%;"
+
w    ' Represents True (because w has the value of -1)
! colspan="3" style="font-size:large; background-color:#9b59b6; color:#ffffff;" | Comparitive Operators
+
x    ' Represents True (because x has a value of a non-zero number)
|-
+
y    ' Represents True (because y has a value of a non-zero number)
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | Symbol
+
z    ' Represents False (because z has a value of 0)
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | Name
 
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | Description
 
|-
 
| rowspan="2" | =
 
| rowspan="2" | Equal
 
| '''Doubles''' Returns -1 if both sides are equal, otherwise 0
 
|-
 
| '''Strings''' Returns -1 if both sides are equal, otherwise 0
 
|-
 
| rowspan="2" style="background-color:#efefef;" | <>
 
| rowspan="2" style="background-color:#efefef;" | Not equal
 
| style="background-color:#efefef;" | '''Doubles''' Returns -1 if both sides are not equal, otherwise 0
 
|-
 
| style="background-color:#efefef;" | '''Strings''' Returns -1 if both sides are not equal, otherwise 0
 
|-
 
| rowspan="2" | >
 
| rowspan="2" | Grater than
 
| '''Doubles''' Returns -1 if the value on the left is larger, otherwise 0
 
|-
 
| '''Strings''' Unknown pattern
 
|-
 
| rowspan="2" style="background-color:#efefef;" | <
 
| rowspan="2" style="background-color:#efefef;" | Less than
 
| style="background-color:#efefef;" | '''Doubles''' Returns -1 if the value on the left is smaller, otherwise 0
 
|-
 
| style="background-color:#efefef;" | '''Strings''' Unknown pattern
 
|-
 
| rowspan="2" | >=
 
| rowspan="2" | Greater than or equal
 
| '''Doubles''' Returns -1 if the value on the left is larger or equal, otherwise 0
 
|-
 
| '''Strings''' Unknown pattern
 
|-
 
| rowspan="2" style="background-color:#efefef;" | <=
 
| rowspan="2" style="background-color:#efefef;" | Less than or equal
 
| style="background-color:#efefef;" | '''Doubles''' Returns -1 if the value on the left is smaller or equal, otherwise 0
 
|-
 
| style="background-color:#efefef;" | '''Strings''' Unknown pattern
 
|}
 
  
Logical operators only work on doubles. They are commonly used with 0 and -1. Other numbers can be used but it may yield different patterns.
+
z - 1    ' Represent True (because 0 - 1 = -1)
 +
w + 1    ' Represent False (because -1 + 1 = 0)
  
{| class="wikitable" style="width: 50%;"
+
' Using logical operators
! colspan="9" style="font-size:large; background-color:#9b59b6; color:#ffffff;" | Logical Operators
+
not w          ' Represent False
|-
+
not (y and z)  ' Represents True
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | P
+
w or z        ' Represents True
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | Q
+
</syntaxhighlight>
| style="font-size:medium; background-color:#efefef;" |
 
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | not P
 
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | P and Q
 
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | P or Q
 
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | P xor Q
 
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | P eqv Q
 
| style="font-weight:bold; font-size:medium; background-color:#efefef;" | P imp Q
 
|-
 
| 0
 
| 0
 
|
 
| -1
 
| 0
 
| 0
 
| 0
 
| -1
 
| -1
 
|-
 
| style="background-color:#efefef;" | 0
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" |
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" | 0
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" | 0
 
| style="background-color:#efefef;" | -1
 
|-
 
| -1
 
| 0
 
|
 
| 0
 
| 0
 
| -1
 
| -1
 
| 0
 
| 0
 
|-
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" |
 
| style="background-color:#efefef;" | 0
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" | 0
 
| style="background-color:#efefef;" | -1
 
| style="background-color:#efefef;" | -1
 
|}
 
  
==Control Flow==
+
===If Statements===
===If statements===
+
The <code>if statement</code> is a basic but useful statement. It has one parameter being a <code>condition</code>.
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
if [conditon] then
+
' Basic if statement
   'statement that should run if the first condition is true
+
if conditon then
elseif [condition] then
+
   statement
   'statement that should run if the other condition is true
+
end if
 +
 
 +
' Shortcut if statement
 +
if condition then statement
 +
 
 +
' If statement using one elseif and an else statement
 +
if conditon then
 +
  statement
 +
elseif condition then
 +
   statement
 +
...    ' You can have as many elseif as you want
 +
else
 +
  statement
 +
end if
 +
</syntaxhighlight>
 +
When TeaScript reads an <code>if statement</code> it will check each <code>condition</code> from top to bottom until it reaches a <code>condition</code> that is true. When it reaches a <code>condition</code> that is true, it will execute the <code>statements</code> inside and continue the code after the entire <code>if statement</code>. This means that <code>conditions</code> written on the top will have priority over those <code>conditions</code> in the bottom.
 +
 
 +
The <code>else</code> is special since it does not require any <code>conditions</code>. An <code>else</code> must be written in the bottom after all other <code>elseif</code> statements (if there are any). The code inside the <code>else</code> will only run if every other <code>condition</code> in the  <code>if</code> and <code>elseif</code> statements evaluated to false.<syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
dim x as integer = 0
 +
dim y as integer = -1
 +
dim z as integer = -1
 +
 
 +
' Since (x and y) evaluates to 0, this statement is not run.
 +
if x and y then z = 0
 +
 
 +
' Since (x and z) evaluates to 0, this statement is not run.
 +
if x and z then
 +
  y = 0
 +
 
 +
' Since (y) evaluates to -1, this statement is run.
 +
elseif y then
 +
  x = -1
 +
 
 +
' Since the previous elseif has priority and only one statement can be run, this statement is not run
 
else
 
else
   'statement that should run if all the other conditions are false
+
   z = -1
 
end if
 
end if
 +
 
</syntaxhighlight>
 
</syntaxhighlight>
===Select Case===
+
 
Select Case lets you easily organize the control flow by a value.  
+
===Select Case Statements===
 +
<code>Select Case</code> lets you easily organize the control flow based on a value. It has one parameter being a value.
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
select case v(var)
+
select case value
 +
  case -1
 +
    statement ' Will run if value is exactly -1
 
   case 0 to 1
 
   case 0 to 1
     'Script that should pass if v(var)'s value is between 0 and 1.
+
     statement ' Will run if value is between (inclusive) 0 and 1
   case 2
+
  case is < -1
     'Script that should pass if v(var)'s value is exactly 2.
+
    statement ' Will run if value is less than negative one
 +
   case 2, 3, 4
 +
     statement ' Will run if value is exactly 2, 3 or 4
 +
  case "example"
 +
    statement ' Will run if value is exactly "example".
 
   case else
 
   case else
     'Script that should pass if v(var)'s value does not match any of the other conditions.
+
     statement ' Will run if value does not match any of the other conditions
 
end select</syntaxhighlight>
 
end select</syntaxhighlight>
  
===For Loop===
+
<code>Select case</code> at its core is similar to various <code>if statements</code> and behaves similarly to the common "switch" statement in other languages. It will read the value that is passed and executes the first code in which the value matches. It will read the cases from top to bottom giving priority to cases at the top.
===Do Loop===
+
 
There are three different versions of do loops: While loops, Until Loops, and Pure Loops.
+
The <code>to</code> keyword can be used when checking for a case.
 +
 
 +
*'''Numbers''' Will be true if the value is between (inclusive) the two numbers provided.
 +
*'''Strings''' Unknown pattern
 +
 
 +
The <code>is</code> keyword can be used to make comparisons to the value. It can be used with  the <code><, >, <=,</code> or <code>>=</code> logical operators.
 +
 
 +
You can use commas to check for multiple cases at once. The commas behave similarly to an <code>or</code> logical operator. The case will go through if it matches with any of the cases.
 +
 
 +
===With Statements===
 +
<code>With statements</code> are useful to read or write on multiple properties of an object. An object can be for example an NPC, Block, or BGO. Check the classes section for more information on SMBX Objects. You can acess all of the properties by typing a <code>.</code> followed by the property name.
 +
<syntaxhighlight lang="vb">
 +
with object
 +
  .property_name
 +
end with
 +
</syntaxhighlight>
 +
<br />
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
'Pure loop:
+
' === Example
do
+
with NPC(1)
   'this loop will run infinitely until it hits an "exit do" statement
+
   .x = 12345
loop
+
  .y = 54321
 
+
  .forecolor = rgba(10, 60, 60, 255)
'While Loop:
+
   v(myVar) = .ysp
do while [condition]
+
end with
   'this loop will run as long as the condition returns true
 
loop while [condition]
 
  
'Until Loop:
+
' This is equivalent to:
do until [condition]
+
  NPC(1).x = 12345
   'this loop will run until the condition returns true
+
  NPC(1).y = 54321
loop until [condition]
+
   NPC(1).forecolor = rgba(10, 60, 60, 255)
 +
  v(myVar) = NPC(1).ysp
 
</syntaxhighlight>
 
</syntaxhighlight>
  
With while and until loops, you may choose where to place the 'while' or 'until' keyword. There can only be one of either keyword in the entire loop.
 
===With Statements===
 
 
===Goto===
 
===Goto===
Using goto it will force the script to jump to the specified line using a label.
+
Using <code>goto</code> will force the script to jump to a specific line to a specific label. The label name must be followed by <code>:</code>.  <code>Goto</code> does not work inside <code>with statements</code>.
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
 
Example:
 
Example:
[statements]
+
 
 
goto Example
 
goto Example
 
</syntaxhighlight>
 
</syntaxhighlight>
When the script reached "goto Example" it will jump to "Example" and execute the script below it. The labels used with goto statements must: have names that do not contain characters that do not follow variable name rules and there must not be two labels with the same name.
+
<br />
 +
 
 
===GoSub===
 
===GoSub===
 +
Using <code>gosub</code> will force the script to jump to a specific line to a specific label. Teascript will remember where the jump happened and can be returned by using  <code>return</code>.The label name must be followed by <code>:</code>.  <code>Gosub</code> does not work inside <code>with statements</code>.
 +
 +
<syntaxhighlight lang="vb">
 +
Example:
 +
 +
gosub Example
 +
return  ' When it reaches this line, it will return back to the first line
 +
 +
</syntaxhighlight><syntaxhighlight lang="vb">
 +
' === Example
 +
gosub Example
 +
call showMsg("b")
  
==Script==
 
Using the script keyword, it allows you to make a function in Teascript.
 
 
Example:
 
Example:
 +
call showMsg("a")
 +
return
 +
' Take note of the order the messages are shown
 +
</syntaxhighlight>
 +
 +
==Loops==
 +
A loop allows you to run a piece of code multiple times. Teascript is very flexible in the type of loops you can create.
 +
 +
It is important to note that you should avoid an infinite loop. Creating an infinite loop will freeze the game. Make sure to either have a [[Functions_(TeaScript)#Sleep|<code>sleep</code>]] function (if the script was called by an event) or an <code>exit</code>.
 +
===Pure Loops===
 +
A <code>pure loop</code> is a very simple and basic form of a loop. It will run indefinitely.
 +
<syntaxhighlight lang="vb">
 +
'Pure loop:
 +
do
 +
  statement
 +
loop
 +
</syntaxhighlight><syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
' Calling this script once will run the code every tick
 +
do
 +
  statement
 +
  call sleep(1)
 +
loop
 +
 +
</syntaxhighlight>
 +
 +
===While Loops===
 +
A <code>while loop</code> will continue the loop while the <code>condition</code> is <code>true</code>. You can set up a <code>while loop</code> in 2 different ways. The difference is by when the loop checks its condition. If you place the <code>while</code> at the bottom, you guarantee then code will be run at least once.<syntaxhighlight lang="vb">
 +
do while condition
 +
  statement
 +
loop
 +
 +
do
 +
  statement
 +
loop while condition
 +
</syntaxhighlight><syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
dim x as integer
 +
 +
x = 0
 +
do while x < 5
 +
  x = x + 1
 +
loop
 +
 +
x = 0
 +
do
 +
  x = x + 1
 +
loop while x < 5
 +
 +
' Both loops ran 5 times
 +
</syntaxhighlight>
 +
 +
===Until Loops===
 +
An <code>until loop</code> will continue the loop until the <code>condition</code> is <code>true</code>. You can set up an <code>until loop</code> in 2 different ways. The difference is by when the loop checks its condition. If you place the <code>until</code> at the bottom, you guarantee then code will be run at least once.<syntaxhighlight lang="vb">
 +
do until condition
 +
  statement
 +
loop
 +
 +
do
 +
  statement
 +
loop until condition
 +
</syntaxhighlight><syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
dim x as integer
 +
 +
x = 0
 +
do until x = 5
 +
  x = x + 1
 +
loop
 +
 +
x = 0
 +
do
 +
  x = x + 1
 +
loop until x = 5
 +
 +
' Both loops ran 5 times
 +
</syntaxhighlight>
 +
 +
===For Loops===
 +
A <code>for loop</code> will run for a set amount of times. You declare a variable then will count the current iteration it is on. A <code>for loop</code> has 3 parameters and they are: <code>initial value</code>, <code>final value</code>, and <code>step value</code>.
 +
 +
A <code>for loop</code> will continue to loop as long as your counter is less or equal to the <code>ending value</code>. The <code>for loop</code> will also stop if your counter is less than your <code>initial value</code>. For every iteration, your counter will increase by the <code>step value</code>. <syntaxhighlight lang="vb">
 +
for i = (initial value) to (ending value) step (step value)
 +
    statement
 +
next
 +
 +
'step value is optional and defaults to 1 when omitted
 +
for i = (initial value) to (ending value)
 +
  statement
 +
next
 +
</syntaxhighlight>
 +
 +
<br /><syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
dim i as integer
 +
for i = 0 to 8 step 2
 +
  call showMsg(i)
 +
next
 +
 +
' The messages displayed are: 0, 2, 4, 6, and 8
 +
</syntaxhighlight>
 +
 +
===Exit===
 +
An exit statement will terminate a loop of a script prematurely.
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
script name(myParam as double, return double)
+
'This works inside a pure, while, or until loop
   return param(myParam) + 1
+
exit do
 +
 
 +
'This works inside a for loop
 +
exit for
 +
 
 +
'This will force the game to stop immediately executing the script
 +
exit script
 +
</syntaxhighlight>
 +
 
 +
==Scripts==
 +
Teascript allows you to create <code>custom script</code> function inside your scripts. This allows you to simplify your code and build tools to expand your script in a more organized manner. There are two types of <code>custom scripts</code> that both work very similarly.
 +
 
 +
When setting up a <code>custom function</code> or <code>custom procedure</code>, all <code>scripts</code> and <code>parameters</code> names must follow '''variable naming standards''' with one exception. Script names must not contain numbers anywhere.
 +
 
 +
====Function====
 +
A <code>custom function</code> allows you to create your own custom functions that behave similarly to the <code>built-in functions</code> shown above. You can add your own <code>custom functions</code> to simplify code or add your very own mathematical functions. You can have as many <code>parameters</code> as you want. You must define the type of data and the return type as shown below. If no <code>return</code> is found, then by default it will return 0 or "" depending on the return type. A <code>custom function</code> must be defined at the bottom of the script.<syntaxhighlight lang="vb.net" line="1">
 +
' type must be double or string
 +
script functionName(param1 as type, param2 as type, ..., return type)
 +
  ' to access a parameter, just type the name
 +
  return value
 +
end script
 +
</syntaxhighlight><syntaxhighlight lang="vb">
 +
' === Example
 +
 
 +
dim x as integer = 5
 +
dim y as integer = 10
 +
dim z as integer
 +
 
 +
z = max(5, 10)
 +
' z returns 10
 +
 
 +
' This script returns the larger parameter
 +
script max(a as double, b as double, return double)
 +
  if a > b then return a
 +
   return b
 
end script
 
end script
 +
</syntaxhighlight>
 +
 +
====Procedure====
 +
A <code>custom procedure</code> are similar to <code>custom functions</code> except they do not have a return value. Use custom procedures to create instructions that you want to repeat together. You can have as many <code>parameters</code> as you want. You must define the type of data as shown below. A <code>custom procedure</code> must be defined at the bottom of the script.<syntaxhighlight lang="vb">
 +
' type must be double or string
 +
script procedureName(param1 as type, param2 as type, ...)
 +
 +
end script
 +
</syntaxhighlight><syntaxhighlight lang="vb" line="1">
 +
' === Example
 +
' This disables both types of jumps
 +
call setJumps(-1)
 +
 +
' This enables both types of jumps
 +
call setJumps(0)
 +
 +
script setJumps(x as double)
 +
  sysval(disablejump) = x
 +
  sysval(disablespinjump) = x
 +
end script
 +
</syntaxhighlight><br />
 +
==Oddities and Quirks==
 +
The following is a list of oddities that you may experience when using TeaScript
 +
 +
'''Dim Variables in If Statements'''
 +
 +
If you initialize a dim variable inside an if statement, it will have a buggy effect. This is a bug in Teascript's side.<syntaxhighlight lang="vb">
 +
' This is a bug
 +
if -1 = -1 then
 +
    dim i as double = 1
 +
    call sysshowmsg(i,0,0)
 +
    dim j as double = i - 2
 +
    dim k as double = j + i
 +
    call sysshowmsg(i,0,0)
 +
    call sysshowmsg(j,0,0)
 +
    call sysshowmsg(k,0,0)
 +
end if
 +
</syntaxhighlight>
 +
 +
 +
'''Procedure-Function Combo'''
 +
 +
When <code>calling</code> a <code>custom function</code> you can ignore the return value. This serves no practical purposes.<syntaxhighlight lang="vb">
 +
' Why would you ever do this?
 +
call max(5, 10)
 +
 +
script max(a as double, b as double, return double)
 +
  if a > b then return a
 +
  return b
 +
end script
 +
</syntaxhighlight>'''Negatives to a Non-Integer Power'''
 +
 +
<code>sqr(x)</code> is equivalent to <code>x^(0.5)</code>. Therefore <code>(-1)^(0.5)</code> results in a complex number with a imaginary component. Teascript does not offer complex numbers in its data types.<syntaxhighlight lang="vb">
 +
dim x as integer = -1
 +
dim y as integer
 +
 +
y = (-1)^(0.5) ' This returns an error when run.
 +
y = x^(0.5)    ' This does not error but will evaluate to 0
 +
</syntaxhighlight>'''Writing Double Quotation Marks'''<br>
 +
Since double quotation marks are reserved for defining string, you must use chr or chrW to write a double quotation mark inside a string.
 +
<syntaxhighlight lang="vb">
 +
str(myVar1) = chrW(34) '34 is the ID of the double quotation marks. (ID 34 works too in chr() too)
 +
 +
'You can define a variable as a quotation mark or call the quotation mark directly, both work the same
 +
str(myVar2) = "These are some "&str(myVar1)&"special"&chrW(34)&" marks"
 +
 +
'str(myVar2) is "These are some "special" marks"
 +
</syntaxhighlight>
 +
 +
'''> THESE PROBLEMS ARE FIXED in 1.4.5 <'''
 +
 +
'''Writing Decimal Numbers'''<br>
 +
When writing decimal number, you must include a number before the decimal point.
 +
<syntaxhighlight lang="vb">
 +
'Wrong
 +
v(myVar) = .1
 +
 +
'Correct
 +
v(myVar) = 0.1
 +
</syntaxhighlight>
 +
 +
 +
'''Writing negative numbers'''<br>
 +
When writing a negative number, make sure there are no other symbols beforehand (except parenthesis).
 +
<syntaxhighlight lang="vb">
 +
'Wrong (Teascript errors due to seeing * and - next to each other)
 +
v(myVar) = 5*-4
 +
 +
'Correct
 +
v(myVar) = 5*(-4)
 +
v(myVar) = -4*5
 
</syntaxhighlight>
 
</syntaxhighlight>

Revision as of 20:19, 23 December 2019

Data Types and Variables

User Variables

User variables can be access in the variable menu or by pressing ctrl+i. All of these variables must be created using this interface.

Doubles & Strings

By clicking the Add button in the variable interface you create a user variable.

You may also select if the variable is a local or global user variable. Local user variables can only exist in a single level and the value is reset every time the level begins. Global variables save the value per level and remembers the value even after quitting the game.

Variable Naming Standard

  • Names are not case sensitive.
  • Names must not contain spaces.
  • Names must be made using a combination of letters and numbers only.
  • Names must start with a letter

User variables work in an unusual way compared to other scripting languages. A user variable has two sides, a double and a string. There are different methods to access each side

' By creating a variable called "myVar" in the interface you can...
' === Access doubles
'Local
val(myVar) or v(myVar)

'Global
gval(myVar) or gv(myVar)

'Local Concatenation in TXTCreate and Event Messages
&val(myVar)

'Global Concatenation in TXTCreate and Event Messages
&gval(myVar)

' === Access strings
'Local
str(myVar)

'Global
gstr(myVar)

'Local Concatenation in TXTCreate and Event Messages
$val(myVar)

'Global Concatenation in TXTCreate and Event Messages
$gvl(myVar)


 1 ' === Example
 2 
 3 v(myVar) = 5
 4 str(myVar) = "Hello"
 5 
 6 v(myVar) = v(myVar) + 2
 7 str(myVar) =  str(myVar) & " World"
 8 
 9 ' v(myVar) now has the value of 7
10 ' str(myVar) now has the value of "Hello World"
11 ' Notice how a user variable simultaneously hold a double and a string at the same time. The double side does not interfere with the string side and vice versa.

Note how a user variable simultaneously can hold a double and a string.

Arrays

By clicking Add while holding shift in the variable interface you create a user array. Currently, user arrays can only contain double values. User arrays must first be initialized using the redim function before usage.

' By creating an array called "myArr" in the interface you can... 
' Initialize the array using redim 
' Read documentation on redim for more information
call redim(0, myArr, ARRAY_LENGHT) 
' Access value of an array at an index 
array(myArr(index))
' === Example
call redim(0, myArr, 3) 
array(myArr(1)) = 5 
array(myArr(2)) = 7 
array(myArr(3)) = array(myArr(1)) + array(myArr(2)) 
' The array now has the following values of [5, 7, 12]

Dim Variables

Dim variables are a different way of creating and interacting with variables compared to user variables. A dim variable can only have a single type of data that must be defined on creation. Variable naming standards are the same as user variables, except you may not use the same name of other existing functions and keywords. If a dim variable is initialized without a value, it defaults to 0 or "" depending on the type.

' You can initialize a variable 
dim varName as type

' You can initialize a variable with a defined value
dim varName as type = value

'Once initialized you just write the variable name to access it
varName
 1 ' === Example
 2 dim myInt as integer
 3 dim myLng as long
 4 dim myDbl as double = 5
 5 dim myStr as string = "Hello"
 6 
 7 myInt = myDbl*2
 8 myLng = myDbl*5
 9 myStr = myStr & " World"
10 
11 'myInt has the value of 10
12 'myLng has the value of 25
13 'myDbl has the value of 5
14 'myStr has the value of "Hello World"


Expressions

An expression is a line of code that evaluates to an answer. Something as simple as 1 + 1 is an expression. Teascript offers different tools to create diverse expressions that suit what you specifically need.

Operators

Mathematical Operators

Mathematical Symbols
Symbol Name Example
+ Addition
12 + 2 + 3 'returns 17
- Subtraction
12 - 2 - 3 'returns 7
* Multiplication
12*2*5 'returns 120
/ Division
'Note that division by 0 will crash SMBX 
12/2/5 'returns 1.2
\ Division with no remainder
'Note that division by 0 will crash SMBX
12\2\5 'returns 1
^ Power
'Note that 0^0 will return 1
12^2 'returns 144
mod Modulus
'Note that modulating by 0 will crash SMBX
12 mod 5 'returns 2
& Concatenation
"ABC" & ";" & "123" 'returns "ABC;123"
( ) Parenthesis
12*(2 + 5) 'returns 84

Comparing Operators

Note that all comparative operators require both sides use the same data type. You can compare numbers with other numbers and strings with other strings, but you cannot compare numbers with strings.

Comparitive Operators
Symbol Name Description
= Equal Numbers Returns -1 if both sides are equal, otherwise 0
Strings Returns -1 if both sides are equal, otherwise 0
<> Not equal Numbers Returns -1 if both sides are not equal, otherwise 0
Strings Returns -1 if both sides are not equal, otherwise 0
> Grater than Numbers Returns -1 if the value on the left is larger, otherwise 0
Strings Unknown pattern
< Less than Numbers Returns -1 if the value on the left is smaller, otherwise 0
Strings Unknown pattern
>= Greater than or equal Numbers Returns -1 if the value on the left is larger or equal, otherwise 0
Strings Unknown pattern
<= Less than or equal Numbers Returns -1 if the value on the left is smaller or equal, otherwise 0
Strings Unknown pattern
like Like Numbers Not compatible, crashes the game
Strings https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/operators/like-operator

Logical Operators

Logical operators only work on numbers. They are commonly used with -1 and 0 to represent true and false respectively. Other numbers can be used but it may yield different patterns.

Logical Operators
P Q not P P and Q P or Q P xor Q P eqv Q P imp Q
0 0 -1 0 0 0 -1 -1
0 -1 -1 0 -1 -1 0 -1
-1 0 0 0 -1 -1 0 0
-1 -1 0 -1 -1 0 -1 -1


Special Values

These special values behave like numbers.

Special Values
Name Value
pi 3.141592654
e 2.71828182
rnd A random number between 0 and 1. The value changes every time the variable is accessed.

Built-in Functions

Functions are powerful tools that allow you to simplify and expand the flexibility of your scripts. To access a function, you write the function name and in parenthesis write the parameters separated by commas. You can put functions inside an expression just as it were a regular number or string.

For a list of custom functions created by the community check here.

myFunc(param1, param2, ..., paramN)
1 ' === Example
2 dim x as integer = -5
3 dim y as integer
4 y = abs(x) + 1  
5 ' x returns -5; y returns 6
6 ' Note how the abs() function is used

These are the the mathematical functions provided in TeaScript.

Parameters can be numbers, strings, and arrays.

Functions
Name and Parameters Return Type Description and Example
abs(x) Number Returns the absolute value of a number
abs(-3) 'returns 3
exp(x) Number Returns the number to the power of the e constant
exp(5) 'returns e^5
log(x) Number Returns the log of the number with a base of e
log(e) 'returns 1
sgn(x) Number Returns the sign of the number (1, -1, or 0)
sgn(10)  'returns 1
sgn(0)   'returns 0
sgn(-10) 'returns -1
int(x) Number Returns the number rounded up. Similar to the common ceiling function
int(2.1) 'returns 3
fix(x) Number Returns the number rounded down. Similar to the common floor function
fix(2.9) 'returns 2
sqr(x) Number Returns the square root of a number
sqr(9) 'returns 3
sin(x) Number Returns the sine of the number. Uses radians
sin(pi) 'returns 0
cos(x) Number Returns the cosine of the number. Uses radians
cos(pi) 'returns 1
tan(x) Number Returns the tangent of the number Uses radians
tan(pi/4) 'returns 1
atn(x) Number Returns the inverse tangent of the number. Uses radians
atn(1) 'returns pi/4
getangle(x, y) Number Returns the angle (from 0 to 1) formed between the triangle. Similar to the common atan2 function.
getangle(1, 0)  'returns 0
getangle(1, 1)  'returns .125
getangle(0, 1)  'returns .25
getangle(-1, 0) 'returns 0.5
getangle(0, -1) 'returns 0.75
rgba(red, green, blue, alpha) Number Returns an SMBX color value. Parameters must be between 0 and 255
rgba(255, 255, 255, 255) 'returns -1
round(x, decimal place) Number Returns the number rounded
round(1.3456, 2) 'returns 1.35
len(txt) Number Returns the length of the text
 len("ABC") 'returns 3
left(txt, len) String Returns the text cropped from the string inputted. The crop begins from the start and ends with the length specified.
left("Hello", 2) ' Returns "He"
right(txt, len) String Returns the text cropped from the string inputted. The crop ends from the end and begins with the length specified.
right("Hello", 3) ' Returns "llo"
mid(txt, start, len) String Returns the text cropped at the specified start and has the specified length provided.
mid("Hello", 2, 3) ' Returns "ell"
asc(char) Number Returns the ANSI code. It will use the first character if more than one is passed
asc("A")  ' Returns 65
chr(code) String Returns a string using the ANSI code. Accepts 0-255
chr(65)  ' Returns "A"
ascw(char) Number Returns the unicode code. It will use the first character if more than one is passed
ascw("A")  ' Returns 65
chrw(code) String Returns a string using the unicode code. Accepts 0-65535
chrw(65) ' Returns "A"
cstr(num) String Converts the number to a string
cstr(1)  ' Returns "1"
cdbl(txt) Number Converts the string into a number
cdbl("1")  ' Returns 1
instr(start, txt, search) Number To return the point of the first appearance of a given string in another string.


start To specify the start point of the search
txt The original string


search The string to be searched
instr(1, "abcde", "b") ' Returns 2
ubound(array) Number Returns the length of the array
call redim(0, myArr, 3)
ubound(myArr) ' Returns 3

Control Flow

When a script is run in TeaScript it will start reading the script from top to bottom, left to right. It will read and execute the code in that order. the following is a list of ways to customize and manipulate what code gets executed in your scripts.

Declarations

A declaration is when you set a value to a variable. This applies to user variables, dim variables, and other values.

' Basic form of a declaration
' The variable is written in the left
' The value you want set is written in the right
variable = value
1 ' === Examples
2 v(myVar) = 5
3 dim x as integer
4 dim y as double = 10
5 sysval(score) = 0
6 x = v(myVar) + 10
7 NPC(1).xsp = 0

Conditions

Conditions represent true and false. In Teascript, -1 and 0 represents true and false. Any number that is not 0 may also represent true, but use -1 and 0 for consistency reasons.

 1 ' === Examples
 2 
 3 -1  ' Represents True
 4 0   ' Represents False
 5 5   ' Represents True (because non-zero numbers represent true)
 6 
 7 dim w as integer = -1
 8 dim x as integer = 5
 9 dim y as integer = 5
10 dim z as integer = 0
11 
12 w    ' Represents True (because w has the value of -1)
13 x    ' Represents True (because x has a value of a non-zero number)
14 y    ' Represents True (because y has a value of a non-zero number)
15 z    ' Represents False (because z has a value of 0)
16 
17 z - 1    ' Represent True (because 0 - 1 = -1)
18 w + 1    ' Represent False (because -1 + 1 = 0)
19 
20 ' Using logical operators 
21 not w          ' Represent False
22 not (y and z)  ' Represents True
23 w or z         ' Represents True

If Statements

The if statement is a basic but useful statement. It has one parameter being a condition.

' Basic if statement
if conditon then
  statement
end if

' Shortcut if statement
if condition then statement

' If statement using one elseif and an else statement
if conditon then
  statement
elseif condition then
  statement
...    ' You can have as many elseif as you want 
else
  statement
end if

When TeaScript reads an if statement it will check each condition from top to bottom until it reaches a condition that is true. When it reaches a condition that is true, it will execute the statements inside and continue the code after the entire if statement. This means that conditions written on the top will have priority over those conditions in the bottom.

The else is special since it does not require any conditions. An else must be written in the bottom after all other elseif statements (if there are any). The code inside the else will only run if every other condition in the if and elseif statements evaluated to false.

 1 ' === Example
 2 dim x as integer = 0
 3 dim y as integer = -1
 4 dim z as integer = -1
 5 
 6 ' Since (x and y) evaluates to 0, this statement is not run.
 7 if x and y then z = 0
 8 
 9 ' Since (x and z) evaluates to 0, this statement is not run.
10 if x and z then
11   y = 0
12 
13 ' Since (y) evaluates to -1, this statement is run.
14 elseif y then
15   x = -1
16 
17 ' Since the previous elseif has priority and only one statement can be run, this statement is not run
18 else
19   z = -1
20 end if

Select Case Statements

Select Case lets you easily organize the control flow based on a value. It has one parameter being a value.

select case value
  case -1
    statement ' Will run if value is exactly -1
  case 0 to 1
    statement ' Will run if value is between (inclusive) 0 and 1
  case is < -1
    statement ' Will run if value is less than negative one
  case 2, 3, 4
    statement ' Will run if value is exactly 2, 3 or 4
  case "example"
    statement ' Will run if value is exactly "example".
  case else
    statement ' Will run if value does not match any of the other conditions
end select

Select case at its core is similar to various if statements and behaves similarly to the common "switch" statement in other languages. It will read the value that is passed and executes the first code in which the value matches. It will read the cases from top to bottom giving priority to cases at the top.

The to keyword can be used when checking for a case.

  • Numbers Will be true if the value is between (inclusive) the two numbers provided.
  • Strings Unknown pattern

The is keyword can be used to make comparisons to the value. It can be used with the <, >, <=, or >= logical operators.

You can use commas to check for multiple cases at once. The commas behave similarly to an or logical operator. The case will go through if it matches with any of the cases.

With Statements

With statements are useful to read or write on multiple properties of an object. An object can be for example an NPC, Block, or BGO. Check the classes section for more information on SMBX Objects. You can acess all of the properties by typing a . followed by the property name.

with object
  .property_name
end with


' === Example
with NPC(1)
  .x = 12345
  .y = 54321
  .forecolor = rgba(10, 60, 60, 255)
  v(myVar) = .ysp
end with

' This is equivalent to:
  NPC(1).x = 12345
  NPC(1).y = 54321
  NPC(1).forecolor = rgba(10, 60, 60, 255)
  v(myVar) = NPC(1).ysp

Goto

Using goto will force the script to jump to a specific line to a specific label. The label name must be followed by :. Goto does not work inside with statements.

Example:

goto Example


GoSub

Using gosub will force the script to jump to a specific line to a specific label. Teascript will remember where the jump happened and can be returned by using return.The label name must be followed by :. Gosub does not work inside with statements.

Example:

gosub Example
return  ' When it reaches this line, it will return back to the first line
' === Example
gosub Example
call showMsg("b")

Example:
call showMsg("a")
return 
' Take note of the order the messages are shown

Loops

A loop allows you to run a piece of code multiple times. Teascript is very flexible in the type of loops you can create.

It is important to note that you should avoid an infinite loop. Creating an infinite loop will freeze the game. Make sure to either have a sleep function (if the script was called by an event) or an exit.

Pure Loops

A pure loop is a very simple and basic form of a loop. It will run indefinitely.

'Pure loop:
do
  statement
loop
1 ' === Example
2 ' Calling this script once will run the code every tick
3 do
4   statement
5   call sleep(1)
6 loop

While Loops

A while loop will continue the loop while the condition is true. You can set up a while loop in 2 different ways. The difference is by when the loop checks its condition. If you place the while at the bottom, you guarantee then code will be run at least once.

do while condition
  statement
loop

do
  statement
loop while condition
 1 ' === Example
 2 dim x as integer
 3 
 4 x = 0
 5 do while x < 5
 6   x = x + 1
 7 loop
 8 
 9 x = 0
10 do 
11   x = x + 1
12 loop while x < 5
13 
14 ' Both loops ran 5 times

Until Loops

An until loop will continue the loop until the condition is true. You can set up an until loop in 2 different ways. The difference is by when the loop checks its condition. If you place the until at the bottom, you guarantee then code will be run at least once.

do until condition
  statement
loop

do
  statement
loop until condition
 1 ' === Example
 2 dim x as integer
 3 
 4 x = 0
 5 do until x = 5
 6   x = x + 1
 7 loop
 8 
 9 x = 0
10 do 
11   x = x + 1
12 loop until x = 5
13 
14 ' Both loops ran 5 times

For Loops

A for loop will run for a set amount of times. You declare a variable then will count the current iteration it is on. A for loop has 3 parameters and they are: initial value, final value, and step value.

A for loop will continue to loop as long as your counter is less or equal to the ending value. The for loop will also stop if your counter is less than your initial value. For every iteration, your counter will increase by the step value.

for i = (initial value) to (ending value) step (step value)
    statement
next

'step value is optional and defaults to 1 when omitted
for i = (initial value) to (ending value)
  statement
next


1 ' === Example
2 dim i as integer
3 for i = 0 to 8 step 2
4   call showMsg(i)
5 next
6 
7 ' The messages displayed are: 0, 2, 4, 6, and 8

Exit

An exit statement will terminate a loop of a script prematurely.

'This works inside a pure, while, or until loop
exit do

'This works inside a for loop
exit for

'This will force the game to stop immediately executing the script
exit script

Scripts

Teascript allows you to create custom script function inside your scripts. This allows you to simplify your code and build tools to expand your script in a more organized manner. There are two types of custom scripts that both work very similarly.

When setting up a custom function or custom procedure, all scripts and parameters names must follow variable naming standards with one exception. Script names must not contain numbers anywhere.

Function

A custom function allows you to create your own custom functions that behave similarly to the built-in functions shown above. You can add your own custom functions to simplify code or add your very own mathematical functions. You can have as many parameters as you want. You must define the type of data and the return type as shown below. If no return is found, then by default it will return 0 or "" depending on the return type. A custom function must be defined at the bottom of the script.

1 ' type must be double or string
2 script functionName(param1 as type, param2 as type, ..., return type)
3   ' to access a parameter, just type the name
4   return value
5 end script
' === Example

dim x as integer = 5
dim y as integer = 10
dim z as integer

z = max(5, 10)
' z returns 10

' This script returns the larger parameter
script max(a as double, b as double, return double)
  if a > b then return a
  return b
end script

Procedure

A custom procedure are similar to custom functions except they do not have a return value. Use custom procedures to create instructions that you want to repeat together. You can have as many parameters as you want. You must define the type of data as shown below. A custom procedure must be defined at the bottom of the script.

' type must be double or string
script procedureName(param1 as type, param2 as type, ...)

end script
 1 ' === Example
 2 ' This disables both types of jumps
 3 call setJumps(-1)
 4 
 5 ' This enables both types of jumps
 6 call setJumps(0)
 7 
 8 script setJumps(x as double)
 9   sysval(disablejump) = x
10   sysval(disablespinjump) = x
11 end script


Oddities and Quirks

The following is a list of oddities that you may experience when using TeaScript

Dim Variables in If Statements

If you initialize a dim variable inside an if statement, it will have a buggy effect. This is a bug in Teascript's side.

' This is a bug
if -1 = -1 then
    dim i as double = 1
    call sysshowmsg(i,0,0)
    dim j as double = i - 2
    dim k as double = j + i
    call sysshowmsg(i,0,0)
    call sysshowmsg(j,0,0)
    call sysshowmsg(k,0,0)
end if


Procedure-Function Combo

When calling a custom function you can ignore the return value. This serves no practical purposes.

' Why would you ever do this?
call max(5, 10)

script max(a as double, b as double, return double)
  if a > b then return a
  return b
end script

Negatives to a Non-Integer Power sqr(x) is equivalent to x^(0.5). Therefore (-1)^(0.5) results in a complex number with a imaginary component. Teascript does not offer complex numbers in its data types.

dim x as integer = -1
dim y as integer

y = (-1)^(0.5) ' This returns an error when run.
y = x^(0.5)    ' This does not error but will evaluate to 0

Writing Double Quotation Marks

Since double quotation marks are reserved for defining string, you must use chr or chrW to write a double quotation mark inside a string.

str(myVar1) = chrW(34) '34 is the ID of the double quotation marks. (ID 34 works too in chr() too)

'You can define a variable as a quotation mark or call the quotation mark directly, both work the same
str(myVar2) = "These are some "&str(myVar1)&"special"&chrW(34)&" marks"

'str(myVar2) is "These are some "special" marks"

> THESE PROBLEMS ARE FIXED in 1.4.5 <

Writing Decimal Numbers
When writing decimal number, you must include a number before the decimal point.

'Wrong
v(myVar) = .1

'Correct
v(myVar) = 0.1


Writing negative numbers
When writing a negative number, make sure there are no other symbols beforehand (except parenthesis).

'Wrong (Teascript errors due to seeing * and - next to each other)
v(myVar) = 5*-4

'Correct
v(myVar) = 5*(-4)
v(myVar) = -4*5