miniSphere 5.1.3

miniSphere 5.1.3 is a maintenance release. This release addresses several issues and adds support for ES2018 Promise#finally().

What's Changed?

• Adds support for Promise#finally() from ES2018.
• Improves the fatal error screen. The error message is displayed on a red background both for greater emphasis and to make it more immediately obvious that something went wrong.
• Improves error messages. The first letter of all error messages is now capitalized for consistency and several messages have been clarified to make them easier to understand.
• Fixes an issue where uncaught exceptions in async functions aren't picked up by SSj.
• Fixes an issue where using an async function as the main entry point (export default from main module) will cause the game to crash on startup with a TypeError.
• Fixes a bug which causes Music.adjustVolume() to throw a ReferenceError.
• Fixes a bug where Dispatch.now() jobs and promise continuations can run before the update phase instead of after it.

miniSphere 5.1.2

miniSphere 5.1.2 is a maintenance release. This releases improves exception handling for asynchronous code.

What's Changed?

• Adds a new logFileName option for new Console() allowing you to specify where the log file will be saved.
• Adds exception handling for promise-based (async) code: uncaught errors in async functions will now cause a game to crash, rather than being silently ignored.
• Cell will now package the entire #/ directory when making an SPK package.
• Logging is now disabled by default for Console objects.
• Fixes a bug where code in .then() continuations or async functions can end up running after a runtime error occurs, leading to strange behavior or even a hard crash.

miniSphere 5.1.1

miniSphere 5.1.1 is a maintenance release.

What's Changed?

• Fixes an issue where the engine can crash on startup when loading a game with circular module dependencies.

miniSphere 5.1.0

miniSphere 5.1.0 is the first minor update in the miniSphere 5.x release series. This release adds a few new APIs, bumps the API level to 2 and fixes several bugs discovered since the last release. Merry Christmas! 🎄🎁

Important Considerations

• Your game can now suspend and resume recurring Dispatch jobs using the new JobToken#pause() and JobToken#resume() APIs. Suspended jobs keep the event loop alive but won't be executed again until they are resumed.

• Thread objects now have .pause() and .resume() methods as well. Pausing a thread suspends its update and input jobs, but not its render job. This allows you to pause updates for an entity while still allowing it to be visible on-screen.

Changes in This Version

• Adds JobToken#pause() and JobToken#resume() methods to allow games to pause and resume Dispatch jobs at any time.
• Adds Thread#pause() and Thread#resume() methods.
• Adds index.mjs to the list of filenames recognized by the module loader.
• Adds a new predefined color, Color.StankyBean.
• Optimizes Surface and Texture size properties: .width and .height are now cached as own properties of the object after the first access.
• Fixes a bug where Sphere.restart() causes some things to be rendered in software afterwards, leading to massive slowdown.
• Fixes a bug in XML.readFile() which made the function completely unusable.
• Fixes a bug where SSj.log() logs "undefined" when passed an Error object with no stack trace.
• Fixes the Sphere Studio template after fallout from the Surface.Screen rename.

miniSphere 5.0.1

miniSphere 5.0.1 is a maintenance release in the miniSphere 5.0 release series. This release fixes several minor bugs and improves the behavior of SSj.log() and SSj.trace() when logging error and function objects.

What's Changed?

• Improves SSj.log() and SSj.trace() output for error and function objects.
• Fixes a bug where calling Exit() won't shut down the game if the built-in map engine is running.
• Fixes a bug where the source code of the mJS module shim isn't shown in SSj.
• Fixes a bug where calling Dispatch.cancelAll() can stop promise resolution.
• Fixes a bug where calling FocusTarget#yield() on an out-of-focus target can allow it to mysteriously regain focus later.

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.

miniSphere 4.8.8

miniSphere 4.8.8 is a maintenance release in the 4.8 release series. This release brings a few minor API changes which were backported from miniSphere 5.0.

What's Changed?

• Adds FS.evaluateScript(), used for loading Sphere v1 and browser scripts without having to fall back on the Sphere v1 API.
• Adds Image#width and Image#height properties.
• Adds SoundStream#length and removes SoundStream#bufferSize.

miniSphere 4.8.7

miniSphere 4.8.7 is a maintenance release in the 4.8 release series. This release fixes a major bug which prevented ~/ paths from working in Sphere 1.x code.

What's Changed?

• Fixes a bug where paths beginning with ~/ were incorrectly interpreted as referring to the save data directory in Sphere v1 code, leading to a runtime error.

miniSphere 4.8.6

miniSphere 4.8.6 is a maintenance release in the 4.8 release series. This release fixes a few bugs that could lead to engine crashes.

What's Changed?

• Fixes a bug where the backbuffer texture is freed prematurely, causing the engine to crash on shutdown.
• Fixes a bug where miniSphere can crash or behave strangely if it's unable to determine the desktop resolution on startup.
• Fixes a bug where miniSphere can crash after calling ExecuteGame() if the engine fails to reinitialize.

miniSphere 4.8.5

miniSphere 4.8.5 is a maintenance release in the 4.8 release series. This release improves windowed mode scaling and includes a backwards compatibility fix.

What's Changed?

• Improves Sphere 1.x backward compatibility by aligning small maps to the
  top-left of the screen instead of centering them, especially important for
  games using a render script.
• Improves the window scaling algorithm so that 320x240 games again run at 2x
  on 1366x768 displays.