# macros A small collection of game macros built on one cross-platform helper library, packaged as a single Python distribution (`game-macros`) with a Nix flake. ## Layout ``` macros/ ├── flake.nix ├── pyproject.toml ├── nix/ │ ├── game-macros.nix # the buildPythonPackage package │ └── pyobjc-framework.nix # custom pyobjc-framework-{Vision,CoreML} ├── src/ │ ├── macrolib/ # shared library │ │ ├── input.py # mouse input + window focus (SendInput / Quartz / uinput) │ │ ├── ocr.py # text recognition (Windows OCR / Apple Vision / RapidOCR) │ │ ├── screen.py # screen capture (mss; grim/portal/spectacle on Wayland) │ │ ├── hotkeys.py # global F-key hotkeys (evdev on Linux, pynput elsewhere) │ │ └── _linux.py # Linux Wayland helpers (output size via wl_output) │ └── shoguns_reign/ # the Shogun's Reign macro │ ├── macro.py # entry point (shoguns-reign) │ ├── matcher.py │ └── vision.py └── shoguns-reign/ # docs + Windows launcher ├── README.md ├── ADDING_STATEMENTS.md └── run.bat ``` `macrolib` abstracts the platform-specific parts, so a macro only deals with game logic: - **Input** — Windows uses the native `SendInput` API (which DirectX games such as Roblox accept where `pyautogui` is ignored); macOS uses Quartz `CGEvent`; Linux uses a uinput virtual mouse (works on Wayland and X11). - **OCR** — Windows uses the Windows OCR engine (`winocr`), macOS uses Apple's Vision framework, and everything falls back to RapidOCR (onnxruntime). - **Screen** — Windows/macOS and Linux/X11 use `mss`; Linux Wayland captures via the compositor: `grim` (`zwlr_screencopy`) on wlroots/niri, `spectacle` on KDE Plasma, and GNOME's Shell screencast service (which also avoids the screenshot portal's flash/shutter sound). The XDG desktop portal is used as a GNOME fallback. If the preferred tool is unavailable the others are tried as fallbacks. - **Hotkeys** — Linux reads `/dev/input` directly via `evdev` (so global hotkeys work even when a Wayland-native window is focused); Windows/macOS use `pynput`. ## Supported platforms | Platform | Input | OCR | How to run | |----------|-----------|--------------------------|------------| | Windows | SendInput | Windows OCR / RapidOCR | double-click `shoguns-reign/run.bat` | | macOS | Quartz | Apple Vision / RapidOCR | `./shoguns-reign/run.sh` or `nix run .#shoguns-reign` | | Linux | uinput | RapidOCR | `./shoguns-reign/run.sh` or `nix run .#shoguns-reign` | On Linux Wayland screen capture uses the desktop's own tool: `grim` on wlroots/niri, `spectacle` on KDE Plasma, and GNOME's Shell screencast service (with `xdg-desktop-portal` as a fallback). Your user must also be able to write `/dev/uinput` for input. ## Usage ```console # Windows: double-click shoguns-reign/run.bat # macOS / Linux: ./shoguns-reign/run.sh # makes a venv, installs, and runs # via Nix nix run .#shoguns-reign # run the macro nix develop # dev shell (PYTHONPATH points at ./src) nix build .#game-macros # the package # any platform via pip pip install . shoguns-reign ``` ## Adding a macro Add a package under `src/` and a `[project.scripts]` entry in `pyproject.toml`; import `macrolib` for input/OCR/screen/hotkeys. It is then available as `shoguns_reign`-style module and a console script.