perception.rst

Perception
==========

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`.
      This is the position used if you want to build a Command Center at the
      base location.

   .. attribute:: library.BaseLocation.depot_position

      A suitable position for building a town hall, defined as a :class:`library.Point2DI`.

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/starcraft-api/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: