Endgame-Analyzer

This is a dynamic program written in C++ to solve Hanabi endgames. Some optimizations are performed, but it is not particularly well-written at the moment and could also use some code cleanup.

As of now, you can run the executable with an id from a hanab.live game and a turn number and the winning percentage for the corresponding game state with optimum play will be calculated.

Here, optimum play refers to the assumption that everbody knows their cards, but not the draw pile.

For example, if the output of the program is 1, then this means that even if an evil adversary is allowed to pick the next card in the deck each time a card is drawn, there is still a strategy that guarantees a win.

Compilation

The build uses CMake. Additionally, you need the following libraries:

• boost: For some faster containers and JSON parsing
• cpr: For easy requests (to download games from hanab.live
• GNU readline: For the command-line interface. Refer to the corresponding pages for installation instructions. On Linux distributions, readline is probably already installed.

Note that the libraries are all FOSS software and GPL-compatible. For installation help, see below.

Now, building the project is quite easy (this assumes you have installed above libraries system-wide):

cmake -DCMAKE_BUILD_TYPE=RELEASE .    // Release build recommended for performance, unless you want to develop
make                                  // Rerun this every time you change sources

Installing the libraries

I can't provide information for all distributions, but in general it should be like the following:

Linux systems:

• boost and cmake: should be available as a system package via your package manager.
  • Unfortunately, on many Debian-derivatives, only boost 1.71 is available with your system repositories. To compile this project, you need boost>=1.75.
  • As an alternative, you can compile boost from source, refer to the Boost Unix installation guide. You will need to link against boost binary libraries as well (see section 5), specifically the 'Program Options' (and optionally 'Unit Test' if you want to compile them). For this, you can use ./bootstrap.sh --with-libraries=program_options (or --with-libraries=program_options,test) to limit compilation of the boost libraries to only those you need. To install boost globally, run sudo ./b2 install, otherwise you will need to point CMake to your local installation and edit CMakeLists.txt acoordingly.
• readline should be installed already, otherwise try your package manager as well. On some systems, you will need to additionally install libreadline-dev (or similar), since this includes the development headers needed for linking during compilation.
• cpr should be fetched as a submodule from its GitHub repository automatically by CMake.
  • Alternatively, install cpr globally via your package manager, see [Installing cpr via your system package manager][#Installing-cpr-via-your-system-package-manager].

Mac OS:

• I recommend installing packages with Homebrew.
• So brew install boost cpr readline cmake should do the job.
• Note this is not tested, since I do not have access to a Mac.

Windows:

• I recommend using the 'Windows Subsystem for Linux (WSL)'. Then, follow the Linux system installation from above.
• WSL is the (currently) only tested installation method for Windows.

Installing cpr via your system package manager

By default, cpr is fetched by CMake during installation from its github origin. You can find details on this installation method on the cpr github page as well.

Alternatively, you might want to install cpr globally on your system. For example, this is possible for Arch via AUR and Fedora via rpm In this case, replace include(FetchContent) FetchContent_Declare(cpr GIT_REPOSITORY https://github.com/libcpr/cpr.git GIT_TAG 2553fc41450301cd09a9271c8d2c3e0cf3546b73) FetchContent_MakeAvailable(cpr) with find_package(cpr) in CMakeLists.txt.

Usage

For a detailed usage explanation, run ./endgame-analyzer --help. The general usage is as follows:

# ./endgame-analyzer (-g GAME_ID | -f GAME_FILE) (-t TURN | -d DRAW_PILE_SIZE) [OPTIONS]

where

• GAME_ID is a game from hanab.live.
• GAME_FILE is a path to a file containing the game as JSON in the hanab.live format.
• TURN specifies the turn of the game state to analyze. Turn 1 is the state before actions have been taken.
• OPTIONS is a list of further options to modify the running of the program, for example
  • --score-goal to optimize for achieving a certain score not necessarily maximum.
  • --clue-modifier to edit the base state and apply a relative modifier to the initial clue count
  • --save-memory Reduce memory usage at the cost of execution time. This typically means 50% less memory, but a slowdown of 4-6 in runtime. You will likely only need this for extreme cases.
  • --version Print version and compilation information for your program.
  • --recursive Evaluates the game from the back until specified game state and prints information during evaluation. Also useful for infinite analysis, in case you are unsure which initial game state is solvable in feasible time.

Be cautious about specifying too low turn counts, your program will eventually run out of memory. Typically, turn counts where roughly 8-10 cards are still in the draw pile are reasonably fast, but running times depend heavily on the exact game state you want to analyze.

License

This is GPLv3-licensed. See LICENSE for details.