Getting started

To find out how to get started with the legacy Sphere 1.x, please check Getting started with Sphere 1.5.

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. The sgm is for legacy Sphere games while new ones use json.
.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 allows you to debug your game. This means that when your game crashes or shows unwanted behavior somewhere, you can figure out where it's happening and why. It's an invaluable time saver.

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:

import { transpile } from 'compiler';

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',
});

transpile('@/scripts/', files('src/*.mjs', true));
transpile('@/scripts/', files('src/*.js', true));

//Now we determine which 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.
• transpile() will compile the ES6 JavaScript modules that the Sphere 2 API uses into something that the Sphere engine knows how to use, since it has a more conventional JavaScript environment. (This is called transpilation.)
  • You will have to put your script code into a src folder.
  • After compilation of your project, the transpiled scripts will end up in the dist/scripts folder, unless you change the parameters of transpile().
• With install(), 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

TODO

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 and its system folder into your newly created directory.
• Copy your game's dist folder there, too.
• Rename the dist folder to 'startup'.

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.