MetaForge Help

← Back to Home

Welcome to MetaForge!

MetaForge is a powerful visual experiment builder for behavioral research. Create professional jsPsych experiments without writing code. This comprehensive guide will walk you through every feature, step by step.

📑 Table of Contents

🚀 Getting Started

Creating Your Account

  1. Visit MetaForge
    Go to the MetaForge website and you'll see the welcome screen.
  2. Sign In
    Choose between:
    • Google Sign-In: Click "Sign in with Google" for quick access
    • Email & Password: Create an account with your email
  3. Access Your Projects
    After signing in, you'll automatically be taken to your Projects page.
💡 Tip:

Your experiments are automatically saved to the cloud, so you can access them from any device!

📁 Managing Projects

Creating a New Project

  1. Click the "New Project" button on your Projects page
  2. Enter a Title for your experiment
  3. Optionally add a Subtitle and Description
  4. Click "Create" to open the editor

Organizing Your Projects

Search & Filter

Project Actions

Each project card has action buttons:

⚠️ Important:

Deleted projects cannot be recovered. Make sure to duplicate important experiments before deleting!

✏️ Editor Basics

Understanding the Interface

The MetaForge editor has three main panels:

Left Sidebar (Trial Editor)

Configure individual trials and their settings. This is where you'll spend most of your time building experiments.

Center Panel (Preview)

See a live preview of your experiment. What you see here is what participants will experience.

Right Sidebar (Timeline)

View and organize all trials in your experiment. Drag and drop to reorder trials.

Basic Workflow

  1. Add a Trial
    Click the "Add Trial" button in the Timeline panel
  2. Choose a Trial Type
    Select from the available plugins (see Trial Types)
  3. Configure the Trial
    Use the left sidebar to set up your trial's content and options
  4. Preview
    Check the center panel to see how it looks
  5. Repeat
    Add more trials to build your complete experiment
💡 Tip:

Your work is automatically saved every few seconds. Look for the "Saved" indicator at the bottom of the left sidebar.

🎯 Trial Types

MetaForge offers 11 different trial types, each designed for specific research needs. Here's a complete guide:

1. HTML Button Response

Best for: Multiple choice questions, consent forms, demographic surveys

What it does: Shows text or images with clickable buttons for responses.

Key Settings:

Example Choices: "Strongly Agree,Agree,Neutral,Disagree,Strongly Disagree"

2. HTML Keyboard Response

Best for: Reaction time tasks, go/no-go tasks, categorization experiments

What it does: Shows content and waits for participants to press specific keyboard keys.

Key Settings:

Example Allowed Keys: "f,j" (common for binary classification tasks)

3. HTML Slider Response

Best for: Rating scales, confidence judgments, continuous measurements

What it does: Presents a slider that participants move to indicate their response.

Key Settings:

4. Canvas Button Response

Best for: Custom visual stimuli, drawings, dynamic graphics

What it does: Lets you draw custom graphics using JavaScript code, then collect button responses.

Key Settings:

💡 Tip:

Click "Edit Canvas Function" to open a full-screen code editor. The default template gives you a starting point!

5. Canvas Keyboard Response

Best for: Custom stimuli with keyboard responses, rapid visual presentation

What it does: Same as Canvas Button Response, but collects keyboard presses instead.

Key Settings:

6. Instructions

Best for: Multi-page instructions, consent forms, tutorials

What it does: Shows multiple pages of content with forward/back navigation.

Key Settings:

7. Survey Multi-Choice

Best for: Multiple choice questionnaires, demographic forms

What it does: Creates forms with radio buttons or dropdown menus.

Key Settings:

💡 Tip:

Use the "Survey Flow" button in the Timeline panel for a visual question builder!

8. Survey Text

Best for: Open-ended responses, free text answers

What it does: Creates forms with text input fields.

Key Settings:

9. Preload

Best for: Loading images, audio, and video before the experiment

What it does: Downloads media files in advance to prevent delays during the experiment.

Key Settings:

💡 Tip:

Add a Preload trial at the beginning of your experiment. Turn on "Auto-preload" to automatically load all your uploaded images!

10. Fullscreen

Best for: Entering or exiting fullscreen mode

What it does: Switches the experiment to fullscreen (or exits fullscreen).

Key Settings:

11. Generic Plugin

Advanced

Best for: Using jsPsych plugins not built into MetaForge

What it does: Lets you use any jsPsych plugin by writing custom code.

Key Settings:

⚠️ Advanced Feature:

This requires knowledge of jsPsych and JavaScript. See the jsPsych documentation for available plugins.

📋 Timeline & Blocks

Understanding the Timeline

The Timeline is the sequence of trials that participants experience. It's shown in the right sidebar.

Basic Timeline Operations

Creating Blocks

Blocks are groups of trials that share common settings. They're useful for:

How to Create a Block

  1. Select multiple trials by clicking them (they'll highlight)
  2. Click the "Create Block" button
  3. Your selected trials are now grouped together
  4. Configure block-level settings in the left sidebar

Block Settings

Setting What It Does
Repetitions How many times to run all trials in the block
Randomize Shuffle trial order within the block each time
Timeline Variables Apply variables to all trials in the block (see below)
Conditional Function Code to determine if the block should run
On Start/Finish Code to run before/after the block
💡 Example Use Case:

Create a practice block with 5 trials, set repetitions to 1, randomize on. Then create a test block with the same trials, set repetitions to 5, randomize on. Participants get randomized practice, then 5 randomized test blocks!

🔄 Timeline Variables

What Are Timeline Variables?

Timeline Variables let you create one trial template and automatically generate many variations. This is perfect for:

How to Use Timeline Variables

  1. Create a Trial or Block
    Select the trial(s) you want to vary
  2. Open Timeline Variables
    Click "Advanced Options" → "Timeline Variables"
  3. Choose Input Mode
    • Table View: Visual spreadsheet-like interface
    • CSV: Paste data from Excel or Google Sheets
    • Text: Write JSON directly
  4. Define Your Variables
    Each column is a variable, each row is one trial repetition
  5. Use Variables in Trials
    Reference variables using {{variableName}} syntax

Example: Word Memory Task

Step 1: Create an HTML Keyboard Response trial

Step 2: Set up Timeline Variables table:

word category correctKey
apple fruit f
carrot vegetable v
banana fruit f
broccoli vegetable v

Step 3: In the trial's stimulus field, write:

<p>Is {{word}} a fruit or vegetable?</p> <p>Press 'f' for fruit, 'v' for vegetable</p>

Result: One trial becomes four trials, each showing a different word!

Sampling Modes

Mode What It Does
Sequential Shows rows in the order you defined
Random Shuffles rows, each shown once
Random with Replacement Randomly picks rows, same row can appear multiple times

Advanced Features

Sample Size

Only show a subset of rows. For example, if you have 20 rows but only want to show 10 random ones.

Weighted Sampling

Add a column named weight to control probability. Higher weights = more likely to appear.

Frequency Sampling

Add a column named frequency to specify exact repetitions. A frequency of 3 means that row appears exactly 3 times.

💡 Pro Tip:

You can have timeline variables at both the trial level AND block level. Block-level variables create combinations with trial-level variables!

🖼️ Media Upload & Management

Uploading Images

MetaForge provides cloud storage for your experiment media.

  1. Open the Image Gallery
    In the rich text editor toolbar, click the image icon
  2. Upload Files
    Either:
    • Click "Upload Images" and select files
    • Drag and drop files into the upload zone
  3. Insert into Trial
    Click on an uploaded image to insert it into your stimulus

Supported File Types

Managing Your Media

Using Media in Timeline Variables

You can reference uploaded images in timeline variables:

stimulus condition
uploads/yourUserId/face1.jpg happy
uploads/yourUserId/face2.jpg sad

Then in your trial stimulus:

<img src="{{stimulus}}" alt="{{condition}}">

Batch Generate Timeline Variables from Images

MetaForge includes a powerful feature to automatically create trials with timeline variables from multiple images at once.

  1. Create or Select a Trial
    Start with any trial type (HTML Button Response, HTML Keyboard Response, etc.). The new trial will inherit the plugin type and settings from your current trial.
  2. Open the Image Gallery
    Click the image icon in the toolbar to open the gallery
  3. Select Multiple Images
    Use the checkboxes to select the images you want to include in your sequence. You can:
    • Click individual checkboxes to select specific images
    • Click "Select All" to select all images
    • Click "Deselect All" to clear your selection
  4. Generate Timeline Variables
    Click the "Generate Timeline Variables" button

What happens automatically:

💡 Tip:

Use the Preload trial with "Auto-preload" enabled to automatically load all your images before the experiment starts!

✨ Pro Tip:

This feature is perfect for creating image sequence trials like Raven's Progressive Matrices, face recognition tasks, or any experiment that shows multiple images in sequence. You can customize the order (sequential, random, or random with replacement) and other timeline variable settings after the trial is created!

📝 Rich Text Editor

Formatting Tools

The stimulus editor includes powerful formatting options:

Text Formatting

Bold, Italic, Underline, Strikethrough

Text Size

Increase or decrease font size with + and - buttons

Colors

Change text color and background color

Fonts

Choose from multiple font families

Alignment

Left, Center, Right text alignment

Lists

Create numbered or bulleted lists

Links

Insert clickable hyperlinks

Code

Format text as inline code

Images

Insert images from your gallery

HTML Mode

Toggle between visual editing and raw HTML:

Using Timeline Variables in Text

You can insert timeline variable placeholders anywhere:

  1. Click the "Insert Variable" button ({{x}} icon)
  2. Type the variable name
  3. The variable will be replaced when the trial runs
Example: <p>Welcome, {{participantName}}!</p>
⚠️ Note:

Timeline variables only work if you've defined them in the Timeline Variables section!

⚙️ Experiment Settings

Click the "Experiment Options" button at the top of the editor to access global settings.

Metadata Tab

Basic information about your experiment:

Display Tab

Visual appearance settings:

Colors

Fullscreen

Custom Styling

Variables Tab

Define experiment-wide JavaScript variables:

Code Tab

Advanced

Add custom JavaScript that runs before your experiment starts:

Developer Tab

Testing and debugging options:

💡 Tip:

Use the simulation mode to quickly test your experiment without clicking through manually!

💾 Data Collection & Storage

Where Does Data Go?

MetaForge offers multiple options for storing participant data:

1. MetaForge Hosting (Default)

When you publish to MetaForge (see Deployment), data is automatically saved to Firestore:

Viewing Response Count

After publishing your experiment, you can track responses in real-time:

Downloading Data

You can download participant data from multiple locations:

  1. From Deploy Tab (Recommended):
    Experiment Options → Deploy → Data Collection → Click "📥 Download Data"
  2. From Data Storage Tab:
    Experiment Options → Data Storage → Click "Download Participant Data"
  3. Data downloads as CSV with all participant responses

2. OSF Integration

Automatically upload data to the Open Science Framework:

  1. Create an OSF Project
    Go to osf.io and create a project
  2. Get Your API Token
    OSF Settings → Personal Access Tokens → Create Token
  3. Configure in MetaForge
    Experiment Options → Data Storage → Enter OSF Project URL and API Token
  4. Test Connection
    Click "Test Connection" to verify

Data will now upload to OSF when participants complete your experiment!

3. Local Download

Participants can download their own data:

Custom Data Fields

Add extra information to each trial:

  1. Click "Advanced Options" on a trial
  2. Expand "Custom Code"
  3. Use "Custom Data" function to add fields
Example: { condition: "experimental", block: "practice", trial_type: "recognition" }
💡 Best Practice:

Always include a Preload trial and test data saving before launching your study!

👥 Participant Management Platforms

SONA Systems Integration

Connect your experiment to SONA for automatic credit granting:

  1. Get SONA Experiment ID
    Create your experiment in SONA and note the Experiment ID
  2. Get Credit Token
    In SONA, go to experiment settings and generate a credit token
  3. Configure in MetaForge
    Experiment Options → Deploy → SONA Settings → Enter ID and Token
  4. Add Study URL to SONA
    Copy the MetaForge experiment URL and add ?sona_id=%SURVEY_CODE%

Example SONA URL:

https://yoursite.com/host.html?id=exp123&sona_id=%SURVEY_CODE%

Prolific Integration

Create and manage Prolific studies directly from MetaForge:

Setup

  1. Get Prolific API Token
    Log into Prolific → Settings → API Tokens → Create Token
  2. Configure in MetaForge
    Experiment Options → Deploy → Prolific Settings → Enter API Token
  3. Set Completion Code
    Create a unique code participants will see when they finish

Creating a Study

  1. Click "Create Prolific Study" button
  2. MetaForge automatically:
    • Creates the study on Prolific
    • Sets the study URL to your experiment
    • Configures completion code
    • Adds PROLIFIC_PID tracking
  3. Finish setup on Prolific (set payment, participants, etc.)

URL Parameters

MetaForge automatically captures these URL parameters:

Parameter Platform What It Stores
sona_id SONA Participant's SONA ID for credit granting
PROLIFIC_PID Prolific Participant's Prolific ID
STUDY_ID Prolific Prolific study ID
SESSION_ID Prolific Prolific session ID
💡 Tip:

All URL parameters are automatically saved in your data, so you can link responses back to participants!

🚀 Publishing & Deployment

Export Options

Click "Actions" menu at the top to access export options:

1. Download as HTML

What you get: A single HTML file with everything embedded

Use for:

2. Export Configuration (.jsexp)

What you get: A JSON file with your experiment structure

Use for:

3. Download as Webloc (macOS)

What you get: A bookmark file that opens your experiment in the editor

Use for: Quick access on macOS

Hosting Options

MetaForge Hosting (Recommended)

Easiest option - no setup required!

  1. Open Experiment Options
    Click "Experiment Options" button at the top of the editor
  2. Enable MetaForge Hosting
    Go to "Deploy" tab → Turn ON "MetaForge Hosting" toggle
  3. Publish Your Experiment
    Click the "🚀 Publish to MetaForge" button that appears
    (The dialog will close automatically and show your shareable URL)
  4. Copy & Share
    Copy the participant URL from the success dialog and share with participants

Participant URL format:

https://yoursite.com/host.html?id=yourExperimentId

Managing Your Published Experiment

After publishing, you'll see a status badge on the editor header and in your Projects page:

Data Collection Controls

Once published, you can manage data collection from Experiment Options → Deploy tab:

⚠️ Publishing Updates to Live Experiments:

If you publish changes to an experiment that already has participant data, MetaForge will warn you. Publishing updates to live experiments may affect data consistency and could impact participants currently taking the experiment. Always review changes carefully before publishing updates.

Stopping Data Collection

To prevent new participants from taking your experiment:

  1. Experiment Options → Deploy → Data Collection section
  2. Click the "🔴 Closed" button
  3. Participants will now see a "Study Closed" message instead of your experiment
  4. You can still download all collected data

Features:

GitHub Pages Hosting

For public, shareable experiments

  1. Get GitHub Token
    GitHub → Settings → Developer Settings → Personal Access Tokens → Generate Token
  2. Configure in MetaForge
    Experiment Options → Deploy → GitHub Pages
    Enter: Username, Token, Repository Name
  3. Publish
    Click "Deploy to GitHub Pages"
  4. Get URL
    Your experiment will be at: https://username.github.io/repository-name/

Features:

OSF Hosting

For open science projects

  1. Configure OSF settings (see Data Collection)
  2. Click "Upload to OSF"
  3. Experiment files uploaded to your OSF project

Testing Before Launch

⚠️ Important Checklist:
  • ✓ Test the experiment yourself completely
  • ✓ Verify data is being saved correctly
  • ✓ Check on different browsers (Chrome, Firefox, Safari)
  • ✓ Test on mobile if participants will use phones
  • ✓ Verify all images load properly
  • ✓ Test SONA/Prolific integration if using
  • ✓ Run through with a colleague

🤝 Collaboration & Sharing

Sharing Projects

Collaborate with colleagues by sharing experiments:

  1. Open Project Card
    Go to your Projects page
  2. Click Share Button
    Click the share icon on the project you want to share
  3. Enter Collaborator Email
    Type the email address of your colleague
  4. Choose Permission Level
    Select "View" or "Edit" access
  5. Send Invitation
    Click "Share" - they'll receive access immediately

Permission Levels

Role Can View Can Edit Can Share Can Delete
Owner ✅ ✅ ✅ ✅
Edit ✅ ✅ ❌ ❌
View ✅ ❌ ❌ ❌

Team Library

Save experiments as templates for your team:

  1. Click the "Save to Library" button on a project card
  2. Project is added to the Public Library
  3. Team members can duplicate it to start new experiments

Trial Library

Save individual trials for reuse:

  1. Save a Trial
    While editing a trial, click "Advanced Options" → "Save to Library"
  2. Use in Other Experiments
    Click "Library" button in Timeline → Select saved trial
💡 Workflow Tip:

Create a template experiment with common trials (consent, demographics, instructions). Save to team library. Start all new experiments by duplicating the template!

🔧 Advanced Features

Custom JavaScript Code

Advanced

MetaForge supports custom JavaScript for advanced users:

Trial-Level Custom Code

Click "Advanced Options" on any trial to access:

Function When It Runs Use For
on_load When trial appears Modify display, start timers, custom animations
on_finish When trial ends Process responses, calculate scores, update variables
Conditional Display Before trial runs Show/hide trial based on previous responses
Custom Data During trial Add metadata to saved data

Example: Conditional Display

Only show a trial if participant got previous answer correct:

function() { const lastTrial = jsPsych.data.get().last(1).values()[0]; return lastTrial.correct === true; }

Example: Custom Data

Add extra fields to the data:

{ experimentPhase: "practice", stimulusCategory: "faces", responseDeadline: 2000 }

Canvas Function Editor

Create custom visual stimuli with JavaScript:

  1. Add a Canvas Button or Canvas Keyboard trial
  2. Click "Edit Canvas Function"
  3. Write JavaScript to draw on the canvas

Example: Draw a Circle

function draw(canvas) { const ctx = canvas.getContext('2d'); ctx.clearRect(0, 0, canvas.width, canvas.height); // Draw circle ctx.beginPath(); ctx.arc(150, 150, 50, 0, 2 * Math.PI); ctx.fillStyle = '#4c8dff'; ctx.fill(); // Add text ctx.font = '20px Arial'; ctx.fillStyle = 'black'; ctx.textAlign = 'center'; ctx.fillText('Click a button!', 150, 250); }

Using Functions in Fields

Some fields accept JavaScript functions instead of static values:

Dynamic Stimulus

Instead of static HTML, use a function:

function() { const trialNumber = jsPsych.data.get().count() + 1; return `<p>This is trial ${trialNumber}</p>`; }

Dynamic Choices

Generate button choices dynamically:

function() { const options = ['Red', 'Green', 'Blue']; return jsPsych.randomization.shuffle(options); }

Accessing jsPsych Data

In any custom code, you can access experiment data:

// Get all data const allData = jsPsych.data.get(); // Get last trial const lastTrial = jsPsych.data.get().last(1).values()[0]; // Filter by type const buttonTrials = jsPsych.data.get().filter({trial_type: 'html-button-response'}); // Get specific column const allRTs = jsPsych.data.get().select('rt').values;

Survey Flow Builder

Visual tool for complex surveys:

  1. Add a Survey Multi-Choice or Survey Text trial
  2. Click "Survey Flow" button in the Timeline
  3. Add questions with drag-and-drop interface
  4. Create randomizer blocks for question randomization
  5. Reorder questions by dragging

Simulation Mode

Automatically test your experiment:

  1. Click "Actions" → "Simulate Experiment"
  2. jsPsych will automatically:
    • Make random button clicks
    • Press random keys
    • Fill in survey responses
    • Complete the entire experiment
  3. Review simulated data to verify everything works
💡 Pro Tip:

Set a random seed in Developer Options to make simulations reproducible. Same seed = same responses every time!

Generic Plugin

Use any jsPsych plugin not built into MetaForge:

  1. Find the plugin on the jsPsych website
  2. Add a Generic Plugin trial
  3. Enter:
    • Plugin Script Path: URL to the plugin's .js file
    • Plugin Type Name: Name of the plugin (e.g., "imageButtonResponse")
    • Trial Code: JavaScript object with trial parameters
⚠️ Advanced Users Only:

Generic plugins require knowledge of jsPsych's plugin system. See the jsPsych documentation for details.

💡 Tips & Best Practices

Experiment Design

Data Quality

Performance

Organization

Collaboration

🔍 Troubleshooting

Common Issues

Images Not Showing

Solutions:

Data Not Saving

Solutions:

Timeline Variables Not Working

Solutions:

Experiment Won't Preview

Solutions:

SONA/Prolific Integration Not Working

Solutions:

Getting Help

If you're stuck:

🎉 Ready to Build!

You now have a complete understanding of MetaForge's features. Whether you're creating a simple survey or a complex behavioral experiment, MetaForge provides the tools you need.

Quick Start Summary

  1. Create a Project - Sign in and click "New Project"
  2. Add Trials - Build your experiment trial by trial
  3. Configure Settings - Set up data collection and display options
  4. Test Thoroughly - Preview and test on multiple devices
  5. Publish - Deploy to MetaForge or GitHub Pages
  6. Collect Data - Share with participants and gather responses
🚀 Next Steps:

Start with a simple experiment - maybe a brief survey or reaction time task. As you get comfortable, explore advanced features like timeline variables and custom code. Happy experimenting!

Ready to Get Started?

Go to My Projects →