Skip to content

Free fork of NotProton: Windows Steam games in Mac Steam, on CodeWeavers' Wine and Apple's Game Porting Toolkit

docs: developer guide, architecture, security policy and complete notices

raymondchins67fbef390cfa
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
new file mode 100644
index 0000000..f653ca1
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -0,0 +1,33 @@
+name: Bug report
+description: Something in Bridgeplay doesn't work (setup, Steam, updates, controllers)
+labels: ["bug"]
+body:
+ - type: textarea
+ id: what
+ attributes:
+ label: What happened
+ description: What did you do, what did you expect, and what happened instead?
+ validations:
+ required: true
+ - type: input
+ id: version
+ attributes:
+ label: Bridgeplay version
+ description: Shown at the bottom of the app's sidebar, for example "Bridgeplay 3.0.1 (35)".
+ validations:
+ required: true
+ - type: input
+ id: macos
+ attributes:
+ label: Mac and macOS version
+ placeholder: MacBook Pro M3, macOS 26.1
+ validations:
+ required: true
+ - type: textarea
+ id: logs
+ attributes:
+ label: Logs
+ description: |
+ Attach `~/Library/Application Support/bridgeplay/bridgeplay.log`. For a game, also
+ attach its `bridgeplay-run.log` (Prefixes page › the game › Open Log).
+ render: text
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..14378cd
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+ - name: Security problem
+ url: https://github.com/raymondchins/Bridgeplay/security/advisories/new
+ about: Report security problems privately, not as a public issue.
+ - name: Problem in NotProton itself
+ url: https://github.com/NotProtonNot/NotProton/issues
+ about: If it also happens with upstream NotProton and CrossOver, report it there.
diff --git a/.github/ISSUE_TEMPLATE/game-report.yml b/.github/ISSUE_TEMPLATE/game-report.yml
index 80e0c98..2bd5ee6 100644
--- a/.github/ISSUE_TEMPLATE/game-report.yml
+++ b/.github/ISSUE_TEMPLATE/game-report.yml
@@ -6,7 +6,9 @@ body:
- type: markdown
attributes:
value: |
- Run `scripts/np-test-game.sh <appid> --stop` first; it writes logs and `result.json` to `compat/runs/<appid>-<timestamp>/`. Attach that folder (zipped) below.
+ Played it with the Bridgeplay app? Fill in the fields and attach the game's `bridgeplay-run.log` (Prefixes page › the game › Open Log).
+
+ Working from a Bridgeplay checkout? Run `scripts/np-test-game.sh <appid> --stop` instead and attach the zipped `compat/runs/<appid>-<timestamp>/` folder.
- type: input
id: name
attributes:
@@ -58,14 +60,14 @@ body:
id: engine
attributes:
label: Engine
- placeholder: WineHQ 11.15
+ placeholder: WineCX 11.17
validations:
required: true
- type: input
id: fork_commit
attributes:
- label: Fork commit
- description: The Bridgeplay version you run, or `git rev-parse --short HEAD` in your Bridgeplay checkout.
+ label: Bridgeplay version
+ description: Shown at the bottom of the app's sidebar (for example 3.0.1 (35)), or `git rev-parse --short HEAD` in a checkout.
validations:
required: true
- type: input
@@ -82,4 +84,4 @@ body:
id: logs
attributes:
label: Logs
- description: Drag and drop the zipped `compat/runs/<appid>-<timestamp>/` folder here, or paste `result.json`.
+ description: Drag and drop `bridgeplay-run.log`, or the zipped `compat/runs/<appid>-<timestamp>/` folder, or paste `result.json`.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..2e9acb5
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,20 @@
+## What and why
+
+<!-- What does this change, and why? Link the issue if there is one. -->
+
+## Checks
+
+<!-- Which checks did you run? For example `make ci-checks`, `make scriptcheck runcheck`, `make app-tests`. -->
+
+## Tested on
+
+- macOS:
+- Steam build (Steam › About Steam):
+- Engine (WineCX 11.17, DXMT, DXVK…):
+- Games tried:
+
+## Shipped files
+
+- [ ] No prebuilt binary, signature database or gamefix changed
+- [ ] A prebuilt binary changed, and its patch folder's README says how it was rebuilt (sha256 updated)
+- [ ] A signature database or gamefix changed, with the evidence in the PR
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..f75d332
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,11 @@
+# Code of Conduct
+
+Bridgeplay follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful and patient, assume good faith, and keep criticism about the work,
+not the person. Harassment, insults and personal attacks are not accepted in issues, pull
+requests or any other project space.
+
+Report unacceptable behaviour to the maintainer, Raymond Chin, through GitHub
+(https://github.com/raymondchins). Reports are handled privately. The maintainer may remove
+comments, close threads or block accounts that break this code.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c1bcb4a..858a556 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,19 +5,46 @@ is the easiest to review. An imperfect PR is still welcome: say what is unfinish
help.
1. **Open an issue first** for anything large, and check closed issues and PRs so work is not
- duplicated. Game reports use the "Game report" template.
-2. **Write the PR description yourself.** Translation is fine; plain human text is easier to
- review than generated text.
-3. **Keep comments short and useful.** Comment where the code is hard to follow, not where it
+ duplicated. Game reports use the "Game report" template, bugs the "Bug report" one.
+2. **Read [docs/DEVELOPING.md](docs/DEVELOPING.md)** for what machine you need, how to build,
+ how to try a change in Steam, and the checks. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+ says where new code goes.
+3. **Write the PR description yourself.** Translation is fine; plain human text is easier to
+ review than generated text. Fill in the template: checks run, macOS, Steam build, engine.
+4. **Keep comments short and useful.** Comment where the code is hard to follow, not where it
is obvious.
-4. **Think through the hard parts.** Code that runs inside Steam, the run script, lsteamclient,
+5. **Think through the hard parts.** Code that runs inside Steam, the run script, lsteamclient,
Wine patches and game saves interact in subtle ways. Consider multiple Steam accounts,
libraries, macOS users and file systems.
-5. **Run the checks** your change touches before opening the PR (`make scriptcheck`,
- `make buildcheck`, `make app`; see [docs/DEVELOPING.md](docs/DEVELOPING.md)).
+6. **Run the checks** your change touches before opening the PR (`make ci-checks` runs them
+ all; `make scriptcheck runcheck` also works on Linux).
-By contributing you agree that your contribution is licensed under the GPL-3.0, like the rest
-of Bridgeplay (see [LICENSE](LICENSE) and [NOTICE](NOTICE)). Changes that belong upstream
-are better sent to [NotProton](https://github.com/NotProtonNot/NotProton).
+## Process
-Report problems at https://github.com/raymondchins/Bridgeplay/issues.
+- Pull requests go into `main`. Commits follow Conventional Commits (`feat(scope):`,
+ `fix(scope):`, `docs:`).
+- The maintainer reviews every PR. CI runs on PRs while the workflows are enabled; until then,
+ say in the PR which checks you ran.
+- Releases are made by the maintainer only (they need the Sparkle signing key); see
+ [docs/RELEASING.md](docs/RELEASING.md).
+- Security problems are reported privately; see [SECURITY.md](SECURITY.md).
+
+## Licensing
+
+A contribution is licensed under the license of the files it changes, as listed in
+[NOTICE](NOTICE). For most of Bridgeplay that is the GPL-3.0 ([LICENSE](LICENSE)). The
+exceptions:
+
+| Path | License |
+|---|---|
+| `lsteamclient/` | Steamworks SDK License (Valve), see `LICENSE.lsteamclient` |
+| `lsteamclient/steamworks_sdk_*/` | Valve's Steamworks SDK headers, redistributed under the Steamworks SDK License |
+| `steam-shim/` | BSD-3-Clause (port of Proton's steam_helper), see `LICENSE.steam-shim` |
+| `*-patch/` Wine patches and the Wine files built from them | LGPL-2.1-or-later, like Wine |
+| `fonts/` | Each font's own license; the build files under `LICENSE.fonts` |
+| `vendor/cJSON.*`, `steam-shim/jsoncpp.cpp`, `steam-shim/json/` | MIT (cJSON), public domain / MIT (JsonCpp) |
+
+Changes that belong upstream are better sent to [NotProton](https://github.com/NotProtonNot/NotProton).
+
+This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). Report problems at
+https://github.com/raymondchins/Bridgeplay/issues.
diff --git a/NOTICE b/NOTICE
index fd36bcb..16218bf 100644
--- a/NOTICE
+++ b/NOTICE
@@ -9,14 +9,17 @@ Bridgeplay is a modified version (fork) of NotProton,
https://github.com/NotProtonNot/NotProton, by way of NotProton-WineHQ (below).
It is licensed under the GNU General Public License version 3 (GPL-3.0), the
same terms as NotProton; see LICENSE. Bridgeplay is free and non-commercial.
-Files under other licenses are listed below and keep their own terms.
+"Non-commercial" describes how Bridgeplay is distributed and is required by Apple's
+Game Porting Toolkit license (below); it does not restrict anyone's rights under the
+GPL-3.0 to Bridgeplay's own code. Files under other licenses are listed below and keep
+their own terms.
Third-party components in Bridgeplay
------------------------------------
Dobby (https://github.com/jmpews/Dobby, commit 5dfc8546), the hooking library
linked into notproton.dylib, is licensed under the Apache License 2.0. Full
-text: LICENSE.dobby.
+text: LICENSE.dobby. Dobby has no NOTICE file to reproduce.
Sparkle 2.10.0 (https://github.com/sparkle-project/Sparkle), embedded in the app
as Sparkle.framework for updates, is licensed under the MIT license together
@@ -61,14 +64,47 @@ All files above are in app/Sources/BridgeplayApp/Resources/. The engine's ntdll
is patched at setup with detours built from ntdll-patch/ (detour*.bin in the
same folder). nvapi64-shim.dll is Bridgeplay's own code, built from nvapi-shim/.
+Shipped in the one-click installer (Bridgeplay-Installer.zip)
+-------------------------------------------------------------
+
+Besides the app, the installer carries these unmodified archives, so a Mac can set
+up without downloading them. The app installs the same archives (pinned by sha256
+in app/Sources/BridgeplayApp/Model/FreeEngine*.swift) when they are not there.
+
+ WineCX runtime 4.7.3 (Libraries.tar.gz from
+ https://github.com/dappermint/winecx-gptk/releases/tag/runtime-v4.7.3):
+ Wine built from https://github.com/dappermint/winecx at
+ e0aa380780b73e20fabcfe78fd42713b94929a53, LGPL-2.1-or-later, with the
+ third-party libraries that runtime bundles under their own licenses.
+ DXMT (dxmt-e94c312.tar.gz, built from https://github.com/3Shain/dxmt at
+ e94c312f5c054263acf261cfa109edf13e757587; docs/DXMT.md), Copyright (c)
+ 2023-2026 Feifan He for CodeWeavers, LGPL-2.1-or-later.
+ DXVK-macOS 1.10.3 (dxvk-macOS-async-v1.10.3-20230507-repack-builtin.tar.gz from
+ https://github.com/Gcenx/DXVK-macOS/releases/tag/v1.10.3-20230507-repack),
+ zlib license.
+ Apple Game Porting Toolkit redistributables (gptk/: D3DMetal.framework and the
+ wine/ libraries from the toolkit's /redist directory), Apple software under
+ Apple's license, shipped as GPTK-License.rtf. Apple's license allows
+ distributing it "solely for non-commercial purposes" (section 2A(iii)), and
+ allows the Framework and Redistributables to be "distributed separately from
+ the Apple Software" (section 2C). The wine/ libraries are Apple's build of
+ Wine (LGPL-2.1-or-later); their source is the Wine source Apple publishes
+ for the Game Porting Toolkit, which Raymond Chin will also provide on request
+ under the offer below.
+
+The license texts of DXMT and DXVK ship next to these archives in the installer.
+
Written offer for source code: the Corresponding Source of each binary above is
the upstream source at the commit named above plus the patch or file named next
-to it, both of which are public: winecx at https://github.com/dappermint/winecx,
-Wine 11.15 at https://dl.winehq.org/wine/source/11.x/, and the patches in this
-repository (https://github.com/raymondchins/Bridgeplay). For at least three
-years after the last release that ships them, Raymond Chin will also provide
-that source on request, for no more than the cost of providing it; open an
-issue at https://github.com/raymondchins/Bridgeplay/issues.
+to it, all of which are public: winecx at https://github.com/dappermint/winecx,
+Wine 11.15 at https://dl.winehq.org/wine/source/11.x/, DXMT at
+https://github.com/3Shain/dxmt, DXVK-macOS at https://github.com/Gcenx/DXVK-macOS,
+and the patches in this repository (https://github.com/raymondchins/Bridgeplay).
+This offer covers every LGPL-licensed file Bridgeplay or its installer ships,
+including the unmodified WineCX runtime and DXMT above. For at least three years
+after the last release that ships them, Raymond Chin will also provide that source
+on request, for no more than the cost of providing it; open an issue at
+https://github.com/raymondchins/Bridgeplay/issues.
NotProton-WineHQ licensing
==========================
@@ -116,8 +152,8 @@ These third party files carry their original notices from the project authors:
steam-shim/jsoncpp.cpp JsonCpp, public domain / MIT (header)
steam-shim/json/json.h JsonCpp, public domain / MIT (header)
steam-shim/json/json-forwards.h JsonCpp, public domain / MIT (header)
- vendor/cJSON.c cJSON, MIT (header)
- vendor/cJSON.h cJSON, MIT (header)
+ vendor/cJSON.c cJSON 1.7.19, MIT (header)
+ vendor/cJSON.h cJSON 1.7.19, MIT (header)
The WineCX engine gets an x86_64 SDL2 from the app bundle, for controller support
in winebus.so (docs/WINECX.md):
diff --git a/README.md b/README.md
index f516278..b7988a0 100644
--- a/README.md
+++ b/README.md
@@ -92,7 +92,7 @@ Bridgeplay runs inside the native macOS Steam client and registers itself as a S
- **Graphics:** Apple's Game Porting Toolkit 4.0 beta 3 (D3DMetal). It is not stored in this repository; the installer ships its redistributables under Apple's non-commercial license (see Install). DXMT and DXVK are available for games that prefer them.
- **Extras:** NVAPI/NGX routing for DLSS on MetalFX, in-process frame generation on `CAMetalLayer`, per-game Game Mode, Retina back buffers and a controller layer for HID pads.
-Building from source: see [docs/DEVELOPING.md](docs/DEVELOPING.md) and [docs/BUILD-LOCAL.md](docs/BUILD-LOCAL.md). The one-click installer lives in [`installer/`](installer/) and is packaged by `scripts/package-installer.sh`.
+Building from source: see [docs/DEVELOPING.md](docs/DEVELOPING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/BUILD-LOCAL.md](docs/BUILD-LOCAL.md). The one-click installer lives in [`installer/`](installer/) and is packaged by `scripts/package-installer.sh`.
## Credits
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..65cc791
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,31 @@
+# Security
+
+Bridgeplay loads code into the Steam client and into games, re-signs Steam, and updates
+itself with a signed Sparkle feed. Please report anything that could let someone else run
+code through it, read Steam data, or ship a bad update.
+
+## Reporting
+
+Report privately through GitHub: **Security › Report a vulnerability** on
+https://github.com/raymondchins/Bridgeplay/security. Please don't open a public issue for a
+security problem.
+
+Include what you found, how to reproduce it, and which Bridgeplay version (Status page) and
+macOS version you used. You will get a reply within a week. Fixes ship as a normal Sparkle
+update, and the release notes credit you unless you prefer not.
+
+## Scope
+
+In scope: the app, `notproton.dylib` and the run script, the installer, the update feed and
+the shipped Wine patches.
+
+Out of scope: Steam, Wine/WineCX, DXMT, DXVK and Apple's Game Porting Toolkit themselves;
+report those upstream. Anything that needs an attacker who already runs code as your macOS
+user is a hardening request, not a vulnerability, but it is still welcome as an issue.
+
+## Known trade-offs
+
+- Bridgeplay is ad hoc signed and not notarized, and the installer removes the download's
+ quarantine flag. Download it only from https://bridgeplay.dev or the GitHub releases.
+- Steam is re-signed so it can load Bridgeplay, which removes Valve's hardened runtime.
+- Updates are verified with an EdDSA signature (`SUPublicEDKey`) before they are installed.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..1179ba4
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,52 @@
+# Architecture
+
+Bridgeplay has three moving parts: an app that sets everything up, a dylib that runs inside
+the Mac Steam client, and patched Wine engines that run the games. This page says what
+each folder is, which process it ends up in, and where new code belongs.
+
+## Components
+
+| Folder | Runs in | How it gets there |
+|---|---|---|
+| `app/` | The Bridgeplay app (SwiftUI, Sparkle updates); also a CLI (`--install-into-steam`, `--setup-winecx`, `--remove-everything`) | `installer/Install.command` copies it to `/Applications` |
+| `dylib/` (`notproton.dylib`: hooks, signature resolver, Steam web UI patches, compat tool registration, the run script `feats/compat_run.sh`) | The Steam client (`steam_osx`) and Steam Helper | The app copies it into `Steam.app/Contents/MacOS`, sets `DYLD_INSERT_LIBRARIES` in Steam's Info.plist and re-signs Steam |
+| `signatures/macos.arm64/` | Data the dylib reads to find Steam functions | Copied to Application Support; the highest-numbered file wins |
+| `lsteamclient/`, `steam-shim/` | Wine: the steamclient bridge and the Windows `steam.exe` | Built against the Wine tree in `bridge/`, shipped in the app payload, put into runners |
+| `ntdll-patch/` | Detours patched into the engine's `ntdll.dll` | Prebuilt `detour*.bin` in the app's Resources, applied by `NtdllPatcher.swift` |
+| `win32u-patch/`, `winemac-patch/`, `winebus-patch/`, `winecoreaudio-patch/`, `wined3d-patch/`, `ws2_32-patch/`, `ngx-signer-patch/` | Replacement Wine files inside the engine | Rebuilt binaries are committed in the app's Resources and copied over the engine at setup |
+| `nvapi-shim/` | Windows `nvapi64.dll` in the game (reports an NVIDIA driver so games offer DLSS) | Prebuilt in the app's Resources |
+| `overlay-shim/` | Mac dylib in the game process (HDR, Metal 4, frame generation) | `DYLD_INSERT_LIBRARIES` from the run script, or loaded by lsteamclient |
+| `controllers/dualsense/`, `controllers/steam-input/` | Bridge and rumble dylibs in the game, plus a `broker` process on loopback UDP | `DYLD_INSERT_LIBRARIES` from the run script |
+| `native-launch/` (`np-native`), `native-shim/` (`libnp_gamepad.dylib`) | Native Mac games | A Steam launch option re-execs the game with the shim inserted |
+| `helpers/` | Small CLIs the dylib and run script call (`iconmaker`, `appinfo`, `game-host`) | Application Support |
+| `gamefixes/` | Per-game defaults read by the run script | Bundled in the app payload and the installer |
+| `installer/` | `Install.command` and its config | Zipped by `scripts/package-installer.sh` |
+| `bridge/`, `scripts/`, `fonts/`, `compat/`, `vendor/` | Build tooling, the Proton font build, the compatibility table, vendored code | Build time only |
+
+## How it fits together
+
+1. The app patches Steam, clones and patches the Wine runners, and re-applies its patch
+ when Steam updates itself.
+2. Steam starts with the dylib, which registers the `bridgeplay-proton-*` compatibility
+ tools, so Windows games show Install and Play like Mac games.
+3. Steam launches a Windows game through the `run` script, which picks the engine
+ (WineCX with D3DMetal, DXMT or DXVK), applies the game's gamefixes and injects the
+ game-side shims.
+
+## Where new code goes
+
+| Change | Folder |
+|---|---|
+| Setup, Status, prefixes, updates | `app/` |
+| Something Steam does or shows | `dylib/` (and `signatures/` when it needs a new Steam function) |
+| How a game is launched, per-game environment | `dylib/feats/compat_run.sh`, `gamefixes/` |
+| A fix inside Wine | The matching `*-patch/` folder: a patch plus a README with the build recipe and sha256 pins, then the rebuilt binary in the app's Resources |
+| Something inside the game process on the Mac side | `overlay-shim/`, `controllers/` |
+| Native Mac games | `native-launch/`, `native-shim/` |
+
+## Naming
+
+Runtime identifiers kept their NotProton names (`notproton.dylib`, `NOTPROTON_*` variables,
+`com.notproton.*` signing identifiers, the `NotProtonVersion` plist key); renaming them
+would need another migration. Everything on disk uses `bridgeplay` since 3.0.0; see
+[RELEASING.md](RELEASING.md#the-300-rename).
diff --git a/docs/BUILD-LOCAL.md b/docs/BUILD-LOCAL.md
index 3031c0d..d8d10a9 100644
--- a/docs/BUILD-LOCAL.md
+++ b/docs/BUILD-LOCAL.md
@@ -9,9 +9,10 @@ targets, in the same order, as `.github/workflows/app.yml`.
exports `DEVELOPER_DIR` for its own process, so the Command Line Tools can stay the
active developer dir and you don't need `xcode-select`. To use a different Xcode, set
`DEVELOPER_DIR` yourself.
-- Homebrew: `brew install cmake mingw-w64 bison flex` (bison must be Homebrew's, at
- `/opt/homebrew/opt/bison/bin`). `shellcheck` and `node` are optional; without them the
- lint and panel checks skip.
+- Homebrew: `brew install cmake mingw-w64 bison flex fontforge gpatch` (bison must be
+ Homebrew's, at `/opt/homebrew/opt/bison/bin`), and the font tools:
+ `python3 -m pip install fonttools brotli`. `shellcheck` and `node` are optional; without
+ them the lint and panel checks skip.
- Network on the first run: Dobby, Wine 11.15 (gitlab.winehq.org), the Proton tarball
and Sparkle.
@@ -19,7 +20,7 @@ targets, in the same order, as `.github/workflows/app.yml`.
```sh
scripts/build-local.sh # build only
-scripts/build-local.sh --checks # build, then every CI check target and the Swift tests
+scripts/build-local.sh --checks # build, then `make ci-checks` (the list CI runs) and the Swift tests
```
`JOBS=n` overrides the parallelism (default: `hw.ncpu`). Every phase also writes its
@@ -51,6 +52,9 @@ At the end the script prints the version (from `dylib/version.h`: `make app` wri
| checks (`--checks`) | about 3m20s | 3m20s |
| total | about 15m, about 18m with checks | 27s, 3m47s with checks |
+A `fonts` phase (the Proton font build, needs fontforge and the font tools) also runs; it is
+not in the table because it was added after these timings.
+
The cold bridge phase breaks down roughly as follows:
| Step | Time |
diff --git a/docs/DEVELOPING.md b/docs/DEVELOPING.md
index bc6eb64..047c69a 100644
--- a/docs/DEVELOPING.md
+++ b/docs/DEVELOPING.md
@@ -1,102 +1,89 @@
-# Bridgeplay developer guide
+# Developing Bridgeplay
-> **This is a fork of [NotProton](https://github.com/NotProtonNot/NotProton).**
->
-> I built this for my girlfriend. She only plays occasionally, maybe once or twice a month, and
-> buying a CrossOver license for that just isn't worth it for us. So this fork adds a free WineHQ
-> engine that runs without CrossOver.
->
-> I'll keep maintaining it until someone asks me to stop. That said, don't expect it to stay up to
-> date: I only work on it when I find the time and motivation, or when something breaks. This fork
-> may lag far behind upstream.
->
-> **If you actually want to support the developers**, please read
-> [NotProtonNot/NotProton#37](https://github.com/NotProtonNot/NotProton/issues/37) first. It explains
-> why the main project chose not to support WineHQ. If you can afford it, consider using the
-> upstream project with CrossOver as intended.
->
-> This fork is not affiliated with or endorsed by the NotProton developers, the Wine project
-> (WineHQ), CodeWeavers or Valve. "Wine" and "CrossOver" are trademarks of their respective
-> owners and are only used here to describe what the software works with. Please report problems
-> with this fork [here](https://github.com/raymondchins/Bridgeplay/issues), not upstream.
->
-> Modified by Leon Seemann, 2026. Like upstream, this fork is licensed under the GPLv3; see
-> [NOTICE](NOTICE) for details.
+How to build Bridgeplay, try a change inside Steam, and run the checks. For what each folder
+is and where new code goes, read [ARCHITECTURE.md](ARCHITECTURE.md). The inherited upstream
+README (NotProton, NotProton-WineHQ) is kept in [UPSTREAM.md](UPSTREAM.md).
----
+## What you need
-## NotProton (upstream)
+| You want to | You need |
+|---|---|
+| Lint shell scripts, check the run script | Any OS with shellcheck 0.11.0: `make scriptcheck runcheck` |
+| Build the app, the dylib, the Wine bridge; run the C and Swift tests | An Apple Silicon Mac, macOS 26 or later, Xcode 27 (`/Applications/Xcode-beta.app` or `/Applications/Xcode.app`), Homebrew |
+| Try a change in Steam, run games | The above, plus Steam installed and Apple's Game Porting Toolkit (see the app's Setup Assistant) |
+| Package the installer or publish a release | The maintainer's Mac (engine cache, GPTK, Sparkle key in the keychain); see [RELEASING.md](RELEASING.md) |
-_From upstream's README._
+Homebrew packages:
-NotProton enables the Steam Play experience from Linux Steam in the macOS Steam client.
+```sh
+brew install cmake mingw-w64 bison flex fontforge gpatch shellcheck node
+python3 -m pip install fonttools brotli
+```
-This is done by forcibly enabling the Steam Play functionality in macOS Steam (which is
-present and inert) as well as by porting some components of Valve's Proton to macOS.
+`/opt/homebrew` is assumed (Homebrew's bison and the Wine tree setup look there). Without
+`shellcheck` or `node` the lint and panel checks skip.
-This tool is intended to be used with the stable Steam Client (version 1791918634) as well as the beta Steam Client (version 1791686101) paired with **CrossOver 26.3 or CrossOver [Preview](https://www.codeweavers.com/preview)
-20261006 / 20260821 / 20261015**, with more supported versions to come.
+## Build
-**NTFS file systems/drivers are not currently supported.**
+```sh
+scripts/build-local.sh # full build: dylib, shims, helpers, Wine bridge, app
+scripts/build-local.sh --checks # the same, then `make ci-checks` and the Swift tests
+```
-Supporting specifically CrossOver is a design goal of this project. Better support for modifying CrossOver (using custom builds of DXMT/patched D3DMetal/MacGameVideoFix) will come in a future update, but support for alternatives to CrossOver itself is not planned.
+A cold build takes about 15 minutes, almost all of it the Wine bridge; later builds take
+under a minute. Outputs, caches and timings are in [BUILD-LOCAL.md](BUILD-LOCAL.md).
-Both the FEX and the Rosetta versions are supported. I recommend using the FEX version of the
-Preview 20261006, as it includes both the FEX version as well as the Rosetta one.
+If a tool fails with a long error, read it before pasting it anywhere: some Xcode tools
+print the whole shell environment, secrets included, when they fail to launch.
-I further recommend going into Steam Settings - Compatibility and selecting the Rosetta version as your default compatibility tool. You can select FEX on a per game basis by right clicking a game in Steam, going into Properties - Compatibility and selecting FEX there.
+## Try a change in Steam
-If a game has a native macOS version as well as a Windows one, Steam will download the macOS version. To override this behavior, right click on the game, select Properties, select Compatibility. Enable 'Force the use of a specific Steam Play compatibility tool'. Select whichever version of CrossOver you want to do use. That will make Steam download the Windows version. Unchecking the 'Force the use...' box or selecting 'No Compatibility Tool' in the drop down list will revert to the macOS version of the game, with the specifics there varying based on your Steam version.
+1. Quit Steam.
+2. `make deploy` installs the dylib, the signature database, fonts and helpers into
+ `~/Library/Application Support/bridgeplay/`. For app changes, run the built
+ `build/Bridgeplay.app` and press Install on its Status page.
+3. Start Steam and launch a game.
-**Valve Anti-Cheat is not supported.** Proton itself does not support VAC in Valve titles; Valve ships native Linux ports instead. VAC titles will launch in Insecure Mode and will not allow matchmaking.
+Logs:
-## Free Wine engine (no CrossOver needed)
+| Log | Where |
+|---|---|
+| Steam side (dylib) | `~/Library/Application Support/bridgeplay/bridgeplay.log` |
+| One game's launch and Wine output | `bridgeplay-run.log`, `bridgeplay-wine.log`; Prefixes page › a game › Open Log |
+| The app | Setup › Reveal Log in Finder |
-Bridgeplay can also run entirely on free software. Under Compatibility Tool, **Download & Set Up**
-fetches the WineHQ 11.15 macOS build from [Gcenx/macOS_Wine_builds](https://github.com/Gcenx/macOS_Wine_builds)
-(hash pinned), unpacks it into `~/Library/Application Support/bridgeplay/engines/` and sets the
-compatibility tool up from it exactly like a CrossOver copy. No CrossOver license is involved; the
-license check is skipped only for loaders whose hash pins the free build.
+To try the Setup Assistant without changing anything:
+`app/.build/debug/BridgeplayApp --setup-preview [--fresh] [--step N]` (debug builds only).
+If it stops with `Library not loaded: @rpath/Sparkle.framework`, start it with
+`DYLD_FRAMEWORK_PATH=app/.build/out/Products/Debug`.
-11.15 is chosen because it is the Wine the bridge components (`lsteamclient`, `steam.exe`) are built
-against. Differences from CrossOver to be aware of:
+## Checks
-- It is an x86_64 build and runs under Rosetta 2, like the Rosetta build of CrossOver.
-- Direct3D 10/11 goes through [DXMT](https://github.com/3Shain/dxmt) (master `e94c312`, LGPL-2.1+,
- see `docs/DXMT.md`), downloaded and pinned alongside Wine, which translates straight to Metal.
- Wine's own wined3d cannot reach feature level 11 on macOS OpenGL. D3DMetal is Apple's and needs
- CrossOver's Wine changes, so this engine does not use it; the WineCX engine can, with a Game
- Porting Toolkit you supply (`docs/WINECX.md`).
-- DXMT needs macdrv functions upstream Wine hides; Bridgeplay ships a rebuilt `winemac.so`
- that exports them (see `winemac-patch/`).
-- D3D 12 has no fast path; vkd3d over the bundled MoltenVK is limited.
-- WineHQ has no msync/esync, so CPU-heavy games can run slower than under CrossOver or Sikarugir.
-- The graphics backend options in the Steam panel have no effect on this engine.
+| Command | Runs |
+|---|---|
+| `make ci-checks` | Every check CI runs (the list lives in the Makefile; `.github/workflows/app.yml` and `build-local.sh --checks` both call it) |
+| `make scriptcheck runcheck` | shellcheck over the build scripts and the run script (also runs on Linux) |
+| `make app-tests` | The Swift tests |
+| `make <name>check` | One suite; see `make ci-checks` for the names |
-To support another WineHQ build, run `ntdll-patch/resolve.py` against its Wine tree, build the
-payloads with `ntdll-patch/build.sh` / `build32.sh`, and add the hashes to `SupportedRunners`,
-`NtdllPatcher.byBuild` and `FreeEngine`.
+Run the checks your change touches before opening a pull request, and say which ones in
+the PR.
-Please read NOTICE for license information.
+## Scripts that are not part of the build
-Please open issue reports with any issues. PRs are welcome and encouraged.
+| Script | Use |
+|---|---|
+| `scripts/np-test-game.sh`, `np-test-batch.sh` | Launch a game (or a list) with Bridgeplay and record the result under `compat/runs/` |
+| `scripts/np-inventory.py`, `np-seed-games.py`, `np_lookup.py`, `compat-table.py` | Build and query `compat/games.json` and the compatibility table |
+| `scripts/steam-launch-options.py` | Read or set a game's Steam launch options |
+| `scripts/sync-upstream.sh` | Merge NotProton upstream and bump the minor version |
+| `scripts/update-gamecontrollerdb.sh` | Refresh the SDL controller mappings at a pinned commit |
-There are many people who worked on similar ideas, similar projects. I did not base NotProton on their work, but I still want to
-give thanks to the people who came before me:
+## Conventions
-[Nat Brown](https://github.com/natbro) made [Kaon](https://github.com/natbro/kaon), which is similar in goals to NotProton.
-
-mont127's [Neutron](https://github.com/mont127/Neutron) is also a similar idea, but implemented differently.
-
-[Gio](https://github.com/giodotblue) was working enabling Steam Play inside of Steam on macOS prior to the release of NotProton itself.
-I would have done things differently had I been aware of that.
-
-Thanks to everyone who has positively contributed to macOS gaming.
-
-Developer Notes:
-
-As far as the source structure goes, the macOS app itself is located in the ```app``` folder. The core logic is in ```dylib```.
-```lsteamclient``` is a macOS port of Valve's lsteamclient. ```steam-shim```is a port of Valve's
-steam-helper from Proton 9.0. ntdll-patch patches the copy of CrossOver that the app
-makes/places in the ```~/Library/Application Support/bridgeplay/runners/``` folder so that
-lsteamclient is loaded.
+- Commits follow Conventional Commits: `feat(scope):`, `fix(scope):`, `docs:`, `chore(release):`.
+- Comments explain why, where the code is not obvious. Match the style of the file you edit.
+- Shipped binaries in `app/Sources/BridgeplayApp/Resources/` are built from the recipe in
+ their patch folder's README; a PR that changes one says how it was rebuilt.
+- Runtime names (`notproton.dylib`, `NOTPROTON_*`, `com.notproton.*`) stay as they are:
+ renaming them would need another migration. Paths and logs use `bridgeplay`.
diff --git a/docs/STATE.md b/docs/STATE-2026-10-10.md
similarity index 98%
rename from docs/STATE.md
rename to docs/STATE-2026-10-10.md
index bdd9162..5962deb 100644
--- a/docs/STATE.md
+++ b/docs/STATE-2026-10-10.md
@@ -1,4 +1,4 @@
-# State (2026-10-10)
+# State on 2026-10-10 (historical log; superseded)
Branch `integrate` = working fork state; nothing pushed except the `dxmt-e94c312` release asset.
diff --git a/docs/UPSTREAM.md b/docs/UPSTREAM.md
new file mode 100644
index 0000000..74dfc45
--- /dev/null
+++ b/docs/UPSTREAM.md
@@ -0,0 +1,104 @@
+# Upstream README (NotProton-WineHQ), kept for history
+
+The current developer guide is [DEVELOPING.md](DEVELOPING.md).
+
+> **This is a fork of [NotProton](https://github.com/NotProtonNot/NotProton).**
+>
+> I built this for my girlfriend. She only plays occasionally, maybe once or twice a month, and
+> buying a CrossOver license for that just isn't worth it for us. So this fork adds a free WineHQ
+> engine that runs without CrossOver.
+>
+> I'll keep maintaining it until someone asks me to stop. That said, don't expect it to stay up to
+> date: I only work on it when I find the time and motivation, or when something breaks. This fork
+> may lag far behind upstream.
+>
+> **If you actually want to support the developers**, please read
+> [NotProtonNot/NotProton#37](https://github.com/NotProtonNot/NotProton/issues/37) first. It explains
+> why the main project chose not to support WineHQ. If you can afford it, consider using the
+> upstream project with CrossOver as intended.
+>
+> This fork is not affiliated with or endorsed by the NotProton developers, the Wine project
+> (WineHQ), CodeWeavers or Valve. "Wine" and "CrossOver" are trademarks of their respective
+> owners and are only used here to describe what the software works with. Please report problems
+> with this fork [here](https://github.com/raymondchins/Bridgeplay/issues), not upstream.
+>
+> Modified by Leon Seemann, 2026. Like upstream, this fork is licensed under the GPLv3; see
+> [NOTICE](NOTICE) for details.
+
+---
+
+## NotProton (upstream)
+
+_From upstream's README._
+
+NotProton enables the Steam Play experience from Linux Steam in the macOS Steam client.
+
+This is done by forcibly enabling the Steam Play functionality in macOS Steam (which is
+present and inert) as well as by porting some components of Valve's Proton to macOS.
+
+This tool is intended to be used with the stable Steam Client (version 1791918634) as well as the beta Steam Client (version 1791686101) paired with **CrossOver 26.3 or CrossOver [Preview](https://www.codeweavers.com/preview)
+20261006 / 20260821 / 20261015**, with more supported versions to come.
+
+**NTFS file systems/drivers are not currently supported.**
+
+Supporting specifically CrossOver is a design goal of this project. Better support for modifying CrossOver (using custom builds of DXMT/patched D3DMetal/MacGameVideoFix) will come in a future update, but support for alternatives to CrossOver itself is not planned.
+
+Both the FEX and the Rosetta versions are supported. I recommend using the FEX version of the
+Preview 20261006, as it includes both the FEX version as well as the Rosetta one.
+
+I further recommend going into Steam Settings - Compatibility and selecting the Rosetta version as your default compatibility tool. You can select FEX on a per game basis by right clicking a game in Steam, going into Properties - Compatibility and selecting FEX there.
+
+If a game has a native macOS version as well as a Windows one, Steam will download the macOS version. To override this behavior, right click on the game, select Properties, select Compatibility. Enable 'Force the use of a specific Steam Play compatibility tool'. Select whichever version of CrossOver you want to do use. That will make Steam download the Windows version. Unchecking the 'Force the use...' box or selecting 'No Compatibility Tool' in the drop down list will revert to the macOS version of the game, with the specifics there varying based on your Steam version.
+
+**Valve Anti-Cheat is not supported.** Proton itself does not support VAC in Valve titles; Valve ships native Linux ports instead. VAC titles will launch in Insecure Mode and will not allow matchmaking.
+
+## Free Wine engine (no CrossOver needed)
+
+Bridgeplay can also run entirely on free software. Under Compatibility Tool, **Download & Set Up**
+fetches the WineHQ 11.15 macOS build from [Gcenx/macOS_Wine_builds](https://github.com/Gcenx/macOS_Wine_builds)
+(hash pinned), unpacks it into `~/Library/Application Support/bridgeplay/engines/` and sets the
+compatibility tool up from it exactly like a CrossOver copy. No CrossOver license is involved; the
+license check is skipped only for loaders whose hash pins the free build.
+
+11.15 is chosen because it is the Wine the bridge components (`lsteamclient`, `steam.exe`) are built
+against. Differences from CrossOver to be aware of:
+
+- It is an x86_64 build and runs under Rosetta 2, like the Rosetta build of CrossOver.
+- Direct3D 10/11 goes through [DXMT](https://github.com/3Shain/dxmt) (master `e94c312`, LGPL-2.1+,
+ see `docs/DXMT.md`), downloaded and pinned alongside Wine, which translates straight to Metal.
+ Wine's own wined3d cannot reach feature level 11 on macOS OpenGL. D3DMetal is Apple's and needs
+ CrossOver's Wine changes, so this engine does not use it; the WineCX engine can, with a Game
+ Porting Toolkit you supply (`docs/WINECX.md`).
+- DXMT needs macdrv functions upstream Wine hides; Bridgeplay ships a rebuilt `winemac.so`
+ that exports them (see `winemac-patch/`).
+- D3D 12 has no fast path; vkd3d over the bundled MoltenVK is limited.
+- WineHQ has no msync/esync, so CPU-heavy games can run slower than under CrossOver or Sikarugir.
+- The graphics backend options in the Steam panel have no effect on this engine.
+
+To support another WineHQ build, run `ntdll-patch/resolve.py` against its Wine tree, build the
+payloads with `ntdll-patch/build.sh` / `build32.sh`, and add the hashes to `SupportedRunners`,
+`NtdllPatcher.byBuild` and `FreeEngine`.
+
+Please read NOTICE for license information.
+
+Please open issue reports with any issues. PRs are welcome and encouraged.
+
+There are many people who worked on similar ideas, similar projects. I did not base NotProton on their work, but I still want to
+give thanks to the people who came before me:
+
+[Nat Brown](https://github.com/natbro) made [Kaon](https://github.com/natbro/kaon), which is similar in goals to NotProton.
+
+mont127's [Neutron](https://github.com/mont127/Neutron) is also a similar idea, but implemented differently.
+
+[Gio](https://github.com/giodotblue) was working enabling Steam Play inside of Steam on macOS prior to the release of NotProton itself.
+I would have done things differently had I been aware of that.
+
+Thanks to everyone who has positively contributed to macOS gaming.
+
+Developer Notes:
+
+As far as the source structure goes, the macOS app itself is located in the ```app``` folder. The core logic is in ```dylib```.
+```lsteamclient``` is a macOS port of Valve's lsteamclient. ```steam-shim```is a port of Valve's
+steam-helper from Proton 9.0. ntdll-patch patches the copy of CrossOver that the app
+makes/places in the ```~/Library/Application Support/bridgeplay/runners/``` folder so that
+lsteamclient is loaded.
diff --git a/vendor/README.md b/vendor/README.md
index 27e3966..3073f42 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -2,7 +2,14 @@
## cJSON
-`cJSON.c` and `cJSON.h`, MIT licensed, used by the signature database loader.
+`cJSON.c` and `cJSON.h`, version 1.7.19 (`CJSON_VERSION_*` in `cJSON.h`), MIT licensed, used
+by the signature database loader. When updating, compare with the current cJSON release and
+its security fixes.
+
+## JsonCpp
+
+`steam-shim/jsoncpp.cpp` and `steam-shim/json/`, the amalgamated JsonCpp 1.6.5
+(`JSONCPP_VERSION_STRING`), public domain / MIT, used by steam-shim.
## Dobby
diff --git a/win32u-patch/README.md b/win32u-patch/README.md
new file mode 100644
index 0000000..c39d835
--- /dev/null
+++ b/win32u-patch/README.md
@@ -0,0 +1,18 @@
+# win32u-patch
+
+`patch-driver-version.sh` makes `app/Sources/BridgeplayApp/Resources/win32u-winecx-11.17.so`
+from runtime 4.7.3's `lib/wine/x86_64-unix/win32u.so` (winecx `e0aa380`). It is a binary edit,
+not a source patch: `driver_vendor_to_version()` reports NVIDIA as `35.0.15.6094` (560.94) in
+the display class key's `DriverVersion`, which games that read it (Deadlock) call out of date,
+hiding DLSS. The script replaces that string and the DirectX key's QWORD `DriverVersion`
+(`35.0.15.8180`) with `35.0.15.9541` (595.41), the version `nvapi-shim` reports, and signs the
+file ad hoc with its original identifier. Keep it in step with `wined3d-patch` and `nvapi-shim`.
+
+```sh
+win32u-patch/patch-driver-version.sh "<runtime 4.7.3>/lib/wine/x86_64-unix/win32u.so"
+```
+
+The script refuses any input other than runtime 4.7.3's `win32u.so` (sha256
+`5ea985227c89b57e5f48d7422059db933d32a213e172577d68e4415d6f7c2a71`). Output sha256
+`b012382d09b2ff1b3c0750d93867f72dd04a7c902bc4179be406b6c558ab162d`, pinned in
+`FreeEngineWinecx.swift`.
diff --git a/wined3d-patch/README.md b/wined3d-patch/README.md
new file mode 100644
index 0000000..4c4eb02
--- /dev/null
+++ b/wined3d-patch/README.md
@@ -0,0 +1,19 @@
+# wined3d-patch
+
+`winecx-driver-version.patch` changes `wined3d_driver_info_init()` in `dlls/wined3d/directx.c`
+(the PE half). When `NOTPROTON_DRIVER_VERSION` holds a four-part version such as
+`32.0.15.9541`, it replaces the driver version wined3d reports, which for a current NVIDIA GPU
+is the GeForce 8 era `31.0.13.4052` (340.52). Games behind the NVIDIA identity D3DMetal is
+given read it through d3d9; Deadlock (Source 2) warns of an old driver and turns off
+asynchronous shader creation. Without the variable, or with a malformed value, nothing changes.
+The same version is reported by `win32u-patch` and `nvapi-shim`; keep the three in step.
+
+Build: against winecx `e0aa380` (runtime 4.7.3), in a tree configured as in
+`winemac-patch/README.md`, with the tree's own rule
+`make dlls/wined3d/x86_64-windows/wined3d.dll`, then `x86_64-w64-mingw32-strip --strip-debug`
+(as for `ws2_32-patch`, see `docs/WINECX.md`, Own host name).
+
+Output: `app/Sources/BridgeplayApp/Resources/wined3d-winecx-11.17.dll`, installed at
+`lib/wine/x86_64-windows/wined3d.dll`, sha256
+`9298c83d927b3b80d0fa36f52bb5f2ecd60ec4daffff3c93d9b080293e59dfe9`
+(pinned in `FreeEngineWinecx.swift`).