Background | Installation | Beginners | Tutorials | Features | Commands List | Coming Soon... | Requested Features | Version History

Background

simpleXR (sXR) is a software package designed to facilitate rapid development of XR experiments. Researchers in many different fields are starting to use virtual/augmented reality for studying things like learning, navigation, vision, or fear. However, the packages previously available for developing in XR were directed at computer scientists or people with a strong background in programming. sXR makes programming as simple as possible by providing one easy to use library with single line commands for more complicated tasks. The package is built for Unity and can be downloaded as a template project or added to previous projects with little effort. Just replace the scene's camera with the sXR_prefab and you'll gain access to multiple user interfaces and a plethora of commands that will allow you to start gathering data in days, not months. Extended reality is hard... simpleXR is simple.

Installation

Installation is now available through the package manager. Add from Git URL (with '.git' at the end), then right click to add sxr_prefab to your scene. For a full guide, see the wiki Installation page

Once installed, "sxr." commands should be automatically available in your IDE without any further setup:

Reporting Bugs, Contributing, and Requesting Features

While every attempt has been made to ensure sXR is compatible with all devices/Unity projects and bug free, there is the chance of encountering problems when using sXR. Please make a new issue on Github if you run into anything that doesn't seem to work how it should, or if there's a new feature you would like to see:

simpleXR is open-source, meaning the community is free to contribute. If you have a forked repository and have added a feature you'd like to see in the main repository, please make sure your code can be merged with the main repository before submitting a pull request. If it cannot merge, please include detailed comments on what has been changed in the main repository that is causing a conflict. To avoid conflicts, it's best to frequently update your working repository to the most up to date version of the package.

For Beginners

While sXR makes Unity much simpler, it can still be complicated if you're just starting out. The project contains a sample experiment with a step-by-step video walkthrough (youtube link). If you don't understand the ExperimentScript.cs file of the sample experiment, I recommend watching the entire video as it breaks down the development process. Feel free to reach out if you get stuck!

Tutorials

The Basics

Storing and accessing variables

Sample experiment video walkthrough (for beginners)

Vive Pro Eye Setup

Replay Mode

Features

Autosave - Enabled by default, can be turned off in the sXR tab of the toolbar. Automatically saves the scene when "Play" is pressed. Be sure to use "File->Save As" to name your scene or it will ask where you want to save.

Automatic VR - Enabled by default, can be turned off in the sXR tab of the toolbar. Automatically switches between moving the camera with keyboard controls (arrow keys/WASD) or with HMD tracking.

Safety Wall - Enabled by default, can be turned off in the sXR tab of the toolbar. Sometimes we don't want participants to see the wireframe boundary of SteamVR and need a bit more control over where the HMD will stop you. Declare the size of your space in the sXR tab and a "Stop" message will appear when the headset reaches the border. Do not rely solely on this feature since HMD tracking can be unstable. Always have participants walk carefully when they're wearing a headset.

Automatic position/eye-tracker recording - Using 'sxr.StartRecordingCameraPos()' or 'sxr.StartRecordingEyeTrackerInfo()' will enable automatic recording of the position/eye-tracker info at the frequency you specify in the sXR tab of the toolbar. Synchronizes eye-tracker and position information allowing for the scene to be replayed with the participant's gaze highlighted

Variable management - Allows you to access/change variables globally with sxr.SetInt/SetFloat/SetString/SetBool and sxr.GetInt/GetFloat/GetString/GetBool. The variables are saved to the computer and will load automatically with Unity. These variables can also be viewed/added/changed with the Unity editor in the sXR tab.

Commands List

Variable Managment

Experiment Control

Data Recording

User Interface

Input Devices

Object Manipulation

Extras

Variable Management

SetPref() Sets a Unity PlayerPref (See https://docs.unity3d.com/ScriptReference/PlayerPrefs.html). Variable persists upon restarting Unity

SetInt()/SetBool()/SetFloat()/SetString() Sets the specified type of variable as a PlayerPref

GetInt()/GetBool()/GetFloat/GetString() Returns the variable with the specified name

Experiment Control

SetExperimentName() - Used to override automatic naming scheme

ChangeExperimenterTextbox() - Chooses what to display on the specified textbox of the experimenter's screen

DefaultExperimenterTextboxes() - Specifies whether or not to use the defaults for textboxes 1-3 on the experimenter screen

ExperimenterTextboxEnabled() - Used to disable/re-enable textboxes on the experimenter's screen.

GetPhase() - Returns the current phase of the experiment. The experiment flow hierarchy is Phase > Block > Trial > Step

GetBlock() - Returns the current block number of the experiment

GetTrial() - Returns the current trial number of the experiment

GetStepInTrial() - Returns the current step of the trial

NextPhase() - Increments to the next phase, resets block/trial/step to zero

NextBlock() - Increments to the next block, resets trial/step to zero

NextTrial() - Increments to the next trial, resets step to zero

SetStep() - Sets the step to the specified number

StartTimer() - Starts a timer with the provided name. If no name is provided, starts the default trial timer. Requires a specified duration to use CheckTimer()

PauseTimer() - Pauses the timer with the provided name. If no name is provided, pauses the default trial timer.

CheckTimer() - Checks if the duration of a timer has passed. If it is a named timer, deletes the timer once duration is reached and CheckTimer() is called

RestartTimer() - Restarts the timer with the provided name. If no name is provided, restarts the default trial timer

TimePassed() - Checks how much time has passed on the timer with the provided name. If no name is provided, checks the default trial timer

TimeRemaining() - Checks how much time is left on the timer with the provided name. If no name is provided, checks the default trial timer

Data Recording

WriteHeaderToTaggedFile() - Writes the header line to the csv file with the specified tag. Any columns that will be made in WriteToTaggedFile() should have a column title declared with this function

WriteToTaggedFile() - Writes the line provided to the csv file with the specified tag

StartRecordingCameraPos() - Starts recording the world position of the vrCamera at the interval specified in sXR_settings

PauseRecordingCameraPos() - Pauses recording the camera until StartRecordingCameraPos() is called again

StartRecordingJoystick() - Starts recording the joystick position at the interval specified in sXR_settings

PauseRecordingJoystic() - Pauses recording the joystick until StartRecordingJoystick() is called again

StartRecordingEyeTrackerInfo() - Starts recording the information provided by an eyetracker at the interval specified in sXR_settings. Supports screenFixationX, screenFixationY, gazeFixationX, gazeFixationY, gazeFixationZ, leftEyePositionX, leftEyePositionY, leftEyePositionZ, rightEyePositionX, rightEyePositionY, rightEyePositionZ, leftEyeRotationX, leftEyeRotationY,leftEyeRotationZ, rightEyeRotationX, rightEyeRotationY, rightEyeRotationZ, leftEyePupilSize, rightEyePupilSize, leftEyeOpenAmount, and rightEyeOpenAmount (if these options are supported by the headset eyetracker, pupil size and eye open amount are not available through OpenXR).

PauseRecordingEyeTrackerInfo() - Pauses recording the eyetracker until StartRecordingEyeTrackerInfo() is called again

StartTrackingObject() - Starts recording the position of the object with the provided name at the interval specified in sXR_settings

PauseTrackingObject() - Pauses recording the position of the object with the provided name until StartTrackingObject() is called again

User Interface

InputSlider() - Creates and displays a slider that the participant can manipulate with the controller laser

InputDropdown() - Creates and displays a dropdown menu that the participant can manipulate with the controller laser

ParseInputUI() - Gets the response from an open InputSlider or InputDropdown

DisplayText() - Displays text to the VR headset at