DaVince scripting tutorial
- Spherical has been reborn, so this tutorial needs to be fixed and updated. Expect some future changes.
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).
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
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.
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).
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!
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.
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!
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.