Designing VR water maze experiments

Trials are run from .vrScript files (up to 13 ready at once: default plus F1–F12). Open and edit them in a text editor such as Notepad++ straight from the live folder; try the supplied demonstrations first. After clicking 'Run HVS 6D VR', press the function key matching the file (F1 runs F1.vrScript). default.vrScript runs with no key; with several files HVS suggests an empty scene in default (SET_SCENE Main) so it is clear a key is needed. Live files must be in C:\Users\[User name]\AppData\LocalLow\HVS Image Software Ltd\HVS 4D VR (show hidden files). List all first-trial settings at the top; add trials with NEXT_TEST followed only by settings that change.

Going deeper

For more than 12 series, prepare descriptive-named versions elsewhere and copy them into place under the required names; keep copies of originals and copy edited live files back to your store. Supplied F-files are examples to adapt. The HVS vrScript technical reference (DOI 10.5281/zenodo.22303968) documents all commands. vrScript files and the .BOND headers are the best record of configuration for methods sections. Scripting is text editing, not programming.

Each vrScript needs a set of general lines that name the scene, the user, trial and subject, and set the tracking area and player scale: SET_SCENE (exact supplied scene name), USER_NAME, TRIAL_NAME, SUBJECT, DESCRIPTOR (e.g. group), REMARKS (appears in results), TRACKING_DIAMETER, TRACKING_AREA_NORTH 0, TRACKING_AREA_SOUTH = diameter, TRACKING_AREA_WEST 0, TRACKING_AREA_EAST = diameter, PLAYER_SCALE. For the VR water maze, a diameter of 200 (cm) is recommended so results are comparable with the rodent maze; keep it consistent across experiments. PLAYER_SCALE 0.16 correctly scales the participant relative to the environment. For target-finding environments TRACKING_DIAMETER is the environment width in metres from the demonstration files and PLAYER_SCALE is 1 or close to it.

Going deeper

Changing PLAYER_SCALE makes the environment feel bigger or smaller. Example from support: speed modifier 1, scale 0.16 and a 2 m pool gave about 0.14 m/s active speed (about 14 s to cross the diameter).

Keyboard: arrow keys give natural movement; A, S, D, F translate (not recommended without a specific purpose). Restrict keys with DEACTIVATE_NAVIGATION_KEYS followed by ACTIVATE_KEY lines. Where head turns set direction (treadmill or rotating chair) include CONTROL_TRANSFORM head_transverse, subject_transverse; omit it for arrow-key navigation. Treadmill or treadplate also needs READ_OMNI on, SMOOTH_MOTION w, n, OMNI_SENS and OMNIDRIVE_INPUT (use your supplied values). Head tilts can be mapped to keys with CONTROL_INPUT lines, e.g. CONTROL_INPUT left_tilt, LEFT_ARROW, -10 (10 = minimum tilt angle); map to A/D/F/S for translation; omit to disable.

Going deeper

For keyboard navigation on a treadmill system, HVS advised removing CONTROL_TRANSFORM, keeping DEACTIVATE_NAVIGATION_KEYS and adding ACTIVATE_KEY UpArrow, LeftArrow and RightArrow. Mobility-limited participants can use the arrow keys. Vive controllers are not officially part of the system (they may work: right disc forward, left disc turn); the treadplate is recommended for proprioceptive feedback, immersion and less motion sickness. Windows Sticky Keys has caused unexpected sliding; turn it off.

Adjust translation and rotation speed with SPEED_MODIFIER and DIRECTIONAL_ROTATION_SPEED; rotation by head turns follows the speed of the head turn. Once participants are used to certain speeds, these lines can give faster or slower than expected motion, and negative values reverse it. With the optional vertical environment, POINT_OF_VIEW third_person, 0 3 0 90 0 0 shows the arena vertically from 3 m away; a red arrow moves while the viewpoint stays fixed; the fifth value rotates the view; a third value of -0.2 can make the arrow easier to see with head tilts.

Going deeper

Treadmill forward motion maps each footfall to movement in the head-gaze direction; with speed modifier 1 and 0.5 s per step, two or more steps per second feels natural. Settings are retained in the .BOND headers for reporting.

A position in the vrScript is six numbers: east/west from centre (+ east), height above floor in metres, north/south (+ north), then sagittal, transverse and coronal rotation in degrees clockwise from North. In the water maze east and north are proportions of pool radius; in other environments they are metres. Before the first trial the participant waits at PRE_TRIAL_START_POINT to check the headset and practise; Enter moves them to TRIAL_START_POINT. In -0.7 1.13 0 0 270 0, 1.13 is water-surface height and 270 means facing west (0 north, 90 east, 180 south). Starting facing the poolside is conventional. Use 0 -1000 0 0 0 0 for the practice pool (featureless arena) or the holding pen in the Standard Laboratory (check your example files).

Going deeper

Start rotation is relative to the calibrated real-world facing direction: a participant facing 180° away from it at the start faces the opposite way in VR. Keep start and target points within about 7/9 of the pool radius: targets too near the wall can leave the virtual body overlapping the wall when the next trial starts at the target. Standard starts face outwards towards the wall and are recorded in .BOND headers. If the participant walks through the wall or starts on the lab floor, recentre the headset with them standing in their real trial position, and ask them to keep still before you press Enter.

The trial ends when the participant reaches the target edge defined by TARGET_RADIUS (metres) and TARGET_POSITION. A visible platform marker uses MOVE_OBJECT Visible_10cm_Platform with height 0 and other coordinates exactly matching TARGET_POSITION; once used, it stays until moved away (e.g. first coordinate 20). Cues and objects are added, moved or removed the same way, e.g. MOVE_OBJECT Star_Cue, Sphere_Cue, Hexagon_Cue, Cone_Cue, Pool_Screens. In target-finding environments, a cone marker (MOVE_OBJECT Cone_Cue with the target's coordinates) shows the target; remove it by moving it (e.g. first coordinate 1000), and target height normally equals start-point height.

Going deeper

TARGET_RADIUS 0.10 equals 10 cm in a 200 cm rodent-scale pool. The HVS 6D VR 2025 location_of_interest feature defines extra positions for analysis (e.g. a proximal cue location) and can be applied afterwards. TARGET_RADIUS is a radius, not a diameter.

MAXIMUM_TIME sets the limit if the target is not reached. TRIAL_TYPE can be visible platform, regular or probe. Probe trials run to the maximum time even when the target is reached; keep the learned position in TARGET_POSITION so it is shown on plots and analysed. In other trials the trial ends at the target edge and the participant can look around for STOP_INTERVAL seconds; with RETURN_TO_START a new trial starts in which they return to the start (repeat the line for each trial where needed). The environment then disappears for INTER_TRIAL_INTERVAL seconds.

Going deeper

Messages: REGULAR_END_TEXT (e.g. Target Reached!), TIMED_END_TEXT (Time's Up) and END_OF_SERIES_MESSAGE; leave blank for no message, and any language may be used. Triangle-completion series can start each trial from the previous target.

You can choose among several supplied VR environments, from a realistic water maze lab to an idealised cue-only arena, and add or move distal cues in each with vrScript lines. Options include a typical MWM lab with four cues, with or without pool screens; a lab with only natural cues; or an idealised environment with no lab features, shadow or walls, where any of four cues can be placed anywhere. Scene names are in your example .vrScript files. In the lab, MOVE_OBJECT lines add or remove the cue set, enclosure, natural cues and screens (first coordinate 20 removes). In the idealised arena, Star, Sphere, Hexagon and Cone cues are positioned by height (second) and distance (first and third) coordinates; Star and Hexagon need rotating to face the arena. Pre-trial start: holding pen in the lab (e.g. -5.2 2.2 4.2 0 0 0), practice pool in the featureless arena (0 -1000 0 0 0 0).

Going deeper

Further environments (natural pool, Minecraft-style, human-scale, apartment, suburban, forest/mountain) are options on some systems. Distal cues can be near the pool or large and far away (direction rather than position).

A dual-strategy water maze lets you tell apart navigation by distant room cues (allocentric) and by nearby cues or routes (egocentric), by adding movable proximal cues to the VR scene. In the dual or multi strategy version, place proximal cues (eight spheres each in white, mid grey, dark grey, red and green), e.g. MOVE_OBJECT Proximal_Cue_Mid_Grey_1 0.4 1.5 0.4 0 0 0 (east, height, north). Design options HVS has suggested: white space with no cues (egocentric route memory); small cues near the target (proximal); large far cues (allocentric, using stereopsis and triangulation); combinations; or a realistic distant environment with or without proximal cues; then forced-strategy trials that move cues.

Going deeper

Allocentric/egocentric behaviour identification is a paid analysis add-on: with a moved proximal cue, search relative to the distal-consistent position indicates allocentric and relative to the new proximal position egocentric. Edit files in a working folder and copy them back after any live edits.

Target-finding (way-finding) tasks use .vrScript files named default and F1–F12 as for the water maze. Differences: TRACKING_DIAMETER is the environment width in metres; PLAYER_SCALE is 1 or close; positions are metres from the centre, and height is above ground level (use the demonstration values, as ground can differ from floor level); a visible cone marker shows the target (move it to e.g. first coordinate 1000 to remove). PRE_TRIAL_START_POINT and TRIAL_START_POINT may be the same. Task data, analysis and back-up follow the water maze procedures.

Going deeper

Probe tasks continue to maximum time, testing the participant's confidence in the target location; keep the learned position in TARGET_POSITION. Other paradigms include triangle completion (path integration).

Follow the way-finding instructions and add MAIN_MP3 and END_WITH_MP3 lines naming mp3 files from C:\HVS Image[version]\Programs\VR\HVS_4D_VR_Data\Audio; the VR moves to the next task when the mp3 ends. Audio plays after Enter is pressed (background birds before). If the mp3 never starts, the file is missing or the name does not match; if the scene continues after it, END_WITH_MP3 is missing or mismatched. Hearing the birds confirms sound settings are fine.

Going deeper

If the Audio folder is missing, copy it from the most recent VR backup folder. Relaxation audio files are provided by HVS. Video playback is not yet included but is possible in principle.

EEG_SHOW_DATA_IN_HMD and EEG_SHOW_DATA_SUMMARY_IN_HMD (with wave types, e.g. alpha theta delta) show per-sensor and summary activity in the headset and on screen; set them to OFF to hide. RELAXATION_THRESHOLD (e.g. -230) sets the relaxed level; OUT_OF_STATE_TIME (e.g. 5 s) is how long 'not relaxed' must last to trigger extra relaxation; RELAXATION_TIME_THRESHOLD (e.g. 10 s) is how long 'relaxed' must last again to move on. Waves show green when relaxed and red when not. MAIN_MP3/END_WITH_MP3 set audio; OUT_OF_STATE_MP3 adds a deepener when needed.

Going deeper

Experiment with the thresholds while displaying EEG on screen. EEG per second can be recorded in BOND\EEG. Biofeedback can also use heart rate or skin conductivity on some systems.