{"id":13793963,"url":"https://github.com/opendilab/DI-star","last_synced_at":"2025-05-12T20:31:26.132Z","repository":{"id":37209996,"uuid":"382817371","full_name":"opendilab/DI-star","owner":"opendilab","description":"An artificial intelligence platform for the StarCraft II with large-scale distributed training and grand-master agents.","archived":false,"fork":false,"pushed_at":"2025-03-13T10:36:57.000Z","size":20295,"stargazers_count":1264,"open_issues_count":0,"forks_count":119,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-08T09:01:50.140Z","etag":null,"topics":["artificial-intelligence","deep-learning","deep-reinforcement-learning","league","reinforcment-learning","self-play","starcraft2"],"latest_commit_sha":null,"homepage":"","language":"Python","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/opendilab.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}},"created_at":"2021-07-04T09:58:25.000Z","updated_at":"2025-04-05T03:54:05.000Z","dependencies_parsed_at":"2024-05-06T04:35:46.529Z","dependency_job_id":null,"html_url":"https://github.com/opendilab/DI-star","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/opendilab%2FDI-star","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendilab%2FDI-star/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendilab%2FDI-star/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendilab%2FDI-star/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opendilab","download_url":"https://codeload.github.com/opendilab/DI-star/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253816743,"owners_count":21968876,"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":["artificial-intelligence","deep-learning","deep-reinforcement-learning","league","reinforcment-learning","self-play","starcraft2"],"created_at":"2024-08-03T23:00:33.972Z","updated_at":"2025-05-12T20:31:21.096Z","avatar_url":"https://github.com/opendilab.png","language":"Python","funding_links":[],"categories":["时间序列","Open-Source Projects","Python"],"sub_categories":["网络服务_其他","Starcraft Projects"],"readme":"# Overview\nDI-star: A large-scale game AI distributed training platform specially developed for the StarCraft II. We've already trained grand-master AI！This project contains:\n\n- [x] Play demo and test code (try and play with our agent!)\n\n- [x] First version of pre-trained SL and RL agent (only Zerg vs Zerg)\n\n- [x] Training code of Supervised Learning and Reinforcement Learning *(updated by 2022-01-31)*\n\n- [x] Training baseline with limited resource(one PC) and training guidance [here](docs/guidance_to_small_scale_training.md) *(New! updated 2022-04-24)*\n\n- [x] Agents fought with [Harstem (YouTube)](https://www.youtube.com/watch?v=fvQF-24IpXs\u0026t=813s)  *(updated by 2022-04-01)*\n\n- [ ] More stronger pre-trained RL agents *(WIP)*\n\n\n\n## Usage\n\n[Testing software on Windows](docs/installation.md) | [对战软件下载](docs/安装教程.md)\n\nPlease star us (click ![stars - di-star](https://img.shields.io/github/stars/opendilab/di-star?style=social) button in the top-right of this page) to help DI-star agents to grow up faster :)\n\n### Installation\n\nEnvironment requirement:\n\n- Python: 3.6-3.8\n\n\n#### 1.Install StarCraftII\n\n- Download the retail version of StarCraftII: https://starcraft2.com\n\nNote: There is no retail version on Linux, please follow the instruction [here](https://github.com/Blizzard/s2client-proto#downloads)\n\n- Add SC2 installation path to environment variables ```SC2PATH``` (skip this if you use default installation path on MacOS or Windows, which is `C:\\Program Files (x86)\\StarCraft II` or `/Applications/StarCraft II`):\n\n    - On MacOS or Linux, input this in terminal:\n\n        ```shell\n        export SC2PATH=\u003csc2/installation/path\u003e\n        ```\n\n    - On Windows:\n       1. Right-click the Computer icon and choose Properties, or in Windows Control Panel, choose System.\n       2. Choose Advanced system settings.\n        3. On the Advanced tab, click Environment Variables.\n        4. Click New to create a new environment variable, set ```SC2PATH``` as the sc2 installation location.\n        5. After creating or modifying the environment variable, click Apply and then OK to have the change take effect.\n\n\n#### 2.Install distar:\n\n```bash\ngit clone https://github.com/opendilab/DI-star.git\ncd DI-star\npip install -e .\n```\n\n#### 3.Install pytorch:\n\nPytorch Version 1.7.1 and CUDA is recommended, Follow instructions from [pytorch official site](https://pytorch.org/get-started/previous-versions/)\n\n\n\n**Note: GPU is neccessary for decent performance in realtime agent test, you can also use pytorch without cuda, but no performance guaranteed due to inference latency on cpu.\nMake sure you set SC2 at lowest picture quality before testing.**\n\n### Play with pretrained agent\n\n#### 1. Download StarCraftII version 4.10.0\nDouble click the file [data/replays/replay_4.10.0.SC2Replay](data/replays/replay_4.10.0.SC2Replay), StarCraftII version 4.10.0 will be automatically downloaded.\n\nNote: We trained our models with versions from 4.8.2 to 4.9.3. Patch 5.0.9 has came out in March 15, 2022, Some changes have huge impact on performance, so we fix our version at 4.10.0 in evaluation.\n\n#### 2. Download models:\n```bash\npython -m distar.bin.download_model --name rl_model\n```\nNote: Specify `rl_model` or `sl_model` after `--name` to download reinforcement learning model or supervised model.\n\nModel list:\n- `sl_model`: training with human replays, skill is equal to diamond players.\n- `rl_model`: used as default, training with reinforcement learning, skill is equal to master or grandmaster.\n- `Abathur`: one of reinforcement learning models, likes playing mutalisk. \n- `Brakk`:  one of reinforcement learning models, likes lingbane rush.\n- `Dehaka`: one of reinforcement learning models, likes playing roach ravager.\n- `Zagara`: one of reinforcement learning models, likes roach rush.\n\n#### 3. Agent test\nWith the given model, we provide multiple tests with our agent.\n\n##### Play against Agent\n```bash\npython -m distar.bin.play\n```\nIt runs 2 StarCraftII instances. First one is controlled by our RL agent. Human player can play on the second one with full screen like normal game.\n\nNote: \n- GPU and CUDA is required on default, add `--cpu` if you don't have these.\n- Download RL model first or specify other models (like supervised model) with argument `--model1 \u003cmodel_name\u003e`\n- In race cases, 2 StarCraftII instances may lose connection and agent won't issue any action. Please restart when this happens.\n\n##### Agent vs Agent\n```bash\npython -m distar.bin.play --game_type agent_vs_agent\n```\nIt runs 2 StarCraftII instances both controlled by our RL Agent, specify other model path with argument `--model1 \u003cmodel_name\u003e --model2 \u003cmodel_name\u003e`\n\n##### Agent vs Bot\n```bash\npython -m distar.bin.play --game_type agent_vs_bot\n```\nRL agent plays against built-in elite bot.\n\n\n## Building your own agent with our framework\nIt is necessary to build different agents within one code base and still be able to make them play against each other.\nWe implement this by making actor and environment as common components and putting everything related to the agent into one directory.\nThe agent called default under distar/agent is an example of this. Every script under default uses relative import, which \nmakes them portable to anywhere as a whole part. \n\nIf you want to create a new agent with/without our default agent, follow instructions [here](docs/agent.md)\n\nIf you want to train a new agent with our framework, follow instructions below and [here](docs/guidance_to_small_scale_training.md) is a guidance with more details of the whole training pipeline.\n### Supervised Learning\nStarCraftII client is required for replay decoding, follow instructions above.\n```bash\npython -m distar.bin.sl_train --data \u003cpath\u003e\n```\n*path* could be either a directory with replays or a file includes a replay path at each line.\n\nOptionally, separating replay decoding and model training could be more efficient, run the three scripts in different terminals:\n```bash\npython -m distar.bin.sl_train --type coordinator\npython -m distar.bin.sl_train --type learner --remote\npython -m distar.bin.sl_train --type replay_actor --data \u003cpath\u003e\n```\n\nFor distributed training:\n```bash\npython -m distar.bin.sl_train --init_method \u003cinit_method\u003e --rank \u003crank\u003e --world_size \u003cworld_size\u003e\nor\npython -m distar.bin.sl_train --type coordinator\npython -m distar.bin.sl_train --type learner --remote --init_method \u003cinit_method\u003e --rank \u003crank\u003e --world_size \u003cworld_size\u003e\npython -m distar.bin.sl_train --type replay_actor --data \u003cpath\u003e\n```\nHere is an example of training on a machine with 4 GPUs in remote mode:\n```bash\n# Run the following scripts in different terminals (windows).\npython -m distar.bin.sl_train --type coordinator\n# Assume 4 GPUs are on the same machine. \n# If your GPUs are on different machines, you need to configure the init_mehod's IP for each machine.\npython -m distar.bin.sl_train --type learner --remote --init_method tcp://127.0.0.1 --rank 0 --world_size 4\npython -m distar.bin.sl_train --type learner --remote --init_method tcp://127.0.0.1 --rank 1 --world_size 4\npython -m distar.bin.sl_train --type learner --remote --init_method tcp://127.0.0.1 --rank 2 --world_size 4\npython -m distar.bin.sl_train --type learner --remote --init_method tcp://127.0.0.1 --rank 3 --world_size 4\npython -m distar.bin.sl_train --type replay_actor --data \u003cpath\u003e\n```\n### Reinforcement Learning\nReinforcement learning will use supervised model as initial model, please download it first, StarCraftII client is also required.\n\n##### 1. Training against bots in StarCraftII: \n```bash\npython -m disatr.bin.rl_train\n```\n\n##### 2. Training with self-play\n```bash\npython -m disatr.bin.rl_train --task selfplay\n```\n\nFour components are used for RL training, just like SL training, they can be executed through different process:\n```bash\npython -m distar.bin.rl_train --type league --task selfplay\npython -m distar.bin.rl_train --type coordinator\npython -m distar.bin.rl_train --type learner\npython -m distar.bin.rl_train --type actor\n```\n\nDistributed training is also supported like SL training.\n\n### Chat group\nSlack: [link](https://join.slack.com/t/opendilab/shared_invite/zt-v9tmv4fp-nUBAQEH1_Kuyu_q4plBssQ)\n\n\nDiscord server: [link](https://discord.gg/dkZS2JF56X)\n\n## Citation\n```latex\n@misc{distar,\n    title={DI-star: An Open-sourse Reinforcement Learning Framework for StarCraftII},\n    author={DI-star Contributors},\n    publisher = {GitHub},\n    howpublished = {\\url{https://github.com/opendilab/DI-star}},\n    year={2021},\n}\n```\n\n## License\nDI-star released under the Apache 2.0 license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopendilab%2FDI-star","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopendilab%2FDI-star","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopendilab%2FDI-star/lists"}