battle

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package battle detects fights from clusters of killmails.

A "battle" is not a thing EVE records — it is inferred from the shape of the killmails: a burst of kills in one system, and two sides that can be told apart from who shot whom. Both halves are heuristics, and the interesting parts of this package are the filters that stop the heuristics being fooled.

Index

Constants

View Source
const (
	// SegmentDuration is the granularity boundaries are refined at. Five
	// minutes is short enough to find the real edges of a fight and long
	// enough that a lull between waves does not split one battle into three.
	SegmentDuration = 5 * time.Minute

	// MinKillsPerSegment is what makes a segment "active". Below it, the
	// killmails are ambient — gate camps, ratting, unrelated skirmishes.
	MinKillsPerSegment = 5

	// MaxInactiveSegments is how much quiet ends a battle. Thirty minutes:
	// long enough to survive a reship, short enough that the next fight in the
	// same system is a separate battle.
	MaxInactiveSegments = 6

	// KillwhoreThreshold drops attackers who contributed almost nothing.
	// Someone who applied 4% of the damage was passing through, and counting
	// them as a belligerent puts unrelated corporations on a side.
	KillwhoreThreshold = 0.05

	// MultiPartyConflictRatio is when a two-sided model stops describing the
	// fight. Above it, too many pairs that shot each other ended up on the same
	// side for the split to mean anything.
	MultiPartyConflictRatio = 0.20
)

Detection parameters.

Variables

This section is empty.

Functions

func ClearWindow

func ClearWindow(ctx context.Context, pool *pgxpool.Pool, from, to any) ([]int64, error)

ClearWindow removes auto-detected battles overlapping a window and reports their ids.

Called before re-detecting the window, and it has to be the whole window rather than each battle as it is re-stored. A late killmail can move a fight's start earlier, and a delete keyed on the new start would match nothing and leave the old row behind — the same battle stored twice, minutes apart. Clearing first makes re-detection a replacement rather than an accumulation.

The ids come back because each one may have an announcement in the ticker that now points at a battle that no longer exists.

Custom battles are never touched: a person assembled those, and the detector does not get to overrule them.

func HasOverlap

func HasOverlap(
	ctx context.Context,
	pool *pgxpool.Pool,
	systemID int32,
	from, to time.Time,
) (bool, error)

HasOverlap reports whether a battle already occupies the same system and time span. The historical TS command skips those rather than replacing them.

func Store

func Store(ctx context.Context, pool *pgxpool.Pool, b *Detected) (int64, error)

Store writes a detected battle and its two sides.

Replaces any existing battle for the same system and start time, so storing the same battle twice corrects it rather than duplicating it. That covers a re-store within one run; a re-detection whose boundaries have moved is handled by ClearWindow, which runs first.

Types

type Attacker

type Attacker struct {
	KillmailID    int64
	CharacterID   int32
	CorporationID int32
	AllianceID    int32
	FactionID     int32
	DamageDone    int64
	FinalBlow     bool
}

Attacker is one participant on a kill.

type Candidate

type Candidate struct {
	SolarSystemID int32
	Kills         int
}

Candidate is a system and window busy enough to be worth analysing.

func FindCandidates

func FindCandidates(ctx context.Context, pool *pgxpool.Pool, from, to any) ([]Candidate, error)

FindCandidates returns the systems with enough kills in a window to contain a battle.

A cheap pre-filter: the detection itself loads every killmail and its attackers, which is far too expensive to run against every system in New Eden for every window. Requiring the minimum segment count over the whole window is a loose bound — a system can pass here and still have no active segment — but it turns thousands of systems into a handful.

type Detected

type Detected struct {
	SolarSystemID   int32
	RegionID        int32
	Start           time.Time
	End             time.Time
	DurationMinutes int
	KillCount       int
	IskDestroyed    float64
	Teams           [2]Team
	MultiParty      bool
	KillmailIDs     []int64
}

Detected is a battle and its two sides.

func Detect

func Detect(killmails []Killmail, attackersByKill map[int64][]Attacker, required *time.Time) *Detected

Detect runs the whole pipeline over one system's killmails.

Returns nil when the killmails are not a battle — too sparse to have an active segment, or with no belligerents left after filtering.

func DetectAll

func DetectAll(killmails []Killmail, attackersByKill map[int64][]Attacker) []*Detected

DetectAll finds every distinct fight in one system window.

Detect returns the first active burst when no required timestamp is supplied. A daily re-scan can contain several fights in the same system, so stopping after that first result silently drops the rest. Advancing to the end of each detected window preserves the same boundary logic while exhausting the input.

type HotspotWindow

type HotspotWindow struct {
	SolarSystemID int32
	Start         time.Time
	End           time.Time
	Kills         int
}

HotspotWindow is one or more nearby UTC hours whose kill count passed the command's candidate threshold.

func FindHotspotWindows

func FindHotspotWindows(
	ctx context.Context,
	pool *pgxpool.Pool,
	from, to time.Time,
	minKills int,
) ([]HotspotWindow, error)

FindHotspotWindows reproduces the TypeScript backfill command's hourly candidate scan. Hot hours separated by at most one empty hour are merged.

type Killmail

type Killmail struct {
	KillmailID          int64
	KillmailTime        time.Time
	SolarSystemID       int32
	RegionID            int32
	TotalValue          float64
	VictimCorporationID int32
	VictimAllianceID    int32
	VictimFactionID     int32
	VictimShipTypeID    int32
}

Killmail is one kill in a candidate battle.

func LoadSystem

func LoadSystem(ctx context.Context, pool *pgxpool.Pool, systemID int32, from, to any) ([]Killmail, map[int64][]Attacker, error)

LoadSystem reads one system's killmails and attackers for a window.

type Team

type Team struct {
	Entries      []TeamEntry `json:"entries"`
	Kills        int64       `json:"total_kills"`
	Losses       int64       `json:"total_losses"`
	IskDestroyed float64     `json:"total_isk_destroyed"`
	IskLost      float64     `json:"total_isk_lost"`
}

Team is one side of a battle.

func ComputeTeamStats

func ComputeTeamStats(killmails []Killmail, attackersByKill map[int64][]Attacker, a TeamAssignment) [2]Team

ComputeTeamStats tallies each side from the killmails and the assignment.

Direct corporation placement wins, with the cohered alliance placement as a fallback. That is the current backend behavior: a corporation filtered from the interaction graph can still have its kills and losses attributed when its alliance was unambiguously assigned by the rest of the fight.

Team totals are accumulated from sided events rather than derived from the member rows. A sided event can have no corporation row (for example an alliance-affiliated NPC corporation), so the two representations are not guaranteed to sum to the same value.

type TeamAssignment

type TeamAssignment struct {
	// CorpTeam maps a corporation to side 0 or 1. A corporation absent from
	// this map was filtered out and must not be counted anywhere.
	CorpTeam map[int32]int

	// CorpAlliance is each corporation's alliance at the time of the fight,
	// taken from the killmails rather than from current membership.
	CorpAlliance map[int32]int32

	// MultiParty marks a fight that two sides do not describe — a
	// free-for-all, or a third party that engaged both.
	MultiParty bool
}

TeamAssignment is the result of splitting belligerents into two sides.

func AssignTeams

func AssignTeams(killmails []Killmail, attackersByKill map[int64][]Attacker) TeamAssignment

AssignTeams splits the belligerents into two opposing sides.

The signal is who shot whom: every attacker-victim pair is an edge, weighted by the value of the kill on a log scale so a titan counts for more than a shuttle without swamping everything. Sides are then assigned greedily from the strongest edges outward.

Two filters matter more than the algorithm:

  • Killwhores. Someone who did 4% of the damage was passing through. Without this filter, a single opportunistic attacker drags their whole corporation onto a side of a fight they had nothing to do with.
  • NPCs. An attacker with a faction and no character is an NPC, and NPCs shoot everyone. Counting them creates edges between corporations that never fought each other.

type TeamEntry

type TeamEntry struct {
	CorporationID int32   `json:"corporation_id"`
	AllianceID    int32   `json:"alliance_id"`
	Kills         int64   `json:"kills"`
	Losses        int64   `json:"losses"`
	IskDestroyed  float64 `json:"isk_destroyed"`
	IskLost       float64 `json:"isk_lost"`
}

TeamEntry is one corporation's contribution to a side.

type Window

type Window struct {
	Start time.Time
	End   time.Time
}

Window is a refined battle start and end.

func RefineBoundaries

func RefineBoundaries(killmails []Killmail, minKills int, required *time.Time) *Window

RefineBoundaries finds the real extent of a fight within a set of killmails.

The killmails must be sorted by time. Segments with enough kills are active; a run of active segments is a candidate battle, ended by enough consecutive quiet ones. A required time selects the candidate containing it, which is how a specific kill is resolved to the battle it belonged to rather than to the first burst in the window.

Returns nil when nothing in the range is busy enough to be a battle.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL