sc2_interfaces.h

Go to the documentation of this file.

#pragma once

#include "sc2api/sc2_common.h"
#include "sc2api/sc2_action.h"
#include "sc2api/sc2_unit.h"
#include "sc2api/sc2_data.h"

#include <vector>

// Forward declarations to avoid including proto headers everywhere.
namespace SC2APIProtocol {
    class Observation;
}

namespace sc2 {

enum class UNIT_TYPEID;
enum class ABILITY_ID;

class ObservationInterface;
struct Score;
struct GameInfo;

enum class Visibility {
    Hidden = 0,
    Fogged = 1,
    Visible = 2,
    FullHidden = 3
};

typedef std::function<bool(const Unit& unit)> Filter;

class ObservationInterface {
public:
    virtual ~ObservationInterface() = default;

    virtual uint32_t GetPlayerID() const = 0;

    virtual uint32_t GetGameLoop() const = 0;

    virtual Units GetUnits() const = 0;

    virtual Units GetUnits(Unit::Alliance alliance, Filter filter = {}) const = 0;

    virtual Units GetUnits(Filter filter) const = 0;

    virtual const Unit* GetUnit(Tag tag) const = 0;

    virtual const RawActions& GetRawActions() const = 0;

    virtual const SpatialActions& GetFeatureLayerActions() const = 0;

    virtual const SpatialActions& GetRenderedActions() const = 0;

    virtual const std::vector<ChatMessage>& GetChatMessages() const = 0;

    virtual const std::vector<PowerSource>& GetPowerSources() const = 0;

    virtual const std::vector<Effect>& GetEffects() const = 0;

    virtual const std::vector<UpgradeID>& GetUpgrades() const = 0;

    virtual const Score& GetScore() const = 0;

    virtual const Abilities& GetAbilityData(bool force_refresh = false) const = 0;

    virtual const UnitTypes& GetUnitTypeData(bool force_refresh = false) const = 0;

    virtual const Upgrades& GetUpgradeData(bool force_refresh = false) const = 0;

    virtual const Buffs& GetBuffData(bool force_refresh = false) const = 0;

    virtual const Effects& GetEffectData(bool force_refresh = false) const = 0;

    virtual const GameInfo& GetGameInfo() const = 0;

    virtual uint32_t GetMinerals() const = 0;

    virtual uint32_t GetVespene() const = 0;

    virtual uint32_t GetFoodCap() const = 0;

    virtual uint32_t GetFoodUsed() const = 0;

    virtual uint32_t GetFoodArmy() const = 0;

    virtual uint32_t GetFoodWorkers() const = 0;

    virtual uint32_t GetIdleWorkerCount() const = 0;

    virtual uint32_t GetArmyCount() const = 0;

    virtual uint32_t GetWarpGateCount() const = 0;

    virtual uint32_t GetLarvaCount() const = 0;

    virtual Point2D GetCameraPos() const = 0;

    virtual Point3D GetStartLocation() const = 0;

    virtual const std::vector<PlayerResult>& GetResults() const = 0;

    virtual bool HasCreep(const Point2D& point) const = 0;

    virtual Visibility GetVisibility(const Point2D& point) const = 0;

    // include pathing blockers like structures. For more accurate pathing results
    // use QueryInterface::PathingDistance.
    virtual bool IsPathable(const Point2D& point) const = 0;

    // include blockers like other structures. For more accurate building placement
    // results use QueryInterface::Placement.
    virtual bool IsPlacable(const Point2D& point) const = 0;

    virtual float TerrainHeight(const Point2D& point) const = 0;

    // it is highly discouraged. It should only be used for extracting feature layers because it would be inefficient to copy these each frame.
    virtual const SC2APIProtocol::Observation* GetRawObservation() const = 0;

};

class QueryInterface {
public:
    virtual ~QueryInterface() = default;

    virtual AvailableAbilities GetAbilitiesForUnit(const Unit* unit, bool ignore_resource_requirements = false, bool use_generalized_ability = true) = 0;
    virtual std::vector<AvailableAbilities> GetAbilitiesForUnits(const Units& units, bool ignore_resource_requirements = false, bool use_generalized_ability = true) = 0;

    virtual float PathingDistance(const Point2D& start, const Point2D& end) = 0;
    virtual float PathingDistance(const Unit* start, const Point2D& end) = 0;

    struct PathingQuery {
        Tag start_unit_tag_ = NullTag;
        Point2D start_;
        Point2D end_;
    };
    virtual std::vector<float> PathingDistance(const std::vector<PathingQuery>& queries) = 0;

    virtual bool Placement(const AbilityID& ability, const Point2D& target_pos, const Unit* unit = nullptr) = 0;

    struct PlacementQuery {
        PlacementQuery() = default;
        PlacementQuery(AbilityID ability_id, Point2D target) :
            ability(ability_id),
            target_pos(target) {};

        AbilityID ability;
        Point2D target_pos;
        Tag placing_unit_tag = 0LL;     // Optional. Used for testing placement with add-ons.
    };
    virtual std::vector<bool> Placement(const std::vector<PlacementQuery>& queries) = 0;
};

class ActionInterface {
public:
    virtual ~ActionInterface() = default;

    virtual void UnitCommand(const Unit* unit, AbilityID ability, bool queued_command = false) = 0;

    virtual void UnitCommand(const Unit* unit, AbilityID ability, const Point2D& point, bool queued_command = false) = 0;

    virtual void UnitCommand(const Unit* unit, AbilityID ability, const Unit* target, bool queued_command = false) = 0;

    virtual void UnitCommand(const Units& units, AbilityID ability, bool queued_move = false) = 0;

    virtual void UnitCommand(const Units& units, AbilityID ability, const Point2D& point, bool queued_command = false) = 0;

    virtual void UnitCommand(const Units& units, AbilityID ability, const Unit* target, bool queued_command = false) = 0;

    virtual const std::vector<Tag>& Commands() const = 0;

    virtual void ToggleAutocast(Tag unit_tag, AbilityID ability) = 0;
    virtual void ToggleAutocast(const std::vector<Tag>& unit_tags, AbilityID ability) = 0;

    virtual void SendChat(const std::string& message, ChatChannel channel = ChatChannel::All) = 0;

    virtual void SendActions() = 0;
};

class ActionFeatureLayerInterface {
public:
    virtual ~ActionFeatureLayerInterface() = default;

    virtual void UnitCommand(AbilityID ability) = 0;

    virtual void UnitCommand(AbilityID ability, const Point2DI& point, bool minimap = false) = 0;

    virtual void CameraMove(const Point2DI& center) = 0;

    virtual void Select(const Point2DI& center, PointSelectionType selection_type) = 0;

    virtual void Select(const Point2DI& p0, const Point2DI& p1, bool add_to_selection = false) = 0;

    virtual void SendActions() = 0;
};

class ObserverActionInterface {
public:
    virtual ~ObserverActionInterface () = default;

    virtual void CameraMove(const Point2D& point, float distance = 0.0f) = 0;

    virtual void CameraFollowPlayer() = 0;

    virtual void SendActions() = 0;
};

class DebugInterface {
public:
    virtual ~DebugInterface() = default;

    // Debug drawing primitives.

    virtual void DebugTextOut(const std::string& out, Color color = Colors::White) = 0;
    virtual void DebugTextOut(const std::string& out, const Point2D& pt_virtual_2D, Color color = Colors::White, uint32_t size = 8) = 0;
    virtual void DebugTextOut(const std::string& out, const Point3D& pt3D, Color color = Colors::White, uint32_t size = 8) = 0;
    virtual void DebugLineOut(const Point3D& p0, const Point3D& p1, Color color = Colors::White) = 0;
    virtual void DebugBoxOut(const Point3D& p_min, const Point3D& p_max, Color color = Colors::White) = 0;
    virtual void DebugSphereOut(const Point3D& p, float r, Color color = Colors::White) = 0;

    // Cheats.

    virtual void DebugCreateUnit(UnitTypeID unit_type, const Point2D& p, uint32_t player_id = 1, uint32_t count = 1) = 0;

    virtual void DebugKillUnit(const Unit* unit) = 0;

    virtual void DebugShowMap() = 0;
    virtual void DebugEnemyControl() = 0;
    virtual void DebugIgnoreFood() = 0;
    virtual void DebugIgnoreResourceCost() = 0;
    virtual void DebugGiveAllResources() = 0;
    virtual void DebugGodMode() = 0;
    virtual void DebugIgnoreMineral() = 0;
    virtual void DebugNoCooldowns() = 0;
    virtual void DebugGiveAllTech() = 0;
    virtual void DebugGiveAllUpgrades() = 0;
    virtual void DebugFastBuild() = 0;
    virtual void DebugSetScore(float score) = 0;
    virtual void DebugEndGame(bool victory = false) = 0;
    virtual void DebugSetEnergy(float value, const Unit* unit) = 0;
    virtual void DebugSetLife(float value, const Unit* unit) = 0;
    virtual void DebugSetShields(float value, const Unit* unit) = 0;

    virtual void DebugMoveCamera(const Point2D& pos) = 0;

      enum AppTest {
        hang = 1,
        crash = 2,
        exit = 3
      };
      virtual void DebugTestApp(AppTest app_test, int delay_ms = 0) = 0;

    virtual void SendDebug() = 0;
};

}  // namespace sc2