{"id":50415479,"url":"https://github.com/itsloopyo/subnautica-2-headtracking","last_synced_at":"2026-05-31T05:31:02.247Z","repository":{"id":359970154,"uuid":"1239994121","full_name":"itsloopyo/subnautica-2-headtracking","owner":"itsloopyo","description":"Subnautica 2","archived":false,"fork":false,"pushed_at":"2026-05-24T10:42:32.000Z","size":32877,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T12:25:08.208Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsloopyo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T16:52:54.000Z","updated_at":"2026-05-24T10:42:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itsloopyo/subnautica-2-headtracking","commit_stats":null,"previous_names":["itsloopyo/subnautica-2-headtracking"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/itsloopyo/subnautica-2-headtracking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsloopyo%2Fsubnautica-2-headtracking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsloopyo%2Fsubnautica-2-headtracking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsloopyo%2Fsubnautica-2-headtracking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsloopyo%2Fsubnautica-2-headtracking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsloopyo","download_url":"https://codeload.github.com/itsloopyo/subnautica-2-headtracking/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsloopyo%2Fsubnautica-2-headtracking/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33720897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T05:31:01.598Z","updated_at":"2026-05-31T05:31:02.239Z","avatar_url":"https://github.com/itsloopyo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Subnautica 2 Head Tracking\n\nAn unofficial decoupled look+aim head tracking mod for Subnautica 2, look around naturally with your head while your mouse or controller controls your aim, with no VR headset required.\n\n![Mod GIF](https://raw.githubusercontent.com/itsloopyo/subnautica-2-headtracking/main/assets/readme-clip.gif)\n\n## Features\n\n- **Decoupled look and aim** - your head moves the camera while the mouse or controller keeps controlling aim, so weapons still fire where the reticle points.\n- **6DOF position tracking** - lean and move your head in space, with asymmetric forward/back limits to prevent clipping through the player.\n\n## Requirements\n\n- Subnautica 2, either the [Steam build](https://store.steampowered.com/app/1962700/Subnautica_2/) or the Game Pass / Xbox app build. Both store versions are supported; the installer auto-detects whichever (or both) you have.\n- An [OpenTrack](https://github.com/opentrack/opentrack)-compatible head tracker (VR headset, webcam, or phone app).\n- Windows 10 or 11, 64-bit.\n\n## Installation\n\n1. Download `Subnautica2HeadTracking-vX.Y.Z-installer.zip` from the [Releases page](https://github.com/itsloopyo/subnautica-2-headtracking/releases).\n2. Extract it anywhere.\n3. Double-click `install.cmd`.\n4. Configure OpenTrack to output UDP to `127.0.0.1:4242`.\n5. Launch the game.\n\n`install.cmd` finds every installed copy of Subnautica 2 on your machine\nand deploys to all of them. If you have both Steam and Game Pass\ninstalled, both are mod-enabled in one pass.\n\nIf the installer cannot find your game, point it at the install root\ndirectly with a positional argument:\n\n```powershell\ninstall.cmd \"D:\\Games\\Subnautica 2\"               :: Steam-layout root\ninstall.cmd \"C:\\XboxGames\\Subnautica 2\\Content\"   :: Game Pass root\n```\n\nor set the `SUBNAUTICA_2_PATH` environment variable to your install root.\n\n### Game Pass / Xbox App Notes\n\nThe Xbox app install is more locked down than the Steam install. Use the\ngame's `Content` folder as the root, normally:\n\n```cmd\nC:\\XboxGames\\Subnautica 2\\Content\n```\n\nThe mod files must end up here:\n\n```cmd\nC:\\XboxGames\\Subnautica 2\\Content\\Subnautica2\\Binaries\\WinGDK\\\n```\n\n`install.cmd` copies the mod there and also plants `dxgi_orig.dll` from\nyour own Windows install. If Windows denies the copy, close the Xbox app,\nright-click `install.cmd`, choose **Run as administrator**, and pass the\nContent path if auto-detection still fails:\n\n```cmd\ninstall.cmd \"C:\\XboxGames\\Subnautica 2\\Content\"\n```\n\n### Manual Installation\n\nIf you would rather place the files by hand, drop the mod into the\nbinaries folder for whichever build you have:\n\n| Store     | Target folder |\n|-----------|---------------|\n| Steam     | `\u003csteam\u003e\\steamapps\\common\\Subnautica2\\Subnautica2\\Binaries\\Win64\\` |\n| Game Pass | `C:\\XboxGames\\Subnautica 2\\Content\\Subnautica2\\Binaries\\WinGDK\\`   |\n\nYou need three files in that folder:\n\n1. `dxgi.dll` - the mod itself (from the release ZIP's `plugins/`). This\n   is a DXGI proxy: every DXGI call the game makes flows through us,\n   which is how we hook the camera path. The same `dxgi.dll` works for\n   both Steam and Game Pass; the proxy fingerprints the running exe and\n   selects the right RVA profile at load time.\n2. `dxgi_orig.dll` - **a copy of your own `C:\\Windows\\System32\\dxgi.dll`**.\n   The mod's exports forward here, so the game still reaches the real\n   DXGI through us. Copy it yourself, matching whichever build you have:\n   ```cmd\n   :: Steam\n   copy C:\\Windows\\System32\\dxgi.dll \"\u003csteam\u003e\\steamapps\\common\\Subnautica2\\Subnautica2\\Binaries\\Win64\\dxgi_orig.dll\"\n   :: Game Pass\n   copy C:\\Windows\\System32\\dxgi.dll \"C:\\XboxGames\\Subnautica 2\\Content\\Subnautica2\\Binaries\\WinGDK\\dxgi_orig.dll\"\n   ```\n3. `HeadTracking.ini` - mod configuration.\n\nThe Nexus ZIP contains both `Binaries\\Win64\\` and `Binaries\\WinGDK\\`\ntrees in one bundle. Extract it at the package root and the files land\nin the right place for whichever build you have - the unused folder is\nharmless. You still need to do the `dxgi_orig.dll` copy step above. The\nGitHub installer ZIP's `install.cmd` does the copy automatically and\nhits both builds at once if both are installed.\n\nFor the Xbox app build, extract the Nexus ZIP into:\n\n```cmd\nC:\\XboxGames\\Subnautica 2\\Content\n```\n\nThen run this from an administrator Command Prompt:\n\n```cmd\ncopy \"C:\\Windows\\System32\\dxgi.dll\" \"C:\\XboxGames\\Subnautica 2\\Content\\Subnautica2\\Binaries\\WinGDK\\dxgi_orig.dll\"\n```\n\n## Setting Up OpenTrack\n\nIn OpenTrack, set the **Output** to \"UDP over network\" and target\n`127.0.0.1:4242`. That is all the mod needs - it listens for the standard\nOpenTrack UDP packet stream.\n\n### VR Headset Setup\n\n1. Connect your headset to the PC with Air Link or Virtual Desktop and start SteamVR.\n2. In OpenTrack, choose the SteamVR input plugin so it reads your headset pose.\n3. Set Output to UDP over network, `127.0.0.1:4242`.\n\n### Webcam Setup\n\n1. In OpenTrack, set the input to the `neuralnet` tracker.\n2. Aim your webcam at your face and calibrate per the OpenTrack tracker guide.\n3. Set Output to UDP over network, `127.0.0.1:4242`.\n\n### Phone App Setup\n\nIf your phone app smooths its own output, send directly to your PC on\nport `4242`. If you want OpenTrack's curve mapping and filtering, point\nthe app at a local OpenTrack instance and let OpenTrack relay to\n`127.0.0.1:4242`.\n\n## Controls\n\nTwo equivalent binding sets - use whichever your keyboard has:\n\n| Action                          | Nav-cluster | Chord          |\n|---------------------------------|-------------|----------------|\n| Recenter                        | `Home`      | `Ctrl+Shift+T` |\n| Toggle tracking                 | `End`       | `Ctrl+Shift+Y` |\n| Cycle tracking mode             | `Page Up`   | `Ctrl+Shift+G` |\n| Toggle yaw mode (world / local) | `Page Down` | `Ctrl+Shift+H` |\n\n`Page Up` / `Ctrl+Shift+G` cycles tracking mode:\n\n1. Normal head-tracked gameplay\n2. Positional tracking disabled, rotational tracking enabled\n3. Rotational tracking disabled, positional tracking enabled\n4. Back to normal\n\n## Configuration\n\nSettings live in `HeadTracking.ini`, next to the game executable\n(`Subnautica2\\Binaries\\Win64\\` for Steam, `Subnautica2\\Binaries\\WinGDK\\`\nfor Game Pass). Edit it and restart the game to apply changes. If both\nbuilds are installed, each has its own copy of the file.\n\nOn the Xbox app build, Windows may block normal saves under the game\nfolder. Open Notepad as administrator, then open:\n\n```cmd\nC:\\XboxGames\\Subnautica 2\\Content\\Subnautica2\\Binaries\\WinGDK\\HeadTracking.ini\n```\n\nIf you installed the game to another drive or folder, use that install's\n`Content\\Subnautica2\\Binaries\\WinGDK\\HeadTracking.ini` path instead.\n\n```ini\n[Network]\nPort = 4242            ; OpenTrack UDP port\nBindAddress = 0.0.0.0  ; listen on all interfaces\n\n[Tracking]\nEnableOnStartup = true ; start with tracking active\nYawSensitivity = 1.0   ; multiplier for left/right look\nPitchSensitivity = 1.0 ; multiplier for up/down look\nRollSensitivity = 1.0  ; multiplier for head tilt\nInvertYaw = false\nInvertPitch = false\nInvertRoll = false\nSmoothing = 0.0        ; 0.0 = responsive, 1.0 = heavy (0.15 floor applied internally)\nAimDecoupling = true   ; head moves view, mouse/controller still aims\nShowReticle = true     ; draw the aim-compensated reticle\nWorldSpaceYaw = true   ; true = horizon-locked yaw (default), false = camera-local\n\n[Position]\nEnabled = true         ; 6DOF head position tracking\nSensitivityX = 1.0\nSensitivityY = 1.0\nSensitivityZ = 1.0\nInvertX = true         ; sideways lean direction\nInvertY = false        ; vertical move direction\nInvertZ = true         ; forward/back lean direction\nLimitX = 0.30          ; max sideways lean in meters\nLimitY = 0.20          ; max vertical move in meters\n; Z limits are swapped because InvertZ = true: with inversion, forward maps to\n; +z (the LimitZBack bound) and backward maps to -z (the LimitZ bound). Keeping\n; forward generous (0.40) and backward restricted (0.10) avoids clipping through\n; the player, so LimitZBack holds the generous value here.\nLimitZ = 0.10          ; backward lean limit in meters\nLimitZBack = 0.40      ; forward lean limit in meters\nSmoothing = 0.15\n\n[Hotkeys]\n; Recenter (Home), toggle tracking (End), and cycle tracking mode (Page Up)\n; are fixed, each also reachable with a Ctrl+Shift chord. Only the yaw-mode\n; toggle is rebindable here. VK code: PageDown = 0x22.\nToggleYawMode = 0x22\n```\n\n## Troubleshooting\n\n**Mod not loading**\n\n- Confirm `dxgi.dll`, `dxgi_orig.dll`, and `HeadTracking.ini` are all in the binaries folder for your build - `Subnautica2\\Binaries\\Win64\\` for Steam, `Subnautica2\\Binaries\\WinGDK\\` for Game Pass. Missing `dxgi_orig.dll` is the most common cause - the proxy forwards every DXGI export there, so without it the game crashes on launch.\n- Windows may block the downloaded DLL: right-click `dxgi.dll`, Properties, then Unblock.\n- Check the mod log next to the DLL for a `build-check: PASS - matched profile ...` line.\n\n**No tracking response**\n\n- Verify OpenTrack is running and its Output is sending to `127.0.0.1:4242`.\n- A firewall may be blocking UDP on port 4242; allow it.\n\n**Jittery / unstable tracking**\n\n- Raise `Smoothing` in `[Tracking]` toward 0.3-0.5.\n- On a wireless or phone tracker, expect more jitter; the built-in 0.15 smoothing floor helps but more smoothing reduces it further.\n\n**Wrong rotation axis**\n\n- If a look axis goes the wrong way, set the matching `Invert` flag (`InvertYaw` / `InvertPitch` / `InvertRoll`) to `true`.\n\n**Yaw feels wrong when looking up or down at extreme angles**\n\n- Try toggling between world-locked and camera-local yaw with `Page Down`. World-locked (default) is horizon-stable; camera-local follows the camera's current up-axis.\n\n## Updating\n\nDownload the new release and run `install.cmd` again. Your config is\npreserved.\n\n## Uninstalling\n\nRun `uninstall.cmd`. This removes `dxgi.dll`, `dxgi_orig.dll`, and\n`HeadTracking.ini` from the binaries folder of every detected install\n(Steam and / or Game Pass). If you had a pre-existing `dxgi.dll` (e.g.\nReShade) when you installed the mod, the original is restored from its\n`.backup` copy. Pass `/force` to discard the backup instead.\n\n## Building from Source\n\nRequires Visual Studio 2022 with the Desktop C++ workload and CMake.\n\n```powershell\ngit clone --recursive https://github.com/itsloopyo/subnautica-2-headtracking\ncd subnautica-2-headtracking\npixi run build\npixi run install\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Credits\n\n- [Unknown Worlds Entertainment](https://unknownworlds.com/) for [Subnautica 2](https://store.steampowered.com/app/1962700/Subnautica_2/).\n- The [OpenTrack](https://github.com/opentrack/opentrack) contributors for the head-tracking UDP protocol.\n- The [CameraUnlock shared core](https://github.com/itsloopyo/cameraunlock-core) for the head-tracking processing pipeline used across all our mods.\n\n## Disclaimer\n\nThis mod is not affiliated with, endorsed by, or supported by Unknown\nWorlds Entertainment or KRAFTON. Use at your own risk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsloopyo%2Fsubnautica-2-headtracking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsloopyo%2Fsubnautica-2-headtracking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsloopyo%2Fsubnautica-2-headtracking/lists"}