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.

Possible frameworks to implement Sphere:

• JavaScript
  • V8
  • SpiderMonkey v1.8.5
  • Jurassic / IronJS / JavaScript.Net / Jinx
• 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.

List of Sphere-compatible engine implementations

Complete or in-progress

• vanilla Sphere (stable: 1.5, unstable: 1.6 beta 4, inactive: 1.7) (source)
  • JavaScript: SpiderMonkey
  • Video: configurable
  • Audio: configurable
  • Input: configurable
• TurboSphere (source, thread)
  • JavaScript: V8
  • Video: SDL2
  • Audio: SDL2
  • Input: SDL2
• unnamed Sphere clone in SDL (source, thread)
  • JavaScript: V8
  • Video: SDL
  • Audio: SDL
  • Input: SDL
• sphere-sfml (source, thread)
  • JavaScript: Jurassic
  • Video: Open GL (via SFML)
  • Audio: libsndfile (via SFML)
  • Input: SFML
• web-sphere (source, thread)
  • JavaScript: browser via pixi.js, three.js
  • Video: browser via pixi.js, three.js
  • Audio: browser via pixi.js, three.js
  • Input: browser via pixi.js, three.js

(TODO: convert above to table?)

(!) Although some engines are listed as compatible they will need a wrapper script to complete 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)