Actions

Every predefined state-listening action exposed by the LUIDA experiment-automation editor, organized by category. Same actions are available in per-state cells and in always-on event handlers.

These pages are not yet fully reviewed. The LUIDA team is continuing to review and improve them. If you find anything wrong on these pages, or have questions that aren't resolved by reading them, please ask or report to the LUIDA team.

The 25 predefined actions you can attach to a state-listening item, grouped by category. Each links to its detailed page with parameters, side effects, examples, and cross-references.

If a behavior you want isn't here, write a Customized Action — a code block with full ClusterScript access.

Where actions fire

The same action library is reused across two contexts on every state-listening item:

Per-state lifecycle slots — On State Start, During State, On State Exit, configured cell-by-cell in the grid.
Always-on event handlers — Start, Update, $.onCollide, $.onInteract, $.onUse, $.onGrab, $.onPhysicsUpdate, $.onRide, $.onSteer, $.onSteerAdditionalAxis, $.onTextInput. Each event hosts one action list (no enter/during/exit split); attach via the + Add event ▾ dropdown on the State-listening Items grid.

The Sleep action is the one exception — it's hidden from the event-handler menus because its { type: "sleep" } form is only meaningful inside the per-state action loop.

Globals available inside actions

Every action runs in a context with three globals readable:

CONDITION — current trial's variable values.
PARTICIPANTS — array of participant handles, 1-indexed.
COLLECTED_DATA — current data scratchpad (most useful inside data calculator scripts).

Inside Start event handlers specifically, LUIDA auto-prepends a prelude that primes CONDITION and PARTICIPANTS so conditional actions work from the first frame (otherwise Start would run before $.onUpdate populates them).

State machine control

ToNextState() — Triggers a transition to the next experiment state.

Item visibility

ShowItem() — Makes the item visible.
HideItem() — Makes the item invisible.

Child visibility

ShowChild(childName) — Makes a specified child object visible.
HideChild(childName) — Makes a specified child object invisible.

Item manipulation

SetText(text) — Sets text on a child Text sub-node.
SetPosition(x, y, z) — Sets the item's world position. Requires MovableItem.
AddPosition(x, y, z) — Offsets the item's world position. Requires MovableItem.
SetRotation(x, y, z) — Sets world rotation (Euler degrees). Requires MovableItem.
AddRotation(x, y, z) — Adds to world rotation (Euler degrees). Requires MovableItem.
SyncWithParticipantBone(participantIndex, bone, posOffset, rotOffset) — Sync this item's transform to a participant's humanoid bone, with offsets. Typically used in During State for per-frame sync.

Child manipulation

SetChildPosition(childName, x, y, z) — Sets local position of a child object.
AddChildPosition(childName, x, y, z) — Offsets local position of a child.
SetChildRotation(childName, x, y, z) — Sets local rotation of a child.
AddChildRotation(childName, x, y, z) — Adds to local rotation of a child.

Data logging

The editor labels these as Push data to collector, Save pushed data in collector, and Upload saved data from collector — the runtime function names below are kept for backward compat. The same three signals (luida_collect_<label>, exp_recordCustomData, exp_uploadCustomData) are also exposed as the three phase toggles on the LuidaDataCollectionGimmick CCK component if you want to fire them from a CCK trigger instead of from an action list. See Configure data collector for the visual builder that defines what each "Save" snapshot looks like.

SendDataToCollector(label, value) — "Push data to collector". Writes a key-value pair to the in-memory collected-data scratchpad.
ProcessAndSaveCollectedData() — "Save pushed data in collector". Snapshots scratchpad to a queued record via your data calculator.
UploadCollectedData() — "Upload saved data from collector". Batches and flushes the queued records to the Web Console.

User feedback & utilities

SendHaptics(participantId, target, frequency, amplitude, duration) — Triggers haptic feedback on the participant's controller.
SendViaOsc(participantId, address, values) — Sends an OSC message from the participant's local client (used for hardware integration).
Sleep(seconds) — Pauses the current action chain for the given duration.

Avatar management

AssignAvatarToParticipant(avatarID, participantIndex) — Spawns and assigns an avatar wrapper to a participant.
UnassignAvatarFromParticipant(participantIndex) — Removes any avatar wrappers, restoring the participant's default avatar.

Conditional execution

Any action can be wrapped in a condition that gates it on a CONDITION variable's value. The editor's "if" toggle on each listener row turns:

ShowItem();

into:

if (CONDITION["difficulty"] === "hard") {
  ShowItem();
}

Useful for showing/hiding stimuli per condition without writing a Customized Action. Available on every action row — both in per-state cells and inside always-on event handlers.