Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • stebr364/pycommandcenter
  • starcraft-ai-course/pycommandcenter
  • eriah592/pycommandcenter
  • edvbe696/pycommandcenter
  • dawab699/pycommandcenter
  • hanja189/pycommandcenter
  • teoga849/pycommandcenter
  • musab250/pycommandcenter
  • emibr898/pycommandcenter
  • chrgu102/pycommandcenter
  • axega544/pycommandcenter
  • edvth289/pycommandcenter
  • jonbo278/py-command-center-v-2
13 results
Show changes
Commits on Source (313)
213 additional commits have been omitted to prevent performance issues.
Hide whitespace changes
Inline Side-by-side
Showing
with 1012 additions and 155 deletions
.gitignore
View file @ 8cf95a69
build/
.idea
.venv
.vs
.vscode
__pycache__
.DS_Store
\ No newline at end of file
.gitlab-ci.yml 0 → 100644
View file @ 8cf95a69
image: gitlab.liu.se:5000/starcraft-ai-course/pycommandcenter
stages:
- compile
- deploy
compile:
variables:
GIT_SUBMODULE_STRATEGY: recursive
stage: compile
script:
- mkdir build
- cd build
- cmake ..
- make commandcenter
artifacts:
paths:
- docs
- build
- scripts/generate_pydocs.py
expire_in: 10 minutes
only:
- master
pages:
variables:
GIT_STRATEGY: none
GIT_CHECKOUT: false
stage: deploy
script:
- cd docs
- python3 -c "import sys, os, conf, commandcenter"
- make html
- cd ..
- mkdir public
- cp -r docs/_build/html/* public
artifacts:
paths:
- public
only:
- master
pack-linux:
variables:
GIT_STRATEGY: none
GIT_CHECKOUT: false
stage: deploy
script:
- cd build/python-api-src
- stubgen -m commandcenter -o .
- cd ../..
- python3 scripts/generate_pydocs.py
artifacts:
paths:
- build/python-api-src/commandcenter.cpython-312-x86_64-linux-gnu.so
- build/python-api-src/commandcenter.pyi
only:
- master
.gitmodules
View file @ 8cf95a69
[submodule "lib/pybind11"]
path = lib/pybind11
url = https://github.com/pybind/pybind11
[submodule "lib/s2client-api"]
path = lib/s2client-api
url = git@github.com:Blizzard/s2client-api.git
[submodule "lib/cpp-sc2"]
path = lib/cpp-sc2
url = https://github.com/cpp-sc2/cpp-sc2.git
[submodule "lib/sc2-gamedata"]
path = lib/sc2-gamedata
url = https://github.com/noorus/sc2-gamedata.git
[submodule "lib/json"]
path = lib/json
url = https://github.com/nlohmann/json.git
[submodule "lib/sc2-techtree"]
path = lib/sc2-techtree
url = https://github.com/BurnySc2/sc2-techtree.git
CMakeLists.txt
View file @ 8cf95a69
cmake_minimum_required (VERSION 3.6)
cmake_minimum_required (VERSION 3.5)
project (starcraft-python-api)
# Build with C++14 support, required by sc2api
......@@ -14,15 +14,26 @@ set(BUILD_API_EXAMPLES OFF CACHE INTERNAL "" FORCE)
set(BUILD_API_TESTS OFF CACHE INTERNAL "" FORCE)
add_subdirectory(lib/pybind11)
add_subdirectory(lib/s2client-api)
add_subdirectory(lib/cpp-sc2)
add_subdirectory(src)
add_subdirectory(python-api-src)
# Hack to make compile, these flags are otherwise set to give errors on warnings
set_target_properties(sc2api PROPERTIES COMPILE_FLAGS "/W4")
set_target_properties(sc2lib PROPERTIES COMPILE_FLAGS "/W4")
set_target_properties(sc2renderer PROPERTIES COMPILE_FLAGS "/W4")
set_target_properties(sc2utils PROPERTIES COMPILE_FLAGS "/W3")
set_target_properties(sc2protocol PROPERTIES COMPILE_FLAGS "/W0")
if (MSVC)
set_target_properties(sc2api PROPERTIES COMPILE_FLAGS "/W4")
set_target_properties(sc2lib PROPERTIES COMPILE_FLAGS "/W4")
set_target_properties(sc2renderer PROPERTIES COMPILE_FLAGS "/W4")
set_target_properties(sc2utils PROPERTIES COMPILE_FLAGS "/W3")
set_target_properties(sc2protocol PROPERTIES COMPILE_FLAGS "/W0")
set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT CommandCenter)
endif (MSVC)
set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT CommandCenter)
if(UNIX AND NOT APPLE)
set_target_properties(libprotobuf PROPERTIES POSITION_INDEPENDENT_CODE ON)
set_target_properties(sc2api PROPERTIES POSITION_INDEPENDENT_CODE ON)
set_target_properties(sc2lib PROPERTIES POSITION_INDEPENDENT_CODE ON)
set_target_properties(sc2renderer PROPERTIES POSITION_INDEPENDENT_CODE ON)
set_target_properties(sc2utils PROPERTIES POSITION_INDEPENDENT_CODE ON)
set_target_properties(sc2protocol PROPERTIES POSITION_INDEPENDENT_CODE ON)
set_target_properties(civetweb-c-library PROPERTIES POSITION_INDEPENDENT_CODE ON)
endif()
CONTRIBUTING.md 0 → 100644
View file @ 8cf95a69
# Extending the API
This is a guide for extending the API and adding more functionality to the courses TDDE25 and TDDD92.
If a function already exist but you can't use it in python, check and see if it's exist in the library files (pybind).
1. Create a declaration of your function in the header file.
2. Create a definition of your function in the source file.
3. Depending on which object you decided to extend, you should also add this function to the library file. The library is the pybind, making it possible to use your function in python.
4. Update the documentation. There are instructions on how you build and test the documentation.
Example:
We want to add function to unit, returning a bool depending on if it's holding a mineral. We have discovered a function in the SC2 API containing this information (sc2_client.ccp). This is a helper function, it doesn't belong to any object.
1. In unit.h: ```bool isCarryingMinerals() const;```
2. In unit.cpp: ```bool Unit::isCarryingMinerals() const
{
return sc2::IsCarryingMinerals(*m_unit);
}```
We can access m_unit in the unit file and with sc2::Function() we can access any function in the blizzard API that doesn't belong to any object. The same goes for any object, for example sc2::Point3D makes us able to access the Point3D object.
3. In lib_unit.cpp: ```.def_property_readonly("is_carrying_minerals", &Unit::isCarryingMinerals)```
4. In the folder named docs we update the documentation. In this case, we update the file unit.rst.
Common problems:
1. The return in python is a memory address:
Make sure that it returns a correct type.
2. The compiler complains about files I have not even touched:
Make sure that the startUp is library and you have release x64. If you just added a new function in pybind, check it.
LICENSE
View file @ 8cf95a69
MIT License
Copyright (c) 2024 Daniel de Leng
Copyright (c) 2018 Jonas Kvarnström, David Bergström
Copyright (c) 2017 David Churchill
Permission is hereby granted, free of charge, to any person obtaining a copy
......
README.md 0 → 100644
View file @ 8cf95a69
# PyCommandCenter: Library for making bots for Starcraft II
PyCommandCenter is a slimmed down version of the popular Starcraft AI
[CommandCenter](https://github.com/davechurchill/commandcenter) connected to
Python.
Key differences:
* Library made for use with Python, made possible by binding existing C++ code
to Python using [pybind11](https://github.com/pybind/pybind11)
* No decision-making, only perception
* Improved TechTree, by importing data from the JSON files provided by
[sc2-gamedata](https://github.com/noorus/sc2-gamedata)
* Everything is built using cmake, allowing for one Visual studio project to
build PyCommandCenter together with all its dependencies
[Download page for Windows](https://gitlab.liu.se/starcraft-ai-course/pycommandcenter/-/tags)
[Wiki page describing how to use it](http://starcraft-ai-course.gitlab-pages.liu.se/pycommandcenter/index.html)
# Code example for making a bot
``` python
import os
from commandcenter import *
class MyAgent(IDABot):
def __init__(self):
IDABot.__init__(self)
def on_game_start(self):
IDABot.on_game_start(self)
def on_step(self):
IDABot.on_step(self)
def main():
coordinator = Coordinator()
bot1 = MyAgent()
participant_1 = create_participants(Race.Terran, bot1)
participant_2 = create_computer(Race.Random, Difficulty.Easy)
coordinator.set_participants([participant_1, participant_2])
coordinator.launch_starcraft()
path = os.path.join(os.getcwd(), "maps", "InterloperTest.SC2Map")
coordinator.start_game(path)
while coordinator.update():
pass
if __name__ == "__main__":
main()
```
# How to build (Windows)
First you need to make sure you got all the build dependencies:
* cmake, installed at C:\Program Files\CMake
* Visual Studio 2022
* git
* python 3.12
If you ever want to make any changes to the library, e.g. adding new features or making bug fixes, it's easier to fork the project before cloning the repository. For instructions on how to fork, see [the gitlab documentation](https://gitlab.liu.se/help/gitlab-basics/fork-project.md).
Now, you are ready to build the python library:
1. Open up a terminal, download the source code using the command: `git clone --recurse-submodules https://gitlab.liu.se/starcraft-ai-course/pycommandcenter.git`
2. Next, open the repository in your file viewer and run the batch script
called `scripts\create-visual-studio-solution-python312.bat`.
3. The file will be located at `build\python-api-src\Release` and its
name will depend on the python version used.
# How to build (Linux)
Same dependencies applies as for Windows, although you don't need Visual
Studio.
1. Open up a terminal, download the source code using the command: `git clone --recurse-submodules https://gitlab.liu.se/starcraft-ai-course/pycommandcenter.git`
2. Next, enter the directory and run the command `mkdir build` followed by `cd
build` and `cmake ..` in order to create the makefiles needed for building the
library.
3. Run `make` to build the project (use `make -j N` if you want to use N
threads)
# Create autocomplete stub
Make sure you have mypy installed. This can be done with:
```terminal
pip3 install -r requirements.txt
```
Navigate to where your commandcenter.pyd/so is located then run:
```terminal
stubgen -m commandcenter -o .
```
NOTE: stubgen might not work on windows unless you have an active python venv.
After creating the .pyi file run the generate_pydocs.py file according to the instructions in that file.
# How to use the library with PyCharm
Start by downloading the library. Click the latest tag in the [PyCommandCenter repository](https://gitlab.liu.se/starcraft-ai-course/pycommandcenter/-/tags) and find a `.pyd` link at the bottom of the tag page.
Place the library in your repository.
Add the library to the Python path in Python by:
1. File->Settings->Project: (project name)->Project Interpreter.
2. Select the cog in the upper right corner and select "Show All".
3. In the new window that opens, select the icon which shows a few folders connected with lines.
4. In the new window, first press the plus icon, and then select the path of your repository (the path to where you placed the library).
5. Restart PyCharm with "File->Invalidate Caches/Restart->Invalidate and Restart".
# Building the documentation
1. Build the library binary as described above, the documentation uses the
binary to automate some parts
2. Install [Sphinx](http://www.sphinx-doc.org)
This can be done with:
```terminal
pip3 install -r requirements.txt
```
3. Go to the `docs` subfolder,
4. If you are **not** running Visual Studio and building in Release mode you
have to change row 17 of [conf.py](docs/conf.py) to match the location
of the resulting `pyd` file
5. Build the documentation:
* If you are using Windows, open a terminal, navigate to the docs/ folder
and run the command `python -m sphinx . _build` (alternatively: `make.bat html`).
* If you are using Linux, open a terminal, navigate to the docs/ folder and
run the command `make html`
# Credits
PyCommandCenter is written and maintained for Linköping University through various contributors over the years. In alphabetical ordering, these include: Sofia Abaied, Dawid Lukasz Abucewicz, Anton Andell, Erik Ahlroth, David Bergström, Edvin Bergström, Jonas Bonnaudet, Emil Brynielsson, Stefan Brynielsson, Ludvig Fors, Hannes Jämtner, Jonas Kvarnström, Daniel de Leng, Fredrik Präntare, Gabriel Tofvesson, David Warnquist, Jonathan Öhrling. Feedback was provided by the teachers and students of TDDD63, TDDE25, and TDDD92.
CommandCenter is written by [David Churchill](http://www.cs.mun.ca/~dchurchill/), Assistant Professor of [Computer Science](https://www.cs.mun.ca/) at Memorial University, and organizer of the [AIIDE StarCraft AI
Competition](http://www.cs.mun.ca/~dchurchill/starcraftaicomp/).
CommandCenter is in turn based on the Blizzard's [StarCraft II AI
API](https://github.com/Blizzard/s2client-api) and the architecture of
[UAlbertaBot](https://github.com/davechurchill/ualbertabot/wiki).
bin/BotConfig.txt deleted 100644 → 0
View file @ ff440799
{
"Bot Info" :
{
"BotName" : "CommandCenter",
"Authors" : "David Churchill",
"PrintInfoOnStart" : false
},
"BWAPI" :
{
"SetLocalSpeed" : 5,
"SetFrameSkip" : 0,
"UserInput" : true,
"CompleteMapInformation" : false
},
"SC2API" :
{
"BotRace" : "Terran",
"EnemyDifficulty" : 2,
"EnemyRace" : "Random",
"MapFile" : "InterloperTest.SC2Map",
"StepSize" : 1
},
"Micro" :
{
"KiteWithRangedUnits" : false,
"ScoutHarassEnemy" : true
},
"Macro" :
{
"WorkersPerRefinery" : 3,
"BuildingSpacing" : 0,
"PylonSpacing" : 3
},
"Debug" :
{
"DrawGameInfo" : true,
"DrawProductionInfo" : true,
"DrawBaseLocationInfo" : true,
"DrawTileInfo" : false,
"DrawWalkableSectors" : false,
"DrawScoutInfo" : false,
"DrawEnemyUnitInfo" : false,
"DrawResourceInfo" : false,
"DrawUnitTargetInfo" : false,
"DrawLastSeenTileInfo" : false,
"DrawSquadInfo" : false,
"DrawWorkerInfo" : false,
"DrawBuildingInfo" : false,
"DrawReservedBuildingTiles" : false
},
"Modules" :
{
"UseAutoObserver" : false
},
"BWAPI Strategy" :
{
"Protoss" : "Protoss_ZealotRush",
"Terran" : "Terran_MarineRush",
"Zerg" : "Zerg_ZerglingRush",
"ScoutHarassEnemy" : true,
"Strategies" :
{
"Protoss_ZealotRush" :
{
"Race" : "Protoss",
"OpeningBuildOrder" : ["Probe", "Probe", "Probe", "Probe", "Pylon", "Probe", "Gateway", "Gateway", "Probe", "Probe", "Zealot", "Pylon", "Zealot", "Zealot", "Probe", "Zealot", "Zealot", "Probe", "Pylon", "Zealot", "Gateway", "Probe", "Pylon", "Probe", "Zealot", "Probe", "Zealot", "Zealot", "Zealot", "Zealot", "Pylon", "Probe", "Zealot", "Zealot", "Zealot" ],
"ScoutCondition" : [ ["Self", "Pylon"], ">", [ 0 ] ],
"AttackCondition" : [ ["Self", "Zealot"], ">=", [ 3 ] ]
},
"Protoss_DragoonRush" :
{
"Race" : "Protoss",
"OpeningBuildOrder" : ["Probe", "Probe", "Probe", "Probe", "Pylon", "Probe", "Probe", "Gateway", "Probe", "Assimilator", "Probe", "Probe", "Cybernetics_Core", "Probe", "Probe", "Gateway", "Singularity_Charge", "Dragoon", "Gateway", "Pylon", "Dragoon", "Dragoon", "Probe", "Gateway", "Pylon", "Probe", "Dragoon", "Dragoon", "Dragoon"],
"ScoutCondition" : [ ["Self", "Pylon"], ">", [ 0 ] ],
"AttackCondition" : [ ["Self", "Dragoon"], ">=", [ 3 ] ]
},
"Terran_MarineRush" :
{
"Race" : "Terran",
"OpeningBuildOrder" : ["SCV", "SCV", "SCV", "SCV", "Barracks", "Barracks", "SCV", "Supply Depot", "SCV", "Marine", "Marine", "Marine", "Marine", "Supply Depot"],
"ScoutCondition" : [ ["Self", "Supply Depot"], ">", [ 0 ] ],
"AttackCondition" : [ ["Self", "Marine"], ">=", [ 4 ] ]
},
"Zerg_ZerglingRush" :
{
"Race" : "Zerg",
"OpeningBuildOrder" : ["Drone", "Spawning Pool", "Zergling", "Zergling", "Zergling", "Zergling"],
"ScoutCondition" : [ ["Self", "Spawning Pool"], ">", [ 0 ] ],
"AttackCondition" : [ ["Self", "Zergling"], ">=", [ 0 ] ]
}
}
},
"SC2API Strategy" :
{
"Protoss" : "Protoss_ZealotRush",
"Terran" : "Terran_MarineRush",
"Zerg" : "Zerg_2HatchRoach",
"ScoutHarassEnemy" : true,
"Strategies" :
{
"Protoss_ZealotRush" :
{
"Race" : "Protoss",
"OpeningBuildOrder" : ["Probe", "Probe", "Pylon", "Probe", "Probe", "Gateway", "Pylon", "Probe", "Gateway", "Probe", "Gateway", "Pylon", "Probe", "Zealot", "Zealot", "Pylon", "Zealot", "Zealot", "Pylon", "Zealot", "Zealot", "Zealot", "Zealot", "Zealot", "Zealot", "Zealot", "Zealot", "Zealot", "Zealot"],
"ScoutCondition" : [ ["Self", "Pylon"], ">", [ 0 ] ],
"AttackCondition" : [ ["Self", "Zealot"], ">=", [ 8 ] ]
},
"Terran_MarineRush" :
{
"Race" : "Terran",
"OpeningBuildOrder" : ["SCV", "SCV", "SupplyDepot", "SCV", "SCV", "Barracks", "Barracks", "Barracks", "Barracks", "SupplyDepot", "SupplyDepot", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine", "Marine"],
"ScoutCondition" : [ ["Self", "SupplyDepot"], ">", [ 0 ] ],
"AttackCondition" : [ ["Self", "Marine"], ">=", [ 8 ] ]
},
"Zerg_ZerglingRush" :
{
"Race" : "Zerg",
"OpeningBuildOrder" : ["SpawningPool", "Drone", "Overlord", "Drone", "Zergling", "Zergling", "Zergling", "Zergling", "Zergling", "Zergling", "Zergling", "Zergling"],
"ScoutCondition" : [ ["GameFrame"], ">=", [ 100 ] ],
"AttackCondition" : [ ["Self", "Zergling"], ">", [ 0 ] ]
},
"Zerg_2HatchRoach" :
{
"Race" : "Zerg",
"OpeningBuildOrder" : ["SpawningPool", "Drone", "Overlord", "Drone", "Drone", "Extractor", "Drone", "Drone", "Hatchery", "Drone", "Overlord", "Drone", "RoachWarren", "Drone", "Drone", "Drone", "Drone", "Roach", "Overlord", "Roach", "Roach", "Roach", "Roach", "Overlord", "Roach", "Roach", "Roach", "Roach", "Roach", "Roach", "Roach"],
"ScoutCondition" : [ ["self", "SpawningPool"], ">=", [ 1 ] ],
"AttackCondition" : [ [["Self", "Roach"], ">=", [ 12 ]], "AND", [["Self", "Overlord"], ">=", [ 1 ]] ]
}
}
}
}
\ No newline at end of file
docker/Dockerfile 0 → 100644
View file @ 8cf95a69
# Sets up a Ubuntu 24.04 LTS environment with Python 3.12 suitable for building PyCommandCenter and its documentation
FROM ubuntu:24.04
LABEL org.opencontainers.image.authors="daniel.de.leng@liu.se"
RUN apt update && apt install -y build-essential cmake python3-full python3-pybind11 python3-pip python3-sphinx python3-sphinx-design
RUN pip3 install mypy==1.10.0 --break-system-packages # Workaround for python3-mypy having outdated version <1.10.0
ENV HOME=/root
WORKDIR /root
docs/.gitignore 0 → 100644
View file @ 8cf95a69
_autosummary/
_build/
venv
.idea
docs/Makefile 0 → 100644
View file @ 8cf95a69
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = PyCommandCenter
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
docs/_templates/layout.html 0 → 100644
View file @ 8cf95a69
{% extends "!layout.html" %}
{% block menu %}
{{ super() }}
<a href="py-modindex.html">modindex</a>
{% endblock %}
\ No newline at end of file
docs/conf.py 0 → 100644
View file @ 8cf95a69
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# Two paths here to work on both Windows and Linux
import sys,os
sys.path.append(os.path.join(os.getcwd(), "..", "build", "python-api-src", "Release"))
sys.path.append(os.path.join(os.getcwd(), "..", "build", "python-api-src"))
sys.path.append(os.getcwd())
# -- Project information -----------------------------------------------------
project = 'PyCommandCenter'
copyright = '2024 Reasoning and Learning Lab, Linköping University'
author = 'Sofia Abaied, Dawid Lukasz Abucewicz, Anton Andell, Erik Ahlroth, David Bergström, Edvin Bergström, Emil Brynielsson, Stefan Brynielsson, Ludvig Fors, Hannes Jämtner, Jonas Kvarnström, Daniel de Leng, Fredrik Präntare, Gabriel Tofvesson, David Warnquist, Jonathan Öhrling'
# The short X.Y version
version = '2.0'
# The full version, including alpha/beta/rc tags
release = ''
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.githubpages',
'sphinx.ext.autosummary',
'sphinx.ext.napoleon',
'sphinx_design',
'enum_doc',
]
autodoc_docstring_signature=True
autosummary_generate=True
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'relations.html',
'searchbox.html',
'sourcelink.html'
]
}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'PyCommandCenterdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'PyCommandCenter.tex', 'PyCommandCenter Documentation',
'David Bergström', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pycommandcenter', 'PyCommandCenter Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PyCommandCenter', 'PyCommandCenter Documentation',
author, 'PyCommandCenter', 'One line description of project.',
'Miscellaneous'),
]
# -- Extension configuration -------------------------------------------------
docs/config.yaml 0 → 100644
View file @ 8cf95a69
language: en
sphinx: true
extensions:
- sphinx_panels
default_domain: py
consecutive_numbering: true
colon_fences: true
dollar_math: true
conversions:
sphinx_panels.dropdown.DropdownDirective: parse_all
\ No newline at end of file
docs/constants.rst 0 → 100644
View file @ 8cf95a69
Constants
=========
See also UNIT_TYPEID, UPGRADE_ID and ABILITY_ID for more constants.
.. _playerconstants:
Player constants
----------------
The following constants are used when referring to a player:
.. autoclass:: commandcenter.PLAYER_SELF
.. autoclass:: commandcenter.PLAYER_ENEMY
.. autoclass:: commandcenter.PLAYER_NEUTRAL
.. autoclass:: commandcenter.PLAYER_ALLY
These are internally represented as integers, but these constants should be
used instead to avoid confusion.
Difficulty
----------
.. autoclass:: commandcenter.Difficulty
:members:
:undoc-members:
AIBuild
-------
.. autoclass:: commandcenter.AIBuild
:members:
:undoc-members:
Race
----
.. autoclass:: commandcenter.Race
:members:
:undoc-members:
.. toctree::
\ No newline at end of file
docs/contributing.rst 0 → 100644
View file @ 8cf95a69
.. _contributing:
Contributors guide
==================
The goal of this page is to give you some guidance regarding how to make changes to the library and its documentation.
Here's a brief overview of the process:
1. Fork the repository
2. Make changes
3. Document the new features / changes you have made
4. Commit and push to your fork
5. Create a Merge request
6. Read the comments on your merge request and make the necessary changes
The rest of the document gives some more details on the individual steps.
If anything is unclear, don't hesitate to contact any lab assistant or create an issue describing the problem.
Forking the repository
----------------------
The code is hosted on `LiU's gitlab <https://gitlab.liu.se/starcraft-ai-course/pycommandcenter/>`_. For instructions on how to fork a repository see `Gitlab's documentation <https://gitlab.liu.se/help/gitlab-basics/fork-project.md>`_.
This will result in your own copy of the repository, where you can make changes. This copy can be used as any other repository on gitlab, but has the additional feature of creating merge requests back to the original repository.
Making changes
--------------
This is done just as any other project. Please try to use the same code standard. Avoid making changes which breaks other student's code.
All code related to binding the C++ code to Python can be found in the subdirectory *python-api-src*. The project uses pybind11 to make the bindings from C++ to Python, see `their extensive documentation <https://pybind11.readthedocs.io/en/stable/>`_ on how to use it.
The code is heavily based on the original `CommandCenter <https://github.com/davechurchill/commandcenter>`_, all code which originally comes from this library lies in the subdirectory *src*.
The source code for all additional dependencies (including pybind11) are registerd as git submodules in the subdirectory *lib*.
The system is built using cmake, see the file `CMakeLists.txt <https://gitlab.liu.se/starcraft-ai-course/pycommandcenter/blob/master/CMakeLists.txt>`_ in the project root.
If a function already exist but you can't use it in python, check and see if it's exist in the library files (pybind).
#. Create a declaration of your function in the header file.
#. Create a definition of your function in the source file.
#. Depending on which object you decided to extend, you should also add this function to the library file. The library is the pybind, making it possible to use your function in python.
#. Update the documentation. There are instructions on how you build and test the documentation.
Example:
We want to add function to unit, returning a bool depending on if it's holding a mineral. We have discovered a function in the SC2 API containing this information (sc2_client.ccp). This is a helper function, it doesn't belong to any object.
#. In unit.h: bool isCarryingMinerals() const;
#. In unit.cpp: bool Unit::isCarryingMinerals() const { return sc2::IsCarryingMinerals(\*m_unit); }
#. We can access m_unit in the unit file and with sc2::Function() we can access any function in the blizzard API that doesn't belong to any object. The same goes for any object, for example sc2::Point3D makes us able to access the Point3D object.
#. In lib_unit.cpp: .def_property_readonly("is_carrying_minerals", &Unit::isCarryingMinerals)
#. In the folder named docs we update the documentation. In this case, we update the file unit.rst.
Common problems:
#. The return in python is a memory address: Make sure that it returns a correct type.
#. The compiler complains about files I have not even touched: Make sure that the startUp is library and you have release x64. If you just added a new function in pybind, check it.
#. The bot crashes whit a exit code -1073741819 (0xC0000005): Make sure that you dont read null values.
Document the new features / changes you have made
-------------------------------------------------
The documentation can be found in the *docs* subdirectory. The documentation is done using Sphinx which auto-generates some parts of the documentation based on the generated Python library. For steps on how to build the documentation see the `README file <https://gitlab.liu.se/starcraft-ai-course/pycommandcenter/blob/master/README.md>`_ in the project root.
The documentation is written in reStructuredText, a quick-guide can be found `here <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_.
Note that documenting changes you make to the library is required to have them merged with the main repository.
Create a Merge request
----------------------
A merge request can be created by going into your fork's project page, selecting *Merge Requests* on the left-hand side and pressing the *New merge request* button.
The source branch should be branch which you have made your changes on and the target branch should be the *master* branch of *course-starcraft/pycommandcenter*.
Read the comments on your merge request and make the necessary changes
----------------------------------------------------------------------
In this step someone will review your changes and make comments. These comments might ask you to make changes to the code or documentation. These changes must be done before the merge request is accepted. Therefore it is important to make merge requests several days before eventual deadlines.
Once the merge request has been accepted the code is now part of PyCommandCenter. Congratulations and thank you for your contribution to the project!
.. toctree::
\ No newline at end of file
docs/coordinates.rst 0 → 100644
View file @ 8cf95a69
Coordinates
===========
The library uses 2 types of coordinate classes. One for integers and one for
floats, these are called :class:`commandcenter.Point2DI` and
:class:`commandcenter.Point2D`. Conversion between the two types is possible by
sending the other type as argument in the constructor. In the case of
Point2D to Point2DI the floating point values will just be cast into
integer values.
Both of the types are hashable so they can be used in sets and dictionaries.
Note that it is the tuple (x_val, y_val) that will be hashed so don't mix
those sets or dictionaries with normal tuples.
Point2DI
--------
.. class:: commandcenter.Point2DI
These points are used for defining the location of tiles, which are used when
placing buildings in Starcraft.
Not many operators are defined for this class, only equality, inequality and
converting to strings are defined.
Point2D
-------
.. class:: commandcenter.Point2D
Instances of this class is used to represent the location of Units and
support many operations for general purpose calculation.
Example
~~~~~~~
.. code:: python
from commandcenter import Point2D, Point2DI
# Creating two points
p1 = Point2D() # Defaults to (0, 0)
p2 = Point2D(1, 2)
# Adding two points
p1 += p2
# Multiplying a point with a scalar
p2 *= 3
# Creating a new point, defined as the sum of p1 and p2
p3 = p1 + p2
print(p1)
print(p2)
print(p3)
# The same works for Point2DI
pi1 = Point2DI(1, 2)
pi2 = Point2DI(1, 2)
# However, we can only compare them. There are no operators for addition,
# subtraction or multiplication.
print(pi1 == pi2) # prints: True
It is also possible to define custom operators for these points, as shown
below:
.. code:: python
from math import sqrt
from commandcenter import Point2D
p1 = Point2D(3, 4)
p2 = Point2D(1, 2)
# Defining a custom @ operator, like this
Point2D.__matmul__ = lambda self, other: self.x * other.x + self.y * other.y
print(p1 @ p2) # prints: 11.0
# Or maybe a distance operator:
Point2D.distance = lambda self, other: sqrt((self.x - other.x)**2 + (self.y - other.y)**2)
print(p1.distance(p2)) # prints: 2.8284...
.. toctree::
\ No newline at end of file
docs/enum_doc.py 0 → 100644
View file @ 8cf95a69
"""
Self built extension to remove the "Members" section of enums from the autodoc output.
"""
def setup(app):
app.connect('autodoc-process-docstring', filter_autodoc_members)
def filter_autodoc_members(app, what, name, obj, options, lines):
new_lines = []
for line in lines:
if "Members:" in line:
break
else:
new_lines.append(line)
lines[:] = new_lines
\ No newline at end of file
docs/gettingstarted.rst 0 → 100644
View file @ 8cf95a69
.. _gettingstarted:
Getting started
===============
The goal of this page is to get you quickly started using the API. The
following code block is the bare minimum you need to start Starcraft II and run
your own bot.
An entire AI template project is available here_, it contains the code below
and more.
.. _here: https://gitlab.liu.se/starcraft-ai-course/sc2-python-bot
.. code-block:: python
import os
from typing import Optional
from commandcenter import *
class MyAgent(IDABot):
def __init__(self):
IDABot.__init__(self)
def on_game_start(self):
IDABot.on_game_start(self)
def on_step(self):
IDABot.on_step(self)
def main():
coordinator = Coordinator()
bot1 = MyAgent()
participant_1 = create_participants(Race.Terran, bot1)
participant_2 = create_computer(Race.Random, Difficulty.Easy)
coordinator.set_real_time(True)
coordinator.set_participants([participant_1, participant_2])
coordinator.launch_starcraft()
path = os.path.join(os.getcwd(), "maps", "InterloperTest.SC2Map")
coordinator.start_game(path)
while coordinator.update():
pass
if __name__ == "__main__":
main()
Now, let us break it down piece by piece to understand it.
.. code-block:: python
from commandcenter import *
This imports everything from the library into your namespace.
Next, we need to define our bot.
.. code-block:: python
class MyAgent(IDABot):
def __init__(self):
IDABot.__init__(self)
def on_game_start(self):
IDABot.on_game_start(self)
def on_step(self):
IDABot.on_step(self)
A bot which plays Starcraft is defined as a subclass to the class :class:`commandcenter.IDABot` which
contains some help code in order to make implementing your bit more straightforward.
If we look closer at our newly created bot, it has three methods which are all
run at different times. The method ``__init__`` is the constructor, which is
called whenever the bot is first created.
The method ``on_game_start`` method is run when the game starts. Lastly, the
method ``on_step`` is run on every time step of the game and thus where most of
the decision making is going to be implemented.
Moving on, we have the code which sets up a game of Starcraft II:
.. code-block:: python
def main():
coordinator = Coordinator()
bot1 = MyAgent()
participant_1 = create_participants(Race.Terran, bot1)
participant_2 = create_computer(Race.Random, Difficulty.Easy)
coordinator.set_real_time(True)
coordinator.set_participants([participant_1, participant_2])
coordinator.launch_starcraft()
path = os.path.join(os.getcwd(), "maps", "InterloperTest.SC2Map")
coordinator.start_game(path)
while coordinator.update():
pass
if __name__ == "__main__":
main()
First we create a coordinator, this is the object we use to start Starcraft.
On the line after that the bot is constructed (the constructor is called).
The rest of the function sets a few settings and then starts Starcraft.
There are a few changes you might want to do here:
Remove or comment out the following line:
.. code-block:: python
coordinator.set_real_time(True)
This line will make the game run at the same speed as humans play the game.
However, your bot might will probably be able to play the game faster. If you
remove or comment out this line the game will run as fast as possible, only
waiting for your bot to return from `on_step`.
If you want to train your agent on certain type of bots. For example, If we
want the opponent to focus on air strategy. You can add the
following line to the bot.
.. code-block:: python
participant_2 = create_computer(Race.Random, Difficulty.Easy, AIBuild.Air)
We can also play two bots against each other by changing the row:
.. code-block:: python
participant_2 = create_computer(Race.Random, Difficulty.Easy)
to:
.. code-block:: python
bot2 = SomeOtherBot()
participant_2 = create_participant(Race.Terran, bot2)
where ``SomeOtherBot`` is a bot defined in the same way as ``MyAgent``.
.. toctree::
\ No newline at end of file
docs/helpers.rst 0 → 100644
View file @ 8cf95a69
Helpers
=======
There are several classes related to processing information about the game
state and the input from StarCraft II. All these classes are taken more or less
directly from the original `CommandCenter`_, but we have left all
decision-making to the user of the API.
.. _CommandCenter: https://github.com/davechurchill/commandcenter
Here is a full list of all managers:
* :class:`commandcenter.BaseLocationManager`
* :class:`commandcenter.TechTree`
* :class:`commandcenter.MapTools`
* :class:`commandcenter.BuildingPlacer`
The rest of this page contains a brief description of each manager.
BaseLocationManager
-------------------
.. class:: commandcenter.BaseLocationManager
.. autoattribute:: base_locations
.. autoattribute:: starting_base_locations
.. automethod:: get_occupied_base_locations
.. automethod:: get_player_starting_base_location
.. automethod:: get_next_expansion
BaseLocation
~~~~~~~~~~~~
.. class:: commandcenter.BaseLocation
Closely related to BaseLocationManager. This is the datastructure used by
the BaseLocationManager to keep track of all base locations and related
information.
.. autoattribute:: position
.. autoattribute:: depot_position
.. autoattribute:: minerals
.. autoattribute:: geysers
.. automethod:: get_ground_distance
.. automethod:: is_occupied_by_player
.. automethod:: is_player_start_location
.. automethod:: contains_position
TechTree
--------
.. autoclass:: commandcenter.TechTree
This class has some invalid information by default, this can be corrected by
placing the file `techtree.json` in the working directory. The
`techtree.json` files are available here_, select the lastest version.
A techtree for StarCraft II version >=4.10 is now available (not fully tested yet),
this can be found under the folder data in this link_.
A recent file is included in the `template repository`_.
.. automethod:: get_data(argument) -> commandcenter.TypeData
.. _link: https://github.com/BurnySc2/sc2-techtree
.. _here: https://github.com/noorus/sc2-gamedata
.. _`template repository`: https://gitlab.liu.se/starcraft-ai-course/sc2-python-bot
TypeData
~~~~~~~~
.. autoclass:: commandcenter.TypeData
:members:
:undoc-members:
.. TODO: Types for all fields would be nice, is required_units List[UnitType] or List[UNIT_TYPEID]?
MapTools
--------
.. autoclass:: commandcenter.MapTools
:members:
:undoc-members:
Color
~~~~~
.. autoclass:: commandcenter.Color
:members:
:undoc-members:
.. automethod:: __init__
DistanceMap
~~~~~~~~~~~
.. autoclass:: commandcenter.DistanceMap
:members:
:undoc-members:
BuildingPlacer
--------------
.. autoclass:: commandcenter.BuildingPlacer
:members:
:undoc-members:
.. toctree::