{"id":28717222,"url":"https://github.com/agarcl/agarcl","last_synced_at":"2026-04-12T11:48:57.737Z","repository":{"id":293404406,"uuid":"983872884","full_name":"AgarCL/AgarCL","owner":"AgarCL","description":"Agar.io for Continual Reinforcement Learning","archived":false,"fork":false,"pushed_at":"2025-05-16T02:43:23.000Z","size":8266,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-15T03:13:56.664Z","etag":null,"topics":["continual-reinforcement-learning","cplusplus","deep-reinforcement-learning","games","python","reinforcement-learning","representation-learning"],"latest_commit_sha":null,"homepage":"https://agarcl.github.io/","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/AgarCL.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":"2025-05-15T03:44:56.000Z","updated_at":"2025-05-27T11:41:46.000Z","dependencies_parsed_at":"2025-05-15T07:34:27.278Z","dependency_job_id":null,"html_url":"https://github.com/AgarCL/AgarCL","commit_stats":null,"previous_names":["agarcl/agarcl"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AgarCL/AgarCL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgarCL%2FAgarCL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgarCL%2FAgarCL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgarCL%2FAgarCL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgarCL%2FAgarCL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgarCL","download_url":"https://codeload.github.com/AgarCL/AgarCL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgarCL%2FAgarCL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273783966,"owners_count":25167494,"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-09-05T02:00:09.113Z","response_time":402,"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":["continual-reinforcement-learning","cplusplus","deep-reinforcement-learning","games","python","reinforcement-learning","representation-learning"],"created_at":"2025-06-15T03:13:49.078Z","updated_at":"2026-04-12T11:48:57.724Z","avatar_url":"https://github.com/AgarCL.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgarCL\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/agarcl_logo.png\" alt=\"AgarCL logo\" width=\"200\"/\u003e\n\u003c/div\u003e\n\n\nA research platform for continual RL that allows for a progression of increasingly sophisticated behaviour.\n\n\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"assets/game_description.png\" alt=\"AgarCL description\" width=\"600\"/\u003e\n\u003c/div\u003e\n\n**AgarCL is based on the game Agar.io.** It's a non-episodic, high-dimensional problem featuring stochastic, ever-evolving dynamics, continuous actions, and partial observability.\n\n## Installation instructions\n\nThe recommended way to use AgarCL is within a Docker container running a Linux OS. This ensures there are no conflicts with other installed packages or platforms. This installation script will allow you to interact with AgarCL in a headless mode.\n\n### Setting up the container\nFollow these steps to set up the container:\n\n1. **Download the Dockerfile**\n   - Download the [Dockerfile.txt](https://github.com/AgarCL/AgarCL/blob/master/Dockerfile.txt).\n   - You can jump to step 4 for instructions to use a pre-built [image](https://hub.docker.com/repository/docker/agarcl/agarclimage/general) that we share.\n\n2. **Navigate to the Directory Containing the Dockerfile**\n   - Open your terminal and navigate to the folder where the `Dockerfile.txt` is located:\n     ```bash\n     cd /path/to/Dockerfile/directory\n     ```\n\n3. **Build the Docker Image**\n   - Build the Docker image by specifying the custom Dockerfile using the `-f` flag:\n     ```bash\n     docker build -f Dockerfile.txt -t agarclimage .\n     ```\n   - Skip to step 5, now that your image is built.\n4. **Directly use the pre-built image**\n   - ```bash\n     docker pull agarcl/agarclimage\n     ```\n     \n\n5. **Run the Docker Container**\n   - Once the image has been built, run the container:\n     ```bash\n     docker run --gpus all -it --name agarclcontainer agarclimage\n     ```\n   - This command will start the container with the name `agarclcontainer`. The `--gpus all` flag tells Docker to use all available GPUs on your host system for the container.\n\n### Installing the AgarCL Platform\n\nNow, let's install the platform on your system (`agarclcontainer` container):\n\n1. **Clone the AgarCL Repository**\n   - Clone the repository with the `--recursive` flag to ensure all submodules are included:\n     ```bash\n     git clone --recursive git@github.com:AgarCL/AgarCL.git\n     ```\n\n2. **Install the Platform**\n   - Change into the `AgarCL` directory:\n     ```bash\n     cd AgarCL\n     ```\n\n   - Run the installation command to set up the platform:\n     ```bash\n     python setup.py install --user\n     ```\n\n   - This will install the platform in your local user environment.\n\n#### Done!\n\n### Installing the AgarCL Platform and benchmarking tools\n\n1. **Clone the AgarCL-benchmark Repository**\n   - Clone the repository:\n     ```bash\n     git clone git@github.com:AgarCL/AgarCL-benchmark.git\n     ```\n\n2. **Navigate to the AgarCL-Benchmark Directory**\n   - Change into the `AgarCL-benchmark` directory:\n     ```bash\n     cd AgarCL-benchmark\n     ```\n\n4. **Clone the AgarCLgit  Repository**\n   - Clone the `AgarCL` repository with the `--recursive` flag to ensure all submodules are included:\n     ```bash\n     git clone --recursive git@github.com:AgarCL/AgarCL.git\n     ```\n\n5. **Navigate to the AgarCL Directory**\n   - Change into the `AgarCL` directory:\n     ```bash\n     cd AgarCL\n     ```\n\n6. **Install the Platform**\n   - Run the installation command to set up the platform:\n     ```bash\n     python setup.py install --user\n     ```\n\n#### Done!\n\n## macOS and Linux Installation Guide\n\n### Installation notes:\n\nEnsure the project is compiled with clang++, not g++\n\n### macOS Installation Guide\n\n\u003e 💡 Before starting:\n\u003e\n\u003e Follow the instructions [here](https://brew.sh/) and make sure you have **homebrew** correctly installed and updated.\n\u003e\n\u003e Make sure **Command Line Tools** are installed properly, follow the [documentation](https://developer.apple.com/xcode/resources/).\n\u003e\n\u003e Note: The installer will automatically install **CMake 3.22** (a compatible version for this project)\n\n\n\nThen follow these steps to set up the AgarCL environment on macOS:\n\n1. **Clone the repository:**\n   ```bash\n   git clone --recursive git@github.com:AgarCL/AgarCL.git\n   ```\n2. **Change into the project directory:**\n   ```bash\n   cd AgarCL\n   ```\n3. **Create a Python virtual environment:**\n   ```bash\n   python -m venv agarclenv\n   ```\n4. **Activate the virtual environment:**\n   ```bash\n   source agarclenv/bin/activate\n   ```\n5. **Run the installer script:**\n   ```bash\n   ./install.sh\n   ```\n6. **Install Python dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n7. **Build \u0026 install the Python package:**\n   ```bash\n   python setup.py install\n    ```\n\n#### Done!\n\n### Linux Installation Guide\n\n1. **Clone the repository:**\n   ```bash\n   git clone --recursive git@github.com:AgarCL/AgarCL.git\n   ```\n2. **Change into the project directory:**\n   ```bash\n   cd AgarCL\n   ```\n3. **Create a Python virtual environment:**\n   ```bash\n   python -m venv agarclenv\n   ```\n4. **Activate the virtual environment:**\n   ```bash\n   source agarclenv/bin/activate\n   ```\n5. **Make the install script executable:**\n   ```bash\n   chmod +x install.sh\n   ```\n\n6. **Run the installer script (may require sudo):**\n   ```bash\n   sudo ./install.sh\n   ```\n7. **Install Python dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n8. **Build and install the Python package:**\n   ```bash\n   python setup.py install\n   ```\n\n## Running the code\nTo run the Go Bigger example, execute the following line:\n\n```python\npython project_path/bench/go_bigger_example.py\n```\n\nTo run the Screen Observations example, execute the following line:\n\n```python\npython project_path/bench/screen_obs_example.py\n```\n\n## Using the environment\n\n\n```python\nimport gymnasium as gym\n\n# Initialise the environment\nenv = gym.make(\"agario-screen-v0\", render_mode=\"human\")\n\n# Reset the environment to generate the first observation\nobservation = env.reset()\nfor _ in range(1000):\n    # this is where you would insert your policy\n    c_target_space = gym.spaces.Box(low=-1, high=1, shape=(2,))\n    d_target_space = gym.spaces.Discrete(3)\n    action = [(c_target_space.sample(), d_target_space.sample())]\n\n    # step (transition) through the environment with the action\n    # receiving the next observation, reward and if the episode has terminated or truncated\n    observation, reward, terminated, truncated, info = env.step(action)\n\n    # If the episode has ended then we can reset to start a new episode\n    if terminated or truncated:\n        observation = env.reset()\n\nenv.close()\n```\n\n### Self-Play setup\n\nIn order to play the game yourself or enable rendering in the gym environment, you will need to build the game\nclient yourself on a system where OpenGL has been installed. Issue the following commands:\n\n\n```shell\ngit submodule update --init --recursive\nmkdir build \u0026\u0026 cd build\ncmake -DCMAKE_BUILD_TYPE=Release ..\nmake -j 2 client agario\n```\n\nThis will output an executable named client in the directory agario\n\n```shell\nagario/client\n```\n\nUse your cursor to control the agent.\n\n\n\n### Loading and Saving Environment Snapshots\n\nAgarCL allows you to save and load snapshots of the environment's state. This feature is useful for debugging, benchmarking, or resuming training from a specific point.\n\n#### Saving a Snapshot\n\nTo save the current state of the environment, use the `save_env_state` method:\n\n```python\nenv.save_env_state('path_to_save_snapshot.json')\n```\n\nThis will save the environment's state to a JSON file at the specified path.\n\n#### Loading a Snapshot\n\nTo load a previously saved snapshot, use the `load_env_state` method:\n\n```python\nenv.load_env_state('path_to_snapshot.json')\n```\nBefore loading a snapshot, ensure that the `load_env_state` option is enabled in the environment configuration. This will allow the environment to restore its state from the specified JSON file.\n\n#### Example Usage\n\nHere is an example of how to use these methods in a script:\n\n```python\nimport gymnasium as gym\n\n# Initialize the environment\nenv = gym.make(\"agario-screen-v0\", render_mode=\"human\")\n\n# Load a snapshot if available\nenv.load_env_state('snapshot.json')\n\n# Reset the environment\nenv.reset()\n\n# Perform some steps\nfor _ in range(100):\n   action = [(env.action_space.sample(), env.action_space.sample())]\n   observation, reward, terminated, truncated, info = env.step(action)\n   if terminated or truncated:\n      break\n\n# Save the environment's state\nenv.save_env_state('snapshot.json')\n\nenv.close()\n```\n\nThis functionality ensures reproducibility and allows for efficient experimentation with different configurations.\n\n### Recording and Saving Videos\n\nAgarCL provides functionality to record and save videos of the environment's execution. This is useful for visualizing agent behavior or debugging.\n\n#### Enabling Video Recording\n\nTo enable video recording, set the `record_video` parameter to `True` in the environment configuration. You can also enable video recording programmatically:\n\n```python\nenv.enable_video_recorder()\n```\n\n#### Saving the Video\n\nTo save the recorded video, use the `generate_video` method:\n\n```python\nenv.generate_video('path_to_save_video', 'video_name.avi')\n```\n\nThis will save the video to the specified path with the given file name.\n\n#### Disabling Video Recording\n\nTo stop recording, use the `disable_video_recorder` method:\n\n```python\nenv.disable_video_recorder()\n```\n\n#### Example Usage\n\nHere is an example of how to record and save a video:\n\n```python\nimport gymnasium as gym\n\n# Initialize the environment\nenv = gym.make(\"agario-screen-v0\", render_mode=\"rgb_array\")\n\n# Enable video recording\nenv.enable_video_recorder()\n\n# Reset the environment\nenv.reset()\n\n# Perform some steps\nfor _ in range(100):\n   action = [(env.action_space.sample(), env.action_space.sample())]\n   observation, reward, terminated, truncated, info = env.step(action)\n   if terminated or truncated:\n      break\n\n# Save the video\nenv.generate_video('videos', 'example_run.avi')\n\n# Disable video recording\nenv.disable_video_recorder()\n\nenv.close()\n```\n\n### Real-Time Render View\n\nDisplay the environment in a live GUI window for debugging, demos, and visually tracking your agent’s decisions as they happen.\n\nAn example of how to invoke the window:\n\n```python\nimport gymnasium as gym\n\n# Initialize the environment\nenv = gym.make(\"agario-screen-v0\", render_mode=\"human\")\n\n# Reset the environment\nenv.reset()\n\n# Perform some steps\nfor _ in range(100):\n   action = [(env.action_space.sample(), env.action_space.sample())]\n   observation, reward, terminated, truncated, info = env.step(action)\n\n   # Update the on-screen display\n   env.render()\n   if terminated or truncated:\n      break\n\nenv.close()\n```\n\n\nThis functionality allows you to capture and analyze the agent's performance visually.\n\n\n## Acknowledgment\nThis implementation is built upon the [AgarLE repository](https://github.com/jondeaton/AgarLE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagarcl%2Fagarcl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagarcl%2Fagarcl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagarcl%2Fagarcl/lists"}