Version 1.7.0

[1.7.0] - 2023-01-16

This version has been postposed a while, but adds several powerful features. A dependency system, support for zipped mods (on both desktop and HTML5!), reworks to versioning functions, and more.

Added

• Added the dependencies key to the ModMetadata format.
  • Example: {"modA": "1.0.0", "modB": "3.*", "modC": "1.9.0 - 2.3.0"}
    • Add an object of key/value pairs to your _polymod_meta.json file, where the key is the mod ID and the value is the version rule.
    • Version rules can match any of those seen in node-semver.
  • Mods provided in the dependency list must be loaded in order for this mod to be loaded.
    • The provided mod list will be reordered to account for dependencies, as needed, and maintaining order otherwise.
    • Missing dependencies, mismatched dependency versions, or cyclical dependencies will result in an error. See skipDependencyErrors for more info.
• Added the optionalDependencies key to the ModMetadata format.
  • Mods provided in the optional dependencies list will reorder the dependency list, but will not cause dependency errors if absent.
• Added the skipDependencyChecks parameter to Polymod.init().
  • Defaults to false.
  • Setting this option to true will skip checks for the presence of mandatory dependencies, and prevent reordering the mod load list.
  • Enabling this option is NOT recommended, since it may break mods which rely on their dependencies.
• Added the new ZipFileSystem.
  • Enable it with Polymod.init({customFilesystem: polymod.fs.ZipFileSystem}).
  • On desktop platforms, ZipFileSystem automatically behaves like SysFileSystem with the additional capability of loading mods from ZIP files (compressed or uncompressed) as though they were folders instead.
  • On HTML5 builds, ZipFileSystem will instead act like a MemoryFileSystem which can load a mod when provided the byte data of a ZIP file.
    • After loading mods, you may need to wait a short time before reloading any images. This is because the browser must asynchronously preload the image data before it can be provided to Haxe.
• Added a convenience functions to handle loading and unloading of mods at runtime.
  • loadOnlyMods() loads a given set of mods, by re-initializing the framework with the appropriate mods enabled.
    • This is as opposed to loadMods(), which appends to the mod list rather than setting it.
  • Note you may need to call clearCache() depending on your framework and your app's current state.
• Added import aliasing and blacklist system for scripted classes.
  • Call Polymod.addImportAlias('full.class.Path', TargetClass) to replace any instances of that import with the target class.
  • Call Polymod.removeImportAlias('full.class.Path') to remove a previously assigned import alias.
  • Call Polymod.blacklistImport('full.class.Path') to throw an error whenever a scripted class attempts to import the chosen module.
• loadMod(), unloadMod(), loadMods(), and unloadMods() now return an array of ModMetadata for each of the mods that are loaded after the operation.
• Added the skipDependencyErrors parameter to Polymod.init().
  • Defaults to false.
  • While this option is true, any dependency issues will cause a warning to be reported, and Polymod will skip the problematic mods and load the rest.
  • While this option is false, any dependency issues (missing dependencies, mismatched versions, or cyclical dependencies) will cause an error to be reported, and Polymod will initialize with NO mods loaded.

Changed

• thx.semver has been added as a mandatory dependency Haxelib, replacing the existing Semantic Version code.
  • This provides full support for the features of node-semver when specifying version rules.
• Updated openfl sample to showcase dependency features.
  • mod2 now has a mandatory dependency on mod1.
  • Added a button to showcase the difference when skipDependencyErrors changes.
• Polymod.scan() has been refactored.
  • scan() now has two modes; the first, used when a parameter object is provided, uses the modRoot and fileSystem given.
    • This will supercede the modRoot and fileSystem that was used for Polymod.init().
  • The second mode, used when a parameter object is not provided, utilizes the filesystem created in Polymod.init().
    • If you want to scan the modlist before loading mods, you can initialize Polymod with an empty modlist before scanning, then use loadMods() to reinitialize with additional mods.
    • If no parameters are provided but init() has not been called yet, an error will be thrown.
• Updated samples to use the hmm dependency management tool.
  • Install hmm via Haxelib, then run hmm install in a sample project to install project-local copies of all necessary dependencies with the correct version.
• IFileSystem.scanMods() has been refactored.
  • scanMods now takes an optional apiVersionRule parameter, and returns Array<ModMetadata>.
  • scanMods will now parse and return the mod metadata, rather than returning an array of mod IDs.
  • scanMods will now optionally filter to only mods which match the provided apiVersionRule (pass null to skip this).
• Reworked error codes for script-related exceptions and warnings.

Removed

• Several deprecated and obsolete options and variables related to this update's changes have been removed.
  • Removed the SemanticVersion utility class.
  • Removed the apiVersionMatch option from PolymodConfig.
  • Removed the POLYMOD_API_VERSION_MATCH define.
  • Removed the modVersion parameter of Polymod.init

Fixed

• Fixed several compilation issues with hscriptPos disabled.