{"id":20930198,"url":"https://github.com/dpbm/snake-ai","last_synced_at":"2026-04-10T23:06:01.706Z","repository":{"id":216523099,"uuid":"731827940","full_name":"Dpbm/snake-ai","owner":"Dpbm","description":"A simple AI in pure c++ to play the snake game","archived":false,"fork":false,"pushed_at":"2024-05-14T17:53:51.000Z","size":677,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-15T12:42:26.438Z","etag":null,"topics":["algorithms","c","cmake","cpp","ctest","dot-product","games","games-ai","games-ia","genetic-algorithm","google-test","machine-learning","machine-learning-algorithms","make","matrix","snake-game"],"latest_commit_sha":null,"homepage":"https://dpbm.github.io/snake-ai/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dpbm.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-12-15T01:20:29.000Z","updated_at":"2024-05-20T02:30:32.297Z","dependencies_parsed_at":"2024-02-10T19:28:49.031Z","dependency_job_id":"6261f575-5e80-498f-8523-61b060c4cc48","html_url":"https://github.com/Dpbm/snake-ai","commit_stats":null,"previous_names":["dpbm/genetic-algorithm","dpbm/snake-ai"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dpbm%2Fsnake-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dpbm%2Fsnake-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dpbm%2Fsnake-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dpbm%2Fsnake-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dpbm","download_url":"https://codeload.github.com/Dpbm/snake-ai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243324266,"owners_count":20273100,"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":["algorithms","c","cmake","cpp","ctest","dot-product","games","games-ai","games-ia","genetic-algorithm","google-test","machine-learning","machine-learning-algorithms","make","matrix","snake-game"],"created_at":"2024-11-18T21:29:49.885Z","updated_at":"2025-12-28T23:29:55.714Z","avatar_url":"https://github.com/Dpbm.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snake AI\n\n\n\n\nhttps://github.com/Dpbm/snake-ai/assets/75098594/81120c76-1979-4c08-8647-6a0fb24e64d4\n\n\n\n\n![Build-Test workflow (cmake)](https://github.com/Dpbm/snake-ai/actions/workflows/cmake-build-test.yml/badge.svg)\n![Docker Hub publish](https://github.com/Dpbm/snake-ai/actions/workflows/dockerhub.yml/badge.svg)\n![GHRC publish](https://github.com/Dpbm/snake-ai/actions/workflows/ghrc.yml/badge.svg)\n\nFor this project, my idea was to explore some algorithms, such as genetic algorithms and Qubo, and \ntechnologies, like C++, to develop something I've always wanted to, all from scratch! \n\nThe urge to build a snake game AI came after I watched some YouTube videos, which inspired me to create something different and just for fun, some of them are listed bellow:\n\n[![Artificial Intelligence in Google's Dinosaur (English Sub)](https://img.youtube.com/vi/P7XHzqZjXQs/0.jpg)](https://youtu.be/P7XHzqZjXQs)\n[![Rede Neural aprendendo a jogar o jogo da cobrinha (SNAKE)\n](https://img.youtube.com/vi/awz1ghokP3k/0.jpg)](https://youtu.be/awz1ghokP3k)\n[![MarI/O - Machine Learning for Video Games](https://img.youtube.com/vi/qv6UVOQ0F44/0.jpg)](https://youtu.be/qv6UVOQ0F44)\n\n\n## Technologies\n\nThe Technologies used were:\n\n* [git](https://git-scm.com/)\n* [SDL2](https://www.libsdl.org/)\n* [C++](https://isocpp.org/)\n* [make](https://www.gnu.org/software/make/)/[cmake](https://cmake.org/)\n* [googletest (ctest)](https://google.github.io/googletest/)\n* [sh](https://www.gnu.org/software/bash/)\n* [Github actions](https://docs.github.com/en/actions)\n* [python 3.10](https://www.python.org/) (used to test the QUBO model)\n* [pygame](https://www.pygame.org/)\n* [docker](https://www.docker.com/)\n* [docker compose](https://docs.docker.com/compose/)\n\n\n## Different modes\n\nIn this version of snake game, I've implemented 3 game modes:\n\n### Play as human\n\nAs the classic one, your can play and enjoy the game by yourself, without any machine inteligent agent.\n\n`PRESS D` to start playing and use the `WASD` to move the snake around.\n\n\n\nhttps://github.com/Dpbm/snake-ai/assets/75098594/c66b2d44-d027-446a-ba97-bae4b6e7269e\n\n\n\n### AI\n\nIn the AI version, you have 2 screens to select either train the AI or let the AI play.\n\n#### Train AI\nTo train the AI `PRESS A` and let her learn to play. If you want you can `PRESS S` during the training to save the best individual weights, but after each generation a weights file is save with the best one. If you want to go back from the training module, you can also `PRESS R` to return to the main Screen.\n\n\n\nhttps://github.com/Dpbm/snake-ai/assets/75098594/71f9e79c-d6b0-4472-a7f9-cab7c918636b\n\n\n\n#### Let the AI play\n\nAfter acquaring the weights file (`.wg`), you can put them into an AI agent to play. To do that, just `PRESS S` at the main SCreen, and import your `.wg` file.\n\n\n### QUBO\n\nThe last mode, is based on QUBO model. This one has a mathematical an expression with some binary variables, and the goal is to minimize it using different combinations for these binary variables.\n\n$$\\sum_{i = 0}^{2}{Q_{ii}x_{i}} + P((\\sum_{i = 0}^{2}{x_{i}})-1)^2$$\n\nIn this expression, $Q$ is a matrix with the distances between the player and the food, which:\n\n```\nQ[0][0] = distance if the player go foward (in the same direction he was)\nQ[1][1] = distance if the player go down/right \nQ[2][2] = distance if the player go up/left\n\nanything else are just zeros\n```\n\n$x_i$ is the binary variable $i$. $P$ is a penality value, in this case we used $(window_{height}*window_{width}) + 10$, the penality part ensures that only one movement will be passed as outcome (either $001$, $010$ or $100$).\n\nTo play this one, `PRESS Q` at the start Screen.\n\n\n\nhttps://github.com/Dpbm/snake-ai/assets/75098594/341a7d76-11cf-4371-9a8f-ba7a36f9fcd3\n\n\n\n## Usage\n\nAll the following usage ways are focused on `Ubuntu` based distros, so some steps may differ for different OS. Remember to check the tools documentation for your system. \n\n### Docker\n\nThe simplest way to run it, is by using Docker. \n\nFirst pull the image:\n```bash\ndocker pull dpbm32/snake-ai\n\n# or using the GHRC version\ndocker pull ghcr.io/dpbm/snake-ai:latest\n```\n\nThen you must grant access to your `XDisplay`.\n\n```bash\nxhost +local:root\n\n# remeber revoking access after using it\nxhost -local:root\n```\n\nAlso, setup a docker volume for the neural network weights output.\n\n```bash\ndocker volume create weights-out\n```\n\nFinally run the image:\n\n```bash\ndocker run -v /tmp/.X11-unix:/tmp/.X11-unix:ro \\\n           -v /path/to/your/weights/input/folder/optional/:/snake/weights_input/ \\\n           --mount source=weights-out,target=/snake/weights_output/ \\\n           -e DISPLAY=$DISPLAY \\\n           -e WPATH=/snake/weights_output/ \\\n           snake-ai\n```\n\n### Docker build local\n\nAnother way to do that is build the image by yourself. To do that run:\n\n```bash\ndocker build -t snake-ai .\n```\n\nThen follow the steps after the `docker pull` from the [#docker section](#docker).\n\n### Docker compose\n\nFinally, There's a [compose file](compose.yaml) in the project directory that you can use to orchestrate the image requirements. \n\nAfter creating a volume and giving the `XDisplay` permissions, run:\n\n```bash\ndocker compose up\n```\n\n### Dev Build\n\nTo build the and run the project, you must the following tools and libraries installed:\n\n* [git](https://git-scm.com/)\n* [SDL2](https://www.libsdl.org/)\n* [C++](https://isocpp.org/)\n* [make](https://www.gnu.org/software/make/)\n* [cmake](https://cmake.org/)\n* [sh](https://www.gnu.org/software/bash/)\n\nThen, clone the project and run the `compilation script`:\n\n```bash\ngit clone https://github.com/Dpbm/snake-ai\ncd ./snake-ai\nchmod +x ./compile.sh ./clean.sh\n./clean.sh \u0026\u0026 ./compile.sh main.cpp\n```\n\nFinally, run the game:\n\n```bash\nLC_NUMERIC=\"C\" ./build/snake\n\n# or, if you want to set a different path to the output weights\nLC_NUMERIC=\"C\" WPATH=\"/path/to/save/the/weights/\" ./build/snake\n\n```\n\n\n### Tests\n\nIn case you want to run the tests by your own, do the following:\n\n```bash\ncd build\nctest\n```\n\n### Qubo test\n\nFinally, inside this repo, there's a subproject made in python to test the Qubo model and how we could use it to play snake game.\nTo access this piece of software:\n\nInstall the dependencies: \n\n```bash\npip install -r requirements.txt #use python\u003e=3.10\n\n#or using conda (recommended)\n\n# in case you don't have conda-lock installed\n# pip install conda-lock \nconda-lock install -n snake-ai conda-lock.yml\nconda activate snake-ai\n```\n\nand run:\n\n```bash\npython ./pygame-qubo-test/main.py\n```\n\n\n\nhttps://github.com/Dpbm/snake-ai/assets/75098594/783bd111-b414-4b62-893c-becf346cb6c8\n\n\nIf you want to understand how the tests to map the qubo version were done, you can do:\n\n```\n# in case you used pip before\n# pip install -r requirements-dev.txt\n\njupyter lab qubo-test.ipynb\n```\n\n\n## Credits\n\nFonts were taken from: [CodeMan38 Google fonts](https://fonts.google.com/specimen/Press+Start+2P)\\\nnativefiledialog-extended by [btzy](https://github.com/btzy/nativefiledialog-extended)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpbm%2Fsnake-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpbm%2Fsnake-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpbm%2Fsnake-ai/lists"}