miniSphere 5.3.0

Merry Christmas! 🎄🎅

miniSphere 5.3.0 is the fourth release in the 5.0 series. This release brings back support for 32-bit Windows and comes with a host of new features and enhancements such as cell init, brand-new Core APIs, a new version of from.js rewritten from the ground up for maximum performance, support for loading .js as ESM, and many fixes for issues and bugs discovered since the previous release.

important note:
the .tar.gz tarball no longer includes ChakraCore binaries. to get these, first check if your distribution has a ChakraCore dev package available and install it if so; if not, then run sudo make deps from the miniSphere source directory to download the binaries from Microsoft and install them. you should only need to do this once.

What's New?

• Several APIs were canonized in this release (refer to the API documentation to see which ones) and the maximum supported API level increased to 2. If you put apiLevel: 2 in your manifest, your game will require miniSphere 5.3 or later. If you still want to support earlier versions, specify apiLevel: 1 in the manifest and test for newer APIs at runtime by checking the value of Sphere.APILevel.

• Cell's command-line syntax has been enhanced to support new commands. Notably, a few options have been promoted to full commands, e.g. cell -c is now cell clean. If you need a quick primer on the new syntax, you can type cell help on the command-line.

• New fromFile factory methods have been added to all built-in classes whose constructor accepts a filename. These methods return a promise for the new object, which allows assets to be loaded asynchronously in implementations where that is necessary.

• The from module has been rewritten for improved performance and along with several new query operators come some minor breaking changes. Query#skip is now called drop, Query#from is now called over and the iteratee for .first and .last is now treated as a mapping function rather than a predicate. As always, refer to the Sphere Runtime API documentation to get up to date on current API usage.

• import statements are now always treated as ES Module imports regardless of filename extension. If your game or Cellscript needs to load CommonJS modules and is now doing so using import, you will need to switch to using require().

• To improve end-user security and ensure the SPK package format is not a malware vector, it is no longer possible to relax or disable the SphereFS sandbox in production. The sandbox manifest field has been moved into a special development namespace which will only honored by SpheRun when running a game from a local directory. When using a relaxed or disabled sandbox during development, Cell will notify you when building for release that full sandboxing will be enforced in production.

• When executing a standalone .js or .mjs script from the command line, starting in miniSphere 5.3, you must use the spherun command. Standalone scripts are executed with the SphereFS sandbox disabled, so allowing the end-user engine to run them was identified as a potential security issue.

• New MouseKey event codes were added (MouseKey.Back, MouseKey.Forward), and therefore games written for API 1 will now end up seeing key codes they can't match to a known constant. This is a potentially breaking change if your game treats unrecognized event codes as an error. Instead of producing an error, unknown event codes should simply be ignored.

• SSj.assert has been added which lets you perform sanity checks during development without impacting performance in production. Expensive checks can be wrapped in an arrow function which will only be called when running the game using SpheRun.

• The obsolete assert and test modules have been removed from the Sphere Runtime in preparation for an upcoming API freeze in miniSphere 6.0. These modules were written based on old CommonJS specifications and don't really have a place in a modern JavaScript codebase.

• The undocumented scenelets (fadeTo, tween, pause, call) that were previously registered by default by the scene module have been removed. They had been retained for internal use, but the Scene API accidentally exposed them to user code. If you're currently using one of the scenelets listed above, you will need to implement their functionality yourself.

• DirectoryStream objects can now be initialized in recursive mode. In this mode, instead of listing subdirectories along with files, it will recursively descend into subdirectories to list the files in them. This provides a convenient way to find files at any level of a directory structure using a single DirectoryStream.

• When calling Transform#rotate and specifying a vector to rotate about, the provided vector is now normalized. This is a bug fix, but may be a breaking change if your game happened to rely on the previous behavior. If your rotations seem broken after upgrading to mS 5.3, this is probably why.

Full Changelog

• Adds support for games targeting API level 2, canonizing several Core APIs.
• Adds cell init to initialize a new Sphere source tree on the command line.
• Adds asynchronous asset loading functions, e.g. Sound.fromFile(), to improve cross-compatibility with Oozaru. Refer to the miniSphere 5.3 release notes for further information.
• Adds a pop-up message when pressing F12 to confirm a screenshot was taken.
• Adds Joystick.P1 through Joystick.P4, providing built-in default gamepad inputs for up to four players.
• Adds new async methods to Socket for performing connnections and I/O via the event loop, allowing a game to await the arrival of data and avoiding the need to explicitly check the state of the socket every frame.
• Adds SSj.assert to automatically verify assumptions made while coding.
• Adds Socket#noDelay which disables Nagle's algorithm for a connection.
• Adds Server#numPending, the length of a Server's connection backlog.
• Adds JSON.fromFile() for loading and parsing a JSON file in a single call.
• Adds Font#widthOf() and Font#heightOf() convenience calls.
• Adds a new parameter to FS.readFile to control how file contents are returned.
• Adds a new class to the from module, Query, which lets you prefabricate queries and run them as many times as you want on any source.
• Adds a new Sphere Runtime module, tween, for handling simple animations.
• Adds support for -h as an alias for --help for all command-line tools.
• Adds FS.directoryOf(), FS.extensionOf() and FS.fileNameOf() for taking apart path strings.
• Adds a new development manifest field to control behavior under SpheRun.
• Adds API support for the Back and Forward buttons found on modern mice.
• Adds a new option, recursive, for DirectoryStream, to include files in subdirectories.
• Adds apiVersion and apiLevel to the example Cellscript.
• Improves module handling; all import statements regardless of extension are now loaded as ESM code.
• Improves security by forcing full SphereFS sandbox enforcement in production.
• Improves security by disabling execution of bare scripts using minisphere.
• Improves BlendOp by making it into a class, allowing games to define their own custom blending modes.
• Improves performance of code using SSj namespace methods in production by avoiding unnecessary native calls.
• Improves performance of from() queries across the board.
• Improves bare-script execution by loading .js files passed on the command line as module code, allowing them to use import.
• Improves the performance of Transform#matrix, particularly on first-access.
• Improves first-access performance of Sphere.Game by avoiding an unnecessary JSON round-trip conversion.
• Improves Cell's command-line syntax. Many options have been replaced with easy-to-remember commands like cell build or cell pack.
• Removes the assert, delegate, joypad, and test modules.
• Removes several internal-use-only Scenario scenelets (fadeTo, call, playSound, tween) which sometimes clashed with game code wanting to use those names.
• Fixes a crash when calling MapEngine/FlipScreen from the main function.
• Fixes an issue where the cursor is hidden while sitting over the game window.
• Fixes an issue where FS.fullPath doesn't add a trailing slash when passed the path of a known directory.
• Fixes an issue where Socket#close disposes of the underlying socket object preventing it from being reused.
• Fixes a bug where the MULTIPLY blend mode is rendered the same as ADD.
• Fixes a bug where Cell puts dist/ in the PWD by default instead of in the directory of the project being built.
• Fixes a bug where calling Sound#play without passing a Mixer doesn't work.
• Fixes a bug where the vector passed to Transform#rotate is not normalized before calculating the rotation matrix, leading to unpredictable behavior.