TeaScript Syntax

WIP documentation of TeaScript. Feel free to add any information necessary below.

Data Types and Variables

Teascript only offers two data types. These are doubles and strings.

Double

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:

'Local
val(myVar) or v(myVar)

'Global
gval(myVar) or gv(myVar)

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

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

String

Strings are represented as text. You can create a string by surrounding text with quotation marks. "Example"

'Local
str(myVar)

'Global
gstr(myVar)

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

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

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.

Variable Usage

Variables can be manipulated in the following ways.

All variables must be created using the variable interface (found using ctrl+i in the editor)

• 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.
• 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.

'To set and get the value of a variable
'(myVar1 and myVar2 are local variables)

v(myVar1) = 1
v(myVar2) = v(myVar1) + 1
v(myVar1) = 5
'myVar1 is 5 and myVar2 is 2

str(myVar1) = "Hello"
str(myVar1) = str(myVar1)&", how are you?" 
'myVar1 is "Hello, how are you?"

Variable Naming Standard

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

Expressions

Mathematical Symbols

Mathematical Symbols
Symbol	Name	Example
+	Addition	12 + 3 + 5 'returns 19
-	Subtraction	12 - 3 - 5 'returns 4
*	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 mudulating by 0 will crash SMBX 12 mod 5 'returns 2
&	Concatenation	"ABC"&";"&"123" 'returns "ABC;123"
( )	Parenthesis	12*(2 + 5) 'returns 84

Mathematical Functions

These are the mathmatical function provided.
Parameters with #param mean that the parameter is a double.
Parameters with "param" mean that the parameter is a string.

Functions
Name and Parameters	Return Type	Description and Example
abs(#num)	Double	Returns the absolute value of a number abs(-3) 'returns 3
exp(#num)	Double	Returns the number to the power of the e constant exp(5) 'returns e^5
log(#num)	Double	Returns the log of the number with a base of e log(e) 'returns 1
sgn(#num)	Double	Returns the sign of the number (1, -1, or 0) sgn(10) 'returns 1 sgn(0) 'returns 0
int(#num)	Double	Returns the number rounded up. Similar to the common ceiling function int(2.1) 'returns 3
fix(#num)	Double	Returns the number rounded down. Similar to the common floor function fix(2.9) 'returns 2
sqr(#num)	Double	Returns the square root of a number sqr(9) 'returns 3
sin(#num)	Double	Returns the sine of the number. Uses radians sin(pi) 'returns 0
cos(#num)	Double	Returns the cosine of the number. Uses radians cos(pi) 'returns 1
tan(#num)	Double	Returns the tangent of the number Uses radians tan(pi/4) 'returns 1
atn(#num)	Double	Returns the inverse tangent of the number. Uses radians atn(1) 'returns pi/4
getangle(#x, #y)	Double	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)	Double	Returns an SMBX color value. Parameters must be between 0 and 255 rgba(255, 255, 255, 255) 'returns -1
round(#num, #decimal_place)	Double	Returns the number rounded decimal_place The decimal place rounded to round(1.3456, 2) 'returns 1.35
len("txt")	Double	Returns the length of the text len("ABC") 'returns 3
left("txt", #len)	String	Returns the text cropped starting with the length provided. The crop begins from the start
right("txt", #len)	String	Returns the text cropped starting with the length provided. The crop finished with the end
mid("txt", #len)	String	Returns the text cropped starting with the length provided. The crop begins with the number provided.
replace("txt", "search", "replacement", #start, #count, #case_insensitive)	String	Replaces a part of the text with a new one. start Where in the txt should the search start count The number of replacements. Set to -1 to disable case_insensitive Set to 1 to make the search case-insensitive, otherwise use 0
asc("character")	Double	Returns the ANSI code. It will use the first character if more than one is passed
chr(#code)	String	Returns a string using the ANSI code. Accepts 0-255
ascw("character")	Double	Returns the unicode code. It will use the first character if more than one is passed
chrw(#code)	String	Returns a string using the unicode code. Accepts 0-65535
cstr(#num)	String	Converts the number to a string
cdbl("txt")	Double	Converts the string into a number
instr(#start, "string1", "string2")	Double	To return the point of the first appearance of a given string in another string. start To specify the start point of the search string1 The original string string2 The string to be searched

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

Comparing and Logical Operators

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

Comparitive Operators
Symbol	Name	Description
=	Equal	Doubles Returns -1 if both sides are equal, otherwise 0
		Strings Returns -1 if both sides are equal, otherwise 0
<>	Not equal	Doubles Returns -1 if both sides are not equal, otherwise 0
		Strings Returns -1 if both sides are not equal, otherwise 0
>	Grater than	Doubles Returns -1 if the value on the left is larger, otherwise 0
		Strings Unknown pattern
<	Less than	Doubles Returns -1 if the value on the left is smaller, otherwise 0
		Strings Unknown pattern
>=	Greater than or equal	Doubles Returns -1 if the value on the left is larger or equal, otherwise 0
		Strings Unknown pattern
<=	Less than or equal	Doubles Returns -1 if the value on the left is smaller or equal, otherwise 0
		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.

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

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.

If statements

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

'Basic if statement
if conditon then
  'code that should run if the condition is "true"
end if

'If statement using one elseif and an else statements
if conditon then
  'code that should run if the condition is "true"
elseif condition then
  'code that should run if the second condition is "true"
else
  'code that should run if all the other conditions are "false"
end if

When TeaScript reads an if statements 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 code that is inside that statement and continue the code after the entire "if statement". This means that conditions written on the top will have priority over those 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"s statements (if there are any). The code inside the "else" will only run if every other "if" and "elseif" had "false" in their conditions.

It is important to note that TeaScript does not have booleans (true and false values). Instead, 0 is considered to be false and any other number is considered to be true. Strings are not accepted as conditions, only doubles are accepted.

Select Case

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

select case value
  case 0 to 1
    'Code that should pass if the value is between (inclusive) 0 and 1.
  case 2
    'Code that should pass if the value is exactly 2.
  case "example"
    'Script that should pass if the value is exactly "example".
  case else
    'Code that should pass if the value does not match any of the other conditions.
end select

"Select case" at its core is similar to various "if statement"s and behaves similar to the common "switch" statement. It will read the value that is passed and only executes the 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.

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

For Loop

A "for loop" is a loop that will run a certain amount of times. It has three parameters: "initial_value", "ending_value", and "setp_value".

for v(myCounter) = initial_value to ending_value step step_value
  'code that will be executed multiple times
next

'step_value is optional and if omitted the loop will behave with a step of 1
for v(myCounter) = initial_value to ending_value
  'code that will be executed multiple times
next

'The loop will stop and skip everything until the "next" keyword
exit for

An already existing variable must be set to "initial_value". The variable will start the loop with this and increment by the value set in "step_value". You can still manipulate the variable while inside the "for loop".

The loop will continue going until the variable is larger or equal to "ending_value" when the script reaches "next". The loop will also stop if the variable is less than the "initial value" when it reaches next. Once the loop stops it will continue reading the script.

When TeaScript reads an "exit for" while inside a "for loop" it will immediately skip to the next keyword and resume the script.

It is important to note that you should avoid an infinite loop. Make sure to either have a "sleep()" function or an "exit for" if you set up a for loop to go indefinitely.

Pure Loop

There are three different versions of do loops: While loops, Until Loops, and Pure Loops.

'Pure loop:
do
  'this loop will run infinitely until it hits an "exit do" statement
loop

'While Loop:
do while [condition]
  'this loop will run as long as the condition returns true
loop while [condition]

'Until Loop:
do until [condition]
  'this loop will run until the condition returns true
loop until [condition]

Loop Until

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.

Goto

Using goto it will force the script to jump to the specified line using a label.

Example:
[statements]
goto Example

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.

Script

Using the script keyword, it allows you to make a function in Teascript. Example:

script name(myParam as double, return double)
  return param(myParam) + 1
end script