2.2.0

2.2.0

This is one of our biggest releases of Epicenter.js in a while. It includes:

• Several major changes to the run strategies and Run Manager.
• A new Scenario Manager for working with time-based projects involving run comparisons.
• A new Presence Service for tracking end users status (online, offline) in multiplayer games.
• A change in the jQuery version required.
• Several bug fixes.

Run Strategy Changes: Consolidating Strategies

Over time we've added a lot of strategies to Epicenter.js to cover different use cases; as our platform grew, some of those strategies became redundant, and made it more difficult to choose which strategy to use. We're addressing this with some efficiency and usability improvements across strategies, namely:

Renamed Strategies

The following strategies have been renamed for clarity:

• persistent-single-player has been renamed to reuse-across-sessions
• always-new has been renamed to reuse-never
• new-if-missing has been renamed to reuse-per-session

The older names will continue to work, but may be removed in a future release.

Deprecated Strategies

The following strategies are now considered deprecated:

• new-if-initialized: All runs now default to being initialized by default, making this redundant.
• new-if-persisted: The Run Service now sets a header (the autoRestore configuration option) to automatically bring back runs into memory, making this redundant.

You can still use these strategies, but they may not accomplish what you expect, and will be removed in a future release.

New 'reuse-last-initialized' Strategy

This release adds a new reuse-last-initialized strategy. It is intended to be a more flexible replacement for the new-if-initialized strategy (which is now deprecated).

This strategy looks for the most recent run that matches particular criteria; if it cannot find one, it creates a new run and immediately executes a set of "initialization" operations.

Examples:

• You have a time-based model and always want the run you're operating on to be at step 10:

       var rm = new F.manager.RunManager({
           strategy: 'reuse-last-initialized',
           strategyOptions: {
               initOperation: [{ step: 10 }]
           }
       })

• You have a custom initialization function in your model, and want to make sure it's always executed for new runs.

strategyOptions is a field you can generally use to pass options to different strategies; while reuse-last-initialized is currently the only strategy which uses it, you can also use this field when creating your own strategies.

Summary

The benefit of this consolidation is that deciding what strategy to use easier than ever:

• reuse-per-session: You reuse the same run until each time you use the Authentication Manager to log out; you get a new run the next time you log back in. Useful for projects designed to be completed in a single session.
• reuse-across-sessions: You reuse the same run until it is explicitly reset. Useful for projects designed to be played across a multiple sessions.
• reuse-never: You get a new run each time you refresh the page.
• multiplayer: The only strategy available for multiplayer projects. A run is shared by the end users in a multiplayer world.

Run Manager Changes

New in this release, there are several changes to the Run Manager, primarily to support Run Strategy changes (described above) and the new Scenario Manager (described below).

getRun Allows Populating Run with Variables

The Run Manager's getRun function now takes in an array of variables as an argument; if provided, it populates the run it gets with the provided variables.

    rm.getRun(['Price', 'Sales'], function (run) {
        console.log(run.variables.Price, run.variables.Sales);
    });

Note: The getRun method will NOT throw an error if you try to get a variable which doesn't exist. Instead, the variables list is empty, and any errors are logged to the console.

Better Validation

The Run Manager now catches common errors, such as passing in invalid strategy names, or missing run options.

More Context Available for Strategy Implementations

The original purpose of the Run Manager was to just find the right strategy and call it, leaving all the 'heavy lifting' (e.g. of authentication) to each individual strategy. Now, the Run Manager does more work up front and just passes in the appropriate information to each strategy, namely:

• Each strategy is mandated to have getRun() and reset() functions. These functions were initially called by the Run Manager with no arguments, but now their signature is:

/**
 + Gets the 'correct' run (the definition of 'correct' depends on strategy implementation)
 + @param  {RunService} runService A Run Service instance for the 'correct' run as determined by the Run Manager
 + @param  {Object} userSession Information about the current user session. See AuthManager#getCurrentUserSession for format
 + @param  {Object} runSession The Run Manager serializes the 'last accessed' run in a cookie and provides it each time `getRun()` is called
 + @return {Promise}             
 */
getRun: function (runService, userSession, runSession){}


/**
 + Resets current run
 + @param  {RunService} runService  A Run Service instance for the 'correct' run as determined by the Run Manager
 + @param  {Object} userSession Information about the current user session. See AuthManager#getCurrentUserSession for format
 + @return {Promise}             
 */
reset: function (runService, userSession){}

• The run returned by the getRun() method is now serialized and stored in a session by the Run Manager, taking over the burden of session management from the individual strategies. This run is provided as a parameter to the next call to strategy.getRun(); the strategy can opt to validate this run (based on run id or any other parameters) and return it, or ignore it altogether depending on its goal.

• Each strategy can register itself as requiring authentication or not (see next section for how to register); if a strategy does so the Run Manager takes care of ensuring there's a valid user session before any of the methods on the strategy are called. This moves the responsibility from the strategy to the Run Manager. The strategy can still opt to handle this itself by not declaring requiresAuth, and do its own validation of the userSession object which is passed to its getRun() and reset() methods.

F.manager.RunManager.strategies

You can access a list of available strategies via F.manager.RunManager.strategies.list.

This behavior mirrors getting the list through F.manager.strategy; however, F.manager.strategy is now considered Deprecated and may be removed in a future release.

The F.manager.RunManager.strategies.register() interface now introduces a new way to register named Run Strategies for use with the Run Manager. Note you can still bypass registering by calling the RunManager with a function, i.e., new F.manager.RunManager({ strategy: function(){}}), so this is a backwards compatible change which just additionally allows naming.

See the run strategies page for more on strategies.

Scenario Manager

This release introduces a new Scenario Manager, accessible as F.manager.ScenarioManager.

Each Scenario Manager allows you to compare the results of several runs. This is mostly useful for time-based models (Vensim, Powersim, SimLang, Stella), but can be adapted to working with other languages as well.

The Scenario Manager can be thought of as a collection of Run Managers with pre-configured strategies. Just as the Run Manager provides use case -based abstractions and utilities for managing the Run Service, the Scenario Manager does the same for the Run Manager.

There are typically three components to building a run comparison:

• A current run in which to make decisions;
• A list of saved runs, that is, all runs that you want to use for comparisons;
• A baseline run to compare against (optional).

See the Scenario Manager docs for examples and more details.

To satisfy these needs a Scenario Manager instance has three Run Managers:

Baseline

var sm = new F.manager.ScenarioManager();
sm.baseline // An instance of a Run Manager with a strategy which locates the most recent baseline run (that is, flagged as `saved` and not `trashed`), or creates a new one.
sm.baseline.reset() // Reset the baseline run. Useful if the model has changed since the baseline run was created.
sm.baseline.getRun() // Typical Run Manager operation which retrieves the baseline run.

If you don't need a baseline for your particular case, you can disable auto-creation of baseline runs by passing in includeBaseline: false to your Scenario Manager options.

Current

var sm = new F.manager.ScenarioManager();
sm.current // An instance of a Run Manager with a strategy which picks up the most recent run (`unsaved` implies a run which hasn't been advanced)
sm.current.reset() // Reset the decisions made on the current run
sm.current.getRun() // Typical Run Manager operation which retrieves the current run

The current Run Manager also has an additional utility method saveAndAdvance. This method clones the current run, then advances and saves this clone (it becomes part of the saved runs list). The current run is unchanged and can continue to be used to store decisions being made by the end user.

Saved Runs

var sm = new F.manager.ScenarioManager();
sm.savedRuns // An instance of a Saved Runs Manager

The savedRuns manager gives you utility functions for dealing with multiple runs (saving, deleting, listing). See more information on saved runs, or the Scenario Manager docs for examples and more details.

Presence Service

The Presence API Service provides methods to get and set the presence of an end user in a project, that is, to indicate whether the end user is online. This happens automatically: in projects that use channels, the end user's presence is published automatically on a "presence" channel that is specific to each group. You can also use the Presence API Service to do this explicitly: you can make a call to indicate that a particular end user is online or offline. See complete details on the Presence Service and also the updated Epicenter Channel Manager's getPresenceChannel().

jQuery Version Requirements

Starting in Epicenter.js 2.0, we introduced support for jQuery 3.1.0. Changes are backwards compatible, so you could use either jQuery 2.1.4 (as for previous releases of Epicenter.js) or jQuery 3.1.0.

Epicenter.js 2.2.0 introduces breaking changes, however, so for Epicenter.js 2.2.0 and later, jQuery 3.1.0 or later is required.

Bug Fixes

This release also includes several bug fixes.

Run Manager's current instance of the run is always valid/up-to-date.

The 'current run service' of the Run Manager can be accessed through rm.run; however, this was buggy in previous releases. This has been fixed. For instance:

    var rm = new F.manager.RunManager();
    var id = rm.run.getCurrentConfig().id; //assume id 1
    rm.reset().then(function () {
        var newid = rm.run.getCurrentConfig().id; //should be 2 but used to return 1 before
    })

runService.query() and runService.filter() return empty arrays for no results.

Due to a quirk in the Epicenter platform, in previous releases, runService.query() and runService.filter() returned an array of runs if they found any, or an empty Object ({}), if no matching runs existed. These methods now correctly return empty arrays. However, this may be a Breaking Change if you were relying on the older behavior.

runService.serial() and runService.parallel() return arrays as callback parameters.

Previously, the callback parameter for runService.serial() or runService.parallel() contained only the result for the most recently executed operation. Now, the parameter to the callback is an array. Each array element is an object containing the results of one operation.

Channel calls respect version

All calls to the cometD channel now respect the versionPath of the rest of the Epicenter.js library.