{"id":25295940,"url":"https://github.com/sleleu/learn2slither","last_synced_at":"2026-02-08T08:32:48.503Z","repository":{"id":276707603,"uuid":"922909417","full_name":"Sleleu/Learn2slither","owner":"Sleleu","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-10T21:55:03.000Z","size":742,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-14T16:03:07.640Z","etag":null,"topics":["42","ai","deep-q-learning","learn2slither","q-learning","reinforcement-learning","snake"],"latest_commit_sha":null,"homepage":"","language":"Python","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/Sleleu.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":"2025-01-27T10:04:00.000Z","updated_at":"2025-02-13T00:13:20.000Z","dependencies_parsed_at":"2025-02-10T01:24:07.671Z","dependency_job_id":"826bc269-e78d-4e85-98b0-e77eefdde4b4","html_url":"https://github.com/Sleleu/Learn2slither","commit_stats":null,"previous_names":["sleleu/ai_snake","sleleu/learn2slither"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Sleleu/Learn2slither","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2FLearn2slither","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2FLearn2slither/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2FLearn2slither/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2FLearn2slither/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sleleu","download_url":"https://codeload.github.com/Sleleu/Learn2slither/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2FLearn2slither/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259843315,"owners_count":22920309,"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":["42","ai","deep-q-learning","learn2slither","q-learning","reinforcement-learning","snake"],"created_at":"2025-02-13T02:54:15.619Z","updated_at":"2026-02-08T08:32:48.440Z","avatar_url":"https://github.com/Sleleu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About the project\n\nLearn2Slither is a 42 school project focused on implementing a **reinforcement learning** agent for the Snake game.\nThe project involves creating an AI that learns to navigate through **Q-learning** implementation, enabling the snake to collect apples while avoiding collisions.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/ebab6150-fe64-4f54-a344-6780dcea2856\" alt=\"Snake Game Learning Process\"\u003e\n\u003c/p\u003e\n\n## Environment Specifications\n\n- Board size: 10x10 grid\n- Two green apples randomly placed (increase snake length)\n- One red apple randomly placed (decrease snake length)\n- Initial snake length: 3 cells\n- Game ending conditions: wall collision, self-collision, or zero length\n\n## States and Actions\nThe snake agent operates with information from **four directions around its head**, representing its local perception of the environment.\n\n![screenshotsnake](https://github.com/user-attachments/assets/0e744551-0f7d-437e-a55e-44d7c04e107d)\n\n\nThis restriction shapes the state space and decision-making process. The agent's actions are limited to four directional movements: UP, LEFT, DOWN, and RIGHT.\n\n## Neural Architecture\n\nThe agent processes information about the game state through a simple **deep neural network (DNN)** with multiple layers. The architecture begins with 20 input neurons that capture essential environmental data, processes this through two hidden layers, and produces action values through the output layer.\n\n### Input Layer (20 neurons)\nThe input layer consists of two types of environmental sensors:\n\n#### Distance Measurements (16 neurons)\nEach direction contains 4 normalized distance values representing:\n\n- Distance to the nearest **wall**\n- Distance to the nearest **green apple**\n- Distance to the nearest **red apple**\n- Distance to the nearest **snake body segment**\n\n#### Danger Detection (4 neurons)\nFour binary neurons (0 or 1) detect **immediate collision threats in adjacent cells**. These neurons activate when:\n\n- A wall is directly adjacent in that direction\n- A snake body segment is directly adjacent in that direction\n\n### Hidden Layers\n\nThe network processes this input through two hidden layers:\n\n- **First hidden layer** contains 128 neurons, allowing for complex pattern recognition\n- **Second hidden layer** contains 64 neurons, further refining these patterns\n\n### Output Layer\n\nThe final layer consists of 4 neurons, each corresponding to a possible movement direction (UP, DOWN, LEFT, RIGHT). These neurons output **Q-values**, representing the **expected future reward for each action** in the current state.\n\n## Bonus Features\nBonus points are awarded for:\n\n- Achieving snake lengths beyond 10 during sessions (15, 20, 25, 30, 35)\n- Creating a polished visual interface\n- Enabling the snake to generalize its learning across different grid sizes\n\n\n# Installation\n\n## Prerequisites\n- Python 3.9 or higher\n- pip (Python package manager)\n- git\n\n## Installation instructions\n\n```bash\n# Clone repository\ngit clone https://github.com/Sleleu/AI_Snake.git\n\n# Go to directory\ncd AI_snake\n\n# Create virtual environnement\npython3 -m venv .venv\n\n# Activate virtual environnement\n# Linux/macOS:\nsource .venv/bin/activate\n# Windows:\n# .venv\\Scripts\\activate\n\n# Install required packages in virtual environnement\npip install -r requirements.txt\n```\n\n# Usage\n\nThe program can be run with various options to control its behavior:\n\n`python3 main.py [options]`\n\n## Available Options\n\n#### Training and Model Management\n- `-t, --train`: Enable training mode for the AI agent\n- `-e EPISODE, --episode EPISODE`: Specify the number of episodes to run\n- `-m MODEL, --model MODEL`: Load a pre-trained model from a specified path\n\n#### Visualization and Debug\n- `-v {on,off}, --visual {on,off}`: Enable or disable the GUI (if you want to train your model faster, disable visualization to reduce computational overhead)\n- `-step-by-step`: Enable step-by-step mode for detailed observation\n- `-plot OUTPUT_FILENAME`: Save training statistics plots to a specified filename\n\nExample of a training statistics plot:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/b1c45ba2-bc71-4a03-bee6-717c135ee9fd\" alt=\"Training Statistics Plot\" width=\"600\"\u003e\n\u003c/p\u003e\n\n#### Game Modes\n\n- `-p, --player`: Enable player mode to play the game manually\n\n## Usage Examples\nTrain the AI for 1000 episodes with visualization:\n```bash\npython3 main.py -t -e 1000\n```\n\nLoad a pre-trained model and watch it play:\n```bash\npython3 main.py -m model/trained_model.pth\n```\n\nTrain without visualization for faster processing:\n```bash\npython3 main.py -t -e 1000 -v off\n```\n\n## Settings\n\nYou can modify basic parameters in `settings.py` like grid size, fruit population, initial snake length and game speed. Since a model can generalize its learning across different grid sizes, you can experiment with settings like:\n\n```python\n# Default game size\nGRID_SIZE = 30\nCELL_SIZE = 15\n...\n# Default game settings\nSNAKE_SIZE = 3\nGREEN_FRUITS_NB = 300\nRED_FRUITS_NB = 300\n...\n# Game speed\nFPS = 150\n```\nHere's what it looks like in action:\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/548346d3-9ac9-4d2c-a130-b12b671396e6\" alt=\"Large Snake Game Environment\"\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleleu%2Flearn2slither","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsleleu%2Flearn2slither","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleleu%2Flearn2slither/lists"}