{"id":51863185,"url":"https://github.com/ncw/gbchess","last_synced_at":"2026-07-24T11:30:24.547Z","repository":{"id":369132688,"uuid":"1261958409","full_name":"ncw/gbchess","owner":"ncw","description":"A complete chess game for the original Nintendo Game Boy DMG, written in C with GBDK-2000","archived":false,"fork":false,"pushed_at":"2026-06-07T11:49:33.000Z","size":111,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-11T21:00:07.449Z","etag":null,"topics":["chess-game","gameboy","gbdk-2020"],"latest_commit_sha":null,"homepage":"","language":"C","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/ncw.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["ncw"],"patreon":"njcw","liberapay":"ncw","custom":["https://rclone.org/donate/"]}},"created_at":"2026-06-07T11:40:25.000Z","updated_at":"2026-07-04T23:07:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ncw/gbchess","commit_stats":null,"previous_names":["ncw/gbchess"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ncw/gbchess","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgbchess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgbchess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgbchess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgbchess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncw","download_url":"https://codeload.github.com/ncw/gbchess/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgbchess/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35841138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-24T02:00:07.870Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["chess-game","gameboy","gbdk-2020"],"created_at":"2026-07-24T11:30:20.216Z","updated_at":"2026-07-24T11:30:24.524Z","avatar_url":"https://github.com/ncw.png","language":"C","funding_links":["https://github.com/sponsors/ncw","https://patreon.com/njcw","https://liberapay.com/ncw","https://rclone.org/donate/"],"categories":[],"sub_categories":[],"readme":"# Game Boy Chess\n\nA complete chess game for the original Nintendo Game Boy DMG, written in C with\n[GBDK-2020](https://github.com/gbdk-2020/gbdk-2020). The whole thing (engine,\nopening book, graphics and UI) fits in a 32 KB ROM and runs on the Game Boy's\n8-bit CPU with its tiny amount of RAM.\n\nIt was written for my [IOCCC 29 entry](https://github.com/ncw/ioccc-gameboy)\nGameBoy emulator to be one of the ROMS that I distrubted with it.\n\nDownload the ROM [gbchess.gb](./gbchess.gb) from the repo.\n\n![Game Boy Chess](gbchess.png)\n\n## Features\n\n- A real chess engine running on real (or emulated) Game Boy hardware:\n  - [0x88 board representation](https://en.wikipedia.org/wiki/0x88) with full move generation and validation\n  - [Negamax search](https://en.wikipedia.org/wiki/Negamax) with [alpha-beta pruning](https://en.wikipedia.org/wiki/Alpha%E2%80%93beta_pruning) and [iterative deepening](https://en.wikipedia.org/wiki/Iterative_deepening_depth-first_search)\n  - [Quiescence search](https://www.chessprogramming.org/Quiescence_Search) to avoid the horizon effect\n  - [MVV-LVA move ordering](https://www.chessprogramming.org/MVV-LVA) (Most Valuable Victim − Least Valuable Aggressor)\n  - Incrementally-updated evaluation: material + [piece-square tables](https://www.chessprogramming.org/Piece-Square_Tables)\n  - A dedicated endgame evaluator (king-to-edge mop-up, king activation) so\n    it can actually finish off K+P vs K and similar endings\n  - Repetition detection with a \"smart contempt\" factor (takes a draw when\n    losing, avoids one when winning)\n  - All search state lives on a global stack rather than the C call stack, to\n    stay within the Game Boy's limited RAM\n- Opening book compiled into the ROM so the first moves play instantly\n- Full rules: castling, en passant, pawn promotion, check, checkmate and\n  stalemate detection\n- Four difficulty levels (~900 to ~1325 Elo) and four player configurations\n  (Human v Human, Human v Computer, Computer v Human, Computer v Computer)\n- Polished UI: animated piece movement with ghost pieces, a live evaluation\n  bar, last-move highlighting, a \"thinking\" spinner, board flipping (automatic\n  for the human side), in-game menus, undo, sound effects and a help screen\n- You can interrupt the engine mid-think (**hold B**) to make it play now,\n  continue, flip the board or start a new game\n\n## Strength\n\nThe engine has been tested over thousands of games against Stockfish (with\n`UCI_LimitStrength`). Approximate ratings by search depth:\n\n| Difficulty | Depth | Elo (vs Stockfish) |\n|------------|-------|--------------------|\n| Beginner   | ~1    | ~900               |\n| Easy       | ~1-2  | ~1050              |\n| Medium     | 2     | ~1250              |\n| Hard       | 3     | ~1325              |\n\n(Levels above the base depth automatically search deeper in the endgame.)\n\n## Controls\n\n| Button   | Action            |\n|----------|-------------------|\n| D-Pad    | Move cursor       |\n| A        | Pick up / place piece |\n| B        | Cancel selection  |\n| Hold B   | Stop the CPU thinking (opens the interrupt menu) |\n| SELECT   | Open the in-game menu |\n\nThe goal, naturally, is to checkmate the opponent's king.\n\n## Building\n\nThe project is designed to compile **both** for the Game Boy and for the host\nmachine - running the exact same engine code on the host is what makes it\npractical to test and debug. This is driven by the `Makefile`.\n\n### Prerequisites\n\n- [GBDK-2020](https://github.com/gbdk-2020/gbdk-2020) installed at `/opt/gbdk`\n  (override with `GBDK_ROOT` in the `Makefile`)\n- `gcc` for the host builds\n- Optionally [Stockfish](https://stockfishchess.org/) and `python-chess` for\n  running strength tests (`match.py`)\n\n### Build everything\n\n```sh\nmake           # builds host binaries and Game Boy ROMs\nmake gb        # just the Game Boy ROMs\nmake host      # just the host binaries\n```\n\nThe playable ROM is produced at `bin/gbchess.gb`. Load it into a Game Boy\nemulator (or a flash cart) to play.\n\n## Project layout\n\n### Shared engine (compiles for GB and host)\n\n| File          | Purpose |\n|---------------|---------|\n| `chess.c/.h`  | 0x88 board, move generation, make/unmake, rules |\n| `eval.c/.h`   | Material, piece-square tables, endgame evaluation, position hashing |\n| `engine.c/.h` | Negamax + alpha-beta + quiescence search, iterative deepening, move ordering |\n| `book.c/.h`   | Opening-book lookup |\n| `book_data.c` | Generated opening-book data (from `book.txt`) |\n\n### Game Boy front-end\n\n| File          | Purpose |\n|---------------|---------|\n| `gbchess.c`   | The Game Boy game: rendering, sprites, input, menus, animation |\n| `tiles.c/.h`  | Tile graphics, generated from `tiles.png` by `png2asset` |\n| `sound.c/.h`  | Sound effects |\n\n### Host tools \u0026 test harnesses\n\n| File             | Purpose |\n|------------------|---------|\n| `uci.c`          | UCI front-end so the engine can play other engines / GUIs |\n| `perft.c`        | Move-generator correctness testing (perft) |\n| `random_game.c`  | Plays random games to sanity-check move generation |\n| `one_ply.c`      | Plays the best 1-ply move (early engine prototype) |\n| `full_player.c`  | Full-search self-play driver |\n| `book_gen.c`     | Compiles `book.txt` into `book_data.c` |\n| `match.py`       | Runs matches vs Stockfish and reports Elo with 95% confidence intervals |\n\n## How it works\n\nThe engine uses a classic 0x88 board where off-board squares are detected with a\nsingle `sq \u0026 0x88` test which is cheap on an 8-bit CPU. Moves are generated as\npseudo-legal and checked for legality lazily inside the search by making the\nmove and testing whether the king is left in check.\n\nThe evaluation is kept in a global score that is updated incrementally as pieces\nare added, removed and moved, so it costs almost nothing to read during search.\nIt combines raw material value with piece-square tables that nudge pieces toward\ngood squares. Once material thins out (or one side has a large lead) a separate\nendgame function takes over, driving the losing king to the edge and bringing\nthe winning king in to help deliver mate.\n\nSearch is negamax with alpha-beta pruning, wrapped in iterative deepening (so a\nsearch interrupted mid-way still has a good move from the previous depth) and a\nquiescence search at the leaves that only follows captures and promotions to\navoid incorrect evaluations in the middle of a trade.\n\n## License\n\nReleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncw%2Fgbchess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncw%2Fgbchess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncw%2Fgbchess/lists"}