{"id":51121657,"url":"https://github.com/scryner/crosspuck","last_synced_at":"2026-06-25T03:01:27.967Z","repository":{"id":362087687,"uuid":"1246571176","full_name":"scryner/crosspuck","owner":"scryner","description":"A simple bridge app from Steam Controller (Puck) to CrossOver for Mac OS","archived":false,"fork":false,"pushed_at":"2026-06-02T13:28:36.000Z","size":1426,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T15:21:44.727Z","etag":null,"topics":["apple-silicon","crossover","gaming","mac-gaming","macos","rust","steam-controller","steam-input","wine"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scryner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T10:23:18.000Z","updated_at":"2026-06-02T13:28:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scryner/crosspuck","commit_stats":null,"previous_names":["scryner/crosspuck"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/scryner/crosspuck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scryner%2Fcrosspuck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scryner%2Fcrosspuck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scryner%2Fcrosspuck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scryner%2Fcrosspuck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scryner","download_url":"https://codeload.github.com/scryner/crosspuck/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scryner%2Fcrosspuck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34757355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-silicon","crossover","gaming","mac-gaming","macos","rust","steam-controller","steam-input","wine"],"created_at":"2026-06-25T03:01:27.320Z","updated_at":"2026-06-25T03:01:27.957Z","avatar_url":"https://github.com/scryner.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CrossPuck\n\n[![License: Apache 2.0](https://img.shields.io/github/license/scryner/crosspuck)](LICENSE)\n[![Latest Release](https://img.shields.io/github/v/release/scryner/crosspuck)](https://github.com/scryner/crosspuck/releases/latest)\n\n![CrossPuck demo showing Steam Controller input in CrossOver Steam](docs/assets/crosspuck-poster.jpg)\n\nCrossPuck lets Steam running in a CrossOver bottle use a Steam Controller\nconnected to the macOS host.\n\n_If CrossPuck helps you, a GitHub star would be appreciated._ ⭐\n\nThe project is split into two production pieces:\n\n- `crosspuck-app`: a macOS menu bar host app. It reads the physical Steam\n  Controller/Puck HID devices, forwards input reports to the guest, and applies\n  guest feedback such as rumbles/haptics back to the controller.\n- `crosspuck-driver`: a guest-side `hid.dll` for the CrossOver Steam process.\n  It exposes virtual HID profiles to Steam and bridges input/output traffic to\n  the macOS host app.\n\nShared HID identity, transport, protocol, and guest runtime logic live in\n`crosspuck-core`. `crosspuck-cli` contains development and diagnostic tools.\n\n## Binary DMG Install\n\nUse these instructions when you have a released `.dmg` installer. Rust and the\nsource tree are not required.\n\n### Requirements\n\n- macOS.\n- A CrossOver or CrossOver Preview Steam bottle.\n- Steam Puck/Controller visible to the macOS host.\n- Steam Puck/Controller paired with a native app on macOS or Windows.\n- A CrossPuck `.dmg` release.\n\n### Install CrossPuck\n\n1. Open the `.dmg`, then drag `CrossPuck.app` into `Applications`.\n2. Start `CrossPuck.app` once from `Applications`.\n3. Open Apple menu \u003e `System Settings` \u003e `Privacy \u0026 Security` \u003e\n   `Input Monitoring`.\n4. Confirm that `CrossPuck.app` is listed and enabled. If it is missing, click\n   the add button (`+`), choose `/Applications/CrossPuck.app`, then enable it.\n   If an older CrossPuck entry points to a different location, remove that entry\n   and add the app from `Applications` again.\n5. Quit and restart CrossPuck after changing `Input Monitoring`.\n6. Quit Steam in the CrossOver bottle if it is already running.\n7. Use the CrossPuck menu bar \"Install Steam Driver...\" item. This installs\n   `hid.dll` next to `Steam.exe` and imports the Wine loader override registry\n   file.\n8. Keep CrossPuck running, then start Steam from the CrossOver bottle.\n\nThe installer handles both `/Applications/CrossOver.app` and\n`/Applications/CrossOver Preview.app`. Preview-marked bottles import through\nCrossOver Preview first; regular bottles import through CrossOver first; the\nother app is used as a fallback when only one is installed.\n\n### Bottles In A Non-Default Location\n\nCrossPuck auto-detects the Steam bottle under\n`~/Library/Application Support/CrossOver/Bottles` by default. If your bottle\nlives elsewhere (for example on an external drive), or several bottles have\nSteam installed, use the menu bar `Advanced` \u003e `Bottle Path` \u003e\n`Choose Bottle...` item to pick the CrossOver bottle CrossPuck should use. The\nchoice is remembered across launches; the `Bottle:` line shows the bottle\ncurrently in use, and `Reset to Default` returns to auto-detection. Two\nenvironment variables override this for scripting: `CROSSPUCK_BOTTLE_PATH`\nselects a specific bottle and takes precedence over the menu selection, and\n`CROSSPUCK_BOTTLES_DIR` changes the directory that auto-detection scans.\n\n### Verify Wine DLL Override\n\nIf Steam does not see the controller, verify the Wine DLL override manually:\n\n1. Open the CrossOver app that owns the Steam bottle. If both CrossOver and\n   CrossOver Preview are installed and you are unsure which owns the bottle,\n   check the Steam bottle in both apps.\n2. Select the Steam bottle.\n3. Open `Wine Configuration`.\n4. Open the `Libraries` tab.\n5. In `Existing overrides`, confirm that `hid (native, builtin)` is present.\n6. If it is missing, enter `hid` in `New override for library`, click `Add`,\n   select the new `hid` entry, click `Edit...`, choose `Native then Builtin`,\n   then click `OK`. Do not remove or replace other existing DLL overrides.\n7. Click `Apply`, then `OK`.\n\n## Source Build\n\nUse these instructions when building CrossPuck from this repository.\n\n### Requirements\n\n- macOS with Rust installed.\n- A checkout of this repository.\n- A CrossOver or CrossOver Preview Steam bottle.\n- Steam Puck/Controller visible to the macOS host.\n- Steam Puck/Controller paired with a native app on macOS or Windows.\n\nInstall the Windows Rust target for the guest DLL:\n\n```sh\nrustup target add x86_64-pc-windows-gnu\n```\n\n### Build The Host App\n\nBuild a debug app bundle. The bundle includes the release guest `hid.dll` under\n`Contents/Resources/GuestDriver/`:\n\n```sh\ntools/build-app.sh debug\n```\n\nBuild a release app bundle:\n\n```sh\ntools/build-app.sh release\n```\n\nThe script prints the generated bundle path, for example:\n\n```text\ntarget/release/CrossPuck.app\n```\n\nThe embedded guest driver manifest is written to:\n\n```text\nCrossPuck.app/Contents/Resources/GuestDriver/manifest.json\n```\n\nLicense files are embedded in:\n\n```text\nCrossPuck.app/Contents/Resources/LICENSE\nCrossPuck.app/Contents/Resources/THIRD-PARTY-NOTICES.md\n```\n\n### Build A DMG\n\nCreate a drag-and-drop installer DMG from the release app bundle:\n\n```sh\ntools/build-dmg.sh\n```\n\nThe default output is:\n\n```text\ntarget/dmg/CrossPuck-0.1.0.dmg\n```\n\nThe DMG opens in a conventional drag-and-drop Finder layout: a large\n`CrossPuck.app` icon on the left, an arrow in the middle, and an `Applications`\nsymlink on the right. The mounted DMG volume uses the app's `CrossPuck.icns`\nicon. For CI release automation, build and codesign the app first, then package\nthat signed app:\n\n```sh\ntools/build-dmg.sh --app target/release/CrossPuck.app\n```\n\nThe script does not notarize. GitHub Actions can notarize and staple the signed\napp before packaging, or notarize and staple the generated DMG after packaging.\n\n### Run The Built App And Install Driver\n\nStart the app before launching Steam in the CrossOver bottle. On macOS, grant\nCrossPuck Input Monitoring permission when prompted; without it the app can\nlisten for guest connections but cannot open the Steam Controller HID device.\nIf permission was denied earlier, enable it in `System Settings` \u003e\n`Privacy \u0026 Security` \u003e `Input Monitoring`, then restart CrossPuck.\n\nUse the menu bar \"Install Steam Driver...\" item to deploy the embedded\n`hid.dll` next to `Steam.exe` in the Steam bottle. Install, update, and repair\nalso write `crosspuck-wine-override.reg` into the bottle and import it with\nCrossOver `regedit`, setting Wine's `hid=native,builtin` DLL override without\nrewriting `user.reg` directly. The app supports both `/Applications/CrossOver.app`\nand `/Applications/CrossOver Preview.app`: preview-marked bottles import through\nCrossOver Preview first, regular bottles import through CrossOver first, and the\nother app is used as a fallback when only one is installed. Uninstalling removes\nonly the app-local `hid.dll`; it intentionally leaves Wine registry settings\nunchanged.\n\n### Build The Guest Driver\n\nBuild the production guest `hid.dll`:\n\n```sh\ncargo build -p crosspuck-driver --release --target x86_64-pc-windows-gnu\n```\n\nThe output is:\n\n```text\ntarget/x86_64-pc-windows-gnu/release/hid.dll\n```\n\n### Manual Shell Install\n\nThe menu bar app is the preferred installer. It handles driver\ninstall/update/uninstall automatically, and install/update/repair import the\nWine loader override registry file as described above. The shell installer\nbelow is mainly for manual development and smoke testing.\n\nCopy the driver next to `Steam.exe` in the target bottle:\n\n```sh\ntools/install-driver.sh --bottle Steam\n```\n\nTo also import Wine's `hid=native,builtin` loader override:\n\n```sh\ntools/install-driver.sh --bottle Steam --override-dll\n```\n\nUseful options:\n\n```sh\ntools/install-driver.sh \\\n  --bottle Steam \\\n  --driver target/x86_64-pc-windows-gnu/release/hid.dll \\\n  --no-build\n```\n\nThe script copies `hid.dll`, backs up any existing local `hid.dll`, and\ninitializes `crosspuck-driver.log`. By default it does not call CrossOver\n`regedit`. With `--override-dll`, it writes `crosspuck-wine-override.reg` into\nthe bottle and imports it with the matching CrossOver app, using CrossOver\nPreview first for preview-marked bottles and CrossOver first for regular\nbottles. It does not set guest runtime options or rewrite `user.reg` directly.\n\nDo not install this DLL into `drive_c/windows/system32`. It is designed to live\nnext to Steam and forward non-virtual HID calls to the real system HID DLL.\n\n## Tools And Diagnostics\n\nTooling, logging options, smoke checks, development verification commands, and\nthe macOS HID reference probe are documented in `tools/README.md`.\n\n## License\n\nCopyright 2026 scryner and CrossPuck contributors.\n\nCrossPuck is licensed under the Apache License, Version 2.0. See\n`LICENSE`.\n\nThird-party dependency license notices are listed in\n`THIRD-PARTY-NOTICES.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscryner%2Fcrosspuck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscryner%2Fcrosspuck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscryner%2Fcrosspuck/lists"}