miniSphere 5.0.0

miniSphere 5.0.0 is the fifth major release of the miniSphere game engine. This release replaces Duktape with the blazing-fast ChakraCore JavaScript engine, brings native ES6 and mJS module support to Sphere for the first time, and includes a great many API refinements, under-the-hood enhancements and optimizations!

Windows users:
Please uninstall any previous version of miniSphere before installing miniSphere 5.0. A great many files were moved or renamed; uninstalling old versions first ensures stale files from the previously installed version will be deleted that would otherwise interfere with the new version.

Important Considerations

• As of miniSphere 5.0.0, the Core API has been frozen. Going forward, no further breaking changes will be made to the Core API and games written against it will continue to function as-is in future versions. This freeze does not apply to the Sphere Runtime!

• miniSphere now uses ChakraCore for blazing-fast JavaScript performance. Chakra is the same engine used in Microsoft Edge and supports most modern JavaScript syntax natively, so you no longer need a transpile() step in your Cellscript to take advantage of ES2015+ features such as arrow functions, destructuring, even await!

• Thanks to the introduction of async and await, the event loop is now a first-class part of the Sphere development experience. To that end, all Sphere v2 functions dedicated the old blocking style have been removed or refactored: both Sphere.run() and screen.flip() are gone, and Sphere.sleep() has been changed to return an awaitable promise instead of blocking the caller.

• mJS modules are now supported natively, without a transpiler. This allows you to use import and export to organize your codebase into self-contained modules without the added complexity of CommonJS. require() has in fact been deprecated and is now provided only for interop with transpilers such as Babel and modules originally written for Node.js. New code should always use the ES2015 module syntax (import/export) and the .mjs file extension.

• The entire Sphere Runtime was overhauled and is now written entirely in mJS. This brought several breaking changes both major and minor. The big changes are listed below, but be sure to review the API documentation to get fully up to speed!

• Because ES2015+ syntax is now supported natively, the Cell Runtime transpile module has been cut. If you're currently using it in your build, you can simply change your Cellscript to use install() in place of transpile() and everything should work as before.

• screen was renamed to Surface.Screen, and the custom screen methods have been moved into the Sphere namespace. So screen.frameRate becomes Sphere.frameRate, etc.

• Dispatch.onUpdate() and Dispatch.onRender() now take an options object as their second parameter. Job priority is now be specified as a property of the options argument and defaults to 0.0 if not provided, as before.

• DataReader and DataWriter have been combined into a single class, DataStream, which inherits from FileStream. This makes it easier to use as it's no longer necessary to construct a FileStream separately. Naturally, any code using the old classes will need to be updated to work with the new class.

• The Console object has been refactored into a full-fledged class. This allows an in-game console to be set up using explicit new Console() syntax rather than the somewhat awkward Console.initialize(). It also makes it possible to create multiple consoles, in case that's ever needed. Existing code using the Console object will need to be updated.

• The new FocusTarget class provides a centralized mechanism for managing input focus. Only one focus target can have the focus at any given time, making this very well-suited to managing input focus in, e.g., menu systems and map engines. Just import FocusTarget from sphere-runtime to try it!

• The Pact class has returned and provides a convenient way to make promises and settle them out-of-band without the awkwardness of working around the promise closure. As long as you have a reference to both the Promise object and the Pact it came from, you can resolve or reject it at any time.

• Scene#run() now returns a promise that can be awaited and never blocks. The boolean parameter that specified whether or not to block until completion has been removed; if you want a scene to run in the background, simply ignore the promise.

• Thread.join() is no longer a blocking call and instead returns a promise that can be awaited. This allows any thread to await termination of another without delaying other threads, regardless of how many joins are already underway.

• A new sandbox field in the JSON game manifest can be used to relax the SphereFS sandbox in order to ease development. The default is a full sandbox as before; 'relaxed' allows use of absolute paths and write access to the game directory, while 'none' disables the sandbox completely.

• Sphere.exit() has been replaced with Sphere.shutDown(). Unlike the former function, Sphere.shutDown() does not exit immediately but rather cancels all outstanding Dispatch jobs, allowing the event loop to unwind naturally on the next tick.

What's Changed?

• miniSphere and Cell now use the ChakraCore JS engine under the hood, vastly improving JavaScript execution performance and bringing long-overdue native support for ES2015+ syntax and built-ins to Sphere.
• Overhauls the entire Sphere Runtime to take full advantage of the event loop as well as modern JavaScript features such as classes, async functions, and promises.
• Adds native support for ES2015+ syntax and mJS modules without transpilation.
• Adds back the Pact class, a more intuitive way to manage promises.
• Adds a new FocusTarget class as a centralized means to manage input focus.
• Adds a new DataStream class, which extends from FileStream to allow more easily reading binary data such as integers and strings from a file.
• Adds Sphere.shutDown() which initiates an asynchronous exit.
• Adds a new inBackground option for Dispatch jobs, for setting up background tasks that shouldn't keep the event loop alive by themselves.
• Adds an optional sandbox field to game.json which can be set to either relaxed or none to relax the file system sandbox and ease development.
• Adds SSj.flipScreen(), useful for debugging rendering code.
• Adds a [Symbol.iterator] to DirectoryStream, allowing directory contents to be enumerated using a standard for...of loop.
• Adds a new --performance command line option for SpheRun which disables the stepping debugger to ensure JavaScript code runs at full speed.
• Adds fullScreen manifest field to specify a game's default fullscreen mode.
• Adds support for quick refs to SSj: when using examine, this assigns a numeric handle to each object in the result, which you can quickly drill into by typing, e.g., x *123.
• Adds Sphere.Compiler which evaluates to the name and version number of the compiler used to build the current game.
• Changes Sphere.sleep() to return a promise instead of blocking, allowing it to be used with await so as to avoid starving the event loop.
• Changes Console into a full-fledged class, which allows for a familiar new Console() usage and gives games the ability to set up multiple consoles if desired.
• Changes RNG to be compatible with the ES2015 iterator protocol.
• Changes SSj namespace functions to be no-ops in the redistributable engine.
• Changes SSj.log() to perform JSON serialization if its argument is an object.
• Changes SSj commands eval, examine to not require quoting the expression.
• Renames screen to Surface.Screen and moves the custom screen properties into the Sphere namespace.
• Renames from.Array() and from.Object() to lowercase to match typical JavaScript naming conventions.
• Renames screen.frameRate and screen.now() to Sphere.frameRate and Sphere.now(), respectively.
• Renames Dispatch.cancel() to JobToken#cancel().
• Renames Color#fade() to Color#fadeTo().
• Renames Keyboard#getChar() to Keyboard#charOf().
• Renames fragment and vertex Shader constructor options to fragmentFile and vertexFile, respectively.
• Removes the experimental Person class from the Sphere Runtime.
• Removes the now-redundant DataReader and DataWriter classes.
• Removes screen.flip(), Sphere.run() and Sphere.exit() in favor of the engine-provided event loop.
• Removes the Cell transpile module in favor of promoting native ES2015.
• Improves the startup routines to also look in dist/ for a bundled game.
• Improves the SSj debugging experience by preventing the engine from switching to fullscreen mode as long as the debugger is attached.
• Improves internal handling of UTF-8 strings, fixing several bugs related to text encoding. Notably, FS.readFile() now correctly handles the UTF-8 signature/BOM if one is present.
• Improves error reporting. SpheRun now prints a complete JavaScript backtrack to the terminal when a JavaScript runtime error occurs.