{"id":24746000,"url":"https://github.com/chausner/sgbust","last_synced_at":"2025-08-10T04:37:31.470Z","repository":{"id":246271118,"uuid":"808952732","full_name":"chausner/sgbust","owner":"chausner","description":"Optimized multi-threaded SameGame solver in C++","archived":false,"fork":false,"pushed_at":"2025-04-13T17:38:55.000Z","size":347,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-10T04:37:29.270Z","etag":null,"topics":[],"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/chausner.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}},"created_at":"2024-06-01T08:59:48.000Z","updated_at":"2025-06-14T08:29:25.000Z","dependencies_parsed_at":"2024-06-27T00:18:50.368Z","dependency_job_id":"6c4a3849-c97a-41e3-8c98-b649d0a714c2","html_url":"https://github.com/chausner/sgbust","commit_stats":null,"previous_names":["chausner/sgbust"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chausner/sgbust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chausner%2Fsgbust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chausner%2Fsgbust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chausner%2Fsgbust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chausner%2Fsgbust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chausner","download_url":"https://codeload.github.com/chausner/sgbust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chausner%2Fsgbust/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269677473,"owners_count":24457853,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"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":[],"created_at":"2025-01-28T03:36:35.491Z","updated_at":"2025-08-10T04:37:31.425Z","avatar_url":"https://github.com/chausner.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sgbust\nOptimized multi-threaded SameGame solver in C++\n\n[![license](https://img.shields.io/github/license/chausner/sgbust.svg)](https://github.com/chausner/sgbust/blob/master/LICENSE)\n\nsgbust is a command-line tool that uses [beam search](https://en.wikipedia.org/wiki/Beam_search) to find good solutions for [SameGame](https://en.wikipedia.org/wiki/SameGame) puzzles.\n\n## Building\n\nTo build sgbust, a C++20-compliant compiler is required.\nsgbust is tested with recent versions of MSVC, gcc and Clang.\nAs of writing, Clang is only supported when libstdc++ is used as STL implementation.\nlibc++ is not supported.\n\n[vcpkg](https://github.com/microsoft/vcpkg) is recommended for installing third-party library dependencies.\nFollow [these instructions](https://github.com/microsoft/vcpkg?tab=readme-ov-file#getting-started) to setup vcpkg before building sgbust.\n\nYou may build either via CMake (supported on all platforms) or via MSBuild (Windows-only).\n\n## Usage\n\n### Generating grids\n\nUse the `generate` command to generate a random grid using the specified width, height, number of colors and minimum group size,\nand save it to the specified path as a BGF file:\n\n```\n.\\sgbust generate sample.bgf --width 15 --height 15 --num-colors 4 --min-group-size 2\n```\n\nYou may optionally pass a custom randomization seed using `--seed` to generate grids deterministically.\nIf no seed is set, a random seed is used.\n\n### Solving grids\n\nUse the `solve` command to search for a good solution of the grid saved at the specified path:\n\n```\n.\\sgbust solve sample.bgf --scoring greedy --scoring-group-score n^2-n\n```\n\nParameters `--scoring` and `--scoring-group-score` define the optimization objective for the search algorithm\nand are further described below.\n\n#### Solution strings\n\nA solution is a sequence of groups that are removed from a grid until no group remains.\nSolutions are represented as compact strings using the following encoding scheme:\n\n* The group in each step of the sequence is represented by a numeric ID,\n  with the first group in a grid (when iterating column-first from top to bottom) being assigned the ID 0, the second the ID 1, etc.\n* Each ID is encoded in base 26 using digits 'A'..'Z'.\n* The encoded IDs are concatenated. IDs with more than one digit are enclosed in parentheses.\n\nFor example, the solution \"(AD)(AA)GPBA\" denotes the sequence consisting of the 30th, 27th, 7th, 16th, 2nd and 1st group.\n\n#### Configuring the optimization objective\n\nSince SameGame implementations exist with a variety of different scoring rules and game objectives,\nsgbust requires the user to specify what to optimize for.\nThe following scoring schemes are currently implemented and can be chosen via the `--scoring` parameter:\n\n* `greedy` (default)\n  * A simple scoring scheme where game states are evaluated based on the current game score which is optimized greedily.\n  * Fast.\n* `potential`\n  * A more advanced variant of `greedy` where not only the current game score is optimized but also potential future scoring opportunities are taken into account.\n  * This scheme is recommended for maximization of the final game score.\n  * Slow.\n* `num-blocks-not-in-groups`\n  * Game states are evaluated based on how many blocks in the grid are not part of any group.\n    By minimizing this number, the algorithm favors solutions that allow as many blocks to be removed as possible.\n  * Recommended if you want to minimize the number of blocks remaining at the end but do not care about the final game score or the number of steps in the solution.\n  * Fast.\n\n#### Configuring scoring rules\n\nThe following parameters can be used to define the scoring rules:\n\n* `--scoring-group-score`: the score of a group, as a polynomial function of the group size\n* `--scoring-clearance-bonus`: bonus added to the final game score if no blocks remain (defaults to zero if not specified)\n* `--scoring-leftover-penalty`: penalty subtracted from the final game score if blocks remain, as a polynomial function of the number of blocks remaining (defaults to zero if not specified)\n\nExamples of polynomial expressions are `n^2`, `2n+1` or `2n^3+2n^2-3n+2`.\nOnly integer coefficients are supported.\n\nNote that, depending on the selected optimization objective (`greedy`/`potential`/`num-blocks-not-in-groups`), some of the parameters may be mandatory, optional or not supported at all.\n\n#### Limiting the search space\n\nBy default, the application attempts to search the complete game tree\nand is thereby guaranteed to find the best possible solution.\nHowever, this is only feasible for very small grids.\nIt is usually necessary to limit the search space using the `--max-beam-size` option\nas otherwise the application would quickly use up all available memory:\n\n```\n.\\sgbust solve sample.bgf --max-beam-size 10000000\n```\n\nThe number following the `--max-beam-size` parameter specifies the beam width during beam search,\ni.e. the maximum number of grid candidates kept in memory.\nIncreasing the beam size typically allows the program to find better solutions.\n\n#### Starting at a partial solution\n\nIt is possible to start the search at an intermediate state by specifying a partial solution string using `--prefix`, e.g.:\n\n```\n.\\sgbust solve sample.bgf --prefix \"XQW(AA)KK\"\n```\n\nThis will search for a good solution beginning with \"XQW(AA)KK\".\n\n#### Advanced options\n\nThere a couple of other advanced options that can be useful in certain cases.\nRun `.\\sgbust solve --help` for more information.\n\n### Displaying grids\n\nUse the `show` command to display the grid saved in the specified BGF file:\n\n```\n.\\sgbust show sample.bgf\n```\n\nIf a solution string is passed using the optional `--solution` parameter,\neach step in the solution is printed out with the resulting intermediate state of the grid, e.g.:\n\n```\n.\\sgbust show sample.bgf --solution \"(AD)ZP(AG)(AH)(AB)(AG)(AD)(AA)ZPPLJFHBPOSPBHHJIAAFAADCAAAAA\"\n```\n\n### Running benchmarks\n\nUse the `benchmark` command to generate an arbitrary number of random grids and solve them using specified parameters.\nNot only can the command be used to benchmark the performance of the solver itself,\nit also outputs statistics such as the percentage of grids that could be fully cleared,\nthe average score and the average number of remaining blocks.\n\nMost of the parameters accepted by the `generate` and `solve` commands are supported, e.g.:\n\n```\n.\\sgbust benchmark --width 15 --height 15 --num-colors 4 --min-group-size 2 --scoring-group-score n^2-n --max-beam-size 10000 --num-grids 1000\n```\n\nThis will generate 1000 grids with the specified dimensions and parameters and solve them.\n\n## Credits\n\nsgbust relies on the following third-party libraries:\n\n* [CLI11](https://github.com/CLIUtils/CLI11): for command-line help and parsing\n* [mdspan](https://github.com/kokkos/mdspan): for convenient 2D matrix access\n* [mimalloc](https://github.com/microsoft/mimalloc): for significant speed-ups and a reduction in memory usage\n* [Parallel Hashmap](https://github.com/greg7mdp/parallel-hashmap): for efficient parallel execution of the search algorithm\n* [wyhash](https://github.com/wangyi-fudan/wyhash): as a very fast hash function in hash maps\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchausner%2Fsgbust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchausner%2Fsgbust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchausner%2Fsgbust/lists"}