Spellscript Tutorial

Revision as of 05:26, 9 March 2013

This is an informal guide on how to get started creating Spellscript scripts in Minecraft. This guide will assume you're an absolute beginner to programming, and will do its best to not only explain the syntax of Spellscript, but give you a solid introduction to the concepts behind programming as well (you'll need them to make awesome scripts!)

See Spellscript for a general language reference-- otherwise, read on...

Your First Spellscript Script

Go ahead and start Minecraft with the console open (instructions), then go ahead and create a new single player world in Creative Mode. Now, place a Spellscript-Block wherever you please, and a lever right next to it-- you can find both in the Creative inventory. Once placed, open up the Spellscript Editor by right-clicking on the block. By default, it's name will be "Untitled Spellscript-Block", and it's content will be "pass" (a statement which equates to "Do nothing"). For your first script, we're going to print "Hello world!" to the command line! Simply replace "pass" with the following:

print "Hello world!"

Now press ctrl+enter, and verify the script is compiling. Now press escape, yank on the lever, and voila! Was "Hello world!" printed to your console? Great, you've created your first Spellscript script! Easy peasy. This is called a "print" statement, and simply prints the expression to its right to the terminal.

Another Example, Followed by Explanation

Now let's try something a bit more complicated:

string left = "Hello"
string right = "world!"

print left + " " + right

Go ahead and recompile it and yank the lever to make sure its working; it should have printed the exact same thing to the console. The difference is, we separated the string into three parts using two variables (left and right) and one literal (" "), then stuck them together with the '+' operator.

Order of Execution

In many programming languages (Spellscript included), statements are executed from top to bottom-- this means that order is important. In programmer jargon, this means that Spellscript is an imperative programming language. To elaborate on the above example: first, left is given the value "Hello", then right is given the value "world!", and then finally, the variables are combined and the result is printed to the console. If the top two lines of code were placed below the print statement, the program would have failed to compile, since as far as the print statement would know, the variables left and right wouldn't exist yet!

Variables and State

Next on the explanation agenda are variables, a very important concept in programming-- they allow your scripts to have "state". In other words, the value stored in a variable can change (hence the name), which can in turn affect the execution of your script.

A variable is declared like <type> <name>, and its valued is changed with the assignment operator, =, like so:

string left
left = "Hello"

int number
number = 3

The two may be combined, as in the original script, to both declare and assign to the variable in one statement:

int anotherNumber = 200

Here's a simple example to demonstrate how a variable can change:

int number = 0
print number

number = 7
print number

number = 234
print number

If put in a Spellscript-block, the above would have printed "0", "7" and then "234" to the console.

The While Loop

Combined with control-statements (such as the while loop), variables allow you to do truly powerful and creative things. Consider the following:

int i = 0

while i < 10:
    print i
    i = i + 1

This prints the numbers 0 though 9 to the console. How? Let's step through it.

First, we create i and set it to 0. We then compare it to 10: if it's less, we print i, increment it by 1, then go back to the comparison step-- otherwise we cease looping. Intuitively, this process will repeat until i equals 10, at which point we exit the loop and hit the end of the script.

Be careful using the while loop: if the comparison always evaluates to True, you'll be stuck in the loop indefinitely and have to force-quit Minecraft! We'll talk about a safer construct next (not to dissuade you from the while loop's utility!)

The For Loop

Iterating Over a Range of Integers

Incidentally, the for loop can be used as a shorthand version of the entire previous construct, like so:

for int i in 0 to 10:
    print i

We call this "iteration" over the integers 0 through 9. Just like the above example, it creates a variable i, sets it to 0, then executes the inner block of code and increments i by 1 repeatedly, until i equals 10.

We can make the above example even shorter-- if we omit the first bound, the for loop will assume a first bound of 0. The following will print the exact same thing as above:

for int i in 10:
    print i

The for loop is your friend-- be good to it and it will be good to you!

Iterating Over a List

Another kind of iteration the for loop is capable of is list iteration; that is, rather than incrementing an integer with each execution of the inner block of code, we can assign a variable to each element of a list in order, ceasing after we've iterated over every element. Go ahead and stick this in a script block, compile it with ctrl+enter, then give that lever another tug:

# This is a comment!  Anything to the right of a '#' is ignored.

string[] lines = ["Hello", "World", "This", "Is", "Rad", "Yo"]
for string line in lines:
    print line

# The following should be output to the console:
# Hello
# World
# This
# Is
# Rad
# Yo

Did the strings get output the terminal? Awesome! Here's an equivalent variation of the above:

string[] lines = ["Hello", "World", "This", "Is", "Rad", "Yo"]
for int i in lines.size():
    print lines[i]

This will print the exact same thing to the console-- the difference is, we used the array indexing operator (the square brackets) to select each element, rather than let the for loop do it for us.

You may be inclined to think the above wouldn't work, since i will iterate over [0..size - 1], rather than [1..size]. However, in most programming languages, the first element of an ordered list is at index 0, not 1. From this, it follows that if a list contains 10 elements, its indices are [0..9], and more generally, [0..size - 1]. This is important information, as indexing outside the bounds of the array will cause your program to throw an error and immediately cease execution.

Review and Take a Break!

Now's a good time to take a break and make sure you understand the examples above-- try fiddling around with them and altering the variables for fun! I'm sure there's some profane things you'd just looove to print to the console :)

Working with Blocks, Calling Methods

Alright young padawan, you've mastered the way of the print statement... it is time to start working with blocks.

As you may already know, blocks are simply the combination of a blockID and a metadata at a given position, integers x, y, and z. You can actually view your character's position in terms of blocks by pressing F3 outside of any menu. Go ahead and pick an empty position you'd like to stick a tower of blocks by using F3, then type the following into your script-block, replacing 'x', 'y', and 'z' with your chosen coordinates:

for int i in 10:
    world.setBlockID(x, y + i, z, 20)

Give the lever a tug, and WALLAH! An instant tower o' glass, baby. Let's explain...

You'll notice a variable 'world' of type World that we never declared-- this variable was handed to us by the Spellscript block and contains the world that the Spellscript-Block exists in (the Surface, the Nether, the End, etc). You can find all such variables and their types by bringing up the Info Screen via ctrl+/.

In this script, we simply iterate over the integers [0..9], and with each iteration call a method belonging to 'world' entitled 'setBlockID', passing it a few parameters so it knows where to place our block.

A method is essentially a predefined snippet of code belonging to a type. Using the dot (".") operator, they can passed a predefined set of parameters and then executed (or "called", as we say in the business). In our case, setBlockID is a method belonging to World that accepts four int parameters: the x, y, and z coordinates we want to place the block at, and the blockID we want to place.

Simple enough, right? Make sure you understand everything in this section before moving on, since it's fixing to get more complicated (and FUN!!!)

Polymorphism

To truly understand methods and types, you must first understand the programming concept of Polymorphism, which basically means an object can be of more than one type at once. In Spellscript (as in many programming languages), this is accomplished via "inheritance." You can think of it as a square-rectangle relationship...

Suppose there are two types, Player and Living, and Player "inherits" from Living. Just as a square is a rectangle, a Player is a Living-- however, the converse isn't necessarily true. That is, just as a rectangle isn't necessarily a square, a Living isn't necessarily a Player.

The nature of this relationship let's Spellscript do useful things, particularly with methods. If a type B inherits from type A, then objects of type B have all the methods of type A, in addition to their own. Even better, if a type C inherits from type B, then C has all the methods of type B and A! Thus in our case, if Player inherits from Living, and Living inherits from Entity, it follows that Player has all the methods of Living and Entity in addition to its own!

This is vital information, as it enables you to understand what methods are available on which objects in Spellscript. To see all of Hack/Mine's available methods in the Spellscript IDE, simply press ctrl+m. You'll see a list of all the types available, in addition to what types they inherit from and what methods belong to them. So if Entity has a method getX, so do Living and Player. Piece of cake!

<to be continued...>