VR Comfort Framework

Open-source VR cybersickness prevention using cusp catastrophe theory.

Most VR comfort systems use simple linear thresholds: "if the score drops below 50, apply a vignette." But cybersickness is not linear. It exhibits sudden onset, asymmetric recovery, and path-dependent behavior — properties that match a cusp catastrophe from dynamical systems theory.

This framework models VR comfort as a two-state system with hysteresis. Once a user transitions from comfort to discomfort, recovery requires sustained high comfort — not just removing the stimulus. The framework also predicts that visible comfort interventions (like obvious tunnel vision) can paradoxically worsen sickness by raising conscious awareness of motion conflict.

Based on production comfort systems deployed on Meta Quest 3.

Quick Start

1. Install the scoring algorithm

Copy examples/unity/ComfortScore.cs into your Unity project, or use the JavaScript version from reference/comfort-score.js for web-based VR.

2. Compute comfort scores from your VR rig

const { computeComfortScore } = require('./reference/comfort-score');

const score = computeComfortScore({
  angularVelocity: 45,      // deg/s head rotation
  droppedFrames: 2,          // missed frames this interval
  sessionMinutes: 40,        // time in VR
  locomotionType: 'smooth'   // smooth locomotion active
});
// score: 72.5

3. Wire the cusp catastrophe state machine

const sm = new ComfortStateMachine();

function onFrame(deltaTime) {
  const score = computeComfortScore(getCurrentInputs());
  const result = sm.update(score, deltaTime);

  if (result.transition === 'fold') {
    // User just transitioned to discomfort — apply stronger vignette
    setVignetteRadius(0.35);
    suggestSnapTurn();
  } else if (result.state === 'flow') {
    // Subliminal vignette — below conscious perception
    setVignetteRadius(0.15);
  }
}

That is the complete core loop. The state machine handles the asymmetric hysteresis, post-recovery conservative windows, and sustained-time gates internally.

Documentation

• theory.md — The cusp catastrophe model explained for developers, not academics. Why linear thresholds fail, what hysteresis means in practice, and five testable predictions.
• implementation.md — Step-by-step guide to building the full system. Instrumentation, scoring, state machine, subliminal vignette shader, presets, and telemetry.

Examples

File	Language	Description
examples/unity/ComfortScore.cs	C#	Standalone comfort scoring utility
examples/unity/ComfortStateMachine.cs	C#	Cusp catastrophe state machine with hysteresis
examples/unity/ComfortVignette.shader	HLSL	URP-compatible subliminal vignette shader
reference/comfort-score.js	JavaScript	Portable scoring algorithm (Node.js + browser)

Platform Support

• Unity (C#) — Full examples provided, tested on Meta Quest 3
• Web (JavaScript) — Reference implementation, works with WebXR
• Any engine — The algorithm is pure math with zero dependencies. Port the scoring formula and state machine to any language.

Key Numbers

Parameter	Value	Rationale
Fold threshold	Score < 45 for 3s	Transition from flow to discomfort
Recovery threshold	Score > 85 for 30s	Transition from discomfort back to flow
Post-recovery window	5 minutes	Conservative thresholds after recovery
Subliminal vignette max	0.15 radius	Below conscious perception threshold
Discomfort vignette max	0.35 radius	Noticeable but not overwhelming
Max angular velocity	60 deg/s	Comfort ceiling for smooth locomotion
Fatigue onset	30 minutes	When session duration penalty begins

License

MIT License. Use it, modify it, ship it.

Citation

If you use this framework in research or a published project:

VR Comfort Framework: Cybersickness prevention using cusp catastrophe theory.
https://github.com/[your-repo-here]