miniSphere 5.2.0

miniSphere 5.2.0 is the third minor release in the miniSphere 5.x series. This version brings a ton of new API functions, lots of under-the-hood performance optimizations, profiling support in SpheRun, a zlib-based data compression API, PNG image manipulation in Cell, support for targeting a specific minimum API level, and much more--plus a ton of smaller enhancements and bug fixes.

Important Considerations

• SpheRun now supports profiling! Call SSj.profile() and pass it an object along with the name of a method and all subsequent calls to that method will be profiled. Then simply run your game with spherun --profile and When the engine shuts down, a table showing the profiling results will be printed to the terminal!

• Using the new Dispatch.onExit() API, or Thread#on_shutDown(), your game can set up cleanup code which will run before the engine closes. This makes it easier to implement autosave systems, for example, and can be used in both Sphere v1 and Sphere v2 codebases.

• Data compression is now supported as a first-class citizen of Sphere v2: Z.deflate and Z.inflate use the zlib DEFLATE compression algorithm, the same one historically used for Sphere v1's DeflateByteArray. These APIs are also available for use in Cellscripts!

• You can now read and write PNG images in a Cellscript, and even work directly at the pixel level, using the new Image API. Images are loaded as 32-bit RGBA to keep manipulation of individual pixels simple.

• Surface is now a proper subclass of Texture, allowing a surface to be used anywhere a texture is expected. This opens the door for awesome render-to-texture effects and avoids the cost of making a copy incurred by calling .toTexture.

• Textures can now be manipulated directly at the pixel level using the new Texture#download and Texture#upload methods. Keep in mind that these are both incredibly expensive so you probably don't want to call them every frame.

• Shape.drawImmediate has been added: this gives games the ability to draw vectorized primitives on-the-fly without the overhead of creating VertexList and Shape objects each time.

• The image module has been removed from the Sphere Runtime. Games currently depending on the Image class should switch to using Prim.blit instead.

Changes in This Version

• Adds support for passing command-line arguments to a game's main().
• Adds profiling support to SpheRun; call SSj.profile() and pass an object and method name to have all subsequent calls to that function timed and included in a detailed Performance Report on shutdown.
• Adds Image to the Cellscript API for manipulating PNG images at build time.
• Adds an apiLevel field to the JSON manifest format which allows you to specify the minimum Sphere v2 API level supported by your game.
• Adds a command-line option, --retro, used to emulate older API levels.
• Adds new APIs for data compression, accessible through the Z namespace and available to both Sphere games and Cellscripts.
• Adds Shape.drawImmediate() function which avoids the overhead of creating VertexList and Shape objects for immediate-mode drawing.
• Adds an experimental Surface#blendOp property for setting the blending mode for objects drawn to a surface, à la Sphere v1 surfaces.
• Adds Dispatch.onExit(), which lets you run code after the event loop exits.
• Adds Texture#upload() and Texture#download() to allow direct manipulation of a texture's RGBA bitmap.
• Adds Thread#on_shutDown() for running code when a thread terminates.
• Adds Pact#toPromise() for cases where you don't want to allow outside code to prematurely resolve a pact.
• Adds print() as an alias for SSj.log().
• Adds SSj.now() for getting microsecond-accurate timestamps under SpheRun.
• Adds the ability to use Surface objects as textures, without the need to call .toTexture() first.
• Adds long-overdue support for all Sphere 1.x Surface blend modes.
• Adds [Symbol.toStringTag] and .constructor for Sphere v2 objects.
• Improves font handling so that the default font can be loaded from an SPK package, avoiding the need to distribute the physical system/ directory.
• Improves the overall performance of all API functions and constructors.
• Improves performance for all Prim drawing functions.
• Renames the --performance command-line option to --profile to reflect its new purpose.
• Removes the pointless --no-sleep command-line option.
• Removes the Sphere Runtime Image class from the API.
• Fixes an internal memory leak mostly affecting Dispatch job execution.
• Fixes a bug in which calling FlipScreen(), DoEvents(), or MapEngine() after entering the event loop leads to a segmentation fault.
• Fixes a bug in which calling DoEvents() doesn't run promise reaction jobs.
• Fixes a bug where Sphere v1 Font#drawTextBox output isn't properly clipped.
• Fixes a bug where calling Sphere v1 exit functions or closing the game window can prevent promise reactions from running.
• Fixes a bug where the Sphere v1 Font#setCharacterImage() API fails to recalculate the font metrics after changing the image, causing text to be rendered incorrectly afterwards.
• Fixes a bug where repeating a list command in SSj could show some of the same lines again.

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.