Skip to content
Snippets Groups Projects
helpers.rst 5.75 KiB
Newer Older
Helpers
=======
David Bergström's avatar
David Bergström committed

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
David Bergström's avatar
David Bergström committed

Here is a full list of all managers:

* :class:`library.BaseLocationManager`
* :class:`library.TechTree`
* :class:`library.MapTools`
* :class:`library.BuildingPlacer`
David Bergström's avatar
David Bergström committed

David Bergström's avatar
David Bergström committed
The rest of this page contains a brief description of each manager.
David Bergström's avatar
David Bergström committed

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`).
David Bergström's avatar
David Bergström committed

   .. automethod:: library.BaseLocationManager.get_occupied_base_locations

   .. automethod:: library.BaseLocationManager.get_player_starting_base_location

   .. automethod:: library.BaseLocationManager.get_next_expansion

David Bergström's avatar
David Bergström committed
.. 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
David Bergström's avatar
David Bergström committed

      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
      
      This function uses BFS and moves in a vertical and horizontal position. Because of this,
      the distance might overshoot compared to calculating it with Pythagoras' theorem.

   .. automethod:: is_occupied_by_player

   .. automethod:: is_player_start_location

   .. automethod:: contains_position
David Bergström's avatar
David Bergström committed


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 techtree for SC2 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`_.
   Instead of using TechTree, it's possible to use the functions in UnitType for
   structure, etc. In IDABot there is functions for getting data about upgrades.	

David Bergström's avatar
David Bergström committed
   .. 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.

.. _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
David Bergström's avatar
David Bergström committed
.. autoclass:: library.TypeData
   :members:
.. TODO: Types for all fields would be nice, is required_units List[UnitType] or List[UNIT_TYPEID]?
David Bergström's avatar
David Bergström committed

MapTools
--------

.. autoclass:: library.MapTools
   :members:
   This class contains two types of methods:

   * Methods for drawing information to the screen
   * Methods for extracting information about the map

   First, let us look at the method concerning drawing information to the 
   screen. Methods with the suffix ``_screen`` takes percentages of the 
   screens height and width, i.e. values between 0 and 1. Methods without 
   this suffix uses the same coordinate system as the game, i.e. world 
   coordinates.

   The top three methods below takes in a Point2D, but it's possible to
   send in x and y as floats instead of Point2D.

   .. automethod:: draw_box
   .. automethod:: draw_circle
   .. automethod:: draw_line
   .. automethod:: draw_text
   .. automethod:: draw_text_screen

   These are methods which are useful for extracting information about the 
   game map:

   .. automethod:: can_build_type_at_position
   .. automethod:: get_closest_tiles_to
   .. automethod:: get_distance_map
   .. automethod:: get_ground_distance
   .. automethod:: get_least_recently_seen_tile
   .. autoattribute:: height
   .. autoattribute:: width
   .. automethod:: is_buildable
   .. automethod:: is_connected
   .. automethod:: is_depot_buildable_tile
   .. automethod:: is_explored
   .. automethod:: is_powered
   .. automethod:: is_valid_position
   .. automethod:: is_valid_tile
   .. automethod:: is_visible
   .. automethod:: is_walkable

David Bergström's avatar
David Bergström committed

David Bergström's avatar
David Bergström committed
.. 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`.