Gw Temp

Menu

Tutorial - 'Sphere Basics' by rjt

An item about Sphere posted on

Blurb

A nice indepth tutorial on the basics of Sphere

Body

This tutorial covers the basics of scripting in Sphere. It requires no previous knowledge of Sphere, and is aimed at users that have used RM2k, and have no programming experience.

First of all, you'll need to download Sphere. It is available at http://sphere.sourceforge.net. After you have installed it, run the editor. Click File -> New -> Project. Name and Title the project what ever you want. A window will appear, with 8 folders and a blue orb icon labelled Game Settings. Each of the 8 folders control a type of resource, much like the Resouce Manager in RM2k/3. The only resource we will be using in this tutorial are scripts.

Scripts control games in Sphere; without a script, the game would not run. Scripts are divided into functions. To give a brief (if slightly inaccurate) explanation of functions, they are sections of code that run together, line by line. A full explanation of functions is difficult to explain before you understand a few other basic concepts, so we'll start looking at them before I try to explain more about functions. When a Sphere game is started, the first code that is run is the game function. This is what creates the opening menu, or starts the first map.

Create a new script by right clicking on the scripts folder icon, and selecting Insert. In the text editor that appears, type this in:

function game()
{
}

This is what a function looks like. The first line tells the computer that this is a function called game. The code for the funtion goes in between the braces (curly brackets {}). As this is the game function, the code in the braces is the first code in the game to be run (and because it's empty at the moment, the game would just open and close). Change the code so that it looks like this:

function game()
{
GetSystemFont().drawText(1, 1, "I R 1337")
FlipScreen();
GetKey();
}

Save the script (File -> Save), then run the game (by clicking the lightning icon in the tool bar).

I know that the code looks confusing now, but everything will make sense when you've read my explanation. The third line, finds out what font your game is using, and then 'draws' "I R 1337" to the screen in that font. However, it's drawn to a part of the screen that isn't shown, unless the FlipScreen() function is used. Note the semicolon (;) after FlipScreen. Almost all functions end with these. The reason the third line doesn't is because of the '.' after GetSystemFont(), and the first line doesn't to show that it's code starts on the next line, in between the braces.The second last line waits until a key is pressed, effectively pausing the screen.

This all works fine, but what if you wanted input from the keyboard? Delete what you have in your script, and copy the following in it's place:

function game()
{
GetSystemFont().drawText(1, 1, "Would you like to quit this program?")
FlipScreen();
var Answer = GetKey();
if(Answer==KEY_Y)
{
Exit();
}
else if(Answer==KEY_N)
{
GetSystemFont().drawText(1, 1, "You chose not to close the program, but I'm going to close

anyway")
FlipScreen();
GetKey();
}
else
{
GetSystemFont().drawText(1, 1, "You didn't pick Y or N ;_;")
FlipScreen();
GetKey();
}
}

Even more confusing than the first example. Save it and test it, then I'll explain the code.

The first four lines you should recognise. The fifth line uses variables. Like in RM2k, variables store values. However, in Sphere, they can hold letters aswell as numbers. In this case, Answer is the variable, and it's value is set to GetKey(), which we know is equal to the key that was pushed (and in the case that none has been pushed, it waits for another key to be pushed). The next line uses an if() command to see if the variable Answer is equal to Y. If it is, then the code in between the braces is run, otherwise it moves onto the next line after the closing brace, which is line 10. if, else if and else are used together. First of all, the computer looks at the statement in the brackets after the if command. If it is true, then the code in between the braces is run. Otherwise the computer looks at else if. Again, if the statement is true, then the code in it's braces is run, and if it is false, the computer looks at the next else if command, or if there are no more, the else command. The code in the braces after the else command is run when all of the other if's and else if's in the group were false (so in this case it's run when Answer is not equal to Y or N). The only other thing in this program that you haven't seen before is where line 8 uses the Exit() function which exits the program.

Up until now, writing things to the screen took three lines. It would tidy up the code alot if there was a function that could write things to the screen, and then FlipScreen() and GetKey() to pause it. But Sphere doesn't come with any function to do this, so there's no way we can, right? Wrong. It's easy enough to make a function, as I'll demonstrate below. Again, delete everything in your script and copy the below:

function Write(Text, x, y)
{
var font = GetSystemFont();
font.drawText(x, y, Text)
FlipScreen();
while (AreKeysLeft()) GetKey();
GetKey();
}

function game()
{
Write("This is being written by the Write function", 1, 1);
}

Line 1 creates the 'Write' function. The things in the brackets are called 'arguments' or 'parameters'. These are values 'given' to the function when it is used. So if I wanted to use Write to say Hi, I'd write 'Write("Hi", 1, 1);' in the game function. In case you're wondering what the number 1's mean, they are the coordinates where the text will be written. The first number is the x value (which controls how far to the right the text is written), and the second is the y value (which is how far it is from the top of the screen. If you're wondering about line's 3 and 4, they're just a more efficient way of writing text to the screen. Why didn't I say this before? Because I didn't want to introduce variables so early in the tutorial, and it didn't make much difference in the end. Line 5 you've seen before, but 6 is new; earlier on when I explained GetKey I didn't fully explain things. When you're typing on your keyboard, the letters you are typing are being added to the KeyQueue. This is a list of the keys you have pushed, that
nothing has happened to yet. For example, when I'm typing in notepad, all of the letters I type are added to the KeyQueue. In notepad, when a letter is added to the KeyQueue, it is automatically added to the page you're writing on, and then removed from the queue. In Sphere this isn't done automatically, the queue has to be removed with the GetKey() command. GetKey removes the first key on the queue, so using GetKey once isn't always enough. Line 6 uses the AreKeysLeft() function to see if the queue is empty, and if it isn't then GetKey() and the process starts again, until the queue has been emptied. Line 7 then waits for a key to be pushed, because there are now no more keys in the queue. If you haven't fully understood this, don't worry, it's not that important at the moment, it's just good to know. The second last line uses Write to write a message to the screen.

Well, this tutorial has gotten quite long, so I'll leave it at this. If some of the format was odd, it's because I converted from notepad and things got messed up. I tried to fix it myself, but I might not have been 100% successful. I'd love to hear some feedback, so if you want to send me feedback or ask me questions, you can contact me at
rjt3003@hotmail.com.