VisuomotorJoystickTask

Synopsis

USBHIDJoystickTask is a BCI2000 application module that implements a center-out visuomotor reaching task controlled with a USB HID joystick. The task is designed to compare movements made under a normal joystick-to-cursor mapping with movements made under an inverted mapping.

During each experimental trial, the participant moves a cursor to the center of the display, holds it there, waits through a warning period, and then moves to a peripheral target. In the automatic condition (labeled Normal to the participant), joystick and cursor movements are congruent. In the controlled condition (labeled Reversed to the participant), joystick-to-cursor movement is inverted after the target appears. The numerical TaskCondition encodings remain 0 and 1, respectively.

The task also includes an optional participant introduction and practice sequence, available in two forms. The default Easy introduction uses animated demonstrations, guided "your turn" screens, and short practice blocks to introduce the normal and reversed mappings. The Standard introduction is the earlier, text-driven sequence that combines instructions, free-movement exploration, and practice trials. The introduction may also be disabled entirely. Tutorial and practice periods are recorded in the BCI2000 data stream but remain separate from experimental trial numbering and experimental performance summaries.

The task is based on the visuomotor paradigm described by Neumann et al. (2018), which was developed to compare automatic and controlled movements and investigate their relationship to basal ganglia function and subthalamic deep brain stimulation in Parkinson's disease. The BCI2000 implementation adapts the original paradigm for USB joystick control and synchronized BCI2000 state recording.

Video Overview

The following video demonstrates the Visuomotor Joystick Task running in BCI2000, including the participant display and joystick-controlled task behavior:

This video displays version 1 of the task, and as such does not include the pre-experiment participant tutorial and practice sequence. It also predates the Easy introduction, the configurable target distance, and the runtime geometry controls described below.

Location

In the inspected development checkout, the USB HID Visuomotor Joystick Task is located at:

src/custom/usb_hid_joystick_task/

The main application implementation is contained in:

USBHIDJoystickTask.cpp

with the corresponding header and build configuration in:

USBHIDJoystickTask.h
CMakeLists.txt

The CMake target is usb_hid_joystick_task_custom (configured with NOBUNDLE), and the target explicitly requires C++17. This checkout is tracked in Git; the former src/private/Application/VisuomotorJoystickTask SVN location does not describe the inspected source tree.

The paths and target above describe the checkout inspected for this documentation update; another deployed BCI2000 tree may arrange custom modules differently.

Versioning

Author

Alexander Speer

Friedman Lab, Department of Neurosurgery

Washington University in St. Louis

Developed in the Friedman Lab.

Contact: speer@wustl.edu

Version History

The task was developed as a USB HID joystick implementation of the automatic/controlled visuomotor reaching paradigm described by Neumann et al. (2018).

The current implementation includes:

Automatic and controlled visuomotor conditions.
Ordered and pseudorandom experimental blocks.
Configurable trial counts and trial timing.
An optional participant introduction and practice sequence, with Standard and Easy tutorial modes.
Automatic and controlled practice trials.
Free-movement demonstrations of normal and reversed cursor control (Standard mode).
Animated cursor, target, and joystick demonstrations with guided "your turn" screens (Easy mode).
Joystick-button and experimenter-controlled tutorial progression.
Automatic, timer-based Easy-introduction progression, including an optional surgery-friendly mode.
USB joystick input through BCI2000's input logging system.
Selection of the participant display on multi-monitor Windows systems.
BCI2000 state logging of task timing, cursor position, target position, condition, block structure, tutorial status, practice trials, trial events, and runtime display geometry.
A separate diagnostic window with visible performance metrics, tutorial controls, manual trial reset, researcher skip controls, Easy-phase previous/restart controls, runtime cursor-diameter and target-distance controls, and pause/resume.
Trial-level reaction time, movement time, and total time measurements.
Configurable cursor diameter, target diameter, and center-to-target distance, with target size affecting acquisition tolerance.
Dedicated one-processing-block states for researcher skip, Easy-phase navigation, and geometry-change events, plus a persistent pause state.
Participant-facing Normal/Reversed terminology and condition cues, without changing automatic/controlled state encodings.
Separation of tutorial/practice data from experimental trial numbering and run-summary metrics.
Behavioral recording through synchronized BCI2000 states; this version does not create a separate results CSV.

The inspected development checkout contains the task under src/custom/usb_hid_joystick_task and has Git history through 2026-11-11 (commits a169ed7 and 7d6d0ea, plus uncommitted working-tree changes that add the EasyIntroPrevious and EasyIntroRestarted states and keep the center and warning cues at fixed size).

Source Code Revisions

Initial development: 8/26/26
Tested under (earlier revision): BCI2000 framework 3.6.9528.4, Release x64, MSVC 19.35
Known to compile under: Visual Studio 2022 / MSVC 19.35 for a prior version of the current source
Earlier documented source revision: 9/1/26
Earlier version, 10/12/26: Task commit 83404dd (the previously documented revision). Added researcher pause/resume and skip controls with corresponding states, configurable cursor/target diameters, participant-facing Normal/Reversed labels and condition cues, and updated diagnostic metrics display; removed secondary CSV output and ResultsFile. Source moved to the inspected custom-module location and CMake target described above.
New version, 11/11/26: Latest inspected task revision (Git commits a169ed7 and 7d6d0ea, plus uncommitted working-tree changes). Added the Easy introduction tutorial mode and made it the default; replaced the boolean EnableIntroduction parameter with the enumerated IntroductionMode parameter; added TargetDistancePixels; added runtime cursor-diameter and target-distance controls to the diagnostic window together with CursorDiameterPx10, TargetDistancePx10, and DisplayGeometryChanged; added researcher PREVIOUS EASY PHASE and RESTART EASY PHASE controls with EasyIntroPrevious and EasyIntroRestarted events; added the EasyIntroPhase state and the Application:EasyIntroduction parameter group. The center and warning markers no longer scale with the cursor diameter.
Observed in the inspected parameter files: the current application build was produced with BCI2000 framework 3.6.9567.1 (release, AMD64, MSVC 19.35) on 2026-11-10. This is build metadata from a saved parameter file, not a verified runtime test of every 11/11/26 change.
Current inspected source revision: 11/11/26 (Git commits a169ed7 and 7d6d0ea, plus uncommitted working-tree changes)
Broken since: No known breaking revision

The earlier framework and compiler information above does not establish a successful build or runtime test of the 11/11/26 source revision; the present update is based on source comparison. The 11/11/26 change record is summarized here and in the Version History section.

Functional Description

Scientific Basis

This task is a BCI2000 adaptation of the visuomotor task described by Neumann et al. (2018).

In the original experiment, participants controlled a cursor using a pen and digitizing tablet. Targets appeared around a central fixation point. In the automatic condition, movement of the pen and cursor was congruent. In the controlled condition, the pen-to-cursor mapping was inverted. Automatic targets were shown in green and controlled targets in red.

Trials in the original experiment began at a central fixation cross. Participants remained at the center for 3 seconds, after which a yellow warning cue appeared for 500 ms. The target appeared 500 ms after the warning cue. The original experiment used eight possible target positions arranged around the center and included both ordered condition blocks and a pseudorandom block.

The present BCI2000 implementation preserves the central features of this paradigm, including the automatic and inverted controlled mappings, green and red targets, 3-second default experimental center hold, 500-ms warning period, 500-ms pre-target delay, and ordered and mixed experimental structures. The current participant-facing descriptions call these mappings Normal and Reversed, respectively; the legacy condition identifiers are retained in code and parameters.

There are several implementation differences. The BCI2000 version uses a USB HID joystick (Any joystick should work, provided that Windows recognizes it as a game controller.) rather than a digitizing tablet, allows the timing and number of trials to be configured, and generates experimental targets over a continuous range of angles rather than restricting targets to eight positions. It also provides an optional tutorial and practice sequence and records task variables directly as synchronized BCI2000 states.

See References for the original study.

Experiment Structure

Four experiment modes are available:

Value	Mode	Description
1	Automatic Only	Runs one block containing only automatic trials.
2	Controlled Only	Runs one block containing only controlled trials.
3	Ordered	Runs one automatic block and one controlled block. `OrderedStartCondition` determines which condition occurs first.
4	Ordered + Pseudorandom	Runs an ordered automatic block, an ordered controlled block, and then a mixed pseudorandom block containing both conditions.

In the mixed block, the application shuffles the configured numbers of automatic and controlled trials. The randomization attempts to avoid both strict alternation and excessively long runs of a single condition.

When the introduction is enabled, its content depends on IntroductionMode.

In Standard mode (IntroductionMode=1), tutorial content depends on ExperimentMode:

Experiment mode	Tutorial content
Automatic Only	General introduction, normal free movement, automatic instructions, automatic practice, completion
Controlled Only	General introduction, normal free movement, controlled instructions, controlled free movement, controlled practice, completion
Ordered	Automatic tutorial and practice followed by controlled tutorial and practice
Ordered + Pseudorandom	Automatic tutorial and practice followed by controlled tutorial and practice

When both conditions are present, the Standard tutorial always presents automatic training before controlled training. OrderedStartCondition affects the experimental block order but does not change the tutorial order.

In Easy mode (IntroductionMode=2, the default), every experiment mode uses the same guided sequence: basic demonstration, normal demonstration, normal "your turn", normal practice when configured, reversed transition, reversed demonstration, reversed "your turn", reversed practice when configured, and a ready screen. The Easy tutorial always presents the normal mapping before the reversed mapping and, unlike the Standard tutorial, always includes a reversed section even in Automatic Only and Controlled Only modes.

In both tutorial modes, the participant sees Normal/Reversed wording, while the experiment parameters and state names continue to use Automatic/Controlled identifiers.

Tutorial and Practice Sequence

When IntroductionMode is 1 (Standard) or 2 (Easy), the tutorial begins at the start of each run before the first experimental block. When it is 0 (Disabled), the tutorial is skipped and the task begins with the experimental block-announcement sequence.

Standard introduction. The Standard introduction (IntroductionMode=1) consists of the following stages:

TutorialPhase	Stage	Description
0	None	Tutorial inactive; normal experiment operation
1	Introduction	General explanation of the task and upcoming conditions
2	Normal free movement	Participant explores normal direct joystick-to-cursor movement
3	Normal instructions	Explanation of the automatic (Normal) condition and green targets
4	Normal practice	Automatic practice trials using the normal mapping
5	Reversed instructions	Explanation of the controlled (Reversed) condition and red targets
6	Reversed free movement	Participant explores continuous reversed joystick-to-cursor control
7	Reversed practice	Controlled practice trials using the inverted mapping
8	Complete	Practice-complete summary before the experiment begins

Easy introduction. The Easy introduction (IntroductionMode=2, the default) uses a guided sequence of animated demonstrations, static "your turn" and transition screens, and short practice blocks. Its stages are recorded in the EasyIntroPhase state:

EasyIntroPhase	Stage	Description
0	None	Easy introduction inactive
1	Basic demonstration	Animated cursor moves from the center to a target without a joystick illustration
2	Normal demonstration	Animated cursor and joystick move together toward green targets
3	Normal: now your turn	Static screen inviting the participant to try the normal mapping
4	Normal practice	Normal-mapping practice trials using deterministic targets
5	Reversed introduction	Static screen explaining that the cursor will move opposite the joystick
6	Reversed demonstration	Animated cursor moves opposite the joystick toward red targets
7	Reversed: now your turn	Static screen inviting the participant to try the reversed mapping
8	Reversed practice	Reversed-mapping practice trials using deterministic targets
9	Ready	Final summary screen before the experiment begins

The Easy sequence always runs in this order: basic demonstration, normal demonstration, normal "your turn", normal practice (when EasyIntroNormalPracticeTrials > 0), reversed introduction, reversed demonstration, reversed "your turn", reversed practice (when EasyIntroReversedPracticeTrials > 0), and ready. It is independent of ExperimentMode, so the reversed stages are presented even when only automatic experimental trials are configured.

Easy-stage behavior:

Demonstration animations use EasyIntroAnimationDurationMs for each movement and EasyIntroAnimationPauseMs for the pause at the target. EasyIntroAnimationLoop repeats the demonstration until the stage advances, and EasyIntroAnimationEnabled=0 replaces the animated movement with a near-static cursor position.
EasyIntroNormalDemoDirections and EasyIntroReversedDemoDirections set how many example movements are shown (1-4; default 2). The first example moves to the lower right and the second directly right; additional examples fan upward.
EasyIntroRequireButtonPress=0 (the default) advances eligible stages automatically: animations after all configured examples have played, the "your turn" and reversed-introduction screens after EasyIntroInterimScreenDurationMs, and the ready screen after EasyIntroReadyScreenDurationMs. Joystick button 1 (unless surgery mode is enabled) or researcher CONTINUE can advance a static screen before its automatic timer expires. Demonstration screens do not become eligible for manual continuation until all configured examples have played.
When EasyIntroRequireButtonPress=1 and EasyIntroSurgeryMode=0, eligible stages wait for joystick button 1 or the researcher CONTINUE control. Static screens are immediately eligible; demonstration screens become eligible after all configured examples have played.
When EasyIntroSurgeryMode=1, the non-practice Easy screens advance automatically and participant joystick-button continuation is disabled. Researcher CONTINUE remains available on eligible screens. Practice trials still require the participant to acquire the targets and return to center.
When EasyIntroRequireJoystickNeutral=1, an automatic advance or participant joystick-button continuation from the normal or reversed demonstration waits until the joystick is neutral. When instruction text is enabled, the display then shows "Let go of the joystick to continue." Researcher CONTINUE bypasses this neutral-joystick gate.
Easy practice uses EasyIntroNormalPracticeTrials and EasyIntroReversedPracticeTrials rather than the Standard practice-trial counts, and uses EasyIntroPracticeCenterHoldMs for its center hold. Success feedback lasts EasyIntroFeedbackDurationMs, or is omitted when EasyIntroPracticeFeedback=0.
EasyIntroShowInstructionText and EasyIntroShowJoystickIllustration hide the instruction text and the animated joystick graphic, respectively.
EasyIntroAllowResearcherSkip=0 disables the researcher skip controls for the Easy introduction (SKIP INTRODUCTION, SKIP PRACTICE, and SKIP CURRENT EASY PHASE). The previous-phase and restart-phase controls remain available.

After the final Easy practice trial, the participant must return the cursor to the center before the sequence advances.

Tutorial Continuation

Tutorial screens that require participant acknowledgement may be advanced using either:

Joystick button 1, or
The experimenter's CONTINUE button in the diagnostic window.

Joystick continuation uses rising-edge detection. Pressing the button advances one eligible tutorial screen, while holding the button does not repeatedly advance the tutorial. The button must be released and pressed again to produce another continuation event.

In the Standard introduction, this applies to the introduction, normal free-movement, instruction, controlled free-movement, and completion screens. In the Easy introduction, researcher CONTINUE can advance any eligible non-practice stage. Joystick button 1 can do the same only when EasyIntroSurgeryMode=0. When EasyIntroRequireButtonPress=1 and surgery mode is off, a participant joystick press or researcher CONTINUE is required; otherwise, stages also advance automatically after their animation or timer. Static Easy screens are immediately eligible, and demonstration screens become eligible after all configured examples have played. During the normal and reversed demonstrations, EasyIntroRequireJoystickNeutral=1 delays automatic or participant-button advancement until the joystick is neutral; researcher CONTINUE bypasses that requirement.

Button presses are ignored during active practice trials and during tutorial transitions that require the participant to return the joystick or cursor to center.

During the experimental portion of the run, joystick button presses do not control trial progression. The researcher CONTINUE control displays CONTINUE UNAVAILABLE when continuation is not permitted. The researcher can also use context-specific skip, previous-phase, and restart-phase controls; these actions are documented under Researcher Skip Controls. The task can be paused during tutorial stages.

Normal Free Movement

During the Standard introduction's normal free-movement stage, the participant may freely move the cursor using the direct absolute joystick mapping.

There is no timer or trial progression during this stage. It continues until the participant presses the joystick button or the experimenter selects CONTINUE.

The Easy introduction does not include a free-movement sandbox. Its normal demonstration, normal "your turn", and normal practice stages serve the same introductory purpose.

Automatic Practice

Automatic practice uses the same direct mapping and the same basic trial phases as experimental automatic trials:

Waiting for center
Holding center
Warning
Pre-target delay
Target visible
Feedback

Practice trials differ from experimental trials in several ways:

Center hold is determined by PracticeCenterHoldTime rather than CenterHoldSeconds in the Standard introduction, and by EasyIntroPracticeCenterHoldMs in the Easy introduction.
Practice targets follow a deterministic sequence.
TaskBlock and TaskTrial remain 0.
PracticeTrial identifies the active practice trial.
Practice activity is recorded in BCI2000 states; this application writes no separate trial-level CSV file.
Practice results are excluded from experimental completion counts and timing summaries.
Practice reset attempts do not increment experimental reset metrics.

In the Easy introduction, normal practice is part of EasyIntroPhase 4, uses EasyIntroNormalPracticeTrials for its trial count, and uses EasyIntroFeedbackDurationMs for success feedback (or no feedback when EasyIntroPracticeFeedback=0). The same trial phases apply.

After the final automatic practice trial, the participant must return the cursor to the center before the tutorial advances.

Controlled Free Movement

The controlled free-movement stage belongs to the Standard introduction. It allows the participant to explore reversed cursor control without a target.

The participant is first asked to return the cursor to center. Once centered, the application records the current joystick and cursor positions as anchors and enables the same relative inverted mapping used during target-directed controlled movement.

When the participant requests continuation, the task requires the joystick to return to the anchored position before advancing. This prevents an abrupt cursor jump when the mapping changes.

The Easy introduction has no controlled free-movement sandbox; its reversed demonstration and reversed "your turn" stages replace it.

Controlled Practice

Controlled practice uses the same basic controlled-trial behavior as the experiment:

Direct absolute mapping is used during centering.
Joystick and cursor anchors are recorded when the target appears.
Target-directed cursor movement uses the relative inverted mapping.
The participant returns the joystick toward its anchor after target acquisition.

Standard controlled practice uses PracticeCenterHoldTime and deterministic practice targets and remains separate from experimental numbering and performance summaries. Its states are recorded in the BCI2000 data stream; no secondary CSV is written.

In the Easy introduction, reversed practice is part of EasyIntroPhase 8, uses EasyIntroReversedPracticeTrials for its trial count, and uses EasyIntroPracticeCenterHoldMs plus EasyIntroFeedbackDurationMs (when EasyIntroPracticeFeedback=1).

After the final controlled practice trial, the participant must complete the return-to-center and return-to-anchor transition before the completion screen appears.

Tutorial Completion

The Standard completion screen summarizes the condition mappings:

Normal (automatic): cursor movement follows joystick movement.
Reversed (controlled): cursor movement is opposite joystick movement.
Green targets identify automatic trials.
Red targets identify controlled trials.

In the Easy introduction, the corresponding screen is EasyIntroPhase 9 (Ready). It states that green targets mean "move toward the target" and red targets mean "move in the opposite direction". Depending on the Easy-introduction parameters, it waits for participant joystick-button or researcher CONTINUE input, or advances automatically after EasyIntroReadyScreenDurationMs.

In both modes, the tutorial then ends, Introduction returns to 0, the originally generated first experimental target is restored, and the experiment begins with the normal 1.5-second block announcement.

Experimental Trial Sequence

Each experimental block begins with a 1.5-second announcement indicating whether the upcoming block is Normal, Reversed, or Mixed. These visible labels correspond to the existing automatic, controlled, and mixed block types; their numerical encodings are unchanged.

A trial then proceeds as follows:

The participant moves the cursor into the center region.
Once centered, the participant must remain there for CenterHoldSeconds.
A yellow warning marker appears for WarningSeconds.
A pre-target interval lasting PreTargetDelaySeconds follows.
The target appears at TargetDistancePixels from the center.
The participant moves the cursor into the target.
Target acquisition records the trial timing measurements and begins the feedback interval.
After FeedbackSeconds, the task advances to the next trial or block.

If the participant leaves the center during the center-hold, warning, or pre-target interval, the task returns to the waiting-for-center phase and the preparation sequence begins again.

A new target is generated when advancing to a new experimental trial. Manually resetting a trial does not generate a new target. Skipping an experimental trial instead advances to the next trial and generates a new target (unless the experiment has finished). A skip-block action advances past the remaining trials in the block.

Automatic Condition (Normal)

During an automatic trial, cursor position follows the joystick using a direct mapping. Moving the joystick in one direction moves the cursor in the corresponding direction.

Automatic targets are displayed in green.

Controlled Condition (Reversed)

During a controlled trial, the normal direct mapping is initially used while the participant returns to and holds the center.

When the target appears, the current joystick position and cursor position are recorded as anchors. Cursor movement then becomes relative to those anchors and inverted. Moving the joystick away from its target-onset position causes the cursor to move in the opposite direction.

Conceptually:

cursor position = anchor cursor position - joystick displacement

The cursor is constrained to the participant display.

After completion of a controlled trial, the inverted mapping remains active until the joystick has returned close to the joystick position recorded at target onset. This prevents an abrupt cursor jump when returning from the controlled mapping to the normal mapping.

Controlled targets are displayed in red.

Joystick Input

Joystick input is provided through BCI2000's input logging system.

Joystick position states are expected to range from 0 through 32767. The application converts these values into internal task coordinates ranging from 0 through 1023.

The application reads:

JoystickXpos
JoystickYpos
JoystickButtons1

JoystickButtons1 is used during the tutorial as a participant continuation button. A rising button press may advance eligible tutorial screens. It does not advance active practice trials and has no effect on experimental trial progression.

Joystick recording is normally enabled using the LogJoystick option. See LogJoystick for configuration details.

Experimental Target Generation

A new target angle is generated for each new experimental trial.

The random target generator produces an integer between 0 and 3599. TargetAngle therefore represents tenths of a degree:

angle in degrees = TargetAngle / 10

This produces target angles from 0.0 through 359.9 degrees.

Targets are positioned at a distance of TargetDistancePixels from the center (default 300 reference-display pixels) using the generated angle.

Unlike the original Neumann et al. experiment, which used eight circularly arranged target locations, the BCI2000 implementation allows experimental targets to appear over a continuous range of angles.

If the target distance is changed at runtime through the diagnostic window, the current and saved experimental target positions are recalculated at the new distance. The current distance is recorded in TargetDistancePx10.

Practice Target Generation

Practice trials use a deterministic six-angle sequence rather than the experimental random target generator:

Sequence value	Target angle
150	15 degrees
450	45 degrees
750	75 degrees
1050	105 degrees
1350	135 degrees
1650	165 degrees

Automatic practice begins with the 15-degree target and follows the sequence in order.

Controlled practice begins with an offset of two positions, producing:

75°, 105°, 135°, 165°, 15°, 45°

If more than six practice trials are configured, the sequence repeats.

These targets are positioned in the lower half of the participant display to reduce overlap with tutorial text, at the current TargetDistancePixels distance. The same deterministic sequence is used for both Standard and Easy practice trials.

The random target generated for the first experimental trial is saved before the tutorial begins and restored after practice finishes.

Trial Phases

The current trial phase is recorded in TaskPhase.

Value	Phase	Description
0	Block announcement / no active practice trial	During the experiment, the upcoming block type is being displayed. During non-trial tutorial screens, including Easy-introduction animation and text screens, `TaskPhase` is also 0.
1	Waiting for center	The task is waiting for the cursor to enter the center region.
2	Holding center	The participant is completing the required center hold.
3	Warning	The yellow warning cue is visible.
4	Pre-target delay	The warning has ended and the task is waiting for target onset.
5	Target visible	The peripheral target is visible and movement may occur.
6	Feedback	The target has been acquired and the task is waiting before advancing.
7	Finished	The run has reached its end after the final trial, or after a researcher action skips the remaining trial(s).

During active automatic or controlled practice trials, including Easy-introduction practice, values 1 through 6 retain the same meanings as they do during experimental trials.

Because non-trial tutorial screens use TaskPhase=0, analysts should use Introduction to distinguish tutorial screens from experimental block announcements. Within the tutorial, TutorialPhase identifies Standard stages and EasyIntroPhase identifies Easy stages.

An experimental target onset is identified by:

Introduction == 0
and TaskPhase transitions from 4 to 5

A practice target onset is identified by:

Introduction == 1
and PracticeTrial > 0
and TaskPhase transitions from 4 to 5

Condition and Block Encodings

State/Parameter	Value	Meaning
`TaskCondition`	0	Automatic
`TaskCondition`	1	Controlled
`TaskBlockType`	0	Ordered automatic block
`TaskBlockType`	1	Ordered controlled block
`TaskBlockType`	2	Pseudorandom mixed block
`OrderedStartCondition`	0	Automatic first
`OrderedStartCondition`	1	Controlled first

During the tutorial, TaskCondition reflects the tutorial condition rather than the first experimental condition. In the Standard introduction it begins at 0 during the general introduction and normal free-movement stages, including in Controlled Only mode, and changes to 1 once the controlled portion of the tutorial begins. In the Easy introduction it is 0 during the basic demonstration and all normal stages, changes to 1 when the reversed introduction begins, and remains 1 through the ready screen.

During the tutorial, TaskBlockType is forced to 0 and should not be interpreted as an experimental ordered-automatic block. The participant sees Normal for TaskCondition=0 and Reversed for TaskCondition=1; these labels do not change the state values.

Participant Display

The participant-facing ApplicationWindow contains:

A light gray background (0xEBEBEB).
A black cursor whose diameter is configured by CursorDiameterPixels (default 16 pixels in the reference display). The cursor diameter can also be changed at runtime from the diagnostic window; the center and warning markers retain their fixed sizes when it changes.
A black central fixation cross.
A gray center marker.
A larger yellow warning marker.
A green target during automatic (Normal) trials.
A red target during controlled (Reversed) trials.
A target diameter controlled by TargetDiameterPixels (default 36 pixels). This value also affects the elliptical target-hit tolerance, not just appearance.
A center-to-target distance controlled by TargetDistancePixels (default 300 pixels).
A visible NORMAL or REVERSED condition cue near the top of the participant display during relevant Standard tutorial stages and block announcements. The cue is not shown during the Easy introduction.
A progress bar near the top of the display during the experiment.
Tutorial and practice instructions when the introduction is enabled. The Standard introduction uses white text in a dark gray message box. The Easy introduction uses black text directly on the light background, and its text-only stages hide the cursor and fixation cross and occupy most of the display.
Animated cursor and target demonstrations during the Easy introduction, optionally accompanied by an animated joystick illustration.
Block announcements using the terms Normal, Reversed, or Mixed.
An "ended" message when the run reaches its end, including when a skip action bypasses the remaining trial(s).

The experimental progress bar is hidden throughout the tutorial and practice sequence. Practice trials do not contribute to experimental progress. When a researcher skips the remainder of an experimental block, the bar can advance to reflect the skipped trial positions even though those trials are not counted as successfully completed.

Changing the cursor diameter or target distance in the diagnostic window updates the participant display on the next processing block, recalculates the current and saved experimental target positions, and pulses DisplayGeometryChanged. The applied values are recorded in CursorDiameterPx10 and TargetDistancePx10. The target diameter can be changed only through the TargetDiameterPixels parameter before the run.

The StimulusDisplay parameter may be used to select the physical monitor on which the participant window appears.

The Normal/Reversed cue is intentional in this USB HID task. The underlying state encoding remains TaskCondition=0 for automatic/Normal and TaskCondition=1 for controlled/Reversed. In the Easy introduction, condition is conveyed by target color and instruction text instead of the on-screen cue.

Diagnostic Window

A separate diagnostic window is shown to the experimenter. In the currently inspected version, the visible panel is the performance metrics panel. During the tutorial it presents the introduction/practice context, mapping condition, cursor diameter, target distance, and applicable practice-trial information; live timing is shown as placeholders where appropriate, and run averages are not yet available. During experimental trials it presents:

Normal or Reversed condition and trial numbering within the block and overall experiment.
Current cursor diameter and target distance.
The current ReactionTimeMs, MovementTimeMs, and TotalTimeMs state values under a panel heading labeled REAL-TIME METRICS. These are not continuously running timers: they remain 0 until a target is acquired, then show the completed trial's values during feedback (and at run end for the final successful trial).
Overall and condition-specific (automatic and controlled) mean timing measurements.

Below the metrics panel are two spin boxes labeled Cursor diameter and Target distance. They adjust the displayed cursor size and center-to-target distance during a run. A change is applied on the next processing block, updates the current and saved target positions, pulses DisplayGeometryChanged, and updates CursorDiameterPx10 and TargetDistancePx10.

The application still assembles a more detailed diagnostic text label containing tutorial phase, task phase, target position, joystick and cursor coordinates, movement status, block type, completion/reset counts, and other status information. However, that text widget is explicitly hidden in the inspected build (mpDiagnosticText->hide()). These detailed values are not visible in the current diagnostic window and should not be mistaken for on-screen readouts. Relevant values can still be obtained from the recorded states.

Researcher Controls

The diagnostic window contains a blue CONTINUE button on eligible tutorial screens. When continuation is unavailable, it displays CONTINUE UNAVAILABLE. In the Easy introduction, researcher CONTINUE remains available even when EasyIntroSurgeryMode=1; surgery mode disables participant joystick-button continuation, not this researcher control. When EasyIntroRequireButtonPress=1 and surgery mode is off, either participant joystick input or researcher CONTINUE is required; otherwise, screens also advance automatically. Static Easy screens are immediately eligible, and demonstration screens become eligible after all configured examples have played. Researcher CONTINUE also bypasses the EasyIntroRequireJoystickNeutral gate.

Its context-sensitive reset button displays:

RESET PRACTICE TRIAL during eligible practice trials.
RESET CURRENT TRIAL during eligible experimental trials.
RESET UNAVAILABLE when reset is not permitted.

The current window also includes SKIP TRIAL, SKIP CURRENT BLOCK, SKIP INTRODUCTION, SKIP PRACTICE, SKIP SANDBOX, PREVIOUS EASY PHASE, RESTART EASY PHASE, and PAUSE/RESUME. Controls are enabled only in the appropriate task context. Skipping the current block and skipping the introduction prompt for confirmation; the other skip controls act without a confirmation dialog.

During the Easy introduction, the SKIP SANDBOX button is relabeled SKIP CURRENT EASY PHASE. PREVIOUS EASY PHASE returns to the preceding Easy stage (it is unavailable on the basic-demonstration stage), and RESTART EASY PHASE restarts the current Easy stage, including restarting an active practice block at its first trial. Setting EasyIntroAllowResearcherSkip=0 disables the Easy skip controls; the previous-phase and restart-phase controls remain available.

Researcher Skip Controls

Control	When available	Behavior	Recorded event
SKIP TRIAL	During an experimental trial before feedback, while not paused	Immediately advances to the next trial (or finishes the run if it was the last trial). A new target is generated for the next trial. A skipped trial does not increment completed-trial or reset metrics. In a controlled trial the return-to-anchor behavior is retained as needed.	`TrialSkipped`
SKIP CURRENT BLOCK	During an experimental trial before feedback, while not paused; confirmation required	Skips the remaining trials in the current block, advances to the next block or ends the run, and increments the overall trial-position counter by the number skipped. It does not count these trials as completed.	`ConditionSkipped`
SKIP INTRODUCTION	During the tutorial, while not paused; confirmation required	Exits the entire tutorial, restores the saved first experimental target, and enters the experimental block-announcement sequence. In the Easy introduction this control is available only when `EasyIntroAllowResearcherSkip=1`.	`IntroductionSkipped`
SKIP PRACTICE	During an active Standard or Easy practice trial, while not paused	Ends the remaining practice trials for that practice condition. In the Standard introduction, after Normal practice it proceeds to Reversed instructions if configured, otherwise tutorial completion; after Reversed practice it proceeds to completion. In the Easy introduction it advances to the next Easy stage. Available in Easy mode only when `EasyIntroAllowResearcherSkip=1`.	`PracticeSkipped`
SKIP SANDBOX / SKIP CURRENT EASY PHASE	During Standard Normal or Reversed free movement, or during any non-practice Easy stage, while not paused	In Standard mode, ends the free-movement stage and proceeds to the appropriate next instructions, practice stage, or completion screen. In Easy mode, the button is relabeled SKIP CURRENT EASY PHASE and advances to the next Easy stage; from the ready stage it begins the experiment. Available in Easy mode only when `EasyIntroAllowResearcherSkip=1`.	`SandboxSkipped`
PREVIOUS EASY PHASE	During the Easy introduction, while not paused, and not on the basic-demonstration stage	Returns to the preceding Easy stage. Moving back from the reversed-transition or ready stage re-enters the preceding practice block at its first trial.	`EasyIntroPrevious`
RESTART EASY PHASE	During the Easy introduction, while not paused	Restarts the current Easy stage. If a practice stage is active, the practice block restarts at its first trial.	`EasyIntroRestarted`

Each skip event is written as a one-processing-block state pulse and is cleared at the beginning of the next processing block. The Easy-phase navigation events EasyIntroPrevious and EasyIntroRestarted follow the same one-block pulse pattern. Skip and navigation actions can bypass the regular end-of-Process() state synchronization. Therefore, the event pulse may precede the updated TaskPhase, TaskTrial, TaskBlock, target, or cursor states by one processing block. If an action ends the entire run, the last recorded phase/trial values may retain their pre-action values rather than representing the usual Finished-phase state. Offline analyses should therefore use the event states, not rely solely on a simultaneous change in other states.

Pause and Resume

The PAUSE/RESUME control is available during both tutorial and experimental portions of the run, but not after the task finishes.

Pausing sets TaskPaused=1. Task trial and cursor progression stop, but the BCI2000 stream continues to record samples with the pause state high.
Resuming sets TaskPaused=0. The program shifts the applicable phase, tutorial, target-onset, and movement-onset clocks forward by the paused duration.
Paused time is excluded from the application's reaction time, movement time, total time, and active phase durations.
Researcher skip, previous-phase, and restart-phase actions are unavailable while paused.
Display-geometry changes made in the diagnostic window are still applied during a pause, without advancing the task.

A paused BCI2000 recording is not the same as a stopped BCI2000 run. Analysts should explicitly account for samples with TaskPaused=1.

Trial Reset

Experimental trials may be manually reset before they reach the feedback phase.

Resetting an experimental trial:

Returns the task to the waiting-for-center phase.
Clears the current movement and timing states.
Generates a TrialReset event.
Increments the experimental diagnostic reset count.
Keeps the same trial number.
Keeps the same target.
Does not generate a successful-trial event or count as a completed experimental trial.

Practice trials may also be reset before feedback, in both the Standard and Easy introductions.

Resetting a practice trial:

Returns the practice trial to the waiting-for-center phase.
Clears movement and timing states.
Generates a TrialReset event.
Keeps the same PracticeTrial value.
Keeps the same deterministic target.
Does not increment experimental reset metrics.
Does not increment experimental completed-trial metrics.

Reset is unavailable during tutorial instruction, demonstration, and free-movement screens and after a trial has entered feedback. Resetting a controlled trial after its target is visible also enables return-to-anchor handling so that resuming normal cursor control does not produce an abrupt jump. Reset preserves the current trial and its target, whereas SKIP TRIAL advances to a new one.

Timing Measurements

The task calculates reaction time, movement time, and total time for successfully completed practice and experimental trials.

Reaction time is the interval between target appearance and detected movement onset.

Movement time is the interval between detected movement onset and target acquisition.

Total time is the interval between target appearance and target acquisition.

Movement onset is detected when either joystick axis differs from the center-hold baseline by more than the task's joystick deadzone.

Timing is measured using a steady clock, but movement onset and target acquisition are detected during calls to Process(). The effective temporal resolution is therefore limited by the BCI2000 processing-block interval.

Practice timing values are recorded in the BCI2000 states but are excluded from experimental timing summaries. The task writes no application-specific CSV. When the researcher pauses the task, clock offsets are adjusted on resume so that the reported RT, MT, and total time exclude the paused interval, even though the paused samples remain in the BCI2000 data stream.

In the Easy introduction, the interval after a successful practice trial is set by EasyIntroFeedbackDurationMs, or is omitted when EasyIntroPracticeFeedback=0. This feedback interval follows target acquisition and does not change the recorded reaction, movement, or total times.

Data Recording

The task records its behavioral and tutorial variables as BCI2000 states, allowing them to be synchronized with the normal BCI2000 .dat recording.

Joystick coordinates are also recorded when joystick input logging is enabled.

Tutorial and practice samples are part of the same BCI2000 run as the experiment. The Introduction state should therefore be used when separating tutorial/practice data from experimental data during offline analysis. Within the tutorial, TutorialPhase identifies Standard stages and EasyIntroPhase identifies Easy stages.

Practice trials record:

Cursor trajectory.
Target coordinates and angle.
Trial phase.
Practice condition.
Movement onset.
Target acquisition.
Reaction time.
Movement time.
Total time.
Practice reset events.
Practice trial number.

Practice trials are intentionally excluded from:

Experimental TaskTrial numbering.
Experimental TaskBlock numbering.
Automatic and controlled completion counts.
Automatic and controlled reset counts.
Mean reaction-time summaries.
Mean movement-time summaries.
Mean total-time summaries.

No secondary results file is created by this application in the current version. The ResultsFile parameter and trial-level CSV writer were removed. All per-trial behavioral information must be reconstructed from the recorded BCI2000 .dat states; joystick state recording additionally depends on the normal LogJoystick configuration.

Researcher skip events (TrialSkipped, ConditionSkipped, IntroductionSkipped, PracticeSkipped, SandboxSkipped), Easy-phase navigation events (EasyIntroPrevious, EasyIntroRestarted), and the persistent TaskPaused state are also recorded. They identify deviations from ordinary trial/tutorial progression and samples recorded during pause.

Display geometry is recorded through CursorDiameterPx10 and TargetDistancePx10, both expressed in tenths of a pixel, and each runtime change produces a one-block DisplayGeometryChanged pulse. Because a target-distance change moves the current and saved targets, TargetX/TargetY and TargetAngle should be interpreted together with the distance state for the samples in question.

The application writes BCI2000 console messages when the task starts and stops and when practice or experimental trials succeed. Messages include the applicable trial/condition and reaction/movement times; these console messages are not an additional trial-level results file and should not be treated as synchronized state data.

Parameters

Parameters for experimental structure, timing, display, and display geometry are grouped under Application:USBHIDJoystick in the BCI2000 parameter tree. AutomaticPracticeTrials, ControlledPracticeTrials, and PracticeCenterHoldTime are grouped under Application:Introduction. IntroductionMode and the EasyIntro* parameters are grouped under Application:EasyIntroduction. Existing parameter files that use the removed EnableIntroduction parameter must be updated.

IntroductionMode

Selects the participant introduction and practice sequence.

Type: integer enumeration

Default: 2

Range: 0-2

Values:

0: Disabled. Skip the introduction and begin the experiment normally.
1: Standard. Text-driven introduction with free movement and practice trials.
2: Easy. Guided demonstrations, "your turn" screens, and short practice blocks (default).

This parameter applies to all experiment modes. It replaces the earlier boolean EnableIntroduction parameter: EnableIntroduction=1 corresponds approximately to IntroductionMode=1 (Standard), and EnableIntroduction=0 corresponds to IntroductionMode=0 (Disabled).

AutomaticPracticeTrials

Number of automatic practice trials presented during the Standard introduction (IntroductionMode=1).

Type: integer

Default: 3

Range: 0-20

The parameter is used only when the selected experiment mode contains automatic trials.

A value of 0 skips automatic practice trials while retaining the automatic instruction page.

The Easy introduction uses EasyIntroNormalPracticeTrials instead.

Practice trials do not count toward the experimental trial-count parameters.

ControlledPracticeTrials

Number of controlled practice trials presented during the Standard introduction (IntroductionMode=1).

Type: integer

Default: 3

Range: 0-20

The parameter is used only when the selected experiment mode contains controlled trials.

A value of 0 skips controlled practice trials. The controlled instruction page and controlled free-movement demonstration are still presented.

The Easy introduction uses EasyIntroReversedPracticeTrials instead.

Practice trials do not count toward the experimental trial-count parameters.

PracticeCenterHoldTime

Center-hold duration used during Standard-introduction practice trials.

Type: floating-point time

Default: 1s

Range: 0s-60s

This parameter replaces CenterHoldSeconds during Standard practice trials only.

Easy-introduction practice trials use EasyIntroPracticeCenterHoldMs.

Experimental trials continue to use CenterHoldSeconds.

The following parameters belong to the Application:EasyIntroduction group and affect only the Easy introduction.

EasyIntroAnimationEnabled

Enables animated cursor demonstrations in the Easy introduction.

Type: integer boolean

Default: 1

Range: 0-1

When set to 0, the cursor is displayed at a near-static position instead of animating between the center and target.

EasyIntroAnimationDurationMs

Duration of each Easy-introduction demonstration movement.

Type: integer (milliseconds)

Default: 2500

Range: 1-60000

EasyIntroAnimationPauseMs

Pause at the target before the next demonstration example or repetition.

Type: integer (milliseconds)

Default: 750

Range: 0-60000

EasyIntroAnimationLoop

Repeats the demonstration until the Easy stage advances.

Type: integer boolean

Default: 1

Range: 0-1

When set to 0, the demonstration plays only the configured number of examples and then stops.

EasyIntroNormalDemoDirections

Number of animated normal-mapping examples.

Type: integer

Default: 2

Range: 1-4

Example 1 moves to the lower right and example 2 moves directly right; additional examples fan upward.

EasyIntroReversedDemoDirections

Number of animated reversed-mapping examples.

Type: integer

Default: 2

Range: 1-4

The visual target movements follow the same sequence as the normal examples, while the illustrated joystick moves in the opposite direction.

EasyIntroNormalPracticeTrials

Number of normal-mapping practice trials in the Easy introduction.

Type: integer

Default: 3

Range: 0-20

A value of 0 skips normal practice while retaining the normal demonstration and "your turn" stages.

EasyIntroReversedPracticeTrials

Number of reversed-mapping practice trials in the Easy introduction.

Type: integer

Default: 3

Range: 0-20

A value of 0 skips reversed practice while retaining the reversed demonstration and "your turn" stages.

EasyIntroPracticeCenterHoldMs

Center-hold duration for Easy-introduction practice trials.

Type: integer (milliseconds)

Default: 3000

Range: 0-60000

This value replaces PracticeCenterHoldTime during Easy practice only.

EasyIntroPracticeFeedback

Enables the brief success-feedback interval after an Easy practice target is acquired.

Type: integer boolean

Default: 1

Range: 0-1

EasyIntroFeedbackDurationMs

Duration of the Easy practice success-feedback interval.

Type: integer (milliseconds)

Default: 500

Range: 0-60000

This value is used only when EasyIntroPracticeFeedback=1.

EasyIntroRequireButtonPress

Controls whether eligible Easy-introduction screens wait for manual continuation rather than advancing on their timers.

Type: integer boolean

Default: 0

Range: 0-1

When set to 0, stages advance automatically after their animations and timers. Joystick button 1 (when surgery mode is off) and researcher CONTINUE can still advance an eligible static screen before its timer expires. When set to 1 and EasyIntroSurgeryMode=0, stages wait for joystick button 1 or CONTINUE. Static screens are immediately eligible; demonstration screens become eligible after all configured examples have played. When surgery mode is on, this parameter does not prevent automatic advancement.

EasyIntroSurgeryMode

Advances the non-practice Easy-introduction screens automatically without participant button presses.

Type: integer boolean

Default: 0

Range: 0-1

This mode is intended for sessions in which the participant cannot operate the joystick button. Participant joystick-button continuation is disabled, and the configured animation, interim-screen, and ready-screen timers control progression. Researcher CONTINUE remains available on eligible non-practice screens. Practice trials still require the participant to acquire each target and return to center.

EasyIntroInterimScreenDurationMs

Time that transition and "your turn" screens remain visible when advancing automatically.

Type: integer (milliseconds)

Default: 2000

Range: 0-60000

EasyIntroReadyScreenDurationMs

Time that the final Easy ready screen remains visible before the experiment starts automatically.

Type: integer (milliseconds)

Default: 5000

Range: 0-60000

This value applies when the ready screen advances automatically.

EasyIntroRequireJoystickNeutral

Requires the joystick to be neutral before an automatic or participant-button advance leaves the normal or reversed Easy demonstration stage.

Type: integer boolean

Default: 1

Range: 0-1

When an automatic advance or participant joystick-button request occurs while the joystick is not neutral, the stage waits for neutral. If EasyIntroShowInstructionText=1, the display asks the participant to let go. Researcher CONTINUE bypasses this requirement.

EasyIntroShowJoystickIllustration

Shows the animated joystick illustration during the normal and reversed Easy demonstrations. The basic demonstration never shows the joystick illustration.

Type: integer boolean

Default: 1

Range: 0-1

EasyIntroShowInstructionText

Shows the Easy-introduction instruction text.

Type: integer boolean

Default: 1

Range: 0-1

EasyIntroAllowResearcherSkip

Enables the researcher skip controls during the Easy introduction.

Type: integer boolean

Default: 1

Range: 0-1

When set to 0, the Easy introduction cannot be exited or advanced with SKIP INTRODUCTION, SKIP PRACTICE, or SKIP CURRENT EASY PHASE. The PREVIOUS EASY PHASE and RESTART EASY PHASE controls remain available.

ExperimentMode

Selects the overall experimental structure.

Type: integer enumeration

Default: 1

Range: 1-4

Values:

1: Automatic only
2: Controlled only
3: Ordered automatic and controlled
4: Ordered automatic, ordered controlled, and pseudorandom mixed

The application verifies during preflight that the trial-count parameters required by the selected mode are at least 1.

The selected mode also determines which condition-specific tutorial sections are presented in the Standard introduction. The Easy introduction does not depend on ExperimentMode.

AutomaticTrials

Number of automatic experimental trials used by experiment modes 1 and 3.

Type: integer

Default: 5

Declared range: 0-10000

When used by the selected experiment mode, the value must be at least 1.

Practice trials are additional and do not reduce or increment this count.

ControlledTrials

Number of controlled experimental trials used by experiment modes 2 and 3.

Type: integer

Default: 5

Declared range: 0-10000

When used by the selected experiment mode, the value must be at least 1.

Practice trials are additional and do not reduce or increment this count.

OrderedStartCondition

Determines which experimental condition is presented first in experiment mode 3.

Type: integer enumeration

Default: 0

Values:

0: Automatic first
1: Controlled first

This parameter does not affect experiment modes 1, 2, or 4.

It also does not affect tutorial order. The Standard tutorial presents automatic training before controlled training when both are included, and the Easy tutorial always presents the normal stages before the reversed stages.

OrderedAutomaticTrials

Number of experimental automatic trials in the ordered automatic block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

OrderedControlledTrials

Number of experimental controlled trials in the ordered controlled block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

RandomAutomaticTrials

Number of experimental automatic trials included in the pseudorandom block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

RandomControlledTrials

Number of experimental controlled trials included in the pseudorandom block of experiment mode 4.

Type: integer

Default: 5

Declared range: 0-10000

When mode 4 is selected, the value must be at least 1.

StimulusDisplay

Selects the physical display used for the participant-facing application window.

Type: integer enumeration

Default: 0

Values:

0: Automatic/default ApplicationWindow placement.
1 and above: Select one of the displays detected when the parameters are published.

On Windows, available monitors are enumerated with their dimensions and primary-display status.

The application verifies during preflight that the selected display exists.

CenterHoldSeconds

Duration for which the participant must keep the cursor within the center region during experimental trials.

Type: floating point

Default: 3.0 seconds

Range: 0.0-60.0 seconds

Leaving the center during this interval restarts the center-acquisition sequence.

This parameter does not control practice center-hold duration. Standard practice trials use PracticeCenterHoldTime, and Easy practice trials use EasyIntroPracticeCenterHoldMs.

WarningSeconds

Duration of the yellow warning cue.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

Leaving the center during the warning interval restarts the center-acquisition sequence.

This parameter applies to both practice and experimental trials.

PreTargetDelaySeconds

Delay between the end of the warning cue and target appearance.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

The participant must remain centered during this interval.

This parameter applies to both practice and experimental trials.

FeedbackSeconds

Interval between successful target acquisition and advancement to the next trial, tutorial transition, or experimental block.

Type: floating point

Default: 0.5 seconds

Range: 0.0-60.0 seconds

This parameter applies to experimental trials and Standard-introduction practice trials. Easy-introduction practice instead uses EasyIntroFeedbackDurationMs when EasyIntroPracticeFeedback=1, or no feedback interval when it is 0.

CursorDiameterPixels

Cursor diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.

Type: floating point

Default: 16.0

Range: 1.0-1000.0

A positive value is required by preflight validation.

The cursor diameter can also be changed at runtime using the Cursor diameter control in the diagnostic window. Runtime changes are recorded in CursorDiameterPx10. The center and warning markers retain their fixed sizes when the cursor diameter changes. Because the cursor radius contributes to the target-hit ellipse, changing the cursor diameter also changes the effective target-acquisition tolerance.

TargetDiameterPixels

Target diameter, expressed in reference-display pixels and converted to normalized rendering dimensions during initialization.

Type: floating point

Default: 36.0

Range: 1.0-1000.0

A positive value is required by preflight validation. In addition to determining visual size, this parameter affects the ellipse used to determine target acquisition. Consequently, changing it can change the effective movement tolerance and behavioral measurements.

This parameter is not adjustable at runtime from the diagnostic window.

TargetDistancePixels

Center-to-target distance, expressed in reference-display pixels.

Type: floating point

Default: 300.0

Range: 1.0-350.0

The value applies to experimental targets, practice targets, and Easy-introduction demonstration targets. It can also be changed at runtime using the Target distance control in the diagnostic window; the applied value is recorded in TargetDistancePx10. Changing the distance recalculates the current and saved experimental target positions, so TargetX and TargetY change without a new target angle being generated.

The ResultsFile parameter was removed; see Data Recording.

States

The following states are defined by USBHIDJoystickTask and are recorded with the normal BCI2000 data stream.

Introduction

1-bit state indicating whether the participant tutorial/practice sequence is active.

Initial value: 0

Values:

0: Tutorial inactive or disabled; experimental data
1: Tutorial or practice sequence active

When IntroductionMode is 1 or 2, this state becomes 1 at the beginning of the run and returns to 0 when the tutorial completes and the experiment begins.

This is the primary state for separating tutorial/practice samples from experimental samples during offline analysis.

TutorialPhase

4-bit state indicating the current stage of the tutorial.

Initial value: 0

Values:

0: Tutorial inactive
1: General introduction
2: Normal free movement
3: Automatic instructions
4: Automatic practice
5: Controlled instructions
6: Controlled free movement
7: Controlled practice
8: Practice complete

After the final automatic or controlled practice feedback interval, TutorialPhase may remain 4 or 7 while PracticeTrial has returned to 0 and the task waits for the participant to return to center.

Outside the tutorial, TutorialPhase is 0.

The values above describe the Standard introduction. In the Easy introduction, TutorialPhase remains 0 throughout; use EasyIntroPhase to identify the stage.

EasyIntroPhase

4-bit state identifying the current stage of the Easy introduction.

Initial value: 0

Values:

0: Easy introduction inactive
1: Basic demonstration
2: Normal demonstration
3: Normal: now your turn
4: Normal practice
5: Reversed introduction
6: Reversed demonstration
7: Reversed: now your turn
8: Reversed practice
9: Ready

The state is nonzero only while IntroductionMode=2 and Introduction=1. Outside the Easy introduction it is 0. TutorialPhase is 0 during all Easy stages.

PracticeTrial

8-bit state identifying the active practice trial.

Initial value: 0

Values:

0: No active practice trial
1 and above: One-based practice trial number within the current practice condition

The state remains nonzero through the practice trial's feedback phase.

After the final practice feedback interval it returns to 0 while the tutorial may still wait for the participant to return to center.

Resetting a practice trial does not increment PracticeTrial.

Both Standard and Easy practice trials use this state; use TutorialPhase or EasyIntroPhase to determine which practice mode is active.

CursorX

10-bit state representing the current horizontal cursor coordinate.

Initial value: 512

Produced range: 0-1023

The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.

CursorY

10-bit state representing the current vertical cursor coordinate.

Initial value: 512

Produced range: 0-1023

The state is updated continuously while the task runs, including during free movement, practice, and experimental trials.

CursorDiameterPx10

16-bit state containing the runtime cursor diameter in tenths of a reference-display pixel.

Initial value: 160

At the start of a run, the value reflects CursorDiameterPixels. It is updated whenever the researcher changes the Cursor diameter control in the diagnostic window.

To convert to pixels:

cursor diameter (px) = CursorDiameterPx10 / 10

TargetDistancePx10

16-bit state containing the runtime center-to-target distance in tenths of a reference-display pixel.

Initial value: 3000

At the start of a run, the value reflects TargetDistancePixels. It is updated whenever the researcher changes the Target distance control in the diagnostic window.

To convert to pixels:

target distance (px) = TargetDistancePx10 / 10

DisplayGeometryChanged

1-bit event-like state indicating that a runtime display-geometry change was applied.

Initial value: 0

The state is set to 1 for one processing block when a change to the cursor diameter or target distance is applied, and is cleared at the beginning of the following processing block. It does not indicate that target diameter changed, because that parameter is fixed for the run.

TaskPhase

3-bit state containing the current trial phase.

Initial value: 0

Values:

0: Experimental block announcement or non-trial tutorial screen
1: Waiting for center
2: Holding center
3: Warning
4: Pre-target delay
5: Target visible
6: Feedback
7: Finished (the run reached its end normally or through a skip action)

During active practice trials, values 1 through 6 have the same meanings as during experimental trials, including Easy-introduction practice.

During non-trial tutorial screens, TaskPhase is forced to 0. This includes all non-practice Easy stages. Therefore, TaskPhase=0 alone no longer uniquely identifies an experimental block announcement.

Use:

Introduction == 0 and TaskPhase == 0

to identify an experimental block announcement. Within the tutorial, EasyIntroPhase or TutorialPhase identifies the screen type.

TaskCondition

1-bit state identifying the current movement condition.

Initial value: 0

Values:

0: Automatic (participant-facing Normal)
1: Controlled (participant-facing Reversed)

During active practice trials, this state identifies the practice condition.

During the general introduction and normal free-movement tutorial stages, it initially reports 0 even when the configured experiment is Controlled Only. In the Easy introduction it reports 0 through the basic demonstration and normal stages, then reports 1 from the reversed-introduction stage onward.

During the experiment it retains its original meaning.

TaskBlockType

2-bit state identifying the type of the current experimental block.

Initial value: 0

Values:

0: Ordered automatic
1: Ordered controlled
2: Pseudorandom mixed

During the tutorial, this state is forced to 0. It should therefore only be interpreted as an experimental block type when Introduction=0.

TargetAngle

12-bit state containing the target angle in tenths of a degree.

Initial value: 0

During experimental trials, generated values range from 0-3599.

To convert to degrees:

degrees = TargetAngle / 10

During practice trials, the state contains the deterministic practice-target angle.

During non-trial tutorial screens, including Easy demonstration and text screens, the state is set to 0.

After tutorial completion, the saved first experimental target is restored.

TargetX

10-bit state containing the horizontal coordinate of the current target.

Initial value: 512

Coordinate units correspond to the task's 0-through-1023 coordinate system.

During practice trials, it describes the current deterministic practice target.

During non-trial tutorial screens, including Easy demonstration and text screens, the target coordinate is written as 0 rather than retaining its initial value 512; gate it by task phase and tutorial status during analysis.

A runtime change of TargetDistancePixels moves the current target and updates this state without generating a new target angle.

TargetY

10-bit state containing the vertical coordinate of the current target.

Initial value: 512

Coordinate units correspond to the task's 0-through-1023 coordinate system.

During practice trials, it describes the current deterministic practice target.

During non-trial tutorial screens, including Easy demonstration and text screens, the target coordinate is written as 0 rather than retaining its initial value 512; gate it by task phase and tutorial status during analysis.

A runtime change of TargetDistancePixels moves the current target and updates this state without generating a new target angle.

TaskBlock

8-bit state containing the current one-based experimental block number.

Initial value: 0

While Introduction=1:

TaskBlock = 0

When the tutorial completes, the first experimental block begins with:

TaskBlock = 1

Practice trials do not consume experimental block numbers.

TaskTrial

16-bit state containing the current one-based overall experimental trial number.

Initial value: 0

While Introduction=1:

TaskTrial = 0

When the tutorial completes, the first experimental trial begins with:

TaskTrial = 1

Trial numbering continues across experimental block boundaries. Manually resetting an experimental trial does not increment TaskTrial.

Practice trials do not consume experimental trial numbers.

MovementStarted

1-bit state indicating whether movement onset has been detected during the current active practice or experimental trial.

Initial value: 0

The state changes to 1 when joystick displacement exceeds the movement deadzone after target onset. It remains high during the remainder of the movement and feedback period.

A rising transition from 0 to 1 identifies movement onset.

During non-trial tutorial screens, the state is forced to 0.

Use Introduction to distinguish practice movement onset from experimental movement onset.

TargetHit

1-bit event-like state indicating successful target acquisition.

Initial value: 0

The state is set to 1 when the cursor reaches a practice or experimental target and is cleared at the beginning of the following processing block. It therefore acts as a one-processing-block pulse.

Experimental acquisition:

TargetHit == 1 and Introduction == 0

Practice acquisition:

TargetHit == 1 and Introduction == 1

TrialReset

1-bit event-like state indicating a manual trial reset.

Initial value: 0

The state is set to 1 when the experimenter successfully resets a practice or experimental trial and is cleared at the beginning of the following processing block.

Experimental reset:

TrialReset == 1 and Introduction == 0

Practice reset:

TrialReset == 1 and Introduction == 1

TrialSkipped

1-bit event state for the researcher's SKIP TRIAL command during an eligible experimental trial.

Initial value: 0

The state is set to 1 when an experimental trial is skipped and cleared on the following processing block. Skipping advances trial position without counting a successful target acquisition and without increasing completed/reset metrics. The next trial receives a newly generated target, unless the run ends.

ConditionSkipped

1-bit event state for the researcher's SKIP CURRENT BLOCK command.

Initial value: 0

The state is set to 1 for one processing block when the remainder of the current experimental block is skipped. This command advances the overall trial-position counter over the skipped trials, which can change the progress indicator without changing completed-trial counts. The control requires experimenter confirmation.

IntroductionSkipped

1-bit event state for the researcher's SKIP INTRODUCTION command.

Initial value: 0

The state is set to 1 for one processing block when the tutorial is exited before normal completion. The current run proceeds directly to the experimental block-announcement sequence and restores the saved first experimental target. This control requires confirmation.

PracticeSkipped

1-bit event state for the researcher's SKIP PRACTICE command.

Initial value: 0

The state is set to 1 for one processing block when the remaining trials in the current practice condition are bypassed. It identifies incomplete tutorial practice and is distinct from experimental TrialSkipped.

SandboxSkipped

1-bit event state for the researcher's SKIP SANDBOX command.

Initial value: 0

The state is set to 1 for one processing block when a Normal or Reversed free-movement sandbox is bypassed in the Standard introduction, or when the researcher advances past a non-practice Easy stage using SKIP CURRENT EASY PHASE. The tutorial advances to the appropriate next stage.

EasyIntroPrevious

1-bit event state for the researcher's PREVIOUS EASY PHASE command.

Initial value: 0

The state is set to 1 for one processing block when the researcher moves back to the preceding Easy-introduction stage, and is cleared at the beginning of the following processing block. It is recorded only during the Easy introduction.

EasyIntroRestarted

1-bit event state for the researcher's RESTART EASY PHASE command.

Initial value: 0

The state is set to 1 for one processing block when the researcher restarts the current Easy-introduction stage, and is cleared at the beginning of the following processing block. If the restarted stage is a practice block, the block begins again at its first trial.

TaskPaused

1-bit persistent (level) state showing whether the task is paused.

Initial value: 0

0: Task running normally.
1: Task paused; task progression is suspended, while the BCI2000 data stream continues.

Unlike the skip and Easy-phase event states, TaskPaused remains high throughout a pause and returns to 0 on resume. Paused time is excluded from the task's reported timing intervals by shifting the relevant clock references on resume.

ReactionTimeMs

32-bit state containing reaction time in milliseconds.

Initial value: 0

Reaction time is measured from target appearance to detected movement onset.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

MovementTimeMs

32-bit state containing movement time in milliseconds.

Initial value: 0

Movement time is measured from detected movement onset to target acquisition.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

TotalTimeMs

32-bit state containing total target-directed trial time in milliseconds.

Initial value: 0

Total time is measured from target appearance to target acquisition.

The state is populated during successful practice and experimental trials.

Practice timing values should be distinguished from experimental values using Introduction.

External Joystick States

The application also uses states provided by BCI2000's input logging system. These states are not defined by USBHIDJoystickTask itself.

State	Description
`JoystickXpos`	Horizontal joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
`JoystickYpos`	Vertical joystick position. BCI2000 joystick input logging uses values from 0 through 32767.
`JoystickButtons1`	State of joystick button 1. During the tutorial, a rising press may advance eligible instruction or free-movement screens. In the Easy introduction it can advance an eligible screen when `EasyIntroSurgeryMode=0`. When `EasyIntroRequireButtonPress=1` and surgery mode is off, either this participant input or researcher CONTINUE is required; when it is 0, stages also advance automatically. It does not advance active practice trials and does not control experimental progression.
`Running`	Standard BCI2000 system state. The application sets it to 0 when the run reaches its end, including when a researcher skips the final trial or the remainder of the final block.

For details about enabling joystick recording and the joystick states provided by BCI2000, see Logging Input.

Data Analysis Notes

Because the tutorial and practice sequence are recorded within the same BCI2000 run as the experiment, analyses should use Introduction to distinguish experimental data from tutorial and practice data.

Measurement/Event	Recommended identification
Experimental samples	`Introduction == 0`
Tutorial/practice samples	`Introduction == 1`
Experimental trial	`Introduction == 0` and `TaskTrial > 0`; check skip events when reconstructing completed trials
Practice trial	`Introduction == 1` and `PracticeTrial > 0`; use `TutorialPhase` or `EasyIntroPhase` to distinguish Standard from Easy practice
Experimental block announcement	`Introduction == 0` and `TaskPhase == 0`
Non-trial tutorial screen	`Introduction == 1`, typically with `TaskPhase == 0`
Standard-introduction stage	`Introduction == 1` and `TutorialPhase > 0`
Easy-introduction stage	`Introduction == 1` and `EasyIntroPhase > 0`
Experimental target onset	`Introduction == 0` and transition from `TaskPhase=4` to `TaskPhase=5`
Practice target onset	`Introduction == 1`, `PracticeTrial > 0`, and transition from `TaskPhase=4` to `TaskPhase=5`
Experimental movement onset	Rising transition of `MovementStarted` with `Introduction == 0`
Practice movement onset	Rising transition of `MovementStarted` with `Introduction == 1`
Experimental target acquisition	`TargetHit == 1` and `Introduction == 0`
Practice target acquisition	`TargetHit == 1` and `Introduction == 1`
Experimental reset	`TrialReset == 1` and `Introduction == 0`
Practice reset	`TrialReset == 1` and `Introduction == 1`
Experimental trial number	`TaskTrial`
Practice trial number	`PracticeTrial`
Experimental block number	`TaskBlock`
Automatic vs. controlled	`TaskCondition`, interpreted together with `Introduction`
Ordered vs. mixed experimental block	`TaskBlockType` when `Introduction == 0`
Reaction time	`ReactionTimeMs`, gated by `Introduction` and the relevant trial event
Movement time	`MovementTimeMs`, gated by `Introduction` and the relevant trial event
Total time	`TotalTimeMs`, gated by `Introduction` and the relevant trial event
Cursor trajectory	`CursorX` and `CursorY`
Target coordinates	`TargetX` and `TargetY` on actual trials; non-trial tutorial screens set these to `0`. Interpret together with `TargetDistancePx10` when the distance may have been changed at runtime.
Target angle	`TargetAngle`
Skipped experimental trial	`TrialSkipped == 1`
Skipped experimental block remainder	`ConditionSkipped == 1`
Introduction bypassed	`IntroductionSkipped == 1`
Practice bypassed	`PracticeSkipped == 1`
Free-movement sandbox bypassed	`SandboxSkipped == 1`; in the Easy introduction this event also records SKIP CURRENT EASY PHASE
Easy phase moved backward	`EasyIntroPrevious == 1`
Easy phase restarted	`EasyIntroRestarted == 1`
Runtime cursor diameter	`CursorDiameterPx10` (tenths of a pixel)
Runtime target distance	`TargetDistancePx10` (tenths of a pixel)
Display-geometry change applied	`DisplayGeometryChanged == 1`
Samples recorded while the task is paused	`TaskPaused == 1`

TargetHit, TrialReset, TrialSkipped, ConditionSkipped, IntroductionSkipped, PracticeSkipped, SandboxSkipped, EasyIntroPrevious, EasyIntroRestarted, and DisplayGeometryChanged are single-processing-block pulses. MovementStarted remains high after movement onset until the trial advances or is reset. TaskPaused is a level state that remains high throughout a pause.

Analyses written for earlier versions of the task should be updated before use with tutorial-enabled data. In particular:

TaskPhase=0 no longer always identifies an experimental block announcement.
TargetHit=1 may indicate a practice or experimental success.
TrialReset=1 may indicate a practice or experimental reset.
Nonzero timing states may belong to practice trials.
TaskCondition and TaskBlockType should not be interpreted as experimental condition/block variables while Introduction=1.
Skip events mark incomplete trials or tutorial stages; skipped experimental trials do not produce TargetHit or increase completed-trial metrics.
ConditionSkipped can cause the progress indicator and overall trial-position counter to jump across uncompleted trials.
On a skip processing block, non-event states such as TaskTrial, TaskBlock, TaskPhase, and target coordinates may not update until the following block because skip dispatch returns before the normal state synchronization. A skip that finishes the run can leave final values at their pre-skip settings.
Samples recorded during TaskPaused=1 remain in the .dat stream. Exclude or flag them as appropriate; RT/MT/total-time values already exclude the pause duration.
TargetX and TargetY are 0 during non-trial tutorial screens, not their initial 512 values.
In the Easy introduction, TutorialPhase remains 0; use EasyIntroPhase to identify the active stage. A practice stage can therefore be identified from PracticeTrial > 0 together with EasyIntroPhase 4 or 8.
PracticeTrial numbering restarts for each practice block and does not indicate whether the block belongs to the Standard or Easy introduction.
Runtime changes to the cursor diameter or target distance appear in CursorDiameterPx10 and TargetDistancePx10, with a one-block DisplayGeometryChanged pulse. A target-distance change moves the current target without changing TargetAngle, so target coordinates from before and after the change are not directly comparable in normalized distance terms. A cursor-diameter change also alters the effective target-acquisition tolerance because the cursor radius contributes to the hit ellipse.
EasyIntroPrevious and EasyIntroRestarted record researcher navigation within the Easy introduction; they are not participant events and do not indicate skipped trials.
Condition names printed on screen and in console messages are Normal/Reversed, but the numeric TaskCondition codes remain Automatic=0 and Controlled=1.
No application-specific CSV is created in the current version; reconstruct trial-level results from synchronized BCI2000 state recordings.

References

Neumann WJ, Schroll H, de Almeida Marcelino AL, Horn A, Ewert S, Irmen F, Krause P, Schneider GH, Hamker F, Kühn AA. Functional segregation of basal ganglia pathways in Parkinson's disease. Brain. 2018;141(9):2655-2669. doi:10.1093/brain/awy206.