Getting started with Sphere 1.5

Warning: Legacy code ahead

This page has been written for the legacy Sphere 1.x API. While this API is supported in miniSphere, it is generally recommended to use the new Sphere 2 API.

You can mix old and new API functions, but please be aware that Sphere 2 objects are different from Sphere 1 objects, so they cannot be used interchangeably.

Note: this article is for legacy Sphere 1.5. Please see Getting started if you wish to get started with miniSphere and the new tools.

This document is only a BRIEF introduction to Sphere. It does not cover much at all about scripting.

Introduction

You may have just downloaded this "Sphere", but have no idea what to do what to do with it. This document will walk you through creating a game, creating a map, creating a spriteset, and then writing some script to glue them all together.

Mac OS X

Recently, the Sphere engine was successfully ported to Mac OS X. Unfortunately, a proper development environment has not yet been made for Sphere on X, so project development on one computer has been rendered impossible until further notice. It IS possible, however, to make the following Sphere-compatible resources in OS X:

Images

Sphere can read many image formats, including but not limited to GIF, JPEG, BMP, and PNG. As such, Sphere compatible images can be made in pretty much any image editor; preferred image editors include Photoshop and The GIMP, but other editors such as Pixen, Paintbrush.app, or Pixelmator work as well. The format recommended for use in Sphere is PNG, primarily for its high quality-to-filesize ratio.

Audio

Sphere can read many audio formats, including but not limited to streamed audio such as WAV, MP3, OGG, and FLAC, and sequenced audio such as IT, XM, and (in some cases) MIDI, As such, Sphere compatible audio can be made in pretty much any audio editor; free software for streaming audio includes Audacity and Reaper (though in Reaper's case you can sequence the audio and rasterize its output to a streaming format), while commercial software includes Logic Pro, Protools, GarageBand, and Bidule; for now, the only known trackers for the music module sequenced formats on OS X are MilkyTracker and Schism Tracker. Schism Tracker is recommended, as it can output in impulsetracker format, though the audio engine used in Schism is a modified Modplug engine, so it won't sound quite the same as in Sphere (which implements DUMB, which is closer to the authentic Impulse Tracker sound).

Scripts & game.sgm

Sphere uses JavaScript as its scripting language. As such, its scripts are simply plain text files with the extension .js, and as such can be written in any text editor. A text editor that features syntax highlighting of the JavaScript language is highly recommended for development purposes, and there are some available for OS X both free and commercial. Your project's base info is stored in a file called game.sgm, which is simply a text file found in your project's base folder. More info about game.sgm's format can be found in Sphere's documentation.

Notes

What remains are Sphere specific formats like windowstyles, spritesets, Sphere bitmap fonts, and Sphere maps+tilesets. For these, either wait for a native OS X editor, use wine (macports has a good version) and attempt to run the Windows editor, or find a Windows computer and run the Windows editor in its native environment.

Linux

coming soon

Windows

Creating the game

Open the editor from the start menu. The Sphere Development Environment is where you will spend a lot of time making a game, so try to get used to it.  :)

The first step in making any game with Sphere is creating the game directory. Click on the blank white paper in the toolbar, or click File | New | Project.

Enter a project name (the name of the game directory) and a game title (what the game will be called in the Sphere main menu). Click OK, and an empty project window will appear. The project window is an index of all of your game resources, such as maps, spritesets, scripts, and images.

Creating a map

First off, let's create a very simple map. Click File | New | Map. Normally, we may wish to specify the initial map size, and the tileset it uses, but for now, the defaults are okay. Just click OK. And yes, we want to use an empty tileset.

A map window will appear, along with four palette windows. If this is the first map you have created, the palette windows will all be on top of each other. Click the "tileset" tab in the map editor window. This is where you edit tiles. Choose a nice green color, right-click on the edit section, and select "Fill RGB." Plain green is okay, but we can add a little texture to the tile with the image editor's filters. Right-click on the tile editor, and choose Filter | Noise. If there is too much noise, try the blur filter.

Now that we have a grass tile, let's add a water one. Find the "Tiles" palette and right-click on it. Select "Append Tile" and click just to the right of the grass tile. Now follow the same steps we used to make the grass tile, but use a dark blue as the base color. Making two tiles wasn't so bad!

Click on the "Map" tab in the map editor window, and you should see that the entire map is filled with the grass tile. Select the water tile from the tiles palette and draw a small lake or river or something. Of course, there aren't any border tiles from grass to water and back, so it won't look very realistic. But for now, that's okay.

The map is pretty much done, so click the little floppy disk toolbar button to save it. Make sure you're going to save the map in the "maps" subdirectory of your game directory and save it as 'field.rmp'. Close the map window, so that only the project window shows up. You may be wondering why the map isn't listed in the maps section on the project. When you save a file, the Sphere Editor doesn't immediately know that a new file may have been added to the project. Click Refresh under the Project menu, and a plus button will appear next to the maps section. If it didn't, you didn't save the map in the right place.

Creating a spriteset

Use the File | New menu to create a new spriteset. You should see a window with a bunch of directions and one frame in each direction. Spritesets in Sphere work in a different way than you may be used to. There are a list of images and each frame in a direction simply points to one of the images. Look for the "Spriteset Images" palette. There is only one blank image in it right now. Try going to the Edit tab and drawing a circle. Then go to the Base tab and draw a rectangle around the circle. The "base" of the sprite is the rectangle where it touches the ground. Think of it as the feet of a person. Sphere uses the base rectangle to figure out how the spriteset collides with other things on the map. If you want to go ahead and make other images, feel free. To add animation to your spriteset, right/click on a frame in the Frames view and Append a new one. Create a new image, assign it to the frame, and use the frame properties option in the right-click menu to assign a delay (in frames, usually 60 frames per second). Finally, save your spriteset and put it in the project, the same way you did with the map.

Writing the game script

You can have all of the game files in the world ready, but how do you tell Sphere what to do with them? The answer to that question is by writing a script. Sphere uses JavaScript as a scripting language, so hopefully a few of you will already be somewhat familiar with it.

Right-click on Scripts in the project window, and then select Insert. Now make sure you're in the game's script directory, and type a filename (game.js, main.js, and startup.js are good choices for a game script). Now that the project has a new empty script, you'll want to tell Sphere that this script is the game script. Double-click on "Game Settings" in the project window and select your startup script. Click OK.

Now open up the startup script in the script editor. Looks like Notepad, eh? The first thing Sphere does when it starts your game is load the main script and call the game function. The simplest game function is as follows:

function game() {
 
}

This function does absolutely nothing.  :) A more useful game function is:

function game() {
	CreatePerson("aegis", "aegis.rss", false);
	AttachInput("aegis");
	AttachCamera("aegis");
	MapEngine("field.rmp", 60);
}

The scope of this document doesn't cover how exactly how to script everything, but I'll try to explain what the above function does.

CreatePerson("aegis", "aegis.rss", false);

Creates a person named "aegis" using spriteset "aegis.rss". The third parameter, false, means that the entity will not be destroyed during map switches.

AttachInput("aegis");

Attaches the input to the entity named "aegis." This allows you to move it around the map with the keyboard.

AttachCamera("aegis");

Attaches the camera to the entity so that, if possible, the entity will be shown in the center of the screen.

MapEngine("field.rmp", 60);

This starts the map engine at 60 frames per second, using "field.rmp" as the initial map.

Now save the script file, like you did with the map and the spriteset.

Conclusion

We have a working (albeit small) game! Click the lightning bolt in the editor's toolbar and walk around on the map a little. :)

Credits

By Chad Austin, adapted for the wiki. Additional material by Neo.