日本語

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.

AI Usage Notice

The Egaroucid library interface was created with assistance from the AI agent Codex.

The Japanese and English versions of this library page were drafted by AI and edited by Nyanyan.

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

By default, this builds a static library. If you need a shared library with SONAME for Linux packaging, add -DBUILD_SHARED_LIBS=ON. For shared libraries, CMake sets VERSION from the Egaroucid version and SOVERSION from the major version.

cmake -S . -B build_lib -DBUILD_ENGINE_LIB=ON -DBUILD_SHARED_LIBS=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.