DaVince scripting tutorial
This tutorial teaches you how to script with JavaScript, and how to apply this knowledge so you can make games in Sphere. I have tried to write the tutorial in such a way that beginners can easily step into the world of Sphere. There are also some tests available which you can take to practice the things you have learnt.
Notes
- Spherical has been reborn, so this tutorial needs to be fixed and updated. Expect some future changes.
Resource pack
Here's a very basic resource pack so you can get started right away. Includes:
- a simple map (rmp file)
- a sprite (rss file)
- a font (rfn file)
- some sounds
File names are in Dutch, but it should be clear what's what.
There are more resources on the Spherical Downloads Repository (coming soon).
Contents
About
This tutorial
Ah, Sphere... An awesome and flexible RPG-creation program... It includes a fully-fledged editor to make your own RPGs (or other kinds of games!), and a flexible, extensive scripting language. But how do you start learning and using this scripting language, and how does it work inside Sphere? This tutorial will help you on your way. Some of the tutorial's chapters are based on other, older and sometimes fairly well-known tutorials, but I tried to make sure that they are easier to understand for newbies. Also, examples were added to these chapters. Next to those, there are chapters that I completely wrote myself. The tests are also original. Well, I hope my tutorial will be useful! Have a good Sphere experience! :)
Questions? Suggestions? Other feedback? My email address is VincentBeers@gmail[Dot]com. You can also of course contact me on the Spherical forums. --DaVince
Sphere
Sphere is a program designed to create RPGs in the style of early Final Fantasy games without too much effort. However, you'll be able to create almost any other kind of 2D game you can imagine if you're skilled enough. It uses a scripting language (JavaScript, which is NOT JAVA!) that "makes everything happen". This, of course, means that you will have to learn this scripting language in order to be able to create a game in Sphere. Scripting isn't always easy, especially for programming/scripting newbies, so I'll try to keep things simple and clear.
Where can I find the latest version of Sphere?
Sphere and its editor can be downloaded from Sphere:Latest. The latest versions can always be found there. The versions of Sphere used when this tutorial was first written are versions 1.10989, 1.11, and 1.13 (1.5 during the rewrite of this tutorial). If some things don't work (correctly), download the latest version of Sphere and these problems will usually disappear. If you already have the latest version and you still encounter problems, there might just be something wrong with your code (or you may have found a bug inside Sphere itself).
Get used to the editor first!
If you want to be able to follow this scripting tutorial well, you will have to get used to the editor's interface a bit first and learn how to use it. If not, AT LEAST get used to the file formats and structure that Sphere games use. Tutorials on how to use the editor's interface can be found in Sphere's default docs. Radnen's Using Sphere tutorial and Sphere/Guide to Sphere are pretty good.
Sphere and Javascript
Sphere uses SpiderMonkey, a special library that makes JavaScript available in applications like Sphere. Sphere itself then adds lots of functions to this implementation of JavaScript so you can actually use it to create a game. JavaScript is a browser scripting language in origin, specially designed for the use in webpages, but as Sphere proves it can be used for other things perfectly fine too. Web JS consists of three parts: the Core, the Client and the Server. Sphere only uses the Core, the other two are actually parts that belong to Web JS.
Configuration and information on scripts
Every Sphere game must have a script where it can start out "reading" (actually interpreting) what to do. The start script to use can be defined in the Game Setings window, accessible by double-clicking on "Game Settings" in a project's main window. You can't define a script if you don't have a script yet, of course, so make one first. Give this first script a good, identifiable name, like start.js or main.js. The script doesn't need to have a specific name like main.js - you can give it any valid name you can think of, "valid" meaning using only characters you can use in a filename. However, it's recommended to keep the name simple and preferably without any special characters (even spaces), so you can quickly and easily reference this script in your code. The start script will be the first script that's read by Sphere's game engine when you start the game. If you want to let Sphere open other scripts next to this one, you can use specific functions in the main script to include these scripts (by using RequireScript()).
You do not need to have more than one script, you could just as well put all of the game's code in the one single start script. But using multiple script files makes everything more clear and easier to find and use. Think about it: seperate scripts for battles, menus, text boxes, storyline... It also allows you to use specific scripts in multiple games, if you make sure to make everything in that script work independently from other scripts... Very nice if you made a nice menu or item system that you want to re-use in a different game. Sphere looks for the function game() inside your startup script when the game is launched. This is the only automatically started (rather, "called") function and gives you a point to start with. All other functions will have to be called by hand. More about functions further down in this document.
You will get to know more about scripts later; I'll talk about where you can use scripts first now.
Places that scripts are used
You can use scripts in different places in Sphere. These are the maps, triggers, persons and files.
Maps have a few internal scripts. You can find these in the Map Properties (menu: Map > Properties). They are useful to have the game control what happens when the map itself is opened or closed, or when/where the player-controlled character is entering or leaving the map. Maps also contain two different types of "entities": triggers and persons.
Triggers are attached to a specific tile and have a script that is launched when the player walks over it.
Persons are entities on the map that have a name, spriteset and scripts to control their actions (like walking around, or talking). Persons can have up to 5 personal scripts, each being run in a different situation:
- On Create, used to run code when the person is created.
- On Destroy, runs right before the person is destroyed.
- On Activate (Touch), runs when the person is being touched by the player-controlled person.
- On Activate (Talk), runs when the player-controlled person faces the person and presses the TALK button (default = space).
- On Generate Commands, runs every frame the map engine is open (but only when the person isn't doing anything else).
Files are the most common place for script code and can be created in any text editor. JavaScript files, whether made in Sphere or not, use the .js file extension. The files are the most important part of a game as these are the main method to give instructions to Sphere, including what to start (and where). The scripts in persons, triggers and maps are more of an extra place for a few instructions when that specific map starts or when you talk to a specific person. More experienced coders tend to avoid making scripts inside maps and entities as much as they can, and instead try to code it all in JS files. They do this because this way, all code stays in one place instead of spread out all over the place, and it becomes easier to access, modify and test this code.
To make a new script file, go to File > new > script, or click on the empty page icon. You'll get a notepad-like editor. This is Sphere's built-in script editor, probably the best one for Sphere scripts. You can also make your scripts in your own favourite text editor, just save them as .js files in the scripts directory of your game.
Now that you know what scripts are all about, we can start the real work!
DaVince scripting tutorial/The basics of scripting
DaVince scripting tutorial/The basics on functions
DaVince scripting tutorial/Variables and more on functions
Test 1
It's good to take a breather from learning new concepts from time to time and actually use the time to put your newly learned concept into practice. I'll help a bit by creating a test that indicates what you should try to do.
Please note that the test is not up-to-date with the revised tutorial right now. This will be fixed soon.
Good luck!
DaVince scripting tutorial/More on variables
DaVince scripting tutorial/Conditions and loops
Test 2
Alright, you should now know enough about data types, conditions, loops, basically anything important enough to be able to make simple games! In fact, you're now fully equipped to make your game already, but if you want to do it orderly and efficiently, you'd better learn more about objects too!
DaVince scripting tutorial/Advanced functionality in functions
DaVince scripting tutorial/Objects
Tutorial TODO list
- Explain try...catch and its lack of implementation in Sphere internals
- Make a glossary for all special terms (if-statement, code block, condition etc.)
- Make more tests, maybe one after each chapter?
- Include pictures?
Come back later and these thing just might be included! Don't be afraid to PM me on the forums for any suggestions, questions, improvements etc.
