Eyetracker

**Look around Minecraft by leaning — with nothing but a webcam.**

Eyetracker turns an ordinary webcam into head tracking for Minecraft. Lean
left and the view slides left, lean down to see your feet in fullscreen, turn
your head to glance behind you without walking. No TrackIR hardware, no
drivers, no subscription — a webcam you already own.

**Press `H` to turn it on.** The mod loads and waits; it never starts on its
own. That is the single most common reason a working setup looks broken.

## What it adds

* **Head-controlled camera.** Yaw and pitch from your head drive your view
  every rendered frame, so the motion is smooth instead of stepped. Turn it
  off — or lose your face — and normal mouse-look is back instantly.
* **One-key recentre (`J`).** Snaps the tracked pose to wherever you are
  already looking, so you can set up in-game without fighting the mapping.
* **A response curve you can shape.** Per-axis sensitivity, a normalisation
  range, and a gamma curve that makes small motions snappy near centre and
  calm at the edges.
* **Client-side only.** It touches nothing but your own camera angle, so it
  works the same in singleplayer and on any multiplayer server.
* **A clear status line.** One chat line when you join a world tells you
  whether the mod is on, off, or waiting for a tracker that has not sent
  anything yet.

## How it works

The companion **Eyetracker** app estimates your head pose from your webcam
using MediaPipe's face-landmark model, smooths it, applies your calibration,
and streams it to Minecraft as JSON over UDP on `127.0.0.1:47777` — loopback
only, nothing leaves your machine. The mod listens, and rewrites your view
angles each frame while tracking is on.

Everything runs locally: no account, no telemetry, no uploads. The tracker's
only network access is a one-time download of the face-landmark model
(Apache-2.0, Google) on first run.

## Requirements

* **Minecraft 26.2** on **Fabric**.
* **Fabric Loader** 0.19.0 or newer.
* **Fabric API** — required, and installed as a dependency from this page.
* **Java 25** or newer (your Minecraft launcher handles this).
* **The Eyetracker tracker app** — free and MIT-licensed, available from this
  project's file list. The packaged Windows build covers most players; the
  tracker also runs from source on macOS and Linux.
* **A webcam.** A phone acting as a Windows virtual camera works too.

## Install

1. Install **Fabric Loader** and **Fabric API** for Minecraft 26.2.
2. Drop the jar into your `mods` folder:
   * **Windows** — `%appdata%\.minecraft\mods`
   * **macOS** — `~/Library/Application Support/minecraft/mods`
   * **Linux** — `~/.minecraft/mods`
3. Start **Eyetracker** before Minecraft. On first run it guides you through
   a short calibration — centre, left, right, up, down. Each step captures
   on its own, about 30 seconds in total. Press `C` to redo it later.
4. Join a world and press **`H`**.

That is the whole setup. You can change the camera, check tracking, and stop
the tracker from the tracker's own window at any time.

## Keys

| Key | Action |
|---|---|
| `H` | head tracking on/off — **you must press this** |
| `J` | recentre to how you sit right now |

Both are rebindable under *Options → Controls*.

## Tuning

Created on first run, at `config/eyetrack.json` in your Minecraft folder:

* `yawSensitivity` / `pitchSensitivity` — degrees of view per degree of head
  (default `1.0`).
* `yawRange` / `pitchRange` — the normalisation range for the curve
  (default `40` / `30`).
* `yawGamma` / `pitchGamma` — below `1.0` is snappier near centre, above
  `1.0` is calmer at the edges (default `1.0`).
* `invertYaw` / `invertPitch` — flip an axis if the view moves the wrong way.
* `staleTimeoutMs` — how long the tracker may be silent before the mod calls
  it "face lost" (default `500`).
* `port` / `bindAddress` — the UDP port and address the mod listens on
  (default `47777` on `127.0.0.1`). Change `port` here and in the tracker
  together.

## Troubleshooting

**Nothing happens, and no message appears.** The mod is not loaded. Check
the mod list on the title screen, and confirm you are on Fabric with Fabric
API installed.

**"No tracker data yet on UDP 47777".** Start Eyetracker, wait for it to
report it is tracking, then press `H` again.

**"Head tracking OFF (tracker found on UDP 47777)".** This is the normal
first line — the mod is working and waiting for you. Press `H`.

**The view drifts or will not return to centre.** Press `J`. Also check the
webcam is behind your monitor rather than beside it.

**The whole view shakes.** Lower `yawGamma` / `pitchGamma` toward `1.0`, or
raise `staleTimeoutMs`.

**The camera moves the wrong way.** Set `invertYaw` / `invertPitch` in the
config and restart the game.

## For developers

Each datagram is one UTF-8 JSON object:

{"v":1,"t":0,"seq":1,"tracking":true,"yaw":0.0,"pitch":0.0,"roll":0.0,"x":0.0,"y":0.0,"z":0.0}

Angles are degrees (`yaw` positive is turned to your left, `pitch` positive
is looking up), translations are centimetres relative to your calibrated
centre. This mod uses `yaw` and `pitch`; `roll` and the translations are sent
for other consumers.

The same datagram also carries four additive eye-gaze fields — `gaze_x`,
`gaze_y`, `gaze_ok` and `blink` — where the gaze values are screen fractions
and `gaze_ok` goes false when your eyes are closed or the two disagree. This
mod ignores all four; the packet version stays `1` because older consumers
simply do not read them.

## Credits and licence

* **MIT licensed**, source available for every part of this project.
* Face-landmark model by **Google** (Apache-2.0), used through MediaPipe.
* Not affiliated with Mojang or Microsoft.

Source, full documentation and issue tracker:
https://github.com/Elias2012-dev/Eyetracker