rep

Documentation

Overview

Package rep models StarCraft: Brood War replays.

Information sources:

BWHF replay model:

https://github.com/icza/bwhf/tree/master/src/hu/belicza/andras/bwhf/model

BWAPI replay tool:

https://github.com/bwapi/bwapi/tree/master/bwapi/libReplayTool

Index

• Constants
• func CmdIneffKind(cmds []repcmd.Cmd, i int) repcore.IneffKind
• func IsCmdEffective(cmds []repcmd.Cmd, i int) bool
• type Commands
• type CommandsDebug
• type Computed
• type DebugFieldDescriptor
• type Header
  • func (h *Header) Duration() time.Duration
  • func (h *Header) MapSize() string
  • func (h *Header) Matchup() string
  • func (h *Header) PlayerNames() string
• type HeaderDebug
• type MapData
  • func (md *MapData) MaxHumanPlayers() (count int)
• type MapDataDebug
• type MapGraphics
• type PlacedUnit
• type Player
• type PlayerDesc
  • func (pd *PlayerDesc) Redundancy() int
• type Replay
  • func (r *Replay) Compute()
• type Resource
• type ShieldBattery
• type Sprite
• type StartLocation

Constants

const (
	// EAPMVersion is a Semver2 compatible version of the EAPM algorithm.
	EAPMVersion = "v1.0.5"
)

Functions

func CmdIneffKind

func CmdIneffKind(cmds []repcmd.Cmd, i int) repcore.IneffKind

CmdIneffKind returns the IneffKind classification of the given command.

cmds must contain commands of the cmd's player only. It may be a partially filled slice, but must contain the player's all commands up to the command in question: len(cmds) > i must hold.

func IsCmdEffective

func IsCmdEffective(cmds []repcmd.Cmd, i int) bool

IsCmdEffective tells if a command is considered effective so it can be included in EAPM calculation.

cmds must contain commands of the cmd's player only. It may be a partially filled slice, but must contain the player's all commands up to the command in question: len(cmds) > i must hold.

Types

type Commands

type Commands struct {
	// Cmds is the commands of the players
	Cmds []repcmd.Cmd

	// ParseErrCmds is list of commands that failed to parse.
	// A parse error command may imply additional skipped (not recorded) commands
	// at the same frame.
	ParseErrCmds []*repcmd.ParseErrCmd

	// Debug holds optional debug info.
	Debug *CommandsDebug `json:"-"`
}

Commands contains the players' commands.

type CommandsDebug

type CommandsDebug struct {
	// Data is the raw, uncompressed data of the section.
	Data []byte
}

CommandsDebug holds debug info for the commands section.

type Computed

type Computed struct {
	// LeaveGameCmds of the players.
	LeaveGameCmds []*repcmd.LeaveGameCmd

	// ChatCmds is a collection of the received chat messages.
	ChatCmds []*repcmd.ChatCmd

	// WinnerTeam if can be detected by the "largest remaining team wins"
	// algorithm. It's 0 if winner team is unknown.
	WinnerTeam byte

	// PlayerID of the replay saver, if known
	RepSaverPlayerID *byte

	// PlayerDescs contains player descriptions in team order.
	PlayerDescs []*PlayerDesc

	// PIDPlayerDescs maps from player ID to PlayerDesc.
	// Note: all computer players have ID=255, so this won't be accurate for
	// computer players.
	PIDPlayerDescs map[byte]*PlayerDesc `json:"-"`
}

Computed contains computed, derived data from other parts of the replay.

type DebugFieldDescriptor

type DebugFieldDescriptor struct {
	Offset int    // Offset of the data field
	Length int    // Length of the data field in bytes
	Name   string // Name of the data field
}

DebugFieldDescriptor describes some arbitrary data in a byte slice.

type Header

type Header struct {
	// Engine used to play the game and save the replay
	Engine *repcore.Engine

	// Version contains information about the replay version.
	// Since version is not stored in replays, this only designates certain version ranges deducted from replay format.
	// Current possible values are:
	//   - "-1.16": version is 1.16 or older
	//   - "1.18-1.20": version is 1.18..1.20
	//   - "1.21+": version is 1.21 or newer
	Version string

	// Frames is the number of frames. There are approximately ~23.81 frames in
	// a second. (1 frame = 0.042 second to be exact).
	Frames repcore.Frame

	// StartTime is the timestamp when the game started
	StartTime time.Time

	// Title is the game name / title
	Title string

	// RawTitle is the undecoded Title data. It may differ from Title if the latter is invalid UTF-8.
	RawTitle string `json:"-"`

	// Size of the map
	MapWidth, MapHeight uint16

	// AvailSlotsCount is the number of available slots
	AvailSlotsCount byte

	// Speed is the game speed
	Speed *repcore.Speed

	// Type is the game type
	Type *repcore.GameType

	// SubType indicates the size of the "Home" team.
	// For example, in case of 3v5 this is 3, in case of 7v1 this is 7.
	SubType uint16

	// Host is the game creator's name.
	Host string

	// RawHost is the undecoded Host data. It may differ from Host if the latter is invalid UTF-8.
	RawHost string `json:"-"`

	// Map name
	Map string

	// RawMap is the undecoded Map data. It may differ from Map if the latter is invalid UTF-8.
	RawMap string `json:"-"`

	// Slots contains all players of the game (including open/closed slots)
	Slots []*Player `json:"-"`

	// OrigPlayers contains the actual ("real") players of the game
	// in the order recorded in the replay.
	OrigPlayers []*Player `json:"-"`

	// Players contains the actual ("real") players of the game
	// in team order.
	Players []*Player

	// PIDPlayers maps from player ID to Player.
	// Note: all computer players have ID=255, so this won't be accurate for
	// computer players.
	PIDPlayers map[byte]*Player `json:"-"`

	// Debug holds optional debug info.
	Debug *HeaderDebug `json:"-"`
}

Header models the replay header.

func (*Header) Duration

func (h *Header) Duration() time.Duration

Duration returns the game duration.

func (*Header) MapSize

func (h *Header) MapSize() string

MapSize returns the map size in widthxheight format, e.g. "64x64".

func (*Header) Matchup

func (h *Header) Matchup() string

Matchup returns the matchup, the race letters of players in team order, inserting 'v' between different teams, e.g. "PvT" or "PTZvZTP". Observers are excluded from the matchup.

func (*Header) PlayerNames

func (h *Header) PlayerNames() string

PlayerNames returns a comma separated list of player names in team order, inserting " VS " between different teams.

type HeaderDebug

type HeaderDebug struct {
	// Data is the raw, uncompressed data of the section.
	Data []byte

	// Descriptor fields of the data
	Fields []*DebugFieldDescriptor
}

HeaderDebug holds debug info for the header section.

type MapData

type MapData struct {
	// Version of the map.
	// 0x2f: StarCraft beta
	// 0x3b: 1.00-1.03 StarCraft and above ("hybrid")
	// 0x3f: 1.04 StarCraft and above ("hybrid")
	// 0x40: StarCraft Remastered
	// 0xcd: Brood War
	// 0xce: Brood War Remastered
	Version uint16

	// TileSet defines the tile set used on the map.
	TileSet *repcore.TileSet

	TileSetMissing bool `json:"tileSetMissing,omitempty"`

	// Scenario name
	Name string

	// Scenario description
	Description string

	// PlayerOwners defines the player types (player owners).
	PlayerOwners []*repcore.PlayerOwner

	// PlayerSides defines the player sides (player races).
	PlayerSides []*repcore.PlayerSide

	// Tiles is the tile data of the map (within the tile set): width x height elements.
	// 1 Tile is 32 units (pixel)
	Tiles []uint16 `json:",omitempty"`

	// Mineral field locations on the map
	MineralFields []Resource `json:",omitempty"`

	// Geyser locations on the map
	Geysers []Resource `json:",omitempty"`

	// StartLocations on the map
	StartLocations []StartLocation

	// MapGraphics holds data for map image rendering.
	MapGraphics *MapGraphics `json:",omitempty"`

	// Debug holds optional debug info.
	Debug *MapDataDebug `json:"-"`
}

MapData describes the map and objects on it.

func (*MapData) MaxHumanPlayers

func (md *MapData) MaxHumanPlayers() (count int)

MaxHumanPlayers returns the max number of human players on the map.

type MapDataDebug

type MapDataDebug struct {
	// Data is the raw, uncompressed data of the section.
	Data []byte
}

MapDataDebug holds debug info for the map data section.

type MapGraphics

type MapGraphics struct {
	// PlacedUnits contains all placed units on the map.
	// This includes mineral fields, geysers and startlocations too.
	// This also includes unit sprites.
	PlacedUnits []*PlacedUnit

	// Sprites contains additional visual sprites on the map.
	Sprites []*Sprite
}

MapGraphics holds info usually required only for map image rendering.

type PlacedUnit

type PlacedUnit struct {
	repcore.Point

	// UnitID is the unit id. This value is used in repcmd.Unit.UnitID.
	UnitID uint16

	// SlotID of the owner of this unit.
	// Belongs to the Player with matching Player.SlotID
	SlotID byte

	// ResourceAmount of if it's a resource
	ResourceAmount uint32 `json:",omitempty"`

	// Sprite tells if this unit is a sprite.
	Sprite bool `json:",omitempty"`
}

type Player

type Player struct {
	// SlotID is the slot ID
	SlotID uint16

	// ID of the player.
	// Computer players all have ID=255.
	ID byte

	// Type is the player type
	Type *repcore.PlayerType

	// Race of the player
	Race *repcore.Race

	// Team of the player
	Team byte

	// Name of the player
	Name string

	// RawName is the undecoded Name data. It may differ from Name if the latter is invalid UTF-8.
	RawName string `json:"-"`

	// Color of the player
	Color *repcore.Color

	// Observer tells if the player only observes the game and should be excluded
	// from matchup.
	// This is not stored in replays, this is a calculated property.
	Observer bool
}

Player represents a player of the game.

type PlayerDesc

type PlayerDesc struct {
	// PlayerID this PlayerDesc belongs to.
	PlayerID byte

	// LastCmdFrame is the frame of the last command of the player.
	LastCmdFrame repcore.Frame

	// CmdCount is the number of commands of the player.
	CmdCount uint32

	// APM is the APM (Actions Per Minute) of the player.
	APM int32

	// EffectiveCmdCount is the number of effective commands of the player.
	EffectiveCmdCount uint32

	// EAPM is the EAPM (Effective Actions Per Minute) of the player.
	EAPM int32

	// StartLocation of the player
	StartLocation *repcore.Point

	// StartDirection is the direction of the start location of the player
	// compared to the center of the map, expressed using the clock,
	// e.g. 1 o'clock, 6 o'clock etc.
	StartDirection int32
}

PlayerDesc contains computed / derived data for a player.

func (*PlayerDesc) Redundancy

func (pd *PlayerDesc) Redundancy() int

Redundancy returns the redundancy percent of the player's commands. A command is redundant if its ineffective.

type Replay

type Replay struct {
	// Stored here for decoding purposes only.
	RepFormat repdecoder.RepFormat `json:"-"`

	// Header of the replay
	Header *Header

	// Commands of the players
	Commands *Commands

	// MapData describes the map and objects on it
	MapData *MapData

	// Computed contains data that is computed / derived from other parts of the
	// replay.
	Computed *Computed

	// ShieldBattery holds info if game was played on ShieldBattery
	ShieldBattery *ShieldBattery `json:",omitempty"`
}

Replay models an SC:BW replay.

func (*Replay) Compute

func (r *Replay) Compute()

Compute creates and computes the Computed field.

type Resource

type Resource struct {
	// Location of the resource
	repcore.Point

	// Amount of the resource
	Amount uint32
}

Resource describes a resource (mineral field of vespene geyser).

type ShieldBattery

type ShieldBattery struct {
	StarCraftExeBuild    uint32
	ShieldBatteryVersion string
	GameID               string
}

ShieldBattery models the data parsed from the ShieldBattery custom section.

type Sprite

type Sprite struct {
	repcore.Point

	// SpriteID is the sprite id.
	SpriteID uint16
}

type StartLocation

type StartLocation struct {
	repcore.Point

	// SlotID of the owner of this start location;
	// Belongs to the Player with matching Player.SlotID
	SlotID byte
}

StartLocation describes a player start location on the map