Difference between revisions of "Getting started"

From Spherical
Jump to: navigation, search
(→‎Writing the game script: game function link)
(Completely overhauled for the entirely new Sphere tools. Plenty left to do!)
Line 1: Line 1:
−
This document is only a BRIEF introduction to Sphere. It does not cover much at all about scripting. The [[Spherical:Latest|latest version of Sphere]] is recommended for development.
+
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.
 +
 
  
 
__TOC__
 
__TOC__
  
−
==Introduction==
+
== 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.
+
 
 +
You can download miniSphere [http://www.spheredev.org/#download 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.
  
−
==Mac OS X==
+
* Images: bmp, png, jpg, tga
−
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:
+
* Sound: wav, ogg, flac, mod, xm, s3m, it.
 +
** MP3 is not currently supported. It is recommended to use OGG files instead.
 +
* Scripts: js, mjs
  
−
===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-specific file formats ===
−
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).
+
Besides the above, miniSphere also supports file formats Specicially made for the game engine.
  
−
===Scripts & game.sgm===
+
{| class="wikitable"
−
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.
+
|-
 +
! 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).
 +
|}
  
−
===Notes===
 
−
What remains are Sphere specific formats like [[API:WindowStyle|windowstyles]], [[API:Spriteset|spritesets]], Sphere [[API:Font|bitmap fonts]], and Sphere [[API:Map|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==
+
== The tools ==
−
coming soon
 
  
−
==Windows==
+
miniSphere comes with several different tools:
−
===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 <var>File | New | Project</var>.
+
* The game engine itself (miniSphere);
 +
* A development environment for Windows (Sphere Studio);
 +
* A debugger (SSJ);
 +
* A programmable compiler (Cell).
  
−
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.
+
==== The game engine: miniSphere ====
  
−
===Creating a map===
+
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.)
−
First off, let's create a very simple map. Click <var>File | New | Map</var>. 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.
+
==== The editor: Sphere Studio ====
  
−
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!
+
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.
  
−
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 debugger: SSJ ====
  
−
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.
+
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.
  
−
===Creating a spriteset===
+
==== The compiler: Cell ====
−
Use the <var>File | New</var> 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===
+
Cell allows you to compile your game project into something that can be distributed on the internet! Once compiled, you will have a <tt>dist</tt> folder that you can put online.
−
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.
+
Please see the [https://github.com/fatcerberus/minisphere/blob/master/docs/cellscript-api.txt 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 ===
 +
 
 +
[http://www.spheredev.org/files/sphere2-template.zip 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:
  
−
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)|game function]]. The simplest game function is as follows:
 
 
<syntaxhighlight>
 
<syntaxhighlight>
−
function game() {
+
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
 +
install('@/distdir', "srcdir/*.*", true);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
This function does absolutely nothing. :) A more useful game function is:
+
===== Notes and details =====
−
<syntaxhighlight>
+
 
−
function game() {
+
* <tt>version</tt> describes the Sphere API version. In this guide, we use the Sphere 2 API.
−
CreatePerson("aegis", "aegis.rss", false);
+
* <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.)
−
AttachInput("aegis");
+
** You will have to put your script code into a src folder.
−
AttachCamera("aegis");
+
** 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>.
−
MapEngine("field.rmp", 60);
+
* 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.
−
}
+
* Again, see the [https://github.com/fatcerberus/minisphere/blob/master/docs/cellscript-api.txt Cellscript API reference] for further details.
−
</syntaxhighlight>
+
 
 +
== 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 <tt>dist</tt> folder.
 +
 
 +
== Running the game ==
 +
 
 +
Navigate to the <tt>dist</tt> folder. Run the game.json file with miniSphere.
 +
 
 +
== Packaging and distributing your game ==
  
−
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.
+
==== Just the game project ====
  
−
<syntaxhighlight>
+
It's as simple as renaming and zipping your <tt>dist</tt> folder!
−
CreatePerson("aegis", "aegis.rss", false);
 
−
</syntaxhighlight>
 
−
Creates a person named "aegis" using spriteset "aegis.rss". The third parameter, false, means that the entity will not be destroyed during map switches.
 
  
−
<syntaxhighlight>
+
==== As a stand-alone game ====
−
AttachInput("aegis");
 
−
</syntaxhighlight>
 
−
Attaches the input to the entity named "aegis." This allows you to move it around the map with the keyboard.
 
  
−
<syntaxhighlight>
+
You might want to make the game stand-alone so people don't need to have miniSphere to run it.
−
AttachCamera("aegis");
 
−
</syntaxhighlight>
 
−
Attaches the camera to the entity so that, if possible, the entity will be shown in the center of the screen.
 
  
−
<syntaxhighlight>
+
* Make a new directory with your game's name.
−
MapEngine("field.rmp", 60);
+
* Copy minisphere.exe and its system folder into your newly created directory.
−
</syntaxhighlight>
+
* Copy your game's dist folder there, too.
−
This starts the map engine at 60 frames per second, using "field.rmp" as the initial map.
+
* Rename the dist folder to 'startup'.
  
−
Now save the script file, like you did with the map and the spriteset.
+
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.
  
−
===Conclusion===
+
==== Uploading and sharing! ====
−
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==
+
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!)
−
By [[Chad Austin]], adapted for the wiki. Additional material by [[User:Apollolux|Neo]].
 
  
−
[[Category:Tutorials]]
+
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.

Revision as of 12:39, 19 June 2017

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 
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.

Retrieved from "http://wiki.spheredev.org/index.php?title=Getting_started&oldid=10006"