@rine-kit/pubg-intelligence 0.0.0-stage → 0.1.1

package/dist/src/style.d.ts

@@ -0,0 +1,304 @@
+import { type RoleCounts } from './fights.js';
+export declare const STYLE_SCHEMA_VERSION: 2;
+export declare const STYLE_RULE_VERSION: "play-style-v2";
+export declare const STYLE_BOOTSTRAP_RESAMPLES = 300;
+export declare const STYLE_BOOTSTRAP_SEED = 20261018;
+/** Ratio to teammates beyond which a difference is worth naming; its inverse applies on the low side. */
+export declare const STYLE_NOTABLE_RATIO = 1.15;
+/** Share of bootstrap resamples that must agree on the direction for a "lean". */
+export declare const STYLE_LEAN_CONFIDENCE = 0.85;
+export declare const STYLE_MIN_FIGHTS = 40;
+export declare const STYLE_MIN_DAMAGE = 1500;
+export declare const STYLE_MIN_MINUTES = 60;
+export declare const STYLE_MIN_SHOTS = 800;
+/** A shot counts as part of a fight when someone on either side was hurt within this long before or after it. */
+export declare const STYLE_ENGAGE_WINDOW_MS = 8000;
+/** Fewest shots in a first-shot or follow-up group before its hit rate is measured. */
+export declare const STYLE_MIN_SPLIT_SHOTS = 300;
+/** A shot fired this soon after the previous one from the same weapon is a follow-up bullet of a burst or spray. */
+export declare const STYLE_BURST_GAP_MS = 120;
+/** Prior shots pulling a teammate class hit rate toward the teammates' overall rate in the weapon-mix adjustment. */
+export declare const STYLE_CLASS_PRIOR_SHOTS = 200;
+export declare const STYLE_MIN_KNOCKS = 25;
+export declare const STYLE_MIN_SPACING_SAMPLES = 100;
+export declare const STYLE_MIN_ZONE_SAMPLES = 150;
+export declare const STYLE_MIN_PICKUP_MATCHES = 8;
+export declare const STYLE_ARCHETYPE_STRONG = 0.45;
+export declare const STYLE_ARCHETYPE_LEAN = 0.3;
+export declare const STYLE_ARCHETYPE_SLIGHT = 0.1;
+/** Weight of an axis that is close to teammates when scoring archetypes; lets a faint lean still point somewhere. */
+export declare const STYLE_EVEN_FACTOR = 0.25;
+export declare const STYLE_ISOLATED_METERS = 150;
+export declare const STYLE_SPACING_BUCKET_SECONDS = 15;
+export declare const STYLE_EARLY_LOOT_SECONDS = 240;
+export declare const STYLE_LATE_PHASE = 5;
+export declare const STYLE_EDGE_RATIO = 0.85;
+export declare const STYLE_MAX_FOOT_STEP_METERS = 400;
+export declare const STYLE_MAX_FOOT_GAP_SECONDS = 30;
+/** Upper edges (metres) of the distance bins used for a damage-weighted median engagement distance. */
+export declare const STYLE_DISTANCE_EDGES: readonly [10, 25, 50, 75, 100, 150, 200, 300];
+/** Upper edges (metres) of the nearest-teammate distance bins. */
+export declare const STYLE_SPACING_EDGES: readonly [20, 50, 100, 150, 250];
+export type WeaponClass = 'AR' | 'SMG' | 'DMR' | 'SR' | 'LMG' | 'SG' | 'Pistol' | 'other';
+export declare function weaponClassOf(weapon: string): WeaponClass;
+/** Damage categories of player-thrown or player-fired explosives and fire. */
+export declare const EXPLOSIVE_DAMAGE: ReadonlySet<string>;
+export interface ThrowableCounts {
+    frag: number;
+    smoke: number;
+    flash: number;
+    fire: number;
+}
+/** Raw-telemetry counters for one member of the squad in one match. */
+export interface PlayerRawStyle {
+    gunDamage: number;
+    /** Rocket, grenade and fire damage to opponents; counts toward damage per minute but not the shooting statistics. */
+    explosiveDamage: number;
+    headDamage: number;
+    /**
+     * Aimed shots: gun shots fired inside a fight, leaving out the shots that went into a downed player, with the shots
+     * that hurt a standing opponent and their damage. Each shot is paired with its damage by attackId, so one shotgun
+     * blast with several pellets is one hit. Fired outside any fight (walls, vehicles, testing, empty air) and finishing
+     * shots into a downed player are counted separately instead of as misses.
+     */
+    shots: number;
+    hits: number;
+    hitDamage: number;
+    /** Shots, hits and hit damage per weapon class (CLASS_ORDER), so hit rates can be compared on the same weapon mix. */
+    classShots: number[];
+    classHits: number[];
+    classHitDamage: number[];
+    /** The first shot of a burst (or a single shot) versus the follow-up bullets of an automatic burst, among the aimed shots. */
+    firstShots: number;
+    firstHits: number;
+    followShots: number;
+    followHits: number;
+    /** Shots fired with nobody on either side hurt within the engage window. */
+    idleShots: number;
+    /** Shots that went into a downed opponent. */
+    finishingShots: number;
+    dealtBins: number[];
+    /** Gun damage dealt in the early (circles 1-2), middle (3-4) and late (5+) game. */
+    phaseDamage: number[];
+    weaponDamage: Record<string, number>;
+    spacingBins: number[];
+    throwables: ThrowableCounts;
+    rides: number;
+    healUses: number;
+    boostUses: number;
+    /** Items picked up in the first minutes after landing. */
+    earlyPickups: number;
+    /** Distance covered on foot in metres. */
+    footMeters: number;
+    zoneSamples: number;
+    zoneEdgeSamples: number;
+    /** Distance in metres from the squad's landing centre; null when the landing is unknown. */
+    landingSpread: number | null;
+}
+/**
+ * One pass over a raw payload: engagement distance, weapons and game stage of the damage, spacing from teammates,
+ * utility, healing, early looting, movement, circle position, rides and landing spread.
+ */
+export declare function analyzeStyleTelemetry(payload: unknown, trackedIds: ReadonlySet<string>): Record<string, PlayerRawStyle>;
+/** Everything the style model needs to know about one member in one match. */
+export interface PlayerStyleMatch extends PlayerRawStyle {
+    minutes: number;
+    fights: RoleCounts;
+}
+export declare function emptyFights(): RoleCounts;
+type Vec = Float64Array;
+/** Damage-weighted median engagement distance in metres, interpolated inside the winning bin. */
+export declare function weightedMedianDistance(bins: readonly number[]): number | null;
+export type StyleAxisKey = 'range' | 'farShare' | 'closeShare' | 'marksman' | 'closeGun' | 'precision' | 'firstShot' | 'followShot' | 'burst' | 'tempo' | 'initiative' | 'fragging' | 'lateGame' | 'earlyLoot' | 'revive' | 'utility' | 'supplies' | 'isolation' | 'risk' | 'zoneEdge' | 'foot' | 'mobility' | 'dpm' | 'hitRate' | 'dmgPerShot' | 'knockRate' | 'conversion' | 'combat';
+export type StyleGroup = '战斗效率' | '射击' | '节奏' | '协作与补给' | '位置与风险';
+export interface StyleAxisDefinition {
+    key: StyleAxisKey;
+    group: StyleGroup;
+    label: string;
+    high: string;
+    low: string;
+    /** Derived from other axes (geometric mean of their ratios) instead of measured directly. */
+    composite?: readonly StyleAxisKey[];
+}
+/**
+ * Axes that make up the fighting-power index and their weights. Chosen on 112 ranked squad matches: damage per
+ * minute tracked fight wins and placement best; headshot share was unreliable (split-half 0.45) and unrelated to
+ * winning, and knock conversion depends on teammates finishing, so both stay as separate axes only.
+ */
+export declare const COMBAT_WEIGHTS: Readonly<Partial<Record<StyleAxisKey, number>>>;
+export declare const COMBAT_COMPONENTS: readonly StyleAxisKey[];
+export declare const STYLE_AXES: readonly StyleAxisDefinition[];
+/** Raw metric for one axis from a summed vector; null when there is too little data to measure it. */
+export declare function axisValue(key: StyleAxisKey, vector: Vec): number | null;
+export interface StyleInputMatch {
+    matchId: string;
+    players: Record<string, PlayerStyleMatch>;
+}
+/** stable: the 95% interval excludes parity; lean: the direction holds in most resamples; even: close to teammates. */
+export type StyleTier = 'stable' | 'lean' | 'even' | 'unknown';
+export interface AxisReading {
+    key: StyleAxisKey;
+    group: StyleGroup;
+    label: string;
+    value: number | null;
+    /** The same metric pooled over the player's teammates. */
+    matesValue: number | null;
+    /** Player value divided by the teammates' pooled value. */
+    ratio: number | null;
+    /** 95% bootstrap interval of the ratio across matches. */
+    low: number | null;
+    high: number | null;
+    /** Share of resamples that agree with the direction of the point estimate. */
+    confidence: number | null;
+    tier: StyleTier;
+    direction: 'high' | 'low' | null;
+    /** True when the interval excludes 1 (kept for callers that only need a flag). */
+    stable: boolean;
+}
+export interface StyleTrait {
+    key: StyleAxisKey;
+    text: string;
+    ratio: number;
+    tier: 'stable' | 'lean';
+    confidence: number | null;
+}
+/** stable and lean name a type; slight is a faint lean ("偏…"); balanced means close to teammates on everything. */
+export type ArchetypeTier = 'stable' | 'lean' | 'slight' | 'balanced';
+export interface PlayerStyle {
+    accountId: string;
+    name: string;
+    matches: number;
+    minutes: number;
+    axes: AxisReading[];
+    traits: StyleTrait[];
+    archetypes: Array<{
+        id: string;
+        label: string;
+        score: number;
+        tier: ArchetypeTier;
+    }>;
+    classShares: Array<{
+        weaponClass: WeaponClass;
+        share: number;
+    }>;
+    weapons: Array<{
+        weapon: string;
+        share: number;
+    }>;
+    landingSpread: number | null;
+    summary: string;
+}
+export interface StyleOverlap {
+    accountIds: [string, string];
+    names: [string, string];
+    similarity: number;
+    sharedTraits: string[];
+}
+export interface AxisSpread {
+    key: StyleAxisKey;
+    group: StyleGroup;
+    label: string;
+    highest: {
+        name: string;
+        value: number;
+        ratio: number | null;
+        tier: StyleTier;
+    };
+    lowest: {
+        name: string;
+        value: number;
+        ratio: number | null;
+        tier: StyleTier;
+    };
+    /** Highest value divided by lowest value; how differently the squad plays on this axis. */
+    spread: number;
+    /** True when at least one of the two extremes is a stable or lean difference from teammates. */
+    supported: boolean;
+}
+export interface CombatEntry {
+    accountId: string;
+    name: string;
+    rank: number;
+    ratio: number | null;
+    low: number | null;
+    high: number | null;
+    confidence: number | null;
+    tier: StyleTier;
+    components: Array<{
+        key: StyleAxisKey;
+        label: string;
+        ratio: number | null;
+        tier: StyleTier;
+    }>;
+}
+/** Shots to hits to knocks to kills for one member, summed over matches. */
+export interface FunnelEntry {
+    accountId: string;
+    name: string;
+    fights: number;
+    minutes: number;
+    /** Aimed shots (inside fights, not into downed players) and the ones that hurt a standing opponent. */
+    shots: number;
+    hits: number;
+    hitRate: number | null;
+    /** Hit rate of the first shot of a burst (or a single shot) and of the follow-up bullets of an automatic burst. */
+    firstShotRate: number | null;
+    followShotRate: number | null;
+    /** Share of aimed shots that were follow-up bullets of a burst. */
+    burstShare: number | null;
+    /** Shots fired with nobody hurt around them, as a share of all shots that were not finishing shots. */
+    idleShare: number | null;
+    /** Shots into downed opponents, as a share of all shots. */
+    finishingShare: number | null;
+    hitDamage: number;
+    damagePerShot: number | null;
+    damagePerMinute: number | null;
+    knocks: number;
+    hitsPerKnock: number | null;
+    kills: number;
+    knockFights: number;
+    knockRate: number | null;
+    chainsDealt: number;
+    chainsFinished: number;
+    conversion: number | null;
+}
+export interface CombatHighlight {
+    name: string;
+    label: string;
+    ratio: number;
+    tier: 'stable' | 'lean';
+    confidence: number | null;
+}
+export interface SquadStyle {
+    schemaVersion: typeof STYLE_SCHEMA_VERSION;
+    ruleVersion: typeof STYLE_RULE_VERSION;
+    matches: number;
+    players: PlayerStyle[];
+    /** One sentence on who fights best, or that the squad cannot be separated on the overall index. */
+    combatVerdict: string;
+    /** Component-level strengths and weaknesses that are stable or lean, strongest first. */
+    combatHighlights: CombatHighlight[];
+    combat: CombatEntry[];
+    funnel: FunnelEntry[];
+    spreads: AxisSpread[];
+    overlaps: StyleOverlap[];
+    gaps: string[];
+    notes: string[];
+}
+export declare function mulberry32(seed: number): () => number;
+export declare function percentile(sorted: readonly number[], fraction: number): number;
+export declare function tierFor(ratio: number | null, low: number | null, high: number | null, confidence: number | null): {
+    tier: StyleTier;
+    direction: 'high' | 'low' | null;
+};
+export interface BuildSquadStyleInput {
+    matches: readonly StyleInputMatch[];
+    names: ReadonlyMap<string, string>;
+}
+/**
+ * One style profile per member: nineteen measurable axes, each expressed as a ratio to the player's teammates
+ * (excluding the player) with a bootstrap interval over matches. Differences are graded stable, lean or even,
+ * so a squad that plays alike still gets honest, ranked tendencies instead of an empty card.
+ */
+export declare function buildSquadStyle(input: BuildSquadStyleInput): SquadStyle;
+export {};