The tasks are all housed in this single repo using a monorepo like-structure. Which task is run is selected at run time based on the passed in parameters (e.g. ?task=egma-math). This can be run standalone as a web app or as an npm package (in ROAD for example). The 'Task Launcher' is simply the name of the class that runs the whole app code.
As a Standalone web app
serve.js -> index.js -> taskConfig.js -> load assets, corpus, setup store -> jsPsych timeline is ran
As a npm package
wherever the package is used -> index.js -> taskConfig.js -> load assets, corpus, setup store -> jsPsych timeline is ran
The app can run in two different modes, and as such uses two different build processes. For standalone, the code is built with Webpack. As an npm package, the code is built with Rollup. They work fundamentally the same regardless of where they are run.
The TaskLauncher class takes in 4 parameters, 1 being optional. firekit, game params, user params, and the display element to attach the jsPsych code to. The display element is optional.
As a Standalone web app
As a standlone web app, the built code includes the serve folder. The entry point is in serve.js.
This folder also includes the config for Firestore.
serve.js includes some additional hooks (functions) from Firebase to check authentication.
In this mode, however, we do not use any authentication but treat the user as a guest.
The TaskLauncher class requires 3 things to run: firekit, user params, and game params. In standalone, we get all the parameters we need for the game from query strings.
As a npm package (In development)
As an npm package the packaged code does not include the serve folder.
You use it as you would any typical npm package:
Install it, import it, and run the code.
As with standalone deployment, it requires a firekit instance, game params, and user params.
Import TaskLauncher from 'core-tasks'
const task = new TaskLauncher(firekit, gameParams, userParams);
task.run();
Firekit is an SDK developed by the ROAR team that allows for a streamlined interaction with Firestore and Firebase. It provides useful functions and tools for task development.
Currently under development
The overarching goal of this project is to simplify task developent, improve productivity, and decrease task development time. Previously, each task was in its own separate repo which led to a ton of WET ("Write Everything Twice" or in this case X times the amount of tasks) code.
Task specifc code lives in the task folder. Each child folder is named after it's respective task name.
Within that there is a trials folder containing timeline.js.
There may be additional helper functions in a helper directory.
Common code that is used throughout multiple tasks is in the shared directory.
This also has a helpers and a trials folder.
taskSetup.js defines global instances / variables that we need to pass all throughout the tasks.
taskConfig.js is where everything comes together for a task. There are 5 main parts to a task, the config, the store (you can think of this as global state), how to load the corpus (if the task needs it), where to get translations (TBD), and how to build the task timeline.
All of these parts in the task config file are ran after recieving the corresponding task name.
In standalone web app mode, tasks and parameters can be changes through query strings. These query string parameters are listed below.
_Note: All tasks are timed. The default is listed below.
task: 'egma-math' | 'matrix-reasoning' | 'mental-rotation' | 'hearts-and-flowers' | 'memory-game' | 'same-different-selection' | 'theory-of-mind' | 'trog' [string] (optional)
age: [number] (optional) ,
audioFeedback: "neutral" ['string'] (optional) {Default: "neutral"},
skipInstructions: [boolean] (optional) {Default: true},
sequentialPractice: [boolean] (optional) {Default: true},
sequentialStimulus: [boolean] (optional) {Default: true},
corpus: "*task-name-here*-item-bank" [string] (optional) {Default: math-item-bank},
buttonLayout: "default" | "grid" | "column" | "diamond" | "triple" [string] (optional) {Default: "default"},
trials: [number] (optional),
stimulusBlocks: [number] (optional) {Default: 3},
numOfPracticeTrials: [number] (optional) {Default: 2},
maxIncorrect: [number] (optional) {Default: 3},
maxTime (minutes): [number] (optional) {Default: 100},
keyHelpers: [boolean] (optional) {Default: true},
storeItemId: [boolean] (optional) {Default: false},
pid: [string] (optional) {Default: random generated string}
We leverage the cypress framework for end to end testing. The tests are located in the cypress directory. To run the tests, you can use the following command:
# Ensure dependencies are installed
npm install
# Run the tests
npx cypress open