Spellscript Tutorial

Revision as of 17:15, 5 August 2014

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

ZKp5sE Great, thanks for sharing this article post.Thanks Again. Will read on...

Tbz143 Appreciate you sharing, great post.Thanks Again. Keep writing.

iIQUcx Really appreciate you sharing this article post.Thanks Again. Keep writing.

8gAUQv I cannot thank you enough for the article.Thanks Again. Much obliged.

The For Loop

Iterating Over a Range of Integers

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

for int i in 0 to 10:
    print i

We call this "iteration" over the integers 0 through 9. Just like a previous 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.

str[] lines = ["HERP", "ADERP", "ALERP"]
for str line in lines:
    print line

# The following should be output to the console:
# HERP
# ADERP
# ALERP

Make sure the output of the script was as expected. (See the comments!)

You'll notice a new kind of variable above: the list. lines in particular is a list of strings. We specify the type "list of strings" by simply appending [] after str, and we create the actual list by placing the comma-separated values we want in between square brackets.

Here's an equivalent variation of the above:

str[] lines = ["HERP", "ADERP", "ALERP"]
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 by its exact location in the list, rather than letting 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 making changes of your own. (Come on, you know you want to...)

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. (See where it says 'x', 'y', and 'z'?) Go ahead and pick an empty position you'd like to stick a tower of blocks by using F3, remembering to floor them to integers (e.g. '17.256' becomes '17' and '-45.3' becomes '-46'). 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', that does exactly what its name implies: it sets a block at a given position in the world to a given block ID. The position and block are specified by passing the method a few parameters when it's called: x, y, z, and blockID.

A method is essentially a predefined snippet of code belonging to a type. Using the dot (".") operator, they can be passed a particular 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 therefore 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 can also find an updated list of methods here on the wiki. 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...>