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.

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.

• 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.

• 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.

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

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]