Viscereality Companion mark
Altered States of Viscereality Companion desktop operator surface

Developer Path

Getting Started

Source-build path for developers and reviewers. Operators should usually start with the packaged download instead.

Getting Started

If you are not changing code and a public packaged release exists, use Download instead of the source-build path below.

Prerequisites

  • Windows 10 or later
  • .NET SDK 10.0 or later
  • Git LFS if you want the committed Sussex APK mirror instead of only the pointer file
  • official Quest tooling from the guided installer or the CLI tooling install-official path if you want the repo to manage hzdb plus Android platform-tools for you
  • or an existing adb install on PATH if you already manage Android platform-tools yourself
  • Node.js 24 or later if you want to build the docs site

Build And Run

git clone <repo-url> ViscerealityCompanion
cd ViscerealityCompanion
git lfs install
git lfs pull
dotnet build ViscerealityCompanion.sln
dotnet test ViscerealityCompanion.sln
dotnet run --project src/ViscerealityCompanion.App

If you want the repo to stage the current official Meta hzdb plus Google's Android platform-tools into the managed LocalAppData cache first, run:

dotnet run --project src/ViscerealityCompanion.Cli -- tooling install-official

If Smart App Control or Windows code integrity blocks the multi-file repo build on this machine, use:

powershell -ExecutionPolicy Bypass -File .\tools\app\Start-Desktop-App.ps1

That path publishes a single-file win-x64 app into artifacts/publish/ViscerealityCompanion.App/, prunes stale repo-local ViscerealityCompanion.exe copies, refreshes the canonical Desktop/Start Menu launcher, and launches the verified build.

If Windows code integrity blocks repo-built test assemblies on this machine, use:

powershell -ExecutionPolicy Bypass -File .\tools\app\Invoke-Signed-DotNetTest.ps1

That wrapper builds the test target, signs unsigned test output .dll and .exe files with the shared trusted CN=MesmerPrism signer from the local certificate store, and then runs dotnet test --no-build with heartbeat progress, TRX output, and hang diagnostics under artifacts/test-results/.

If you want a separate launcher for the repo-local development build, use:

powershell -ExecutionPolicy Bypass -File .\tools\app\Refresh-Local-Desktop-Launcher.ps1

That creates a clearly labeled Viscereality Companion (Local Dev) shortcut on Desktop and Start Menu. It launches the app through dotnet run so you can test local changes before publishing a single-file build. The published shortcut keeps the plain Companion icon, while the local-dev shortcut adds a small badge so you can tell them apart at a glance.

The app runs against the committed sample session-kit catalogs under samples/quest-session-kit/ and the public runtime-config profiles under samples/oscillator-config/.

Study-shell definitions are loaded separately from samples/study-shells/. You can also point the app at an external study-shell folder with VISCEREALITY_STUDY_SHELL_ROOT so new simplified operator windows can be added without changing the main app binary.

The repo-local session-kit sample is now the preferred default source. It currently contains one public Sussex Quest target plus one scene-matched runtime baseline. That keeps older internal APK and profile variants out of the public operator shell unless you explicitly point it at another catalog root. The committed samples/quest-session-kit/APKs/SussexExperiment.apk is the same Sussex APK used by the packaged study shell, so run git lfs pull before assuming the repo copy is present locally.

If adb is available, the Windows shell will use it automatically for:

  • USB probe and Wi-Fi ADB bootstrap
  • direct APK install from the selected file path
  • device profile application and explicit CPU/GPU level updates
  • app launch and headset status polling

The shell does not auto-select a target on startup anymore. It waits for an explicit headset snapshot. If the current foreground app is not in the public catalog, the target remains empty until you choose one manually.

CLI Tool

dotnet run --project src/ViscerealityCompanion.Cli -- --help
dotnet run --project src/ViscerealityCompanion.Cli -- probe
dotnet run --project src/ViscerealityCompanion.Cli -- catalog list --root samples/quest-session-kit
dotnet run --project src/ViscerealityCompanion.Cli -- status

See CLI Reference for the full command set.

Build The Docs Site

npm ci
npm run pages:build

The generated site is written to site/.

Windows Packaging

If you want the installed single-launcher path locally, use:

powershell -ExecutionPolicy Bypass -File .\tools\app\Build-App-Package.ps1 -Unsigned

That builds the MSIX package scaffolding under artifacts/windows-installer/.

Read Next