Developing a Sphere-compatible engine

Notice

This tutorial article is incomplete, but it is also important. Do not edit it unless you've been given permission, thanks.

This article aims to provide a checklist and resources for developing a JavaScript-powered game engine that is compatible with Sphere's JavaScript API.

Introduction

Throughout this article, the original Sphere implementation shall be referred to as "vanilla" Sphere and consisted of use of an older version of SpiderMonkey as the JavaScript engine, the first-party Corona library for the software implementation of video, and the first-party Audiere library for the audio driver. Input was mapped directly in software using whatever API was native to the OS in the case of the Windows and Linux versions of vanilla Sphere. The recent Mac OS X port of vanilla Sphere used SDL to handle all input and output while still using an older version of SpiderMonkey for JavaScript.

Possible frameworks to implement Sphere:

• JavaScript
  • V8
  • SpiderMonkey v1.8.5
  • Jurassic / IronJS / JavaScript.Net / Jint
• Game Libraries
  • SDL
  • SFML
• Graphics libraries
  • OpenGL
  • pixi.js / three.js
  • DirectX (DirectDraw)
  • hand-rolled software renderer.
• Audio libraries
  • Audiere
  • Libsndfile
  • BASS
  • Irrklang
  • FMod

(TODO: more)

Input

SDL

If you want to use SDL, it will be helpful to set up an event filter to catch application close events. Since the main function that needs proper access to events is GetKey, you can disable mouse movement, mouse button, and key-up events so that the event queue will be filled with just keydown events. This simplifies the implementation of the GetKey function, as it is the only function that needs the queue to contain a specific kind of event. Be sure to pump or poll for events whenever input is requested. This also keeps the engine responsive during calls to getkey, and tending the event queue keeps the engine responsive in general.

Keyboard state polling (as in IsKeyPressed()) can be handled with getting the keystate and comparing keysyms.

SFML

If you are using SFML, you need to handle the key pressed and released events. It's a good idea to use a static array for all of the keys, mouse, and joystick buttons. The array's index corresponds with a key, mouse, and joystick code with a true/false value indicating IsPressed. In order to support more than one joystick you may need to bump up that joystick array to a 2D array, where 'x' is the joystick id and 'y' is the button code.

For the key queue, just use a queue data structure. Enqueue keys on the released state, and dequeue keys with GetKey.

Other input libraries

(TODO: list possible input handling libraries and gotchas)

Handling keyboard input notes

GetKey() must be able to block the sphere engine. If the key queue is empty, go into a loop that just updates the game screen.

(TODO: fill)

Key Constant Mapping

In SDL, SFML, and other game libraries, key code enumerations offered in source may differ from Sphere's. In order to map keys correctly you might need to implement a very large map that is basically a "this key" = "that key" list. Such a technique is optional if you already follow Sphere's key naming conventions, but what this will do is allow other Sphere engines to use those same codes if you saved a game with key mappings from vanilla Sphere.

See Sphere's list of keycode constants for the official list, also at https://github.com/sphere-group/sphere/blob/v1.6/sphere/docs/development/keys.txt

Handling mouse input notes

(TODO)

Handling joystick input notes

(TODO)

Other input methods

(TODO)

Output

Video

Blitting is a process that draws the image or surface to a screen's render target prior to flipping. In web based engines this is best emulated with a "draw queue". You fill the queue with what to draw prior to a frame and update it when you are ready.

(TODO: more) (TODO: multi-monitor?) (TODO: touch-screen?)

Audio

SFML

Audio is split between sounds and music. They have the same API, but music streams intrinsically. Volume however takes a range of 0 to 100. Treat that as a percent of the 0 to 255 range Sphere uses. You might need to cache the volume into a private variable and get set from that, making sure to set the underlying volume as a percent of whatever you used.

Sphere-format file loading

Sphere uses five custom file formats, all containing bitmap data in some form or another: bitmap fonts, spritesets, stylized window frames, maps, and map tilesets. Some of them have metadata interspersed with the bitmap data, others have a dedicated block that contains all the metadata for the file in one section regardless of the bitmap data. Maps in particular have the option of choosing to embed its tileset within its file or to point to an external tileset file. All have fixed size headers that are trivial to read. All integer values are stored in Intel order/little-endian and unless otherwise noted all pixel values are 32-bit and stored in the order RGBA.

Fonts

Pretty straight forward. Version 1 Sphere fonts only allow 8-bit grayscale pixels and are deprecated in favor of version 2 fonts. Version 2 fonts use bitmaps containing full 32-bit RGBA pixels. There are reserved bytes to be aware of, otherwise no metadata.

Spritesets

Three separate versions with separate loading behaviors. Much more complicated than fonts, some reserved bytes, lots of metadata. (TODO: expand)

WindowStyles

Two versions to handle. Some reserved bytes, some deprecated properties depending on version, small amount of metadata. (TODO: expand)

Maps

Lots of metadata, small amount of reserved bytes, can embed tilesets or refer to external tileset files. (TODO: expand)

Tilesets

Lots of metadata, small amount of reserved bytes, bitmap data is in one large block after header but before metadata. (TODO: expand)

The map engine

(TODO)

The MapEngine loop

(TODO)

Maintaining API compatibility

Sphere's original JavaScript API was written with a procedural mentality. JavaScript is a language with a powerful prototype-based inheritance system, so you may want to change Sphere's native objects such as the Color object to allow variable creation via the new syntax; if you do this natively you must either write the equivalent loading function (in this case, CreateColor) as native code or in a scripted shim. The system script oldsphere.js is an example of such a shim, existing to maintain compatibility with projects written for pre-1.0 versions of Sphere. If you'd rather leave the original procedural-style loading functions but add the ability to create native Sphere objects with a working prototype constructor, visit this forum thread for information on doing it in script.

Compatibility with 1.5

(TODO)

Compatibility with 1.6 beta

(TODO)

Compatibility with 1.7 alpha

(TODO)

Backwards-compatibility with pre-1.5

(TODO)

List of Sphere-compatible engine implementations

Complete or in-progress

Complete or in-progress Sphere-compatible engines

Implementation	Operating System	Version	JS engine	Video driver	Audio driver	Input handler
vanilla Sphere source, thread	Win x86, OSX, Linux x86	stable: 1.5 unstable: 1.6 beta 4 inactive: 1.7 alpha	SpiderMonkey	configurable	configurable	configurable
TurboSphere source, thread	Win x86/64, OSX, Linux x86/64, Solaris 10 amd64	0.4.0	V8	OpenGL via SDL2	BASS	SDL2
unnamed Sphere clone in SDL source, thread	?	?	V8	SDL	SDL	SDL
sphere-sfml source, thread	Win x86, OSX(?)	0.65 alpha	Jurassic	OpenGL via SFML 2	libsndfile via SFML 2	SFML 2
web-sphere source, thread	Chrome, Firefox, and IE9+	pixi.js version: ? three.js version: ?	browser via pixi.js, three.js	browser via pixi.js, three.js	browser via pixi.js, three.js	browser via pixi.js, three.js

Info

Although some engines are listed as compatible they will need a shim script to maintain compatibility with Sphere's API. For example, LoadImage may indeed return the correct image format by using a different API such as return new Image().

Discontinued or abandoned

(TODO)

See also

(TODO)