Difference between revisions of "Getting started"

From Spherical
Jump to: navigation, search
m (Starting a new game project: Edited mismatching headings)
(The debugger: SSJ: Flesh out SSj description)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
To find out how to get started with the legacy Sphere 1.x, please check [[Getting started with Sphere 1.5]].
+
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.
 
  
 +
''This article is still a work in progress and not 100% complete yet.''
  
 
__TOC__
 
__TOC__
Line 21: Line 20:
 
** MP3 is not currently supported. It is recommended to use OGG files instead.
 
** MP3 is not currently supported. It is recommended to use OGG files instead.
 
* Scripts: js, mjs
 
* Scripts: js, mjs
 
  
 
=== Sphere-specific file formats ===
 
=== Sphere-specific file formats ===
Line 34: Line 32:
 
| game.sgm, game.json
 
| game.sgm, game.json
 
| Project file
 
| Project file
| You can run your game by opening it with miniSphere. The sgm is for legacy Sphere games while new ones use json.
+
| 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
 
| .rmp
Line 60: Line 58:
 
| 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).
 
| 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 ==
 
== The tools ==
Line 79: Line 76:
 
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.
 
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 ====
+
==== 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.
+
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 ====
 
==== The compiler: Cell ====
Line 90: Line 87:
  
 
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).
 
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 ==
 
== Starting a new game project ==
Line 113: Line 109:
  
 
It includes the required Cellscript.mjs, some commonly used folders, and an example scrip in the src folder.
 
It includes the required Cellscript.mjs, some commonly used folders, and an example scrip in the src folder.
 
  
 
=== Creating the project folder yourself ===
 
=== Creating the project folder yourself ===
Line 122: Line 117:
  
 
<syntaxhighlight>
 
<syntaxhighlight>
import { transpile } from 'compiler';
 
 
 
Object.assign(Sphere.Game, {
 
Object.assign(Sphere.Game, {
 
name: "Your game name here",
 
name: "Your game name here",
Line 133: Line 126:
 
});
 
});
  
transpile('@/scripts/', files('src/*.mjs', true));
+
// install the game's scripts and modules
transpile('@/scripts/', files('src/*.js', true));
+
install('@/scripts', files('src/*.mjs', true));
 +
install('@/scripts', files('src/*.js', true));
  
//Now we determine which folders get added into  
+
// now we determine which additional folders get added into the distributed version of the game
install('@/distdir', "srcdir/*.*", true);
+
install('@/distdir', "srcdir/*", true);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 143: Line 137:
  
 
* <tt>version</tt> describes the Sphere API version. In this guide, we use the Sphere 2 API.
 
* <tt>version</tt> describes the Sphere API version. In this guide, we use the Sphere 2 API.
* <tt>transpile()</tt> 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.)
+
* <tt>install()</tt> 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 script code into a src folder.
+
** You will have to put your source modules into a <tt>src/</tt> folder.
** After compilation of your project, the transpiled scripts will end up in the dist/scripts folder, unless you change the parameters of <tt>transpile()</tt>.
+
** After compilation of your project, the installed scripts will end up in the <tt>dist/scripts</tt> folder, unless you change the parameters of <tt>install()</tt>.
* With <tt>install()</tt>, 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.
+
* With additional <tt>install()</tt> 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 <tt>srcdir/</tt> will be recursively copied into <tt>dist/distdir</tt>.
 
* Again, see the [https://github.com/fatcerberus/minisphere/blob/master/docs/cellscript-api.txt Cellscript API reference] for further details.
 
* Again, see the [https://github.com/fatcerberus/minisphere/blob/master/docs/cellscript-api.txt Cellscript API reference] for further details.
  
Line 163: Line 157:
 
=== Writing the game script ===
 
=== Writing the game script ===
  
TODO
+
Every Sphere game must have a main module--let's call it for the sake of argument <code>main.mjs</code>--which contains the game's startup code.  At its most basic, the typical main module looks something like this:
 +
 
 +
<syntaxhighlight>
 +
export default
 +
class MyGame
 +
{
 +
    constructor()
 +
    {
 +
        /* load resources, set variables, etc. */
 +
    }
 +
 
 +
    start()
 +
    {
 +
        /* ready... set...G*MUNCH*    stupid pig */
 +
    }
 +
}
 +
</syntaxhighlight>
 +
 
 +
<code>export default</code> makes the class the default export for the module, so <code>MyGame</code> 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 <code>start()</code> 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 <code>Thread</code>, for example, gives you built-in update and render hooks:
 +
 
 +
<syntaxhighlight>
 +
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 */
 +
    }
 +
}
 +
</syntaxhighlight>
 +
 
 +
When subclassing <code>Thread</code>, no <code>start()</code> method is required because it's already provided by the <code>Thread</code> class.
  
 
== Compiling the game ==
 
== Compiling the game ==
Line 192: Line 236:
 
== Packaging and distributing your game ==
 
== Packaging and distributing your game ==
  
==== Just the game project ====
+
=== Just the game project ===
  
 
It's as simple as renaming and zipping your <tt>dist</tt> folder!
 
It's as simple as renaming and zipping your <tt>dist</tt> folder!
  
==== As a stand-alone game ====
+
=== 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.
 
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.
 
* Make a new directory with your game's name.
* Copy minisphere.exe and its system folder into your newly created directory.
+
* Copy <code>minisphere.exe</code>, <code>ChakraCore.dll</code>, and the entire <code>system</code> folder into your newly created directory.
 
* Copy your game's dist folder there, too.
 
* 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.
+
Now people can double-click <code>minisphere.exe</code> 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! ====
+
=== Uploading and sharing! ===
  
 
Upload your game somewhere (we have a [https://drive.google.com/open?id=0Bw-4UFVty4u1REhieE5WUTU0LVE public uploads folder available]). Then, share it with the Spherical community or wherever you like! (We love seeing new games and releases!)
 
Upload your game somewhere (we have a [https://drive.google.com/open?id=0Bw-4UFVty4u1REhieE5WUTU0LVE 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, [http://rpgmaker.net/ rpgmaker.net] is also a nice place to upload your game, find an audience and receive feedback.
 
If the game is an RPG, [http://rpgmaker.net/ rpgmaker.net] is also a nice place to upload your game, find an audience and receive feedback.
 +
 +
[[Category:Tutorials]]
 +
[[Category:Sphere 2]]

Latest revision as of 03:48, 28 October 2017

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.