Legaia's Official Unofficial Sphere Tutorial

From Spheriki

Contents 1 Preface 2 About The Tutorial 3 Use It Properly 4 Installing Sphere 5 Tutorial Features (Table of Contents) 5.1 Chapter 1 – “Let’s Introduce Sphere” 6 Chapter 1 - "Let's Introduce Sphere" 6.1 Object-Oriented Programming (OOP) 6.1.1 The Object model 6.2 Writing Projects in Sphere 6.2.1 The 3-Step Process: 6.3 Different Files Associated With a Sphere Project 6.4 The Sphere Development Environment 6.4.1 The Toolbar 6.5 Writing Your First Sphere Project 6.6 Finding and Fixing Errors 6.7 Naming Conventions 6.8 Help 6.9 Chapter Summary 6.10 Review Questions 6.11 Programming Exercises 7 Word Count: 3319

Preface

Hello, and welcome to a world of sleepless nights and crazy fun. What is this world I speak of? Well, that would be the world of Sphere. Sphere is an excellent game maker with a very easy to learn programming language called JavaScript (or ECMAScript). And Sphere has all the tools that you need to create a whole game inside the IDE (Integrated Development Environment). That’s right! You can design everything from fonts to sprite sets, maps to window styles, and beyond.

Sphere has been through many different versions, each one giving a plethora of new features. The newest one, which you have hopefully already gotten, is version 1.13, found at the Spherical website, in the important links section at the end of this tutorial.

If you are a hopeful game programmer, eyes shining for something new and exciting, then Sphere is the engine for you. It's a house with many entries and exits. It's up to you to find the entry that makes you a productive member of this ever-growing community of game developers. Have fun with all of your future endeavors and the best of luck to you! May the Spherical gods look over you and keep you interested in this great tool. See you inside!

About The Tutorial

This tutorial is not only used as a way of teaching you Sphere, but also as an introductory programming course; this tutorial assumes that this is the first time that you have ever programmed before. Already decent programmers may be able to skip some of the chapters. We also hope that if you made it this far you have a working understanding of the Windows OS.

Use It Properly

In order to get the most out of this tutorial it is recommended that you complete all end-of-chapter reviews, tests, and exercises. Doing so allows you to grasp the knowledge given to you throughout each chapter.

Installing Sphere

Again, these instructions are for windows users only. Linux users can find instruction on installation on the spheredev website.

1. You must first download all of the DLLs, Binaries, and Docs from at the following address: Sphere:Latest
2. Unpack all of the files using whatever program you use to extract .zip files. You can download a trial version of winzip at the Winzip Homepage.
3. You must now move all of the Sphere DLL files into the Binaries folder you extracted.
4. Finally, replace the doc’s folder in the sphere binaries folder with the new one. To open the editor, simply click editor.exe.

Tutorial Features (Table of Contents)

Goals will be defined at the beginning of each chapter. These goals will tell you what you should expect to have learned by the end of each chapter. If you cannot answer these questions when you have completed the chapter then it is advised that you study the topic until you are able to.

Chapter 1 – “Let’s Introduce Sphere”

This chapter is meant to introduce Sphere’s integrated development environment (IDE). You will be walked through your very first program in this chapter. It will also introduce you to OOP concepts of objects, properties, methods, and events. Debugging elements are also introduced.

Chapter 1 - "Let's Introduce Sphere"

Things you should be able to do at the end of the chapter …

1. Explain the term object-oriented programming (OOP).
2. Explain the concepts of classes, objects, properties, methods, and events.
3. List and describe the three steps for writing a game.
4. Describe the various files that make up a game done with sphere.
5. Write and run your first “game” in sphere.
6. Identify syntax errors, run-time errors, and logic errors.

During your experience with Sphere, you will write a wide variety of games, likely of all different genres. This chapter will familiarize you with Sphere’s graphical user interface (GUI – pronounced “Gooey”). Using Sphere gives you the opportunity to create just about any type of 2D game imaginable with the human mind. Projects you create with Sphere will hopefully utilize a programming technique known as object-oriented programming (OOP).

Object-Oriented Programming (OOP)

In the OOP model, programs do not happen in a sequence. The computer does not control the flow of execution; instead the user does by causing events such as button presses or mouse clicks to take place. For example, if the user presses escape during a game, the program would automatically make a call to an Exit procedure which you have written somewhere for the program.

The Object model

With Sphere, you'll work with objects. These objects have properties, methods, and events. Each object is based on a class.

Objects

You can think of an object as a thing. An example of an object could be heroes and NPCs.

Properties

Properties are what describe the objects. Some properties of the heroes object could be hp, mp, level, name, etc. When you refer to a property of an object, you must name the object, add a period, and then name the property. For example, if you want to get a heroes name you would do it as heroes.name (pronounced “heroes dot name”).

Methods

Actions associated with objects are called methods. Methods are the verbs of object-oriented programming. Using functions as objects you can use prototypes as a means of defining methods. For example, heroes.prototype.attack = function(who).

You could now use this method in a battle system or something.

Events

An event occurs when the user takes an action such as pressing a key or clicking a button. Events could also be stepping on a trigger on the map. You are able to write different procedures based on these events. For example, if the user presses CTRL you could write some code to make him swing a sword.

Classes

Although Sphere doesn’t truly have classes, functions can be used much the same way. A class is like a template or a blueprint used to create a new object. A class contains the definition of all the available properties, methods, and events. For example you can create a function like this: function enemy(name,hp,mp).

Each time that you create a new enemy object, it will be based on the enemy class or function. You could create three enemies, although they have different names, hp amounts, and mp amounts, they are still all based on the same enemy class and therefore changes can easily be made dynamically as well as individually.

This has just been a quick introductory to OOP. Object-oriented programming will be discusses in greater depth in another chapter so don’t worry if you didn’t really understand too much of this as of right now.

Writing Projects in Sphere

When writing projects with Sphere, there is a three-step process that is helpful to follow. You follow the same process for both project planning and the actual process of creating your project. The three steps involve setting up the user interface, defining all of the different systems, and finally creating the code for these systems.

The 3-Step Process:

1. Design the user interface. You'll plan what everything should look like in the end. All the different aspects of your project should be planned out and sketched on paper before you even touch a computer. It's sometimes a good idea to scan sketches and ask people what they think of the idea and if they have any pointers.
2. Plan the systems. You’ll clearly define what you want to happen in the different systems implemented into your game. Sometimes it's a good idea to have a flowchart of your game to show all the ways your systems interact with each other.
3. Plan the basic code. You’ll create psuedocode for all of your different functions and classes. You should have an idea of how your systems work before you get to coding.

For those of you who don’t know already, psuedocode is an English expression or comment that describes an action. For example, if you wanted to plan what would happen if the user were to press ESC then you could write something like: Call gameEnd() function.

Different Files Associated With a Sphere Project

.mng	Animation file. The main type of animation file used with Sphere (if at all) is a .mng file.
.rfn	Sphere Font File. Font files in Sphere use the .rfn prefix. These fonts can be imported using the windows font to Sphere font converter or they can be designed from scratch.
.png	Image File. When you create an image using Sphere’s built in editor, Sphere saves the files as a .png file. Images in Sphere can be any resolution. Sphere supports 32-bit graphics as well as transparency.
.rmp	Map File. When you create a new map in Sphere, it saves the map as a .rmp file. Sphere’s map editor isn’t the greatest one in the world, but after some practice you should be able to use it effectively.
.js	JavaScript Code File. As you know by now, Sphere uses JavaScript as it’s primary scripting language. You can have as many of these files as your project requires. It’s these files that actually make up the gameplay within the Sphere engine.
.mod, .midi, .wav, etc	Music Files. Sphere’s audiere library supports quite a few types of music files, including .ogg and .mp3. It does support MIDI files, but I don't recommend you use these; they lengthen the loading time of your game.
.rss	Spritesets. Spriteset files are the entities that are placed on a map. These are the different sprites such as the hero sprite, NPCs, and various monsters that you may have. Then again, they can be anything that you as the user feel you must interact with within the game.
.rws	Window Styles. These are the boxes that you see below text and such in games. They can make or break the look of your game, so make sure your spriting style does not clash with itself!
.spk	Sphere Package File. This is the packaged game file. Packing a file into a .spk file is not recommended because only users who have Sphere on their computer would be able to play your game. You're better off making a .zip file of all of your project resources or using a freeware .exe creator.

The Sphere Development Environment

Figure 1.1 - This is what you see when you create a new project with sphere.
















The Sphere development environment (Fig.1.1) is where you create and test the games made with Sphere. This type of development environment is called an integrated development environment (IDE). The IDE consists of various tools, including a map editor which lets you easily design the look of your game; a .js file editor for making and editing program code; an image editor for making images; and a spriteset editor for making sprites. The IDE has a very simple WYSIWYG (what you see is what you get) interface.

The Toolbar

Figure 1.2 - The Standard Toolbar

1. Create a new .js file.
2. Open…
3. Save
4. Run
5. Pencil Tool (image Editing)
6. Line Tool (Image Editing)
7. Rectangle Tool (Image Editing)
8. Circle Tool (Image Editing)
9. Eclipse Tool (Image Editing)
10. Paint Bucket (Image Editing)
11. Selection (Image Editing)
12. Free Selection (Image Editing)
13. 1x1 Area (Map Editor)
14. 3x3 Area (Map Editor)
15. 5x5 Area (Map Editor)
16. Select Tile (Map Editor)
17. Fill Rectangular Area (Map Editor)
18. Fill Area (Map Editor)
19. Copy Area (Map Editor)
20. Paste Area (Map Editor)
21. Copy Entity (Map Editor)
22. Paste Entity (Map Editor)
23. Move Entity (Map Editor)
24. Create Obstruction Segment (Map Editor)
25. (Numbered Wrong, there is no 25.)
26. Delete Obstruction (Map Editor)
27. Move Obstruction (Map Editor)
28. Add a Zone (Map Editor)
29. Edit a Zone (Map Editor)
30. Move a Zone (Map Editor)
31. Delete a Zone (Map Editor)
32. Execute a Script (Map Editor)

Writing Your First Sphere Project

Figure 1.3 - Example output of your first project.

For this first project, I’m going to stick with tradition and get you to display the simple message “Hello, World!” on the screen.

Okay, so, first of all, open the editor by clicking on editor.exe in your Sphere folder. Next, click File-->New-->Project. Name the folder HelloWorld and name the game Hello World. Then make a new script by clicking File-->New-->Script. Save the script as game.js. In the script file, type the following:

function game()
{
  while(!IsKeyPressed(KEY_ESCAPE))
  {
    GetSystemFont().drawText(5,5,”Hello, World! I’m a programmer!”);
    FlipScreen();
  }
  Abort(“Awesomeness…”);  //This forces an exit error and shows a message.
}

Now save the file and click on the thunderbolt to run the project.

I will now explain what everything did.

• First, function game(). This line is the first thing that the engine looks for; it is the start of the game. The code between the curly braces {} is what is called when the function is ran.
  
• Next is, while(!IsKeyPressed(KEY_ESCAPE)). What this does is it keeps doing everything between the curly braces until the key ESC is pressed on the keyboard.
  
• GetSystemFont().drawText(5,5,”Hello, World! I’m a programmer!”); This uses the GetSystemFont() built-in function in order to use a font file that comes with Sphere. drawText() is considered as a method for the font object. The two numbers “5,5” are the x and y-coordinates of the screen. In the game making world, point 0,0 is usually located at the upper-left of the screen and the numbers are positive to the right and also down the y axis. The text in quotations is what will be displayed on the screen at point 5,5. Finally, you may or may not have noticed the semicolon at the end of the line. This semicolon is there to let the engine know that it is done with that line and to move onto the next one. Although you can sometimes get away without using a semicolon, it's a good practice to always include them. If you want to, play around with the numbers and change the text in order to get a feel for what’s happening.
  
• FlipScreen(); This is the function that actually draws everything to the screen for the whole wide world to see. Again, make sure you follow with a semicolon.
  
• You can also leave comments in your code by using 2 backslashes (//) followed by anything you want. The engine does not read the code that comes after this. For example: //This is a comment can only be seen by you! To span more than one line we use /*comment stuff here*/, where /* is the start of the multi-line comment and */ is the end. It's a good practice to comment your code, especially when your code begins to grow to hundreds or even thousands of lines.

There you go, your first Sphere program is now totally complete! Sure, it’s not the most magnificent thing in the world, but get this - you have gotten your feet wet and are ready to continue learning how to use this wonderful program! It won’t be long, and we’ll have a guy walking around on a map in no time.

Finding and Fixing Errors

There are three kinds of programming errors: syntax errors, run-time errors, and logic errors.

Syntax Errors

These happen went you do not condone to JavaScript’s rules for punctuation, format, or spelling. You can check your syntax before running you program by pressing F7 or by clicking Script-->Check Syntax… The editor not only tells you that there are syntax errors but it will also try to locate these errors for you if at all possible.

Run-Time Errors

If your program stops functioning during execution, then you have a run-time error or an exception. The Sphere engine will exit and usually lets you know what caused the error to happen. Arithmetic operations are one of the most common reasons for run-time errors. Something like dividing by 0, finding the square root of a negative number, or calculating a non-numeric data type will cause a run-time error. In a later chapter you will learn how to catch these errors so that the engine doesn't stop when the error occurs.

Logic Errors

A logic error is where the program runs with no problems but produces the wrong data. This could be something simple like a wrong formula. Beginning programmers often overlook logic errors because they think that once a program is running then their job is done.

We in the programming world commonly call errors “bugs”. Therefore, when we try to fix errors, we call it “debugging”.

Naming Conventions

Naming conventions are not necessary, but they do make programming and reading code a whole lot easier. The convention that I will be using throughout this tutorial is called “camel casing”, meaning you begin the name with a lowercase letter and capitalize each additional word in the name (kindaLikeThis). I also tend to append a three letter prefix to the beginning of my file names such as imgDog, bgmCastleSong, etc.

Help

The best place for help regarding anything in Sphere would be at the spheredev website, at http://www.spheredev.org/wiki.
The Spherical forums is a good place as well: http://www.spheredev.org/forums
And a general JavaScript guide: http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide

Chapter Summary

1. Sphere is used to write many different types of games and it’s language of choice is JavaScript.
2. JavaScript is an object-oriented language.
3. In the OOP model, classes are used to create objects that have properties, methods, and events.
4. The most current version of Sphere is v1.3.
5. To plan a project, sketch what it should look like, plan the functions and classes, and implement the actual code for the functions.
6. The Sphere IDE consists of several tools including a map editor, image editor, spriteset editor, code editor, window style editor, font editor, and a music player.
7. Comments are used for documentation. Good programming practices require comments for every function.
8. The abort([message]) function exits the engine and displays an custom error message.
9. There are three types of errors that can occur in a project: syntax errors, which go against the syntax rules of JavaScript; run-time errors, which contain a statement that cannot execute properly; and logic errors, which produce results, but not the results you wanted.
10. Finding and fixing program errors is called “debugging”.
11. Following naming conventions makes your job as a coder much easier.

Review Questions

1. What are objects and properties? How are they related to each other?
2. What are the three steps for planning sphere projects? Describe what happens during each step.
3. What is the purpose of a .rmp file? A .rws file?
4. What is an event? Give some examples.
5. What is meant by the term “debugging”?
6. What is a syntax error? When does it occur and what might cause it? A run-time error? A logic error?
7. What type of file would you presume each of the following were?
   1. imgCat
   2. fntBigBlue
   3. windowBig

Programming Exercises

1. Center align some text along the vertical axis. (HINT-Use GetScreenWidth())
2. Center align some text along the horizontal axis. (HINT-Use GetScreenHeight())
3. Draw text in the center of the screen.

Word Count: 3319