Developing a Sphere-compatible engine
- 1 Notice
- 2 Introduction
- 3 Input
- 4 Output
- 5 Sphere-format file loading
- 6 The map engine
- 7 Maintaining API compatibility
- 8 List of Sphere-compatible engine implementations
- 9 See also
Possible frameworks to implement Sphere:
- SpiderMonkey v1.8.5
- Game Libraries
- Graphics libraries
- pixi.js / three.js
- DirectX (DirectDraw)
- hand-rolled software renderer.
- Audio libraries
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.
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.
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
Handling joystick input notes
Other input methods
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 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.
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.
Three separate versions with separate loading behaviors. Much more complicated than fonts, some reserved bytes, lots of metadata. (TODO: expand)
Two versions to handle. Some reserved bytes, some deprecated properties depending on version, small amount of metadata. (TODO: expand)
Lots of metadata, small amount of reserved bytes, can embed tilesets or refer to external tileset files. (TODO: expand)
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
The MapEngine loop
Maintaining API compatibility
Compatibility with 1.5
Compatibility with 1.6 beta
Compatibility with 1.7 alpha
Backwards-compatibility with pre-1.5
List of Sphere-compatible engine implementations
Complete or in-progress
|Implementation||Operating System||Version||JS engine||Video driver||Audio driver||Input handler|
|Win x86, OSX, Linux x86||stable: 1.5
unstable: 1.6 beta 4
inactive: 1.7 alpha
|Win x86/64, OSX, Linux x86/64, Solaris 10 amd64||0.4.0||V8||OpenGL via SDL2||BASS||SDL2|
|unnamed Sphere clone in SDL
|Win x86, OSX(?)||0.65 alpha||Jurassic||OpenGL via SFML 2||libsndfile via SFML 2||SFML 2|
|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|
Discontinued or abandoned