Collection of macros
Files
README.md

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 #

# 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.