Content Creation Reference Tables

Last Updated: 2026-10-09 | For: Teachers & Content Creators | Level: Intermediate to Advanced

This page is the field-level lookup companion to Quick Start: Content Creation.

Table of Contents

1. Overview
2. TDF File Structure
   • Setspec (Lesson Settings)
   • Units
   • Delivery Settings
3. Related Guides

Overview

This page is a reference-only guide for field names and behavior. For first-lesson walkthroughs and minimal starter examples, use Quick Start: Content Creation.

To set up content for students, yourself, or someone else, you must create 2 files:

1. Tutor Definition File (TDF) - Controls lesson behavior and structure
2. Stimulus File - Contains the actual questions and answers

Type/serialization note: many deployments store config values as JSON strings (for example "true" and "30000"). Follow existing package conventions in your environment.

Tutor Definition File (TDF)

The current TDF authoring structure is rooted at tutor. The required lesson metadata lives in tutor.setspec; lesson and unit delivery behavior lives in deliverySettings.

setspec

All TDFs contain a setspec object that applies to all units.

Canonical setspec fields

These names align with mofacts/client/lib/tooltipContent.ts and Audio & Speech Settings.

Condition load balancing

Use loadbalancing on a root TDF that lists experiment conditions. It applies only when MoFaCTS assigns a condition to a participant who does not already have one; a returning participant keeps their previously assigned condition.

MoFaCTS tracks one count per condition in the root TDF. That counter increments at the countcompletion milestone: "beginning" increments after assignment, "end" increments when the lesson finishes, and a number increments when the participant reaches that unit. Counts therefore do not necessarily mean completed participants.

• "min" selects randomly among the condition or conditions with the lowest count. This is the usual choice when you want the most direct balancing. For counts [3, 4, 4], it always assigns the next participant to the condition with count 3.
• "max" selects randomly among every condition whose count is below the current highest count. It deliberately excludes the condition or conditions tied for the highest count; it does not select the most-filled condition. For counts [3, 4, 5], it selects randomly between the conditions with counts 3 and 4, never the one with 5.

When every condition has the same count, both modes select randomly from all conditions. "max" can make several lower-count conditions eligible at once, while "min" limits selection to the least-filled condition or tied least-filled conditions.

"not-max" adds a server-owned block allocator with the same eligibility rule as "max": conditions below the highest count, or all conditions on an all-equal tie. One shuffled block contains each eligible condition once. The server consumes that block in order, replenishes it after exhaustion, and rebuilds it if the observed maximum count or eligible IDs change. Reordering condition filenames alone does not reset a block; canonical child IDs own its identity.

Block position and participant assignment are saved together in a Mongo transaction. Concurrent launches cannot consume the same slot, and a retry/return uses the participant's saved assignment. For countcompletion: "beginning", the count increment is part of that same transaction. Later count milestones retain their existing timing, so these remain milestone counts, not an additional set of assignment counts. Explicit owner-selected previews do not consume block slots or beginning counts. Replacing/resetting counts clears the block but does not change saved assignments.

Returning participants keep their saved condition assignment. The server-owned block is not authored TDF content. Replacing/resetting counts clears the block without changing existing assignments. Existing min, max, and omitted settings retain their behavior.

Audio/Speech fields in setspec

Use canonical spellings exactly:

• speechIgnoreOutOfGrammarResponses (not speechIgnoreOutOf GrammarResponses)
• audioPromptMode

Units may override audioInputEnabled and audioPromptMode as top-level unit fields. An omitted unit field inherits the corresponding setspec value; see Audio & Speech Settings.

Media and asset resolution constraints

Reference TDF snippet

This mirrors current package usage (for example Countries of the World, AllConditions_Fixed) without embedding real keys.

{
  "tutor": {
    "setspec": {
      "name": "countries_top200",
      "lessonname": "Countries of the World",
      "stimulusfile": "Countries_of_the_World_top200_2025.json",
      "userselect": "true",
      "lfparameter": "0.85",
      "shuffleclusters": "0-199",
      "experimentTarget": "flashcardtest",
      "audioInputEnabled": "true",
      "audioPromptMode": "feedback",
      "speechIgnoreOutOfGrammarResponses": "true"
    },
    "deliverySettings": {
      "experimentLoginText": "Participant ID"
    },
    "unit": []
  }
}

Prolific participation

Use the Prolific study ID as setspec.experimentTarget and set root setspec.prolificCompletionUrl to https://app.prolific.com/submissions/complete?cc=ABC123 with the study's completion code. The completion code must be nonempty and alphanumeric. No credentials, custom ports, fragments, other hosts, or extra query parameters are accepted; there is no default.

https://your-mofacts-host/experiment/<STUDY_ID>?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}}

Replace <STUDY_ID> with the actual study ID and keep all three placeholders unchanged. The researcher connects their own Prolific account and links the existing study to their own experiment in the Prolific panel. A Prolific launch requires all three identity parameters exactly once, a matching study, valid completion configuration, and a passwordless experiment. Invalid launches show an error; they do not switch to manual login. The same identity triple resumes the existing account, condition, and saved progress. Different studies use separate participation accounts.

Ordinary launches without these parameters retain manual IDs, password-protected entry, authored prompts, and ordinary completion navigation, even when the lesson has Prolific configuration.

The first saved session completes the initial paid Prolific submission: completed work followed by a positive lockout before the next unit, or the end of the assigned experiment. Initial pre-work lockouts do not count. Saved adaptive units and selected conditions determine completion. Later visits use private return links, with bonuses entered explicitly by the researcher. Lockout expiry queues Prolific messages; Prolific owns email notification delivery. See Admin Reference for management and payment safeguards.

Link parameters establish local participation identity but do not verify Prolific eligibility or submission ownership. MoFaCTS saves local completion before requesting the redirect; Prolific owns completion-code actions, approval, and payment. See Prolific's study contract.

unit

A TDF is a sequence of "units" following the setspec. Units have the following fields

Session selectors include learningsession, assessmentsession, videosession, autotutorsession, sparcsession, and gazecalibrationsession. A unit with instruction fields such as unitinstructions or picture and no session object is an instruction-only unit. H5P display configuration is unsupported and is rejected by authoring and package upload.

deliverySettings

deliverySettings is the unified settings object for learner-runtime behavior. It replaces the old split between delivery parameters and UI settings.

Supported scopes:

Keep setspec for lesson metadata, audio API keys, language/voice settings, and non-delivery lesson setup. Use deliverySettings for timing, feedback, answer controls, and learner-facing presentation controls.

Language metadata in setspec describes authored content: contentLanguage is its BCP 47 language tag, recommendedUiLocales lists suggested platform locales, and translationStatus is author-declared (author-provided, not-translated, draft, or reviewed). These fields do not request translation or change scoring rules. Keep response-language and TTS settings explicit in audio-enabled lessons; see Audio and Speech Settings.

Delivery Settings Table

Timing, Scheduling, and Answer Controls

Runtime Timer Contract

The following describes the current source contract. Delivery timers are measured as the learner-visible presentation envelope, not just the static fully visible period.

• drill, purestudy, reviewstudy, and correctprompt begin when the trial content starts its fade-in.
• Fade-in and fade-out time are included in the configured duration.
• Pre-recorded question audio and timeuntilaudio count against the configured response window; authors should choose drill values that leave enough response time when media is present.
• Generated TTS may extend an expired response/study/feedback timer only until active playback completes. It does not restart a fresh full-duration timer.
• Typed input activity, voice start, and speech-recognition retry/error activity reset the response timeout for drill/test-style response windows.

Older deployed builds differ: the inspected cardMachine build starts its full response countdown after the question-audio gate finishes, while exported latencies begin at trial reveal. Four seconds of audio plus a ten-second countdown can consequently produce 14-15-second no-input timeout latencies. See Timer Behavior Depends on the Collection Build for the identified build and limitations; do not apply the current contract retroactively to those records.

Configured durations, absolute timestamps, and exported elapsed latencies are distinct quantities. Time is generally response onset, Problem Start Time is reveal, and CF (End Latency) excludes feedback. See Interpreting Trial Timing before using these fields to calculate typing time or between-trial gaps.

Prompt Display and Feedback Presentation

Audio-Related Delivery Settings

Operational validation before assignment

1. Verify lesson appears under intended class-selection context.
2. Verify one launch using a real student account.
3. Verify at least one new export row appears after launch/response.
4. For condition-root content, verify expected condition labels in exported data.

Deprecated Fields and Migration

See Also

• Quick Start: Content Creation
• Stimulus Files
• Trial Types Reference
• AutoTutor Sessions