hackmatch 1.1

Exapunks HACK*MATCH Bot

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!

---

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) <[e-mail]>
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) [e-mail]

License and Copyright

Copyright (C) 2023 Rodrigo Silva (MestreLion) <[e-mail]>.
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.