Unity SDK

Install the Unity SDK

Step 1 · Install dependencies

Install the base dependencies if they are not already present.

TextMeshPro (com.unity.textmeshpro) ships with Unity. No separate install needed. The first time a scene requires TMP, click Import TMP Essentials when prompted.

Step 2 · Download the package

https://github.com/harmoneyes/HarmonEyesSDK/raw/main/HarmonEyesSDK.unitypackage

Step 3 · Import into Unity

In Unity, choose Assets › Import Package › Custom Package… and open the HarmonEyesSDK.unitypackage you downloaded. Leave all boxes checked and click OK.

Mock Tracker sample

The SDK ships with a Mock Tracker sample that lets you exercise the SDK and validate your license key without a Vive or Meta Quest Pro headset connected. It can also replay CSV recordings captured by the Vive or Meta sample collectors, so you can re-run the SDK against a known data stream.

1. Open Assets/HarmonEyesSDK/Samples/HarmonEyesMockTrackerSample/Scenes/HarmonEyesMockTrackerSampleScene.
2. Select the EyeTrackingDataMockAnalyzer prefab and enter your license key in the EyeTrackingConfig component.
3. On the same prefab, the MockEyeTrackingCollectingData component exposes a “Session Csv” slot. A bundled CSV (eyetrackingsample_meta_quest_pro.csv) is assigned by default; drag in your own recording to replay it.
4. The “Playback Speed Multiplier” (1×–20×) controls how fast rows are emitted, and higher values compress wall-clock time so the time-gated capabilities (Fatigue, Mental Readiness) reach their thresholds faster during testing.
5. Select the appropriate eye-tracker type in the AnalyzeEyeTrackingData component (defaults to Pupil Labs to match the sample CSV).
6. Press Play. The in-scene text fields display Cognitive Load, Fatigue, Attention, and Mental Readiness, confirming the SDK is loaded and the license key validated.

Overview & integration

The Unity SDK turns raw eye-tracking data from a supported headset or webcam into four real-time capabilities: Cognitive Load, Fatigue, Attention, and Mental Readiness. It is delivered as a Unity package: a native theia library, a C# wrapper, three platform sample scenes (Meta Quest Pro, HTC Vive Focus Vision, and a headset-free Mock player), and editor scripts.

What it produces

Supported hardware

For any tracker not listed, select the nearest lower-Hz preset.

Get a license key

A license key is required. Contact us to obtain one. The same key is entered on the AnalyzeEyeTrackingData component in each sample scene.

Three ways to use the SDK

Manual integration

A custom integration is three steps.

Add the AnalyzeEyeTrackingData component to a GameObject, enter the license key, and pick the tracker preset that matches your hardware (or the closest sample-rate match, rounding down). The component handles native SDK creation, license validation, and session start automatically on Start. Read AnalyzeEyeTrackingData.Instance.EyeTrackingInitCompleted to know when initialisation has completed.

using UnityEngine;
using HarmonEyes.EyeTracking.Common;

public class MyCollector : MonoBehaviour
{
    [SerializeField] private Camera headCamera;

    void FixedUpdate()
    {
        var analyze = AnalyzeEyeTrackingData.Instance;
        if (analyze == null || !analyze.EyeTrackingInitCompleted) return;

        long timestampNs = (long)(Time.timeAsDouble * 1e9);

        // Pull per-eye origin, orientation, closed-weight and a blink
        // decision from your platform's API.
        Vector3    leftEyeOrigin       = Vector3.zero;
        Quaternion leftEyeOrientation  = Quaternion.identity;
        float      leftEyeClosed       = 0f;
        Vector3    rightEyeOrigin      = Vector3.zero;
        Quaternion rightEyeOrientation = Quaternion.identity;
        float      rightEyeClosed      = 0f;
        bool       isBlinking          = false;

        Sample s = GazeDataSampleFactory.CreateGazeSample(
            analyze.SessionId, timestampNs,
            leftEyeOrigin,  leftEyeOrientation,  leftEyeClosed,
            rightEyeOrigin, rightEyeOrientation, rightEyeClosed,
            headCamera.fieldOfView,
            isBlinking);

        analyze.SubmitGazeSample(s);
    }
}

Polling: read the latest payload on demand:

var mw = analyze.EyeTrackingAnalyzer.CurrentMentalWorkload;   // Cognitive Load
if (mw != null) Debug.Log($"Cognitive Load: {mw.LevelName} (conf {mw.confidence:F2})");

Event-driven: subscribe once, react to each new prediction:

analyze.EyeTrackingAnalyzer.OnMentalWorkloadResult += mw =>
    Debug.Log($"Cognitive Load: {mw.LevelName} (conf {mw.confidence:F2})");

API reference

Real-time Cognitive Load, Fatigue, Attention, and Mental Readiness from eye-tracking hardware. Every type below lives in the HarmonEyes.EyeTracking.Common namespace.

Analysis outputs

Cognitive Load and Fatigue refresh once per second (edge-triggered when a new native batch arrives); Attention updates continuously as fixations and saccades accumulate; Mental Readiness is computed on demand from accumulated Cognitive Load predictions. Each payload carries a monotonically increasing counter (batch_number, total_observations, or total_predictions) so consumers can edge-trigger UI updates.

Scene setup

1. Add AnalyzeEyeTrackingData to a GameObject, which holds SDK config and the latest predictions, and runs the once-per-second submission of accumulated gaze samples to the native SDK.
2. Enter your license key in the LicenseKey field. It is validated synchronously during Start(); success or failure is logged to the Unity console.
3. Add a platform-specific collector that submits samples into Instance.EyeTrackingData.Samples each tracker frame.

License validation

On scene start, validation happens automatically. Two boolean flags expose the outcome:

if (AnalyzeEyeTrackingData.Instance.LicenseKeyValidated) { /* SDK is live; start submitting samples */ }
if (!AnalyzeEyeTrackingData.Instance.EyeTrackingInitCompleted) { /* missing/invalid key */ }

Submitting eye-tracking data

Per-frame eye data is built into a neutral Sample via GazeDataSampleFactory.CreateGazeSample, then submitted via SubmitGazeSample. Accumulated samples are pushed to the native SDK once per second. The factory projects each eye’s gaze ray onto a 1600×1200 virtual screen at 600 mm using the supplied FOV.

Accessing results

Subscribe to callbacks, or poll the Current* properties (all nullable, so null-check before use).

var a = AnalyzeEyeTrackingData.Instance.EyeTrackingAnalyzer;
a.OnMentalWorkloadResult  += mw  => Debug.Log(mw.LevelName);   // Cognitive Load
a.OnFatigueResult         += fat => Debug.Log(fat.LevelName);
a.OnAttentionResult       += att => Debug.Log(att.label);
a.OnMentalReadinessResult += mr  => Debug.Log($"low {mr.low_percentage:F0}% / high {mr.high_percentage:F0}%");

a.CurrentMentalWorkload    // MentalWorkloadData,   nullable  (Cognitive Load)
a.CurrentFatigue           // FatigueData,          nullable
a.CurrentAttention         // AttentionData,        nullable
a.CurrentMentalReadiness   // MentalReadinessData,  nullable

Class reference

Scene-level singleton MonoBehaviour. Owns the native SDK lifecycle and the 1 Hz analyzer pump. Exactly one instance must exist in the scene.

Static class. Builds Sample records; hides the XY projection, per-session blink-ID iteration, and pupil-diameter computation.

public static Sample CreateGazeSample(
    string sessionId, long timestampNs,
    Vector3 leftEyeOrigin, Quaternion leftEyeOrientation,
    Vector3 rightEyeOrigin, Quaternion rightEyeOrientation,
    float fovDeg, bool isBlinking,
    double pupilDiameterLeft = 0.0,
    double pupilDiameterRight = 0.0);

Returns a Sample populated with the timestamp, left/right eye screen XY (pixels), optional pupil diameters, and a monotonic blink ID. EndSession(string sessionId) clears the per-session blink-ID counter, an optional cleanup when many sessions run in one app.

Thin C# wrapper around the native theia C API, managed by AnalyzeEyeTrackingData. Documented for advanced users. Normal integrations don’t call it directly.

One frame of eye data in the neutral shape the analyzer consumes. Build with CreateGazeSample.