DaVince scripting tutorial/The basics on functions

From Spheriki

The basics on functions

Functions

This tutorial will make sure that you can make your own game in Sphere. A simple, but working game.

A function is a thing you give an identifiable name, put some code in, and then you can run that code any time you reference the function by its name. For example, you can make a function called TextBox that would make a box displaying text appear, and then you can show this text box whenever you like by calling the function TextBox elsewhere. It's very useful to make your code manageable, and it prevents you from doing bad things like copying the same block of code over and over again in different places. The bad thing about doing things like that is: if you make a change to the code you'll need to change it everywhere else, too. If you have a function, you only need to change it once in that function. It also makes your code take up much fewer lines (because your six lines of code is now replaced by one - the call to the function containing those six lines).

The structure of a function

As you should know by now, every Sphere game must have a main script file, containing the main function called game. If you don't know or remember, please read chapter 1 again.

• A function always starts with the word function so both Sphere and the reader of the script knows we're going to make a function. You call such a word a keyword because JavaScript uses it internally to identify what you're trying to do. In this case, we want to define a function.
• After the word function comes the name of the function. When giving it a name, keep in mind only letters, numbers and the underscore _ are allowed. It is also not possible to start the name with a number. Examples: FunctionName, funcname1, function_name.
• After the name come two parentheses: an opening parenthesis and a closing parenthesis (). Things can go inbetween these parentheses, but I'll explain that later.
• After that, you put an opening brace { which indicates that the code coming after the brace will belong to your function.
• After the brace, you put the code that would be run when the function is run.
• When you're done with your code, you close down the functions with the closing brace }.

Example of a function named 'game':

function game()
{
  //code comes here.
}

That's what a function looks like, basically. game() is, as mentioned before, the starting function for a Sphere game.

Still, if you try to run this code, nothing will happen. Sphere will open and then immediately close. That's because we didn't put any code in yet. Let's add one very simple command, with a comment in front of it:

function game()
{
  //This function will open the map map.rmp.
  MapEngine("map.rmp", 60);
}

This piece of code WILL do something, namely it will open the map engine with the file map.rmp, with a framerate of 60 frames per second. Still, if you want this code to work, make sure that the file map.rmp actually exists (and is inside the maps/ directory of your game)!

The above code also demonstrates what calling a function looks like. MapEngine() is a function inside Sphere itself, but if it were coded in JS by a normal user it would have the same structure as the game() function:

function MapEngine(map, framerate)  //map, framerate will be explained in the next chapter.
{
  //Code to make the map engine to work here.
}

The original function actually consists of internal Sphere code, not scripted in JS, but in the programming language Sphere itself has been written in, C++.

Example of some simple Sphere functions

Okay, now for some more difficult stuff. 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()
{
  CreatePerson("my_name", "character.rss", false);
  //Creates a new person. gives him the name my_name and loads the spriteset file character.rss for his looks.
  //'false' indicates he should NOT be destroyed when the game switches maps. That means he'll keep existing even on other maps.
 
  AttachCamera("my_name");
  //Makes sure that the camera is always pointed at the person called my_name.
 
  AttachInput("my_name");
  //Bind the default input to the person my_name. This means that when you press an arrow key, he'll move, stuff like that.
 
  MapEngine("map.rmp", 60);
  //We'll open map.rmp with a framerate of 60 frames per second (fps).
}

The functions:

• CreatePerson(person_name, spriteset, destroy_with_map)
• AttachCamera(person_name)
• AttachInput(person_name)
• MapEngine(mapfile, framerate)

A list of common functions

There are a lot more common Sphere functions, another bunch explained below. You can look up all the other Sphere functions in the doc_functions.txt file that comes with Sphere (it's in the docs directory). You should also check out the Functions documentation on this website, it's a lot more comprehensive and offers examples for each function.

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

LoadFont("font_file.rfn").drawText(10, 10, "Good day, world!");