Skip to content

Windows Setup

Jump to bottom
Bubbleshum edited this page Jun 27, 2026 · 3 revisions

Windows Setup

How to run WPR on Windows and import your first game. For build instructions see Building WPR.

Requirements

Requirement Notes
Windows 10 1809 (build 17763) or Windows 11 Desktop target's TPM is 17763
.NET 8 runtime Bundled if you self-contained-publish; otherwise install the .NET 8 desktop runtime
~50 MB disk for WPR Plus whatever your games need under %LocalAppData%\WPR\

WPR's graphics / audio / SDL backend ships next to the executable (FNA3D.dll, SDL2.dll, FAudio.dll, FNWP72.dll, ffmpeg.exe). No separate Vulkan / DirectX install is required — FNA3D picks a Direct3D 11 backend on Windows by default.

Getting WPR

There are no official binary releases yet. Build from source:

  1. Follow Building WPR.
  2. The desktop output lands at Src/UI/WPR.UI.Desktop/bin/Debug/net8.0-windows10.0.17763.0/ — distribute that whole folder.

First launch

Run WPR.UI.Desktop.exe. On first launch the app:

  • Creates %LocalAppData%\WPR\ for game installs and the SQLite databases.
  • Initialises the applications.db and achievements.db schemas.
  • Logs startup health-check output to the host console (and the per-game log file once a game launches).

The UI's main view is the game library — empty on first run.

Importing a game

  1. Click Add in the sidebar.
  2. Point at a .xap file (Windows Phone game package) you legally own. For XNA games shipped as a folder rather than a .xap, the library scanner can also pick those up if you place them under %LocalAppData%\WPR\Apps\<ProductId>\.
  3. The install pipeline runs:
    • ApplicationInstaller unpacks to %LocalAppData%\WPR\Apps\<ProductId>\.
    • ApplicationPatcher.PatchDll IL-rewrites each *.dll, leaving a .dll.original sibling.
    • XnaAchievementSeeder.SeedAsync populates the achievements DB.
  4. The game appears in the library.

Install only happens once per .xap. See Architecture for the pipeline details.

Launching a game

Pick the game from the library and click Run. WPR routes to one of two launchers based on ApplicationType:

Type Launcher
XNA XnaLauncher → ApplicationLaunch.Start (runs on FNA in a separate window)
Silverlight SilverlightLauncher.LaunchAsync (runs in an Avalonia host)

The first launch of a heavyweight game can take 5–30 s before the first frame renders. Subsequent launches are faster (warm shader caches, OS file cache).

Where things live

%LocalAppData%\WPR\
├── Apps\
│   └── <ProductId>\
│       ├── <Game>.dll               ← patched user assembly
│       ├── <Game>.dll.original      ← untouched copy
│       ├── AppManifest.xaml
│       ├── WMAppManifest.xml
│       ├── Content\…
│       └── wpr_game_debug.log       ← per-game trace (DEBUG builds)
└── Database\
    ├── achievements.db              ← per-game achievement rows
    └── applications.db              ← installed-app catalogue

The per-game wpr_game_debug.log is the first thing to read when a game crashes silently or shows a black screen. See Troubleshooting.

Input

Input Status
Mouse (as touch) Supported — left click = touch, drag = swipe
Touchscreen (Windows tablets) Supported via SDL2
Multi-touch Supported — real fingers + the mouse coexist in the touch slot table
Keyboard Used for the accelerometer simulator (defaults WASD), plus per-game key bindings

See Controls for the keyboard accelerometer, sensitivity slider, and the in-game tilt overlay.

Updating WPR

git pull

Then rebuild (Rider's build button, or the CLI command from Building WPR). The reinstall-vs-rebuild rule applies:

Change Action
Shim or runtime change Rebuild only — installed games pick up the new behaviour on next launch
Patcher table change (ApplicationPatcher.cs) Rebuild and reinstall the affected games

If the changelog (Update History) mentions an extractor or patcher table change for a specific game, that game needs reinstalling.

Common Windows-side issues

App won't launch — "The application failed to start because [some DLL] was not found."

You're missing a native dependency next to the exe. Confirm FNA3D.dll, SDL2.dll, FAudio.dll, FNWP72.dll, and ffmpeg.exe are present in the same directory as WPR.UI.Desktop.exe.

Game launches to a black screen

Check %LocalAppData%\WPR\Apps\<ProductId>\wpr_game_debug.log for [wpr-ex] lines — those are the swallowed exceptions during Draw. See Troubleshooting for the common patterns and what they mean.

SmartScreen warning

WPR isn't code-signed. SmartScreen will warn on first launch — "More info" → "Run anyway".

Game in library but won't run

Check applications.db actually has the row — sometimes a partial install leaves the folder without registering it. Easiest fix is to delete %LocalAppData%\WPR\Apps\<ProductId>\ and re-import the .xap.

Related pages

Clone this wiki locally