Difference between revisions of "Developing a Sphere-compatible engine"

Revision as of 21:38, 17 July 2013

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

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

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.

Key Constant Mapping

In SDL, SFML, and other game libraries the key codes may differ from Sphere's. In order to get the correct key mapping you might need to implement a very large structure that says "this key" = "that key". This does not have to happen as it is optional so long as you keep to the same key naming conventions. What this will do is fix it so that if you saved a game with key mappings from vanilla sphere, other sphere engines can use those same codes.

See key constants: (KEY_ESCAPE = 1, KEY_F1 = 2, ... etc).

https://github.com/sphere-group/sphere/blob/v1.6/sphere/docs/development/keys.txt

(keyboard, mouse, joystick, touch-screen?)

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.

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

(!) 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)