The Enhanced Module Management Application (EMMA) is an attempt to address a burr under my saddle, namely the crap-shoot that is Update All in Foundry VTT, especially around periods where Foundry core, game system updates, and modules are all being updated.
EMMA comes in two parts:
- EMMA Module is a Foundry VTT module that takes over the Module Management button (it can be turned off, returning control to the default module management application, while still maintaining the data needed by EMMA Setup). The EMMA module can be used on its own.
- EMMA Setup is a browser extension (Chromium and Firefox) that adds a new EMMA button to the Foundry Setup screen. This opens the EMMA Setup extension that provides a much more powerful module installation and updating system to Foundry VTT. The EMMA Setup requires EMMA Module be installed in the Foundry VTT instance (it does not have to be active in any worlds but you really should have it active in all worlds otherwise EMMA Setup cannot perform at its best).
Heads-up
For efficiency, EMMA sends a list of your installed modules and their versions to a catalogue server (https://catalogue.mondarth.com). This information is used to find available updates and is not stored.
EMMA Module
The EMMA module, by default, takes over the Module Management button on the settings tab. Once opened you can choose either tree view of split view. These views are designed with minimal clutter, all details for each module are hidden by default in a drawer that can be toggled with a disclosure caret at the right end of a module’s entry. The contents of this drawer can be customised by each user in EMMA’s Settings.
If you prefer to use the default Module Management the EMMA interface can be disabled in EMMA’s Settings. When disabled (rather than deactivated) EMMA will still maintain the data file used by the EMMA Setup application but will no longer open from the Module Management button.
EMMA has a ‘hypothetical’ mode, accessed by toggling the flask icon on the left side of the toolbar. Any actions taken while in Hypothetical Mode (HM) have no lasting effect, everything resets when you exit HM. While in HM you can activate and deactivate modules and select different versions of modules, the game system, and the Foundry VTT core in order to see if these changes ‘work together’. Alternatively, you can just ask EMMA to work out the best versions of each module, the game system, and core (best, in this context, means the highest version that maintains compatibility). EMMA module works with only the world in which it is active—EMMA Setup works across your whole Foundry VTT installation.
Safety first
In hypothetical mode ALL changes revert on exit.
Outside hypothetical mode modules can be activated and deactivated and then only when you save your selected configuration, just as with the default module manager.
EMMA Setup Extension
EMMA Module is cool, but EMMA Setup is awesome!
EMMA changes the workflow of module installation in Foundry VTT. With EMMA you first create a plan, then you execute that plan. This two step process is used because planning EMMA ensures that each chosen module, game system, and core combination works across all of your installation (assuming you have install EMMA module in each of your worlds).
The best option is to let EMMA figure everything out. Select the Foundry VTT root of the tree browser then in the right panel click ‘Plan the best versions’. EMMA will work out which combination of core, game systems, and modules will work together across all of your current game worlds.
EMMA makes it deliberately difficult to create a plan that causes a world to break or lose access to a module due to incompatibility. To force EMMA to create a bad plan you typically have to deny access to a worlds current state (by not activating EMMA module in the world) or explicitly tell it to ignore a world or module when planning.
You can lock or pin certain features so the plan will not choose newer versions. This is particularly useful if you do not want to update your Foundry VTT core or one or more game systems but still want to find the most recent versions of modules compatible with your existing installation.
The difference between locking and pinning: locking provides access to Foundry’s own Locked state (only the currently installed version can be locked and it will be locked by Foundry too), pinning is an EMMA only way to tell EMMA that you want a specific version of the core, game system, or module to be put into the plan. Adding locks or pins constrains EMMA and you should avoid them unless there is a very specific reason to force a particular version.
EMMA makes module requires relationships mandatory, again in an effort to maintain consistency. It also provides detailed feedback on why specific versions cannot be selected.
EMMA also performs these compatibility checks for new installs. If the latest version of a module you select is incompatible with your current plan then EMMA will try to find an earlier version of the module, that is compatible, to install. If none is available, EMMA will say so and explain the problem.
EMMA tries to find all versions of a module, even those released by the author but not yet published to the Foundry VTT package index (these are marked with a flask in their version badge to indicate that they are potentially experimental).
Limitations
EMMA ultinately uses Foundry’s own package installation, so EMMA cannot break Foundry’s own rules (these tend to be less constraind than EMMA, so they are unlikely to cause any issues).
EMMA works of data provided by package authors in the system.json or module.json, as such bad information in these will result in issues in EMMA. One particular issue is where multiple ‘versions’ in the Foundry index all point to the same module.json. EMMA will reject any module.json that does not ultimately specify a version matching one being offered. This means the Foundry index may list a dozen versions but if they all point to one module.json then only the version in the module.json is ‘seen’ by EMMA all of the others are invalid and pruned resulting in gaps.
Safety first
EMMA makes no changes to your system until you confirm the plan’s run and EMMA uses Foundry’s own internal package installation to install the specific system.json and module.json files listed in the plan.
EMMA cannot update your Foundry VTT core version when --noupdate is set. It will stop the plan run and tell you to update your core. When you start yous new core EMMA will pick up the plan on the next step. If it does attempt an ‘in-place’ update it uses Foundry’s internal update mechanism and will succeed or fail accordingly.
Feedback
Additional information available on the documentation site.