V2 Migration

V2 is a rewrite and, therefore, introduces a lot of changes. But we have worked hard to keep the core experience similar to v1. This guide explains the differences with v1, what you need to know to start a new experiment, and how you might migrate your existing experiments.

Differences with v1

The significant difference is the backing technology: Empirica is no longer built on top of Meteor. It is a bespoke framework focused on experiment development. Day to day, this only changes things a little.

The empirica command

The command we use is now called empirica instead of meteor, but you still have an empirica create command to create a new project. And you start your development server by running the command without argument: empirica.

Code organization

We still have server/ and client/ directories. They are separate npm projects now. We used to have one package.json at the root of the project. Now both the client and server have their package.json, meaning they have their own npm dependencies. This is cleaner and easier in the long run. Also, in both directories, you will now see a subdirectory called src/, where all your code will reside. The base directory for the server and client is now only used for the configuration of each project.

Server-side

On the server, we have the same callbacks except for one: onGameInit is not called onGameStart (we already had an onGameStart that was not very used, and we have now merged them).

The arguments for each callback have changed a bit. We only pass the principal object for the callback. For example, onGameStart passes a Game object, and onStageEnd passes a Stage object. You can walk through the objects if you need to reach related objects. For example, if you need the Game object in a Stage callback (say onStageStart), you can do: stage.round.game. It follows the logical structure of the objects: batches > games > rounds > stages. Players for a game are on the Game object.

Client-side

On the client side, we are using a recent version of React, so you must learn about React Hooks.

The main objects (game, round, stage...) are no longer passed down between Components. Instead, you use the custom React Hooks provided by the empirica package. The main hooks are useGame, usePlayer (current player), usePlayers (all players in the current Game), useRound, and useStage. The initial template demonstrates how to use these.

Configuration for intro and exit steps, as well as Consent, NewPlayerForm, Loading, and NoBatches components, are now all done in the App.jsx. See the Special Empirica Components page for details.

Data

The database is no longer MongoDB. It is a single JSON file that resides in the .empirica/local directory, called tajriba.json (Tajriba is the name of our API Server). To back up or clear the database is simply a matter of copying or deleting that file.

We do not recommend reading that file directly, as the format for that file might change over time. Also, if you upgrade empirica, any previous tajriba.json file will be invalid with the newer version. Using the export command, you can still export the data from that file, even on a different version. However, we recommend exporting data before upgrading, then clearing the Tajriba file after the upgrade.

The empirica export is the preferred way to access the data. See Exporting the data for details about the export command.

Deployment

Deployment is no longer done in Meteor Galaxy. Deployment is much easier done manually than it used to be, but it is still very much manual at the moment. See the Deploying Your Experiment page for an example deployment. We are working on further simplifying deployment.

API changes

Game Init

You should make game initialization calls (addRound, addStage...) you used to make in onGameInit in onGameStart. Note that you can now add Rounds and Stages in any callback. For example, you can add a new Stage to a Round in onStageEnd. This allows for a dynamic number of Rounds and Stages. You could start by creating only 1 Round and 1 Stage in onGameStart, and add Stages and Rounds as needed during the Game.

Stage Submit

Stage submission is now done with player.stage.set("submit", true) (it used to be player.stage.submit()). And you can check whether the player has submitted the stage (the on client and server) with player.stage.get("submit") (it used to be player.stage.submitted). You can now cancel a player's submit status by setting "submit" to false player.stage.set("submit", false).

Game Treatment

Game treatment is no longer in game.treatment. It is now found in game.get("treatment").

Identifiers

Identifiers (IDs) are now .id (it used to be ._id). For example, you can do game.id (instead of game._id).

Migrating an existing experiment

The process of migrating an existing experiment is not automatic. If you do not need the new features of v2 and are done with developing your experiment, we recommend keeping it on v1. If you have just started or are about to start, moving to v2 is a good idea.

If you wish to convert your existing experiment, we recommend you create a new v2 experiment from scratch (see Creating your experiment).

Then, move over your callbacks, making sure to change the reference to your objects (see theServer-side section above).

On the client side, you will need to move over your configuration manually (intro/exit steps, component overrides... – see the Client-side section above). For Components, we recommend starting by migrating everything over as is and simply using the React Hooks on the very top Components and letting your existing Components pass down the main object (game, round...) as they used to in v1. Later you can migrate your components one by one to the new Hooks model for added clarity/simplicity (as well as improved performance). However, it is not a mandatory change!

Missing features compared to v1

There are a few known missing features compared to v1:

• Bot There is currently no bot system in v2. We have everything we need to implement a great bot system, we it's not there yet. We will release this as soon as possible. Let us know your use case in a ticket.

• Improved Admin There is, of course, an admin UI already in v2, but it could be more feature rich. We are working on improvements there. Again, if you have particular features you want to see, create a ticket with your experience so to help us prioritize what to work on first.

• Automated Deployment Deployment currently requires setting up a server manually. We want to make this experience much more accessible. We're working on it.