# Introduction Easy Multiplayer Interactive Experiments in the Browser {% hint style="success" %} This documentation is for Empirica v2. If you want to see the documentation for Empirica v1, head over to [https://docsv1.empirica.ly](https://docsv1.empirica.ly/). Note about the name `v2`. This is the second major version of Empirica after a complete re-write. But, confusingly, the main npm package for empirica v2 (@`empirica/core`) is currently numbered with `1` (i.e.: v1.x.y), because we're using a new package name. Sorry for the confusion. {% endhint %} Empirica is an open-source JavaScript framework for running multiplayer interactive experiments and games in the browser. Empirica makes it easy to develop and iterate on sophisticated designs in a statistically sound manner. It offers a unique combination of power, flexibility, and speed. Empirica is a powerful framework that facilitates the management of your games and experiments and is useful even for single-player research. Empirica uses industry-standard open-source technologies (Go, GraphQL, Typescript, Javascript, React) Empirica provides a helpful structure to how your Games, Players, Rounds, and Stages interact. Furthermore, Empirica gives you an Admin Panel that makes organizing and running your Games for data collection easy and intuitive. Empirica is the one method that provides enough flexibility to build any experiment while still being accessible and helpful to the researcher. ### Quick start More details can be found on [#quick-start](#quick-start "mention"). If you just want to get on with it: ``` curl -fsS https://install.empirica.dev | sh empirica create myexperiment cd myexperiment empirica ``` ### I want to use Empirica. Where do I start? Visit the [Getting Started](/getting-started/setup) part of this documentation to get you started. Follow our [first experiment tutorial](https://github.com/empiricaly/docsv2/blob/main/guides/tutorial-your-first-experiment/your-first-experiment.md). To learn more about the parts of an Empirica app (e.g., what are Games, Rounds, and Players?) visit the [Concepts](/overview/concepts) page. ### What skills do I need to use Empirica? Empirica helps you build online apps for online research. As with many online tools, basic notions of HTML, CSS, and JavaScript will be helpful. Knowing a bit about React.js can also be beneficial, although you do not need to be an expert. There are many tutorials online for all the technologies mentioned here. ### Why should I use Empirica instead of just Node.js and React.js directly? While Node.js and React.js are powerful tools, and you could build sophisticated experiments with them, Empirica makes building and managing your experiments much easier. Notably, Empirica provides an Admin Panel that allows you to manage the conditions of your experiments (Treatments and Factors) and which Games are running, collecting data, or waiting for players. Empirica does the heavy lifting in managing games, player connections, game life cycles, and more. ## What's new with Empirica v2? Empirica v2 is a major departure from v1. It goes well beyond a few API changes since we have completely rebuilt Empirica from the ground up with new technologies. Here are a few key elements of the change: * **New Features!** We have introduced a bunch of new capabilities. We are still working on the documentation, but here are a couple of examples of what's now possible: * Custom assignments: we have opened up the entire assignment flow. You can hook in anywhere and do all kinds of fun new assignment logic. * (Re-)Assignment to ongoing games: players can join ongoing games. They can also be reassigned between games. * **Developer UX** Loading is fast; changes refresh instantly; we use standard npm libraries; the empirica command helps through the development process, etc. We have built a strong foundation and have only started the developer experience improvements. * **New Technologies** We are still using open-source technologies, but we no longer rely on Meteor.js. We have built a custom framework with a GraphQL server in Go. The backend is still on Node.js, though we no longer use Fibers, a deprecated Node.js technology used in Meteor. And we are up to date with React v18+ on the frontend. * **Open Architecture** We have purposefully centered our design on a Graphql API. We are not locked into one language or framework. We currently support a Node.js backend and a React front. But someone could develop a python backend to integrate with their existing libraries and a Flutter frontend to build a mobile app. {% hint style="info" %} To learn more about Empirica v2's differences and how to migrate to v2, see our v2 migration guide. {% endhint %} # Setup 1. Run the installation script: ```sh curl -fsS https://install.empirica.dev | sh ``` That's it, you're done! Proceed to create your experiment: {% content-ref url="/pages/-M-DU6peo0\_R4jW1X\_mJ" %} [Creating your experiment](/getting-started/quick-start) {% endcontent-ref %} {% hint style="info" %} #### Running an older version? If you are running on an older version and are encountering version issues, try running the curl command above again. It should reset your local install. {% endhint %} {% hint style="success" %} #### Upgrading To upgrade the empirica command globally on your machine, you can either run `empirica upgrade --global` outside of any projects, or run the curl command above again. {% endhint %} {% hint style="warning" %} #### Volta error Some users have been seeing a Volta error that prevents empirica from properly managing node (here: ). It can be resolved it by installing the right versions of node manually and removing the `volta` lines from `client/package.json` and `server/package.json`. {% endhint %} ### **A note about Windows Setup** {% hint style="warning" %} Windows is currently not natively supported. Empirica does work on Windows with Microsoft's WSL 2. {% endhint %} {% hint style="danger" %} The installation of WSL 2 has been greatly simplified since Windows 10 version 2004, released at the end of 2021. Windows 11 also benefits from the new much simplified procedure. The following documentation does not cover the new installation. If you are using Windows 10 2004 and higher, we recommend you look online how to install WSL 2, then you can follow the macOS/Linux procedure above. {% endhint %} Empirica is built on industry-standard open-source web technologies which run best in Unix-like operating systems such as Linux and macOS. \*\*\*\* *If you are a Windows user and get stuck at any point in the development process, please contact or join the* [*Slack channel*](https://join.slack.com/t/empirica-ly/shared_invite/zt-1fb34yq47-YlgYUJmXJAdv7QmHsa_fdw) *for community-based technical support on a wide range of topics.* {% content-ref url="/pages/-MQFm\_OhGD0ymKg\_sz4z" %} [Windows WSL Instructions](/getting-started/setup/windows-instructions) {% endcontent-ref %} # Windows WSL Instructions (new) Updated version of WSL? If you have not already done so, **install** [**Windows Subsystem for Linux (WLS)**](https://learn.microsoft.com/en-us/windows/wsl/) by opening your terminal and running: ``` wsl --install ``` Now you may be prompted to create a username and password. Make sure to write down your login credentials for the future! Note: Copying and pasting may be disabled in the default settings of your WLS terminal. To remedy this, right-click the title bar and select 'Properties --> Options --> Use Ctrl+Shift+C/V as Copy/Paste.' **Install Empirica** in your WSL terminal with the following command. You may be prompted to use the WSL password you just created. ```sh curl https://install.empirica.dev | sh ``` 🎉 Congrats, you've now installed Empirica! 🎉 # Windows WSL Instructions ## Step 1. Install WSL 2 and Ubuntu 20.04 1. Follow either the written instructions or video tutorial below to install WSL2. 2. During this process, select "Ubuntu 20.04" or higher as your Linux version. 3. See our overview below for a summary with screenshots. **Written Instructions:**\ **Video Tutorial:**\ (commands in the description) #### Our Summary of these Instructions: 1. Enable the Windows Subsystem for Linux 2. Ensure you meet the requirements for WSL2 3. Enable the Virtual Machine feature in Windows (see screenshot below) 4. Download the WSL2 update package 5. Set WSL2 as your default Linux system 6. Open Microsoft store, search for Ubuntu 20.04, and install it 7. Launch the terminal and follow the prompt to create a new username/password (see screenshot below). #### Screenshot: Enabling Virtual Machine feature in Windows: ![](/files/-MJ7XEtznp94AWHI2D4o) #### Screenshot: Running Ubuntu 20.04 in Windows for the first time: ![](/files/-MJ7XK7FFSB-TRlxfqrg) ## Step 2. Install NVM *Note: Copy these commands and then paste into WSL2 by right-clicking on the terminal.* Enter the following commands into your Ubuntu terminal: ``` curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash # Download and install source ~/.profile # Reload system environment nvm install lts/erbium ``` ## Step 3. Editing Files in WSL2 In order to access your WSL2 file directory, run the following command in WSL2: ``` explorer.exe . ``` This will allow you to browse WSL2 as if it were another computer on a local network. {% hint style="info" %} If you are using the WSL, you files for your experiment must be in the WSL, you can't use the WSL to run an experiment stored on the rest of your computer. {% endhint %} ### Using code editors Different [code editors](/resources/code-editors) (such as VSCode) will have commands that you can run to open them in the current directory (e.g., `code .`). This helps make for a better coding experience in the WSL. # Linux Instructions The installation script requires `curl` to be installed, and some Linux distributions ship without it. You can install curl by first running the following lines in the terminal: #### Ubuntu / Debian / Debian based distributions ``` sudo apt update && sudo apt upgrade sudo apt install curl curl --version ``` #### Red-hat / Fedora / CentOS / Other Red-hat based distributions ``` yum install curl ``` After installing curl, proceed with the setup directions as normal in "Setup". {% content-ref url="/pages/-M-DZSKixhVwcSzJSWYl" %} [Setup](/getting-started/setup) {% endcontent-ref %} # Creating your experiment Once you have finished setting up Node and Meteor, [as per our setup guide](/getting-started/setup), you can use `empirica create` to create your experiment. Simply run the following command, where `my-experiment` is your experiment name (no spaces or uppercase letters): ```bash empirica create my-experiment ``` It will create a directory called `my-experiment` inside the current folder. Inside that directory, it will generate the initial [structure](https://github.com/empiricaly/docsv2/blob/main/getting-started/broken-reference/README.md) and install the transitive dependencies. Once the installation is done, open your project folder: ```bash cd my-experiment ``` You can now read more about the running your experiment, the structure of an Empirica experiment, and you can try our tutorial: {% content-ref url="/pages/-MTtiX7H8rZS8QB\_1vq\_" %} [Running your experiment](/getting-started/quick-test) {% endcontent-ref %} # Running your experiment Once you have created an experiment using empirica create. ## Running the app locally Run the app on your local machine with one command: ``` empirica ``` This can take a few minutes. This will start the app that you can access as a participant: You can access the `admin panel` here: ## Loading the factors and treatments Treatments and factors can be entered via the admin panel. Empirica also enables "experiment as code" by which experimental treatments and factors can edited directly in [YAML](https://learnxinyminutes.com/docs/yaml/) at `.empirica/treatments.yaml`. ## Testing the app To run a game, create a new `batch` with the games of treatments you want to use and click start on the batch. Open a player tab by going to . The player that you open with is cached on your browser. Whenever you start a game with this player, your local app will keep that information. To play again there are multiple things you can do: * Click on the **Reset current session** button in the bottom right menu to reset this player, and create a new game for this player to join. * Click on the **New Player** button in the bottom right menu to open a new tab with a different player (you will see tab with an id). **The app will automatically ("hot") reload when save changes to the code.** # Updating your experiment When new features or bug fixes are added to Empirica, you should try to upgrade to the latest version. {% hint style="info" %} Before upgrading, you can head over to the [Empirica Release Notes](https://github.com/empiricaly/empirica/releases) to verify that there are no BREAKING CHANGES between your current and the latest versions. To check the current version of your experiment, see [#check-the-current-version-of-your-experiment](#check-the-current-version-of-your-experiment "mention"). {% endhint %} ## Check the current version of your experiment At the root of your experiment, run `empirica version`: ``` $ empirica version Version: v1.0.0-rc.24 SHA: bc4184e Build: 169 Branch: main Time: 2022-12-28T08:21:58Z Client: 1.0.0-rc.24 Server: 1.0.0-rc.24 ``` ## Updating Empirica in your Experiment You can update the packages in your experiment by running the following command at the root of your experiment: 
$ empirica upgrade
Within your current experiment, this will upgrade both the `empirica` command and the npm packages used in `client/` and `server/`. This will **not** upgrade the `empirica` command globally. To upgrade the empirica command globally, see [#updating-the-empirica-command](#updating-the-empirica-command "mention") ## Change to a specific version in your experiment If you need to upgrade (or downgrade) to a specific version of Empirica, you can pass the exact version like so: ``` $ empirica upgrade --version "v1.2.3" ``` You can also choose to only upgrade the command line or the npm packages individually with either: ``` $ empirica upgrade --commandOnly $ empirica upgrade --packagesOnly ``` ## Updating the Empirica command To upgrade the `empirica` command globally (outside any existing experiment), run the following: ``` $ empirica upgrade --global ``` # Game Life Cycle *Elements on this page refer to the* [*concepts*](/overview/concepts)*, and* [*API*](/overview/api) *of an Empirica experiment.* Empirica experiments are event driven. The image below summarizes the lifecycle from the beginning of a game through exit steps. ![](/files/-M_5u7cgy5ZsdnOmkqgX) ### Beginning and intro steps In the admin panel, you would create a Batch of games for players to join. Players enter the game where they go through a consent form (optional), they provide an identifier (which can be set via URL queries), and they do the intro steps (the instructions and other components you have set in the intro steps. All of these are set by you in the `./client` . During these steps, players are **asynchronous**; namely, they complete these steps at their own pace until they have finished them, independent from the pace of other players. ### gameStart Once players finish the intro steps they are sent to a lobby where they wait until every player has joined. When every player has joined, the Game object is created based on what is set in `./server/src/callbacks.js` in the `Empirica.onGameStart()`. This is where certain parameters are set, and where the Rounds and their Stages are created. ### Rounds and Stages Then players go through each Stage of each Round. Once a Stage is finished, they move on to the next. If this was the last Stage of a Round, they move on to the next Round. If this was the last Round, they move on to the Exit Steps. During these steps, players are **synchronous**; namely, every player has to finish each stage before they can all move on to the next. In the `./server/src/callbacks.js`, a series of callbacks are triggered during this process: * Before a round starts, [`onRoundStart`](https://github.com/empiricaly/docsv2/blob/main/overview/api/README.md#empiricaonroundstartcallback) is called. * Before a stages starts, [`onStageStart`](https://github.com/empiricaly/docsv2/blob/main/overview/api/README.md#empiricaonstagestartcallback)is called. * When a Stage ends, [`onStageEnd`](https://github.com/empiricaly/docsv2/blob/main/overview/api/README.md#empiricaonstageendcallback) is called. * When a Round ends, [`onRoundEnd`](https://github.com/empiricaly/docsv2/blob/main/overview/api/README.md#empiricaonroundendcallback)is called. See our guide on customising when player submit a stage: {% content-ref url="/pages/-MeZTEmahAt8YzPgoM3K" %} [Customising when players submit stages](/overview/lifecycle/customising-when-players-submit-stages) {% endcontent-ref %} ### Game end and exit steps Finally, when the last Round ends, after the end of Stage and Round callbacks are triggered, the [`onGameEnd`](https://github.com/empiricaly/docsv2/blob/main/overview/api/README.md#empiricaongameendcallback) callback is called in the `./server/src/callbacks.js`. After which, the players goes through the exit steps. During these steps, players are **asynchronous**; namely, they complete these steps at their own pace until they have finished them, independent from the pace of other players. ### List of callbacks The list of callbacks goes as follows in order: * `onGameStart` Required * `onRoundStart` Repeated for each Round * `onStageStart` Repeated for each Stage * `onStageEnd` Repeated for each Stage * `onRoundEnd` Repeated for each Round * `onGameEnd` # Customising when players submit stages ## When players submit (end) a stage Instead of having players wait until the end of the stage, you can have them submit their answer. This will set the Stage as submitted for them. If all the other players have also submitted the Stage, then the players move on to the next Stage or Round. To set the stage to submitted you need to run this method from the `player` prop: ``` player.stage.set("submit", true); ``` This will change this property, that you can use to see if the stage has been submitted (it is a Boolean, true or false): ``` player.stage.get("submit"); ``` For example, you could create a button, that has a handle method for `onClick` that will do the necessary with the player's answer and call `player.stage.set("submit", true)`. ## What players see when they have submitted a stage Once a player submits for the stage, you might want to show something different on the screen. For example, instead of showing the stage's question/task (and avoiding players submitting multiple responses), you could show a message thanking the player for submitting the stage and telling them that they will have to wait for all players to submit the stage before they can move on to the next one. You can do this by setting a **conditional** that renders different elements depending on what `player.stage.get("submit")` returns. For example: ```jsx { player.stage.get("submit") ?
Thank you for your answer. The next stage will start when all the other players have submitted their answer.
:
} ``` # Concepts *Elements on this page might refer to the* [*life cycle*](/overview/lifecycle) *or the* [*API*](/overview/api) *of an Empirica experiment.* ## Game A Game is a single run of the experiment. It is also used to describe the experiment that was developed. One or more *Players* participate in a Game. A Game is divided into three main parts: Intro steps, Game, and Exit Steps. The *Intro Steps* are when Players arrive in the game. Before arriving at the Lobby, they can read instructions, answer quizzes, etc.. The Intro Steps are asynchronous (each player completes them at their own pace). Once all the Players have reached the Lobby stage, the *Game* initializes. The Game is composed of r*ounds* divided into *Stages*. Players must complete every stage of a round before moving on to the next Round. The Game is synchronous (every player has to finish a stage before they can all move on to the next stage). Once every Round is complete, the Players will reach the *Exit Steps* where they can read a debrief, answer questionnaires, etc. The Exit Steps are asynchronous. ## Player Players are users participating in a Game. A game must have a least 1 Player. Each Player entry in the database will contain information such as their last login, their unique ID, the ID of the Game they are participating in, which steps they have accomplished, and any other data you additionally assign to Players (e.g., an avatar to represent the Player). ## Batch A Batch is a set of 1 or more Games that run in parallel. Batches allow the creation of different assignment methods for player distribution: simple and complete. Batches are run one at a time in order of creation time. If you start multiple batches at once in the admin, only the first will accept players. Once full, the next batch will automatically start receiving players. ## Round A Game is made up of 1 or more ordered Rounds. A round contains one or more stages. Rounds are usually composed of the same stages that repeat throughout the game. For example, in the guess the correlation experiment, we ask the player to guess the correlation between a graph and a numerical value on each round. In the first stage of each round, it's the guess. The second stage is the reveal of the result. And in the third stage, we show what other players have guessed. All in the same round. And in the next round, we repeat those stages. All rounds are not required to contain the same stages or even the same number of stages. ## Stage A Round may contain one or more stages. A stage has a `duration`. The `duration` is a required field that sets the duration of the stage **in seconds**, with a minimum of 5 seconds and no maximum. You can also allow Players to *submit* a stage, which marks it as done for the given player. When all players have submitted, the stage is considered done. If the stage timer runs out, the stage is also considered done, whichever happens first. Usually, a `name` field is used to programmatic reference the stage. It can later be used in the UI code to differentiate stages. If you do not want to have a timer and wait until players submit, you can set the timer to an unreasonable value (e.g. 30000000 \~= a year), and hide the timer in the UI. The Rounds and Stages are **synchronous** (every player has to finish a stage before they can all move on to the next stage). The timer allows you to avoid one Player not responding and stopping the other Players from continuing because a new stage starts when the timer ends. ## Factors Factors are variables that will affect how a game will play. One *Factor Type* is mandatory for any Empirica game, the `playerCount` number. Factors are assembled into Treatments, which are themselves assigned to Games. To create *Factor Values*, you must first create Factor Types. A *Factor Type* describes the Factor. A \_Factor Type) has a `name`, a `description`, a `type,` and a `required` marker. * The `name` must be a code-friendly name, such a `playerCount`, which does not contain spaces or odd characters and is written in [camelCase](https://en.wikipedia.org/wiki/Camel_case). * The `description` is a human-readable description used in the admin UI to help other admins understand what this factor does. * Finally, the `type` is a computing type (integer, string, ...) to limit what \_Factor Values *can be created for this \_Factor Type*. * Factor Types can also be marked as `required`, meaning they are required in all treatments. The Factors can then be accessed as a property of the Game. This can be used to represent different conditions. For example, say you want some Games to show information from the other Players' answers to each other and some Games not to. You can have a "socialInformation" factor set to "yes" and "no", and only show the information from other Players if `game.socialInformation == "yes"` . ## Treatment A Treatment is a named *set of Factors*. Each Factor can appear at most once in a treatment, and required Factors must be present. The set of Factors in a treatment must be unique. No two treatments with the same set of factors can be created. ## Game Lobby A Game Lobby is where the players wait for other players to arrive until the game starts. ### Lobby Config Lobby configs configure the Game Lobby for common scenarios. It contains a timer duration for the lobby and handles the experiment's behavior in case of timeouts. Such as whether it start anyway or cancel the game once the timer runs out. ## Intro Steps The Intro Steps are pages shown to the user after registering and before the game or game lobby. The game designer can configure these steps to contain whatever is needed: instructions, a quiz, forms, etc. The steps can be altered depending on the treatment assigned to the current player or the treatments. The Intro Steps are **asynchronous** (each player completes them at their own pace). ## Exit Steps The Exit Steps are pages shown to the user after the game. They are configured by the experiment designer and may contain: results, reward instructions, quiz, thank-you note... The steps shown may be altered depending on any parameter of the player (results, etc.). If you want to use parameters that are not originally on the player (results that might be on the game for example), you should copy the parameters that you will need in the exit steps onto the player object in the `onGameEnded` callback. The Exit Steps are **asynchronous** (each player completes them at their own pace). # Randomization & Batches ## Creating batches In the `Admin panel` you can create a batch of games. Select the games of the different treatments you want and create the batch. To start the games in the batch click the `► Start` button. Now players can join the games in that batch. If all the games from that batch are full, they will be allocated to games in other open batches that have the same treatments. If there are no such games available, the players will receive a `gameFull` and told that there are no games available. ## What do the assignment methods 'simple' and 'complete' do? These are different methods for randomly allocating players to different Games. When you create a Batch, you can create multiple games within it, and these games can have different treatments. With experiments, one usually wants to randomly allocate players across the different games (Treatments). **Simple** will randomly allocate players to either of the games. Imagine rolling a die for each player to determine which game they are sent to. This might lead to situations where more than the maximum number of players of a game are allocated to a game. In that case, the first players to reach the lobby will be those who get the play the game and the others will be unable to join and their status will be set to `gameFull`. **Complete** will randomly allocate players to either of the games except those who already have the maximum number of players. This avoids the potential gameFull issue of the simple allocation method. ## What's the difference between N batches of 1 game each or 1 batch of N games? The assignment of players to games is done in batches sequentially and within each batch players will be randomly assigned to one game. Therefore, when you have 1 batch with multiple games, players will be assigned randomly to each of the X games according to the assignment method. This means it's possible that none of the games fill up even though enough players join for at least one game to proceed past the lobby as the players are distributed across various games. This would not happen if each batch has only one game: the first game will fill up with the first players who move past the lobby and the remaining players will transition to the game in the second batch. If you want to ensure the maximum possible number of players get assigned to a game, a good strategy would be to start batches each with 1 game per each treatment condition. For example, if you have two treatment conditions of 8 players each, your batches should contain 1 game of each treatment. This way you can be sure if 16 players join, all 16 will be randomized between only 2 games and you don't lose any of your players in games that never fill up. **This approach however has a drawback as it does not randomize between players with different arrival time or completion time of instructions.** ## Overriding default assignment The default assignment algorithm privileges randomness for better experimental results, but this results in what we call "overbooking", in other terms, assigning more players than a game is deisgned for. This can lead to some games getting "underbooked", and to not being able to overflow players from an overbooked game into another game if the treatments do not match up (we do not overflow overbooked players between games with different treatment since the intro steps the players go through might be different between treatments). We have added a couple options to modify the behavior of the assignment that reduces the randomness and increases assignment percentage: * The `preferUnderassignedGames` option will try to assign players to games that are underassigned, before assigning to games that are already full, resuming the assignment process as usual if no underassigned games are available, in the current batch (this option does not try to prefer games that are underassigned across batches). * The `neverOverbookGames` option will never assign players to games that are\ already full. This will push players into the next batches, if no games are available in the current batch. If no games are available in the next batches, the player will be sent to exit. This option is a bit more strict than `preferUnderassignedGames` and it can result in longer waiting times for players, and potentially game that never start if a player never finishes the intro steps. Given the strict nature of the `neverOverbookGames` option, it is generally recommended to use `preferUnderassignedGames` option if you do not want the normal behavior of the assignment algorithm. If you use a single batch, `preferUnderassignedGames` should fill optimally. Note that `neverOverbookGames` takes precedence over `preferUnderassignedGames`, meaning that if both options are set to `true`, `preferUnderassignedGames` will be ignored. To apply these options, in `server/src/index.js`, you can add the following options to the `Classic` function: ```js ctx.register( Classic({ preferUnderassignedGames: true, }) ); ``` ```js ctx.register( Classic({ neverOverbookGames: true, }) ); ``` # API This document describes Empirica's [server](#server), [client](#client) and [shared ](#shared)APIs. ## Server ### `Empirica.onGameStart(callback)` The `onGameStart` callback is called just before a game starts, when all players are ready, and it must create rounds and stages for the game. One (and one only) onGameStart callback is required for Empirica to work. The callback receives one argument, the [`game` object](#game-object), which gives access to the `players` and the treatment for this game. It also offers the `addRound()` method, which allows to add a round to the `game`. The returned Round object will implement the `addStage(stageArgs)` method, which allows to add a Stage to the Round. The `stageArgs` object to be passed to the stage creation method must contain: * `duration`: the stage duration, in seconds Note that the Game has not yet been created when the callback is called, and you do not have access to the other properties of the Game which will be created subsequently. #### Example ```js Empirica.gameInit(game => { game.players.forEach((player, i) => { player.set("score", 0); }); const round1 = game.addRound(); round1.addStage({ duration: 120 name: "Response", }); if (game.treatment.playerCount > 1) { round1.addStage({ duration: 120 name: "Result", }); } const round2 = game.addRound(); round1.addStage({ duration: 300 name: "Response", someotherfield: "mydata" }); if (game.treatment.playerCount > 1) { round1.addStage({ duration: 120 name: "Result", }); } }); ``` ### **Game Callbacks** Game hooks are optional methods attached to various events throughout the game life cycle to update data on the server-side. Contrary to client side data updates, sever-side updates are synchronous, there is no risk of conflicting updates, and important calculations can be taken at precise points along the game. \`\` ### `Empirica.onRoundStart(callback)` `onRoundStart` is triggered before each round starts, and before `onStageStart`. It receives the same options as `onGameStart`, and the [round](#round-object) that is starting. #### Example ```javascript Empirica.onRoundStart(({ round }) => { round.set("scoreToReach", round.currentGame.get("maxScore")); }); ``` ### `Empirica.onStageStart(callback)` `onRoundStart` is triggered before each stage starts. It receives the same options as `onRoundStart`, and the [stage](#stage-object) that is starting. #### Example ```javascript Empirica.onStageStart(({ stage }) => { stage.set("randomColor", myRandomColorGenerator()); }); ``` ### `Empirica.onStageEnded(callback)` `onStageEnded` is triggered after each stage. It receives the current [game](#game-object), the current [round](#round-object), and [stage](#stage-object) that just ended. #### Example ```javascript Empirica.onStageEnded(({ stage }) => { const expectedScore = stage.round.get("expectedScore"); const group = stage.get("score") > expectedScore ? "great" : "not_great"; stage.set("scoreGroup", group); }); ``` ### `Empirica.onRoundEnded(callback)` `onRoundEnded` is triggered after each round. It receives the current [game](#game-object), and the [round](#round-object) that just ended. #### Example ```javascript Empirica.onRoundEnded(({ round }) => { let maxScore = 0; round.currentGame.players.forEach((player) => { const playerScore = player.round.get("score") || 0; if (playerScore > maxScore) { maxScore = playerScore; } }); round.set("maxScore", maxScore); }); ``` ### `Empirica.onGameEnded(callback)` `onGameEnded` is triggered when the game ends. It receives the `game` that just ended. #### Example ```javascript Empirica.onGameEnded(({ game }) => { let maxScore = 0; game.rounds.forEach((round) => { const roundMaxScore = round.get("maxScore") || 0; if (roundMaxScore > maxScore) { maxScore = roundMaxScore; } }); game.set("maxScore", maxScore); }); ``` ### Empirica.on(model, callback) `on(model, callback)` listens to the creation of new mode objects. Model objects are the "game", "round", "stage", "player" and "batch". The callback receives a `ctx` object, and the model object listened to. In the example below, we're listening to new games, so we receive the `game` as argument. ```jsx Empirica.on("game", (ctx, { game }) => { if (game.get("initCalc")) return; game.set("initCalc", initCalcs()); }); ``` {% hint style="warning" %} Beware, `Empirica.on(model, callback)`is called on new objects **and** when the server restarts (when you run `empirica` or the server restarts after a code change in development mode). You should add a check such as the one in the example above, where we check if `initCalc` was already set at the top of the callback. {% endhint %} ### Empirica.on(model, attributeName, callback) `on(model, attributeName, callback)` listens on changes to the attribute of `attributeName` on `model`. Model objects are the "game", "round", "stage", "player" and "batch". The callback receives a `ctx` object, the model object, and the attribute value. In the example below, we're listening on changes to `choice` on the `player` model. ```jsx Empirica.on("player", "choice", (ctx, { player, choice }) => { if (choice === "yes") { // ... } }); ``` {% hint style="info" %} We recommend using the value of the attribute given on the callback argument instead of doing `.get(attributeName)` on the model object as the value could have changed changed asynchronously. {% endhint %} ### Empirica.flush() `Empirica.flush(): Promise` adds the ability to manually flush changes outside of callback functions. This is useful when you want to make changes asynchronously without blocking the callback. For example, if you want to call an external API and update an attribute with the results, but your don't want to block the callback while waiting for the API to respond. `Empirica.flush()` will return a promise that resolves when the changes have been flushed. You can use `await Empirica.flush()` to wait for the changes to be flushed. But you do not have to wait for the flush. It is only useful if you have multiple flushes in a single function, where you want to commit the changes in steps. The simplest example: ```js Empirica.on("stage", "myTrigger", (ctx, { stage, myTrigger }) => { callMyAPI.then((value) => { stage.set("value", value); Empirica.flush(); }); }); ``` An example with different use cases: ```js Empirica.on("stage", "myTrigger", (ctx, { stage, myTrigger }) => { // Copying the stage to the global namespace so we can use it outside of the // callback function. See below this callback function. myStage = stage; // flush setTimeout(() => { stage.set("b", (stage.get("b") || 0) + 1); Empirica.flush(); }, 2000); }); // Note: copying a stage to the global namaspace like this is not recommended, // this is just for illustration purposes. If you have multiple games running // at the same time, stages will overwrite each other. let myStage; setInterval(() => { if (myStage) { myStage.set("c", (myStage.get("c") || 0) + 1); Empirica.flush(); } }, 1000); ``` Note: if you perform blocking operations between changes, the changes before the blocking operations **might** be flushed before flushing manually. The change log is global, so while you're blocking, other changes might happen in a callback elsewhere, and that could trigger a flush of all latent changes. If you want to make a set of changes atomic, you should not do any blocking operations between them (i.e. use `await` or Promises) or collect your changes in a local datastructure and apply them at once. If you are starting an interval (`setInterval`), you should make sure to clear it properly. Here's an example with an interval per game: ```js const timers = {}; // We use the game event to start the interval. this ensures that the interval // is started on a server restart. Empirica.on("game", (ctx, { game }) => { if (!game.isRunning) return; timers[game.id] ||= setInterval(() => { // do something Empirica.flush(); }, 1000); }); Empirica.onGameEnd(({ game }) => { clearInterval(timers[game.id]); }); ``` Or have a single interval that manages all games: ```js const activeGames = new Set(); // We use the game event to start the interval. this ensures that the interval // is started on a server restart. Empirica.on("game", (ctx, { game }) => { if (game.isRunning) { activeGames.add(game); } }); setInterval(() => { for (const game of activeGames) { // do something } Empirica.flush(); }, 1000); Empirica.onGameEnd(({ game }) => { activeGames.delete(game.id); }); ``` ## Server Objects ### `Game` object | Property | Type | Description | | -------------- | ----------------------------------------- | ---------------------------------------------------- | | `players` | Array of [Player objects](#player-object) | Players participating in this Game. | | `rounds` | Array of [Round objects](#round-object) | This will return every round that makes up the game. | | `stages` | Array of [Stage objects](#stage-object) | This will return every stage that makes up the game. | | `currentRound` | [Round object](#round-object) | The current Round. | | `currentStage` | [Stage object](#stage-object) | The current Stage. | ### `Round` object | Property | Type | Description | | ------------- | --------------------------------------- | ----------------------------- | | `stages` | Array of [Stage objects](#stage-object) | Stages composing this Round. | | `currentGame` | [Game object](#game-object) | Game this round is a part of. | ### `Stage` object
PropertyTypeDescription
roundRound objectRound this stage is a part of.
currentGameGame objectGame this stage is a part of.
### `Player` object | Property | Type | Description | | -------------- | ----------------------------- | --------------------------------------------------- | | `id` | String | The ID the player used to register (e.g. MTurk ID). | | `currentRound` | [Round object](#round-object) | Round the player is currently in. | | `currentStage` | [Stage object](#stage-object) | Stage the player is currently in. | | `currentGame` | [Game object](#game-object) | Game the player is currently in. | ## Client {% hint style="info" %} See the [Special Empirica Component](/guides/special-empirica-components) page for more info. {% endhint %} ## # 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](https://reactjs.org/docs/hooks-intro.html). 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](/guides/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 [Managing the Data](/guides/managing-the-data#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](/guides/deploying-my-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](/getting-started/quick-start)). Then, move over your callbacks, making sure to change the reference to your objects (see the[#server-side](#server-side "mention") section above). On the client side, you will need to move over your configuration manually (intro/exit steps, component overrides... – see the [#client-side](#client-side "mention") 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. # Managing the Data ## Recording the data There are multiple places where you can record data in an Empirica experiment. ### To the player One way of recording the data of players' responses is to set them to the `player` prop itself. You can do so with this command: ``` player.set("name_of_property", value) ``` You can retrieve what you have set as a specific property/answer for the player with: ``` player.get("name_of_property") ``` ### To the game, round or stage If you want to save general data (not specific to one player), you can save it to the `game`, `round` or `stage` with: ``` game.set("name_of_property", value) round.set("name_of_property", value) stage.set("name_of_property", value) ``` You can retrieve what you have set as a specific property/answer with: ``` game.get("name_of_property") round.get("name_of_property") stage.get("name_of_property") ``` ### To the player.game, player.round or player.stage One way of recording the data of players' responses is to set them to the `player.game`, `player.round` or `player.stage` prop to identify a particular data/response of a *particular player* to a *particular game, round or stage*. You can do so with this command: ``` player.game.set("name_of_property", value) player.round.set("name_of_property", value) player.stage.set("name_of_property", value) ``` You can retrieve what you have set as a specific property/answer with: ``` player.game.get("name_of_property") player.round.get("name_of_property") player.stage.get("name_of_property") ``` ## Exporting the data Empirica can export your data to CSV format by running from the root of your experiment: ``` $ empirica export ``` This will create a zip file containing multiple csv files. Each file represents an object type (batches, games, players, rounds...). Each line is one of those objects. And each column is one of the keys in the object. For example, if you do `player.set("myvar", 42)`, in the export, you will find a line in the `players.csv` file where the `myvar` column will contain `42`. # Special Empirica Components ## No Games The "No experiments available" page can be overriden in the `App.jsx` file with the `noGames` prop on `` like so (file simplified for clarity): ```jsx import { MyNoGames } from "./MyNoGames.jsx"; // ... export default function App() { // ... return ( ) } ``` The "no games" component does not receive any special props. ## Consent The consent page can be overriden in the `App.jsx` file with the `consent` prop on `` like so (file simplified for clarity): ```jsx import { MyConsent } from "./MyConsent.jsx"; // ... export default function App() { // ... return ( ) } ``` The Consent component will receive one prop: * `onConsent`: this is a function that should be called if the player consents. If they do not consent, you can either modify something on the page (e.g. hide the consent form) or redirect them away from the experiment. Here's a simplistic Consent component example: ```jsx export function MyConsent({ onConsent }) { return (
Do you consent?
); } ``` If you don't want to fundamentaly change the Consent, and only want to change the text of the default consent, you can use the Consent component provided with the Empirica package: ```jsx import { Consent } from "@empirica/core/player/react"; export function MyConsent({ onConsent }) { return ( ); } ``` ## PlayerCreate (where players set their id) Players have to set their id at a **PlayerCreate page** just after the consent page. This could be a name, an MTurk/Prolific id, a student id, an email, etc. You might want to change its design, format, or instructions. For example, if you want participants to provide a student id but no other personal information, you would want to make your own clear instructions. The default PlayerCreate.jsx page looks like this: ```jsx import React, { useState } from "react"; export function MyPlayerForm({ onPlayerID, connecting }) { // For the text input field. const [playerID, setPlayerID] = useState(""); // Handling the player submitting their ID. const handleSubmit = (evt) => { evt.preventDefault(); if (!playerID || playerID.trim() === "") { return; } onPlayerID(playerID); }; return (
Enter your Player Identifier
setPlayerID(e.target.value)} />
); } ``` There are 2 props passed to the PlayerCreate component: * `onPlayerID`: the callback you must call with the player identifier you collected from the Player. * `connecting`: this will be true while the player create being identified (after you have submitted with `onPlayerID`), until the player is "logged in". This field allows you to disable or hide the form while sending the login data to the server. Once you've made your version of the PlayerCreate component, you can import it into the `App.jsx` file, and set the `playerCreate` prop on `` like so (file simplified for clarity): ```jsx import { MyPlayerForm } from "./MyPlayerForm.jsx"; // ... export default function App() { // ... return ( ) } ``` ## Lobby The lobby page can be overriden in the `App.jsx` file with the `lobby` prop on `` like so (file simplified for clarity): ```jsx import { MyLobby } from "./MyLobby.jsx"; // ... export default function App() { // ... return ( ) } ``` At the moment, the Lobby does not have any special fields, but you do have access the current Player (`const player = usePlayer()`) and the current treatment (`player.get("treatment")`). ## Timer There is a `Timer.jsx` component in the default game template that represents the stage timer and shows players how much time is left at that stage. The time remaining on the current stage (in milliseconds) can be accessed with the `useStageTimer()` React Hook. Note that the timer might not exist if there is no current stage (before the Game starts, or in between Stages) Here is the code for a basic Timer component: ```jsx import { useStageTimer } from "@empirica/core/player/classic/react"; import React from "react"; export function MyTimer() { const timer = useStageTimer(); return (
{timer?.remaining ? Math.round(timer?.remaining / 1000) : 0} seconds
); } ``` ## Finished, Loading and Connecting The Finished, Loading and Connecting pages can be overriden in the `App.jsx` file with the `finished`, `loading`, and `connecting` props on `` like so (file simplified for clarity): ```jsx import { Myloading } from "./Myloading.jsx"; import { Finished } from "./Finished.jsx"; // ... export default function App() { // ... return ( ) } ``` These components do not receive any special props. Function of these components: * `loading`: is shown any time the experiment is loading, including between stages. * `connecting`: us shown while the experiment is connecting to the server. This will happen on the initial page start, or if the server disconnects at any point. By default, the connecting page is the same as the loading page. * `finished`: is the last page shown to the player after they have finished the Game and all the exit steps. ## Empirica Chat {% hint style="warning" %} This chat documentation has not been update for Empirica v2 yet and is likely incorrect! {% endhint %} To add a chat in Empirica, you can use our simple solution by using the **Empirica Chat**. For detailed information about Empirica Chat, see [here](https://github.com/empiricaly/chat). ### Installing First, install Empirica Chat with: ``` npm install --save @empirica/chat ``` ### Import and Usage In the components you want to use the chat, import this: ``` import { Chat } from "@empirica/chat"; ``` Then you can create the chat component with: ```jsx ``` `chat` expects 2 required props: * `player`: the current player * `scope`: object that the chat will be attached to, can be game, round, or stage objects. ### Scoping The scope is important because it determines where the chat data (the messages) will be stored. You can access them again afterwards based on the scope. For example, if the scope is set to the Round: ```javascript const chat = round.get("chat") ?? []; ``` ### Multiple chat instances within the same scope You can pass an optional `customKey` string prop to differentiate different chats within the same scope. This changes which get/set key on the given scope the chat will be recorded. ```jsx ``` ### Display names `Chat` also displays a name for each participant, which you need to set in the experiment independently of the `playerId`: `player.set('name', "myPseudonym")` ### Other functionalities There are many other functionalities with Empirica chat that you can see [here](https://github.com/empiricaly/chat). # The Admin Panel ## Structure The Admin Panel can be accessed at `/admin`. It is made of two parts: * The **monitoring** section * The **configuration** section ### The Monitoring section Here you can create and run batches of games and monitor player statuses. ### The Configuring section Here you can create factors and treatments before creating batches. ## Clearing Players: How players can play again, even if they were led to the exit steps. Players can only play once. If there is a problem (e.g., the lobby timed out or the game was full), or if you want players to play again, you can *clear* them, which allows them to play again. In the **monitoring section**, in the **players tab**, you can see the status of every Player. A button called `Clear`, to the right of each player line, allows you to clear them one by one. Once *retired*, players can refresh their page/return to the link of your game, and they will be randomly allocated to a game with the same treatment as before. They are allocated to a game with the same treatment, so they don't discover a game with different conditions or instructions. ## Treatments and factors settings The treatments and factors are saved in a `.empirica/treatments.yaml`. It is often shared by simply committing it to your code versioning system (e.g., Git). You can edit treatments and factors manually in that file (make sure to reload the admin page after edits). Alternatively, you can edit these directly in the admin UI, which will update the `.empirica/treatment.yaml` file. # Deploying Your Experiment How to deploy your experiment. {% hint style="info" %} This page describes deployment in a general way. For a full tutorial from A to Z go to: [Ubuntu tutorial](/guides/deploying-my-experiment/ubuntu-tutorial). {% endhint %} {% hint style="warning" %} Deploying requires some knowledge of Linux and servers. {% endhint %} This page describes how to deploy Empirica using any server or VM provider. Empirica is a single command and uses an embedded database, so there is only one executable to install. First, you need a server. There are thousands of different options on how to get running here. One quick and easy service we can recommend is [Digital Ocean's Droplets](https://docs.digitalocean.com/products/droplets/quickstart/). You will need to be able to connect to the server over SSH. If you need to become more familiar, [here's an introduction](https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys). ## Bundling your experiment Bundling your experiment is the task of building all the code you've created for your experiment and packaging it, along with the configuration, into a compressed "bundle" file. To do so, run at the root of your experiment: ``` empirica bundle ``` This should create a file like `[name-of-your-experiment].tar.zst`. This is your bundled experiment. This is what you will deploy to your server. You should not add this to your code repository. ## Setting up the server You will need the empirica binary: ``` curl https://install.empirica.dev | sh -s ``` ## Running the experiment Just so you know, you will need to send your experiment bundle to the server. For example, using `scp`: ``` scp myexperiment.tar.zst someuser@example.com:~ ``` And finally, on the server, run the experiment with: ``` empirica serve myexperiment.tar.zst ``` Your experiment will be available at the address of that machine on port 3000. ## Optional: setup a reverse proxy We recommend you use a Reverse Proxy to expose your experiment to the internet and secure connections with HTTPS. An excellent tool for this is [Caddy](https://caddyserver.com). Check out the installation instructions [here](https://caddyserver.com/docs/install). You will need a domain name to use HTTPS (encrypted connections). We will not go into much detail here, but you can find many registrars online, such as Google Domains, Cloudflare Registrar, Namecheap, or Hover. Then you will need to configure your domain name to point to your server. This is also beyond the scope of this guide. Still, you should be able to look up the documentation of your hosting provider (e.g., Digital Ocean) and your Registrar (e.g., Google Domains) to figure out how to point your domain name to your server using either an A Record or CNAME Record. Once your domain name is set up (we will use `www.example.com` in our example), you can run: ``` caddy reverse-proxy --from www.example.com --to localhost:3000 ``` This will set up the HTTPS certificate and redirect all incoming traffic to empirica. ## Saving the database The data in empirica will be stored in `.empirica/local/tajriba.json`. Copy that file to a safe place after running your experiment. You can take as many snapshots of your data as you wish by copying that file every so often. You can also export the data from the server by running the export command. See the export section on the [Managing the Data](/guides/managing-the-data) page. # Ubuntu tutorial This will is a tutorial explaining how to setup Empirica an Ubuntu 23.10 Droplet on Digital Ocean. This will go through all the steps needed to deploy an Empirica experiment in a generally secure manner, how to update your experiment, and how to retrieve your data. We are using Digital Ocean, which is relatively easy to use, but you can use any hosting provider and the steps will be similar if you use Ubuntu 22+. This tutorial does assume a few things: * You have minimal Linux, command line, and ssh experience. If you don't check out some quick intro tutorials on Youtube. * You have a domain name. A subdomain on empirica.app can be provided, see Setup your domain below for details. ### Bundle your experiment At the root of your experiment, run: ```sh empirica bundle ``` This will create a file called `myexperiment.tar.zst` where `myexperiment` is the name of your experiment or `empirca`. This file will be useful later in the process. ### Create your dropplet on Digital Ocean 1. Sign up to [Digital Ocean](https://www.digitalocean.com) 2. Click `Create` in the top left, then `Droplets` 3. Choose a region close to you ; datacenter doesn't matter much, leave the default 4. For the image selection, choose `Ubuntu` then `23.10 x64` 5. For size, choose `Basic`, then `Premium AMD`, then `4GB/2CPU` or `8GB/4CPU` depending on your needs. Generally, you can get by with 2 CPUs, espcially during development, and you can always upgrade your droplet later. 6. `Enable automated backup...`, daily, doesn't hurt 7. For SSH keys, if you know what's up, add your key, if you don't, follow [this tutorial](https://docs.digitalocean.com/products/droplets/how-to/add-ssh-keys/). 8. Enable `Add improved metrics...` 9. Quantity: 1 10. Hostname: you choose (e.g. myexperiment), this is unrelated to your domain name, it's mostly just the name in your Digital Ocean admin UI. 11. Click `Create Droplet` 12. Wait for the Droplet to start, and note down the IP address ### Setup your domain #### Your own domain If you have a access to a domain name, we'll assume you know how to setup an A Record (name is the domain or subdomain name you want to use, the value is the IP address of your Droplet, and for TTL either automatic/default, or 5 min if you expect to change the address soon). You might want to double check your domain is configured correctly (it can take a few minutes to propagate). On macos and linux you can use dig: ```sh dig @8.8.8.8 mydomainname.com A ``` #### empirica.app subdomain If you do not have a domain name, you can contact Nicolas P. on Slack with the subdomain on empirica.app you'd like to use (e.g. mycoolexperiment.empirica.app). Please provider 2-3 options that are not too generic (e.g. `experiment` is too generic) so we don't conflict, and the IP address of your Droplet. A couple of notes: * please do not do anything illegal on your domain. We are not responsible for anything sketchy you do on your subdomain * if you're taking down your experiment, please let us know so we can cleanup the DNS entry. We reserve the right to clear the subdomain if we haven't heard from your in a year or two ### Setup your server SSH into your server using the IP address from your Droplet. For example: ```sh ssh root@123.123.123.123 ``` {% hint style="info" %} For the more experienced users, these instructions are installing things as root. We understand that is not ideal. Setting up a separate user is beyond the scope of this tutorial. The nature of Empirica deployments is to be usually short lived and relatively low risk. You are welcome to setup a non-privileged user if you prefer. If you wish to contribute improvements to this tutorial with such instructions, that would be simple enough for the casual users, contributions are welcome! {% endhint %} #### Install Empirica To install empirica on your server, run: ```sh curl -fsS https://install.empirica.dev | sh ``` #### Install caddy Caddy is the reverse proxy that will enable HTTPS on your experiment. To install, run the following commands: ```sh sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list sudo apt update sudo apt install caddy ``` #### Setup Empirica We want Empirica to reload automatically in case of a crash, a server restart, or an update. For that we will create a few folders and configuration files. First, create a folder for the deployment at the root of your user (where you ssh-ed in). We will use a directory called `empirica`: ```sh mkdir empirica ``` We will create 2 files to start and restart empirica using `systemctl`. First, run: ```sh sudo nano /etc/systemd/system/empirica.service ``` In this file, paste the following: ```systemd [Unit] Description=Empirica Service After=network.target [Service] Type=simple WorkingDirectory=/root/empirica ExecStart=/usr/local/bin/empirica serve /root/empirica/empirica.tar.zst Restart=always RestartSec=5 KillSignal=SIGINT TimeoutStopSec=10 Environment="PATH=/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" [Install] WantedBy=multi-user.target ``` Save the file (with nano, ctrl+o then Enter) and exit (ctrl+x). We will then create a restarter file: ```sh sudo nano /etc/systemd/system/empirica-restart.service ``` And paste the following: ```systemd [Unit] Description=Empirica restarter After=network.target [Service] Type=oneshot ExecStart=/usr/bin/systemctl restart empirica.service [Install] WantedBy=multi-user.target ``` We will then create a watcher file: ```sh sudo nano /etc/systemd/system/empirica.path ``` And paste the following: ```systemd [Unit] Description=Watch /root/empirica/empirica.tar.zst for changes [Path] PathChanged=/root/empirica/empirica.tar.zst Unit=empirica-restart.service [Install] WantedBy=multi-user.target ``` Save and exit nano. This file will restart empirica when the empirica bundle changes. Run the following to register these 2 files: ```sh sudo systemctl daemon-reload ``` #### First deployment Next, we'll upload your Empirica experiment bundle (the `.tar.zst` file we created in the first step) from your machine to your server. You can do that with `scp` (replace myexerpiment with the name of your bundle and the IP address with your Droplet IP address): ```sh scp myexperiment.tar.zst 123.123.123.123:~/empirica/empirica.tar.zst ``` We can now start empirica like so: ```sh sudo systemctl enable --now empirica.service ``` Check that it's running as expected: ```sh curl -v localhost:3000 ``` It should return a bunch of html with an HTTP code 200 (`HTTP/1.1 200 OK`). #### Setup Caddy Delete the existing configuration for Caddy: ```sh rm /etc/caddy/Caddyfile ``` And add a new one: ```sh sudo nano /etc/caddy/Caddyfile ``` With the following, where the domain name if the domain name you setup: ``` mydomain.empirica.app { reverse_proxy localhost:3000 } ``` And restart caddy: ```sh systemctl restart caddy ``` It might take a minute for the HTTPS certificates to generate. Go to your domain in your browser, and if all goes well, your experiment is deployed, with HTTPS. #### Restart empirica on changes We will enable our restarter units: ```sh sudo systemctl enable --now empirica-restart.service sudo systemctl enable --now empirica.path ``` Now, next time you bundle and upload again, empirica should restart automatically. See [#update-your-experiment](#update-your-experiment "mention") below. ### Run experiment #### Access the admin Go to `/admin` on your domain in the browser. You will be asked for a username and password. You can find the default username (`admin` by default) and password (randomly generated with your new project) in your project in `.empirica/empirica.toml` on your local machine. You can change or add more users from that file and redeploy. #### Export the data On your server, the data will be in `~/empirica`, and you can run the following from root: ```sh cd empirica empirica export ``` To copy the data back to your machine, you can run, from your machine (`*` will pull all the exports, you can specify the exact zip file your want instead) : ```sh scp 123.123.123.123:~/empirica/*.zip . ``` #### Update your experiment To update your experiment, bundle and scp again from your local machine: ```sh empirica bundle scp myexperiment.tar.zst 123.123.123.123:~/empirica/empirica.tar.zst ``` You will need to reload the browser to see the changes. It does not reload the page automatically as it does in local development mode. ### Administration tasks #### Stop, restart, or start empirica manually ```sh systemctl stop empirica systemctl restart empirica systemctl start empirica ``` #### View logs ```sh journalctl -u empirica -f ``` # Beginner Experiment: Prisoner's Dilemma In this beginner-level tutorial, you will build a simple two-player experiment from scratch, based on the classic [“Prisoner’s Dilemma”](https://en.wikipedia.org/wiki/Prisoner's_dilemma) game. This tutorial introduces the major building blocks of an Empirica experiment, including players, rounds, stages, and UI design. This tutorial can be used independently or as a supplement to the Empirica workshop and tutorial (to be) filmed at the International Conference for Computational Social Science in July 2023. ### How social scientists can use this tutorial This tutorial provides detailed instructions that will help you get started building your first experiment in Empirica. The tutorial doesn't assume any prior knowledge of Javascript or React, although some experience with programming will be helpful. Many experiments can be built up from this basic foundation with small changes to the way information is presented or the choices participants are presented with. The goal of this tutorial is to help you become more comfortable with Empirica and understand how to translate your experiments from ideas to tangible code. For resources that can help you become a more capable developer, see: {% content-ref url="/pages/6O6haFdYcE5Btj7tVW7F" %} [Javascript and React](/resources/javascript-and-react) {% endcontent-ref %} {% content-ref url="/pages/-MJ7y7f1-T1HW337HyRz" %} [Helpful Linux Commands](/resources/helpful-linux-commands) {% endcontent-ref %} ### How software developers can use this tutorial If you are a software developer and comfortable using React, JavaScript, CSS, etc., this tutorial will help you quickly understand the basic structure of an Empirica experiment. This tutorial may act as a helpful example to refer to when implementing other experiments that your team wants to explore. To get more familiar with the Empirica conceptual model, see: {% content-ref url="/pages/-M-DYevE5uIQKvfsnfrW" %} [Conceptual Overview](/overview/lifecycle) {% endcontent-ref %} ## About the experiment The Prisoner's Dilemma is a classic concept in game theory that explores the tension between cooperation and self-interest. It is often used as an experimental tool in social psychology to study decision-making, trust, and cooperation. In the standard version of the Prisoner's Dilemma, two individuals are arrested for a crime and are held in separate cells. They are both given the opportunity to cooperate with each other or betray each other by confessing to the crime. The outcomes are as follows: 1. If both prisoners remain silent (cooperate), they each receive a moderate sentence for a lesser charge. 2. If one prisoner confesses (betrays) and the other remains silent, the betrayer receives a minimal sentence, while the other prisoner receives a severe sentence. 3. If both prisoners confess (betray), they both receive a moderately severe sentence. The dilemma arises because each prisoner must decide whether to trust the other person and cooperate for a potentially better outcome for both or act in their self-interest by betraying the other, which might lead to a better personal outcome if the other remains silent. ### Special thanks This tutorial was developed by James Houghton, Mohammad Alsobay, and Michael Li, with support from Millie Gu and others. # Part 1: Before you start ## Setting up the dependencies Before you complete the tutorial, you will need to install Empirica as described in the link below: {% content-ref url="/pages/-M-DZSKixhVwcSzJSWYl" %} [Setup](/getting-started/setup) {% endcontent-ref %} ## Setting up the editing environment This tutorial was developed using Visual Studio Code. You are welcome to use any editor or IDE you are comfortable with, but if you don't have a favorite, or you want to follow along precisely with the tutorial, you may want to give it a try. You can find instructions on the page linked below: {% content-ref url="/pages/-MJ9gqydiZpZyUppD2iS" %} [Code Editors](/resources/code-editors) {% endcontent-ref %} # Part 2: Creating the Experiment in Empirica To create your experiment, open your terminal and navigate to the directory where you want to create your project. (e.g. `cd ~/Desktop`). You can find a refresher on terminal commands used to navigate directories here: {% content-ref url="/pages/-MJ7y7f1-T1HW337HyRz" %} [Helpful Linux Commands](/resources/helpful-linux-commands) {% endcontent-ref %} ### Set up a project using the template experiment To set up a template experiment, enter the following command in your terminal window: ```sh empirica create prisoners-dilemma ``` This will create a folder named 'prisoners-dilemma' for the project and populate it with a template experiment. (e.g. `~/Desktop/prisoners-dilemma`) You should see something similar to the following: {% code title="output:" %} ```bash ✓ Setup directory ✓ Copy project files ✓ Install client packages ✓ Install server packages ✓ Upgrade empirica packages ✓ Generate default settings Empirica (local build) experiment created. Get started: > cd prisoners-dilemma > empirica ``` {% endcode %} To work within the newly created folder, change into the newly created directory: ```sh cd prisoners-dilemma ``` ### Test-drive the template experiment To start the experiment, run the command: ```sh empirica ``` You should see something similar to the following in the terminal window: {% code title="output:" %} ```bash Empirica (local build) server running: Player http://localhost:3000 Admin http://localhost:3000/admin ``` {% endcode %} To view the experiment, type `http://localhost:3000/admin/` into your browser address bar. (You can use any browser you like, the images in this tutorial show the Chrome browser.) You will see the Empirica admin interface, which handles setting up treatments and launching batches of games:
> Note: if you see a login page like the following, you should use the username "admin". > > You can print the auto-generated password by running the terminal command `cat .empirica/empirica.toml` within your `prisoners-dilemma` folder.

Admin console login screen

#### Start a "batch" The admin console opens to the "Batches" tab. To create a new batch, click the "New Batch" button to open the batch creation drawer. We will create one game with the "Two Players" treatment. Edit your settings to look like this:
Click `Create` to return to the main batch screen. You'll see that a batch has been added to the batches list. Click "Start" to begin the batch.
If you find it helpful to see the process animated:

admin site example

#### Play the game To play the game, open a new tab to url `http://localhost:3000/`. You should see something like the following:
For now, enter your name as the identifier. When your experiment is deployed, this will be where participants enter their MTurk Worker ID, Prolific Identifier, etc. You will need to create a second player to join the game. While you are developing the game on your local computer, you will see a toolbar in the lower left corner:
Click the second button to add a new participant - a view for this second participant will open in a new tab. Enter a **different** identifier, and walk through the experiment by playing for both participants. **Try opening each of the players' tabs side-by-side so you can see how each player's view is updated in real time!**
**As a brief rundown, the stages of the experiment are as follows:** 1. Player Consent 2. Player Identification 3. Intro Steps (Here an "Instructions" page) 4. A lobby, where you wait for enough players to complete the introduction for the game to launch 5. Synchronous Game Stages (here a guessing game, and minesweeper, just for fun) 6. Exit Steps (surveys, payment instructions, debrief, etc) #### Stop the development server Once you have had a chance to play through the game, return to your terminal window and shut down the empirica server by pressing the control key and the 'c' key simultaneously (`+c`). If it asks you for confirmation, you can push the same key combination again. # Part 3: Getting Accustomed to the Code To get a glimpse of the actual code that runs Empirica, open Visual Studio Code to the `prisoners-dilemma` folder. > You can either do this manually, by going to `File > Open Folder` and selecting the `prisoners-dilemma` folder, or by typing in your terminal `code .` within the `prisoners-dilemma` directory. The template experiment includes three subdirectories: 1. `.empirica` stores data and config files that we need to run the experiment. 2. `client` is where the code that runs on your experiment participant's browser lives. 3. `server` is where all the code that runs on the server lives.

Collapsed File Tree

The `client` and `server` directories are each structured as a node package, and contain some boilerplate code that we can ignore: * `node_modules/` is a folder containing dependencies, and is managed for us (we never need to touch it) * `dist/` is a folder for the compiled version of our code, which gets built automatically * `package.json` and `package-lock.json` contain references to other packages that our experiment depends on * `client/index.html`, `client/vite.config.js`, `client/uno.config.ts`, `client/jsconfig.json` `server/jsconfig.js` are all configuration files we can leave as they are In this tutorial, we will make changes in the following places: * `client/src/` is a folder containing the views the participant sees, built up as React components. * `server/src/callbacks.js` is a file for server-side code that is called when specific actions happen in the game. * `.empirica/local/tajriba.json` is where our experiment data is stored. It is often helpful to delete this file when you restart the server, to start with a clean slate. Have a quick browse through the files in `client/src/examples` to see how the jelly bean and minesweeper examples are implemented. # Part 4: Coding the Prisoner's Dilemma Game In this section, we break down the initial process of creating an experiment into subparts, for clarity. If you have any problems along the way, you may refer to [this GitHub repository](https://github.com/JamesPHoughton/prisonersDilemmaDemo) that contains all the code contained in the following parts. # Part 4.1: Removing example code When you create an experiment with the `empirica create` command, Empirica populates a template experiment with the jelly bean and minesweeper code that you saw in the previous step. We won't use this example code in our experiment, so let's clean it out. There are a few steps: * delete the entire `client/src/examples` folder * In `client/src/Stage.jsx`: * remove the imports for `JellyBeans` and `MineSweeper` (2 lines) * replace the `switch` statement and its three cases (8 lines, including brackets) with the code \` ``` return (

Not yet implemented...

) ``` The file should look like this when you are done: {% code title="Stage.jsx" lineNumbers="true" %} ```jsx import { usePlayer, usePlayers, useRound, } from "@empirica/core/player/classic/react"; import { Loading } from "@empirica/core/player/react"; import React from "react"; export function Stage() { const player = usePlayer(); const players = usePlayers(); const round = useRound(); if (player.stage.get("submit")) { if (players.length === 1) { return ; } return (
Please wait for other player(s).
); } return (

Not yet implemented...

) } ``` {% endcode %} * In the `server/src/callbacks.js` file: * empty the contents of the `onGameStart` and `onStageEnded` functions, keeping the function definitions * delete everything after the empty function definition for `Empirica.onGameEnded({})`. When you are done, the file should look like this: ```javascript import { ClassicListenersCollector } from "@empirica/core/admin/classic"; export const Empirica = new ClassicListenersCollector(); Empirica.onGameStart(({ game }) => {}); Empirica.onRoundStart(({ round }) => {}); Empirica.onStageStart(({ stage }) => {}); Empirica.onStageEnded(({ stage }) => {}); Empirica.onRoundEnded(({ round }) => {}); Empirica.onGameEnded(({ game }) => {}); ``` > Note: In JavaScript, a callback function is a function that is passed as an argument to another function and is invoked or called at a specific point within that function's execution. The callback function is typically used to ensure that certain code is executed only after the completion of a specific task or operation. In our case, these callbacks are invoked when parts of the experiment start and end. #### Restart empirica Now we can restart Empirica to have it reflect our changes. The command below will remove our existing datafile and start the server. ```sh rm .empirica/local/tajriba.json; empirica ``` At this point of the tutorial, you should be able to start a new game on the admin site (). At this stage, if we login as a participant (by visiting [http://localhost:3000](http://localhost:3000/admin/)), the game will be stuck in loading, as we haven't yet added any content - that's what we'll do next! # Part 4.2: Intro Text The first step in coding our experiment will be to replace the filler text in the Introduction page with actual instructions for the participant. This text is stored the file `client/src/intro-exit/Introduction.jsx`. The component will initially look like this: {% code title="src/intro-exit/Introduction.jsx" lineNumbers="true" %} ```jsx import React from "react"; import { Button } from "../components/Button"; export function Introduction({ next }) { return (

Instruction One

Lorem ipsum, dolor sit amet consectetur adipisicing elit. Eius aliquam laudantium explicabo pariatur iste dolorem animi vitae error totam. At sapiente aliquam accusamus facere veritatis.

); } ``` {% endcode %} The function contained in this file is called a **React Component**. This is just a function that returns a piece of a page for your browser to display, and it can contain other React components within it. By assembling a number of different React components in a hierarchy, we can build up the whole page, while being able to separate reusable pieces into their own files. For example, the `Button` element is another React component that we import into this file. The button's behavior and styling are defined in a separate file (`src/components/Button.jsx`) so that we can reuse it in a number of pages in our experiment. All components need to return something that React will translate into plain HTML to display on the page. In this case, it is returning mostly HTML, with the `Button` component and a little inline styling thrown in (more on this later). For now, lets replace just the display text (and it's paragraph tags `

...

`, lines 11-15 above) with instructions related to the prisoners dilemma. Feel free to experiment with your own text and styling. The code below is what we will use in this tutorial: ```html

In this game, you will be partnered with another experiment participant.
In each round of the game, you and your partner will:

(a) choose whether to work together or to look out for your own interests

(b) see each others choices and the results of your choices

``` Within the browser, you can see these changes reflected immediately by simply saving the changed file. (In some cases, you may need to refresh the page.) This is called 'hot reloading', which is incredibly useful for debugging and UI editing.

hot reloading

Your edited file should look like this: 
import React from "react";
import { Button } from "../components/Button";

export function Introduction({ next }) {
  return (
    <div className="mt-3 sm:mt-5 p-20">
      <h3 className="text-lg leading-6 font-medium text-gray-900">
        Instruction One
      </h3>
      <div className="mt-2 mb-6">
        <p>
          In this game, you will be partnered with another experiment
          participant.
          <br />
          In <strong>each round of the game</strong>, you and your partner will:
        </p>
        <p>
          (a) choose whether to work together or to look out for your own
          interests
        </p>
        <p>(b) see each others choices and the results of your choices</p>
      </div>
      <Button handleClick={next} autoFocus>
        <p>Next</p>
      </Button>
    </div>
  );
}
# Part 4.3: Set up the game stages Now we will create placeholders for the two stages that the participants will use to play the game. First, in the **'Choice'** stage, participants will decide whether to cooperate, or defect. Second, in the **'Result'** stage, they will see the choice that their partner made, and their payoff. #### Create placeholder components Create a folder in the `client/src`. We will call it `stages`, as it will hold the code for the various stages the participant will progress through. Within this folder, we will create 2 files. First, create `Choice.jsx` with the following placeholder code: {% code title="client/src/stages/Choice.jsx" lineNumbers="true" %} ```jsx import React from "react"; export function Choice() { return
"Choice" component not yet implemented
; } ``` {% endcode %} Second, create `Result.jsx` with the following boilerplate code: {% code title="client/src/stages/Result.jsx" lineNumbers="true" %} ```jsx import React from "react"; export function Result() { return
"Result" component not yet implemented
; } ``` {% endcode %} #### Set up stage sequencing Now we need to tell Empirica that within each round of the game, participants will advance through two sequential stages: one called "**Choice"** and one called **"Result".** We do this on the server, so that Empirica can coordinate advancing all players through the stages simultaneously. The place for this is in the `onGameStart` callback, found in `server/src/callbacks.js`. This function is called when enough players have advanced to the lobby for the game to start, and it is where we can most easily modify the sequence of the game. First we need to add a 'round' to the game, using the `game.addRound` function. This function takes a dictionary with various keys, for now we'll just use the `name` key. ```javascript Empirica.onGameStart(({ game }) => { const round = game.addRound({ name: `Round`, }); }); ``` After we have created the round, we need to attach a stage to it for each of the choice and result stages: ```javascript Empirica.onGameStart(({ game }) => { const round = game.addRound({ name: `Round`, }); round.addStage({name: "choice", duration:10000}); round.addStage({name: "result", duration:10000}); }); ``` For now, we'll set the maximum duration of each stage to 10,000 seconds, after which the game will advance even if one or more players has not submitted an answer. This is to make it easier to develop the experiment. When we are getting ready to deploy our experiment, we will set this to a more reasonable number. The `server/src/callbacks.js` file should now look like this: {% code title="server/src/callbacks.js" lineNumbers="true" %} ```javascript import { ClassicListenersCollector } from "@empirica/core/admin/classic"; export const Empirica = new ClassicListenersCollector(); Empirica.onGameStart(({ game }) => { const round = game.addRound({ name: `Round`, }); round.addStage({ name: "choice", duration: 10000 }); round.addStage({ name: "result", duration: 10000 }); }); Empirica.onRoundStart(({ round }) => {}); Empirica.onStageStart(({ stage }) => {}); Empirica.onStageEnded(({ stage }) => {}); Empirica.onRoundEnded(({ round }) => {}); Empirica.onGameEnded(({ game }) => {}); ``` {% endcode %} #### Display components during the appropriate stages Now that we have placeholders for the components that will be displayed during the 'choice' and 'result' stages, and Empirica knows to coordinate these two stages, we need to tell the participant display to show the correct component during the correct time window. For this, we will return to `client/src/Stage.jsx`, which by convention handles switching displays between different stages of the game. (This is just convention, you can use any structure of React components that works for your experiment.) FIrst, we need to tell the `client/src/Stage.jsx` component which stage of the game we are currently in. We will use Empirica's `useStage` hook to gain access to the object representing the current stage in the game. ([Hooks](https://react.dev/reference/react) are React functions that return an object that can be shared across a number of different components.) First we need to import this hook by adding it to the hooks already in our import list: ```jsx import { usePlayer, usePlayers, useRound, useStage, } from "@empirica/core/player/classic/react"; ``` We then need to call the hook to gain access to the stage object. We put calls to all of the hooks at the top of the component, so the following line can go under the calls to the `useRound` hook: ``` const stage = useStage(); ``` Now we can use the value of the stage object in a `switch` statement to display a different component for each value of the stage's name. This code will replace the code `return

Not yet implemented...

;` that we used as a placeholder earlier. ```jsx switch (stage.get("name")) { case "choice": return <>; case "result": return <>; default: return ; } ``` For now, we're using a pair of empty tags in place of the objects. Lastly, we need to import the placeholder components we defined above. Import statements such as these all belong together at the top of the file: ```jsx import { Choice } from "./stages/Choice"; import { Result } from "./stages/Result"; ``` Finally, we can use these components inside the switch statement instead of the empty tags `<>`. ```jsx switch (stage.get("name")) { case "choice": return ; case "result": return ; default: return ; } ``` With all changes made, the `Stage.jsx` file should look like this: {% code title="Stage.jsx" lineNumbers="true" %} ```jsx import { usePlayer, usePlayers, useRound, useStage, } from "@empirica/core/player/classic/react"; import { Loading } from "@empirica/core/player/react"; import React from "react"; import { Choice } from "./stages/Choice"; import { Result } from "./stages/Result"; export function Stage() { const player = usePlayer(); const players = usePlayers(); const round = useRound(); const stage = useStage(); if (player.stage.get("submit")) { if (players.length === 1) { return ; } return (
Please wait for other player(s).
); } switch (stage.get("name")) { case "choice": return ; case "result": return ; default: return ; } } ``` {% endcode %} > Note: Remember to restart your server using the command `rm .empirica/local/tajriba.json; empirica` in your terminal whenever you make an update to a server-side file. Restart your server, and walk through your experiment. It should look like this:

admin and participant sites at the end of this step

# Part 4.4: Build the "Choice" React Component At this point, we'll get into a little bit more user interface design, by filling out the "Choice.jsx" placeholder we created earlier. #### Describe the Prisoner's Dilemma in Text First, we'll enter some text to describe the Prisoner's Dilemma to the participant in more detail. In our `client/src/stages/Choice.jsx` file, we can replace the "Choice component not yet implemented" text we had earlier with the following description, keeping the outer `
...
` tags. > Note: we need to use parentheses to enclose the return statement when it spans more than one line. ```jsx return (

🙀 You and your partner in crime have been arrested! 🙀

  • If you both 🤐🤐 keep silent, you will both get 2 months in jail.
  • If you 📣 testify against your partner and he 🤐 keeps silent, you will only spend 1 month in jail.
  • If you 🤐 keep silent, but your partner 📣 testifies, you get 12 months in jail.
  • If you both 📣📣 testify, you both get 6 months in jail.

What do you do?

); ``` In this description, we use standard HTML tags for an unordered list to format the text (for more information, see [here](https://www.w3schools.com/html/default.asp)). If you save the file at this point and return to your browser, you should be able to see the text we just entered formatted nicely. #### Add buttons for each option We also want to add a button for each choice. First we need to import the button component at the top of the file: ```jsx import { Button } from "../components/Button"; ``` Now we can create the button components themselves. These will sit below the text, but within the outermost `
` tag. We will enclose them in additional `
` tags so that we can apply some styling to them independently of the rest of the page ```jsx
``` The `className` attribute here is a list of inline styling parameters, which follow the format of [Tailwind CSS](https://tailwindcss.com/). You don't need to know anything else about this now, other than to know that [`flex`](https://tailwindcss.com/docs/flex) allows components to adjust to the size of the window, and [`justify-center`](https://tailwindcss.com/docs/justify-content#center) centers the contents of the `
`. There are a wide variety of styling keywords you can use to structure your pages, and it is well worth reading through the Tailwind documentation. In addition to styling the `
` we can also apply style to the buttons themselves. In this case, we'll add 5 pixels of margin around each button, to separate them from one another and the remaining content, as below: ```jsx
``` #### Handle the button clicks If you click the buttons at this point, nothing will happen, because we haven't "handled" the button click event. To do so, we need to create a new function that will be called when a button is clicked. This function will live inside the `Choice` component, prior to the `return` statement, and should take a single parameter that indicates which button was clicked. For now, all it will do is log the value of the parameter that was passed into it: ```javascript function onClick (choice) { console.log("You chose:", choice) }; ``` Now we need to make sure this function gets called when the button is clicked. If you look at the file in which the Button component is defined, you'll notice that it has a `handleClick` argument that accepts a function to be called when the button is clicked. We can't pass our `onClick` function directly into this argument, however, because we need to specify the value of the `choice` that will be passed to `onClick`. We do this with an [arrow function](https://javascript.info/arrow-functions-basics). The function will take an empty argument list `()` and then call the `onClick` function for us, with the right value of the argument. For example: ```javascript () => onClick("silent") ``` defines a function we can pass along to our button component that will then call our `onClick` function with the choice "silent". Our code for the button components now should look like this: ```jsx ``` Now if you return to the browser, and click the buttons, you should see the name of the button output to the browser console. {% hint style="warning" %} Wait! What's the browser console?\ \ The browser console is your best friend for debugging. You can open the console in chrome by clicking the three vertical dots in the upper right corner, and navigating to "More tools > Developer Tools". (Or on a mac, pressing `+