[ project ] [ map editor ] [ tile editor ] [ spherescript ] [ F.A.Q. ]

(S)phere (s)cript

Spherescript is a c style programing language for sphere.
(this is the magic that holds games together)

variables
Variables are just a place to store information, we could use a variable for anything from whether or not a door is open to how many items there are.
variable types
There are several types of variables.
int - integer meaning only whole numbers, e.g. 5
string - string meaning text, e.g. "five"
image - an image variable used for pictures
color - a color variable, in red, blue, green and alpha values
bool - true or false variables, e.g. false
float - real number variables, e.g. 5.67 (numbers after the point allowed)
variable definition
If you want to set a variables value.
(these examples presume you have already defined the variable type)
int e.g. one = 5;
string e.g. two = "five";
image e.g. three = LoadImage("three.i32");
color e.g. four.red = 5;
float e.g. five = 5.34
global / temperory variables
What is the difference?
Well a global variable is a variable that is there for use in all functions.
And a temperory variable is a variable that is there for use in that function only.

string global;
/* global variables aren't in any functions, that way all functions can call and edit them. */

void name()
{
string temp;
/* no return, 'so temp' is destroyed */
}

Most of your variables will be temperory variables to save memory.

Definition of any variable must be in function!
arrays definition
Arrays are to save time. Lets say a sword has 3 different things we want to measure.
We could do this without using arrays like so:-
int sword_a;
int sword_b;
int sword_c;
Or to save time and energy we could do this with arrays:-
int[3] sword;
Which makes 3 variables sword[0], sword[1] and sword[2].
arrays
With your arrays defined you can now use them.
sword[0] = 1;
sword[1] = 5;
sword[2] = sword[0] + sword[1];
semicolons
All lines of code (apart from statements, comments and functions) end with a semicolon.
e.g.

DrawText(0,0, "The end is nigh.");

functions
You can use functions to refer to code in your script.
e.g. name();

However, building a function is in someways just as easy.

void name()
{
'code here
}

or:-

string name()
{
'code here
return "hello";
}
operaters
void, int, string, bool, image and color are all operaters in a sense.
Operaters are used when a function is built and sets the return value.
void means doesn't return
color means returns a color value.
string means returns a text value, etc...
passing parameters
You can create functions that take in values, much like some of the system functions.

e.g. add(1,5);

int add(int one, int two)
{
return one + two;
}

e.g. text("hello");

void text(string text)
{
DrawText(0,0, text);
/* nothing needs to be returned so this uses the void operater */
}
returning
If a function returns a value like our add(int one, int two) function you can use it to set a variable.
int six;
six = add(1,5);
The variable type must match that of the operater of the function.
(in this case the operater was int so the variable was int)
system functions
You can use system functions in your script.
These system functions are the basis of spherescript.

// engine
void Exit()
void ExitMessage(string)
void ChangeMusic(string)
void PlaySound(string)

// timing
int GetTime()
void Delay(int)

// input
void LockInput()
void UnlockInput()
bool AnyKeyPressed()
bool KeyPressed(int)
int GetMouseX()
int GetMouseY()
bool MouseButtonPressed(int)

// graphics
void FlipScreen()
void SetClippingRectangle(int,int,int,int)
void ApplyColorMask(color)
void SetFrameRate(int)

// images
image LoadImage(string)
image GrabImage(int,int,int,int)
void DestroyImage(image)
void BlitImage(image,int,int)

// text
void SetFont(string)
void SetTextColor(color)
void DrawText(int,int,string)
void DrawTextBox(int,int,int,int,int,string)

// windows
void SetWindowStyle(string)
void DrawWindow(int,int,int,int)

// miscellaneous
void FadeIn(int)
void FadeOut(int)

// map engine
void MapEngine()
void ChangeMap(string)
int GetTile(int,int,int)
void SetTile(int,int,int,int)
void SetColorMask(color,int)

// party
void ClearParty()
void AddPartyCharacter(string)

// persons
void CreatePerson(string,string,int,int)
void DestroyPerson(string)
void SetPersonText(string,string)
void WarpPerson(string,int,int)
void QueuePersonCommand(string,string)

// string
int StringLength(string)
int StringWidth(string)
string LeftString(string,int)
string RightString(string,int)
string MidString(string,int,int)
string Character(int)
int Ascii(string)

// math
float abs(float)
float sin(float)
float cos(float)
float tan(float)
float asin(float)
float acos(float)
float atan(float)
int random(int,int)

// surface handling
surface CreateSurface(int,int)
void DestroySurface(surface)
void CreateImageFromSurface(surface)

// pen/brush
void SetPenColor(color)
void SetBrushColor(color)

// surface primitives
void SetPixel(surface,int,int)
void Line(surface,int,int,int,int)
void Circle(surface,int,int,int)
void Rectangle(surface,int,int,int,int)

// colors
color BlendColors(color,color) color BlendColorsWeighted(color,color,int)

// animation
void PlayAnimation(string)

// type conversion
string itos(int)
float itof(int)
int stoi(string)
float stof(string)
float ftoi(float)
float ftos(float)

script commenting
You can comment on your scripts so that you can remember what you were trying to do, or so that you can find and eliminate errors.

e.g. /* this is a multi line comment */
e.g. ' this is the first single line comment
e.g. // this is the second single line comment

All text from /* to the */ is ignored by the compiler.
All text on a line starting from ' or // is also ignored by the compiler.
ssc
(S)phere (s)cript (c)ompiler or ssc compiles the code so that it can be used.
To compile a script simply open it with sde and from the menu:-

script > compile

statments
There are several statements in spherescript.
if, else and while.
if(sword[2] == 2)
{
'do this
}

/* after the if statement you can put an else statement */

else
{
'okay then do this
}

/* or if you want you can repeat an event continuously */

while(sword == 0)
{
'do this until sword isnt equal to 0
}
testing values

You can test values using if, else and while statements with:-

== means equals equal to
!= means not equal to
> means greater than
< means less than

e.g.

while(sword[0] != 5)
{
if(sword[0] > 5)
{
'you have too many swords, get rid of some
}
if(sword[0] < 5)
{
'you have too little swords, get some more
}
}
coding styles
If you indent you script files like I do, you'll find it easier to find where statements and functions being and end.
This means that all { will line up with all } like in some of my examples.
If you dont do this your scripts will become messy and hard to read.
game function
The function that is ran first by sphere.
A simplistic example of a game function is:-
void game()
{
AddPartyCharacter("flik.rss");
ChangeMap("castle.rmp");
MapEngine();
}

This would place the character Flik into the castle.

structs
A structure is a place that you can store variables.
For example:-
struct herb
{
bool owned;
int amount;
string ready;
}

No need for returning these variables, you can just call upon them like so:-

herbs.owned = true;
herbs.amount = 2;
herbs.ready = "no";
switches
An easy way to test variables.
For example:-
switch(herb.amount)
{
case 0: DrawText(0,0, "You have no herbs.");
case 1: DrawText(0,0, "You have one herb.");
'default: DrawText(0,0, "You have lots o' herbs.");
}

Very neat, just saves time.
The case must match that of the variable you are testing and as such default isnt supported in spherescript.

key words
The key words arent very hard to spot.
(their highlighted by spherescript in sde)
They are:-

void, int, bool, string, float, true, false, if, else, while, do, until, switch, case, for, return, implement, use

All operaters, variable types, statements and a few other words basically.