Starcraft II Data Structures
Common
This is one of “those” files that just contains a few bits and bobs such as action, position, image data structures etc.
- Author
Bryce Ferenczi
- Version
0.1
- Date
2024-05-27
- Copyright
Copyright (c) 2024
-
template<>
struct formatter<cvt::Action::TargetType> : public formatter<string_view> - #include <common.hpp>
fmt formatter specialization for cvt::Action::TargetType
Public Functions
-
inline auto format(cvt::Action::TargetType a, format_context &ctx) const -> format_context::iterator
-
inline auto format(cvt::Action::TargetType a, format_context &ctx) const -> format_context::iterator
-
namespace cvt
Typedefs
-
typedef std::uint64_t UID
Type that represents unique identifier in the game.
Functions
-
template<typename T>
auto enumToOneHot(Action::TargetType e) noexcept -> std::vector<T> Convert enum to onehot for target type.
- Template Parameters:
T – output data type of one-hot vector
- Parameters:
e – Target type enumeration
- Returns:
One hot encoding vector of target type
-
struct Action
- #include <common.hpp>
Player action in StarCraft II.
Public Types
Public Functions
Public Members
-
TargetType target_type = {TargetType::Self}
Type of target this action effects.
-
TargetType target_type = {TargetType::Self}
-
template<typename T>
struct Image - #include <common.hpp>
Type-erased single channel image data container.
- Template Parameters:
T – datatype of image elements
Public Functions
-
auto operator==(const Image &other) const noexcept -> bool = default
Compare equality of images.
- Parameters:
other – comparison image
- Returns:
True if image data is equal
-
inline auto nelem() const noexcept -> std::size_t
Number of elements in the image.
- Returns:
Number of elements in the image
-
inline void resize(int height, int width)
Resize the underlying data buffer to new height and width.
- Parameters:
height – new height
width – new width
-
inline void clear() noexcept
Clear the data buffer and shape.
-
inline auto size() const noexcept -> std::size_t
Size in bytes of the buffer.
- Returns:
Size in bytes of the buffer
-
inline auto empty() const noexcept -> bool
Check if data buffer is empty.
- Returns:
True if data buffer is empty
-
inline auto data() noexcept -> ptr_type
Typed pointer to the data.
- Returns:
Typed pointer to the data
-
inline auto data() const noexcept -> const_ptr_type
Const Typed pointer to the data.
- Returns:
Const Typed pointer to the data
-
inline auto as_span() noexcept -> std::span<value_type>
requires (!std::same_as<value_type, bool>) Typed modifiable view of the data, unavailable if value_type is bool.
- Returns:
Typed span view of the data
-
inline auto as_span() const noexcept -> std::span<const value_type>
requires (!std::same_as<value_type, bool>) Typed const view of the data, unavailable if value_type is bool.
- Returns:
Typed span view of the const data
-
struct Point2d
- #include <common.hpp>
Basic discrete 2d point.
-
struct Point3f
- #include <common.hpp>
Basic continuous 3d point.
-
struct Score
- #include <common.hpp>
All score data from the player point-of-view of StarCraft II.
Public Members
-
float score_float
-
float idle_production_time
-
float idle_worker_time
-
float total_value_units
-
float total_value_structures
-
float killed_value_units
-
float killed_value_structures
-
float collected_minerals
-
float collected_vespene
-
float collection_rate_minerals
-
float collection_rate_vespene
-
float spent_minerals
-
float spent_vespene
-
float total_damage_dealt_life
-
float total_damage_dealt_shields
-
float total_damage_dealt_energy
-
float total_damage_taken_life
-
float total_damage_taken_shields
-
float total_damage_taken_energy
-
float total_healed_life
-
float total_healed_shields
-
float total_healed_energy
-
float score_float
-
typedef std::uint64_t UID
Enums
Common enums in StarCraft II and accompanying tools such as enum->string and enum->one-hot.
- Author
Bryce Ferenczi
- Version
0.1
- Date
2024-05-27
- Copyright
Copyright (c) 2024
-
template<>
struct formatter<cvt::Alliance> : public formatter<string_view> - #include <enums.hpp>
fmt formatter specialization for alliance
-
template<>
struct formatter<cvt::CloakState> : public formatter<string_view> - #include <enums.hpp>
fmt formatter specialization for cloak state
Public Functions
-
inline auto format(cvt::CloakState c, format_context &ctx) const -> format_context::iterator
-
inline auto format(cvt::CloakState c, format_context &ctx) const -> format_context::iterator
-
template<>
struct formatter<cvt::Visibility> : public formatter<string_view> - #include <enums.hpp>
fmt formatter specialization for visibility
Public Functions
-
inline auto format(cvt::Visibility v, format_context &ctx) const -> format_context::iterator
-
inline auto format(cvt::Visibility v, format_context &ctx) const -> format_context::iterator
-
template<>
struct formatter<cvt::AddOn> : public formatter<string_view> - #include <enums.hpp>
fmt formatter specialization for addon
-
template<>
struct formatter<cvt::Race> : public formatter<string_view> - #include <enums.hpp>
fmt formatter specialization for race
-
template<>
struct formatter<cvt::Result> : public formatter<string_view> - #include <enums.hpp>
fmt formatter specialization for result
-
namespace cvt
Enums
-
enum class Alliance : char
Values:
-
enumerator Self
-
enumerator Ally
-
enumerator Neutral
-
enumerator Enemy
-
enumerator Self
-
enum class CloakState : char
Values:
-
enumerator Unknown
-
enumerator Cloaked
-
enumerator Detected
-
enumerator UnCloaked
-
enumerator Allied
-
enumerator Unknown
Functions
-
template<typename E>
consteval auto getEnumValues() Get all the possible values for a particular enum.
- Template Parameters:
E – enum type
- Returns:
Array of all possible enum values
-
template<typename E>
constexpr auto numEnumValues() -> std::size_t The number of possible values of an enum.
- Template Parameters:
E – type of enum
- Returns:
Number of possible enum values
-
namespace detail
Functions
-
template<typename T>
auto enumToOneHot_helper(auto enumVal, const std::ranges::range auto &enumValues) -> std::vector<T> Enum conversion helper that takes an enum value and an array of all possible enum values, finds the index where the enum appears and returns that index.
- Template Parameters:
T – value type of output vector
- Parameters:
enumVal – enum to convert
enumValues – array of all possible enum values
- Returns:
vector one-hot encoding of the enum.
Variables
-
template<typename T>
constexpr bool always_false_v = always_false<T>::value Always false type to help printing type info at a compile time error.
- Template Parameters:
T – type to print
-
template<typename T>
struct always_false : public std::false_type - #include <enums.hpp>
Helper type.
- Template Parameters:
T –
-
template<typename T>
-
enum class Alliance : char
Units
Unit data structures for StarCraft II. NeutralUnits are treated specially as many properties such as buffs and cloak_state are never utilized, so we save precious bytes and make a smaller structure especially for neutral structures.
- Author
Bryce Ferenczi
- Version
0.1
- Date
2024-05-27
- Copyright
Copyright (c) 2024
-
namespace cvt
-
struct NeutralUnit
- #include <units.hpp>
Static Neutral units in the Game.
Note
Static Neutral Units such as VespeneGeysers are missing many of the common player unit properties and therefore are handled separately to save space and better separate neutral entities and dynamic agents.
Public Functions
-
auto operator==(const NeutralUnit &other) const noexcept -> bool = default
-
inline operator std::string() const noexcept
-
auto operator==(const NeutralUnit &other) const noexcept -> bool = default
-
struct NeutralUnitSoA
- #include <units.hpp>
SoA representation of a collection of Neutral Units.
Public Types
-
using struct_type = NeutralUnit
Public Functions
-
auto operator==(const NeutralUnitSoA &other) const noexcept -> bool = default
-
inline auto size() const noexcept -> std::size_t
-
inline auto operator[](std::size_t idx) const noexcept -> NeutralUnit
-
using struct_type = NeutralUnit
-
struct Unit
- #include <units.hpp>
Basic StarCraft II Unit Data.
Public Functions
-
inline operator std::string() const noexcept
Public Members
-
Visibility observation = {}
-
CloakState cloak_state = {CloakState::Unknown}
-
int unitType = {}
-
float health = {}
-
float health_max = {}
-
float shield = {}
-
float shield_max = {}
-
float energy = {}
-
float energy_max = {}
-
float weapon_cooldown = {}
-
int buff0 = {}
-
int buff1 = {}
-
float heading = {}
-
float radius = {}
-
float build_progress = {}
-
char cargo = {}
-
char cargo_max = {}
-
char assigned_harvesters = {}
-
char ideal_harvesters = {}
-
bool is_blip = {false}
-
bool is_flying = {false}
-
bool is_burrowed = {false}
-
bool is_powered = {false}
-
bool in_cargo = {false}
-
inline operator std::string() const noexcept
-
struct UnitOrder
- #include <units.hpp>
Element in order queue for unit to follow.
Public Functions
-
inline operator std::string() const noexcept
-
inline operator std::string() const noexcept
-
struct UnitSoA
- #include <units.hpp>
SoA representation of a collection of StarCraft II units.
Public Functions
-
inline auto size() const noexcept -> std::size_t
Public Members
-
std::vector<int> unitType = {}
-
std::vector<Visibility> observation = {}
-
std::vector<float> health = {}
-
std::vector<float> health_max = {}
-
std::vector<float> shield = {}
-
std::vector<float> shield_max = {}
-
std::vector<float> energy = {}
-
std::vector<float> energy_max = {}
-
std::vector<char> cargo = {}
-
std::vector<char> cargo_max = {}
-
std::vector<char> assigned_harvesters = {}
-
std::vector<char> ideal_harvesters = {}
-
std::vector<float> weapon_cooldown = {}
-
std::vector<CloakState> cloak_state = {}
-
std::vector<char> is_blip = {}
-
std::vector<char> is_flying = {}
-
std::vector<char> is_burrowed = {}
-
std::vector<char> is_powered = {}
-
std::vector<char> in_cargo = {}
-
std::vector<int> buff0 = {}
-
std::vector<int> buff1 = {}
-
std::vector<float> heading = {}
-
std::vector<float> radius = {}
-
std::vector<float> build_progress = {}
-
inline auto size() const noexcept -> std::size_t
-
struct NeutralUnit
Interface
Common interface and utilities for replay data structures.
- Author
Bryce Ferenczi
- Version
0.1
- Date
2024-05-27
- Copyright
Copyright (c) 2024
-
namespace cvt
-
template<typename StepDataType>
struct ReplayDataTemplate - #include <replay_interface.hpp>
Structure that contains ReplayInfo and replay data stored as an Array-of-Structures, where the array dimension is time.
- Template Parameters:
StepDataType – structure type of observation data at each timestep.
Public Types
-
using step_type = StepDataType
struct type of observation data at each step
Public Functions
-
inline auto operator==(const ReplayDataTemplate &other) const noexcept -> bool
Check equality between replays.
- Parameters:
other – comparator
- Returns:
True if both replays are equal
-
inline auto size() const noexcept -> std::size_t
Number of observed steps in the replay data.
- Returns:
std::size_t
-
inline auto operator[](std::size_t index) const noexcept -> const StepDataType&
Get constant reference to replay data at step index.
- Parameters:
index – index of replay observations
- Returns:
const StepDataType&
-
inline auto operator[](std::size_t index) noexcept -> StepDataType&
Get reference to replay data at step index.
- Parameters:
index – index of replay observations
- Returns:
const StepDataType&
-
inline auto getReplayHash() noexcept -> std::string&
Get the unique hash ID of the replay.
- Returns:
Mutable reference of string hash of the replay
-
inline auto getReplayHash() const noexcept -> const std::string&
Get the unique hash ID of the replay.
- Returns:
Constant reference to string hash of the replay
-
inline auto getPlayerId() noexcept -> std::uint32_t&
Get the player perspective Id of the replay.
- Returns:
Mutable reference to Player Id of the replay
-
inline auto getPlayerId() const noexcept -> std::uint32_t
Get the player perspective Id of the replay.
- Returns:
Constant reference to Player Id of the replay
Public Members
-
ReplayInfo header
Metadata of the replay.
-
std::vector<StepDataType> data
Observation data from each sample step in time.
-
template<IsSoAType StepDataSoAType>
struct ReplayDataTemplateSoA - #include <replay_interface.hpp>
Structure that contains ReplayInfo and replay data stored as a Structure-of-Arrays.
- Template Parameters:
StepDataSoAType – structure of arrays type of replay data
Public Types
-
using step_type = StepDataSoAType::struct_type
struct type of observation data at each step
-
using struct_type = ReplayDataTemplate<typename StepDataSoAType::struct_type>
AoS equivalent struct type.
-
using header_type = ReplayInfo
Header that contains metadata about the replay.
Public Functions
-
inline auto operator==(const ReplayDataTemplateSoA &other) const noexcept -> bool
Check equality between replays.
- Parameters:
other – comparator
- Returns:
True if both replays are equal
-
inline auto size() const noexcept -> std::size_t
Number of observed steps in the replay data.
- Returns:
std::size_t
-
inline auto operator[](std::size_t index) const noexcept -> step_type
Get replay data at step index.
- Parameters:
index – index of replay observations
- Returns:
StepDataType
-
inline auto getReplayHash() noexcept -> std::string&
Get the unique hash ID of the replay.
- Returns:
Mutable reference of string hash of the replay
-
inline auto getReplayHash() const noexcept -> const std::string&
Get the unique hash ID of the replay.
- Returns:
Constant reference to string hash of the replay
-
inline auto getPlayerId() noexcept -> std::uint32_t&
Get the player perspective Id of the replay.
- Returns:
Mutable reference to Player Id of the replay
-
inline auto getPlayerId() const noexcept -> std::uint32_t
Get the player perspective Id of the replay.
- Returns:
Constant reference to Player Id of the replay
Public Members
-
ReplayInfo header
Replay metadata.
-
StepDataSoAType data
Observation data from each sample step in time in SoA form.
-
struct ReplayInfo
- #include <replay_interface.hpp>
General replay metadata common to all replay data structures.
Public Functions
-
auto operator==(const ReplayInfo &other) const noexcept -> bool = default
Default equality operator between two replay headers.
- Parameters:
other – Replay to compare against.
- Returns:
True if both are identical.
Public Members
-
std::string replayHash = {}
Unique hash/identifier associated with a game.
-
std::string gameVersion = {}
Version of the game played as a string i.e. 4.9.2.12345.
-
std::uint32_t playerId = {}
The POV Player Id, i.e. Player 1 or 2.
-
std::uint32_t durationSteps = {}
Number of gameSteps in the replay.
-
int playerMMR = {}
MMR of the POV Player.
-
int playerAPM = {}
APM of the POV Player for this game.
-
int mapWidth = {}
Map width in game units.
-
int mapHeight = {}
Map height in game units.
-
auto operator==(const ReplayInfo &other) const noexcept -> bool = default
-
template<typename StepDataType>
All Data
Replay data structure for recording and deserializing all observation data.
- Author
Bryce Ferenczi
- Version
0.1
- Date
2024-05-27
- Copyright
Copyright (c) 2024
-
namespace cvt
Typedefs
-
using ReplayData = ReplayDataTemplate<StepData>
ReplayData with only scalar data.
-
using ReplayDataSoA = ReplayDataTemplateSoA<StepDataSoA>
ReplayData as SoA with only scalar data.
-
template<>
struct DatabaseInterface<ReplayDataSoA> - #include <replay_all.hpp>
Database interface implementation for ReplayDataSoA.
Public Static Functions
-
static inline auto getHeaderImpl(std::istream &dbStream) -> ReplayInfo
-
static inline auto getEntryUIDImpl(std::istream &dbStream) -> std::string
-
static inline auto getEntryImpl(std::istream &dbStream) -> ReplayDataSoA
-
static inline auto addEntryImpl(const ReplayDataSoA &d, std::ostream &dbStream) noexcept -> bool
-
static inline auto getHeaderImpl(std::istream &dbStream) -> ReplayInfo
-
struct StepData
- #include <replay_all.hpp>
Step data that contains scalar, minimap and unit data. Basically all of it.
Public Types
-
using has_scalar_data = std::true_type
-
using has_minimap_data = std::true_type
-
using has_unit_data = std::true_type
-
using has_scalar_data = std::true_type
-
struct StepDataSoA
- #include <replay_all.hpp>
SoA representation of an array of StepData.
Public Types
-
using has_scalar_data = std::true_type
-
using has_minimap_data = std::true_type
-
using has_unit_data = std::true_type
Public Functions
-
auto operator==(const StepDataSoA &other) const noexcept -> bool = default
-
inline auto operator[](std::size_t idx) const noexcept -> StepData
Gather step data from each array to make structure of data at step.
- Parameters:
idx – time index of replay to gather.
- Returns:
Gathered step data.
-
inline auto size() const noexcept -> std::size_t
Number of game steps in the Structure-of-Arrays.
- Returns:
std::size_t
Public Members
-
std::vector<std::uint32_t> gameStep = {}
-
std::vector<std::uint16_t> minearals = {}
-
std::vector<std::uint16_t> vespene = {}
-
std::vector<std::uint16_t> popMax = {}
-
std::vector<std::uint16_t> popArmy = {}
-
std::vector<std::uint16_t> popWorkers = {}
-
std::vector<std::vector<NeutralUnit>> neutralUnits = {}
-
using has_scalar_data = std::true_type
-
using ReplayData = ReplayDataTemplate<StepData>
Minimap + Scalar Data
Replay observation data that only contains scalar (score and economy) and minimap data. Is compatible with reading ReplayData as the ordering of the data is the same, we just stop reading before Unit data.
- Author
Bryce Ferenczi
- Version
0.1
- Date
2024-05-27
- Copyright
Copyright (c) 2024
-
namespace cvt
Typedefs
-
using ReplayDataNoUnits = ReplayDataTemplate<StepDataNoUnits>
ReplayData with minimap and scalar data.
-
using ReplayDataSoANoUnits = ReplayDataTemplateSoA<StepDataNoUnitsSoA>
ReplayData as SoA with minimap and scalar data.
-
template<>
struct DatabaseInterface<ReplayDataSoANoUnits> - #include <replay_minimaps.hpp>
Database interface implementation for ReplayDataSoANoUnits.
Public Static Functions
-
static inline auto getHeaderImpl(std::istream &dbStream) -> ReplayInfo
-
static inline auto getEntryUIDImpl(std::istream &dbStream) -> std::string
-
static inline auto getEntryImpl(std::istream &dbStream) -> ReplayDataSoANoUnits
-
static inline auto addEntryImpl(const ReplayDataSoANoUnits &d, std::ostream &dbStream) noexcept -> bool
-
static inline auto getHeaderImpl(std::istream &dbStream) -> ReplayInfo
-
struct StepDataNoUnits
- #include <replay_minimaps.hpp>
Replay step data that contains scalar data and minimap data.
Public Functions
-
auto operator==(const StepDataNoUnits &other) const noexcept -> bool = default
-
auto operator==(const StepDataNoUnits &other) const noexcept -> bool = default
-
struct StepDataNoUnitsSoA
- #include <replay_minimaps.hpp>
SoA representation of an array of StepDataNoUnits.
Public Types
-
using has_scalar_data = std::true_type
-
using has_minimap_data = std::true_type
-
using struct_type = StepDataNoUnits
Public Functions
-
auto operator==(const StepDataNoUnitsSoA &other) const noexcept -> bool = default
-
inline auto operator[](std::size_t idx) const noexcept -> struct_type
Gather step data from each array to make structure of data at step.
- Parameters:
idx – time index of replay to gather.
- Returns:
Gathered step data.
-
inline auto size() const noexcept -> std::size_t
Number of game steps in the Structure-of-Arrays.
- Returns:
std::size_t
-
using has_scalar_data = std::true_type
-
using ReplayDataNoUnits = ReplayDataTemplate<StepDataNoUnits>
Scalar Data
Replay observation data that only contains scalar (score and economy) data. Is compatible with reading ReplayData and ReplayDataNoUnits as the ordering of the data is the same, we just stop reading before minimap data.
- Author
Bryce Ferenczi
- Version
0.1
- Date
2024-05-27
- Copyright
Copyright (c) 2024
-
namespace cvt
Typedefs
-
using ReplayDataNoUnitsMiniMap = ReplayDataTemplate<StepDataNoUnitsMinimap>
ReplayData with minimap and scalar data.
-
using ReplayDataSoANoUnitsMiniMap = ReplayDataTemplateSoA<StepDataNoUnitsMinimapSoA>
ReplayData as SoA with minimap and scalar data.
-
template<>
struct DatabaseInterface<ReplayDataSoANoUnitsMiniMap> - #include <replay_scalars.hpp>
Database interface implementation for ReplayDataSoANoUnitsMiniMap.
Public Static Functions
-
static inline auto getHeaderImpl(std::istream &dbStream) -> ReplayInfo
-
static inline auto getEntryUIDImpl(std::istream &dbStream) -> std::string
-
static inline auto getEntryImpl(std::istream &dbStream) -> ReplayDataSoANoUnitsMiniMap
-
static inline auto addEntryImpl(const ReplayDataSoANoUnitsMiniMap &d, std::ostream &dbStream) noexcept -> bool
-
static inline auto getHeaderImpl(std::istream &dbStream) -> ReplayInfo
-
struct StepDataNoUnitsMinimap
- #include <replay_scalars.hpp>
Replay step data that only contains scalar data.
Public Types
-
using has_scalar_data = std::true_type
Public Functions
-
auto operator==(const StepDataNoUnitsMinimap &other) const noexcept -> bool = default
-
using has_scalar_data = std::true_type
-
struct StepDataNoUnitsMinimapSoA
- #include <replay_scalars.hpp>
SoA representation of an array of StepDataNoUnitsMinimap.
Public Functions
-
auto operator==(const StepDataNoUnitsMinimapSoA &other) const noexcept -> bool = default
-
inline auto operator[](std::size_t idx) const noexcept -> StepDataNoUnitsMinimap
Gather step data from each array to make structure of data at step.
- Parameters:
idx – time index of replay to gather.
- Returns:
Gathered step data.
-
inline auto size() const noexcept -> std::size_t
Number of game steps in the Structure-of-Arrays.
- Returns:
std::size_t
-
auto operator==(const StepDataNoUnitsMinimapSoA &other) const noexcept -> bool = default
-
using ReplayDataNoUnitsMiniMap = ReplayDataTemplate<StepDataNoUnitsMinimap>