{"id":13937790,"url":"https://github.com/adam-mcdaniel/chess-engine","last_synced_at":"2025-05-16T10:06:18.986Z","repository":{"id":42031188,"uuid":"332889186","full_name":"adam-mcdaniel/chess-engine","owner":"adam-mcdaniel","description":"A dependency-free chess engine♟️ library built to run anywhere.","archived":false,"fork":false,"pushed_at":"2024-04-18T18:14:25.000Z","size":3098,"stargazers_count":444,"open_issues_count":4,"forks_count":31,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-11T18:38:56.838Z","etag":null,"topics":["ai","chess","game"],"latest_commit_sha":null,"homepage":"https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adam-mcdaniel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-25T21:30:55.000Z","updated_at":"2025-05-09T22:08:27.000Z","dependencies_parsed_at":"2024-04-11T03:31:18.907Z","dependency_job_id":"1d5fa5e8-ad47-4e68-b576-0702e1b0fc20","html_url":"https://github.com/adam-mcdaniel/chess-engine","commit_stats":{"total_commits":107,"total_committers":5,"mean_commits":21.4,"dds":0.08411214953271029,"last_synced_commit":"bb617a7d76f27981018a1c34d9e312f59a8fad5b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-mcdaniel%2Fchess-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-mcdaniel%2Fchess-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-mcdaniel%2Fchess-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adam-mcdaniel%2Fchess-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adam-mcdaniel","download_url":"https://codeload.github.com/adam-mcdaniel/chess-engine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509477,"owners_count":22082891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chess","game"],"created_at":"2024-08-07T23:03:53.545Z","updated_at":"2025-05-16T10:06:18.968Z","avatar_url":"https://github.com/adam-mcdaniel.png","language":"Rust","funding_links":["https://www.buymeacoffee.com/adam.mcdaniel"],"categories":["Rust"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e♔chess-engine♚\u003c/h1\u003e\n\n  \u003cp\u003e\n    \u003cstrong\u003eA dependency-free chess engine library built to run anywhere.\u003c/strong\u003e\n  \u003c/p\u003e\n\n  \u003ch3\u003e\n    \u003ca href=\"https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html#average-ai\"\u003eDemo\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://docs.rs/chess-engine/\"\u003eDocs\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"mailto:adam.mcdaniel17@gmail.com\"\u003eContact Me\u003c/a\u003e\n  \u003c/h3\u003e\n\n  \u003csub\u003eWritten in Rust🦀💖\u003c/sub\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html#average-ai\"\u003e\n    \u003cimg alt=\"Chess in the terminal\" src=\"./assets/terminal2.png\" width=\"36%\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html#average-ai\"\u003e\n    \u003cimg alt=\"Chess in the web\" src=\"./assets/web.png\" width=\"63%\"/\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\n## Why write a Chess engine?\n\nAbove all, [this video](https://www.youtube.com/watch?v=DpXy041BIlA\u0026t=7s) by [Tom7](http://tom7.org/) is my inspiration for this project. He's absolutely brilliant and I implore you to watch his content.\n\nI love chess a _lot_. It's definitely one of my favorite games ever. However, I've always been disappointed when trying to write programs that play chess digitally (particularly in a compiled language). Although several amazing engines exist, it's near impossible to find a neat library for chess-related-programming that runs on everything.\n\nchess-engine is a solution to my problem. If you want a chess engine that runs on embedded devices, the terminal, [the desktop (with a gui)](https://github.com/adam-mcdaniel/chess-engine/tree/main/examples/chess-gui), _and_ [the web](https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html#average-ai), this is probably your best bet.\n\n## How does it work?\n\nThis particular AI (along with most other chess AIs) works using the [Minimax algorithm](https://en.wikipedia.org/wiki/Minimax), along with [Alpha-Beta pruning](https://en.wikipedia.org/wiki/Alpha%E2%80%93beta_pruning) for optimization.\n\nNow, let's unpack that.\n\nThe Minimax algorithm essentially iterates through all possible moves recursively, and evaluates all of the boards after the moves are played. If the board is _more_ favorable, it will **encourage** playing its parent move, but if a board is _less_ favorable, then it will select **against** playing a given move.\n\n![Minimax](./assets/mini-max.jpeg)\n\nAdditionally, when the AI attempts to see past just the current board, it will assume the human _always_ responds with the best moves. As a result, the computer almost **never** blunders.\nThis allows the computer to almost always play objectively better moves than the player.\n\n## Embedded in the Web\n\nBecause it has zero dependencies, it's extremely simple to embed in the web browser using wasm. [Try playing it yourself!](https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html#average-ai)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003cstrong\u003eAverage AI Setting\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003ca href=\"https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html#average-ai\"\u003e\n    \u003cimg alt=\"Try playing it yourself!\" src=\"./assets/web-board.png\"/\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## Usage\n\nThe `Board` structure has a few different methods that allow users to generate moves from a given position, including `get_best_next_move`, `get_worst_next_move`, and `get_legal_moves`. These are particularly handy for writing chess AIs to play against.\n\n```rust\nfn main() {\n    let board = Board::default();\n\n    // Get the best move with 4 moves of lookahead\n    let best_move = board.get_best_next_move(4);\n    // Get the worst move with 3 moves of lookahead\n    let worst_move = board.get_worst_next_move(3);\n\n    // Get all of the possible legal moves for the given player\n    let legal_moves = board.get_legal_moves();\n    // Print the board\n    println!(\"{}\", board);\n\n    print!(\"CPU chose to \");\n    match best_move {\n        Move::Piece(from, to) =\u003e println!(\"move {} to {}\", from, to),\n        Move::KingSideCastle =\u003e println!(\"castle kingside\"),\n        Move::QueenSideCastle =\u003e println!(\"castle queenside\"),\n        Move::Resign =\u003e println!(\"resign\")\n    }\n}\n```\n\nTo add some variation or more advanced play, consider writing an AI that plays known openings that build better positions before using the `get_best_next_move` method!\n\n#### Custom Boards\n\nAdditionally, users can create their own custom `Board` objects other than the default one. This is done using the `BoardBuilder` structure. The `BoardBuilder` structure supports enabling and disabling castling, placing rows and columns of pieces, and placing individual pieces.\n\n_**Keep in mind when using a `BoardBuilder` that castling is disabled by default!**_\n\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003cstrong\u003ePlay the Horde Chess Variant\u003c/strong\u003e\n  \u003c/p\u003e\n\n  \u003ca href=\"https://adam-mcdaniel.github.io/chess-engine/docs/book/index.html#other-features\"\u003e\n    \u003cimg alt=\"Play the Horde Chess Variant\" src=\"./assets/horde.png\"/\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n```rust\nfn main() {\n    // `BoardBuilder::new()` returns an empty board\n    // with castling disabled.\n    // Creating a board builder from another board\n    // structure will preserve\n    // all settings from the board (such as castling\n    // and the last en-passant move).\n\n    // This BoardBuilder constructs the \"Horde\" chess variant!\n    let board = BoardBuilder::from(Board::default())\n            .row(Piece::Pawn(WHITE, A1))\n            .row(Piece::Pawn(WHITE, A2))\n            .row(Piece::Pawn(WHITE, A3))\n            .row(Piece::Pawn(WHITE, A4))\n            .piece(Piece::Pawn(WHITE, F5))\n            .piece(Piece::Pawn(WHITE, G5))\n            .piece(Piece::Pawn(WHITE, B5))\n            .piece(Piece::Pawn(WHITE, C5))\n            .build();\n\n    // The CPU can also play variants!\n    let cpu_move = board.get_best_next_move(3);\n    \n    match board.play_move(cpu_move) {\n        GameResult::Continuing(next_board) =\u003e {\n            println!(\"{}\", next_board);\n        }\n\n        GameResult::Victory(winner) =\u003e {\n            // You can use the ! operator on a player's\n            // color to invert.\n            println!(\"{} loses. {} is victorious.\",\n              !winner, winner\n            );\n        }\n\n        GameResult::IllegalMove(x) =\u003e {\n            eprintln!(\"{} is an illegal move.\", x);\n        }\n\n        GameResult::Stalemate =\u003e {\n            println!(\"Drawn game.\");\n        }\n    }\n}\n```\n\n## About the Author\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003e\n    \u003ca href=\"https://adam-mcdaniel.net\"\u003eWebsite\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://adam-mcdaniel.net/blog\"\u003eBlog\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://github.com/adam-mcdaniel\"\u003eGitHub\u003c/a\u003e\n  \u003c/h3\u003e\n\n  \u003cp\u003e\n    I'm a freshman in college, mainly working on side projects like these in the ~30 minute breaks between classes. If you enjoy my projects, consider supporting me by buying me a coffee!\n  \u003c/p\u003e\n\n  \u003ca href=\"https://www.buymeacoffee.com/adam.mcdaniel\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-blue.png\" alt=\"Buy Me A Coffee\" height=\"60px\" width=\"217px\"/\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadam-mcdaniel%2Fchess-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadam-mcdaniel%2Fchess-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadam-mcdaniel%2Fchess-engine/lists"}