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
- func ClearWindow(ctx context.Context, pool *pgxpool.Pool, from, to any) ([]int64, error)
- func HasOverlap(ctx context.Context, pool *pgxpool.Pool, systemID int32, from, to time.Time) (bool, error)
- func Store(ctx context.Context, pool *pgxpool.Pool, b *Detected) (int64, error)
- type Attacker
- type Candidate
- type Detected
- type HotspotWindow
- type Killmail
- type Team
- type TeamAssignment
- type TeamEntry
- type Window
Constants ¶
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 ¶
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 ¶
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 ¶
Candidate is a system and window busy enough to be worth analysing.
func FindCandidates ¶
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 ¶
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 ¶
HotspotWindow is one or more nearby UTC hours whose kill count passed the command's candidate threshold.
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.
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 ¶
Window is a refined battle start and end.
func RefineBoundaries ¶
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.