日本語

Egaroucid Library Feature (Experimental)

You can use Egaroucid's search engine as a standalone library independent from GUI / Console.

This API is experimental and may change in future versions.

Introduction

The Egaroucid library provides the following features:

Best-move search API (egaroucid_search_array)
Legal move generation API (egaroucid_get_legal_moves)
Flipped-disc calculation API (egaroucid_get_flipped_discs)

The public header is #include <egaroucid/egaroucid.h>.

How to Use

First, get the source code.

git clone https://github.com/Nyanyan/Egaroucid.git
cd Egaroucid

The library sample code is in examples/cpp/simple.cpp.

The public header is include/egaroucid/egaroucid.h.

Run the following commands in the repository root in order.

(GUI / Console are not built, and only the library feature is enabled.)

cmake -S . -B build_lib -DBUILD_ENGINE_LIB=ON -DBUILD_CONSOLE=OFF -DBUILD_GUI=OFF

If you only want to build the library:

cmake --build build_lib --config Release --target egaroucid

If you want to run the sample code (build the sample executable too):

cmake --build build_lib --config Release --target egaroucid_cpp_example

Using only --target egaroucid does not generate the sample executable.

If you specify --target egaroucid_cpp_example, the dependent egaroucid library is also built.

For Windows (Visual Studio), run the sample with:

.\build_lib\examples\Release\egaroucid_cpp_example.exe

For Linux / macOS (Ninja / Makefiles), run the sample with:

./build_lib/examples/egaroucid_cpp_example

This sample refers to resource files in bin/resources inside the Egaroucid repository.

So please run it from the repository root.

Library Usage

Board Representation

The index of board[64] is 0=a1, 1=b1, ..., 63=h8
Cell value is -1=empty, 0=black, 1=white
Player value is 0=black to move, 1=white to move

High-Level Usage

1. egaroucid_global_init(resource_dir)

2. egaroucid_create()

3. egaroucid_search_array(...)

4. If needed, egaroucid_get_legal_moves(...) and egaroucid_get_flipped_discs(...)

5. egaroucid_destroy()

Sample Code

#include <stdio.h>
#include <string.h>

#include <egaroucid/egaroucid.h>

static char cell_to_char(int cell) {
    if (cell == EGAROUCID_BLACK) {
        return 'X';
    }
    if (cell == EGAROUCID_WHITE) {
        return 'O';
    }
    return '.';
}

static void print_board(const int board[64]) {
    printf("  a b c d e f g h\n");
    for (int row = 0; row < 8; ++row) {
        printf("%d ", row + 1);
        for (int col = 0; col < 8; ++col) {
            printf("%c ", cell_to_char(board[row * 8 + col]));
        }
        printf("\n");
    }
}

static void move_to_coord(int move, char coord_out[3]) {
    if (move < 0 || move >= 64) {
        coord_out[0] = '-';
        coord_out[1] = '-';
        coord_out[2] = '\0';
        return;
    }
    coord_out[0] = (char)('a' + (move % 8));
    coord_out[1] = (char)('1' + (move / 8));
    coord_out[2] = '\0';
}

int main(void) {
    egaroucid_status st = egaroucid_global_init("bin/resources");
    if (st != EGAROUCID_OK) {
        printf("egaroucid_global_init failed: %d\n", st);
        return 1;
    }

    egaroucid_engine *engine = egaroucid_create();
    if (engine == NULL) {
        printf("egaroucid_create failed\n");
        return 1;
    }

    int board[64];
    for (int i = 0; i < 64; ++i) {
        board[i] = EGAROUCID_EMPTY;
    }
    board[27] = EGAROUCID_WHITE; /* d4 */
    board[28] = EGAROUCID_BLACK; /* e4 */
    board[35] = EGAROUCID_BLACK; /* d5 */
    board[36] = EGAROUCID_WHITE; /* e5 */

    printf("initial board:\n");
    print_board(board);

    egaroucid_search_options opt;
    memset(&opt, 0, sizeof(opt));
    opt.size = sizeof(opt);
    opt.level = 21;
    opt.use_book = 1;
    opt.book_accuracy_level = 0;
    opt.use_multi_thread = 1;
    opt.show_log = 0;
    opt.time_limit_ms = -1; /* currently ignored */

    egaroucid_search_result res;
    memset(&res, 0, sizeof(res));
    res.size = sizeof(res);

    st = egaroucid_search_array(engine, board, EGAROUCID_BLACK, &opt, &res);
    if (st != EGAROUCID_OK) {
        printf("egaroucid_search_array failed: %d\n", st);
        egaroucid_destroy(engine);
        return 1;
    }

    char best_move_coord[3];
    move_to_coord(res.move, best_move_coord);
    printf(
        "best move=%s (%d) value=%d depth=%d nodes=%llu\n",
        best_move_coord,
        res.move,
        res.value,
        res.depth,
        (unsigned long long)res.nodes
    );

    int legal[64];
    int n_legal = 0;
    st = egaroucid_get_legal_moves(board, EGAROUCID_BLACK, legal, &n_legal, NULL);
    if (st == EGAROUCID_OK) {
        printf("n_legal=%d\n", n_legal);
    }

    if (res.move >= 0) {
        int flipped[64];
        int n_flipped = 0;
        st = egaroucid_get_flipped_discs(board, EGAROUCID_BLACK, res.move, flipped, &n_flipped, NULL);
        if (st == EGAROUCID_OK) {
            printf("n_flipped=%d\n", n_flipped);
            if (n_flipped > 0) {
                board[res.move] = EGAROUCID_BLACK;
                for (int i = 0; i < n_flipped; ++i) {
                    board[flipped[i]] = EGAROUCID_BLACK;
                }
                printf("board after best move:\n");
                print_board(board);
            }
        }
    }

    egaroucid_destroy(engine);
    return 0;
}

Notes

This API is experimental.
time_limit_ms is currently accepted but unused.
The license is GPL-3.0-or-later, same as Egaroucid itself.