Spellscript Tutorial

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, go ahead and place a Spellscript-Block as an Op on a server (you can find them 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 your chat screen! Simply replace "pass" with the following:

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! You've written your first Spellscript script! Pretty simple, sure, but it's a good starting point.

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>