DaVince scripting tutorial/Variables and more on functions

From Spheriki

Variables & more on functions

Let's continue onto the second part of chapter 3.

Variables

If you inserted more texts or objects of the same type in your code, you'll find that it is pretty annoying to type things like LoadFont("file") 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 LoadFont("file") or whatever!

var i_gave_it_a_name;

This is how you make a variable. It does NOT have a value or contain any data yet. I did give it the name "i_gave_it_a_name", which means we can type i_gave_it_a_name every time we need its contents. You can't do that yet, though, as it doesn't have any contents right now. What we have done here is declared (created) a variable. This means that you made a piece of memory available for our variable. The keyword var is only needed once, and that is during declaration. After that, every time you type the variable's name, JS already knows it's a variable.

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

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

This code declares a variable called music. Then we give it a value. The value we just gave it is LoadSound("SomeFile.mp3"), which is a function that loads a sound file an puts it (as a value of sorts) inside the variable. Now you can use the variable music as a 'shortcut' to what's inside it, which is the contents of LoadSound("SomeFile.mp3") in this case.

music.play(true);
//This is much easier than LoadSound("SomeFile.mp3").play(true);

What you see is music.play(true), but Sphere sort of reads it as LoadSound("SomeFile.mp3").play(true) because music is a variable containing (the result of) LoadSound("SomeFile.mp3"). This is not only easier to type, but it also saves a lot of memory because the actual sound file is loaded only once into variable music, and not reloaded for every time we need the music. Using just LoadSound("SomeFile.mp3") all the time would load the file over and over every time, making your game use way too much memory. Not only that, but if you load the same song twice, it's still identified as two different songs in memory, so you can't actually use the .stop() function to stop music if you don't put it in a variable!

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

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

The variable is declared and immediately given a value. Don't forget you don't need the var keyword anymore after you declared the variable once.

var haha = LoadFont("haha.rfn");
 
haha = LoadFont("eh.rfn");  //As you can see, there's no 'var' in front.
haha = LoadSound("haha.mp3");

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

Variables and data types

You can store more than just functions in a variable! You can also use them to hold numbers or text so you can use these later. These different types of data is called exactly that - a data type.

Example:

var story = 1;
var current_text = "What a nice string of text I am!";

This is useful for storylines, for example. If an event has happened: change the value of the story variable so Sphere knows that the event has happened. There are many more types of data that you can store, they will be explained in detail in the More on variables section.

Adding and subtracting to variables

How to add and subtract values from variables containing numbers? It isn't as hard as you'd expect...

• variable++ adds 1 to your variable.
• variable-- subtracts 1 from your variable.
• variable += value adds the value to your variable.
• variable -= value subtracts the value from your variable.
• variable = value changes your variable to the value.

Of course, you could always do something like variable = variable - 4 if you like. But why do that if there's a shorthand version like variable -= 4?

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.

game();

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.

function Name()
{
  //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.

//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.
 
var window = GetSystemWindowStyle();
//Declare the variable 'window' and put the standard Sphere window style in it.
 
var font = GetSystemFont();
//Opens the (ugly lol) standard Sphere system font and puts it in the 'font' variable.
 
 
//Here's our own function named 'TextBox'.
function TextBox()
{
  //Code goes inbetween the braces {}.
  window.drawWindow(5,5,310,100);
  font.drawText(5,5,"Some text");
  FlipScreen();
  GetKey();
}

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

function game()
{
  TextBox();
}

Function arguments

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:

 function TextBox(text)
 {
   window.drawWindow(5,5,310,100);
   font.drawText(5,5,text);
   FlipScreen();
   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:

TextBox("Hello");
TextBox("Line 2");
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.

The stuff that we insert inbetween the parentheses is saved into an argument, we gave this argument the name 'text'. Arguments behave like variables, but only inside their own function. They don't exist outside the function. (The same actually counts for variables made inside a function.) Anyway, what Sphere will do is give assign whatever value you put inbetween parentheses to this argument, and then use it inside the function.

If that wasn't clear enough, imagine that Sphere is doing this: (it doesn't happen literally, but you can compare it with this anyway:)

• Take the text that was found when the function is called and put it in our argument 'text'.
• Walk through the function and look for other places using this argument 'text'.
• Replace it with what we got through the function call.

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

And here it is in physical form:

function a(argument)
{
  Abort(argument);
}
 
//And to call it:
a("This text is used by the Abort() function inside the a() function.");

function a("something!")  //Don't write code like this! Only put something that looks like a variable. This is just an example on what Sphere might do internally.
{
  Abort("something!");
}

Multiple arguments in one function

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

function TextBox(x, y, text)
{
  window.drawWindow(x, y, 310,100);
  font.drawText(x, y, text);
  FlipScreen();
  GetKey();
}

The function call would look like this:

TextBox(10, 15, "hahaha!");

This will make the text "haha" appear on x position 10 and y position 15.