DaVince scripting tutorial/About JavaScript

From Spheriki

About Sphere's 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!