Difference between revisions of "DaVince scripting tutorial"

This tutorial teaches you how to script with JavaScript, and how to apply this knowledge so you can make games in Sphere. I have tried to write the tutorial in such a way that beginners can easily step into the world of Sphere. There are also some tests available which you can take to practice the things you have learnt.

This tutorial teaches you how to script with JavaScript, and how to apply this knowledge so you can make games in Sphere. I have tried to write the tutorial in such a way that beginners can easily step into the world of Sphere. There are also some tests available which you can take to practice the things you have learnt.

=== This tutorial ===

=== This tutorial ===

--DaVince

--DaVince

=== Where can I find the latest version of Sphere? ===

=== Where can I find the latest version of Sphere? ===

== Sphere and Javascript ==

== Sphere and Javascript ==

You will get to know more about scripts later; I'll talk about where you can use scripts first now.

You will get to know more about scripts later; I'll talk about where you can use scripts first now.

You can use scripts in different places in Sphere. These are the maps, triggers, persons and files.

You can use scripts in different places in Sphere. These are the maps, triggers, persons and files.

== The basics of scripting ==

== The basics of scripting ==

===Comments===

===Comments===

/* This is also a comment.

/* This is also a comment.

*/

*/

A comment can be put on the same line as a line of code, too. This is useful for explaining just that line:

A comment can be put on the same line as a line of code, too. This is useful for explaining just that line:

===End a line of code with a semicolon===

===End a line of code with a semicolon===

different_bit_of_code_goes_here;

different_bit_of_code_goes_here;

== The basics on functions ==

== The basics on functions ==

===Functions===

===Functions===

===The structure of a function===

===The structure of a function===

* Valid function names: <tt>FunctionName</tt>, <tt>do_300_things</tt>, <tt>EatDonut</tt>.

* Valid function names: <tt>FunctionName</tt>, <tt>do_300_things</tt>, <tt>EatDonut</tt>.

After the name come an opening parenthesis and a closing parenthesis (). This is intended so you can provide extra data to the function (I'll explain in detail later).

After the name come an opening parenthesis and a closing parenthesis (). This is intended so you can provide extra data to the function (I'll explain in detail later).

function game()

function game()

{

{

   //code comes here.

   //code comes here.

Let's add one very simple command, with a comment in front of it:

Let's add one very simple command, with a comment in front of it:

function game()

function game()

{

{

}

}

function MapEngine(map, framerate)  //map, framerate will be explained in the next chapter.

function MapEngine(map, framerate)  //map, framerate will be explained in the next chapter.

{

{

   //Code to make the map engine to work here.

   //Code to make the map engine to work here.

}

}

The original MapEngine function actually consists of internal Sphere code, not scripted in JS, but in the programming language Sphere itself has been written in (C++). You can't change this without changing Sphere itself.

The original MapEngine function actually consists of internal Sphere code, not scripted in JS, but in the programming language Sphere itself has been written in (C++). You can't change this without changing Sphere itself.

I'm going to show you and explain a few of the most used functions in Sphere. Every line of code will be explained.

I'm going to show you and explain a few of the most used functions in Sphere. Every line of code will be explained.

function game()

function game()

{

{

   //We'll open map.rmp with a framerate of 60 frames per second (fps).

   //We'll open map.rmp with a framerate of 60 frames per second (fps).

}

}

Check these pages for more details:

Check these pages for more details:

===A list of common functions===

===A list of common functions===

NOTE BEFORE YOU USE THESE: Some functions have a period . in them. I'll talk about what this means in detail later. For now, just put the appropriate function that loads a resource in front. Example LoadFont("file").drawText(1, 1, "text");

NOTE BEFORE YOU USE THESE: Some functions have a period . in them. I'll talk about what this means in detail later. For now, just put the appropriate function that loads a resource in front. Example LoadFont("file").drawText(1, 1, "text");

== Variables and more on functions ==

== Variables and more on functions ==

When you're coding and need the exact same bit of data several times, you'll find that it is pretty annoying to type things like <tt>"I am a string"</tt> <tt>LoadFont("file")</tt> over and over again. Luckily there is is this little thing called a variable, which you can use to store these things (and values, text and a lot more!). Because of this you will only need to type the name of the variable to get what's stored inside it, which could be our <tt>LoadFont("file")</tt> or whatever! Well, that's just one of many advantages of it.

When you're coding and need the exact same bit of data several times, you'll find that it is pretty annoying to type things like <tt>"I am a string"</tt> <tt>LoadFont("file")</tt> over and over again. Luckily there is is this little thing called a variable, which you can use to store these things (and values, text and a lot more!). Because of this you will only need to type the name of the variable to get what's stored inside it, which could be our <tt>LoadFont("file")</tt> or whatever! Well, that's just one of many advantages of it.

var some_name;

var some_name;

This is how you make a variable. It does NOT contain any kind of value yet. It has the name <tt>some_name</tt>, which means I would type <tt>some_name</tt> every time I needed its contents. (You can't do that yet, though, as it doesn't have any right now.)

This is how you make a variable. It does NOT contain any kind of value yet. It has the name <tt>some_name</tt>, which means I would type <tt>some_name</tt> every time I needed its contents. (You can't do that yet, though, as it doesn't have any right now.)

Now, let's declare a different variable and assign a value to it.

Now, let's declare a different variable and assign a value to it.

var music;

var music;

music = LoadSound("SomeFile.mp3");

music = LoadSound("SomeFile.mp3");

This code declares a variable called <tt>music</tt>. Then we give it a value. The value we just gave it is <tt>LoadSound("SomeFile.mp3")</tt>, which is a function that loads a sound file an puts it (as a value of sorts) inside the variable. Now you can refer to the variable's name, <tt>music</tt>, to to get to its contents. In this case, that is the sound data retrieved from <tt>LoadSound("SomeFile.mp3")</tt>.

This code declares a variable called <tt>music</tt>. Then we give it a value. The value we just gave it is <tt>LoadSound("SomeFile.mp3")</tt>, which is a function that loads a sound file an puts it (as a value of sorts) inside the variable. Now you can refer to the variable's name, <tt>music</tt>, to to get to its contents. In this case, that is the sound data retrieved from <tt>LoadSound("SomeFile.mp3")</tt>.

music.play(true);

music.play(true);

What you see is <tt>music.play(true)</tt>, but Sphere sort of reads it as <tt>LoadSound("SomeFile.mp3").play(true)</tt> because music is a variable containing (the result of) LoadSound("SomeFile.mp3").

What you see is <tt>music.play(true)</tt>, but Sphere sort of reads it as <tt>LoadSound("SomeFile.mp3").play(true)</tt> because music is a variable containing (the result of) LoadSound("SomeFile.mp3").

Not just that, but if you load the same song twice, it's still identified as two different songs in memory. This means you wouldn't be able to use stuff like the .stop() function to stop music if you don't put it in a variable! Example:

Not just that, but if you load the same song twice, it's still identified as two different songs in memory. This means you wouldn't be able to use stuff like the .stop() function to stop music if you don't put it in a variable! Example:

LoadSound("SomeFile.mp3").play();

LoadSound("SomeFile.mp3").play();

LoadSound("SomeFile.mp3").stop();

LoadSound("SomeFile.mp3").stop();

//Wait, the music isn't stopping! That's because the file is loaded from file twice, and so recognized as two different bits of data in memory.

//Wait, the music isn't stopping! That's because the file is loaded from file twice, and so recognized as two different bits of data in memory.

With a variable:

With a variable:

var music;

var music;

music = LoadSound("SomeFile.mp3");

music = LoadSound("SomeFile.mp3");

music.play();

music.play();

music.stop();  //It stops playing properly, because thanks to the variable name "music", Sphere knows what song (data) to stop.

music.stop();  //It stops playing properly, because thanks to the variable name "music", Sphere knows what song (data) to stop.

There is another, faster way to declare a variable and assign a value to it at once. You can do it like this:

There is another, faster way to declare a variable and assign a value to it at once. You can do it like this:

var music = LoadSound("SomeFile.mp3");

var music = LoadSound("SomeFile.mp3");

The variable is declared and immediately given a value.

The variable is declared and immediately given a value.

var haha = LoadFont("haha.rfn");

var haha = LoadFont("haha.rfn");

haha = LoadFont("eh.rfn");

haha = LoadFont("eh.rfn");

haha = LoadSound("haha.mp3");

haha = LoadSound("haha.mp3");

As you can see you can also change the value in the variable any time you like. It IS called a variable, after all. Its contents can vary, even from one moment to the other.

As you can see you can also change the value in the variable any time you like. It IS called a variable, after all. Its contents can vary, even from one moment to the other.

===Variables and data types===

===Variables and data types===

You can store all kinds of stuff in a variable! For example, you can use them to hold numbers or text for later use. These different types of data are called exactly that - a ''data type''. Example:

You can store all kinds of stuff in a variable! For example, you can use them to hold numbers or text for later use. These different types of data are called exactly that - a ''data type''. Example:

var story = 1;

var story = 1;

var player_name = "Pete Peterson";

var player_name = "Pete Peterson";

This is useful for many different things. For example, story progression: if an event has happened: change the value of the <tt>story</tt> variable so Sphere knows that the event has happened. Or in the case of the string, you could remember a character's name that was entered by the user.

This is useful for many different things. For example, story progression: if an event has happened: change the value of the <tt>story</tt> variable so Sphere knows that the event has happened. Or in the case of the string, you could remember a character's name that was entered by the user.

There are many more types of data that you can store, and they will be explained in detail soon.

There are many more types of data that you can store, and they will be explained in detail soon.

===Adding and subtracting to variables===

===Adding and subtracting to variables===

===Creating a function===

===Creating a function===

As you probably know by now, Sphere reads the commands you insert. These commands are called functions... game(), for example, is a function too, so it could be started the same way as for example a FlipScreen(): by typing its name and the braces behind it.

As you probably know by now, Sphere reads the commands you insert. These commands are called functions... game(), for example, is a function too, so it could be started the same way as for example a FlipScreen(): by typing its name and the braces behind it.

So with this you'd run whatever is in function game(). This particular function doesn't need to be called manually, because game() is automatically called when Sphere starts your game. But it's a good example on how to create your own functions.

So with this you'd run whatever is in function game(). This particular function doesn't need to be called manually, because game() is automatically called when Sphere starts your game. But it's a good example on how to create your own functions.

Making your own function is pretty simple. Just look at how you made the game() function... You can make your own functions in the same way.

Making your own function is pretty simple. Just look at how you made the game() function... You can make your own functions in the same way.

function Name()

function Name()

{

{

   //Code comes here.

   //Code comes here.

}

}

You can put code in functions, this code will be executed as soon as the function is called from somewhere else. As an example we'll try to make a function that executes all commands necessary to make a box containing text.

You can put code in functions, this code will be executed as soon as the function is called from somewhere else. As an example we'll try to make a function that executes all commands necessary to make a box containing text.

//First we'll declare a few variables outside of any function.

//First we'll declare a few variables outside of any function.

//This makes them global, which means they will exist in any function, even if you didn't declare them there.

//This makes them global, which means they will exist in any function, even if you didn't declare them there.

var font = GetSystemFont();

var font = GetSystemFont();

//Here's our own function named 'TextBox'.

//Here's our own function named 'TextBox'.

   FlipScreen();

   FlipScreen();

   GetKey();

   GetKey();

If you insert TextBox(); in your game function, everything in the TextBox() function will be run once you start the game.

If you insert TextBox(); in your game function, everything in the TextBox() function will be run once you start the game.

function game()

function game()

{

{

   TextBox();

   TextBox();

}

}

There is something lacking about our textbox: you can add TextBox(); to your code, but the end result will always stay the same. Every time you call TextBox() you will see the text "Some text" appear on the screen, no matter what. But what if we wanted to display something else, like "Hello", "Line 2" or "Status: moody"? It's not smart to make four different functions just for that, that would be a waste of memory. It would duplicate almost the exact same code four times, defeating the purpose of having a function! So instead, we slightly change the TextBox() function.

There is something lacking about our textbox: you can add TextBox(); to your code, but the end result will always stay the same. Every time you call TextBox() you will see the text "Some text" appear on the screen, no matter what. But what if we wanted to display something else, like "Hello", "Line 2" or "Status: moody"? It's not smart to make four different functions just for that, that would be a waste of memory. It would duplicate almost the exact same code four times, defeating the purpose of having a function! So instead, we slightly change the TextBox() function.

Examine the following code:

Examine the following code:

function TextBox(text)

function TextBox(text)

{

{

   GetKey();

   GetKey();

}

}

Look at the spot where the function is declared (the first line). Inbetween the parentheses there's something new now. This is NOT a function or variable, but an argument. Arguments (also named parameters) can pass values (any kind: numbers, strings etc) on to your function, resulting in the output varying depending on what you "fed" the function. Now we can put all our different text in the function and get different results:

Look at the spot where the function is declared (the first line). Inbetween the parentheses there's something new now. This is NOT a function or variable, but an argument. Arguments (also named parameters) can pass values (any kind: numbers, strings etc) on to your function, resulting in the output varying depending on what you "fed" the function. Now we can put all our different text in the function and get different results:

TextBox("Hello");

TextBox("Hello");

TextBox("Line 2");

TextBox("Line 2");

TextBox("Status: dead");

TextBox("Status: dead");

As you can see we put our text in-between double apostophes ", in-between the braces () of the function call. The " are there to show Sphere that it's a string of text. More on that in chapter 5.

As you can see we put our text in-between double apostophes ", in-between the braces () of the function call. The " are there to show Sphere that it's a string of text. More on that in chapter 5.

* The result is different every time because it's dependant on what you inserted!

* The result is different every time because it's dependant on what you inserted!

And here it is in physical form:

And here it is in physical form:

function a(argument)

function a(argument)

{

{

   Abort("something!");

   Abort("something!");

}

}

If you want to have more than one argument, simply seperate the argument names with a comma:

If you want to have more than one argument, simply seperate the argument names with a comma:

function TextBox(x, y, text)

function TextBox(x, y, text)

{

{

   GetKey();

   GetKey();

}

}

== More on variables ==

== More on variables ==

===2. Text===

===2. Text===

You know this one already, too, if you have been paying close attention to the last chapter. You can use regular sentences, words, letters and characters with this type of content. You call this a string. Strings are used to store and use text in your program. Strings are recognizable by the fact that they have double quotes put around them (like "this"). This is done to clearly define to the system that it is a text string, not a number or anything else. You can also use single quotes if it's more convenient at the time, but take care with single quotes if you have "regular" text: words like it's use a single quote too, so they would end the string. Strings are also typically useful to define file and directory names.

You know this one already, too, if you have been paying close attention to the last chapter. You can use regular sentences, words, letters and characters with this type of content. You call this a string. Strings are used to store and use text in your program. Strings are recognizable by the fact that they have double quotes put around them (like "this"). This is done to clearly define to the system that it is a text string, not a number or anything else. You can also use single quotes if it's more convenient at the time, but take care with single quotes if you have "regular" text: words like it's use a single quote too, so they would end the string. Strings are also typically useful to define file and directory names.

There is a way to "connect" seperate strings together, in fact, it doesn't even have to be a string to be able to connect it to a string. Connecting (or combining) two strings (or compatible types) is what you would call concatenating. There is a very simple way to concatenate: use the plus sign as if you were "adding" two values.

There is a way to "connect" seperate strings together, in fact, it doesn't even have to be a string to be able to connect it to a string. Connecting (or combining) two strings (or compatible types) is what you would call concatenating. There is a very simple way to concatenate: use the plus sign as if you were "adding" two values.

Run the following code in Sphere:

Run the following code in Sphere:

var string = "I am a string" + " with a second string concatenated";

var string = "I am a string" + " with a second string concatenated";

string = string + " and a third string concatenated";

string = string + " and a third string concatenated";

" And a fifth one on the next line, because the plus character allows this.";

" And a fifth one on the next line, because the plus character allows this.";

Abort(string);

Abort(string);

Sphere will show something like this:

Sphere will show something like this:

Strings can also contain some special characters you can use for formatting the text when it's put on screen:

Strings can also contain some special characters you can use for formatting the text when it's put on screen:

Try running the following code to see how you can use these:

Try running the following code to see how you can use these:

The result will be something like this:

The result will be something like this:

I'm on a new line.

I'm on a new line.

Me too.

Me too.

     I'm on a new line with a tab in front.

     I'm on a new line with a tab in front.

C:\path\to\something.txt

C:\path\to\something.txt

You can put objects in variables. Objects are a kind of function too, but they can do much more internally, like store and retreive sub-values and even sub-functions inside. They also can have "changing" states: two objects can be the same on the outside, but store very different things. For example, you can have two instances of an Image object, one containing a small icon and the other a big cloud graphic. Objects are complex, so I'll leave the explanation at that for now and go more in-depth later in the tutorial.

You can put objects in variables. Objects are a kind of function too, but they can do much more internally, like store and retreive sub-values and even sub-functions inside. They also can have "changing" states: two objects can be the same on the outside, but store very different things. For example, you can have two instances of an Image object, one containing a small icon and the other a big cloud graphic. Objects are complex, so I'll leave the explanation at that for now and go more in-depth later in the tutorial.

Anyway! Sphere has a bunch of internal objects that can load images, music, basically all basic file resources. These objects can be made (instantiated) and stored inside variables by calling their appropiate LoadWhatever() functions, like LoadImage(file) or LoadFont(file). These then offer some internal "sub"-functions (or subvalues) to get or change further information, like image.width and image.height, or Font.getHeight().

Anyway! Sphere has a bunch of internal objects that can load images, music, basically all basic file resources. These objects can be made (instantiated) and stored inside variables by calling their appropiate LoadWhatever() functions, like LoadImage(file) or LoadFont(file). These then offer some internal "sub"-functions (or subvalues) to get or change further information, like image.width and image.height, or Font.getHeight().

var blah = LoadFont("fontfile.rfn");

var blah = LoadFont("fontfile.rfn");

var fontheight = blah.getFontHeight();

var fontheight = blah.getFontHeight();

blah contains an instance of Sphere's internal Font object, which has methods (subfunctions, indicated with a separating dot) to further do things with this object, like draw it on the screen.

blah contains an instance of Sphere's internal Font object, which has methods (subfunctions, indicated with a separating dot) to further do things with this object, like draw it on the screen.

===5. New functions===

===5. New functions===

You can also put NEW functions in variables, like this:

You can also put NEW functions in variables, like this:

{

{

   //Code comes here.

   //Code comes here.

This is basically a different way to declare a function. It's functionally equivalent to this:

This is basically a different way to declare a function. It's functionally equivalent to this:

{

{

   //Code comes here.

   //Code comes here.

This might seem useless, it has several uses:

This might seem useless, it has several uses:

Objects use it to create methods (subfunctions, example is the getHeight() method in Font.getHeight()), because the syntax to make these is a bit different.

Objects use it to create methods (subfunctions, example is the getHeight() method in Font.getHeight()), because the syntax to make these is a bit different.

You can make anonymous functions. These are normal functions that do not have a name. An example of doing this is when you pass a function as an argument:

You can make anonymous functions. These are normal functions that do not have a name. An example of doing this is when you pass a function as an argument:

function CallMe(argument)

function CallMe(argument)

{

{

//...

//...

CallMe(function() { Abort("something happens in here."); });

CallMe(function() { Abort("something happens in here."); });

That's a lot of braces and parentheses! But all we do on the last line is create a function on the spot, on a single line, and not assign any identifiable name to it. I could also have done the following for the last line, but then you wouldn't call it an anonymous function anymore:

That's a lot of braces and parentheses! But all we do on the last line is create a function on the spot, on a single line, and not assign any identifiable name to it. I could also have done the following for the last line, but then you wouldn't call it an anonymous function anymore:

var somefunction = function()

var somefunction = function()

{

{

CallMe(somefunction);

CallMe(somefunction);

Still, it does the same thing; pass a function to another function, showing that functions can be allowed as "values" to pass to other things just as well as a number or a string.

Still, it does the same thing; pass a function to another function, showing that functions can be allowed as "values" to pass to other things just as well as a number or a string.

Should my textbox draw a window?

Should my textbox draw a window?

var draw_a_window = true;

var draw_a_window = true;

//And in a textbox function somewhere:

//And in a textbox function somewhere:

     windowstyle.drawWindow(x, y, w, h);

     windowstyle.drawWindow(x, y, w, h);

   }

   }

Do I want to debug my game and show extra values on the screen?

Do I want to debug my game and show extra values on the screen?

var DEBUG = true;

var DEBUG = true;

//Anywhere else in code:

//Anywhere else in code:

if (DEBUG) { /* Do something related to testing your game */ }

if (DEBUG) { /* Do something related to testing your game */ }

Do I want to check if something finished in order to end a loop?

Do I want to check if something finished in order to end a loop?

var finished = true;

var finished = true;

while (finished == false)

while (finished == false)

   //Do whatever until I set finished to true somewhere in this loop.

   //Do whatever until I set finished to true somewhere in this loop.

}

}

An alternative way of checking for false is by putting an exclamation mark in front of the condition (or variables in the condition), like this:

An alternative way of checking for false is by putting an exclamation mark in front of the condition (or variables in the condition), like this:

Do I want to check if something simply is true or false, or do I want to make it true or false?

Do I want to check if something simply is true or false, or do I want to make it true or false?

if (!sound.isPlaying())  //Check if sound is not playing (sound.Playing == false).

if (!sound.isPlaying())  //Check if sound is not playing (sound.Playing == false).

{

{

   sound.play(true);  //The true here is an argument to sound.play, which answers Sphere's question: should the music loop?

   sound.play(true);  //The true here is an argument to sound.play, which answers Sphere's question: should the music loop?

}

}

As you can see, it has many small but important uses. You'll encounter these two values a lot.

As you can see, it has many small but important uses. You'll encounter these two values a lot.

Or maybe you wish to erase a variable's previous value.

Or maybe you wish to erase a variable's previous value.

Or maybe you wish to declare a variable, but not set a value yet... But then again, in that case you could just not set a value: JS will automatically enter undefined as the default value for a variable not given a value.

Or maybe you wish to declare a variable, but not set a value yet... But then again, in that case you could just not set a value: JS will automatically enter undefined as the default value for a variable not given a value.

Declaring the array

Declaring the array

To make an array, you can type one of the following:

To make an array, you can type one of the following:

- OR -

- OR -

I recommend using [] because it's shorter to type, though it doesn't really make a difference. The first way is a nice example of instantiating an object, though, so you might want to come back here later when you're learning about objects.

I recommend using [] because it's shorter to type, though it doesn't really make a difference. The first way is a nice example of instantiating an object, though, so you might want to come back here later when you're learning about objects.

The first way to do it is by putting values in it right when you declare the array.

The first way to do it is by putting values in it right when you declare the array.

- OR -

- OR -

This is how you declare the array and immediately put some values in it. An array is like a list of items where you can store a value, each seperated with a comma. All items in this list also have a number, starting from 0, which can be used to identify the seperate items, or places in the array.

This is how you declare the array and immediately put some values in it. An array is like a list of items where you can store a value, each seperated with a comma. All items in this list also have a number, starting from 0, which can be used to identify the seperate items, or places in the array.

The second way to store values in an array is by already having declared the array, and then assigning values to spots in the array:

The second way to store values in an array is by already having declared the array, and then assigning values to spots in the array:

var array = [];  //or new Array();

var array = [];  //or new Array();

array[number] = a_new_value;

array[number] = a_new_value;

For example, I'll now change some of the values in the array blah we made before:

For example, I'll now change some of the values in the array blah we made before:

blah[0] = "new value!";  //Spot 0 contained the value 1 before, now it contains "new value!".

blah[0] = "new value!";  //Spot 0 contained the value 1 before, now it contains "new value!".

blah[1] = 7;      //And this used to be 6

blah[1] = 7;      //And this used to be 6

blah[7] = "new value";  //Spot 7 comes after the last spot (spot 6, which contains 88), so basically we created a new spot to store a value in.

blah[7] = "new value";  //Spot 7 comes after the last spot (spot 6, which contains 88), so basically we created a new spot to store a value in.

blah[9] = [1, 2, 3];  //Another subarray with three items is added to the blah array. Spot 8 will contain an undefined value.

blah[9] = [1, 2, 3];  //Another subarray with three items is added to the blah array. Spot 8 will contain an undefined value.

This way you can change the values (or make new values) on different places of your array. The old values (if there are any) are replaced, just like in a normal variable.

This way you can change the values (or make new values) on different places of your array. The old values (if there are any) are replaced, just like in a normal variable.

Since we didn't touch spots 2 and 3, they'll keep their original values, which were 4 and "Theo". That means that our array now consists of the following values:

Since we didn't touch spots 2 and 3, they'll keep their original values, which were 4 and "Theo". That means that our array now consists of the following values:

["new value!", 7, 4, "Theo", "Pete", ["subarray!"], 88, "new value", undefined, [1, 2, 3]]

["new value!", 7, 4, "Theo", "Pete", ["subarray!"], 88, "new value", undefined, [1, 2, 3]]

Now how do we use these values? Well, that's pretty simple, actually. Just refer to your array and add straight brackets right after it containing the number of the spot you want to reach. For example:\

Now how do we use these values? Well, that's pretty simple, actually. Just refer to your array and add straight brackets right after it containing the number of the spot you want to reach. For example:\

var nn = blah[3];  //nn now contains the value "Theo".

var nn = blah[3];  //nn now contains the value "Theo".

TextBox(blah[4]);  //TextBox will print out the text "Pete".

TextBox(blah[4]);  //TextBox will print out the text "Pete".

Abort(blah[9]);    //Sphere will quit, showing the text "[1, 2, 3]" (the array gets interpreted as a string, showing its internal values).

Abort(blah[9]);    //Sphere will quit, showing the text "[1, 2, 3]" (the array gets interpreted as a string, showing its internal values).

So what are arrays useful for? Well, for example, they can be useful for an inventory:

So what are arrays useful for? Well, for example, they can be useful for an inventory:

var inventory = ["Potion", "Antidote", "Empty bottle"];

var inventory = ["Potion", "Antidote", "Empty bottle"];

But most importantly, they can be used to store similar data together and perform mass actions on them. Like naming all characters in your game (or just the party) and then generating a person on the map for each one of them:

But most importantly, they can be used to store similar data together and perform mass actions on them. Like naming all characters in your game (or just the party) and then generating a person on the map for each one of them:

var people = ["DaVince", "Petey Pirate", "Aegis", "Flikky", "Nidoran"];

var people = ["DaVince", "Petey Pirate", "Aegis", "Flikky", "Nidoran"];

CreatePerson(people[3], people[3] + ".rss", true);

CreatePerson(people[3], people[3] + ".rss", true);

CreatePerson(people[4], people[4] + ".rss", true);

CreatePerson(people[4], people[4] + ".rss", true);

Now, the above might not seem like it has any advantage ("Why not just do <tt>CreatePerson("DaVince", "DaVince.rss", true)</tt>?").

Now, the above might not seem like it has any advantage ("Why not just do <tt>CreatePerson("DaVince", "DaVince.rss", true)</tt>?").

Conditions basically check if something is true or not. For example, it can check if the variable <tt>blah</tt> contains value <tt>4</tt>, and if it is, it will evaluate this as <tt>true</tt>. You use the '''<tt>if</tt>''' keyword to make this check, in the following style:

Conditions basically check if something is true or not. For example, it can check if the variable <tt>blah</tt> contains value <tt>4</tt>, and if it is, it will evaluate this as <tt>true</tt>. You use the '''<tt>if</tt>''' keyword to make this check, in the following style:

Now for a complete example:

Now for a complete example:

var story = 0;

var story = 0;

   story = 1;

   story = 1;

}

}

Declare variable story with value 0

Declare variable story with value 0

Set story to 1; now this condition can't run again

Set story to 1; now this condition can't run again

Close the block of code for the condition

Close the block of code for the condition

{{col-end}}

{{col-end}}

Explanation:

Explanation:

* <tt>Check whether variable 'story' contains value 0</tt>

* <tt>Check whether variable 'story' contains value 0</tt>

The == operator (that's what you call it) is just one of a set of comparisons you can use in conditions. It compares whether one number is equal to the other. But more types of comparisons exist, like checking if a value is higher or lower than the other. Here they are:

The == operator (that's what you call it) is just one of a set of comparisons you can use in conditions. It compares whether one number is equal to the other. But more types of comparisons exist, like checking if a value is higher or lower than the other. Here they are:

You use all of these in the same way you used the double equals sign.

You use all of these in the same way you used the double equals sign.

if (a > b) { TextBox("a was higher."); }

if (a > b) { TextBox("a was higher."); }

if (a != b) { TextBox("a and b are different."); }

if (a != b) { TextBox("a and b are different."); }

if (a === b) { TextBox("a is the exact same object with the exact same value as b."); }

if (a === b) { TextBox("a is the exact same object with the exact same value as b."); }

//etc.

//etc.

===Loops: 'while' and 'for'===

===Loops: 'while' and 'for'===

====while====

====while====

Loops in Sphere! These are very useful for things like repeating code. One advantage is that you don't have to have many lines containing the same code over and over again. Example:

Loops in Sphere! These are very useful for things like repeating code. One advantage is that you don't have to have many lines containing the same code over and over again. Example:

var value = 0;

var value = 0;

value++;

value++;

TextBox(value);

TextBox(value);

//etcetera etcetera....

//etcetera etcetera....

It takes up way too much code if you want to add 1 to value and show a textbox with that value 100 times in a row. That's where the loop comes in: a loop makes it neat and short because you just enter the two lines (value++ and TextBox(value)) in it once, and then run it a hundred times! The loop takes a condition to determine when it should still repeat the code running inside. If the condition is false, the loop ends.

It takes up way too much code if you want to add 1 to value and show a textbox with that value 100 times in a row. That's where the loop comes in: a loop makes it neat and short because you just enter the two lines (value++ and TextBox(value)) in it once, and then run it a hundred times! The loop takes a condition to determine when it should still repeat the code running inside. If the condition is false, the loop ends.

var value = 0;

var value = 0;

//Code continues here when the loop is done.

//Code continues here when the loop is done.

====for====

====for====

A for loop looks a bit different. It's because you do multiple things at once, still in the loop. A for loop usually looks like this:

A for loop looks a bit different. It's because you do multiple things at once, still in the loop. A for loop usually looks like this:

for (var value = 0; value < 100; value++)

for (var value = 0; value < 100; value++)

There are three things here, and semicolons inbetween them! That's a bit different from the usual... But, it's not as difficult to grasp as you might think, and it actually makes the loop much more powerful...

There are three things here, and semicolons inbetween them! That's a bit different from the usual... But, it's not as difficult to grasp as you might think, and it actually makes the loop much more powerful...

for (var blah = 0; blah < 25; blah++)

for (var blah = 0; blah < 25; blah++)

{

{

   TextBox("This loop started " + blah + " times so far...");

   TextBox("This loop started " + blah + " times so far...");

}

}

TextBox("Countdown for liftoff! Ready...");

TextBox("Countdown for liftoff! Ready...");

for (var blah = 10; blah > 0; blah--)

for (var blah = 10; blah > 0; blah--)

}

}

TextBox("ZERO! We have a liftoff!");

TextBox("ZERO! We have a liftoff!");

====Practical example of combining loops with arrays====

====Practical example of combining loops with arrays====

Now for a different use of the loop that also shows its practical use in combination with a collection of data (in this case, an array). We're going back to the last example of the previous chapter, and we're going to rewrite it to use a loop.

Now for a different use of the loop that also shows its practical use in combination with a collection of data (in this case, an array). We're going back to the last example of the previous chapter, and we're going to rewrite it to use a loop.

Goal: to create persons on the map using their names identified in the array.

Goal: to create persons on the map using their names identified in the array.

Original version:

Original version:

var people = ["DaVince", "Petey Pirate", "Aegis", "Flikky", "Nidoran"];

var people = ["DaVince", "Petey Pirate", "Aegis", "Flikky", "Nidoran"];

CreatePerson(people[3], people[3] + ".rss", true);

CreatePerson(people[3], people[3] + ".rss", true);

CreatePerson(people[4], people[4] + ".rss", true);

CreatePerson(people[4], people[4] + ".rss", true);

New version:

New version:

var people = ["DaVince", "Petey Pirate", "Aegis", "Flikky", "Nidoran"];

var people = ["DaVince", "Petey Pirate", "Aegis", "Flikky", "Nidoran"];

var len = people.length;  //array.length can be used to get the length of an array.

var len = people.length;  //array.length can be used to get the length of an array.

   CreatePerson(people[i], people[i] + ".rss", true);  //people[i] is people[0], then people[1], then people[2]...

   CreatePerson(people[i], people[i] + ".rss", true);  //people[i] is people[0], then people[1], then people[2]...

}

}

====do...while====

====do...while====

There is also a third type of loop, but it's basically the same as a while loop and not many people use it. If you still want to know more about it, check out this page.

There is also a third type of loop, but it's basically the same as a while loop and not many people use it. If you still want to know more about it, check out this page.

== Advanced functionality in functions ==

== Advanced functionality in functions ==

The inefficient way is nesting a condition inside another one.

The inefficient way is nesting a condition inside another one.

if (value > 0)

if (value > 0)

{

{

   }

   }

}

}

You're running two conditions, here. But you're also running two if clauses. This takes up a tiny bit more processing power. The computer gets a tiny bit more to do, because it has to do this:

You're running two conditions, here. But you're also running two if clauses. This takes up a tiny bit more processing power. The computer gets a tiny bit more to do, because it has to do this:

* And then another one, because we had two conditions.

* And then another one, because we had two conditions.

====The efficient way====

====The efficient way====

if (value > 0 && value < 10)

if (value > 0 && value < 10)

{

{

   TextBox("The value is somewhere in-between 0 and 10.");

   TextBox("The value is somewhere in-between 0 and 10.");

}

}

What Sphere does now:

What Sphere does now:

Next to the &&, which is called the AND operator, there is the OR operator. This special operator will evaluate the entire result as true if any of the given conditions is true, no matter if all others are false. This can be useful if you want some common code to run under only some circumstances:

Next to the &&, which is called the AND operator, there is the OR operator. This special operator will evaluate the entire result as true if any of the given conditions is true, no matter if all others are false. This can be useful if you want some common code to run under only some circumstances:

if (cheat_mode || backflip_mode || the_player_kicks_ass)  //If even just one of these three equals true...

if (cheat_mode || backflip_mode || the_player_kicks_ass)  //If even just one of these three equals true...

{

{

   DoABackflip();

   DoABackflip();

}

}

The player might do a backflip if any of the three variables given are true. Doesn't matter if only one of them is true, or all three... As long as something is true, it'll run the code inside the block.

The player might do a backflip if any of the three variables given are true. Doesn't matter if only one of them is true, or all three... As long as something is true, it'll run the code inside the block.

The two types of operators can be combined. You could check if all elements in a set of conditions is true, and then compare that to another conditions that might override it and run the condition anyway. It's best to group these together by using extra parentheses. Example:

The two types of operators can be combined. You could check if all elements in a set of conditions is true, and then compare that to another conditions that might override it and run the condition anyway. It's best to group these together by using extra parentheses. Example:

if ((master_password_entered && voice_recognition_success && confirmed_twice) || evil_intruder_override)

if ((master_password_entered && voice_recognition_success && confirmed_twice) || evil_intruder_override)

{

{

   SelfDestruct(ship);

   SelfDestruct(ship);

}

}

The ship will ONLY self-destruct if the master password was entered, the voice recognition succeeded AND the user confirmed the self-destruct sequence twice. Only then. Oh, or if there's an evil intruder who somehow overrode the system.

The ship will ONLY self-destruct if the master password was entered, the voice recognition succeeded AND the user confirmed the self-destruct sequence twice. Only then. Oh, or if there's an evil intruder who somehow overrode the system.

Note that it also works with loops.

Note that it also works with loops.

{

{

   DontGiveUp();

   DontGiveUp();

}

}

===Leaving out the braces===

===Leaving out the braces===

This is another exception to the syntax rules in JavaScript, and sometimes a rather handy one: you can choose to leave out the braces. However, you can do this in only ONE case: when there's only one statement to make. The if-statement immediately closes after you put that finishing semicolon after your only line of code that's going to be run in the condition:

This is another exception to the syntax rules in JavaScript, and sometimes a rather handy one: you can choose to leave out the braces. However, you can do this in only ONE case: when there's only one statement to make. The if-statement immediately closes after you put that finishing semicolon after your only line of code that's going to be run in the condition:

if (condition)

if (condition)

   Statement();

   Statement();

if (next_condition)

if (next_condition)

   OtherStatement();

   OtherStatement();

Of course, you can still format this in any way you like. This can make code much more compact:

Of course, you can still format this in any way you like. This can make code much more compact:

if (story == 1) Statement();

if (story == 1) Statement();

if (story == 2) SecondPart();

if (story == 2) SecondPart();

if (story == 3) ThirdPart();

if (story == 3) ThirdPart();

if (story >= 4) Abort("End of the game!");

if (story >= 4) Abort("End of the game!");

Another exception exists where you can use several statements if you like. However, this method is less compatible; a few JavaScript keywords like return and break will NOT work if you do this:

Another exception exists where you can use several statements if you like. However, this method is less compatible; a few JavaScript keywords like return and break will NOT work if you do this:

if (condition)

if (condition)

   Statement1(),  //Use a comma, not a semicolon, and you can keep feeding the thing code until a semicolon ; is encountered!

   Statement1(),  //Use a comma, not a semicolon, and you can keep feeding the thing code until a semicolon ; is encountered!

   story++,

   story++,

   Statement2();  //End of the code to run for this condition.

   Statement2();  //End of the code to run for this condition.

Note that it also works with loops.

Note that it also works with loops.

   DontGiveUp();

   DontGiveUp();

for (var i = 0; i < 1000; i++)

for (var i = 0; i < 1000; i++)

   TextBox("The loop has run " + i + " times now. WILL IT EVER END? Yes, at 999.");

   TextBox("The loop has run " + i + " times now. WILL IT EVER END? Yes, at 999.");

===The "else" keyword===

===The "else" keyword===

There are two types of ways to use else:

There are two types of ways to use else:

Basically, using just else is like defining code that will run in all other cases. else if can only exist right after an if or another else if. else can only exist once, and that is after all other related conditions.

Basically, using just else is like defining code that will run in all other cases. else if can only exist right after an if or another else if. else can only exist once, and that is after all other related conditions.

var story = (any value)

var story = (any value)

else    //Story could be 5, or 389, or -300 for all we know

else    //Story could be 5, or 389, or -300 for all we know

   Abort("That story section does not exist, fool!");

   Abort("That story section does not exist, fool!");

== Objects ==

== Objects ==

I've mentioned objects before, now we'll go into more detail about them. An object is one of the more complicated things in Sphere, but they will allow you to do very powerful things.

I've mentioned objects before, now we'll go into more detail about them. An object is one of the more complicated things in Sphere, but they will allow you to do very powerful things.

===What is an object?===

===What is an object?===

Objects use names instead of numbers for your data. These "names" are properties if you're storing data and methods if you're storing functions.

Objects use names instead of numbers for your data. These "names" are properties if you're storing data and methods if you're storing functions.

Objects can have different instances.

Objects can have different instances.

===What is an instance?===

===What is an instance?===

Objects are very useful for one specific thing - creating clones of itself that contain different data, and possibly different behavior. When you start making your own object, you start out by shaping the "original" object, which is called the prototype. From here on, your prototype will serve as the way to create actual, usable objects out of your prototype. These new, copied objects are what you would call an instance of that object. Instances let you have similar object - with different values.

Objects are very useful for one specific thing - creating clones of itself that contain different data, and possibly different behavior. When you start making your own object, you start out by shaping the "original" object, which is called the prototype. From here on, your prototype will serve as the way to create actual, usable objects out of your prototype. These new, copied objects are what you would call an instance of that object. Instances let you have similar object - with different values.

===An example of different instances===

===An example of different instances===

The best example to start out with is with something familiar: let us look back at Sphere's own, internal object. When you use LoadImage(), you actually create a new instance of the internal Sphere Image object. For example:

The best example to start out with is with something familiar: let us look back at Sphere's own, internal object. When you use LoadImage(), you actually create a new instance of the internal Sphere Image object. For example:

var a = LoadImage("a.png");

var a = LoadImage("a.png");

var b = LoadImage("b.png");

var b = LoadImage("b.png");

Both a and b are Image objects, but they contain different images - that is, different data.

Both a and b are Image objects, but they contain different images - that is, different data.

===Making your own prototype===

===Making your own prototype===

Now, Sphere's internals use functions like LoadImage(), but this is not actually "true" object-oriented programming, and it is not how we will make our own object prototype. But in this first step, it will almost appear as if we are!

Now, Sphere's internals use functions like LoadImage(), but this is not actually "true" object-oriented programming, and it is not how we will make our own object prototype. But in this first step, it will almost appear as if we are!

function MyObject()

function MyObject()

{

{

There you go, we just made an object prototype. What? It looks just like making a function? That's exactly right - all functions are actually objects, except we don't normally use them as such! Let's take it a step further and see what's so different about objects.

There you go, we just made an object prototype. What? It looks just like making a function? That's exactly right - all functions are actually objects, except we don't normally use them as such! Let's take it a step further and see what's so different about objects.

function MyObject()

function MyObject()

{

{

   this.myproperty = 4;

   this.myproperty = 4;

}

}

Objects have properties. Inside properties, you store values. It's just like using var, but instead we use this. The reason for this is so we can access the value from outside the function. Not only that, but we tell Sphere that this variable-type thing is a default value that the prototype will give to each instance, after which it can be changed individually per instance. You could access the property from the outside as follows:

Objects have properties. Inside properties, you store values. It's just like using var, but instead we use this. The reason for this is so we can access the value from outside the function. Not only that, but we tell Sphere that this variable-type thing is a default value that the prototype will give to each instance, after which it can be changed individually per instance. You could access the property from the outside as follows:

But take note! We are still making an object prototype here, so it's better to leave the prototype alone. Why? Because if you change the prototype's properties' values, new instances would take over that new value too (but old ones would still be in their original state with the old values). This can become a mess, so be careful with it. Usually you will want your prototype to be well-defined inside itself, and nowhere else.

But take note! We are still making an object prototype here, so it's better to leave the prototype alone. Why? Because if you change the prototype's properties' values, new instances would take over that new value too (but old ones would still be in their original state with the old values). This can become a mess, so be careful with it. Usually you will want your prototype to be well-defined inside itself, and nowhere else.

function MyObject()

function MyObject()

{

{

   }

   }

}

}

The above added method adds 1 to our property, so every time it's called, myproperty would increase by 1.

The above added method adds 1 to our property, so every time it's called, myproperty would increase by 1.

===Making an instance of the object===

===Making an instance of the object===