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

package/dist/src/battle.d.ts

@@ -0,0 +1,280 @@
+import { type NormalizedMatch, type TelemetryEventPhase, type TelemetryLocation } from '@rine-kit/pubg-domain';
+export declare const BATTLE_RECONSTRUCTION_SCHEMA_VERSION: 2;
+export declare const BATTLE_RECONSTRUCTION_PARSER_VERSION: "battle-reconstruction-v2";
+export declare const BATTLE_CONTACT_GAP_SECONDS = 28;
+export declare const BATTLE_KNOCK_OUTCOME_WINDOW_SECONDS = 120;
+export declare const BATTLE_POST_KNOCK_RESPONSE_WINDOW_SECONDS = 30;
+export declare const BATTLE_CONTEXT_BEFORE_SECONDS = 5;
+export declare const BATTLE_CONTEXT_AFTER_SECONDS = 28;
+export declare const BATTLE_POSITION_SAMPLE_INTERVAL_SECONDS = 15;
+export type BattleEventType = 'ATTACK' | 'DAMAGE' | 'KNOCK' | 'KILL' | 'REVIVE' | 'POSITION';
+export type BattleTimestampSource = 'absolute' | 'clock' | 'elapsed' | 'unknown';
+export type ObservedPlayerState = 'ACTIVE_OBSERVED' | 'KNOCKED' | 'DEAD' | 'UNKNOWN';
+export type KnockOutcome = 'KILL' | 'REVIVE' | null;
+export interface BattleVector {
+    x: number | null;
+    y: number | null;
+    z: number | null;
+}
+export interface BattleZoneState {
+    center: BattleVector | null;
+    radius: number | null;
+}
+export interface BattleCircleSample {
+    id: string;
+    sourceEventId: string;
+    timeSeconds: number | null;
+    timestampSource: BattleTimestampSource;
+    phase: TelemetryEventPhase;
+    elapsedSeconds: number | null;
+    alivePlayers: number | null;
+    aliveTeams: number | null;
+    safetyZone: BattleZoneState;
+    poisonGasWarningZone: BattleZoneState;
+    redZone: BattleZoneState;
+    blackZone: BattleZoneState;
+}
+export interface BattleCircleTransition {
+    id: string;
+    fromSampleId: string;
+    toSampleId: string;
+    fromSourceEventId: string;
+    toSourceEventId: string;
+    timeSeconds: number;
+    changedZones: Array<'safetyZone' | 'poisonGasWarningZone' | 'redZone' | 'blackZone'>;
+}
+export interface BattleSourceEvent {
+    id: string;
+    sourceEventId: string;
+    type: BattleEventType;
+    rawType: string;
+    timeSeconds: number | null;
+    timestampSource: BattleTimestampSource;
+    phase: TelemetryEventPhase;
+    actorId: string | null;
+    victimId: string | null;
+    actorTeamId: string | null;
+    victimTeamId: string | null;
+    attackId: string | null;
+    dbnoId: string | null;
+    semanticKey: string;
+    damage: number;
+    hit: boolean;
+    weaponId: string | null;
+    /** Optional supplemental telemetry facts used by versioned R2 rules. */
+    blueZone?: boolean | null;
+    damageReason?: string | null;
+    location: TelemetryLocation | null;
+}
+export interface BattleTelemetryDocument {
+    schemaVersion: typeof BATTLE_RECONSTRUCTION_SCHEMA_VERSION;
+    parserVersion: typeof BATTLE_RECONSTRUCTION_PARSER_VERSION;
+    rawEventCount: number;
+    domainNormalizedEventCount: number;
+    events: BattleSourceEvent[];
+    circleSamples: BattleCircleSample[];
+    diagnostics: {
+        unrecognizedDomainEventCount: number;
+        excludedPreMatchEventCount: number;
+        excludedPreMatchContactEventCount: number;
+        untimedBattleEventCount: number;
+    };
+}
+export interface BattleTimelineEvent {
+    id: string;
+    sourceEventId: string;
+    type: BattleEventType;
+    rawType: string;
+    timeSeconds: number;
+    timestampSource: BattleTimestampSource;
+    actorRef: string | null;
+    victimRef: string | null;
+    actorTeamRef: string | null;
+    victimTeamRef: string | null;
+    damage: number | null;
+    weapon: string | null;
+    location: BattleVector | null;
+}
+export interface BattlePlayerState {
+    playerRef: string;
+    state: ObservedPlayerState;
+    lastObservedAtSeconds: number | null;
+}
+export interface BattleTeamSummary {
+    teamRef: string | null;
+    memberRefs: string[];
+    tracked: boolean;
+    lastObserved: {
+        active: number;
+        knocked: number;
+        dead: number;
+        unknown: number;
+        completeness: 'observed-members-only';
+        states: BattlePlayerState[];
+    };
+}
+export interface KnockChain {
+    knockEventId: string;
+    knockedPlayerRef: string | null;
+    attackerRef: string | null;
+    knockAtSeconds: number;
+    outcome: KnockOutcome;
+    outcomeEventId: string | null;
+    outcomeAtSeconds: number | null;
+    elapsedSeconds: number | null;
+    windowSeconds: typeof BATTLE_KNOCK_OUTCOME_WINDOW_SECONDS;
+}
+export interface BattlePositionSample {
+    sourceEventId: string;
+    playerRef: string;
+    teamRef: string | null;
+    timeSeconds: number;
+    location: BattleVector;
+}
+export interface BattleEpisode {
+    id: string;
+    startSeconds: number;
+    endSeconds: number;
+    durationSeconds: number;
+    contactGapSeconds: typeof BATTLE_CONTACT_GAP_SECONDS;
+    participantRefs: string[];
+    teams: BattleTeamSummary[];
+    firstKnock: {
+        sourceEventId: string;
+        attackerRef: string | null;
+        victimRef: string | null;
+        timeSeconds: number;
+    } | null;
+    knockChains: KnockChain[];
+    timeline: BattleTimelineEvent[];
+    positions: BattlePositionSample[];
+    circleSampleRefs: string[];
+    circleTransitionRefs: string[];
+    evidenceEventIds: string[];
+    diagnostics: {
+        conflictingStateTransitions: number;
+        unknownTeamContacts: number;
+        ambiguousContextEvents: number;
+        positionsSuppressedBySampling: number;
+    };
+}
+export interface BattleObservedTeamState {
+    teamRef: string;
+    memberCountObserved: number;
+    activeObserved: number;
+    knockedObserved: number;
+    deadObserved: number;
+    unknownObserved: number;
+    completeness: 'observed-members-only';
+}
+export interface BattleStateTimelineEntry {
+    sourceEventId: string;
+    timeSeconds: number;
+    type: 'KNOCK' | 'REVIVE' | 'KILL';
+    actorRef: string | null;
+    victimRef: string | null;
+    actorTeamRef: string | null;
+    victimTeamRef: string | null;
+    states: BattleObservedTeamState[];
+}
+export interface BattleAdvantageWindow {
+    teamRefs: [string, string];
+    observedLeadTeamRef: string;
+    startedAtSeconds: number;
+    endedAtSeconds: number;
+    durationSeconds: number;
+    resolution: 'equalized' | 'reversed' | 'ongoing';
+    startEventId: string;
+    endEventId: string | null;
+    evidenceEventIds: string[];
+    assessment: 'observed-knock-balance-only';
+    rosterCompleteness: 'observed-members-only';
+}
+export interface BattleAdvantageChange {
+    teamRefs: [string, string];
+    timeSeconds: number;
+    previousLeadTeamRef: string | null;
+    nextLeadTeamRef: string | null;
+    classification: 'lead' | 'equalized' | 'reversed';
+    sourceEventId: string;
+}
+export interface BattleGroup {
+    id: string;
+    startSeconds: number;
+    endSeconds: number;
+    durationSeconds: number;
+    episodeIds: string[];
+    teamRefs: string[];
+    bridgeEvidenceEventIds: string[];
+    timeline: BattleTimelineEvent[];
+    stateTimeline: BattleStateTimelineEntry[];
+    advantageWindows: BattleAdvantageWindow[];
+    advantageChanges: BattleAdvantageChange[];
+    firstKnockAdvantage: BattleAdvantageWindow | null;
+    postKnockResponse: {
+        status: 'observed' | 'not_observed_in_window' | 'incomplete';
+        firstKnockEventId: string | null;
+        responseEventId: string | null;
+        elapsedSeconds: number | null;
+        windowSeconds: 30;
+    };
+    possibleThirdParty: Array<{
+        teamRef: string;
+        episodeId: string;
+        evidenceEventIds: string[];
+        status: 'possible_third_party_contact';
+    }>;
+    rosterCompleteness: 'observed-members-only';
+}
+export interface BattleReconstructionResult {
+    schemaVersion: typeof BATTLE_RECONSTRUCTION_SCHEMA_VERSION;
+    parserVersion: typeof BATTLE_RECONSTRUCTION_PARSER_VERSION;
+    status: 'available' | 'no_contact_events';
+    episodes: BattleEpisode[];
+    battles: BattleGroup[];
+    circleSamples: BattleCircleSample[];
+    circleTransitions: BattleCircleTransition[];
+    diagnostics: {
+        rawEventCount: number;
+        domainNormalizedEventCount: number;
+        battleEventCount: number;
+        contactEventCount: number;
+        episodeCount: number;
+        battleGroupCount: number;
+        multiTeamBattleCount: number;
+        groupedEpisodeCount: number;
+        duplicateSourceEventCount: number;
+        duplicateTimelineAssignmentCount: number;
+        unassignedContactEventCount: number;
+        untimedContactEventCount: number;
+        preMatchContactEventCount: number;
+        noParticipantContactEventCount: number;
+        sameTeamContactEventCount: number;
+        ineffectiveContactEventCount: number;
+        unknownPhaseContactEventCount: number;
+        unknownTeamContactEventCount: number;
+        unknownPhaseCircleSampleCount: number;
+        unresolvedKnockChainCount: number;
+        reviveWithoutUniqueKnockCount: number;
+        conflictingTeamReferenceCount: number;
+        conflictingStateTransitionCount: number;
+        ambiguousContextEventCount: number;
+        positionsSuppressedBySampling: number;
+        overlappingEpisodePairCount: number;
+        sharedCircleSampleContextCount: number;
+    };
+}
+export declare function battlePlayerRef(matchId: string, playerId: string): string;
+export declare function battleTeamRef(matchId: string, teamId: string): string;
+export declare function normalizeBattleTelemetry(payload: unknown, match: NormalizedMatch): BattleTelemetryDocument;
+export interface ReconstructBattleOptions {
+    match: Pick<NormalizedMatch, 'matchId'>;
+    telemetry: BattleTelemetryDocument;
+    trackedPlayerIds?: Iterable<string>;
+}
+export declare function reconstructBattleEpisodes(input: ReconstructBattleOptions): BattleReconstructionResult;
+export declare function reconstructBattleMatch(input: {
+    match: NormalizedMatch;
+    telemetry: unknown;
+    trackedPlayerIds?: Iterable<string>;
+}): BattleReconstructionResult;