{"id":20724568,"url":"https://github.com/simoninithomas/ml-agents-snowball-fight","last_synced_at":"2025-09-09T11:06:07.400Z","repository":{"id":112538241,"uuid":"319910870","full_name":"simoninithomas/ml-agents-snowball-fight","owner":"simoninithomas","description":"A multi-agent environment using Unity ML-Agents Toolkit","archived":false,"fork":false,"pushed_at":"2020-12-09T16:07:21.000Z","size":250,"stargazers_count":10,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-23T18:04:16.147Z","etag":null,"topics":["ai","artificial-intelligence","deep-learning","deep-reinforcement-learning","mlagents","reinforcement-learning","unity","unity3d"],"latest_commit_sha":null,"homepage":"https://www.simoninithomas.com","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simoninithomas.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":"2020-12-09T09:48:03.000Z","updated_at":"2024-03-13T13:58:50.000Z","dependencies_parsed_at":"2023-05-15T21:15:06.853Z","dependency_job_id":null,"html_url":"https://github.com/simoninithomas/ml-agents-snowball-fight","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simoninithomas%2Fml-agents-snowball-fight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simoninithomas%2Fml-agents-snowball-fight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simoninithomas%2Fml-agents-snowball-fight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simoninithomas%2Fml-agents-snowball-fight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simoninithomas","download_url":"https://codeload.github.com/simoninithomas/ml-agents-snowball-fight/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250487530,"owners_count":21438612,"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":["ai","artificial-intelligence","deep-learning","deep-reinforcement-learning","mlagents","reinforcement-learning","unity","unity3d"],"created_at":"2024-11-17T04:15:30.445Z","updated_at":"2025-04-23T18:04:19.579Z","avatar_url":"https://github.com/simoninithomas.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snowball Fight 🎄☃️, a multi-agent environment for ML-Agents\nA multi-agent environment using Unity ML-Agents Toolkit where four agents compete in a 2vs2 snowball fight game.\n\n\u003cimg src=\"docs/images/snowballfight.png\" align=\"middle\" width=\"3000\"/\u003e\n\n## The Environment\n- Four agents compete **in a 2 vs 2 snowball fight game**.\n- The goal is to **hit the opponent team while avoiding the opponent and your teammate snowballs ❄️**.\n- The aesthetics follows the ML-Agents and the implementation is inspired by the SoccerTwo environment.\n\n### Observation Space\n- Vector Observation space: 336 \n    - **11 ray-casts forward** distributed over 100 degrees.\n    - **3 ray-casts backward** distributed over 90 degrees.\n    - Each  of the raycasts detecting 6 possible object types, along with the object's distance. \n      - Hence each raycast state dimensions = `nb of possible object (6) + Vector3 object's distance (3) * three obs stack (3) = 6+3*3 = 27`.\n      - Therefore, the forward ray-casts contribute 264 state dimensions and backward 72 state dimensions over three observation stacks.\n    - **Bool canShoot** (you can only shoot a snowball every 2 seconds).\n\n### Action Space (Discrete) \n- Vector Action space:\n  - **Four branched actions** corresponding to forward, backward, sideways movement, rotation, and snowball shoot.\n\n### Agent Reward Function (dependant):\n- (1 - accumulated time penalty): when a snowball hit one of the opponents accumulated time penalty is incremented by (1 / MaxStep) every fixed update and is reset to 0 at the beginning of an episode.\n- (-1) When a snowball hit one of the agent of the team.\n\n## How to use it \n- 1️⃣ Download the [ml-agents Release 10](https://github.com/Unity-Technologies/ml-agents/archive/release_10.zip) repository.\n- 2️⃣ Clone this repository.\n### On ML-Agents\n- 3️⃣ Put the `SnowballFight.yaml` file to your ML-Agents folder into `.\\config\\ppo`.\n### On Unity\n- 4️ Open the Unity Project `Project` in ML-Agents repo.\n- 5️ Import package \u003e Custom package `snowballfight.unitypackage` file.\n\n## The next steps\n- (Currently updating it) Allow the simulation to continue until one of the team is completely defeated.\n- Preparing an article that explains how Snowball fight works and multi-agents (Elo rating system, self-play etc), in the meantime if you want to know more about multi-agents check this [amazing blogpost from Unity team](https://blogs.unity3d.com/2020/02/28/training-intelligent-adversaries-using-self-play-with-ml-agents/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimoninithomas%2Fml-agents-snowball-fight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimoninithomas%2Fml-agents-snowball-fight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimoninithomas%2Fml-agents-snowball-fight/lists"}