Immersa OpenXR Fishtank (native) - portable build
=================================================

Build: 2.4.33-1-ge896c411 (+ uncommitted working-tree changes)
Built: 2026-07-20, Windows x64, Release

This folder is self-contained: unzip it anywhere and run. Shaders are compiled
into the executable, so there are no asset files to keep alongside it. The
Visual C++ runtime DLLs are bundled, so no redistributable install is needed.


Quick start
-----------

  RunFishtankDesktop.cmd   No OpenXR runtime needed. Renders the scene to a
                           window. Use this first to confirm the PC can run it.

  RunFishtank.cmd          XR mode, against the OpenXR runtime registered on
                           this PC. Start Immersa Studio first.


Requirements on the target PC
-----------------------------

- Windows 10/11 x64.
- A Vulkan-capable GPU with current drivers. Roughly GTX 10-series class or
  newer is enough; the demo is sized to run fluently on ~2018 GPUs.
- For XR mode only: an OpenXR runtime. Installing Immersa Studio registers
  itself as the system runtime. To point at a specific runtime instead, set
  XR_RUNTIME_JSON before launching, e.g.

    set XR_RUNTIME_JSON=C:\path\to\openxr_monado-dev.json
    ImmersaOpenXrFishtank.exe

- Studio's room-setup bridge is optional. When Studio is running, recenter
  snaps the tank to the physical screen; without it, recenter places the tank
  in front of the head.


Controls
--------

  Trigger                  Close the tweezers - grab a nearby creature, or
                           spawn one (fish inside the tank, butterfly outside).
  Menu button (left)       Recenter the aquarium. On a DTrack flystick this is
  or R in the window       the button assigned to "Application menu" in Studio's
                           flystick settings.
  Left-click in window     Spawn a fish where the click ray enters the tank.
  Esc                      Quit.

A status line (fps, placement mode, bridge state) prints every second.


Useful options
--------------

  --fish <n>               Tank population (default 18).
  --seed <n>               Biodiversity seed (default 61786).
  --size <m>               Tank width in metres (default 0.5).
  --height <m>             Tank centre height above floor (default 1.4).
  --distance <m>           Tank distance in front of origin (default 1.0).
  --no-mirror              Disable the desktop mirror window.
  --bridge <url>           Studio room-setup bridge base URL (default:
                           auto-discover on http://127.0.0.1:8093).
  --desktop                Standalone mode, no OpenXR runtime.
  --desktop-eye-res <WxH>  Per-eye offscreen size in desktop mode
                           (default 1920x1080).
  --desktop-device <name>  Pick the GPU whose name contains this substring.
                           On multi-GPU machines, pin the same card the XR
                           runtime uses.
  --desktop-vsync          FIFO present instead of mailbox.
  --pixel-load <n>         Inject n fractal iterations per fragment - fill-bound
                           benchmark load (default 0).
  --fractal-only           Draw only the fullscreen sky pass and force --fish 0.

Arguments passed to the .cmd launchers are forwarded to the executable, so
e.g. "RunFishtank.cmd --fish 40 --size 0.8" works.


Troubleshooting
---------------

"Failed to find an OpenXR runtime"     Start Immersa Studio, or set
                                       XR_RUNTIME_JSON, or use desktop mode.
Window opens then closes immediately   Run the .cmd rather than the .exe so the
                                       error text stays on screen.
Vulkan device creation fails           Update the GPU driver. On a laptop with
                                       switchable graphics, force the discrete
                                       GPU, or use --desktop-device.
