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 known as 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:

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

Other
TeaScript.vbs also lists SMBX Events, 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 through View > Variables or Ctrl+i.)


 * 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/exit or when you quit the episode.

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.

Mathematical Functions
These are the mathematical functions provided. Parameters with #param mean that the parameter is a double. Parameters with "param" mean that the parameter is a string.

Special Values
These special values behave like numbers.

Comparing Operators
Note that all comparative operators require 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)

Logical Operators
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.

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 "condition". 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" at its core is similar to various "if statement"s and behaves similarly to the common "switch" statement in other languages. 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

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

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

With Statements
With statements are useful to set multiple statements to a given object. Object means an object of the game. Here's an example:

Goto
Using goto will force the script to jump to a specific line using a label. 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, there must not be two labels with the same name and there should not be goto statements inside "with" statements either (meaning you can't use them when scripting an npc).

GoSub
Gosub statements are very similar to goto ones, but there is a noticeable difference.

While goto statements will simply jump into a given line, gosub statement can keep track of where it came from. This means the program won't search through the whole stack to find a given label, instead it will do from the last "return" found. Gosub statements must follow the same rules as goto statements.

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

Pure
A "pure loop" is a very simple and basic form of a loop.

The loop will run indefinitely.

While
The game will repeat executing statements inside do statement until condition returns true. The condition be checked at the beginning or either at the end of the loop.

In this example the game checks the condition at the beginning, meaning if condition is false the game won't execute statements inside "do".

In this example the condition is checked at the end of the loop. This means that is condition is false the game will execute anyway statements inside "do" until it reaches "while" and verify the condition.

Until
The game will repeat executing statements inside do statement until condition returns false. You can also make the game check the condition at the beginning or at the end of the loop like with "while" statements.

For
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".

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.

Exit
An exit will terminate a loop and skip the code after it until it reaches the "loop" or "next" keyword (Depending on what loop it was used on).

Script
Using the script keyword, it allows you to make useful custom functions and procedures in Teascript.

When setting up a script, all parameters must be defined by name and type as shown below. You may have as many parameters as needed. Note that return is optional. All script and parameter naming standards are similar to variable naming standards with one exception. Script names must not contain numbers. Unlike common functions in other languages, TeaScript cannot do the following:


 * Set the value of passed down parameters. All parameters passed down are read-only.
 * Create recursive scripts. You cannot call a script within itself.

The "return" keyword will only in functions. If a function has no return, then it will return 0 or "" (based on the return type that was specified. SMBX will error if you include a return in a procedure.

It is important to note that when called, procedures must have the "call" keyword. This also applies to a function if you do not read the returned value.

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

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.

> THESE PROBLEMS ARE FIXED in 1.4.5 <

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

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