Which approach should I use?

LUIDA has multiple ways to do the same thing in many places. This page lists the common decisions and suggests a default for each. If you're not sure why your design isn't working, it's worth checking this page — sometimes the issue is a mismatched approach.

State-listening item vs CCK Trigger + Gimmick

Use a state-listening item when:

• The behavior is keyed off the experiment's state machine — i.e., it should happen "when state X starts" or "during state Y."
• You want LUIDA to manage the script generation and per-state logic for you.
• The action you want is one of the 25 predefined actions or a Customized Action you can write inline.

Use a plain CCK Trigger + Gimmick when:

• The behavior is not state-dependent — e.g., a button that always does the same thing regardless of what state the experiment is in.
• The behavior is purely physical (door opens when touched, ball flies when grabbed).
• You're integrating with stock CCK content that already uses Trigger/Gimmick patterns.

Default: state-listening item if it touches the experiment flow at all; plain CCK if it's just world-physics or always-on UI.

Auto-transition (exit timer) vs explicit state_triggerTransition

Use auto-transition (Has Exit Time = 1.5s) when:

• The state has a fixed duration regardless of participant input. Stimulus presentation, fixation cross, ITI.
• You don't care about precise reaction time — auto-transitions are accurate to the frame, but if you need millisecond-precise timing, log timestamps yourself in On State Exit and don't rely on the timer.

Use state_triggerTransition (i.e., a LuidaToNextStateGimmick fired by a button) when:

• The state ends on a participant action — pressing a button, picking up an object, looking at a target for X seconds.
• Different participants will spend different amounts of time in this state.
• You want to record reaction time as transitionTime - enterTime.

Both: you can set "Has Exit Time" and allow state_triggerTransition. The first one to fire wins. Common: "respond within 5 seconds, otherwise auto-advance with no response logged."

Default: explicit transition for response states, auto-transition for stimulus states.

Customized Action vs separate state-listening item

A Customized Action lets you write inline ClusterScript inside a state-listening item's grid cell. Useful for one-off logic that doesn't fit the predefined action list.

Use a Customized Action when:

• The logic is short — a few lines.
• It only makes sense in the context of one specific state for one specific item.
• It uses local context like the item's transform, which would be awkward to access from another item.

Use a separate state-listening item when:

• The logic is more than ~20 lines and starts wanting its own functions.
• The same logic is reused across multiple states.
• The logic is stateful — keeps internal counters between calls.

Default: Customized Action first; refactor to a separate item only when reuse appears.

Within-subjects vs between-subjects variable

See the dedicated page: Within vs between subjects. The short version:

• Within when every participant can plausibly experience all values, you want more statistical power per participant, and order effects are manageable.
• Between when conditions involve persistent state (giving someone information you can't take back), demand characteristics are a risk, or the manipulation is identity-laden.

If you can't decide and the constraints aren't binding, default to within — fewer participants needed.

CSEmulator vs Cluster test space for testing

Use CSEmulator (Unity Play mode) when:

• You're iterating on logic — variable definitions, state-machine wiring, action chains.
• You don't need to test multi-participant behavior. CSEmulator simulates one participant only.
• Network latency isn't relevant to what you're testing.

Use a Cluster test space when:

• You're testing multi-participant flow.
• You're testing avatar assignment / VRM rendering / haptics — things CSEmulator doesn't fully simulate.
• You're confirming the experiment runs correctly end-to-end before publishing.
• You want to check session-eligibility and condition-balancing behavior, which only the real Web Console can do.

Default: CSEmulator for fast iteration; Cluster test space for final verification per build.

Single Process+Save+Upload vs Process+Save per trial, Upload at end

When uploading custom data, you have a choice of when to call UploadCollectedData():

Per trial:

Trial - Rest On State Start: ProcessAndSaveCollectedData() (on Response Exit)
                              UploadCollectedData()

At end:

Each trial:  ProcessAndSaveCollectedData() (only)
End:         UploadCollectedData()

Per-trial pros: if a participant disconnects mid-experiment, you still have all completed trials' data.

Per-trial cons: N network round-trips. If your experiment has 200 trials, that's 200 uploads.

At-end pros: one upload, fewer race conditions, simpler timing.

At-end cons: if anything crashes — the participant's network drops, Cluster has a momentary outage, the participant force-quits — all uploaded data for that session is lost.

Default: per-trial for studies with rare, high-value participants (clinical samples, expert users). At-end for high-throughput crowdsourced studies where you can absorb session-level data loss.

A reasonable compromise: process and save every trial; upload every 5–10 trials. That's ProcessAndSaveCollectedData() on every Trial - Rest, but UploadCollectedData() only when exp_trialID % 10 === 0. This is a Customized Action.

Building one big scene vs multiple scenes

Unity convention is multiple scenes per project. LUIDA's convention is one experiment per scene — but a scene can be quite complex.

Default: one scene per experiment. Use Unity's prefab system to factor out reusable parts, but keep the actual experiment in one scene file.

LUIDA's "Create new scene" and "Duplicate current scene" menu items copy the per-scene state list and variable assets too — so duplicating a scene gives you a fresh experiment with the same structure as the original. That's faster than building a second experiment from scratch, and it's how Tutorial 1's Priming_complete and Priming_incomplete are organized.

When in doubt

Many LUIDA design questions become clearer once you ask:

Does this thing depend on the experiment's state? On the participant's condition?

If yes to either, it goes through LUIDA's state-listening / variable system. If no to both, it can be plain CCK without involving LUIDA at all.

Where to go next

• State machine & trial lifecycle — refresh on what states do.
• Reference → Actions — see what predefined actions exist before writing a Customized Action.
• Tutorials — each tutorial walks through these decisions in context.