Cross-platform Exapunks HACK*MATCH bot

Yet another bot for Exapunks' amazing (and annoyingly hard) HACK*MATCH arcade minigame.

Want to score 100,000 points and grab the hardest of its achievements and join the 0,7% club? Look no further!

Don't feel frustrated if you, like me, have no skills for a NES-like reflex game and think such arcade game have no place in a logic/puzzle programming game such as Exapunks.

Why create another bot? Well, I felt it would not be cheating if I programmed the bot myself! Exapunks is all about coding and hacking, so creating a bot to hack it fits in perfectly!

See it in action!

Features

• Cross Platform, works on Windows, macOS and Linux
• Works on several resolutions, from 1920x1200 to 1366x768
• Read and write game settings to get user's current keyboard mapping and to automatically turn off CRT effects.
• Launch the game if needed, using Steam's steam://rungameid/716490 game URI.
• Pure Python: easy to understand, install and run, no compiler or other tools needed.
• Command-line arguments to benchmark, debug, watch-only and more.

Heavily inspired by and adapted from:

• Fidel-solver's exapunks-hack-match bot

  • C++, X11 and 1600x900 only, requires custom keys, has fuzzy tolerance on colors.
  • Arguably the most well-known reference, possibly the first bot published.
  • +500K points recorded on YouTube.

• Laelath's hack-match-bot

  • Rust, X11 and 1920x1080 only, requires default keys and no CRT, no fuzziness.
  • An elegant code with great insights on image parsing and board solving.
  • +8M points recorded on YouTube.

Special thanks to Dissecting fidelSolver's Game Bot for Playing Hack*Match, an amazing presentation by Alan Shen that helped me understand the basic concepts and building blocks of both above projects.

Installing

Run this to install the bot and its dependencies, preferably in a virtual environment:

pip3 install hackmatch

This bot is written in Python and uses PyAutoGUI, which has some pre-requisites beyond its pip install. For Debian, Ubuntu and derivatives, just run:

sudo apt install python3-tk

For instructions on all platforms, see the PyAutoGUI documentation.

I've also included a tool to automatically create the python virtual environment, apt-install the requirements and pip-install dependencies and the bot itself, all in a single step:

./install.sh

Note: even if code itself is compatible with earlier Python versions, some dependencies require Python 3.7. It was fully tested on Python 3.8.

Usage

For basic usage, just run:

hackmatch-bot

• If the game is installed in Steam, it will automatically launch Exapunks if not already running.
• Keep the bot running (i.e., leave the terminal open), and manually enter and start the HACK*MATCH minigame.
• Profit!

Debugging, testing or fine-tuning?

$ hackmatch-bot --help
usage: hackmatch-bot [-h] [-q | -v] [--benchmark] [--watch] [--solve-time TIME]
                                    [--board TEXT | IMAGE]

positional arguments:
  IMAGE              Ignore game window and solve IMAGE instead.
                     Useful when debugging with --verbose.

optional arguments:
  -h, --help         show this help message and exit
  -q, --quiet        Suppress informative messages.
  -v, --verbose      Verbose mode, output extra info.
  --benchmark        Benchmark mode, run for 30 seconds.
                       Best used with --quiet and game already launched.
  --watch            Watch mode, read and solve board but do not play.
  --solve-time TIME  Time in milliseconds to solve each parsed board,
                       0 for unlimited. [Default: 850 ms]
  --board TEXT       Ignore game window and solve TEXT instead.

Copyright (C) 2023 Rodrigo Silva (MestreLion) <linux@rodrigosilva.com>
License: GPLv3 or later, at your choice. See <http://www.gnu.org/licenses/gpl>

Contributing

Patches are welcome! Fork, hack, request pull!

See the To-Do List for more updated technical information and planned features.

If you find a bug or have any enhancement request, please to open a new issue

Author

Rodrigo Silva (MestreLion) linux@rodrigosilva.com

License and Copyright

Copyright (C) 2023 Rodrigo Silva (MestreLion) <linux@rodrigosilva.com>.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.