diff --git a/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts b/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts index 7a70639..2ba84cd 100644 --- a/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts +++ b/apps/api/src/modules/analysis/analysis-pipeline.service.spec.ts @@ -88,6 +88,30 @@ function createTimelinePayload( }; } +function createTimelinePayloadWithFrames( + matchId = 'KR_1', + frames: Array<{ + timestamp?: number; + events?: Record[]; + participantFrames?: Record; + }> = [], +) { + return { + metadata: { + matchId, + participants: ['target-puuid', 'ally-puuid'], + }, + info: { + frameInterval: 60_000, + frames: frames.map((frame, index) => ({ + timestamp: frame.timestamp ?? index * 60_000, + events: frame.events ?? [], + participantFrames: frame.participantFrames ?? {}, + })), + }, + }; +} + interface ExecQuery { exec: jest.Mock, []>; } @@ -375,21 +399,46 @@ describe('AnalysisPipelineService', () => { }); it('stores derived timeline data when a timeline is available', async () => { - const timeline = createTimelinePayload('KR_1', [ + const timeline = createTimelinePayloadWithFrames('KR_1', [ { - type: 'CHAMPION_KILL', + timestamp: 0, + participantFrames: { + '1': { position: { x: 4_020, y: 6_000 } }, + '6': { position: { x: 3_000, y: 6_000 } }, + '7': { position: { x: 8_000, y: 6_000 } }, + }, + }, + { timestamp: 10_000, - killerId: 1, - victimId: 6, - assistingParticipantIds: [2], - position: { x: 1_000, y: 1_000 }, + events: [ + { + type: 'CHAMPION_KILL', + timestamp: 10_000, + killerId: 1, + victimId: 6, + assistingParticipantIds: [2], + }, + ], + }, + { + timestamp: 60_000, + participantFrames: { + '1': { position: { x: 4_020, y: 6_000 } }, + '6': { position: { x: 9_000, y: 6_000 } }, + '7': { position: { x: 14_000, y: 6_000 } }, + }, }, { - type: 'ELITE_MONSTER_KILL', timestamp: 900_000, - killerId: 4, - killerTeamId: 100, - monsterType: 'DRAGON', + events: [ + { + type: 'ELITE_MONSTER_KILL', + timestamp: 900_000, + killerId: 4, + killerTeamId: 100, + monsterType: 'DRAGON', + }, + ], }, ]); const getMatchTimeline = jest @@ -433,6 +482,17 @@ describe('AnalysisPipelineService', () => { participantIds: [4], }, ], + deathEvents: [ + { + t: 10_000, + victimParticipantId: 6, + x: 4_000, + y: 6_000, + zone: 'southWestJungle', + shutdownBountyGiven: 0, + nearestAllyDistanceApprox: 5_000, + }, + ], objectiveWindows: [ { objectiveTimeMs: 900_000, diff --git a/apps/api/src/modules/analysis/timeline-derived.service.spec.ts b/apps/api/src/modules/analysis/timeline-derived.service.spec.ts index 9575ffc..e10e235 100644 --- a/apps/api/src/modules/analysis/timeline-derived.service.spec.ts +++ b/apps/api/src/modules/analysis/timeline-derived.service.spec.ts @@ -13,6 +13,24 @@ function createTimelinePayload( }; } +function createTimelinePayloadWithFrames( + frames: Array<{ + timestamp?: number; + events?: Record[]; + participantFrames?: Record; + }>, +) { + return { + info: { + frames: frames.map((frame, index) => ({ + timestamp: frame.timestamp ?? index * 60_000, + events: frame.events ?? [], + participantFrames: frame.participantFrames ?? {}, + })), + }, + }; +} + describe('TimelineDerivedService', () => { const service = new TimelineDerivedService(); @@ -270,6 +288,133 @@ describe('TimelineDerivedService', () => { expect(derived.objectiveWindows[0].monsterType).toBe('BARON_NASHOR'); }); + it('builds death events with shutdown bounty, zone, and nearest ally approximation', () => { + const derived = service.buildDerivedData( + createTimelinePayloadWithFrames([ + { + timestamp: 0, + participantFrames: { + '1': { position: { x: 9_870, y: 4_414 } }, + '7': { position: { x: 9_000, y: 4_000 } }, + '8': { position: { x: 12_000, y: 4_000 } }, + }, + }, + { + timestamp: 30_000, + events: [ + { + type: 'CHAMPION_KILL', + timestamp: 30_000, + killerId: 1, + victimId: 6, + shutdownBounty: 277, + position: { x: 9_866, y: 4_414 }, + }, + ], + }, + { + timestamp: 60_000, + participantFrames: { + '1': { position: { x: 9_870, y: 4_414 } }, + '7': { position: { x: 10_000, y: 4_000 } }, + '8': { position: { x: 12_000, y: 4_000 } }, + }, + }, + ]), + ); + + expect(derived.deathEvents).toEqual([ + { + t: 30_000, + victimParticipantId: 6, + x: 9_866, + y: 4_414, + zone: 'dragonPit', + shutdownBountyGiven: 277, + nearestAllyDistanceApprox: 553, + }, + ]); + }); + + it('interpolates missing death positions from victim frames', () => { + const derived = service.buildDerivedData( + createTimelinePayloadWithFrames([ + { + timestamp: 0, + participantFrames: { + '1': { position: { x: 4_020, y: 6_000 } }, + '6': { position: { x: 3_000, y: 6_000 } }, + '7': { position: { x: 8_000, y: 6_000 } }, + }, + }, + { + timestamp: 30_000, + events: [ + { + type: 'CHAMPION_KILL', + timestamp: 30_000, + killerId: 1, + victimId: 6, + }, + ], + }, + { + timestamp: 60_000, + participantFrames: { + '1': { position: { x: 4_020, y: 6_000 } }, + '6': { position: { x: 5_000, y: 6_000 } }, + '7': { position: { x: 10_000, y: 6_000 } }, + }, + }, + ]), + ); + + expect(derived.deathEvents).toEqual([ + { + t: 30_000, + victimParticipantId: 6, + x: 4_000, + y: 6_000, + zone: 'southWestJungle', + shutdownBountyGiven: 0, + nearestAllyDistanceApprox: 5_000, + }, + ]); + }); + + it('classifies representative Summoner Rift death zones', () => { + const positions = [ + { x: 600, y: 600, zone: 'blueBase' }, + { x: 14_200, y: 14_200, zone: 'redBase' }, + { x: 1_000, y: 9_000, zone: 'topLane' }, + { x: 6_500, y: 6_500, zone: 'middleLane' }, + { x: 9_000, y: 1_000, zone: 'bottomLane' }, + { x: 8_000, y: 7_000, zone: 'river' }, + { x: 2_500, y: 8_500, zone: 'northWestJungle' }, + { x: 12_000, y: 9_000, zone: 'northEastJungle' }, + { x: 4_000, y: 6_000, zone: 'southWestJungle' }, + { x: 13_000, y: 5_000, zone: 'southEastJungle' }, + { x: 9_866, y: 4_414, zone: 'dragonPit' }, + { x: 5_007, y: 10_471, zone: 'baronPit' }, + { x: -1, y: 7_500, zone: 'unknown' }, + ]; + const derived = service.buildDerivedData( + createTimelinePayload([ + positions.map((position, index) => ({ + type: 'CHAMPION_KILL', + timestamp: (index + 1) * 1_000, + killerId: 1, + victimId: 6, + position: { x: position.x, y: position.y }, + })), + ]), + ); + + expect(derived.deathEvents.map((deathEvent) => deathEvent.zone)).toEqual( + positions.map((position) => position.zone), + ); + }); + it('builds weighted advantage events for kills, plates, towers, and objectives', () => { const derived = service.buildDerivedData( createTimelinePayload([ diff --git a/apps/api/src/modules/analysis/timeline-derived.service.ts b/apps/api/src/modules/analysis/timeline-derived.service.ts index e5f8e96..6999aea 100644 --- a/apps/api/src/modules/analysis/timeline-derived.service.ts +++ b/apps/api/src/modules/analysis/timeline-derived.service.ts @@ -1,6 +1,8 @@ import { ADVANTAGE_EVENT_WEIGHTS, + SUMMONERS_RIFT_MAP, type AdvantageEventType, + type SummonersRiftMapZone, } from '@persona-lenz/shared'; import { Injectable } from '@nestjs/common'; @@ -13,6 +15,7 @@ interface TimelineChampionKillEvent { timestamp: number; killerId?: number; victimId?: number; + shutdownBounty?: number; assistingParticipantIds: number[]; position?: TimelinePosition; victimDamageReceived: Array<{ @@ -30,6 +33,11 @@ interface TimelineEliteMonsterKillEvent { position?: TimelinePosition; } +interface TimelineFrameSnapshot { + timestamp: number; + participantPositions: Map; +} + export interface TimelineFightCluster { startTimeMs: number; endTimeMs: number; @@ -59,9 +67,20 @@ export interface TimelineAdvantageEvent { participantIds: number[]; } +export interface TimelineDeathEvent { + t: number; + victimParticipantId: number; + x: number; + y: number; + zone: SummonersRiftMapZone; + shutdownBountyGiven: number; + nearestAllyDistanceApprox: number | null; +} + export interface TimelineDerivedData { fightClusters: TimelineFightCluster[]; advantageEvents: TimelineAdvantageEvent[]; + deathEvents: TimelineDeathEvent[]; objectiveWindows: TimelineObjectiveWindow[]; } @@ -129,6 +148,82 @@ function distance( return Math.hypot(left.x - right.x, left.y - right.y); } +function isWithinRadius( + position: TimelinePosition, + center: TimelinePosition, + radius: number, +): boolean { + return distance(position, center) <= radius; +} + +function classifySummonersRiftPosition( + position: TimelinePosition | undefined, +): SummonersRiftMapZone { + if (!position) { + return 'unknown'; + } + + const { + baronPit, + baseRadius, + coordinateMax, + coordinateMin, + dragonPit, + jungleMidline, + laneAxisHalfWidth, + objectivePitRadius, + riverBandHalfWidth, + } = SUMMONERS_RIFT_MAP; + const { x, y } = position; + + if ( + x < coordinateMin || + y < coordinateMin || + x > coordinateMax || + y > coordinateMax + ) { + return 'unknown'; + } + if (isWithinRadius(position, dragonPit, objectivePitRadius)) { + return 'dragonPit'; + } + if (isWithinRadius(position, baronPit, objectivePitRadius)) { + return 'baronPit'; + } + if (x <= baseRadius && y <= baseRadius) { + return 'blueBase'; + } + if (x >= coordinateMax - baseRadius && y >= coordinateMax - baseRadius) { + return 'redBase'; + } + if (Math.abs(x + y - coordinateMax) <= riverBandHalfWidth) { + return 'river'; + } + if (x <= laneAxisHalfWidth || y >= coordinateMax - laneAxisHalfWidth) { + return 'topLane'; + } + if (Math.abs(x - y) <= laneAxisHalfWidth) { + return 'middleLane'; + } + if (y <= laneAxisHalfWidth || x >= coordinateMax - laneAxisHalfWidth) { + return 'bottomLane'; + } + if (x < jungleMidline && y >= jungleMidline) { + return 'northWestJungle'; + } + if (x >= jungleMidline && y >= jungleMidline) { + return 'northEastJungle'; + } + if (x < jungleMidline && y < jungleMidline) { + return 'southWestJungle'; + } + if (x >= jungleMidline && y < jungleMidline) { + return 'southEastJungle'; + } + + return 'unknown'; +} + function isConnectedKill( left: TimelineChampionKillEvent, right: TimelineChampionKillEvent, @@ -281,6 +376,7 @@ function parseChampionKillEvent( timestamp, killerId: asParticipantId(event.killerId), victimId: asParticipantId(event.victimId), + shutdownBounty: asNumber(event.shutdownBounty), assistingParticipantIds: parseAssistingParticipantIds( event.assistingParticipantIds, ), @@ -289,6 +385,33 @@ function parseChampionKillEvent( }; } +function parseTimelineFrame( + frame: Record, +): TimelineFrameSnapshot | undefined { + const timestamp = asNumber(frame.timestamp); + if (timestamp === undefined) { + return undefined; + } + + const participantFrames = asRecord(frame.participantFrames); + const participantPositions = new Map(); + for (const [participantIdValue, participantFrameValue] of Object.entries( + participantFrames, + )) { + const participantId = asParticipantId(Number(participantIdValue)); + const participantFrame = asRecord(participantFrameValue); + const position = parsePosition(participantFrame.position); + if (participantId !== undefined && position) { + participantPositions.set(participantId, position); + } + } + + return { + timestamp, + participantPositions, + }; +} + function parseEliteMonsterKillEvent( event: Record, ): TimelineEliteMonsterKillEvent | undefined { @@ -398,8 +521,14 @@ function extractTimelineEvents(timeline: Record) { const championKills: TimelineChampionKillEvent[] = []; const eliteMonsterKills: TimelineEliteMonsterKillEvent[] = []; const advantageEvents: TimelineAdvantageEvent[] = []; + const frameSnapshots: TimelineFrameSnapshot[] = []; for (const frame of frames) { + const frameSnapshot = parseTimelineFrame(frame); + if (frameSnapshot) { + frameSnapshots.push(frameSnapshot); + } + for (const rawEvent of asArray(frame.events)) { const event = asRecord(rawEvent); switch (asString(event.type)) { @@ -458,6 +587,9 @@ function extractTimelineEvents(timeline: Record) { advantageEvents: advantageEvents.sort( (left, right) => left.timestampMs - right.timestampMs, ), + frameSnapshots: frameSnapshots.sort( + (left, right) => left.timestamp - right.timestamp, + ), }; } @@ -558,17 +690,134 @@ function buildObjectiveWindows( })); } +function interpolatePosition( + frameSnapshots: TimelineFrameSnapshot[], + participantId: number, + timestampMs: number, +): TimelinePosition | undefined { + let previous: { timestamp: number; position: TimelinePosition } | undefined; + let next: { timestamp: number; position: TimelinePosition } | undefined; + + for (const frame of frameSnapshots) { + const position = frame.participantPositions.get(participantId); + if (!position) { + continue; + } + if (frame.timestamp <= timestampMs) { + previous = { timestamp: frame.timestamp, position }; + } + if (frame.timestamp >= timestampMs) { + next = { timestamp: frame.timestamp, position }; + break; + } + } + + if (previous && next) { + if (previous.timestamp === next.timestamp) { + return previous.position; + } + + const ratio = + (timestampMs - previous.timestamp) / + (next.timestamp - previous.timestamp); + return { + x: previous.position.x + (next.position.x - previous.position.x) * ratio, + y: previous.position.y + (next.position.y - previous.position.y) * ratio, + }; + } + + return previous?.position ?? next?.position; +} + +function nearestAllyDistanceApprox( + frameSnapshots: TimelineFrameSnapshot[], + victimParticipantId: number, + deathPosition: TimelinePosition, + timestampMs: number, +): number | null { + const victimTeamId = teamIdFromParticipantId(victimParticipantId); + if (!victimTeamId) { + return null; + } + + let nearestDistance = Number.POSITIVE_INFINITY; + for (let participantId = 1; participantId <= 10; participantId += 1) { + if ( + participantId === victimParticipantId || + teamIdFromParticipantId(participantId) !== victimTeamId + ) { + continue; + } + + const allyPosition = interpolatePosition( + frameSnapshots, + participantId, + timestampMs, + ); + if (!allyPosition) { + continue; + } + + nearestDistance = Math.min( + nearestDistance, + distance(deathPosition, allyPosition), + ); + } + + return Number.isFinite(nearestDistance) ? Math.round(nearestDistance) : null; +} + +function buildDeathEvents( + championKills: TimelineChampionKillEvent[], + frameSnapshots: TimelineFrameSnapshot[], +): TimelineDeathEvent[] { + return championKills.flatMap((event) => { + if (event.victimId === undefined) { + return []; + } + + const position = + event.position ?? + interpolatePosition(frameSnapshots, event.victimId, event.timestamp); + if (!position) { + return []; + } + + return [ + { + t: event.timestamp, + victimParticipantId: event.victimId, + x: position.x, + y: position.y, + zone: classifySummonersRiftPosition(position), + shutdownBountyGiven: event.shutdownBounty ?? 0, + nearestAllyDistanceApprox: nearestAllyDistanceApprox( + frameSnapshots, + event.victimId, + position, + event.timestamp, + ), + }, + ]; + }); +} + @Injectable() export class TimelineDerivedService { public buildDerivedData( timeline: Record, ): TimelineDerivedData { - const { advantageEvents, championKills, eliteMonsterKills } = - extractTimelineEvents(timeline); + const { + advantageEvents, + championKills, + eliteMonsterKills, + frameSnapshots, + } = extractTimelineEvents(timeline); return { fightClusters: buildFightClusters(championKills), advantageEvents, + deathEvents: buildDeathEvents(championKills, frameSnapshots), objectiveWindows: buildObjectiveWindows(eliteMonsterKills), }; } diff --git a/apps/api/src/shared-contract.spec.ts b/apps/api/src/shared-contract.spec.ts index e771ed8..7591f74 100644 --- a/apps/api/src/shared-contract.spec.ts +++ b/apps/api/src/shared-contract.spec.ts @@ -2,6 +2,8 @@ import { ADVANTAGE_EVENT_WEIGHTS, FEATURE_SCHEMA_VERSION, METRICS, + SUMMONERS_RIFT_MAP, + SUMMONERS_RIFT_MAP_ZONES, VECTOR_DIMENSION, type AnalysisRequestAcceptedDto, type AnalysisJobStatusDto, @@ -73,6 +75,35 @@ describe('shared feature registry', () => { baron: 3, }); }); + + it('defines shared Summoner Rift map zones for timeline-derived metrics', () => { + expect(SUMMONERS_RIFT_MAP_ZONES).toEqual([ + 'blueBase', + 'redBase', + 'topLane', + 'middleLane', + 'bottomLane', + 'river', + 'northWestJungle', + 'northEastJungle', + 'southWestJungle', + 'southEastJungle', + 'dragonPit', + 'baronPit', + 'unknown', + ]); + expect(SUMMONERS_RIFT_MAP).toEqual({ + coordinateMin: 0, + coordinateMax: 15_000, + laneAxisHalfWidth: 1_500, + riverBandHalfWidth: 1_500, + jungleMidline: 7_500, + baseRadius: 2_200, + objectivePitRadius: 2_500, + dragonPit: { x: 9_866, y: 4_414 }, + baronPit: { x: 5_007, y: 10_471 }, + }); + }); }); describe('shared DTO contracts', () => { diff --git a/packages/shared/src/feature-registry.ts b/packages/shared/src/feature-registry.ts index c224f6d..7fdaa82 100644 --- a/packages/shared/src/feature-registry.ts +++ b/packages/shared/src/feature-registry.ts @@ -230,3 +230,34 @@ export const ADVANTAGE_EVENT_WEIGHTS = { } as const; export type AdvantageEventType = keyof typeof ADVANTAGE_EVENT_WEIGHTS; + +export const SUMMONERS_RIFT_MAP_ZONES = [ + 'blueBase', + 'redBase', + 'topLane', + 'middleLane', + 'bottomLane', + 'river', + 'northWestJungle', + 'northEastJungle', + 'southWestJungle', + 'southEastJungle', + 'dragonPit', + 'baronPit', + 'unknown', +] as const; + +export type SummonersRiftMapZone = + (typeof SUMMONERS_RIFT_MAP_ZONES)[number]; + +export const SUMMONERS_RIFT_MAP = { + coordinateMin: 0, + coordinateMax: 15_000, + laneAxisHalfWidth: 1_500, + riverBandHalfWidth: 1_500, + jungleMidline: 7_500, + baseRadius: 2_200, + objectivePitRadius: 2_500, + dragonPit: { x: 9_866, y: 4_414 }, + baronPit: { x: 5_007, y: 10_471 }, +} as const;