Free fork of NotProton: Windows Steam games in Mac Steam, on CodeWeavers' Wine and Apple's Game Porting Toolkit
Swift apple-silicond3dmetaldxmtdxvkgame-porting-toolkitgptkmac-gamingmacosmetalfxrosetta-2steamsteam-playwinewinecx
docs: add AGENTS.md and CLAUDE.md (#1)
Raystorms78fb3ebcf8f1
diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 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.mdnew file mode 100644index 0000000..43c994c--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1 @@diff --git a/dylib/AGENTS.md b/dylib/AGENTS.mdnew file mode 100644index 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.mdnew file mode 100644index 0000000..43c994c--- /dev/null+++ b/dylib/CLAUDE.md@@ -0,0 +1 @@