Getting started

To find out how to get started with the legacy Sphere 1.x, please check Getting started with Sphere 1.5. It is strongly recommended not to use the legacy engine for new projects!

This article is still a work in progress and not 100% complete yet.

Introduction

You can download miniSphere here.

You may have just downloaded this "Sphere", but have no idea what to do what to do with it. This article will explain everything that is useful to know about the game engine and its tools. Then it will walk you through creating a tiny little game from scratch.

File support

miniSphere has native support for many different file formats, so you generally don't have to worry about having to convert files much.

• Images: bmp, png, jpg, tga
• Sound: wav, ogg, flac, mod, xm, s3m, it.
  • MP3 is not currently supported. It is recommended to use OGG files instead.
• Scripts: js, mjs

Sphere-specific file formats

Besides the above, miniSphere also supports file formats Specicially made for the game engine.

File	What is it?	Notes
game.sgm, game.json	Project file	You can run your game by opening it with miniSphere. Contains some info about your game (like its name, author and resolution). The sgm is for legacy Sphere games while new ones use the json file.
.rmp	Map file	Can be created with editors like Sphere Studio or the legacy Sphere editor.
.rts	Map tileset	Contains tile images and tile data. It can be reused across maps.
.rss	Spriteset	For creating game sprites. They can be animated.
.rfn	Bitmap font	A font file consisting of many images per character that you can edit.
.rws	Windowstyle	For designing resizable windows that go around things like text boxes and menus.
.spk	Sphere game package	This is a packaged Sphere game, for easy distribution of your game (and some protection if you don't want your source code to be shown).

The tools

miniSphere comes with several different tools:

• The game engine itself (miniSphere);
• A development environment for Windows (Sphere Studio);
• A debugger (SSJ);
• A programmable compiler (Cell).

The game engine: miniSphere

This is the game engine that will ultimately allow you to run your game. If you associate .sgm and game.json files with it, you can simply double-click them and run the game. (There are other ways to make it easy for distribution as well.)

The editor: Sphere Studio

miniSphere comes with Sphere Studio, an integrated editor, which lets you create, view and edit the different file types mentioned above. It also has a built-in code editor for editing your JavaScript (js and mjs) files.

The debugger: SSj

SSj is a JavaScript debugger that allows you to debug your code in realtime. You can use it to view variable values, see which functions are being called, and evaluate JavaScript code, all while the game is actively running. When your game crashes or shows unwanted behavior somewhere, SSj gives you the tools to figure out where it's happening and why. It's an invaluable time saver, and can even help you find bugs that would be impossible to track down otherwise!

The compiler: Cell

Cell allows you to compile your game project into something that can be distributed on the internet! Once compiled, you will have a dist folder that you can put online.

Please see the Cellscript API reference for details on this tool.

Cell requires a build script (Cellscript.mjs) in your project folder to compile the game. Sphere Studio will generate this file for you and so compiling is made easy (just one click).

Starting a new game project

There are several ways to start a new game project:

• Creating a new project in Sphere Studio;
• Creating the project folder yourself;
• Using a template.

In the future, a feature will be added that allows you to create a new project from the command line.

In any case, you will end up with a project folder containing a Cell.mjs file. This is your build script that Cell will use to compile your game.

Creating a new project in Sphere Studio

This one is easy: fire up Sphere Studio. After the first-run configuration screens, you can create a new project right from the menu.

Using a template

Download the template

It includes the required Cellscript.mjs, some commonly used folders, and an example scrip in the src folder.

Creating the project folder yourself

Finally, it's not too difficult to start a new project entirely from scratch. All you need is a text editor to create a valid Cellscript.mjs.

Cellscript.mjs should, at the very minimum, contain the following:

Object.assign(Sphere.Game, {
	name: "Your game name here",
	version: 2,
	author: "Your name here",
	summary: "Summary of the game",
	resolution: '1280x720',
	main: 'scripts/main.js',
});

// install the game's scripts and modules
install('@/scripts', files('src/*.mjs', true));
install('@/scripts', files('src/*.js', true));

// now we determine which additional folders get added into the distributed version of the game
install('@/distdir', "srcdir/*", true);

Notes and details

• version describes the Sphere API version. In this guide, we use the Sphere 2 API.
• install() copies files from the source directory into the final distribution (what you're building with Cell and running with Sphere).
  • You will have to put your source modules into a src/ folder.
  • After compilation of your project, the installed scripts will end up in the dist/scripts folder, unless you change the parameters of install().
• With additional install() directives, you define what files and folders get included into your distributed game, and under what name the folder will be known. In this case, all files from srcdir/ will be recursively copied into dist/distdir.
• Again, see the Cellscript API reference for further details.

Creating your game

TODO

Creating a map

TODO

Creating a sprite

TODO

Writing the game script

Every Sphere game must have a main module--let's call it for the sake of argument main.mjs--which contains the game's startup code. At its most basic, the typical main module looks something like this:

export default
class MyGame
{
    constructor()
    {
        /* load resources, set variables, etc. */
    }

    start()
    {
        /* ready... set...G*MUNCH*    stupid pig */
    }
}

export default makes the class the default export for the module, so MyGame can actually be named anything you want. On startup, the engine will instantiate the exported class (read: create an object from it) and call the start() method to kickstart execution.

Encapsulating the startup code with a class rather than a simple function (as was done in Sphere 1.5) offers a few benefits. Most notably, you can take advantage of subclassing. Deriving from Thread, for example, gives you built-in update and render hooks:

import { Thread } from 'sphere-runtime';

export default
class MyGame extends Thread
{
    constructor()
    {
        // when subclassing, the constructor must call the superclass before
        // doing anything else.
        super();

        /* load resources, set variables, etc. */
    }
    
    on_update()
    {
        /* code here will run once per frame */
    }

    on_render()
    {
        /* code to perform rendering for each frame, may be skipped to
           prevent slowdown */
    }
}

When subclassing Thread, no start() method is required because it's already provided by the Thread class.

Compiling the game

This step is needed to create a version of your game project that can be run with miniSphere.

From the editor

If you're using Sphere Studio or any other compatible IDE, it's literally a matter of pressing the "Build" button. If you want to distribute your game, make sure you select "release" mode rather than "debug".

You can also click the "Run" button to both compile and start the game right away from the editor.

Note: when running the game from the editor, you have the option to use miniSphere's powerful debugging features. For this, the game needs to run in debug mode. See Using the debugger for more information.

From the command line/terminal

• Open a terminal and navigate to the directory where your Cellscript.mjs is located.
• Run the following command

   cell

Your game will be compiled and a runnable version of it will be put in the dist folder.

Running the game

Navigate to the dist folder. Run the game.json file with miniSphere.

Packaging and distributing your game

Just the game project

It's as simple as renaming and zipping your dist folder!

As a stand-alone game

You might want to make the game stand-alone so people don't need to have miniSphere to run it.

• Make a new directory with your game's name.
• Copy minisphere.exe, ChakraCore.dll, and the entire system folder into your newly created directory.
• Copy your game's dist folder there, too.

Now people can double-click minisphere.exe to run your game! Of course, you can also copy the Linux and OS X binaries into this same directory to offer a cross-platform way for people to run your game.

Uploading and sharing!

Upload your game somewhere (we have a public uploads folder available). Then, share it with the Spherical community or wherever you like! (We love seeing new games and releases!)

If the game is an RPG, rpgmaker.net is also a nice place to upload your game, find an audience and receive feedback.