A Unity prototype for preparing a low-stimulus, symptom-limited VR rehabilitation study for adolescents with persistent symptoms after concussion.
Research prototype only. This software is not a medical device or an independent treatment tool. It does not diagnose concussion, determine recovery, or provide return-to-play clearance. Any use with adolescents requires an approved research protocol, IRB approval, parental permission and participant assent, and supervision by qualified clinicians.
The project is designed to support investigation of the following questions:
- Is daily, symptom-targeted VR exposure after concussion associated with a faster reduction in daily symptom scores?
- Do symptoms associated with emotional, physical/visual, and cognitive domains improve more quickly after repeated exposure to the corresponding task?
- Can symptom change be recorded safely alongside performance measures such as head-gaze tracking error, memory accuracy, and reaction time?
This repository is not a completed clinical trial platform. It is a development and feasibility prototype for implementing and testing the research flow and three intervention modules.
| Nature Calm | Gaze Stabilization | Memory & Reaction |
|---|---|---|
 |
 |
 |
| Fixed horizon, low-amplitude water, and breathing guide | Horizontal and vertical target paths with a fixation anchor | Backpack, basketball, and bottle memory choices |
These images are QA captures rendered by a Unity Editor camera from the same runtime environments. They are not captures from a Quest 3 headset.
See the intervention storyboard for the detailed design rationale and frame-by-frame data contract.
A staggered multiple-baseline SCED across participants is the preferred candidate design for three participants. Because concussion symptoms can change rapidly through natural recovery, a simple pre/post comparison would make it difficult to separate an intervention effect from the passage of time.
| Component | Proposed approach | Current implementation |
|---|---|---|
| Participants | Three high-school students with concussion who meet the approved eligibility criteria | Not implemented; requires a research protocol |
| Phase A | Participant-specific staggered baseline periods with daily symptom measurement | Not implemented |
| Phase B | Supervised daily VR sessions with symptom checkpoints | Session prototype implemented |
| Primary outcome | Daily total score and rate of change from an approved validated symptom scale | Six-item placeholder implemented |
| Secondary outcomes | Domain-specific symptoms, head-gaze error, memory accuracy, and reaction time | Partially implemented |
| Analysis | Level, trend, immediacy, overlap, phase-specific slopes, and sensitivity analyses | Not implemented |
Final baseline lengths, session frequency, stopping rules, clinically allowable symptom increase, and the statistical analysis plan must be approved by clinicians, methodologists, and the IRB. A reversal or ABAB design that withdraws treatment during recovery is not the preferred option.
flowchart LR
A["Pre-session symptom check"] --> B["Nature Calm"]
B --> C["Symptom checkpoint"]
C -->|Rest| R1["Supervised rest"]
R1 --> D["Gaze Stabilization"]
C -->|Continue| D
D --> E["Symptom checkpoint"]
E -->|Rest| R2["Supervised rest"]
R2 --> F["Memory & Reaction"]
E -->|Continue| F
F --> G["Post-session symptom check"]
G --> H["Summary + de-identified CSV"]
X["ESC safety stop"] -. available throughout .-> H
The default prototype settings are 12 seconds for Nature Calm, 15 seconds for Gaze Stabilization, and six Memory & Reaction trials. These values support rapid development testing and do not represent a clinical dose.
- Uses a seated posture and a stationary camera by default.
- Presents a fixed horizon, a teal-to-blue sky, soft morning light, and linear fog.
- Uses one central breathing sphere to guide inhalation and exhalation.
- Limits the water shader wave amplitude to
0.006to reduce visual motion. - Excludes automatic camera motion, particles, flicker, lens flare, and strong peripheral movement.
- Uses Blender-generated low-poly pine trees with procedural Unity lake and mountain meshes.
Currently recorded: task duration and post-task symptom ratings.
- Uses a stable clinic-like background and a central fixation anchor.
- Moves a teal target slowly in horizontal and then vertical directions.
- Samples the angle between the camera forward vector and the target direction to calculate mean error.
- Because the standard Quest 3 does not provide an eye-tracking sensor, the current measure is a head-gaze proxy, not eye gaze.
- The current prototype does not include walking; the user is instructed to keep the camera/head as stable as possible.
A future walking or treadmill condition must be developed as a separate module after fall-risk assessment, supervision procedures, harness/environment planning, and clinical approval.
Currently recorded: mean head-gaze angular error and sample count.
- Uses a backpack, basketball, and bottle that can be recognized without reading.
- Enlarges the target object for 1.2 seconds before returning all choices to their baseline scale.
- Accepts participant responses using
1,2, or3. - Provides brief, non-flashing feedback.
- Maintains both editable Blender source and Unity-ready OBJ/MTL assets.
Currently recorded: correct responses, number of trials, and median reaction time for correct responses.
The current UI records an integer rating for each of the following items:
- Headache
- Dizziness
- Nausea
- Eye strain
- Light sensitivity
- Difficulty concentrating
These six items are placeholders for validating the UI and data pipeline. Before use in a study, they must be replaced with an age-appropriate validated instrument, the required usage permissions, and its official scoring rules.
When a session is completed or stopped for safety, the following variables are exported as one row of CSV data:
| Domain | Example variables |
|---|---|
| Identity and time | participant_id, session_id, started_utc, ended_utc |
| Completion status | status, stop_reason |
| Symptoms | pre_total, after_calm_total, after_pursuit_total, post_total, max_symptom_increase |
| Nature Calm | calm_seconds |
| Gaze | pursuit_mean_error_degrees, pursuit_samples |
| Cognition | memory_correct, memory_trials, median_correct_reaction_seconds |
Storage location:
Application.persistentDataPath/ConcussionVR/Sessions
The current CSV pipeline is not intended to collect directly identifying information. Before research deployment, the team must define participant ID generation, access control, encryption, retention, and secure deletion procedures.
- Supervised seated mode is the default.
- A stable horizon or fixation anchor remains visible.
- Each screen presents one instruction and one primary stimulus goal.
- Each active module is followed by a symptom checkpoint and a rest option.
- The
Esckey can stop the session at any time and records the stop reason. - The software does not prescribe or automatically increase clinical difficulty.
- The interface does not use diagnostic, recovery, or return-to-play language.
- Unsupervised adolescent use is excluded from the v1 scope.
flowchart TD
Scene["ConcussionVRPrototype.unity"] --> Controller["PrototypeSessionController"]
Controller --> View["PrototypeView / UI input"]
Controller --> Tasks["TaskEnvironment"]
Tasks --> Builder["InterventionSceneBuilder"]
Builder --> Art["EnvironmentArtFactory"]
Art --> Shaders["Custom shaders + procedural meshes"]
Art --> Models["Blender OBJ/MTL resources"]
Controller --> Data["SessionRecord + SessionRules"]
Data --> CSV["CsvSessionExporter"]
Assets/ConcussionVR/
├── Editor/ # Scene generation and QA capture tools
├── Resources/ # Blender models and custom shaders
├── Runtime/ # Session flow, environments, UI, and data export
├── Scenes/ # Executable Unity scene
└── Tests/ # EditMode and PlayMode tests
ArtSource/Blender/ # Editable Blender source
Docs/ # Storyboards, screenshots, and QA evidence
Tools/Blender/ # Procedural Blender asset-generation script
- Unity
6000.4.9f1 - Windows development environment
- Blender 5.x, only when regenerating assets
- Meta Quest integration is planned; the current version is centered on Unity Editor and desktop input.
- Open the repository folder in Unity Hub.
- Open
Assets/ConcussionVR/Scenes/ConcussionVRPrototype.unity. - Enter Play Mode.
- Use the mouse on symptom-assessment screens.
- Use
1,2, or3during the memory task. - Press
Escat any time to enter the safety-stop flow.
blender --background --python Tools/Blender/build_intervention_assets.pyThe script regenerates the Blender source, Unity-ready OBJ/MTL assets, and a QA preview. If Blender is not available on PATH, use the full path to the executable.
Run the following Unity menu command:
Concussion VR > Capture High Fidelity Previews
Captures are saved in Docs/QA/HighFidelity/.
Run the EditMode and PlayMode suites with Unity Test Runner.
Current automated coverage includes:
- Session startup screen and button transitions
- Symptom-increase progression rules
- Nature Calm lake and mountain meshes, pine trees, and sky/water shaders
- Horizontal and vertical pursuit-target motion
- Blender-based memory-task objects and materials
- Memory-cue presentation and removal
Latest verified result: PlayMode 2/2 passed and the Windows standalone build completed successfully.
| Phase | Development goal | Completion criterion | Status |
|---|---|---|---|
| P0 | Desktop research flow, safety stop, and CSV export | Complete or stop a full session and save data | Complete |
| P1 | Visual prototypes for all three interventions | Pass the storyboard contract and QA screen review | Complete |
| P2 | Clinician-authored dose profiles | Lock duration, speed, amplitude, trials, and rest settings before a session | Planned |
| P3 | OpenXR and Quest 3 controller/head pose | Validate input, frame rate, and fixed horizon on the device | Planned |
| P4 | High-resolution time-series logging | Store target and head pose with shared timestamps | Planned |
| P5 | SCED study layer | Record phase schedules, daily measures, missingness, and protocol deviations | Planned |
| P6 | Data protection | Validate ID policy, encryption, export, and audit logging | Planned |
| P7 | Healthy-adult usability pilot | Validate input errors, readability, cybersickness, and safety-stop flow | Planned |
| P8 | Limited feasibility study after clinical and IRB approval | Meet predefined safety and acceptability criteria | Planned |
ScriptableObject-based clinician-authored difficulty profiles- Synchronized target-position and head-pose time-series recording for the Gaze module
- Quest 3 OpenXR input and performance-budget validation
- A validated symptom instrument with study participant/session management
- Participant-specific staggered baselines and daily measurement schedules
- Long-format CSV/JSON export and a data dictionary for analysis
- Free walking and artificial locomotion
- Automatic camera motion
- Optokinetic stripes and visually crowded scenes
- Automatic difficulty progression
- Competitive scoring and intense reward effects
- Labeling measurements as eye gaze on hardware without eye tracking
- Diagnostic or recovery-clearance functions
- Clinical eligibility, stopping criteria, and allowable symptom increase
- Validated symptom instrument and measurement frequency
- Participant-specific baseline lengths and phase-transition rules
- Pursuit speed, amplitude, and direction ranges
- Whether a walking task is necessary and the associated fall-prevention protocol
- Data security, retention period, and access controls
- Preregistered analysis plan and inter-rater reliability procedures for visual analysis
No open-source license is currently specified. Therefore, the repository does not automatically grant permission to reuse or distribute its contents. The licenses for the code, models, and reference materials must be finalized before research or collaborative distribution.