Observer

Contains StarCraft II game observation classes. Each variant saves observations at different rates to balance between verbosity and dataset size.

Author: Bryce Ferenczi
Version: 0.1
Date: 2024-05-27
Copyright: Copyright (c) 2024

namespace cvt

template<typename DataSoA> class ActionConverter : public cvt::BaseConverter<DataSoA>

#include <observer.hpp>

The alphastar dataset only saves if the player makes an action and its associated preceding observation.

Private Functions

void OnStep() final: Copies common data each step, will only commit that data on action observation. Each step will have the previous step’s observation and current step’s action.

template<typename DataSoA> class BaseConverter : public sc2::ReplayObserver

#include <observer.hpp>

Base replay observer and converter that implements functions common to all the other sampling variants.

Template Parameters:: DataSoA – observation data structure to be observed and serialized

Subclassed by cvt::ActionConverter< DataSoA >, cvt::FullConverter< DataSoA >, cvt::StridedConverter< DataSoA >

Public Functions

inline auto loadDB(const std::filesystem::path &path) -> bool

Loads the database from the specified path.

Parameters:: path – The path to the database file.
Returns:: True if the database was loaded successfully, false otherwise.

inline void setReplayInfo(std::string_view hash, std::uint32_t playerId) noexcept

Sets the replay information for the BaseConverter.

Parameters:

hash – The hash of the replay.
playerId – The ID of the player.

void OnGameStart() override: This function is called when the game starts. Gathers basic replay info such as player mmr.

void OnGameEnd() override: Checks if the game has ended in a normal state and then writes replay to database.

inline auto hasWritten() const noexcept -> bool

Checks if the BaseConverter has successfully written data.

Returns:: true if the BaseConverter has successfully written data, false otherwise.

inline auto isKnownHash(const std::string &hash) const noexcept -> bool

Checks if a given hash is known in the database.

Note

const std::string& used rather than std::string_view due to lack of set::contains compatibility.

Parameters:: hash – The hash to check.
Returns:: True if the hash is known, false otherwise.

inline void addKnownHash(std::string_view hash) noexcept

Adds a known hash to the BaseConverter’s list of known hashes.

Parameters:: hash – The hash to be added.

void clear() noexcept

Clears the BaseConverter object. This function clears the internal state of the BaseConverter object. It resets all the member variables to their default values.

See also

BaseConverter

Note

This function does not deallocate any memory.

Protected Functions

void copyHeightMapData() noexcept: Copies the height map data for the match.

void copyUnitData() noexcept: Copies the unit data from observation to stepData.back().

void copyActionData() noexcept: Copies the action data to stepData.back().

void copyDynamicMapData() noexcept: Copies the dynamic map data to stepData.back().

void copyCommonData() noexcept: Copies the common data such as scalars gameStep, minerals, vespene to stepData.back().

inline auto reassignResourceId(const NeutralUnit &unit) noexcept -> bool

Reassigns the resource ID for a given NeutralUnit when it changes visibility. It gets reassociated with an old id based on locality.

Parameters:: unit – The NeutralUnit for which the resource ID needs to be reassigned.
Returns:: True if the resource ID was successfully reassigned, false otherwise.

template<std::ranges::range R> inline void initResourceObs(R &&neutralUnits) noexcept: Initializes the resource observations with the first observation and default values.

template<std::ranges::range R> inline void updateResourceObs(R &&neutralUnits) noexcept: Updates the resource observer. Update resourceObs_ based on visible units. Reassign jumbled UIDs to be consistent over the game assign snapshot unis the last known quantity.

Protected Attributes

ReplayDatabase<DataSoA> database_

DataSoA::struct_type replayData_

std::unordered_map<UID, ResourceObs> resourceObs_

std::unordered_set<std::string> knownHashes_ = {}

bool mapDynHasLogged_ = {false}

bool mapHeightHasLogged_ = {false}

bool writeSuccess_ = {false}

std::chrono::high_resolution_clock::time_point start_ = {}

template<typename DataSoA> class FullConverter : public cvt::BaseConverter<DataSoA>

#include <observer.hpp>

Convert and serialize every observation. This could be big.

Private Functions

void OnStep() final: Copies observation data every step.

struct ResourceObs

#include <observer.hpp>

Vespene/Minearal resource observation.

Public Members

UID id: Original ID.

Point3f pos: Location on map.

int qty: Last observation quantity.

template<typename DataSoA> class StridedConverter : public cvt::BaseConverter<DataSoA>

#include <observer.hpp>

Convert and serialize at a particular stride (i.e. every 10 steps). Also has flag which enables saving on player actions.

Public Functions

inline void SetStride(std::size_t stride)

Set the sampling stride.

Parameters:: stride – stride to set between 1 and 10’000

inline void SetActionSaving(bool should_save) noexcept

Set whether gamesteps with actions should be saved.

Parameters:: should_save – true if actions are saved

inline auto ActionsAreSaved() const noexcept -> bool

Query if actions are being saved.

Returns:: True if actions are being saved

inline auto GetStride() const noexcept -> std::size_t

Get the currently set stride.

Returns:: Currently set stride

inline void OnGameStart() final: Checks the stride has been set before normal start.

Private Functions

void OnStep() final: Only samples observation/action at strided intervals.

Private Members

std::size_t stride_ = {0}: Number of replay steps between saving observations.

bool saveActions_ = {false}: Flag to also enable saving on player actions.