No Plugins; Monolithic


    0.3.0 • Public • Published



    The goal of of this project is to provide useful functionality for those seeking to integrate chess datasets (ABK, Polyglot, CTG, ECO, EPD) and engine protocols (Winboard/Xboard, UCI). This library isn't an engine, or a chess database; but instead is designed to help people who want to integrate engines and databases in order to perform more detailed analysis. For example one could take an existing game, classify the opening by ECO code, and then send the game for analysis against various engines (e.g. Komodo, Stockfish, etc) and opening book databases.


    npm install chess-tools


     const ChessTools = require('chess-tools');
     //See the examples/ folder in this package.



    All the submodules are under the ChessTools namespace.


    Allows for reading opening books in various formats with a generic interface.

    General Interface
        const ChessTools = require('chess-tools');
        const OpeningBook = ChessTools.OpeningBook.<type>
        const book = new OpeningBook();
        const fen = "rnbqkbnr/pppp1ppp/8/4p3/8/8/PPPPPPPP/RNBQKBNR w KQkq";
        stream = getFileOrBytesStreamSomehow();
        book.on("loaded", ()=> {
            let entries = book.find(fen);
            for (let entry of entries) {
                //See entry.js for each module to manage data.
    Supported Formats:
    • CTG -- used by products such as Chessbase
    • Polyglot -- used by a number of open source projects
    • ABK -- used by products such as Arena

    Other Data Formnats


    Allows for loading and parsing EPD files into individual entries organized by position.

        const ChessTools = require('chess-tools');
        const EPD = ChessTools.EPD;
        const epd = new EPD();
        const fen =  '3r1rk1/1p3pnp/p3pBp1/1qPpP3/1P1P2R1/P2Q3R/6PP/6K1 w - -'
        stream = getFileOrBytesStreamSomehow();
          let epdEntry = epd.find(fen);
          console.log("Best move is", epd.best_move);
          console.log("Comments are", epd.comments);
          //see epd/entry.js for more details.

    Allows for openings to be classified based on a pgn string.

        const ECO = ChessTools.ECO;
        const eco = new ECO();
        let pgn = "1. e4 e5 2. Nf3 Nc6 3. Bc4 Nf6 4. d3";
        eco.on("loaded", ()=>{ 
            let opening = eco.find(pgn);
            console.log("ECO CODE", opening.eco_code);
            console.log("VARIATION", opening.variation);
            //See entry.js in the eco folder for more details.
        eco.load_default(); //loads a default opening database (see sources below)
        //alternatively eco.load(stream) for a stream of a standard pgn file of openings.

    Chess Engine Integration

    Simplify communications with chess engines using either the XBoard/Winboard protocol or UCI. Default support is provided for running engines and communicating over stdin/stdout; but an abstact interface is defined below that can be extened to support other forms of interprocess/interserver communications (e.g. Sockets)


    An abstract interface to chess engines. Provides an Abstract Manager class with a generic API interface and a Connetion class that handles the low level communications. Two concrete Manager classes are available:

    • ChessTools.Engines.Manager.Xboard -- provides support for the Xboard/Winboard protocol
    • ChessTools.Engines.Manager.UCI -- provides support for the UCI protocol (recommended if available from your engine of choice).

    A generic async ponderPosition(fen, options) interface is provided. See xboard.js and uci.js for protocol specifc features.

        const ChessTools = require('chess-tools');
        const enginePath = "/path/to/engine/executable" //e.g. /usr/local/bin/gnuchess
        const engineArgs = [] //additional args e.g. "--uci"
        const conn = new ChessTools.Engines.Connection.LocalProcess(engine_path, engine_args);
        const engineManager = new ChessTools.Engines.Manager.UCI(conn, {ponder_timeout : 30000 });
        /* ponderTimeout is the amount of time in milliseconds the engine should contemplate before we force it to move (30 seconds (30000) default) */
        engineManager.on("initialized", async ()=>{ 
          let bestmove = await engineManager.ponderPosition(
          "rnbqkbnr/pp1ppppp/8/2p5/4P3/5N2/PPPP1PPP/RNBQKB1R b KQkq - 1 2", 
          {lines : 5} ); //number of lines to consider at the same time.
          console.log("BESTMOVE ", bestmove);
          engine.quit(); //closes teh engine and teh 

    Future Plans / Roadmap

    Eventually I want to expand to support various tablebase and game databases.


    Note: Sample Files are believed to be in the public domain or licensed under GPL. Sources are provided below.


    npm i chess-tools

    DownloadsWeekly Downloads






    Last publish


    • johnfontaine