Spellscript Tutorial

Revision as of 20:42, 25 February 2013

This is an informal guide on how to get started creating Spellscript scripts in Minecraft. See Spellscript for a general language reference-- otherwise, read on...

Your First Spellscript Script

To get started, open up Minecraft via the command line-- this is important so you can see your scripts' output and any lengthy error messages. The easiest way to do this on Windows is to create a .txt file, stick the following text in it, rename the extension to .bat, then double-click it. Here's the text:

java -Xmx2048M -Xms2048M -jar "Minecraft.exe"

Once you've started Minecraft, make sure the command prompt/terminal/crazy-box-full-of-text has opened, 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. Now let's try something more complicated:

# This is a comment!  Anything to the right of a '#' is removed from the script.

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

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

Again, make sure everything is compiling with ctrl+enter, exit the editor, then give the lever a veritable tug. Did the numbers get output the terminal? Awesome! Now to explain...

<to be continued>

Printing to the Player's Chat Box

if activator is None:
    return

if not (activator instanceof Player):
    return

Player player = activator as Player
player.tell("Hello world!")

We'll break this down and explain what's happening, but first, go ahead and left-click the block to make sure everything's working. Was "Hello world!" printed on your chat console? Good!

activator is a variable referring to the entity that activated the block (in this case, you!) None is a special value indicating a value of "nothing". If activator is None, the block wasn't activated directly by an entity, so we don't do anything-- thus, we return, which means we cease execution, basically.

Next if statement, we check to ensure the activator is a player and not just some arbitrary living entity we weren't expecting. To do this, we check the type of activator via the instanceof keyword. (If you open the Info screen via ctrl+/, you'll notice the type of activator is actually Living, which means the activator isn't necessarily a Player. This involves a programming concept known as "Polymorphism", which we'll discuss later.) We then invert the value of this expression with the not operator, and again cease execution with return if the whole expression evaluates to True.

Now that we're certain that the activator is a Player, we go ahead and safe-cast it as such and stick it in a new variable so we can start working with it as Player, not just as a Living. If we safe-casted a Living that happened not to be a Player, the expression would evalute to None-- however, we've already checked for this and are consequently guaranteed that it's a Player, so we don't have to check for None as we did in the first step.

Finally, we call a method belonging to player called "tell", that accepts a string parameter. This particular method causes the parameter handed to it to be printed to the player's chat console (which is what we want!)

Now the script has reached its end, and will finish execution. Whew!

Polymorphism

Two important concepts here are types and methods. To understand these, 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 "single-inheritance." Think of it as a square-rectangle relationship-- just as a square is a rectangle but a rectangle isn't necessarily a square, a Player is a Living but a Living isn't necessarily a Player. The instanceof and as operations allow us to check for the corner cases when a rectangle happens to be a square, or a Living happens to be Player.

The nature of this relationship let's Spellscript do useful things with methods. Particularly, it means if 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. To see all of Hack/Mine's available methods in the Spellscript Editor, 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>