Addition of the Triple Handle Controller plugin for continuous, three-dimensional affective ratings

packages/plugin-triple-handle-controller/README.md

@@ -0,0 +1,38 @@
+# triple-handle-controller plugin
+
+## Overview
+
+This plugin collects responses to a video file in real time using a game controller.
+
+## Loading
+
+### In browser
+
+```js
+<script src="https://unpkg.com/@jspsych-contrib/[email protected]">
+```
+
+### Via NPM
+
+```
+npm install @jspsych-contrib/plugin-triple-handle-controller
+```
+
+```js
+import jsPsychTripleHandleController from "@jspsych-contrib/plugin-triple-handle-controller";
+```
+
+## Compatibility
+
+This extension was tested with jsPsych v8.1.0.
+
+## Documentation
+
+The documentaion can be read [here](/docs/index.md).
+
+## Author / Citation
+
+Created by [Caluã de Lacerda Pataca](https://www.caluapataca.com) and [Russell Lee](https://github.com/rl2939).
+
+### Citation
+de Lacerda Pataca, C., & Lee, R. (2024, December 8). A jsPsych Plugin for Continuous Real-Time Valence, Arousal, and Dominance Reporting Using a Three-Handle Controller. https://doi.org/10.31234/osf.io/snr5u

packages/plugin-triple-handle-controller/docs/index.md

@@ -0,0 +1,85 @@
+# triple-handle-controller
+
+Current version: 1.0.2. [See version history](https://github.com/jspsych/jsPsych/blob/main/packages/plugin-triple-handle-controller/CHANGELOG.md).
+
+This plugin displays a video and records inputs from the participant via a game controller. This plugin requires an external game controller with at least one or more analogue input devices, such as a handle or a pressure sensitive button. The recording of data starts when the user presses the record button and ends when the video stops.
+
+The plugin will record data as indicated by the _rate_ variable (how many times it will record per second).
+
+## Parameters
+
+In addition to the [parameters available in all plugins](https://www.jspsych.org/latest/overview/plugins/index.html#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of _undefined_ must be specified. Other parameters can be left unspecified if the default value is acceptable.
+
+| Parameter     | Type    | Default Value                       | Description                                                                                                                                                                                                                           |
+| ------------- | ------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| title         | string  | undefined                           | The title to appear above the video.                                                                                                                                                                                                  |
+| video_src     | string  | undefined                           | The url of the video location.                                                                                                                                                                                                        |
+| axis_1        | numeric | undefined                           | The input number of the first axis.                                                                                                                                                                                                   |
+| axis_2        | numeric | undefined                           | The input number of the second axis.                                                                                                                                                                                                  |
+| axis_3        | numeric | undefined                           | The input number of the third axis.                                                                                                                                                                                                   |
+| axis_location | complex | ["L", "H", "R"]                     | An array of three characters which will indicate the placement of each of the three axises on screen. "L" places the axis on the left of the screen, "R" places the axis on the right of the screen, and "H" hides the axis entirely. |
+| axes_labels   | complex | ["axis1", "axis2", "axis3"]         | An array of the three axis names. If an axis is not going to be used, then an empty string ("") can be used in place of the name.                                                                                                     |
+| axis1_labels  | complex | ["low", "neutral", "high"]          | An array of labels for axis 1. The label in index 1 appears near the bottom of the axis, the one in index 2 appears near the middle, and the one in index 3 appears near the top.                                                     |
+| axis2_labels  | complex | ["negative", "neutral", "positive"] | An array of labels for axis 2. The label in index 1 appears near the bottom of the axis, the one in index 2 appears near the middle, and the one in index 3 appears near the top.                                                     |
+| axis3_labels  | complex | ["a", "b", "c"]                     | An array of labels for axis 3. The label in index 1 appears near the bottom of the axis, the one in index 2 appears near the middle, and the one in index 3 appears near the top.                                                     |
+| controller_detection_message | string | A controller with throttles has not been detected. \n If you have already plugged one in, please try pressing any \n of its buttons or sliding its throttles to activate it. | The message to tell the user to connect or activate a controller. |
+| play_string 	| string | Play 								| String to represent the play button. |
+| pause_string 	| string | Pause 								| String to represent the pause button. |  
+| record_string | string | Record 								| String to represent the record button. |
+| try_again_string | string | Try again 						| String to represent the "Try again" button. |
+| save_string 	| string | Save 								| String to represent the save button.|
+| rate          | numeric | 1000                                | Number of miliseconds between each data call.                                                                                                                                                                                         |
+
+## Data Generated
+
+In addition to the [default data collected by all plugins](https://www.jspsych.org/latest/overview/plugins/index.html#data-collected-by-all-plugins), this plugin collects the following data for each trial.
+
+| Name        | Type    | Value                                                                                                                                                                              |
+| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| data_arrays | array   | An array of three arrays, each representing an different input device. Each of the three arrays inside contains a value of the handle taken as often as set in the rate parameter. |
+| rate        | numeric | Number of miliseconds between each data call.                                                                                                                                      |
+| video_src   | string  | A URL to a copy of the videodata.                                                                                                                                                  |
+| duration    | numeric | The length of the video, in seconds.                                                                                                                                               |
+
+
+
+## Examples
+
+This code runs an experiment involving two levers.
+
+
+```
+        const videos = ["Test.webm"];
+
+        var experiment = [
+            {
+                type: jsTripleHandleController,
+                axis_1: 0,
+                axis_2: 1,
+                axis_3: 2,
+                axis_location: ["L", "R", "H"],
+                axis1_labels: ["No", "Maybe", "Yes"],
+                axis2_labels: ["0%", "50%", "100%"],
+                css_clases: ["thc-override"],
+                axes_labels: ["axis1 (axis 1)", "axis2 (axis 2)", "item 3 (axis 3)"],
+                title: "Follow the instructions in the video.",
+                // A monitor refresh rate of 60 Hz means that
+                // the screen changes every 16.7 ms or higher.
+                rate: 1000 / 60, //16.777...
+            },
+        ];
+
+        async function createExperiment() {
+            const videoSrc = `./videos/${videos[0]}`;
+            experiment[0].video_src = videoSrc;
+            jsPsych.run(experiment);
+        }
+
+        createExperiment();
+```
+
+## Demo
+
+See the examples folder.
+
+The bullet train video (BulletTrainFriction.webm) is from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:BulletTrainFriction.webm), under the [Creative Commons CC0 1.0 Universal Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/deed.en).

packages/plugin-triple-handle-controller/examples/index.html

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <title>Axis1/Axis2/Axis3 Measurements</title>
+    <meta name="description" content="" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <script src="https://unpkg.com/[email protected]"></script>
+    <script src="https://unpkg.com/@jspsych/[email protected]"></script>
+    <script src="../src/index.js"></script>
+    <link
+      href="https://unpkg.com/[email protected]/css/jspsych.css"
+      rel="stylesheet"
+      type="text/css"
+    />
+    <link
+      rel="icon"
+      href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🧪</text></svg>"
+    />
+
+    <style>
+      @import url("https://fonts.googleapis.com/css2?family=Inter:slnt,[email protected],200..900&display=swap");
+
+      :root {
+        --primary: 32, 107, 248;
+        --paperColor: 255, 253, 245;
+        --column-width: 720px;
+      }
+
+      body {
+        background-color: rgb(var(--paperColor));
+        margin: 0;
+        padding: 0;
+      }
+
+      .jspsych-display-element,
+      .jspsych-display-element input[type="text"],
+      .jspsych-btn,
+      button,
+      textarea,
+      p,
+      * {
+        font-family: "Inter", sans-serif;
+      }
+
+      #jspsych-content {
+        width: 100%;
+        max-width: unset;
+      }
+
+      #thc-player {
+        background-color: black;
+      }
+    </style>
+  </head>
+  <body>
+    <script>
+      let jsPsych = initJsPsych({
+        on_finish: function () {
+          jsPsych.data.displayData();
+        },
+      });
+      const subjectId = jsPsych.randomization.randomID(10);
+      const filename = `${subjectId}.json`;
+
+      const videos = ["BulletTrainFriction.webm"];
+
+      jsPsych.data.addProperties({
+        subject: subjectId,
+      });
+
+      let experiment = [
+        {
+          type: jsTripleHandleController,
+          axis_1: 0,
+          axis_2: 1,
+          axis_3: 2,
+          axis_location: ["L", "R", "L"],
+          axis1_labels: ["low", "neutral", "high"],
+          axis2_labels: ["negative", "neutral", "positive"],
+          css_clases: ["thc-override"],
+          axes_labels: ["axis1 (axis 1)", "axis2 (axis 2)", "item 3 (axis 3)"],
+          title: "Bullet Train Friction",
+          // A monitor refresh rate of 60 Hz means that
+          // the screen changes every 16.7 ms or higher.
+          rate: 1000 / 60,
+        },
+      ];
+
+      async function createExperiment() {
+        const videoSrc = `./videos/${videos[0]}`;
+        experiment[0].video_src = videoSrc;
+        jsPsych.run(experiment);
+      }
+
+      createExperiment();
+    </script>
+  </body>
+</html>

packages/plugin-triple-handle-controller/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@jspsych-contrib/plugin-triple-handle-controller",
+  "version": "1.0.0",
+  "description": "This plugin collects responses to a video file in real time using a game controller.",
+  "unpkg": "dist/index.browser.min.js",
+  "files": [
+    "index.js",
+    "dist"
+  ],
+  "scripts": {
+    "build": "babel index.js --presets @babel/preset-env,minify --source-maps --out-file dist/index.browser.min.js",
+    "build:watch": "npm run build -- --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jspsych/jspsych-contrib.git",
+    "directory": "packages/plugin-triple-handle-controller"
+  },
+  "contributors": ["Caluã de Lacerda Pataca", "Russell Lee"],
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/jspsych/jspsych-contrib/issues"
+  },
+  "homepage": "https://github.com/jspsych/jspsych-contrib/tree/main/packages/plugin-triple-handle-controller",
+  "devDependencies": {
+    "@jspsych/config": "^3.2.1",
+    "jspsych": "^8.1.0",
+    "prettier": "^2.8.4"
+  }
+}