Skip to content

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

docs: add AGENTS.md and CLAUDE.md (#1)

Raystorms78fb3ebcf8f1
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a2f84b3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,104 @@
+# Bridgeplay
+
+Bridgeplay runs Windows-only Steam games on Apple Silicon Macs inside the native macOS Steam
+client. It turns on Steam Play in Mac Steam and runs games through CodeWeavers' WineCX with
+Apple's Game Porting Toolkit (D3DMetal), DXMT or DXVK. It is a GPL-3.0 fork of
+[NotProton](https://github.com/NotProtonNot/NotProton). The user-facing overview is in
+[README.md](README.md). `docs/DEVELOPING.md` is still the upstream README, so don't take build
+steps from it.
+
+## Where code lives
+
+| Path | What it is | Runs in |
+|---|---|---|
+| `app/` | SwiftUI app and CLI (Swift package, Sparkle updates). Sets up Steam, engines and runners. Tests are in `app/Tests/` | Its own process |
+| `dylib/` | `notproton.dylib`: hooks, Steam web UI patches, compat tool registration, and the game `run` script (`dylib/feats/compat_run.sh`). See [dylib/AGENTS.md](dylib/AGENTS.md) | Steam client and Steam Helper |
+| `signatures/macos.arm64/` | Byte signatures the dylib resolves per Steam build | Read by the dylib |
+| `lsteamclient/`, `steam-shim/`, `bridge/` | Proton's steamclient bridge and `steam.exe`, built against the Wine tree that `bridge/` sets up | Wine |
+| `ntdll-patch/` | Detours patched into the engine's `ntdll.dll`; the prebuilt `detour*.bin` live in `app/Sources/BridgeplayApp/Resources/` | Wine |
+| `*-patch/` (win32u, winemac, winebus, winecoreaudio, wined3d, ws2_32, ngx-signer) | Patches for single WineCX/WineHQ files. The rebuilt binaries are committed in `app/Sources/BridgeplayApp/Resources/` | Wine |
+| `nvapi-shim/` | Windows `nvapi64.dll` that lets games use DLSS (answered by MetalFX) | Wine |
+| `overlay-shim/` | HDR, Metal 4 and frame generation | Game process |
+| `controllers/` | DualSense Bluetooth bridge and Steam Input rumble | Game process, plus a broker process |
+| `native-launch/`, `native-shim/` | Launch wrapper and gamepad shim for native Mac games | Native game process |
+| `helpers/` | Small tools the dylib and run script call (icons, app info, game host, shortcuts) | Command line |
+| `gamefixes/` | Per-game defaults, `<appid>.conf`. Format: [docs/GAMEFIXES.md](docs/GAMEFIXES.md) | Read by the run script |
+| `installer/`, `scripts/` | The `Install.command` installer, plus build, test and release scripts | — |
+| `fonts/`, `vendor/` | Proton's font build; vendored cJSON (Dobby is cloned, see [vendor/README.md](vendor/README.md)) | — |
+| `compat/` | Game compatibility list, generated from `compat/games.json`. Don't edit `compat/README.md` by hand | — |
+
+More docs: [docs/WINECX.md](docs/WINECX.md) (engine, patch build recipes and pins),
+[docs/DXMT.md](docs/DXMT.md), [docs/dualsense-bluetooth.md](docs/dualsense-bluetooth.md),
+[docs/game-mode-host.md](docs/game-mode-host.md) and [docs/RELEASING.md](docs/RELEASING.md).
+
+## Build and check
+
+A full build needs an Apple Silicon Mac with Xcode 27. Prerequisites, caches and timings
+are in [docs/BUILD-LOCAL.md](docs/BUILD-LOCAL.md). The workflows run only `make scriptcheck`
+and `make runcheck` (shellcheck 0.11.0) on Linux; everything else runs on macOS.
+
+```sh
+scripts/build-local.sh # full build in CI order; --checks also runs checks and Swift tests
+```
+
+Or build step by step, in the order `.github/workflows/app.yml` uses:
+
+```sh
+git clone https://github.com/jmpews/Dobby.git vendor/dobby
+git -C vendor/dobby checkout 5dfc8546954ce3b3198132ab13fddb89ee92cdd7 # DOBBY_COMMIT in app.yml
+make dobby
+make all overlay-shim iconmaker appinfo
+make bridge # Wine tree, lsteamclient, steam.exe (slow on first run)
+make fonts # needs fontforge, gpatch, afdko, fonttools
+make app-payload app # out/Bridgeplay.app
+```
+
+The checks the workflows run (`make -s <target>`):
+
+- **Lint:** `scriptcheck`, `runcheck`
+- **App:** `mincheck`, `l10ncheck`, `app-tests` (the Swift tests)
+- **C and shell suites:** `sigcheck`, `callscheck`, `webpatch-fixtures`, `peicon-fixtures`,
+ `panel-behavior`, `spawn-env`, `activatecheck`, `compatcheck`, `compatsvc-check`,
+ `shortcutcheck`, `launch-shell`, `envcheck`, `buildcheck`, `settingscheck`, `routecheck`,
+ `bridgecheck`, `gamedrivecheck`, `launchercheck`, `seedcheck`, `gamefixescheck`
+- **Hardware-free device checks:** `game-host-check`, `dualsense-check`, `steam-rumble-check`
+
+`make tests-list` prints the test paths. A check whose tool or input is missing prints
+`skipped` and exits 0: that is not a pass. Install the tool, or say the check didn't run.
+
+To try a change against your own Steam, run `make deploy` after `make fonts`. It copies
+the dylib into `Steam.app` and installs the signatures, fonts and helpers into
+`~/Library/Application Support/bridgeplay/`; restart Steam afterwards. Logs go to
+`~/Library/Application Support/bridgeplay/bridgeplay.log`.
+
+## Rules
+
+- **Large changes:** open an issue first. Check closed issues and PRs for duplicate work.
+ Changes that belong upstream go to NotProton.
+- **PR descriptions** are written by the contributor in their own words. Don't generate one.
+- **Comments:** keep them short. Comment where the code is hard to follow, not where it is
+ obvious.
+- **Run the checks your change touches** before opening a PR.
+- **Licence:** contributions are GPL-3.0. Files under other licences are listed in
+ [NOTICE](NOTICE) and keep their terms.
+- **The hard parts interact in subtle ways:** code inside Steam, the run script,
+ lsteamclient, Wine patches and game saves. Design for several Steam accounts on one Mac,
+ several Steam library folders (including external drives), several macOS users sharing
+ one `/Applications/Steam.app`, and volumes that are case-sensitive or not APFS. The app
+ must not rewrite `Steam.app` or Steam's config files while Steam is running (Steam
+ rewrites `config.vdf` when it quits). Never lose a game's save or prefix data.
+- **Wine patches:** a patch change is not finished until the binary it produces is
+ rebuilt with the recipe in [docs/WINECX.md](docs/WINECX.md) or the patch folder's
+ README. Then update its sha256 pins (in `docs/WINECX.md` and
+ `app/Sources/BridgeplayApp/Model/FreeEngineWinecx.swift`) and its entry in
+ [NOTICE](NOTICE). Don't commit a binary without its patch.
+- **Legacy names stay:** existing installs depend on `notproton.dylib`, the `NOTPROTON_*`
+ variables, `com.notproton.*` identifiers and the fallback to the old `notproton` support
+ folders. Don't rename them. User-facing names are Bridgeplay's (`BRIDGEPLAY_*`).
+- **Localization:** user-facing app strings are localized (en, it, zh-Hans) in
+ `app/Sources/BridgeplayApp/Resources/Localization/Localizable.xcstrings`. `make l10ncheck`
+ checks them.
+- **Versions:** version bumps are separate `chore(release)` commits made with
+ `scripts/bump-version.sh`; see [docs/RELEASING.md](docs/RELEASING.md).
+- **Commits:** Conventional Commits, e.g. `feat(setup): …`, `fix(migration): …`,
+ `docs: …`.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/dylib/AGENTS.md b/dylib/AGENTS.md
new file mode 100644
index 0000000..3e5f127
--- /dev/null
+++ b/dylib/AGENTS.md
@@ -0,0 +1,28 @@
+# dylib/
+
+`notproton.dylib` is loaded into every Steam client on the Mac, through
+`DYLD_INSERT_LIBRARIES` in `Steam.app`'s Info.plist. A crash, hang or leak here takes Steam
+down for the user. The constructor in `core/loader.c` only does work in `steam_osx` and
+`Steam Helper`.
+
+- **Steam addresses** come from `signatures/macos.arm64/<steam build>.json`, resolved through
+ `resolver/`. If a signature doesn't resolve on a Steam build, the feature stays off; the
+ dylib must not guess an address. A new or renamed signature needs an entry in the
+ signature files and a passing `make sigcheck` and `make sigdb-fixtures`. `make anchorcheck`
+ checks the files against a real `steamclient.dylib`, so run it on a Mac with Steam.
+- **Child processes:** `hooks/hook_spawn.c` strips the insert from processes Steam starts,
+ so games and other apps don't inherit the dylib. Keep that true for any new spawn path
+ (`make spawn-env`).
+- **The run script** is `feats/compat_run.sh`. It is POSIX `sh`, runs once per game launch,
+ and is embedded into the dylib at build time (`embed_script.py` →
+ `out/generated/compat_run.h`), so run `make` after editing it.
+ - It reads settings as `NOTPROTON_<X>`. The loop at its top maps the user-facing
+ `BRIDGEPLAY_<X>` spelling onto them, so document new settings as `BRIDGEPLAY_<X>`.
+ - Gamefix `.conf` files are data, never shell code. A new key needs a case in the
+ allow-list in `gamefix_reason`, a row in [docs/GAMEFIXES.md](../docs/GAMEFIXES.md), and
+ a passing `make gamefixescheck`.
+ - Checks for the run script: `runcheck`, `envcheck`, `settingscheck`, `routecheck`,
+ `gamedrivecheck`, `launchercheck`, `gamefixescheck`.
+- **Tests** live in `dylib/tests/`. They run without Steam or Dobby; several `#include` the
+ `.c` file under test for that reason. Add a new check as a Makefile target and to the
+ check list in `.github/workflows/app.yml`.
diff --git a/dylib/CLAUDE.md b/dylib/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/dylib/CLAUDE.md
@@ -0,0 +1 @@