This guide is to get you up and running to program sphere's script styles.
Last updated. 12 of June, 1999

1.0 SphereScript. What the...?
 1.1 Gee... That's sounds complicated.
 1.2 <Darklich>: Variables.
 1.3 <Darklich>: ' This Text doesn't exist.
 1.4 <Darklich>: A funtion.
 1.5 <Darklich>: Variables inside and outside a function.
 1.6 <Darklich>: returning and getting variables, give or take a little.
 1.7 <Darklich>: if and else statements
 1.8 <Darklich>: Switch and case statements
 1.9 <Darklich>: while and do-while loops
 3.10 <Darklich>: for loops
 3.11 Calling Functions
 3.12 <Darklich>: Math.
 3.13 Compiling scripts
 3.14 <Darklich>: Hey that's it.
2.0 Writing scripts for Sphere!
 2.1 Starting Script
 2.2 Getting Sphere to recognise your startup script
 2.3 Resources word on writing scripts
 2.4 Scripting for maps
 2.5 Coming Soon...
------------------------------------------------------------------------------


1.0 SphereScript. What the...?
------------------------------
SphereScript. The stuff that makes the little dudes talk back in the game, or
how little menus shows up when ya look at your status, and more! This is one
of the most flexible script around, and uses pseudo C scripts. 

 1.1 Gee... That's sounds complicated.
 -------------------------------------
 Actually, it's not. SphereScript is kinda like C, but slightly easier. It's
 even easier to learn than Verge2's Scripting language and has baffled its
 long time users. Okay, I'll dedicate the next few sections on the basics of
 Spherescript... (For those C/C++ veteren buffs, do not skip this! glance it
 if you want but this but not skip!). Please note that I'm will not cover
 SphereScript in assembly format, which is more optimised but harder to learn,
 but also because I do not know how to do this! I don't know crap about
 assembly. The concept of popping and pushing registers, jump, add, multiply,
 subtract from registers, etc, are beyond me! 

 1.2 <Darklich>: Variables.
 --------------------------
 This is the important thing in your programming life. You'll be using
 variables for most of your functions(cover later). Let's go on then, shall
 we?

 A variable is like a box, except it can store a specific type of information.
 These boxes can be retrieved later to get information, for simplicity sake.
 There are a couple of common variables type we will use, and these are:
 int         -- integer, eg. 1, 4, 56, 200
 string      -- characters, eg. "I am a duck", "C", "Duh."
 image       -- image data, pictures of Pamela-lookalikes, or <censored> goat
                porn, anime girls, guys with ridiculous amount of muscles.
 color       -- color value in RGBA(red, green, blue, alpha).

 To create a variable, specify the type of variable we will use and give it
 a name! Please note that there cannot be any spaces between the name of the
 variable. Oh, include a semicolon as well, because it means end of current
 instruction.

 eg. int Number_Of_Cows;
     int Z = 5;
     string Sleep = 'Z';
     string VergePeople = "Cool!";
     image LaraCroft;
     color Red.red = 255;

     string Song = "Do " + "Re " + "Mi " + "Fa " + "So " + "La " + "Ti ";

     Darklich = "This is a egotistical self promotion.";
     string Darklich;


 You can also declare the variable type afterwards, spherescript isn't fussy
 about that. As well, you can combine the strings into one string with a +.

 It's also possible to transfer the contents of a variable to another
 variable. To correctly do this, the variable on the left side of equal is
 the receiver, and the variable on the right gives the info. Note that "char"
 variables does not support it, and there's a way to do it through calling
 functions.

 eg.
 int first;
 int second;
 second = 2;
 first = second;

 We'll get a bit more on variables after functions.

 1.3 <Darklich>: ' This Text doesn't exist.
 -------------------------------------------
 Commenting on work is good. It helps other people and you to understand what
 you are planning or what is happening. To comment, just put a ' and
 spherescript will ignore the rest of the line.

 eg.
 ' Hello, This is Bob
 ' Darklich: Yes! Yes! Yes! Oh yeah, baby!

 1.4 <Darklich>: A function.
 --------------------------
 Functions are a set of instructions telling the computer on what to do. They
 have a name, and the set of instruction is inside the curly braces.

 void This_Function()
 {
   ' Put instructions here
 }

 Chad said Functions in SphereScript do not require the braces. However I do
 recommend to add them because of readability. An example of a braceless
 function would be:

 int max(int a, int b)
    if (a > b)
       return a;
    else
       return b;

 Functions names do not have a space. The brackets and "void" have special
 purposes which we will discuss further on.

 1.5 <Darklich>: Variables inside and outside a function.
 --------------------------------------------------------
 Now, here's a confusing part. If you don't understand, come back to this
 and read it again after doing a bit of coding.

 ' Global Variables
 int Outside;

 void Say_Cow()
 {
  'Temporary Variables
  char Moo;
 }

 Integer "Outside" would be considered a global variable. Global variable
 means any functions can access them and modify them. Character "Moo" on the
 other hand, is a temporary variable because after the function ends, the
 variable is destroyed. Temporary variables cannot be accessed by other
 functions.

 1.6 <Darklich>: returning and getting variables, give or take a little.
 -----------------------------------------------------------------------
 "What the hell do you mean?", some of you might ask. It means what it means.
 In a function, you can receive variables. This is very useful when you want
 to get an information from a variable so you can call up another function
 to draw a box. In this example, we've called up a function called "Draw_Box"
 and passed the information of variable "y" to it. Integer "Homer" gets "x".

 void Get_it(int x, int y)
 {
  int Homer;
  Homer = x;
  Draw_Box(y);
 }

 Returning variables is kinda the same. When returning a variable, call
 return(insert_variable_here). Note that you can only return compatible
 variables set by the function. For example, "int Send_it()" can only return
 integers. If you do not wish to send anything back, set the return compatible
 variable of the function to "void", hence what I have been doing in the last
 few functions.

 int Send_it()
 {
  int z;
  z = 15;

  ' This also could be "return z;"
  ' You can also return stuff like "return 15" as long as it's compatible
  return(z);
 }

 ' Not Okay
 string Send_Ass()
 {
  int z;
  z = 15;

  return(z);
 }

 1.7 <Darklich>: if and else statements
 --------------------------------------
 if and else statements plays some important part to how the outcome of the
 function. We don't want to get the same outcome sometimes because of the
 type of situation we're in. Let's say if this person has sexy legs, we would
 branch out to 3 different outcomes: sexy, not sexy, just plain ugly (like
 some people that I see sometimes).

                                   if
                               Sexy Legs?
                             /     |      \
                           /       |        \                         
                         /         |          \
                       /          else          \
                     /             |              \
                    sexy           |             Not sexy
                               Just dammned
                                  ugly

 Here's the code that is equivilent to the diagram.

 int SexyLegs(int Sexy)
 {
  int yes = 1;
  int no = 2;
  int Just_Damn_Ugly = 3;

  ' If it's sexy.... :)
  if (Sexy == yes)
   return yes;

  ' If it's not sexy... :(
  if (Sexy == no)
   return no;

  ' It's just damn ugly! O_o
  else
   return Just_Damn_Ugly;
 }

 A little bit more advanced stuff in using "if", is checking the variable does
 not equal to something. As well, you can put up curly braces after the "if",
 so you can put in more instructions other than one.

 int Numbats;
 string Outcome;

 void G_function()
 {
  Numbats = 1;

  if (Numbats != 1)

 }

 Later on, we'll get to really advanced stuff like checking if a function 
 returns a variable and determine what to do with it.

 1.8 <Darklich>: switch and case statements
 ------------------------------------------
 "switch and case" statements are like "if and else", but a little more
 specific. You must call "switch" before using any "case" statements,
 otherwise the statements can't find the data to match it.  Please note that
 in case statements, a "default" case statement can be used if the data
 doesn't match any of the other case statements. This is particularly useful
 for catching anything from a variable if some freak accident goes wrong.

 For example, let's say we wanted to determine the outcome of string "Outcome"
 from the number of frogs in the amazon that got eaten by locals. We would
 create a variable called "Frogs_Eaten", and call "switch". Just to be easier,
 we set the "Frogs_Eaten" to 3 on that day.

 void Outcome_Of_Message()
 {
  int Frogs_Eaten;
  string Outcome;

  ' Frogs eaten on this day
  Frogs_Eaten = 3;

  switch(Frogs_Eaten)
  {
   case 0:
    Outcome = "Wow, that never happened before";

   case 1:
   case 2:
    Outcome = "Still Okay";

   case 3:
   case 4:
    Outcome = "...";

   ' nothing matched
   default:
    Outcome = "I dunno";
  }

 }

 This wraps up all the basic pathway statements that you need to know.

 1.9 <Darklich>: while and do-while loops
 ----------------------------------------
 Loops are statements that keeps repeating forever until something something
 breaks it. "while and do-while" are the most basic types of loops around.
 The while loops checks for a variable or argument that is valid, and will
 keep checking it until the variable changes.

 void someloop()
 {
  int something;

  while(something != 3)
    {
      ' do something
      something = something + 1;
    }

 }

 1.10 <Darklich>: for loops
 --------------------------
 For loops are really neat. It's used to do very tedious procedures and also
 increases readability. The syntax of for goes like this:

 for( <initial value>; <value's condition>; <changes to value>)

 Sometimes, the syntax have more than one change of value, no initial value,
 or no condition. Don't try this though, I'm not sure Spherescript supports
 that.

 let's try an example. Let's increment a value from 1 to 10 in variable a. To
 do so, create a variable called a, call a for loop and change it from the
 inside of the loop.

 void my_loop()
 {
  int a;
  int i;        'temporary variable

  'This increases a by one each time until ten
  for (i=1; i<11; i++)
  {
   a = i;
  }

  ' neat huh?
 }

 1.11 Calling Functions
 ----------------------
 Functions are cool. You can call another function within another. The only
 thing to be careful about it is to pass the necessary data(if needed to call
 the function) to the function. Here's how to do it:

 int returnMe()
 {
   return 43;
 }

 void workIt()
 {
  int value;

  value = returnMe();
 }

 1.12 <Darklich>: Math.
 ----------------------
 Integers can do mathematical stuff. I've almost forgot about that. The only
 part needed is knowing your math skills (or what's left of it). In C, you
 can add, minus, multiply or divide. There's some more, but that'll be for
 those really curious. Here's how to call the syntax:

 int a, b, c;
 a = 6;
 b = 5;

 ' We're adding this up
 c = a + b;     'c is 11
 c = a + 12;    'c is 18

 ' Minus
 c = a - 6;     'c is 0

 ' Multiply
 c = a * b;     'c is 30

 ' Divide
 c = 36 / a;    'c is 6
 
 ' this is equivelent to each other
 'Adding
 c = c + 1;
 c += 1;

 'Minusing
 a = a - 5;
 a -= 5;

 'Multiplying
 b = b * 5;
 b *= 5;

 'Dividing
 d = d / 2;
 d /= 2;

 1.13 Compiling scripts
 ----------------------
 We've covered about how to write the scripts. What about making it readable
 to Sphere? Easy. We compile them to Sphere's machine language. Compiling
 the scripts to Sphere's native machine language is used for speed reasons.

 To compile your scripts, run the SphereScript Compiler. Load your script
 (File->Load...), then from the menubar, click on Script->Compile. This should
 make the compiler to change your script to an assembly formatted script, then
 compile it to machine language. The assembly formatted script has a extension
 of .ssa, and the assembled script would be a .ssx extension.

 1.14 <Darklich>: Hey that's it.
 -------------------------------
 Yup. That's all you need to know about the basics of Sphere scripting.
 Now let's go do some serious stuff!


2.0 Writing scripts for Sphere!
-------------------------------
 
 2.1 Starting Script
 -------------------
 The starting script for Sphere is what you want to setup and display on the
 screen before the actual game begins. I suggest you have a script called
 begin.ss or startup.ss with the needed functions. Okay, Sphere can only
 reads game() when you first fire up the game. game() acts like main() or
 WinMain for those do C programming, where everything is exists under the
 game function. So you have to put all you code inside game(), and here's an
 example.

 void game()
 {
   AddPartyCharacter("aegis.rss");
   AddPartyCharacter("darklich.rss");
   ChangeMap("cave.rmp");
   MapEngine();
 }

 This show on startup, it will change to the map called start.map in the map
 directory. As well, it set the main sprite as aegis.rss. These are important
 to the startup script mainly they currently the only way to get to your
 initial map. A call to AddPartyCharacter is to set up the sprite that is
 controllable to the game player. MapEngine starts the engine that runs map.
 You can add more than this, like a title screen or a menu to load, run a new
 game or quit, but I won't tell you how to do it. Live and learn. If you have
 real problems, ask either AegisKnight or me.

 Here's what Chad said to me:
 ---- CHAD -- The startup() function is now called game()
 ----         It's very similar to main() in C, in that, when it exits, the
 ----         game is over.
 ----         Here's an example game() function:
 ----   void game()
 ----   {
 ----     AddPartyCharacter("aegis.rss");
 ----     AddPartyCharacter("darklich.rss");
 ----     ChangeMap("cave.rmp");
 ----     MapEngine();
 ----   }

 2.2 Getting Sphere to recognise your startup script
 ---------------------------------------------------
 To do that, you need to have a file called game.inf which will tell Sphere
 what the name of the game is, plus the compiled startup script. Here's the
 current syntax that must exist in game.inf:
 name=
 script=

 The name can be as long as you want. Bewarned though, if the name is too long
 it would be cut off, so keep the name short. The script will be the compiled
 script name with the game() function. 

 2.3 Resources and writing scripts
 ---------------------------------
 Remember, the source resource directory of the scripts will be located at
 where game.inf is. So if your directory is something like this:

 abxy->game.inf
     ->[maps]
     ->[tiles]
     ->[etc]
     ->[scripts]
     ->[images]
     ->[spritesets]

 your scripts would have to point to <map/somemap.map> for a map,
 <images/p.pcx> for a image, and so on, depending on where game.inf is located
 and such.

 2.4 Scripting for maps
 ----------------------
 Coding/Scripting is hard, but the most easiest part is interfacing the map with
 scripts. The most easiest way to interface the map is to have triggers. Triggers
 are little things that is either when a player touch a certain place on the floor
 (Darklich steps on a stone, and suddenly a secret passage appears right in front
 of him), or when they open a door.
 "Here's the information on triggers:

 In RMap, you go to the map information dialog box.  From there, you select a
 script (must be compiled!).  Then you right-click on a tile on the map and
 select "Add Entity..."  Then you change the entity type to Trigger and type in
 the name of a function.  When the party (the first character) steps on the tile,
 it executes the function in the script.  You can use this to set color masks,
 change the song, play a sound effect, create an entity (when the entity
 functions are written! ;), or do whatever." - Chad

 2.5 Coming soon...
 ------------------
 some tutorial coming soon! More stuff! Stay tuned! Same time, same place, some
 bat channel!
 
 - Darklich
 "See the kid who plays Weasly Crusher fuck the tree!"
