SC2API
An API for AI for StarCraft II
sc2_interfaces.h
Go to the documentation of this file.
1 
9 #pragma once
10 
11 #include "sc2api/sc2_common.h"
12 #include "sc2api/sc2_action.h"
13 #include "sc2api/sc2_unit.h"
14 #include "sc2api/sc2_data.h"
15 
16 #include <vector>
17 
18 // Forward declarations to avoid including proto headers everywhere.
19 namespace SC2APIProtocol {
20  class Observation;
21 }
22 
23 namespace sc2 {
24 
25 enum class UNIT_TYPEID;
26 enum class ABILITY_ID;
27 
28 class ObservationInterface;
29 struct Score;
30 struct GameInfo;
31 
32 enum class Visibility {
33  Hidden = 0,
34  Fogged = 1,
35  Visible = 2,
36  FullHidden = 3
37 };
38 
44 typedef std::function<bool(const Unit& unit)> Filter;
45 
48 public:
49  virtual ~ObservationInterface() = default;
50 
53  virtual uint32_t GetPlayerID() const = 0;
54 
57  virtual uint32_t GetGameLoop() const = 0;
58 
61  virtual const Units& GetUnits() const = 0;
62 
68  virtual Units GetUnits(Unit::Alliance alliance, Filter filter = {}) const = 0;
69 
74  virtual Units GetUnits(Filter filter) const = 0;
75 
79  virtual const Unit* GetUnit(Tag tag) const = 0;
80 
86  virtual const Unit* GetPreviousUnit(Tag tag) const = 0;
87 
90  virtual const Units& GetUnitsAdded() const = 0;
91 
96  virtual const Units& GetUnitsRemoved() const = 0;
97 
100  virtual const RawActions& GetRawActions() const = 0;
101 
104  virtual const SpatialActions& GetFeatureLayerActions() const = 0;
105 
108  virtual const std::vector<PowerSource>& GetPowerSources() const = 0;
109 
112  virtual const std::vector<UpgradeID>& GetUpgrades() const = 0;
113 
116  virtual const Score& GetScore() const = 0;
117 
121  virtual const Abilities& GetAbilityData(bool force_refresh = false) const = 0;
122 
126  virtual const UnitTypes& GetUnitTypeData(bool force_refresh = false) const = 0;
127 
131  virtual const Upgrades& GetUpgradeData(bool force_refresh = false) const = 0;
132 
136  virtual const Buffs& GetBuffData(bool force_refresh = false) const = 0;
137 
140  virtual const GameInfo& GetGameInfo() const = 0;
141 
144  virtual int32_t GetMinerals() const = 0;
145 
148  virtual int32_t GetVespene() const = 0;
149 
153  virtual int32_t GetFoodCap() const = 0;
154 
158  virtual int32_t GetFoodUsed() const = 0;
159 
163  virtual int32_t GetFoodArmy() const = 0;
164 
168  virtual int32_t GetFoodWorkers() const = 0;
169 
172  virtual int32_t GetIdleWorkerCount() const = 0;
173 
176  virtual int32_t GetArmyCount() const = 0;
177 
180  virtual int32_t GetWarpGateCount() const = 0;
181 
184  virtual Point2D GetCameraPos() const = 0;
185 
188  virtual Point3D GetStartLocation() const = 0;
189 
193  virtual bool HasCreep(const Point2D& point) const = 0;
194 
198  virtual Visibility GetVisibility(const Point2D& point) const = 0;
199 
201  // include pathing blockers like structures. For more accurate pathing results
202  // use QueryInterface::PathingDistance.
205  virtual bool IsPathable(const Point2D& point) const = 0;
206 
208  // include blockers like other structures. For more accurate building placement
209  // results use QueryInterface::Placement.
212  virtual bool IsPlacable(const Point2D& point) const = 0;
213 
217  virtual float TerrainHeight(const Point2D& point) const = 0;
218 
220  // it is highly discouraged. It should only be used for extracting feature layers because it would be inefficient to copy these each frame.
223  virtual const SC2APIProtocol::Observation* GetRawObservation() const = 0;
224 };
225 
226 
232 public:
233  virtual ~QueryInterface() = default;
234 
239  virtual AvailableAbilities GetAbilitiesForUnit(Tag tag, bool ignore_resource_requirements = false) = 0;
245  virtual std::vector<AvailableAbilities> GetAbilitiesForUnits(const std::vector<Tag>& tags, bool ignore_resource_requirements = false) = 0;
246 
251  virtual float PathingDistance(const Point2D& start, const Point2D& end) = 0;
257  virtual float PathingDistance(const Tag& start_unit_tag, const Point2D& end) = 0;
258 
259  struct PathingQuery {
260  Tag start_unit_tag_ = NullTag;
261  Point2D start_;
262  Point2D end_;
263  };
265  virtual std::vector<float> PathingDistance(const std::vector<PathingQuery>& queries) = 0;
266 
274  virtual bool Placement(const AbilityID& ability, const Point2D& target_pos, Tag placing_unit_tag_ = NullTag) = 0;
275 
276  struct PlacementQuery {
277  PlacementQuery() = default;
278  PlacementQuery(AbilityID ability_id, Point2D target) :
279  ability(ability_id),
280  target_pos(target) {};
281 
282  AbilityID ability;
283  Point2D target_pos;
284  Tag placing_unit_tag = 0LL; // Optional. Used for testing placement with add-ons.
285  };
290  virtual std::vector<bool> Placement(const std::vector<PlacementQuery>& queries) = 0;
291 };
292 
293 
297 public:
298  virtual ~ActionInterface() = default;
299 
308  virtual void UnitCommand(Tag unit_tag, AbilityID ability) = 0;
312 
317  virtual void UnitCommand(Tag unit_tag, AbilityID ability, const Point2D& point) = 0;
318 
323  virtual void UnitCommand(Tag unit_tag, AbilityID ability, Tag target_tag) = 0;
324 
326  virtual void UnitCommand(const std::vector<Tag>& unit_tags, AbilityID ability) = 0;
327 
329  virtual void UnitCommand(const std::vector<Tag>& unit_tags, AbilityID ability, const Point2D& point) = 0;
330 
332  virtual void UnitCommand(const std::vector<Tag>& unit_tags, AbilityID ability, Tag target_tag) = 0;
333 
337  virtual const std::vector<Tag>& Commands() const = 0;
338 
342  virtual void ToggleAutocast(Tag unit_tag, AbilityID ability) = 0;
346  virtual void ToggleAutocast(const std::vector<Tag>& unit_tags, AbilityID ability) = 0;
347 
352  virtual void SendActions() = 0;
353 };
354 
358 public:
359  virtual ~ActionFeatureLayerInterface() = default;
360 
363  virtual void UnitCommand(AbilityID ability) = 0;
364 
369  virtual void UnitCommand(AbilityID ability, const Point2DI& point, bool minimap = false) = 0;
370 
372  virtual void CameraMove(const Point2DI& center) = 0;
373 
377  virtual void Select(const Point2DI& center, PointSelectionType selection_type) = 0;
378 
383  virtual void Select(const Point2DI& p0, const Point2DI& p1, bool add_to_selection = false) = 0;
384 
387  virtual void SendActions() = 0;
388 };
389 
390 
396 public:
397  virtual ~DebugInterface() = default;
398 
399  // Debug drawing primitives.
400 
404  virtual void DebugTextOut(const std::string& out, Color color = Colors::White) = 0;
409  virtual void DebugTextOut(const std::string& out, const Point2D& pt_virtual_2D, Color color = Colors::White) = 0;
414  virtual void DebugTextOut(const std::string& out, const Point3D& pt3D, Color color = Colors::White) = 0;
419  virtual void DebugLineOut(const Point3D& p0, const Point3D& p1, Color color = Colors::White) = 0;
424  virtual void DebugBoxOut(const Point3D& p_min, const Point3D& p_max, Color color = Colors::White) = 0;
429  virtual void DebugSphereOut(const Point3D& p, float r, Color color = Colors::White) = 0;
430 
431  // Cheats.
432 
438  virtual void DebugCreateUnit(UnitTypeID unit_type, const Point2D& p, uint32_t player_id = 1, uint32_t count = 1) = 0;
439 
442  virtual void DebugKillUnit(Tag tag) = 0;
443 
445  virtual void DebugShowMap() = 0;
447  virtual void DebugEnemyControl() = 0;
449  virtual void DebugIgnoreFood() = 0;
451  virtual void DebugIgnoreResourceCost() = 0;
453  virtual void DebugGiveAllResources() = 0;
455  virtual void DebugGodMode() = 0;
457  virtual void DebugIgnoreMineral() = 0;
459  virtual void DebugNoCooldowns() = 0;
461  virtual void DebugGiveAllTech() = 0;
463  virtual void DebugGiveAllUpgrades() = 0;
465  virtual void DebugFastBuild() = 0;
467  virtual void DebugSetScore(float score) = 0;
470  virtual void DebugEndGame(bool victory = false) = 0;
474  virtual void DebugSetEnergy(float value, Tag tag) = 0;
478  virtual void DebugSetLife(float value, Tag tag) = 0;
482  virtual void DebugSetShields(float value, Tag tag) = 0;
483 
486  virtual void DebugMoveCamera(const Point2D& pos) = 0;
487 
488  enum AppTest {
489  hang = 1,
490  crash = 2,
491  exit = 3
492  };
496  virtual void DebugTestApp(AppTest app_test, int delay_ms = 0) = 0;
497 
500  virtual void SendDebug() = 0;
501 };
502 
503 }
Possible actions for feature layers.
Definition: sc2_action.h:113
Definition: sc2_interfaces.h:276
Common data types, including points, rectangles and colors.
A unit. Could be a structure, a worker or a military unit.
Definition: sc2_unit.h:63
Unit data in an observation.
Alliance
Relationship to this player.
Definition: sc2_unit.h:77
Definition: sc2_interfaces.h:231
2D integer point.
Definition: sc2_common.h:95
Scores.
Definition: sc2_score.h:179
Definition: sc2_common.h:14
Definition: sc2_common.h:49
Definition: sc2_action.h:9
All available abilities for a unit.
Definition: sc2_data.h:91
RGB Color.
Definition: sc2_common.h:115
Definition: sc2_interfaces.h:259
The ObservationInterface reflects the current state of the game. Guaranteed to be valid when OnGameSt...
Definition: sc2_interfaces.h:47
std::function< bool(const Unit &unit)> Filter
Definition: sc2_interfaces.h:44
Initial data for a game and map.
Definition: sc2_map_info.h:69
Definition: sc2_interfaces.h:395
Definition: sc2_interfaces.h:296
Definition: sc2_connection.h:16
Definition: sc2_interfaces.h:357