Experiment builder reference

Every configuration card on the story settings page, explained in depth. Each section below describes what a card does, when you'd use it, every field it exposes, and the gotchas that have surprised researchers before. If you just want to scan the platform, the landing page has the short version.

Workspace & collaborators #workspace

What it does

Every story belongs to one user — the creator. The creator can grant other registered users co-owner access so a small team can run a study together without sharing a login.

When to use it

• You're co-running a study with another researcher and they need to download data or replace HTML.
• You're handing a study over to a colleague — add them as co-owner, confirm they can access it, then remove yourself with "Leave this study".

Roles & permissions

Gotchas

Assets #assets

What it does

Hosts the static files your Twine story references — images, audio, video, custom CSS, anything you'd load with a relative URL. Files are served at /play/<slug>/assets/ and the platform injects a <base> tag into your HTML so paths like img/Logo.png resolve correctly.

When to use it

• Your Twine uses any external media (images, sounds, fonts, etc.).
• You want to keep your .html small by externalising large media.

Fields

Gotchas

Tracker contract #tracker-contract

What it does

Every story you upload gets a small JavaScript block injected at the bottom of its HTML before it's served to participants. That block — the tracker — is what turns a stand-alone Twine export into a tracked experiment. It reads the participant's id from the URL, resumes their save if they're returning, records every passage they visit, every click and form change they make, and ships that back to the platform. The contract describes exactly what the tracker captures and what it sends — so you can audit, plan analysis, and design URLs against a fixed surface.

How it gets into your HTML

• Injected automatically when you upload a story (or add / replace a condition's HTML).
• Re-injection is idempotent: re-running it on already-tracked HTML is a no-op byte-for-byte.
• The Tracker version card on the story page can re-inject the latest tracker into existing HTML without re-uploading — your sessions are preserved.
• Two HTML elements are added, immediately before </body>: a <style id="tracker-hide"> that hides the page until resume completes, and a <script id="trip-hustlers-tracker"> that contains the tracker code.

URL parameters the platform reads

The platform accepts the participant id under any of the names below. Whichever you supply, the play route normalises the URL with a 302 redirect so the tracker always sees a canonical User_ID (or PROLIFIC_PID).

Endpoints the tracker calls

What the tracker uploads (the payload)

Every /upload_twine_data POST carries a JSON body with these fields. The server upserts on (story_id, user_id), so a returning participant keeps the same row.

Resume flow

• On load, the tracker fetches /resume_twine_data?user_id=... in parallel with SugarCube booting.
• It waits until SugarCube has rendered its first passage and the resume call has returned.
• If a save_blob is present, the tracker calls Save.base64.load() (or the legacy Save.deserialize()) and forces a re-render with Engine.show() — so the participant lands on the passage they left, not the start passage.
• The hider <style> is removed once resume is settled. Until then, the page is blank — so a returning participant never sees a flash of the start passage before their save loads.
• If multimodal capture is enabled with Require successful capture, resume also waits for the camera + landmarker to come up. A capture-required overlay covers the page if they don't.

Engine requirement

• SugarCube v2.37+. Uploads of Harlowe or Chapbook stories are rejected at upload time (the platform checks <tw-storydata> + the application-name="SugarCube" meta).
• jQuery is required and SugarCube ships it; nothing for you to add.
• The tracker waits for window.SugarCube.State and window.SugarCube.Save before attaching any handlers. Stories that load slowly or stall on assets still get full instrumentation once SugarCube finishes booting.

What the tracker does not do

• No keystroke contents. When behavioural keystroke timing is enabled, only an inter-keystroke category (printable, backspace, whitespace, control) is recorded. The actual key value is never sent. If you need free-text answers, use a story <input> and read it from inputs.csv.
• No camera footage. Multimodal capture sends 52 numeric blendshape scores per frame. No image, no video, no facial landmark coordinates leave the participant's browser.
• No IP, no fingerprint, no third-party calls. The tracker talks only to the platform host you've deployed.
• No mutation of the story HTML beyond the injection block. Your Twine, your assets, your CSS — all untouched.

Server-side guarantees on the upload

• One row per (story, user_id). Replays of the same passage_index don't create duplicate sessions.
• Regression guard. When a returning participant's first upload looks like a boot render (lower passage_index than what's already stored), the server keeps the prior save_blob and only touches updated_at.
• completed_at is stamped exactly once. The first upload whose click_history contains a configured ending-passage title sets it; further uploads never re-stamp or clear it. The per-arm quota counts off this field.
• focus_history is additive. Each upload's entries are appended to the server-stored array, with a received_at stamp.
• decisions and inputs snapshot on every upload — the server stores the latest version each time, with received_at preserved from the first sighting of a given index so the timestamp doesn't drift.

Behavioural + multimodal extension

When you enable behavioural or multimodal capture for a story, the same tracker installs extra collectors and starts streaming to /upload_twine_events on a separate cadence (default every 5 s, plus beacons on tab hide / unload). Events live in a separate collection from the main session, so they don't bloat the session document or the save_blob. They show up as events.jsonl / events.csv in the downloaded data. See Behavioural measurements and Multimodal capture for the per-channel details.

Gotchas

Tracker version #tracker-status

What it does

The platform injects a small JavaScript block ("the tracker") into every uploaded story. When the platform's tracker code changes — to fix a bug or add a feature — older stories keep their old injected code until you re-inject. This card shows whether your study is on the latest tracker and gives you a one-click refresh.

When to use it

• The card shows a vermillion "outdated" message.
• You've read release notes that mention a tracker change relevant to your study.

Gotchas

Replacing the HTML #replace

What it does

Swaps the story's HTML in place. The slug, the public URL, every collected participant session and assignment are preserved — only the story content is replaced.

When to use it

• You found a typo in your Twine and re-exported.
• You're polishing dialogue mid-study but don't want to disturb in-progress participants.

Gotchas

Conditions (multi-arm) #conditions

What it does

Lets one study serve multiple HTML variants — one per experimental arm. Each condition gets its own injected HTML, its own public play URL (?condition=<name>), and optionally its own completion behaviour, weight (for randomization), and quota (cap on completed participants).

When to use it

• You're running a between-subjects experiment with two or more arms.
• You want one study, one data export, but different HTMLs per arm.
• You need quota balancing across arms (e.g. exactly 50 completions each).

Converting single → multi

The first time you add a condition, the form asks for a name to give the existing HTML (e.g. control) and lets you upload the second arm. The existing HTML is reused as-is — no re-injection, no copy.

Fields

Randomization mode

Per-arm completion override

Each row in the Conditions table can expand a "Customize completion" drawer to override the study-wide completion settings (endings, action kind, debrief text, redirect URL, delay, max session, hide UI bar) for just that arm. Tick "Override study-wide completion config" to make the override active.

Gotchas

Pre-survey #pre-survey

What it does

Sends participants to an external survey before the Twine experience starts. When a participant arrives at the play URL, the platform forwards every query parameter they brought (PROLIFIC_PID, condition, User_ID, …) to the survey URL, plus an extra redirect_url that points back to the Twine with survey_done=1 appended. The survey is responsible for redirecting to redirect_url on submission — otherwise the participant never reaches the Twine.

When to use it

• You collect demographics or consent on Qualtrics / SurveyMonkey before play.
• You need a screening question (age, attention check) before the participant burns time on the story.

Fields

Qualtrics setup (most common)

1. Open the survey in the editor → Survey Flow.
2. Click Add a New Element → Embedded Data. Move the new block to the very top of the flow.
3. In that block, add fields named exactly: redirect_url, PROLIFIC_PID, User_ID, condition. Leave the values empty — Qualtrics auto-fills them from the URL when "Value will be set from Panel or URL" is the default. Save the flow.
4. Go to Survey Options → Survey Termination (or End of Survey in newer UI) → choose Redirect to a URL.
5. Paste this exactly into the URL box: ${e://Field/redirect_url}
6. Publish the survey and copy the anonymous link into the Pre-survey URL field above.

SurveyMonkey

Use the Custom Variables feature to capture redirect_url from the link, then set Survey Ending → Redirect to your own webpage with the value [redirect_url].

Google Forms

Forms doesn't support outbound redirects natively. You'd need an Apps Script add-on (a Form Submit trigger that calls HtmlService to redirect). Use Qualtrics or SurveyMonkey instead if you can.

Custom survey / web form

Read redirect_url from window.location.search on page load, store it, and on submit do window.location.assign(redirect_url).

Gotchas

Completion quota #over-quota

What it does

Caps the number of completed participants. Once the cap is hit, new participants are redirected to the over-quota URL (typically a Prolific "study full" completion code) instead of seeing the Twine. Participants who already started can always come back and finish.

When to use it

• You're paying per participant and need a hard ceiling.
• Your Prolific study has a fixed sample size and you want over-recruited participants to receive a completion code instead of starting the study.

Fields

Gotchas

Completion behaviour #completion

What it does

Defines what happens when a participant reaches one of the configured "ending" passages: stay on the page, show a debrief, or redirect to an external URL (typically the Prolific completion link).

When to use it

• You're using Prolific and need to forward participants to a completion URL.
• You want a debrief screen with the study description, links to literature, or contact info.
• You need to cap session duration (e.g. fire completion after 30 minutes regardless of progress).

Ending passages

One passage title per line. The builder offers two helpers: a "Detected endings" chip row (passages no other passage links to — likely terminal nodes) and an "All passage names" picker. Click a chip to append it to the list.

Action fields

Gotchas

Behavioural measurements #behavioral

What it does

Captures rich behavioural signals — high-precision reaction time, mouse trajectory, hover dwell on choices, window focus / idle, scroll, keystroke timing — beyond the basic passage and choice history. Off by default. When enabled, all channels turn on unless you've already picked individual ones.

When to use it

• You're running a study where reaction time matters (e.g. forced-choice paradigms).
• You want to detect distraction or off-task behaviour (idle, blur, tab switches).
• You're studying hesitation / hover patterns before choice clicks.

Channels

Parameters

Gotchas

Multimodal capture #multimodal

What it does

Streams MediaPipe Face Landmarker blendshape scores (52 expression dimensions per frame) from the participant's webcam during play. No video or image data leaves the browser — only the numerical blendshape vectors are uploaded.

When to use it

• You're running affect / emotion research and need per-frame expression signals.
• You want a low-bandwidth alternative to full video recording for facial analysis.

Fields

Gotchas

Downloaded data #export

What it does

The Download data button on the dashboard (and the per-study page) packages everything the platform has collected for that story into a single ZIP file named <slug>-<timestamp>.zip. The same archive is produced for admin exports at /admin/studies/:id/export, with the action recorded in the audit log. The export is generated on demand from the current database state — there's no nightly snapshot or cached copy, so you always get the latest.

What's inside the ZIP

Every CSV uses standard quoting (RFC 4180): fields containing commas, quotes, or newlines are wrapped in double quotes and embedded quotes are doubled. Objects (variables, decision data, payload) are serialised as JSON inside their cell. Excel reads it correctly; pandas reads it with the default read_csv — for the embedded-JSON columns, parse with json.loads on the column afterwards.

Data dictionary — sessions.json / sessions.csv

One participant per row. sessions.json includes every nested array verbatim from the database; sessions.csv replaces the nested arrays with their lengths (click_count, focus_event_count, …) for quick scanning. If you only need counts, use the CSV; for any deeper analysis go to the JSON or to the per-event CSVs below.

Data dictionary — clicks.csv

One row per element of click_history. Visit order within a session is given by click_index.

Data dictionary — focus.csv

Tab-visibility and window-focus events. The browser fires these on backgrounding the tab, switching apps, locking the screen, etc.

Data dictionary — decisions.csv

One row per click on a story link or button (the tracker delegates on #story a and #story button). Captures the choice the participant made.

Data dictionary — inputs.csv

Changes on story form fields (free-text answers, sliders, dropdowns). The tracker records every change event on #story input / textarea / select.

Data dictionary — events.jsonl / events.csv

Behavioural and multimodal events live in a separate collection — they're append-only and high-volume, so they're streamed rather than batched into the session document. Each row is one event. The events.jsonl file is line-delimited JSON, ideal for pandas.read_json(path, lines=True); events.csv is the same data with payload kept as a JSON-encoded column.

Working with the data

• Python (pandas): pd.read_csv("sessions.csv"); for embedded-JSON columns (variables, data, payload) follow up with df["data"].apply(json.loads).
• Python (notebooks, full fidelity): json.load(open("sessions.json"))["sessions"] gives you the nested list directly.
• R: readr::read_csv() for the CSVs; jsonlite::stream_in() for events.jsonl.
• Joining: user_id is the join key everywhere. The CSVs already carry condition for convenience, but it's also unambiguously available from sessions.csv.

Gotchas

Deleting a story #delete

What it does

Removes the story, its HTML (all arms if multi-condition), its assets, and every participant session and event collected against it.

When to use it

• You uploaded the wrong file and want a clean slate.
• The study is finished and you've exported your data.

Gotchas