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.
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 command we use is now called
meteor, but you still have an
empirica createcommand to create a new project. And you start your development server by running the command without argument:
We still have
client/directories. They are separate npm projects now. We used to have one
package.jsonat 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.
On the server, we have the same callbacks except for one:
onGameInitis not called
onGameStart(we already had an
onGameStartthat 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,
onGameStartpasses a Game object, and
onStageEndpasses 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.
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
usePlayers(all players in the current Game),
useStage. The initial template demonstrates how to use these.
The database is no longer MongoDB. It is a single JSON file that resides in the
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.jsonfile 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.
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.
You should make game initialization calls (
addStage...) you used to make 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 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
Game treatment is no longer in
game.treatment. It is now found in
Identifiers (IDs) are now
.id(it used to be
._id). For example, you can do
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.
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!
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.