MiniScript is a modern scripting language designed to be clean, simple, and easy to learn. It was designed from the ground up by borrowing only the best ideas from other languages such as Python, Lua, Basic, and C#. If you know pretty much any other programming language, you’ll pick up MiniScript almost immediately. And if you’ve never written a line of code in your life, don’t panic! MiniScript is the friendliest and most fun way to get started. It’s much easier than you probably expect. Important: MiniScript is designed as an embedded programming language. That means you will usually use it inside some other program, such as a video game. You should find another document that describes how to access and use MiniScript within that other program. This document only describes the MiniScript language itself, and the intrinsic functions that are common to most MiniScript applications.

Let’s jump right in with an example, to see what MiniScript code looks like.

Clean, Clear Syntax

s = "Spam"
while s.len < 50
s = s + ", spam"
end while
print s + " and spam!"

Each statement in MiniScript normally occurs on a single line by itself. Notice that there are no semicolons, curly braces, or other markers at the end of a line.

However, there is one exception: if you want to join multiple statements on one line, just to make your code more compact, you can do this by separating the statements with a semicolon. The following code is ugly, but legal.

s = "Spam"; while s.len < 50; s = s + ", spam"; end while
print s + " and spam!"

In practice this feature is rarely used, but it’s there if you need it.

Code Blocks

If you’re used to C-derived languages (such as C, C++, C#, etc.), then you’re used to seeing curly braces around blocks of code. MiniScript doesn’t roll that way; code blocks always begin with a keyword (if, for, while, or function) and end with a matching end statement (end if, end for, end while, or end function).

Whitespace and Indentation

You can insert spaces and tabs into your code pretty much wherever you want. You can’t break up an identifier or keyword (pr int is not the same as print), nor omit a space between two identifiers or keywords (end if is correct, but endif would not work). And of course spaces within quotation marks go into your string exactly as you would expect. But between numbers, operators, etc., you can include extra spaces however you like. The following two lines are exactly the same, as far as MiniScript is concerned.

x=4*10+2
x = 4 * 10 + 2

To make the structure of code more readable, it’s traditional to indent the lines within a code block by either a tab or two spaces. But it’s not required. MiniScript doesn’t care how or whether you indent your code, so do whatever works best for you.

Breaking Long Lines

Unlike C-derived languages, there are no semicolons or other funny punctuation at the end of each line to let the computer know that the statement is over. Instead, the line break alone is enough to signal that. But what if you need to enter a statement longer than one line? MiniScript will recognize that a statement is incomplete, and continues on the next line, if the last token (before any comment — see below) is an open parenthesis, square bracket, or brace; or a comma, or any binary operator (such as +, *, and so on). So, for example, you could do:

speech = ["Four score and seven years ago our fathers",
"brought forth on this continent, a new nation, conceived",
"in Liberty, and dedicated to the proposition that all",
"men are created equal."]

That’s four lines, but only one statement as far as MiniScript is concerned. That’s because the first three lines each ends with a comma, which tells MiniScript that more is coming.

Comments

Comments are little notes you leave for yourself, or other humans reading your code. They are completely ignored by MiniScript. Comments begin with two slashes, and extend to the end of a line. So you can put a comment either on a line by itself, or after a statement.

// How many roads must a man walk down?
x = 6*7 // forty-two

Just like indentation, comments are never required… but they’re probably a good idea!

Use of Parentheses

Parentheses in MiniScript have only three uses:

1. Use them to group math operations in the order you want them, just as in algebra.
   x = (2+4)7 // this is different from 2+47
2. Use them around the arguments in a function call, except when the function call is the entire statement.
   print cos(0) // parens needed; cannot just say: print cos 0
3. Use them when declaring a function (see the Functions chapter).

Since other languages often require parentheses in lots of other silly places, it’s worth pointing out where parentheses are not used in MiniScript. First, don’t put parentheses around the condition of an if or while statement (more on these later). Second, parentheses are not needed (and should be omitted) when calling a function without any arguments. For example, there is a time function that gets the number of seconds since the program began. It doesn’t need any arguments, so you can invoke it without parentheses.

x = time

Finally, as mentioned above, you don’t need parentheses around the arguments of a function that is the very first thing on a statement. The following example prints ten numbers, waiting one second each, and then prints a message. Notice how we’re calling print and wait without any parentheses. But the range call, because it has arguments and is used as part of a larger statement, does need them.

for i in range(10, 1)
print i
wait
end for
print "Boom!"

Local and Global Variables

A variable is a word (also called an identifier) associated with a value. Think of variables as little boxes that you can store data in. You create a variable simply by assigning a value to it, as in many of the examples we’ve already seen.

x = 42

This line creates a variable called x, if it didn’t exist already, and stores 42 in it. This replaces the previous value of x, if any.

Variables in MiniScript are dynamically typed; that is, you can assign any type of data (see the chapter on Data Types) to any variable.

Variables are always local in scope. That means that a variable called “x” inside one function has nothing at all to do with another variable called “x” in another function; each variable is scoped (restricted) to the current function executing at the time of the assignment.

However, MiniScript also supports code outside of any function, as in all the examples we’ve seen so far. In this context, local and global variables are the same. In other words, assigning 42 to x outside of a function creates a global variable called x. Such global variables may be accessed from any context.

Note that when a context has a local variable of the same name as a global, an identifier will always resolve to the local variable first. Similarly, a simple assignment statement within a function will always create a local variable, rather than a global one. In cases where you really need to access the global variable instead, there is a globals object that provides this access. (See the Intrinsic Functions chapter for more detail on globals.)

demo = function()
print x // prints the global x (40)
x = 2 // creates a local ‘x’ with a value of 2
print x // prints the local x (2)
print globals.x // prints the global x again (40)
globals.x = 42 // reassigns the global x
print x // still the local value (2)
print globals.x // prints the new global value (42)
end function
x = 40 // creates a global ‘x’ with a value of 40
demo // invokes the function above

Overuse of global variables can sometimes lead to tricky bugs, so it’s best to use them sparingly and rely on local variables as much as possible. MiniScript is designed so that this good practice is what happens naturally.

MiniScript is Case-Sensitive

Uppercase and lowercase matters in MiniScript. The print intrinsic function must be typed exactly print, and not Print, PRINT, or any other variation. The same applies to any variables, functions, or classes you define.

While how you use case in your own identifiers is up to you, a common convention is to capitalize classes (e.g. Shape), but use lowercase for variables. Thus the following would be a perfectly sensible bit of code.

shape = new Shape // create a Shape object called shape

While we’re on the subject of conventions, in most cases you should avoid starting any global variables or function names with an underscore. Identifiers starting with an underscore are often used by the host environment for special “under the hood” code, and name collisions there could cause problems.