[ 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.