helpers.rst

Helpers
=======

There are several classes related to processing information about the game
state and the input from Starcraft. 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:`library.BaseLocationManager`
* :class:`library.TechTree`
* :class:`library.MapTools`
* :class:`library.BuildingPlacer`

The rest of this page contains a brief description of each manager.

BaseLocationManager
-------------------

.. class:: library.BaseLocationManager

   .. attribute:: library.BaseLocationManager.base_locations

      A list of all :class:`library.BaseLocation` on the current map

   .. attribute:: library.BaseLocationManager.starting_base_locations

      A list of all :class:`library.BaseLocation` on the current map which a player
      started at, indexed by Player constant (see :ref:`playerconstants`).

   .. automethod:: library.BaseLocationManager.get_occupied_base_locations

   .. automethod:: library.BaseLocationManager.get_player_starting_base_location

   .. automethod:: library.BaseLocationManager.get_next_expansion

BaseLocation
~~~~~~~~~~~~

.. class:: library.BaseLocation

   Closely related to BaseLocationManager. This is the datastructure used by
   the BaseLocationManager to keep track of all base locations and related
   information.

   .. attribute:: library.BaseLocation.position

      The position of the center of the BaseLocation, defined as a :class:`library.Point2D`.

   .. attribute:: library.BaseLocation.depot_position

      A suitable position for building a town hall (Command Center, Hatchery or
      Nexus), defined as a :class:`library.Point2DI`.

   .. autoattribute:: mineral_fields

   .. autoattribute:: minerals

   .. autoattribute:: geysers

   .. automethod:: get_ground_distance

   .. automethod:: is_occupied_by_player

   .. automethod:: is_player_start_location

   .. automethod:: contains_position


TechTree
--------

.. class:: library.TechTree

   This class contains all information about units and what is required to
   build a certain unit and what builds it. It only has one method, which is
   used to look-up unit types properties:

   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
   recent file is included in the `template repository`_.

   .. method:: get_data(argument) -> library.TypeData

      Argument is either an instance of the class :class:`library.UnitType` or
      an instance of the class :class:`library.CCUpgrade`, depending on what
      information is wanted.

.. _here: https://github.com/noorus/sc2-gamedata
.. _`template repository`: https://gitlab.ida.liu.se/course-starcraft-ai/sc2-python-bot

TypeData
~~~~~~~~

.. autoclass:: library.TypeData
   :members:
   :undoc-members:

.. TODO: Types for all fields would be nice, is required_units List[UnitType] or List[UNIT_TYPEID]?

MapTools
--------

.. autoclass:: library.MapTools
   :members:
   :undoc-members:

Color
~~~~~

.. autoclass:: library.Color 	
   :members:
   :undoc-members:

   .. automethod:: __init__

DistanceMap
~~~~~~~~~~~

.. autoclass:: library.DistanceMap
   :members:
   :undoc-members:

BuildingPlacer
--------------

.. autoclass:: library.BuildingPlacer 	
   :members:
   :undoc-members:

   This class is useful for placing all buildings, except refineries and town halls (Command Centers, Hacheries and Nexus).

   If you want to place a town hall, take a look at attribute `depot_location` of :class:`library.BaseLocation`.

   If you want to place a refinery, take a look at attribute `geysers` of :class:`library.BaseLocation` and the method build_target of :class:`library.Unit`.