@bdelab/roar-tasks

Description

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.

App code flow

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

How the task launcher works

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();

What is firekit?

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.

Project structure

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.

Current Tasks & Parameters

In standalone web app mode, tasks and parameters can be changes through query strings. These query string parameters are listed below.

Common Parameters

_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}

Math (includes Number Line) - Default

Matrix Reasoning

Mental Rotation

Hearts and Flowers

Memory Game

Same Different Selection

TROG

Theory of Mind

How ROAR / LEVANTE Tasks work within the greater ROAD infrastructure

Data flow diagram

End to End Testing

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