{"id":20290134,"url":"https://github.com/daniel-m-campos/rl-snake-game","last_synced_at":"2026-05-07T12:35:54.254Z","repository":{"id":214419327,"uuid":"337855377","full_name":"daniel-m-campos/RL-Snake-Game","owner":"daniel-m-campos","description":"This is a Reinforcement Learning Snake Game with an NCurses UI","archived":false,"fork":false,"pushed_at":"2021-03-03T20:52:04.000Z","size":503,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-01-14T08:52:29.234Z","etag":null,"topics":["ncurses-ui","reinforcement-learning","sdl2","snake-game"],"latest_commit_sha":null,"homepage":"","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/daniel-m-campos.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}},"created_at":"2021-02-10T21:12:38.000Z","updated_at":"2021-03-25T01:07:51.000Z","dependencies_parsed_at":"2023-12-28T04:25:21.951Z","dependency_job_id":"6f5c1896-2e57-46dc-a7b3-69af8e4c9c7c","html_url":"https://github.com/daniel-m-campos/RL-Snake-Game","commit_stats":null,"previous_names":["daniel-m-campos/rl-snake-game"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-m-campos%2FRL-Snake-Game","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-m-campos%2FRL-Snake-Game/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-m-campos%2FRL-Snake-Game/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-m-campos%2FRL-Snake-Game/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-m-campos","download_url":"https://codeload.github.com/daniel-m-campos/RL-Snake-Game/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241787488,"owners_count":20020099,"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":["ncurses-ui","reinforcement-learning","sdl2","snake-game"],"created_at":"2024-11-14T15:06:24.535Z","updated_at":"2026-05-07T12:35:54.247Z","avatar_url":"https://github.com/daniel-m-campos.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RL Snake Game\n\nA Reinforcement Learning Snake Game written in modern C++23. An NCurses terminal menu lets you:\n\n1. Play snake yourself.\n2. Watch a trained RL bot play.\n3. Train a new RL bot, then watch it play.\n\n### Example\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"snake_game.gif\"/\u003e\n\u003c/p\u003e\n\nThe original snake game code was inspired by [CppND-Capstone-Snake-Game](https://github.com/udacity/CppND-Capstone-Snake-Game).\n\n---\n\n## Dependencies\n\n| Dependency | Version | Notes |\n|---|---|---|\n| CMake | \u003e= 3.28 | [Installation instructions](https://cmake.org/install/) |\n| make | \u003e= 4.1 | Linux/Mac |\n| SDL2 | \u003e= 2.0 | [Installation instructions](https://wiki.libsdl.org/Installation) |\n| NCurses | \u003e= 6.1 | |\n| gcc/g++ or clang++ | C++23 support required | |\n| GoogleTest | v1.15.2 | Fetched automatically via CMake `FetchContent` (tests only) |\n\n### Installing dependencies on Linux\n\n```bash\nsudo add-apt-repository ppa:ubuntu-toolchain-r/test\nsudo apt update\nsudo apt install libsdl2-dev libncurses5-dev libncursesw5-dev\nsudo apt install -y gcc-13 g++-13\nexport CC=gcc-13\nexport CXX=g++-13\n```\n\n### Installing dependencies on macOS\n\n```bash\nbrew install cmake sdl2 ncurses llvm\n```\n\n---\n\n## Building\n\n```bash\n# 1. Clone the repo\ngit clone \u003crepo-url\u003e \u0026\u0026 cd RL-Snake-Game\n\n# 2. Configure and build\ncmake -S . -B build\ncmake --build build\n\n# 3. Run\n./bin/RLSnakeGame\n```\n\n### Building with tests\n\nGoogleTest is fetched automatically by CMake — no manual installation needed.\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake .. -DBUILD_TESTS=ON \u0026\u0026 cmake --build .\nctest --output-on-failure\n```\n\n---\n\n## Training\n\nTraining runs using Q-Learning with ε-greedy exploration. All parameters are editable from the dashboard UI before starting a run.\n\n| Parameter | Default |\n|---|---|\n| Episodes | 1,000 |\n| Max steps per episode | 1,000,000 |\n| Epsilon (ε-greedy) | 0.5 |\n| Discount factor (γ) | 0.9 |\n| Step size (α) | 0.5 |\n| Threads | hardware concurrency |\n| Checkpoint interval | 0 (disabled) |\n\nTraining runs in parallel across multiple threads. Each thread trains an independent Q-table; after all episodes complete (or at each checkpoint), worker Q-tables are merged using a greedy-max strategy (highest Q-value per state-action pair wins). Setting a non-zero checkpoint interval splits training into chunks, saving progress after each chunk and bounding memory usage.\n\nTrained Q-value tables are saved in a compact binary format and loaded automatically when you select \"Watch bot play.\"\n\n---\n\n## Code Structure\n\nHeaders are in `include/`, source files in `src/`, and tests in `tests/`.\n\n### Reinforcement Learning API\n\nTemplate-based tabular RL API. Q-Learning is fully implemented; the interface also supports SARSA and Expected SARSA.\n\n| File | Description |\n|---|---|\n| `include/state_action_map.h` | Maps (state, action) pairs to Q-values |\n| `include/action_valuer.h` | Interface for Q-value lookup and update |\n| `include/policy.h` | Policy interface (ε-greedy implemented) |\n| `include/agent.h` | `Agent` interface and `AgentImpl` |\n| `include/learner.h` | `Learner` interface and `QLearner` |\n| `include/environment.h` | Environment interface |\n| `include/simulator.h` | Runs agent–environment interaction loops |\n| `include/hash_util.h` | Hash combiner for `std::pair` keys in state-action maps |\n\n### Snake Game\n\n| File | Description |\n|---|---|\n| `include/snake.h` / `src/snake.cpp` | Snake entity |\n| `include/food.h` / `src/food.cpp` | Food placement |\n| `include/game.h` / `src/game.cpp` | Core game logic |\n| `include/game_environment.h` / `src/game_environment.cpp` | Wraps the game as an RL `Environment` |\n| `include/game_simulator.h` / `src/game_simulator.cpp` | Runs RL simulation over the game |\n| `include/controller.h` | Controller interface |\n| `include/keyboard_controller.h` / `src/keyboard_controller.cpp` | Human keyboard input |\n| `include/agent_controller.h` / `src/agent_controller.cpp` | Bot controller driven by the RL agent |\n| `include/renderer.h` / `src/renderer.cpp` | SDL2 rendering |\n\n### NCurses UI\n\n| File | Description |\n|---|---|\n| `include/menu.h` / `src/menu.cpp` | Generic menu component |\n| `include/game_menu_factory.h` / `src/game_menu_factory.cpp` | Builds the main game menu |\n| `include/gui.h` / `src/gui.cpp` | Top-level NCurses GUI |\n| `include/dashboard.h` / `src/dashboard.cpp` | Panel-based dashboard with progress rendering |\n\n### IO\n\n| File | Description |\n|---|---|\n| `include/io.h` / `src/io.cpp` | Save and load trained Q-value tables |\n\n### Entry Point\n\n| File | Description |\n|---|---|\n| `include/trainer.h` / `src/trainer.cpp` | Orchestrates single-threaded training runs |\n| `include/parallel_trainer.h` / `src/parallel_trainer.cpp` | Multi-threaded training with Q-table merge |\n| `include/training_config.h` | Training hyperparameters and atomic progress counters |\n| `include/main_utils.h` / `src/main_utils.cpp` | Startup helpers |\n| `src/main.cpp` | `main()` — launches the NCurses GUI |\n\n### Factories\n\n`include/agent_factory.h` and `include/action_valuer_factory.h` assemble RL components, and adapter classes wire the snake game to the RL algorithms and GUI.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-m-campos%2Frl-snake-game","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-m-campos%2Frl-snake-game","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-m-campos%2Frl-snake-game/lists"}