{"id":48512142,"url":"https://github.com/mit-ll/spacegym-od2d","last_synced_at":"2026-04-07T17:33:41.101Z","repository":{"id":94745852,"uuid":"572111206","full_name":"mit-ll/spacegym-od2d","owner":"mit-ll","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-09T18:51:22.000Z","size":72571,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-05-09T20:45:04.428Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/mit-ll.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-11-29T15:20:13.000Z","updated_at":"2024-05-09T18:50:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"97abcc3e-88fb-401d-9f76-9a77eeb6a186","html_url":"https://github.com/mit-ll/spacegym-od2d","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mit-ll/spacegym-od2d","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mit-ll%2Fspacegym-od2d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mit-ll%2Fspacegym-od2d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mit-ll%2Fspacegym-od2d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mit-ll%2Fspacegym-od2d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mit-ll","download_url":"https://codeload.github.com/mit-ll/spacegym-od2d/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mit-ll%2Fspacegym-od2d/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31522438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-07T17:33:40.929Z","updated_at":"2026-04-07T17:33:41.071Z","avatar_url":"https://github.com/mit-ll.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OrbitDefender2D\n\n\n\u003cimg src=\"logo.svg\" width=\"600\"\u003e \n\n## Overview\n\n2D, grid-based board games inspired by the orbital domain\n\n2D environment can be viewed as an orbital plane with objects in circular orbits\n\nSee the wiki for more info: https://github.com/mpj15/spacegym-od2d/wiki\n\n### Design Principles\n\n*TODO*\n\n------------\n\n## Installation\n\nTo install this package, run:\n\n```bash\npip install -e .\n```\n\nFor development of this package, we recommend using the conda environment defined in `environment.yml`. To create and activate this environment, run:\n\n```bash\nconda env create -f environment.yml\nconda activate orbit_defender2d\n```\n\n------------\n\n## Testing\n\nFor developers, unit and integration tests are located in the `tests/` directory and can be run with:\n\n```bash\npytest -v\n```\n\nNote that `test_game_server.py` can sometimes fail if too many processes are running due to slow responses between game servers and clients. It is recommended that tests be run seperately with the following two commands:\n\n```bash\npytest . --ignore=tests/test_game_server.py # run all tests except game server\npytest tests/test_game_server.py            # run game server tests\n```\n------------\n\n## How to Start the Game\n\nFor more details, please see the [__Game Rules Wiki__](https://github.com/mpj15/spacegym-od2d/wiki) and access the User Guide. \n\n1. In a terminal window, navigate to your src folder inside the spacegym-od2d folder from the GitHub repository. \n2. Activate the orbit_defender2d environment by typing the following command: \n\n```bash\nconda activate orbit_defender2d\n```\nNext to your user ID in the terminal, it should now say orbit_defender2d instead of \"base\". \n\n3. Use python to start the game file that you are choosing to run. Please reference the User Guide for a comprehensive list of file names. The following command will run a Human v. AI game. \n\n```bash\npython koth_game_rollout_CLI.py\n```\n\n------------\n\n## Game: King Of the Hill (KOTH)\n\nThe [King of the Hill Game](https://github.com/mit-ll/spacegym-od2d/tree/master/src/orbit_defender2d/king_of_the_hill) is a balanced game of two players. Each player has a collection of satellites (referred to as \"pieces\" or \"tokens\") that they control. Satellites are seperated into categories of point-scoring tokens (\"High Value Asset- HVA\") and defensive/offensive tokens (\"Patrol\"). Each satellites can move about the board by expending fuel and can engage with satellites of the opposing agent. Each player also has a special a goal location, i.e. \"hill\", on which they can place their seeker to score points. The objective of the game is to score more points that your opponent. You can minimize the number of points scored by your opponent by attacking their pieces.\n\nFor comprehensive rule set, please see the [__Game Rules Wiki__](https://github.com/mpj15/spacegym-od2d/wiki)\n\n### KOTH Tutorials\n\nThe KOTH game consists of [core game code](https://github.com/mit-ll/spacegym-od2d/blob/master/src/orbit_defender2d/king_of_the_hill/koth.py) and two interfaces for running the game. To see an example of how the core KOTH game is run (using random, yet valid, actions from each player), see [`core_random_game.py`](https://github.com/mit-ll/spacegym-od2d/blob/master/src/orbit_defender2d/king_of_the_hill/examples/core_random_game.py). This can be executed as:\n\n```bash\npython src/orbit_defender2d/king_of_the_hill/examples/core_random_game.py\n```\n\nThere is a human-playable interface to the game that uses a [game server](https://github.com/mit-ll/spacegym-od2d/blob/master/src/orbit_defender2d/king_of_the_hill/game_server.py) running in python that can talk to a game clients running a Unity-based user interface (_under development, no link at this time_). For an example of running a game using the game server (with random-valid actions and python game clients as stand-ins for the Unity clients), see [`server_random_game.py`](https://github.com/mit-ll/spacegym-od2d/blob/master/src/orbit_defender2d/king_of_the_hill/examples/server_random_game.py). This can be run as:\n\n```bash\npython src/orbit_defender2d/king_of_the_hill/examples/server_random_game.py\n```\n\nThere is also an AI playable that wraps the core KOTH game in a OpenAI Gym-like [environment](hhttps://github.com/mit-ll/spacegym-od2d/blob/master/src/orbit_defender2d/king_of_the_hill/examples/pettingzoo_random_game.py). To enable development of multi-agent RL algorithms we will be using a [PettingZoo](https://github.com/PettingZoo-Team/PettingZoo) environment, which is also described in this [paper](https://arxiv.org/pdf/2009.14471.pdf). For an example of the PettingZoo-wrapped KOTH game, see [`pettingzoo_random_game.py`](). This can be run as:\n\n```bash\npython src/orbit_defender2d/king_of_the_hill/examples/pettingzoo_random_game.py\n```\n\nThe PettingZoo-wrapped game can be visualized based on a rendering function. For example, run\n\n```bash\npython src/orbit_defender2d/king_of_the_hill/examples/pettingzoo_random_rendered_game.py\n```\n\n------------\n\n## Citation\n\n~~\u003e TODO: *Zenodo DOI to be added upon making repo public*\n\n```\n@inproceedings{allen2023spacegym,\n  title={SpaceGym: Discrete and Differential Games in Non-Cooperative Spa\nce Operations},\n  author={Allen, Ross E and Rachlin, Yaron and Ruprecht, Jessica and Loughran, Sean and Varey, Jacob and Viggh, Herbert},\n  booktitle={2023 IEEE Aerospace Conference},\n  pages={1--12},\n  year={2023},\n  organization={IEEE}\n}\n```\n\n------------\n\n## Disclaimer\n\nDISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.\n\nThis material is based upon work supported by the Under Secretary of Defense for Research and Engineering under Air Force Contract No. FA8702-15-D-0001. Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Under Secretary of Defense for Research and Engineering.\n\n© 2022 Massachusetts Institute of Technology.\n\nSubject to FAR52.227-11 Patent Rights - Ownership by the contractor (May 2014)\n\nSPDX-License-Identifier: MIT\n\nThe software/firmware is provided to you on an As-Is basis\n\nDelivered to the U.S. Government with Unlimited Rights, as defined in DFARS Part 252.227-7013 or 7014 (Feb 2014). Notwithstanding any copyright notice, U.S. Government rights in this work are defined by DFARS 252.227-7013 or DFARS 252.227-7014 as detailed above. Use of this work other than as specifically authorized by the U.S. Government may violate any copyrights that exist in this work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmit-ll%2Fspacegym-od2d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmit-ll%2Fspacegym-od2d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmit-ll%2Fspacegym-od2d/lists"}